# cjm-fasthtml-sysmon


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_fasthtml_sysmon
```

## Project Structure

    nbs/
    ├── components/ (5)
    │   ├── base.ipynb    # Base components for rendering process count and status badges.
    │   ├── cards.ipynb   # Card components for rendering system monitoring dashboards with CPU, memory, disk, network, GPU, process, and temperature information.
    │   ├── common.ipynb  # Common UI components for rendering progress bars and stat cards.
    │   ├── modals.ipynb  # Modal components for configuring system monitoring refresh intervals.
    │   └── tables.ipynb  # Table components for displaying top CPU, memory, and GPU process information.
    ├── core/ (2)
    │   ├── html_ids.ipynb  # Centralized HTML ID constants for the application
    │   └── utils.ipynb     # Utility functions for formatting data and managing UI colors.
    └── monitors/ (8)
        ├── cpu.ipynb        # Monitor and collect CPU usage metrics, per-core statistics, and frequency information.
        ├── disk.ipynb       # Monitor and collect disk usage information for all mounted partitions.
        ├── gpu.ipynb        # Monitor and collect GPU metrics including utilization, memory usage, temperature, and process information.
        ├── memory.ipynb     # Monitor and collect memory and swap usage statistics.
        ├── network.ipynb    # Monitor and collect network interface statistics, bandwidth usage, and connection information.
        ├── processes.ipynb  # Monitor and collect information about running processes including CPU and memory usage rankings.
        ├── sensors.ipynb    # Monitor and collect temperature readings from system sensors including CPU, GPU, and storage devices.
        └── system.ipynb     # Monitor and collect static system information including OS details, hardware configuration, and boot time.

Total: 15 notebooks across 3 directories

## Module Dependencies

``` mermaid
graph LR
    components_base[components.base<br/>base]
    components_cards[components.cards<br/>cards]
    components_common[components.common<br/>common]
    components_modals[components.modals<br/>modals]
    components_tables[components.tables<br/>tables]
    core_html_ids[core.html_ids<br/>HTML IDs]
    core_utils[core.utils<br/>utils]
    monitors_cpu[monitors.cpu<br/>CPU monitoring]
    monitors_disk[monitors.disk<br/>disk monitoring]
    monitors_gpu[monitors.gpu<br/>GPU monitoring]
    monitors_memory[monitors.memory<br/>memory monitoring]
    monitors_network[monitors.network<br/>network monitoring]
    monitors_processes[monitors.processes<br/>Process monitoring]
    monitors_sensors[monitors.sensors<br/>sensors]
    monitors_system[monitors.system<br/>system]

    components_base --> core_html_ids
    components_base --> monitors_processes
    components_cards --> core_utils
    components_cards --> monitors_network
    components_cards --> components_tables
    components_cards --> monitors_cpu
    components_cards --> components_base
    components_cards --> components_common
    components_cards --> monitors_disk
    components_cards --> monitors_processes
    components_cards --> monitors_sensors
    components_cards --> monitors_system
    components_cards --> monitors_memory
    components_cards --> core_html_ids
    components_cards --> monitors_gpu
    components_common --> core_utils
    components_common --> monitors_system
    components_modals --> core_html_ids
    components_tables --> monitors_processes
    components_tables --> core_html_ids
    components_tables --> monitors_gpu
```

*21 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### base (`base.ipynb`)

> Base components for rendering process count and status badges.

#### Import

``` python
from cjm_fasthtml_sysmon.components.base import (
    render_process_count,
    render_process_status
)
```

#### Functions

``` python
def render_process_count(
    total:int  # The total number of processes
)-> FT:  # A Span element containing the process count badge
    "Render the process count badge."
```

``` python
def render_process_status(
    status_counts:dict  # Dictionary mapping process status names to their counts
)-> FT:  # A Div element containing status badges
    "Render the process status badges."
```

### cards (`cards.ipynb`)

> Card components for rendering system monitoring dashboards with CPU,
> memory, disk, network, GPU, process, and temperature information.

#### Import

``` python
from cjm_fasthtml_sysmon.components.cards import (
    scroll_preserve_script,
    get_cpu_text_color,
    render_cpu_cores_grid,
    render_os_info_card,
    render_cpu_card,
    render_memory_card,
    render_disk_entries,
    render_disk_card,
    render_network_interfaces,
    render_network_connections,
    render_network_card,
    render_process_card,
    render_gpu_metrics,
    render_gpu_processes_section,
    render_gpu_card,
    render_temperature_sensors,
    render_temperature_card
)
```

#### Functions

``` python
def get_cpu_text_color(
    percent:float  # CPU usage percentage
)-> ColoredUtilityDaisyUI:  # CSS class string for semantic color based on CPU usage
    "Get semantic color based on CPU usage percentage."
```

``` python
def render_cpu_cores_grid(
    cpu_percents:list  # List of CPU usage percentages for each core
)-> FT:  # A Div element containing a responsive grid of CPU core usage
    "Render CPU cores as a responsive grid with color-coded percentages."
```

``` python
def render_os_info_card()-> FT:  # A Div element containing the OS information card
    "Render the OS information card."
```

``` python
def render_cpu_card(
    cpu_info:dict  # Dictionary containing CPU usage information
)-> FT:  # A Div element containing the CPU usage card
    "Render the CPU usage card."
```

``` python
def render_memory_card(
    mem_info:dict  # Dictionary containing memory usage information
)-> FT:  # A Div element containing the memory usage card
    "Render the memory usage card."
```

``` python
def render_disk_entries(
    disk_info:list  # List of dictionaries containing disk information
)-> FT:  # A Div element containing disk entries
    "Render just the disk entries section."
```

``` python
def render_disk_card(
    disk_info:list  # List of dictionaries containing disk usage information
)-> FT:  # A Div element containing the disk usage card
    "Render the disk usage card using helper functions."
```

``` python
def render_network_interfaces(
    net_info:dict  # Dictionary containing network information
)-> FT:  # A Div element containing network interfaces
    "Render just the network interfaces section."
```

``` python
def render_network_connections(
    net_info:dict  # Dictionary containing network information
)-> FT:  # A Div element containing connection statistics
    "Render just the network connections section."
```

``` python
def render_network_card(
    net_info:dict  # Dictionary containing network interface and connection information
)-> FT:  # A Div element containing the network monitoring card
    "Render the network monitoring card using helper functions."
```

``` python
def render_process_card(
    proc_info:dict  # Dictionary containing process information and statistics
)-> FT:  # A Div element containing the process monitoring card
    "Render the process monitoring card."
```

``` python
def render_gpu_metrics(
    gpu_info:dict  # Dictionary containing GPU information
)-> FT:  # A Div element containing GPU metrics section
    "Render just the GPU metrics section (utilization, memory, temp, power)."
```

``` python
def render_gpu_processes_section(
    gpu_info:dict  # Dictionary containing GPU information
)-> FT:  # A Div element containing GPU processes section
    "Render just the GPU processes section."
```

``` python
def render_gpu_card(
    gpu_info:dict  # Dictionary containing GPU information and statistics
)-> FT:  # A Div element containing the GPU information card
    "Render the GPU information card using helper functions."
```

``` python
def render_temperature_sensors(
    temp_info:list  # List of dictionaries containing temperature information
)-> FT:  # A Div element containing temperature sensors
    "Render just the temperature sensors section."
```

``` python
def render_temperature_card(
    temp_info:list  # List of dictionaries containing temperature sensor information
)-> FT:  # A Div element containing the temperature sensors card
    "Render the temperature sensors card using helper functions."
```

### common (`common.ipynb`)

> Common UI components for rendering progress bars and stat cards.

#### Import

``` python
from cjm_fasthtml_sysmon.components.common import (
    render_stat_card,
    render_progress_bar
)
```

#### Functions

``` python
def render_stat_card(
    title_text:str,  # The title text for the stat card
    value_text:str,  # The main value to display in the stat card
    desc_text:str=None,  # Optional description text below the value
    value_color:str=None  # Optional color class for the value text
)-> FT:  # A Div element containing the stat card with consistent styling
    "Render a stat card with consistent styling."
```

``` python
def render_progress_bar(
    value:float,  # The current progress value
    max_value:float=100,  # The maximum value for the progress bar (default: 100)
    label:str=None  # Optional label text to display above the progress bar
)-> FT:  # A Div element containing the progress bar with optional label
    "Render a progress bar with label."
```

### CPU monitoring (`cpu.ipynb`)

> Monitor and collect CPU usage metrics, per-core statistics, and
> frequency information.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.cpu import (
    get_cpu_info
)
```

#### Functions

``` python
def get_cpu_info() -> dict:  # A dictionary containing CPU usage information
    """Get current CPU usage information."""
    cpu_percent = psutil.cpu_percent(interval=0.1, percpu=False)
    cpu_percent_per_core = psutil.cpu_percent(interval=0.1, percpu=True)
    cpu_freq = psutil.cpu_freq()

    return {
        'percent': cpu_percent,
    "Get current CPU usage information."
```

### disk monitoring (`disk.ipynb`)

> Monitor and collect disk usage information for all mounted partitions.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.disk import (
    get_disk_info
)
```

#### Functions

``` python
def get_disk_info() -> list:  # A list of dictionaries containing disk usage information for each partition
    """Get disk usage information."""
    partitions = psutil.disk_partitions()
    disk_info = []

    for partition in partitions
    "Get disk usage information."
```

### GPU monitoring (`gpu.ipynb`)

> Monitor and collect GPU metrics including utilization, memory usage,
> temperature, and process information.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.gpu import (
    get_gpu_info
)
```

#### Functions

``` python
def get_gpu_info() -> dict:  # A dictionary containing GPU availability, type, details, and process information
    """Check for GPU availability and get info using nvitop."""
    gpu_info = {'available': False, 'type': 'None', 'details': {}, 'processes': []}
    "Check for GPU availability and get info using nvitop."
```

### HTML IDs (`html_ids.ipynb`)

> Centralized HTML ID constants for the application

#### Import

``` python
from cjm_fasthtml_sysmon.core.html_ids import (
    HtmlIds
)
```

#### Classes

``` python
class HtmlIds:
    "HTML ID constants used throughout the application."
    
    def as_selector(id_str: str) -> str
        "Convert an ID to a CSS selector format (with #)."
```

### memory monitoring (`memory.ipynb`)

> Monitor and collect memory and swap usage statistics.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.memory import (
    get_memory_info
)
```

#### Functions

``` python
def get_memory_info() -> dict:  # A dictionary containing memory usage information
    """Get current memory usage information."""
    mem = psutil.virtual_memory()
    swap = psutil.swap_memory()

    return {
        'total': mem.total,
    "Get current memory usage information."
```

### modals (`modals.ipynb`)

> Modal components for configuring system monitoring refresh intervals.

#### Import

``` python
from cjm_fasthtml_sysmon.components.modals import (
    render_settings_modal
)
```

#### Functions

``` python
def render_settings_modal(
    refresh_intervals:dict,  # Dictionary containing refresh interval values for each component
    post_rt:str="/update_intervals" # Target route path
)-> FT:  # A Dialog element containing the settings modal
    "Render the settings modal for configuring refresh intervals."
```

### network monitoring (`network.ipynb`)

> Monitor and collect network interface statistics, bandwidth usage, and
> connection information.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.network import (
    NETWORK_STATS_CACHE,
    get_network_info
)
```

#### Functions

``` python
def get_network_info() -> dict:  # A dictionary containing network interface information and connection statistics
    """Get network interface information and statistics."""
    interfaces = []
    stats = psutil.net_io_counters(pernic=True)
    addrs = psutil.net_if_addrs()

    current_time = time.time()

    for interface, io_stats in stats.items()
    "Get network interface information and statistics."
```

#### Variables

``` python
NETWORK_STATS_CACHE = {0 items}
```

### Process monitoring (`processes.ipynb`)

> Monitor and collect information about running processes including CPU
> and memory usage rankings.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.processes import (
    get_process_info
)
```

#### Functions

``` python
def get_process_info(top_n:int=5) -> dict:  # Number of top processes to return for CPU and memory categories  # A dictionary containing top processes and process statistics
    """Get top processes by CPU and memory usage."""
    processes = []

    # Get all processes with their info
    for proc in psutil.process_iter(['pid', 'name', 'cpu_percent', 'memory_percent', 'memory_info', 'username', 'status'])
    "Get top processes by CPU and memory usage."
```

### sensors (`sensors.ipynb`)

> Monitor and collect temperature readings from system sensors including
> CPU, GPU, and storage devices.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.sensors import (
    get_temperature_info
)
```

#### Functions

``` python
def get_temperature_info() -> list:  # A list of dictionaries containing temperature sensor information
    """Get temperature sensor information."""
    temps = []

    try
    "Get temperature sensor information."
```

### system (`system.ipynb`)

> Monitor and collect static system information including OS details,
> hardware configuration, and boot time.

#### Import

``` python
from cjm_fasthtml_sysmon.monitors.system import (
    get_static_system_info
)
```

#### Functions

``` python
def get_static_system_info() -> dict:  # A dictionary containing static system information
    """Get system information that doesn't change during runtime."""
    
    try
    "Get system information that doesn't change during runtime."
```

### tables (`tables.ipynb`)

> Table components for displaying top CPU, memory, and GPU process
> information.

#### Import

``` python
from cjm_fasthtml_sysmon.components.tables import (
    render_cpu_processes_table,
    render_memory_processes_table,
    render_gpu_processes_table_body,
    render_gpu_processes_table
)
```

#### Functions

``` python
def render_cpu_processes_table(
    top_cpu:list  # List of dictionaries containing top CPU-consuming process information
)-> FT:  # A Div element containing the CPU processes table
    "Render the CPU processes table."
```

``` python
def render_memory_processes_table(
    top_memory:list  # List of dictionaries containing top memory-consuming process information
)-> FT:  # A Div element containing the memory processes table
    "Render the memory processes table."
```

``` python
def render_gpu_processes_table_body(
    gpu_processes:list  # List of dictionaries containing GPU process information
)-> FT:  # A Div element containing the GPU processes table body
    "Render just the GPU processes table body."
```

``` python
def render_gpu_processes_table(
    gpu_processes:list  # List of dictionaries containing GPU process information
)-> FT:  # A Div element containing the GPU processes table
    "Render the GPU processes table."
```

### utils (`utils.ipynb`)

> Utility functions for formatting data and managing UI colors.

#### Import

``` python
from cjm_fasthtml_sysmon.core.utils import (
    find_free_port,
    format_bytes,
    format_bandwidth,
    format_uptime,
    get_progress_color,
    get_temperature_color,
    get_temperature_badge_color,
    open_browser
)
```

#### Functions

``` python
def find_free_port() -> int:  # An available port number
    """Find an available port."""
    with closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as s
    "Find an available port."
```

``` python
def format_bytes(
    bytes_value:int  # The number of bytes to format
) -> str:  # A formatted string representation of the byte value
    "Format bytes to human readable string."
```

``` python
def format_bandwidth(
    bytes_per_sec:float  # The number of bytes per second to format
) -> str:  # A formatted string representation of the bandwidth value
    "Format bandwidth to human readable string."
```

``` python
def format_uptime(
    boot_time_str:str  # Boot time in '%Y-%m-%d %H:%M:%S' format
) -> str:  # A formatted string representation of the uptime
    "Format uptime from boot time string."
```

``` python
def get_progress_color(
    percent:float  # The percentage value to determine color for
) -> SingleValueUtility:  # A progress color from the DaisyUI color scheme
    "Get progress bar color based on percentage."
```

``` python
def get_temperature_color(
    temp_celsius:float,  # The temperature value in Celsius
    high:int=85,  # The threshold for high temperature
    critical:int=95  # The threshold for critical temperature
) -> ColoredUtilityDaisyUI:  # A text color from the DaisyUI semantic colors
    "Get color for temperature display."
```

``` python
def get_temperature_badge_color(
    temp_celsius:float,  # The temperature value in Celsius
    high:int=85,  # The threshold for high temperature
    critical:int=95  # The threshold for critical temperature
) -> SingleValueUtility:  # A badge color from the DaisyUI color scheme
    "Get badge color for temperature."
```

``` python
def open_browser(
    url:str  # The URL to open in the browser
) -> None:  # None
    "Open browser based on environment settings."
```