feat: add system stats API for dashboard monitoring

- GET /tools/system/stats - Real-time host system statistics
- CPU usage, memory, all mounted disks, network I/O
- GPU/VRAM stats via nvidia-smi (if available)
- Uses psutil for cross-platform host metrics
- Auto-discovers and filters real filesystems

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/domains/tools/controller.py

@@ -3,6 +3,7 @@ Tools Controller
 
 Provides utility tool endpoints including:
 - DNS lookups
+- System stats
 """
 from fastapi import APIRouter, HTTPException, status
 
@@ -11,6 +12,8 @@ from src.shared.logging import get_logger
 from src.domains.tools.dns.schemas import DNSLookupRequest, DNSLookupResponse
 from src.domains.tools.dns.service import DNSService
 from src.domains.tools.dns.exceptions import DNSQueryError
+from src.domains.tools.system.schemas import SystemStatsResponse
+from src.domains.tools.system.service import SystemStatsService
 
 logger = get_logger(__name__)
 
@@ -21,11 +24,13 @@ class ToolsController(BaseController):
 
     Provides endpoints for:
     - DNS lookups
+    - System stats
     """
 
     def __init__(self):
         super().__init__(prefix="/tools", tags=["Tools"])
         self.dns_service = DNSService()
+        self.system_stats_service = SystemStatsService()
 
     def create_router(self) -> APIRouter:
         """Create and configure the router"""
@@ -95,6 +100,52 @@ class ToolsController(BaseController):
                     detail="An unexpected error occurred during DNS lookup"
                 )
 
+        @router.get(
+            "/system/stats",
+            response_model=SystemStatsResponse,
+            status_code=status.HTTP_200_OK,
+            summary="Get host system statistics",
+            description="""
+            Get real-time host system resource statistics.
+
+            Returns CPU, memory, disk, network, and GPU/VRAM usage for the host machine
+            (not Docker container metrics).
+
+            **Metrics Returned:**
+            - **CPU:** Usage percentage, core count, load averages
+            - **Memory:** Usage percentage, total/used/available bytes
+            - **Disk:** Usage percentage, total/used/free bytes (root partition)
+            - **Network:** Total bytes sent/received
+            - **GPU:** VRAM usage (if NVIDIA GPU available via nvidia-smi)
+
+            **Use Cases:**
+            - Dashboard system monitoring widgets
+            - Health checks and alerting
+            - Capacity planning
+            """
+        )
+        async def get_system_stats() -> SystemStatsResponse:
+            """
+            Get current host system statistics
+
+            Returns:
+                System statistics including CPU, memory, disk, network, and GPU
+
+            Raises:
+                HTTPException: 500 for processing errors
+            """
+            try:
+                logger.info("Fetching system stats")
+                result = await self.system_stats_service.get_stats()
+                return result
+
+            except Exception as e:
+                logger.error(f"Failed to get system stats: {str(e)}", exc_info=True)
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=f"Failed to collect system stats: {str(e)}"
+                )
+
         return router