Use NVML directly and cache nvidia-smi calls

README.md

@@ -104,6 +104,19 @@ stats = dev.metric(fast=True)
 print(stats.memory_used, stats.utilization)
 ```
 
+### NVIDIA NVML and `nvidia-smi` caching
+
+For NVIDIA devices, Device-SMI first tries to call NVML directly via `libnvidia-ml` so it does not spawn `nvidia-smi` repeatedly. When NVML is not available, it falls back to `nvidia-smi`.
+
+`nvidia-smi` caching is disabled by default (`nvidia_smi_cache_ttl = 0`). Set the TTL to a positive value to enable a thread-safe LRU cache that returns stale data within the TTL window:
+
+```py
+from device_smi import Device
+
+Device.config.nvidia_smi_cache_ttl = 2.0  # seconds; 0 disables caching
+Device.config.nvidia_smi_cache_maxsize = 32
+```
+
 ## Roadmap
 
 - Support Intel/Gaudi

device_smi/__init__.py

@@ -1 +1,2 @@
+from .config import config as config
 from .device import Device as Device

device_smi/config.py

@@ -0,0 +1,38 @@
+class Config:
+    """Module-level configuration for ``device-smi``."""
+
+    def __init__(self):
+        # A TTL of 0 disables the nvidia-smi cache entirely so every call
+        # runs the subprocess. Set it >0 to enable caching.
+        self._nvidia_smi_cache_ttl = 0.0
+        self._nvidia_smi_cache_maxsize = 16
+
+    @property
+    def nvidia_smi_cache_ttl(self) -> float:
+        """How long ``nvidia-smi`` results are cached, in seconds.
+
+        ``0.0`` disables caching and every call spawns a fresh subprocess.
+        """
+        return self._nvidia_smi_cache_ttl
+
+    @nvidia_smi_cache_ttl.setter
+    def nvidia_smi_cache_ttl(self, value: float) -> None:
+        value = float(value)
+        if value < 0:
+            raise ValueError("nvidia_smi_cache_ttl must be greater than or equal to 0")
+        self._nvidia_smi_cache_ttl = value
+
+    @property
+    def nvidia_smi_cache_maxsize(self) -> int:
+        """Maximum number of distinct ``nvidia-smi`` query results kept in the LRU cache."""
+        return self._nvidia_smi_cache_maxsize
+
+    @nvidia_smi_cache_maxsize.setter
+    def nvidia_smi_cache_maxsize(self, value: int) -> None:
+        value = int(value)
+        if value <= 0:
+            raise ValueError("nvidia_smi_cache_maxsize must be greater than 0")
+        self._nvidia_smi_cache_maxsize = value
+
+
+config = Config()

device_smi/device.py

@@ -7,6 +7,7 @@
 from .amd import AMDDevice
 from .apple import AppleDevice
 from .base import _run
+from .config import config
 from .cpu import CPUDevice
 from .intel import IntelDevice
 from .nvidia import NvidiaDevice
@@ -25,6 +26,8 @@ def _get_torch_runtime():
 
 
 class Device:
+    config = config
+
     def __init__(self, device, *, fast_metrics_interval: float = 0.200):
         # init attribute first to avoid IDE not attr warning
         # CPU/GPU Device