sgtop 0.1.0__tar.gz

sgtop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HarrytheOrange
+
+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.

sgtop-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: sgtop
+Version: 0.1.0
+Summary: btop-style terminal monitor for a live SGLang deployment
+Author: HarrytheOrange
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HarrytheOrange/sgtop
+Project-URL: Issues, https://github.com/HarrytheOrange/sgtop/issues
+Keywords: sglang,llm,monitoring,tui,gpu,prometheus
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sgtop
+
+A [btop](https://github.com/aristocratos/btop)-style terminal dashboard for a live [SGLang](https://github.com/sgl-project/sglang) deployment — concurrency, KV-cache headroom, GPU utilization, and (optionally) per-request latency, all in one screen.
+
+![sgtop screenshot](docs/screenshot.png)
+
+Not affiliated with the SGLang project. It's a small, independent, read-only sidecar: it never touches your inference traffic, it only reads sglang's own log file, `nvidia-smi`, and (if enabled) sglang's Prometheus `/metrics` endpoint.
+
+## Why
+
+`nvtop` tells you a GPU is at 98% utilization. It doesn't tell you whether your sglang server can actually take more concurrent requests, whether one data-parallel replica is starving while another is idle, or what your real TTFT looks like. `sgtop` answers those instead:
+
+- **Concurrency vs. capacity** — running requests / the actual `max_running_requests` sglang computed at startup, not a guess.
+- **KV-cache headroom** — tokens in use / total KV budget, per replica.
+- **Per-DP-replica breakdown** — if you run `--dp-size > 1`, each replica gets its own panel, so an imbalanced load-balancing setup is obvious at a glance instead of hidden in an aggregate number.
+- **Latency percentiles** — TTFT / end-to-end / queue-time p50/p90/p99 over a rolling 5-minute window, once you turn on `--enable-metrics` on the sglang side.
+- **GPU panel** — utilization, memory, temperature, power, right below the request-level view.
+
+## Install
+
+```bash
+pipx install sgtop        # recommended — isolated, puts `sgtop` on your PATH
+# or
+pip install --user sgtop
+```
+
+Requires Python ≥ 3.9 on Linux or macOS. No dependencies — it's pure standard library (`curses` + `urllib`), so there's nothing else to install.
+
+From source:
+
+```bash
+git clone https://github.com/HarrytheOrange/sgtop
+cd sgtop
+pip install -e .
+```
+
+## Quick start
+
+`sgtop` is a client. It needs something to talk to: `sgtop-server`, a small sidecar that tails sglang's log file and exposes a JSON API. Run it on the same machine as sglang (or anywhere with network access to it):
+
+```bash
+# 1. Launch sglang, redirecting its output to a file sgtop-server can tail:
+python -m sglang.launch_server --model-path ... --dp-size 2 --enable-metrics > server.log 2>&1 &
+
+# 2. Start the sidecar, pointing it at that log file:
+sgtop-server --log server.log --service-port 30000 --port 30001 &
+
+# 3. Watch it:
+sgtop --port 30001
+```
+
+`sgtop-server` also serves a plain HTML version of the same data at `http://<host>:30001/` — handy if you want to glance at it from a browser instead of a terminal, or point it at a machine other than the one you're `ssh`'d into:
+
+```bash
+sgtop --host 10.0.0.5 --port 30001
+```
+
+## `--enable-metrics` (optional, recommended)
+
+Without it, `sgtop` still shows concurrency, KV-cache usage, throughput and GPU stats — all parsed from sglang's own log lines, no extra flags needed.
+
+Add `--enable-metrics` to your `launch_server` command and the LATENCY panel comes alive with TTFT, end-to-end latency, per-replica queue time, and prefix-cache hit rate, scraped from sglang's Prometheus endpoint. `sgtop-server` diffs consecutive scrapes itself to give you a real rolling-window p50/p90/p99 instead of an all-time average — Prometheus histograms are cumulative counters, so a naive read would just show a number that keeps drifting toward whatever the very first few requests looked like.
+
+## Keybindings
+
+`q` to quit. That's it — it's a dashboard, not an editor.
+
+## How it works
+
+- `sgtop-server` tails the log file sglang writes when you redirect its stdout/stderr, extracting the periodic `Decode batch` / `Prefill batch` lines each DP replica prints, plus the one-time `max_total_num_tokens=... max_running_requests=...` line printed at startup. It samples `nvidia-smi` on an interval, and if `--enable-metrics` is on, scrapes `/metrics` and keeps a short rolling window of histogram deltas for latency percentiles. All of it is exposed as JSON at `/api/status`.
+- `sgtop` polls that JSON and renders it with `curses` — gradient meters, sparkline history, boxed panels, degrading gracefully to a 3-color/16-color palette on terminals without 256-color support.
+
+Both are plain Python, no compiled extensions, so `pipx install` is instant.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sgtop-0.1.0/README.md

@@ -0,0 +1,77 @@
+# sgtop
+
+A [btop](https://github.com/aristocratos/btop)-style terminal dashboard for a live [SGLang](https://github.com/sgl-project/sglang) deployment — concurrency, KV-cache headroom, GPU utilization, and (optionally) per-request latency, all in one screen.
+
+![sgtop screenshot](docs/screenshot.png)
+
+Not affiliated with the SGLang project. It's a small, independent, read-only sidecar: it never touches your inference traffic, it only reads sglang's own log file, `nvidia-smi`, and (if enabled) sglang's Prometheus `/metrics` endpoint.
+
+## Why
+
+`nvtop` tells you a GPU is at 98% utilization. It doesn't tell you whether your sglang server can actually take more concurrent requests, whether one data-parallel replica is starving while another is idle, or what your real TTFT looks like. `sgtop` answers those instead:
+
+- **Concurrency vs. capacity** — running requests / the actual `max_running_requests` sglang computed at startup, not a guess.
+- **KV-cache headroom** — tokens in use / total KV budget, per replica.
+- **Per-DP-replica breakdown** — if you run `--dp-size > 1`, each replica gets its own panel, so an imbalanced load-balancing setup is obvious at a glance instead of hidden in an aggregate number.
+- **Latency percentiles** — TTFT / end-to-end / queue-time p50/p90/p99 over a rolling 5-minute window, once you turn on `--enable-metrics` on the sglang side.
+- **GPU panel** — utilization, memory, temperature, power, right below the request-level view.
+
+## Install
+
+```bash
+pipx install sgtop        # recommended — isolated, puts `sgtop` on your PATH
+# or
+pip install --user sgtop
+```
+
+Requires Python ≥ 3.9 on Linux or macOS. No dependencies — it's pure standard library (`curses` + `urllib`), so there's nothing else to install.
+
+From source:
+
+```bash
+git clone https://github.com/HarrytheOrange/sgtop
+cd sgtop
+pip install -e .
+```
+
+## Quick start
+
+`sgtop` is a client. It needs something to talk to: `sgtop-server`, a small sidecar that tails sglang's log file and exposes a JSON API. Run it on the same machine as sglang (or anywhere with network access to it):
+
+```bash
+# 1. Launch sglang, redirecting its output to a file sgtop-server can tail:
+python -m sglang.launch_server --model-path ... --dp-size 2 --enable-metrics > server.log 2>&1 &
+
+# 2. Start the sidecar, pointing it at that log file:
+sgtop-server --log server.log --service-port 30000 --port 30001 &
+
+# 3. Watch it:
+sgtop --port 30001
+```
+
+`sgtop-server` also serves a plain HTML version of the same data at `http://<host>:30001/` — handy if you want to glance at it from a browser instead of a terminal, or point it at a machine other than the one you're `ssh`'d into:
+
+```bash
+sgtop --host 10.0.0.5 --port 30001
+```
+
+## `--enable-metrics` (optional, recommended)
+
+Without it, `sgtop` still shows concurrency, KV-cache usage, throughput and GPU stats — all parsed from sglang's own log lines, no extra flags needed.
+
+Add `--enable-metrics` to your `launch_server` command and the LATENCY panel comes alive with TTFT, end-to-end latency, per-replica queue time, and prefix-cache hit rate, scraped from sglang's Prometheus endpoint. `sgtop-server` diffs consecutive scrapes itself to give you a real rolling-window p50/p90/p99 instead of an all-time average — Prometheus histograms are cumulative counters, so a naive read would just show a number that keeps drifting toward whatever the very first few requests looked like.
+
+## Keybindings
+
+`q` to quit. That's it — it's a dashboard, not an editor.
+
+## How it works
+
+- `sgtop-server` tails the log file sglang writes when you redirect its stdout/stderr, extracting the periodic `Decode batch` / `Prefill batch` lines each DP replica prints, plus the one-time `max_total_num_tokens=... max_running_requests=...` line printed at startup. It samples `nvidia-smi` on an interval, and if `--enable-metrics` is on, scrapes `/metrics` and keeps a short rolling window of histogram deltas for latency percentiles. All of it is exposed as JSON at `/api/status`.
+- `sgtop` polls that JSON and renders it with `curses` — gradient meters, sparkline history, boxed panels, degrading gracefully to a 3-color/16-color palette on terminals without 256-color support.
+
+Both are plain Python, no compiled extensions, so `pipx install` is instant.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

sgtop-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sgtop"
+version = "0.1.0"
+description = "btop-style terminal monitor for a live SGLang deployment"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = []
+authors = [{ name = "HarrytheOrange" }]
+keywords = ["sglang", "llm", "monitoring", "tui", "gpu", "prometheus"]
+classifiers = [
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+
+[project.urls]
+Homepage = "https://github.com/HarrytheOrange/sgtop"
+Issues = "https://github.com/HarrytheOrange/sgtop/issues"
+
+[project.scripts]
+sgtop = "sgtop.cli:main"
+sgtop-server = "sgtop.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sgtop-0.1.0/setup.cfg

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

sgtop-0.1.0/src/sgtop/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sgtop-0.1.0/src/sgtop/app.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import curses
+import time
+from datetime import datetime
+
+from . import theme as th
+from .data import bucket_series, fetch_status
+
+SPARK_WIDTH = 40
+WINDOW_S = 300  # matches the dashboard's own history retention
+
+
+def human_uptime(seconds: float | None) -> str:
+    if not seconds:
+        return "—"
+    seconds = int(seconds)
+    h, rem = divmod(seconds, 3600)
+    m, _ = divmod(rem, 60)
+    d, h = divmod(h, 24)
+    return f"{d}d {h}h {m}m" if d else f"{h}h {m}m"
+
+
+def fmt_secs(value: float | None) -> str:
+    if value is None:
+        return "  n/a"
+    return f"{value*1000:4.0f}ms" if value < 1 else f"{value:5.2f}s"
+
+
+class App:
+    def __init__(self, stdscr, host: str, port: int, interval: float):
+        self.stdscr = stdscr
+        self.host = host
+        self.port = port
+        self.interval = interval
+        self.theme = th.Theme()
+        self.last_status: dict | None = None
+
+    def run(self) -> None:
+        curses.curs_set(0)
+        self.theme.setup()
+        self.stdscr.nodelay(True)
+        self.stdscr.timeout(int(self.interval * 1000))
+        while True:
+            key = self.stdscr.getch()
+            if key in (ord("q"), 27):
+                return
+            status = fetch_status(self.host, self.port)
+            if status is not None:
+                self.last_status = status
+            self.render(self.last_status)
+
+    # -- rendering -----------------------------------------------------
+    def render(self, status: dict | None) -> None:
+        stdscr = self.stdscr
+        stdscr.erase()
+        h, w = stdscr.getmaxyx()
+        boxw = max(50, min(w - 2, 110))
+
+        self._header(0, boxw, status)
+
+        if status is None or not status.get("service_up"):
+            th.safe_addstr(stdscr, 3, 2, "waiting for sglang-dashboard at "
+                            f"{self.host}:{self.port} ...", curses.color_pair(th.PAIR_BAD))
+            self._footer(h - 1, boxw)
+            stdscr.refresh()
+            return
+
+        now = status["now"]
+        caps = status.get("caps", {})
+        active = status.get("active", {})
+        hist_decode = status.get("history", {}).get("decode", [])
+        hist_gpu = status.get("history", {}).get("gpu", [])
+
+        y = 2
+        total_running = total_cap = total_tok = total_tok_cap = 0
+        for i, dp in enumerate(sorted(set(active) | set(caps))):
+            pair = th.PAIR_TITLE_CYAN if i % 2 == 0 else th.PAIR_TITLE_MAGENTA
+            y = self._dp_panel(y, boxw, dp, pair, active.get(dp, {}), caps.get(dp, {}), hist_decode, now)
+            cap = caps.get(dp, {})
+            a = active.get(dp, {})
+            total_running += a.get("running", 0)
+            total_cap += cap.get("max_running", 0)
+            total_tok += a.get("tokens", 0)
+            total_tok_cap += cap.get("max_tokens", 0)
+
+        y = self._total_panel(y, boxw, total_running, total_cap, status["summary"])
+        y = self._latency_panel(y, boxw, status.get("prom", {}))
+        y = self._gpu_panel(y, boxw, status.get("gpus", []), hist_gpu, now)
+
+        errors = status.get("errors", [])
+        if errors:
+            th.safe_addstr(stdscr, y, 0, f"⚠ {len(errors)} error(s) in the last 5min — see logs/deploy.log",
+                            curses.color_pair(th.PAIR_BAD))
+            y += 1
+
+        self._footer(h - 1, boxw)
+        stdscr.refresh()
+
+    def _header(self, y: int, boxw: int, status: dict | None) -> None:
+        stdscr = self.stdscr
+        up = bool(status and status.get("service_up"))
+        dot = "●" if up else "○"
+        dot_pair = th.PAIR_TITLE_CYAN if up else th.PAIR_BAD
+        state = f"online · pid {status.get('pid')}" if up and status else "offline"
+        uptime = human_uptime(status.get("uptime")) if status else "—"
+        clock = datetime.now().strftime("%H:%M:%S")
+
+        th.safe_addstr(stdscr, y, 0, "sgtop", curses.A_BOLD | curses.color_pair(th.PAIR_TITLE_CYAN))
+        th.safe_addstr(stdscr, y, 6, " SGLang concurrency monitor", curses.A_DIM)
+        right = f"{dot} {state}   up {uptime}   {clock}"
+        th.safe_addstr(stdscr, y, max(0, boxw - len(right)), dot, curses.color_pair(dot_pair))
+        th.safe_addstr(stdscr, y, max(0, boxw - len(right)) + 2, right[2:])
+
+    def _footer(self, y: int, boxw: int) -> None:
+        th.safe_addstr(self.stdscr, y, 0, "q quit", curses.A_DIM)
+
+    def _dp_panel(self, y: int, boxw: int, dp: str, title_pair: int, a: dict, cap: dict,
+                  hist_decode: list, now: float) -> int:
+        stdscr = self.stdscr
+        h = 6
+        th.draw_box(stdscr, self.theme, y, 0, h, boxw, dp, title_pair)
+        inner_w = boxw - 4
+        running, queue, tokens = a.get("running", 0), a.get("queue", 0), a.get("tokens", 0)
+        max_running, max_tokens = cap.get("max_running", 0), cap.get("max_tokens", 0)
+
+        if max_running:
+            label = f"concurrency {running}/{max_running} ({running/max_running*100:4.1f}%) q={queue}"
+            bar_w = th.fit_meter_width(inner_w, label)
+            th.draw_meter(stdscr, self.theme, y + 1, 2, bar_w, running / max_running, label)
+        else:
+            th.safe_addstr(stdscr, y + 1, 2, "concurrency: cap unknown (waiting for startup log line)",
+                            curses.color_pair(th.PAIR_DIM))
+
+        if max_tokens:
+            label = f"kv-cache {tokens}/{max_tokens} ({tokens/max_tokens*100:4.1f}%)"
+            bar_w = th.fit_meter_width(inner_w, label)
+            th.draw_meter(stdscr, self.theme, y + 2, 2, bar_w, tokens / max_tokens, label)
+
+        thr_series = bucket_series(hist_decode, "ts", lambda it: it["throughput"], now, WINDOW_S,
+                                    SPARK_WIDTH, filter_fn=lambda it: it.get("dp") == dp)
+        th.draw_sparkline(stdscr, y + 3, 2, thr_series, title_pair)
+        th.safe_addstr(stdscr, y + 3, 2 + SPARK_WIDTH + 2,
+                        f"decode {a.get('throughput', 0):7.1f} tok/s (last 5min)")
+
+        th.safe_addstr(stdscr, y + 4, 2,
+                        f"accept_len={a.get('accept_len', 0):.2f}  accept_rate={a.get('accept_rate', 0)*100:5.1f}%")
+        return y + h + 1
+
+    def _total_panel(self, y: int, boxw: int, running: int, cap: int, summary: dict) -> int:
+        stdscr = self.stdscr
+        h = 4
+        th.draw_box(stdscr, self.theme, y, 0, h, boxw, "TOTAL", th.PAIR_TITLE_ORANGE)
+        inner_w = boxw - 4
+        if cap:
+            label = f"concurrency {running}/{cap} ({running/cap*100:4.1f}%)"
+            bar_w = th.fit_meter_width(inner_w, label)
+            th.draw_meter(stdscr, self.theme, y + 1, 2, bar_w, running / cap, label)
+        th.safe_addstr(stdscr, y + 2, 2,
+                        f"req/min={summary.get('requests_1m', 0):<4d} req/5min={summary.get('requests_5m', 0):<5d} "
+                        f"accept_rate(60s)={summary.get('accept_rate_60s', 0)*100:5.1f}%")
+        return y + h + 1
+
+    def _latency_panel(self, y: int, boxw: int, prom: dict) -> int:
+        """TTFT / E2E / queue-time / cache-hit — everything that needs sglang
+        started with --enable-metrics. TTFT and E2E have no per-DP label
+        (sglang aggregates them server-wide), queue-time and cache-hit do."""
+        stdscr = self.stdscr
+        h = 5
+        th.draw_box(stdscr, self.theme, y, 0, h, boxw, "LATENCY (--enable-metrics, 5min)", th.PAIR_TITLE_MAGENTA)
+
+        if not prom.get("enabled"):
+            th.safe_addstr(stdscr, y + 2, 2,
+                            "not enabled — add --enable-metrics to serve517.sh and restart to see this",
+                            curses.color_pair(th.PAIR_DIM))
+            return y + h + 1
+
+        latency = prom.get("latency", {})
+        queue_by_dp = prom.get("queue_by_dp", {})
+        cache_by_dp = prom.get("cache_hit_by_dp", {})
+
+        def stat_row(row: int, label: str, s: dict | None) -> None:
+            if not s:
+                th.safe_addstr(stdscr, row, 2, f"{label:<5} no samples yet", curses.color_pair(th.PAIR_DIM))
+                return
+            th.safe_addstr(stdscr, row, 2,
+                            f"{label:<5} mean={fmt_secs(s['mean'])}  p50={fmt_secs(s['p50'])}  "
+                            f"p90={fmt_secs(s['p90'])}  p99={fmt_secs(s['p99'])}  n={s['count']:.0f}")
+
+        stat_row(y + 1, "TTFT", latency.get("ttft"))
+        stat_row(y + 2, "E2E", latency.get("e2e"))
+
+        parts = []
+        for dp in sorted(set(queue_by_dp) | set(cache_by_dp)):
+            q = queue_by_dp.get(dp)
+            qtxt = f"p50={fmt_secs(q['p50'])} p90={fmt_secs(q['p90'])}" if q else "no samples"
+            ch = cache_by_dp.get(dp)
+            chtxt = f" cache-hit={ch*100:4.1f}%" if ch is not None else ""
+            parts.append(f"DP{dp} queue {qtxt}{chtxt}")
+        th.safe_addstr(stdscr, y + 3, 2, "   ".join(parts))
+        return y + h + 1
+
+    def _gpu_panel(self, y: int, boxw: int, gpus: list, hist_gpu: list, now: float) -> int:
+        stdscr = self.stdscr
+        n = max(1, len(gpus))
+        h = n + 2
+        th.draw_box(stdscr, self.theme, y, 0, h, boxw, "GPUs", th.PAIR_TITLE_CYAN)
+        inner_w = boxw - 4
+        bar_w = min(24, max(6, inner_w - 55))
+        for i, g in enumerate(gpus):
+            row = y + 1 + i
+            label = f"GPU{g['index']}"
+            th.safe_addstr(stdscr, row, 2, label)
+            end_x = th.draw_meter(stdscr, self.theme, row, 2 + len(label) + 1, bar_w, g["util"] / 100,
+                                   f"{g['util']:5.1f}%")
+            th.safe_addstr(stdscr, row, end_x + 2,
+                            f"mem={g['mem_used']:6.0f}/{g['mem_total']:6.0f}MiB  "
+                            f"{g['temp']:3.0f}C  {g['power']:5.1f}W")
+        return y + h + 1

sgtop-0.1.0/src/sgtop/cli.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import argparse
+import curses
+
+from .app import App
+from .data import DEFAULT_HOST, DEFAULT_PORT
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="btop-style terminal monitor for a live SGLang deployment. "
+        "Reads a running monitor_dashboard.py's /api/status endpoint — no local "
+        "file access, so it works against any host on the LAN serving one."
+    )
+    ap.add_argument("--host", default=DEFAULT_HOST, help=f"dashboard host (default: {DEFAULT_HOST})")
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"dashboard port (default: {DEFAULT_PORT})")
+    ap.add_argument("--interval", type=float, default=1.0, help="refresh interval in seconds (default: 1.0)")
+    args = ap.parse_args()
+
+    def _run(stdscr):
+        App(stdscr, args.host, args.port, args.interval).run()
+
+    curses.wrapper(_run)
+
+
+if __name__ == "__main__":
+    main()

sgtop-0.1.0/src/sgtop/data.py

@@ -0,0 +1,50 @@
+"""Networking + time-series helpers. No filesystem access: everything comes
+from a running monitor_dashboard.py's /api/status endpoint, so sgtop can
+point at any host on the LAN that's serving one."""
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Callable, Optional
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 30001
+
+
+def fetch_status(host: str, port: int, timeout: float = 2.0) -> Optional[dict]:
+    try:
+        with urllib.request.urlopen(f"http://{host}:{port}/api/status", timeout=timeout) as r:
+            return json.loads(r.read())
+    except Exception:
+        return None
+
+
+def bucket_series(
+    items: list[dict],
+    ts_key: str,
+    value_fn: Callable[[dict], Optional[float]],
+    now: float,
+    window_s: float,
+    width: int,
+    filter_fn: Optional[Callable[[dict], bool]] = None,
+) -> list[float]:
+    """Bucket `items` into `width` evenly-spaced buckets covering the last
+    `window_s` seconds, averaging value_fn(item) within each bucket. Empty
+    buckets come back as 0.0, so the sparkline reads as "idle", not "no data".
+    """
+    if width <= 0:
+        return []
+    buckets: list[list[float]] = [[] for _ in range(width)]
+    start = now - window_s
+    step = window_s / width
+    for item in items:
+        if filter_fn is not None and not filter_fn(item):
+            continue
+        ts = item.get(ts_key)
+        if ts is None or ts < start:
+            continue
+        idx = min(width - 1, max(0, int((ts - start) / step)))
+        v = value_fn(item)
+        if v is not None:
+            buckets[idx].append(v)
+    return [sum(b) / len(b) if b else 0.0 for b in buckets]