core

Core data structures for infrastructure monitoring

SystemStats

Standardized snapshot of system resources. This DTO is used by:

• ResourceScheduler: Checks gpu_free_memory_mb and memory_available_mb against plugin requirements
• Dashboard UIs: Displays resource usage via the details field
• Logging/Metrics: Tracks resource utilization over time

The to_dict() method ensures compatibility with the JSON-based communication protocol.

---

SystemStats

def SystemStats(
    cpu_percent:float=0.0, memory_used_mb:float=0.0, memory_total_mb:float=0.0, memory_available_mb:float=0.0,
    gpu_type:str='None', gpu_free_memory_mb:float=0.0, gpu_total_memory_mb:float=0.0, gpu_used_memory_mb:float=0.0,
    gpu_load_percent:float=0.0, details:Dict=<factory>
)->None:

Standardized snapshot of system resources.

Example Usage

from cjm_infra_plugin_system.core import SystemStats

# Create stats snapshot
stats = SystemStats(
    cpu_percent=45.2,
    memory_used_mb=16384,
    memory_total_mb=32768,
    memory_available_mb=16384,
    gpu_type="NVIDIA",
    gpu_free_memory_mb=8192,
    gpu_total_memory_mb=24576,
    gpu_used_memory_mb=16384,
    gpu_load_percent=75.0,
    details={
        "gpu_0": {"name": "RTX 4090", "temp_c": 65},
        "gpu_1": {"name": "RTX 4090", "temp_c": 68}
    }
)

# Convert to dict for JSON transmission
stats_dict = stats.to_dict()

ProcessStats

Per-process resource usage snapshot reported by MonitorPlugin.list_processes (CR-3).

This is the typed replacement for the free-form SystemStats.details['processes'] channel that pre-CR-3 monitor plugins used. Substrate consumers (e.g. cjm-fasthtml-job-monitor via the SG-47 cascade) call list_processes() directly and iterate ProcessStats instances rather than parsing a nested dict shape.

Monitor implementations that lack per-process GPU visibility (CPU-only systems, AMD pre-ROCm, etc.) inherit the default list_processes() -> [] and don’t need to override.

---

ProcessStats

def ProcessStats(
    pid:int=0, gpu_index:int=-1, gpu_memory_mb:float=0.0, command:str=''
)->None:

Per-process resource usage snapshot reported by MonitorPlugin.list_processes.

CR-3 introduced this as the typed replacement for SystemStats.details['processes']. Monitor plugins that can enumerate per-process GPU usage (e.g. NVIDIA via nvitop) return a list of these; monitors without per-process visibility return [] from the default MonitorPlugin.list_processes() implementation.