picomon 0.1.1__tar.gz

picomon-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Omar Kamali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

picomon-0.1.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: picomon
+Version: 0.1.1
+Summary: Minimal curses dashboard for monitoring AMD GPUs via amd-smi
+Author-email: Omar Kamali <picomon@omarkama.li>
+License: MIT License
+        
+        Copyright (c) 2025 Omar Kamali
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/omarkamali/picomon
+Project-URL: Issues, https://github.com/omarkamali/picomon/issues
+Project-URL: Repository, https://github.com/omarkamali/picomon
+Keywords: amd,gpu,monitor,cli,curses
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# picomon
+
+picomon is a tiny terminal dashboard for monitoring AMD GPUs via `amd-smi`. It polls basic metrics (gfx activity, memory usage, and power) and renders them as sparklines inside a curses UI so you can keep an eye on accelerators without launching a full GUI stack. 
+
+Homepage: <https://omarkamali.github.io/picomon/>
+
+## Why?
+
+I like nvtop but the asserts kept crashing it on some AMD devices. picomon is a lightweight alternative that just polls metrics and renders them as sparklines, trading off ironclad accuracy checks for more reliability.
+
+It hasn't been tested on all AMD GPUs. If it fails to run on your GPU, please open a new issue using [this template](https://github.com/omarkamali/picomon/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBug%5D).
+
+## Requirements
+
+- Python 3.9 or newer
+- The `amd-smi` CLI available on your PATH (if your GPU is properly setup then you already have this)
+- An ANSI-compatible terminal for the curses UI
+
+## Installation
+
+```shell
+pip install picomon
+```
+
+## Usage
+
+After installation, run the CLI:
+
+```
+$ picomon
+
+┌──────────────────────────────────────────┐  ┌──────────────────────────────────────────┐
+│ GPU 0  GFX  42%  UMC  21%                │  │ GPU 1  GFX  78%  UMC  66%                │
+│ PWR 135/250W (54%)  VRAM 10.0/16.0GB 62% │  │ PWR 210/250W (84%)  VRAM 14.5/16.0GB 90% │
+│                                          │  │                                          │
+│ GFX ▁▂▂▃▄▄▅▆▆▇█▇▆▅▄▃▂▁                   │  │ GFX ▂▃▄▅▆▇██▇▆▅▄▂▂▃▅▆                    │
+│ PWR ▁▁▂▂▃▄▄▅▆▇██▇▆▅▄▂▁                   │  │ PWR ▂▂▃▄▅▆▇██▇▆▅▄▃▂▂▃                    │
+│ VRM ▁▁▂▂▃▄▄▅▆▇███▇▆▅▄▂                   │  │ VRM ▂▃▄▅▆▆▇███▇▆▅▄▃▂▂▃                   │
+└──────────────────────────────────────────┘  └──────────────────────────────────────────┘
+```
+
+Key bindings:
+- `q` to quit
+
+Common flags:
+- `--update-interval` (seconds between refreshes, default 3)
+- `--history-minutes` (rolling window to retain, default 30)
+- `--static-timeout` / `--metric-timeout` (seconds to wait for `amd-smi` responses)
+
+These correspond to the `PicomonConfig` dataclass, so you can also import and reuse
+picomon as a library:
+
+```python
+from picomon import PicomonConfig, run_monitor
+
+config = PicomonConfig(update_interval=1.5)
+run_monitor(["--update-interval", str(config.update_interval)])
+```
+
+## Development
+
+- Run tests with `pytest` (see the CI workflow for reference)
+- Use `scripts/publish.py` to cut a GitHub release once tags are in place
+
+## License
+
+MIT © [Omar Kamali](https://omarkamali.com)
+
+Source: <https://github.com/omarkamali/picomon>

picomon-0.1.1/README.md

@@ -0,0 +1,69 @@
+# picomon
+
+picomon is a tiny terminal dashboard for monitoring AMD GPUs via `amd-smi`. It polls basic metrics (gfx activity, memory usage, and power) and renders them as sparklines inside a curses UI so you can keep an eye on accelerators without launching a full GUI stack. 
+
+Homepage: <https://omarkamali.github.io/picomon/>
+
+## Why?
+
+I like nvtop but the asserts kept crashing it on some AMD devices. picomon is a lightweight alternative that just polls metrics and renders them as sparklines, trading off ironclad accuracy checks for more reliability.
+
+It hasn't been tested on all AMD GPUs. If it fails to run on your GPU, please open a new issue using [this template](https://github.com/omarkamali/picomon/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBug%5D).
+
+## Requirements
+
+- Python 3.9 or newer
+- The `amd-smi` CLI available on your PATH (if your GPU is properly setup then you already have this)
+- An ANSI-compatible terminal for the curses UI
+
+## Installation
+
+```shell
+pip install picomon
+```
+
+## Usage
+
+After installation, run the CLI:
+
+```
+$ picomon
+
+┌──────────────────────────────────────────┐  ┌──────────────────────────────────────────┐
+│ GPU 0  GFX  42%  UMC  21%                │  │ GPU 1  GFX  78%  UMC  66%                │
+│ PWR 135/250W (54%)  VRAM 10.0/16.0GB 62% │  │ PWR 210/250W (84%)  VRAM 14.5/16.0GB 90% │
+│                                          │  │                                          │
+│ GFX ▁▂▂▃▄▄▅▆▆▇█▇▆▅▄▃▂▁                   │  │ GFX ▂▃▄▅▆▇██▇▆▅▄▂▂▃▅▆                    │
+│ PWR ▁▁▂▂▃▄▄▅▆▇██▇▆▅▄▂▁                   │  │ PWR ▂▂▃▄▅▆▇██▇▆▅▄▃▂▂▃                    │
+│ VRM ▁▁▂▂▃▄▄▅▆▇███▇▆▅▄▂                   │  │ VRM ▂▃▄▅▆▆▇███▇▆▅▄▃▂▂▃                   │
+└──────────────────────────────────────────┘  └──────────────────────────────────────────┘
+```
+
+Key bindings:
+- `q` to quit
+
+Common flags:
+- `--update-interval` (seconds between refreshes, default 3)
+- `--history-minutes` (rolling window to retain, default 30)
+- `--static-timeout` / `--metric-timeout` (seconds to wait for `amd-smi` responses)
+
+These correspond to the `PicomonConfig` dataclass, so you can also import and reuse
+picomon as a library:
+
+```python
+from picomon import PicomonConfig, run_monitor
+
+config = PicomonConfig(update_interval=1.5)
+run_monitor(["--update-interval", str(config.update_interval)])
+```
+
+## Development
+
+- Run tests with `pytest` (see the CI workflow for reference)
+- Use `scripts/publish.py` to cut a GitHub release once tags are in place
+
+## License
+
+MIT © [Omar Kamali](https://omarkamali.com)
+
+Source: <https://github.com/omarkamali/picomon>

picomon-0.1.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "picomon"
+version = "0.1.1"
+description = "Minimal curses dashboard for monitoring AMD GPUs via amd-smi"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Omar Kamali", email = "picomon@omarkama.li" }
+]
+requires-python = ">=3.9"
+keywords = ["amd", "gpu", "monitor", "cli", "curses"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/omarkamali/picomon"
+Issues = "https://github.com/omarkamali/picomon/issues"
+Repository = "https://github.com/omarkamali/picomon"
+
+[project.scripts]
+picomon = "picomon.monitor:run"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

picomon-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

picomon-0.1.1/src/picomon/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+try:
+    from importlib import metadata as _metadata
+except ImportError:  # pragma: no cover
+    _metadata = None  # type: ignore[assignment]
+
+from .config import PicomonConfig
+from .monitor import run as run_monitor
+
+__all__ = ["PicomonConfig", "run_monitor", "__version__"]
+
+if _metadata is not None:
+    try:  # pragma: no cover - best effort in editable installs
+        __version__ = _metadata.version("picomon")
+    except _metadata.PackageNotFoundError:  # type: ignore[attr-defined]
+        __version__ = "0.0.0"
+else:  # pragma: no cover
+    __version__ = "0.0.0"

picomon-0.1.1/src/picomon/config.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PicomonConfig:
+    """Runtime configuration for picomon."""
+
+    update_interval: float = 3.0
+    history_minutes: int = 30
+    static_timeout: float = 10.0
+    metric_timeout: float = 5.0
+
+    def __post_init__(self) -> None:
+        if self.update_interval <= 0:
+            raise ValueError("update_interval must be greater than zero")
+        if self.history_minutes <= 0:
+            raise ValueError("history_minutes must be greater than zero")
+        if self.static_timeout <= 0:
+            raise ValueError("static_timeout must be greater than zero")
+        if self.metric_timeout <= 0:
+            raise ValueError("metric_timeout must be greater than zero")
+
+    @property
+    def max_points(self) -> int:
+        """Maximum number of samples to retain per metric."""
+
+        return max(1, int(self.history_minutes * 60 / self.update_interval))

picomon-0.1.1/src/picomon/history.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections import deque
+from datetime import datetime
+from typing import Deque
+
+__all__ = ["GPUHistory", "parse_value_unit"]
+
+
+def parse_value_unit(value) -> float:
+    """Parse amd-smi outputs like {'value': 42, 'unit': '%'} into floats."""
+
+    if isinstance(value, dict) and "value" in value:
+        try:
+            return float(value["value"])
+        except (TypeError, ValueError):
+            return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    try:
+        stripped = str(value).strip().rstrip("%WMGBs/")
+        return float(stripped)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+class GPUHistory:
+    """Static info + rolling metric history for one GPU."""
+
+    def __init__(self, max_points: int):
+        self.vram_total_mb: float = 0.0
+        self.power_limit_w: float = 0.0
+
+        self.timestamps: Deque[datetime] = deque(maxlen=max_points)
+        self.gfx: Deque[float] = deque(maxlen=max_points)
+        self.umc: Deque[float] = deque(maxlen=max_points)
+        self.power_w: Deque[float] = deque(maxlen=max_points)
+        self.vram_used_mb: Deque[float] = deque(maxlen=max_points)
+
+    def add_sample(
+        self,
+        ts: datetime,
+        gfx: float,
+        umc: float,
+        power_w: float,
+        vram_used_mb: float,
+    ) -> None:
+        self.timestamps.append(ts)
+        self.gfx.append(gfx)
+        self.umc.append(umc)
+        self.power_w.append(power_w)
+        self.vram_used_mb.append(vram_used_mb)
+
+    def prune_before(self, cutoff: datetime) -> None:
+        while self.timestamps and self.timestamps[0] < cutoff:
+            self.timestamps.popleft()
+            self.gfx.popleft()
+            self.umc.popleft()
+            self.power_w.popleft()
+            self.vram_used_mb.popleft()
+

picomon-0.1.1/src/picomon/monitor.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Sequence
+
+import curses
+
+from .config import PicomonConfig
+from .smi import load_static_info, update_dynamic_info
+from .ui import render_loop
+
+__all__ = ["build_parser", "run"]
+
+DEFAULT_CONFIG = PicomonConfig()
+
+_LOG_LEVELS = {
+    "CRITICAL": logging.CRITICAL,
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="picomon",
+        description="Minimal AMD GPU dashboard with curses UI",
+    )
+    parser.add_argument(
+        "--update-interval",
+        type=float,
+        default=DEFAULT_CONFIG.update_interval,
+        help="Refresh interval in seconds (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--history-minutes",
+        type=int,
+        default=DEFAULT_CONFIG.history_minutes,
+        help="How many minutes of history to retain (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--static-timeout",
+        type=float,
+        default=DEFAULT_CONFIG.static_timeout,
+        help="Timeout (seconds) when collecting static metadata (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--metric-timeout",
+        type=float,
+        default=DEFAULT_CONFIG.metric_timeout,
+        help="Timeout (seconds) when polling metrics (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=sorted(_LOG_LEVELS),
+        help="Verbosity for logging diagnostics (default: %(default)s)",
+    )
+    return parser
+
+
+def _configure_logging(level: str) -> None:
+    logging.basicConfig(level=_LOG_LEVELS.get(level.upper(), logging.INFO))
+
+
+def _config_from_namespace(ns: argparse.Namespace) -> PicomonConfig:
+    return PicomonConfig(
+        update_interval=ns.update_interval,
+        history_minutes=ns.history_minutes,
+        static_timeout=ns.static_timeout,
+        metric_timeout=ns.metric_timeout,
+    )
+
+
+def run(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    _configure_logging(args.log_level)
+    logger = logging.getLogger("picomon")
+
+    try:
+        config = _config_from_namespace(args)
+    except ValueError as exc:
+        logger.error("Invalid configuration: %s", exc)
+        return 2
+
+    gpus = load_static_info(config)
+    if not gpus:
+        logger.error(
+            "No GPUs detected via amd-smi static metrics. Check permissions/install."
+        )
+        return 1
+
+    update_dynamic_info(config, gpus)
+
+    def tick() -> None:
+        update_dynamic_info(config, gpus)
+
+    try:
+        curses.wrapper(render_loop, config, gpus, tick)
+    except KeyboardInterrupt:  # pragma: no cover - user initiated
+        return 0
+    except curses.error as exc:
+        logger.error("Curses rendering failed: %s", exc)
+        return 1
+
+    return 0

picomon-0.1.1/src/picomon/smi.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from datetime import datetime, timedelta
+from typing import Dict, Protocol, Sequence
+
+from .config import PicomonConfig
+from .history import GPUHistory, parse_value_unit
+
+__all__ = ["load_static_info", "update_dynamic_info"]
+
+logger = logging.getLogger(__name__)
+
+
+class CommandRunner(Protocol):
+    def __call__(self, args: Sequence[str], *, timeout: float) -> str: ...
+
+
+def _default_runner(args: Sequence[str], *, timeout: float) -> str:
+    return subprocess.check_output(  # type: ignore[return-value]
+        args,
+        text=True,
+        stderr=subprocess.DEVNULL,
+        timeout=timeout,
+    )
+
+
+def _run_json(
+    args: Sequence[str], *, timeout: float, runner: CommandRunner
+) -> dict | None:
+    try:
+        output = runner(args, timeout=timeout)
+    except Exception as exc:  # pragma: no cover - just log
+        logger.debug("Failed to run %s: %s", " ".join(args), exc)
+        return None
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError as exc:  # pragma: no cover - unexpected
+        logger.debug("Failed to parse amd-smi json: %s", exc)
+        return None
+
+
+def load_static_info(
+    config: PicomonConfig, *, runner: CommandRunner | None = None
+) -> Dict[int, GPUHistory]:
+    """Return GPU histories seeded with static data from amd-smi."""
+
+    runner = runner or _default_runner
+    data = _run_json(
+        ["amd-smi", "static", "--vram", "--limit", "--json"],
+        timeout=config.static_timeout,
+        runner=runner,
+    )
+    if not data:
+        return {}
+
+    gpus: Dict[int, GPUHistory] = {}
+    for entry in data.get("gpu_data", []):
+        gpu_id = entry.get("gpu")
+        if gpu_id is None:
+            continue
+        try:
+            gpu_idx = int(gpu_id)
+        except (TypeError, ValueError):
+            continue
+
+        hist = GPUHistory(config.max_points)
+
+        vram_block = entry.get("vram", {}) or {}
+        size = vram_block.get("size")
+        if size is not None:
+            hist.vram_total_mb = parse_value_unit(size)
+
+        limit_block = entry.get("limit", {}) or {}
+        pwr = limit_block.get("socket_power") or limit_block.get("max_power")
+        if pwr is not None:
+            hist.power_limit_w = parse_value_unit(pwr)
+
+        gpus[gpu_idx] = hist
+
+    return gpus
+
+
+def update_dynamic_info(
+    config: PicomonConfig,
+    gpus: Dict[int, GPUHistory],
+    *,
+    runner: CommandRunner | None = None,
+    timestamp_provider=datetime.now,
+) -> None:
+    """Add a fresh sample for each GPU in-place."""
+
+    runner = runner or _default_runner
+    data = _run_json(
+        [
+            "amd-smi",
+            "metric",
+            "--usage",
+            "--power",
+            "--mem-usage",
+            "--json",
+        ],
+        timeout=config.metric_timeout,
+        runner=runner,
+    )
+    if not data:
+        return
+
+    ts = timestamp_provider()
+    for entry in data.get("gpu_data", []):
+        gpu_id = entry.get("gpu")
+        if gpu_id is None:
+            continue
+        try:
+            gpu_idx = int(gpu_id)
+        except (TypeError, ValueError):
+            continue
+
+        hist = gpus.get(gpu_idx)
+        if hist is None:
+            hist = gpus[gpu_idx] = GPUHistory(config.max_points)
+
+        usage = entry.get("usage", {}) or {}
+        gfx = max(0.0, min(100.0, parse_value_unit(usage.get("gfx_activity", 0))))
+        umc = max(0.0, min(100.0, parse_value_unit(usage.get("umc_activity", 0))))
+
+        power_block = entry.get("power", {}) or {}
+        socket_pwr = power_block.get("socket_power") or power_block.get("SOCKET_POWER")
+        power_w = parse_value_unit(socket_pwr) if socket_pwr is not None else 0.0
+
+        mem_usage = entry.get("mem_usage", {}) or {}
+        used = mem_usage.get("used_visible_vram") or mem_usage.get("used_vram")
+        total = mem_usage.get("total_visible_vram") or mem_usage.get("total_vram")
+        vram_used_mb = parse_value_unit(used) if used is not None else 0.0
+        if total is not None:
+            total_mb = parse_value_unit(total)
+            if total_mb > 0:
+                hist.vram_total_mb = total_mb
+
+        hist.add_sample(ts, gfx, umc, power_w, vram_used_mb)
+
+    cutoff = ts - timedelta(minutes=config.history_minutes)
+    for hist in gpus.values():
+        hist.prune_before(cutoff)

picomon-0.1.1/src/picomon/ui.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import curses
+import time
+from typing import Callable, Dict
+
+from .config import PicomonConfig
+from .history import GPUHistory
+
+__all__ = ["sparkline", "draw_gpu_box", "render_loop"]
+
+SPARK_BARS = "▁▂▃▄▅▆▇█"
+
+
+def sparkline(values, width: int, vmax: float | None) -> tuple[str, str]:
+    """Return a two-row sparkline string for the provided samples."""
+
+    if width <= 0:
+        return "".ljust(0), "".ljust(0)
+    vals = list(values)
+    n = len(vals)
+    if n == 0:
+        return " " * width, " " * width
+
+    if vmax is None or vmax <= 0:
+        vmax = max(vals) if max(vals) > 0 else 1.0
+
+    nb = len(SPARK_BARS)
+    top_row: list[str] = []
+    bot_row: list[str] = []
+
+    for col in range(width):
+        if width == 1:
+            idx = n - 1
+        else:
+            idx = int(col * (n - 1) / (width - 1))
+        v = vals[idx]
+        frac = max(0.0, min(1.0, v / vmax))
+
+        if frac <= 0.5:
+            bot_frac = frac * 2.0
+            level = int(round(bot_frac * (nb - 1)))
+            bot_ch = SPARK_BARS[level]
+            top_ch = " "
+        else:
+            bot_ch = SPARK_BARS[-1]
+            top_frac = (frac - 0.5) * 2.0
+            level = int(round(top_frac * (nb - 1)))
+            top_ch = SPARK_BARS[level]
+
+        top_row.append(top_ch)
+        bot_row.append(bot_ch)
+
+    return "".join(top_row), "".join(bot_row)
+
+
+def draw_gpu_box(win, gpu_id: int, hist: GPUHistory) -> None:
+    win.box()
+    box_h, box_w = win.getmaxyx()
+    inner_w = box_w - 2
+    spark_w = max(16, inner_w - 6)
+
+    if hist.timestamps:
+        gfx_now = hist.gfx[-1]
+        umc_now = hist.umc[-1]
+        pwr_now = hist.power_w[-1]
+        vram_now = hist.vram_used_mb[-1]
+    else:
+        gfx_now = umc_now = pwr_now = vram_now = 0.0
+
+    pwr_lim = hist.power_limit_w if hist.power_limit_w > 0 else 1.0
+    vram_tot = hist.vram_total_mb if hist.vram_total_mb > 0 else 1.0
+
+    pwr_pct = 100.0 * pwr_now / pwr_lim
+    vram_pct = 100.0 * vram_now / vram_tot
+
+    header = (
+        f"GPU {gpu_id}  "
+        f"GFX {gfx_now:3.0f}%  "
+        f"UMC {umc_now:3.0f}%  "
+        f"PWR {pwr_now:4.0f}/{pwr_lim:4.0f}W ({pwr_pct:3.0f}%)  "
+        f"VRAM {vram_now/1024:4.1f}/{vram_tot/1024:4.1f}GB ({vram_pct:3.0f}%)"
+    )
+    win.addnstr(1, 1, header, inner_w)
+
+    top, bot = sparkline(hist.gfx, spark_w, 100.0)
+    win.addnstr(2, 1, "GFX ", inner_w)
+    win.addnstr(2, 5, top, spark_w)
+    win.addnstr(3, 5, bot, spark_w)
+
+    top, bot = sparkline(hist.power_w, spark_w, hist.power_limit_w or None)
+    win.addnstr(4, 1, "PWR ", inner_w)
+    win.addnstr(4, 5, top, spark_w)
+    win.addnstr(5, 5, bot, spark_w)
+
+    top, bot = sparkline(hist.vram_used_mb, spark_w, hist.vram_total_mb or None)
+    win.addnstr(6, 1, "VRM ", inner_w)
+    win.addnstr(6, 5, top, spark_w)
+    win.addnstr(7, 5, bot, spark_w)
+
+
+def render_loop(
+    stdscr,
+    config: PicomonConfig,
+    gpus: Dict[int, GPUHistory],
+    tick: Callable[[], None],
+) -> None:
+    curses.curs_set(0)
+    stdscr.nodelay(True)
+
+    while True:
+        tick()
+
+        stdscr.erase()
+        max_y, max_x = stdscr.getmaxyx()
+
+        title = f"picomon (last {config.history_minutes} min) - q to quit"
+        stdscr.addnstr(0, 0, title, max_x - 1)
+        stdscr.hline(1, 0, curses.ACS_HLINE, max_x - 1)
+
+        box_h = 9
+        total_cols = 2
+        col_w = (max_x - 3) // total_cols
+        col_x = [1, 1 + col_w + 1]
+
+        gpu_ids = sorted(gpus.keys())
+        for idx, gpu_id in enumerate(gpu_ids):
+            col = 0 if idx < 4 else 1
+            row_idx = idx if idx < 4 else idx - 4
+            top = 2 + row_idx * box_h
+            if top + box_h >= max_y:
+                continue
+
+            x = col_x[col]
+            win = stdscr.derwin(box_h, col_w, top, x)
+            draw_gpu_box(win, gpu_id, gpus[gpu_id])
+
+        stdscr.refresh()
+
+        end_time = time.time() + config.update_interval
+        while time.time() < end_time:
+            ch = stdscr.getch()
+            if ch in (ord("q"), ord("Q")):
+                return
+            time.sleep(0.1)

picomon-0.1.1/src/picomon.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: picomon
+Version: 0.1.1
+Summary: Minimal curses dashboard for monitoring AMD GPUs via amd-smi
+Author-email: Omar Kamali <picomon@omarkama.li>
+License: MIT License
+        
+        Copyright (c) 2025 Omar Kamali
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/omarkamali/picomon
+Project-URL: Issues, https://github.com/omarkamali/picomon/issues
+Project-URL: Repository, https://github.com/omarkamali/picomon
+Keywords: amd,gpu,monitor,cli,curses
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# picomon
+
+picomon is a tiny terminal dashboard for monitoring AMD GPUs via `amd-smi`. It polls basic metrics (gfx activity, memory usage, and power) and renders them as sparklines inside a curses UI so you can keep an eye on accelerators without launching a full GUI stack. 
+
+Homepage: <https://omarkamali.github.io/picomon/>
+
+## Why?
+
+I like nvtop but the asserts kept crashing it on some AMD devices. picomon is a lightweight alternative that just polls metrics and renders them as sparklines, trading off ironclad accuracy checks for more reliability.
+
+It hasn't been tested on all AMD GPUs. If it fails to run on your GPU, please open a new issue using [this template](https://github.com/omarkamali/picomon/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBug%5D).
+
+## Requirements
+
+- Python 3.9 or newer
+- The `amd-smi` CLI available on your PATH (if your GPU is properly setup then you already have this)
+- An ANSI-compatible terminal for the curses UI
+
+## Installation
+
+```shell
+pip install picomon
+```
+
+## Usage
+
+After installation, run the CLI:
+
+```
+$ picomon
+
+┌──────────────────────────────────────────┐  ┌──────────────────────────────────────────┐
+│ GPU 0  GFX  42%  UMC  21%                │  │ GPU 1  GFX  78%  UMC  66%                │
+│ PWR 135/250W (54%)  VRAM 10.0/16.0GB 62% │  │ PWR 210/250W (84%)  VRAM 14.5/16.0GB 90% │
+│                                          │  │                                          │
+│ GFX ▁▂▂▃▄▄▅▆▆▇█▇▆▅▄▃▂▁                   │  │ GFX ▂▃▄▅▆▇██▇▆▅▄▂▂▃▅▆                    │
+│ PWR ▁▁▂▂▃▄▄▅▆▇██▇▆▅▄▂▁                   │  │ PWR ▂▂▃▄▅▆▇██▇▆▅▄▃▂▂▃                    │
+│ VRM ▁▁▂▂▃▄▄▅▆▇███▇▆▅▄▂                   │  │ VRM ▂▃▄▅▆▆▇███▇▆▅▄▃▂▂▃                   │
+└──────────────────────────────────────────┘  └──────────────────────────────────────────┘
+```
+
+Key bindings:
+- `q` to quit
+
+Common flags:
+- `--update-interval` (seconds between refreshes, default 3)
+- `--history-minutes` (rolling window to retain, default 30)
+- `--static-timeout` / `--metric-timeout` (seconds to wait for `amd-smi` responses)
+
+These correspond to the `PicomonConfig` dataclass, so you can also import and reuse
+picomon as a library:
+
+```python
+from picomon import PicomonConfig, run_monitor
+
+config = PicomonConfig(update_interval=1.5)
+run_monitor(["--update-interval", str(config.update_interval)])
+```
+
+## Development
+
+- Run tests with `pytest` (see the CI workflow for reference)
+- Use `scripts/publish.py` to cut a GitHub release once tags are in place
+
+## License
+
+MIT © [Omar Kamali](https://omarkamali.com)
+
+Source: <https://github.com/omarkamali/picomon>

picomon-0.1.1/src/picomon.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/picomon/__init__.py
+src/picomon/config.py
+src/picomon/history.py
+src/picomon/monitor.py
+src/picomon/smi.py
+src/picomon/ui.py
+src/picomon.egg-info/PKG-INFO
+src/picomon.egg-info/SOURCES.txt
+src/picomon.egg-info/dependency_links.txt
+src/picomon.egg-info/entry_points.txt
+src/picomon.egg-info/requires.txt
+src/picomon.egg-info/top_level.txt
+tests/test_config.py
+tests/test_smi.py

picomon-0.1.1/src/picomon.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

picomon-0.1.1/src/picomon.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+picomon = picomon.monitor:run

picomon-0.1.1/src/picomon.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7

picomon-0.1.1/src/picomon.egg-info/top_level.txt

@@ -0,0 +1 @@
+picomon

picomon-0.1.1/tests/test_config.py

@@ -0,0 +1,22 @@
+import pytest
+
+from picomon.config import PicomonConfig
+
+
+def test_max_points_derived_from_history_and_interval():
+    cfg = PicomonConfig(update_interval=2.0, history_minutes=1)
+    assert cfg.max_points == 30
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"update_interval": 0},
+        {"history_minutes": 0},
+        {"static_timeout": 0},
+        {"metric_timeout": 0},
+    ],
+)
+def test_invalid_values_raise_value_error(kwargs):
+    with pytest.raises(ValueError):
+        PicomonConfig(**kwargs)

picomon-0.1.1/tests/test_smi.py

@@ -0,0 +1,83 @@
+import json
+from datetime import datetime
+
+from picomon.config import PicomonConfig
+from picomon.smi import load_static_info, update_dynamic_info
+
+
+def _runner_with_payload(payload: dict[str, object]):
+    response = json.dumps(payload)
+
+    def _runner(args, *, timeout):  # type: ignore[override]
+        return response
+
+    return _runner
+
+
+def test_load_static_info_populates_static_fields():
+    config = PicomonConfig(update_interval=1.0, history_minutes=1)
+    runner = _runner_with_payload(
+        {
+            "gpu_data": [
+                {
+                    "gpu": 0,
+                    "vram": {"size": {"value": 16384, "unit": "MB"}},
+                    "limit": {"socket_power": {"value": 250, "unit": "W"}},
+                }
+            ]
+        }
+    )
+
+    gpus = load_static_info(config, runner=runner)
+
+    assert 0 in gpus
+    hist = gpus[0]
+    assert hist.vram_total_mb == 16384
+    assert hist.power_limit_w == 250
+
+
+def test_update_dynamic_info_appends_samples():
+    config = PicomonConfig(update_interval=1.0, history_minutes=1)
+    static_runner = _runner_with_payload(
+        {
+            "gpu_data": [
+                {
+                    "gpu": 0,
+                    "vram": {"size": {"value": 16384, "unit": "MB"}},
+                    "limit": {"socket_power": {"value": 250, "unit": "W"}},
+                }
+            ]
+        }
+    )
+    gpus = load_static_info(config, runner=static_runner)
+
+    metrics_runner = _runner_with_payload(
+        {
+            "gpu_data": [
+                {
+                    "gpu": 0,
+                    "usage": {"gfx_activity": {"value": 40, "unit": "%"}},
+                    "power": {"socket_power": {"value": 120, "unit": "W"}},
+                    "mem_usage": {
+                        "used_visible_vram": {"value": 8192, "unit": "MB"},
+                        "total_visible_vram": {"value": 16384, "unit": "MB"},
+                    },
+                }
+            ]
+        }
+    )
+
+    now = datetime(2024, 1, 1, 12, 0, 0)
+    update_dynamic_info(
+        config,
+        gpus,
+        runner=metrics_runner,
+        timestamp_provider=lambda: now,
+    )
+
+    hist = gpus[0]
+    assert hist.timestamps[-1] == now
+    assert hist.gfx[-1] == 40
+    assert hist.power_w[-1] == 120
+    assert hist.vram_used_mb[-1] == 8192
+    assert hist.vram_total_mb == 16384