vllmpytop 0.1.0__tar.gz

vllmpytop-0.1.0/LICENSE

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

vllmpytop-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: vllmpytop
+Version: 0.1.0
+Summary: A btop-style terminal UI for monitoring a vLLM instance and its GPU in real time.
+Author-email: Theodore Kirby <theo@kirby.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theo-kirby/vllmtop
+Project-URL: Repository, https://github.com/theo-kirby/vllmtop
+Project-URL: Issues, https://github.com/theo-kirby/vllmtop/issues
+Keywords: vllm,gpu,monitoring,tui,terminal,btop,nvml,prometheus,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nvidia-ml-py>=12.0
+Requires-Dist: prometheus-client>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# vllmtop
+
+A **btop-style terminal UI** for monitoring a running [vLLM](https://github.com/vllm-project/vllm)
+instance and its GPU in real time. Hand-rolled braille charts, a responsive
+curses layout, and a non-blocking background poller so the UI never stalls on
+network or NVML latency.
+
+```
+╭─┐¹ gpu ┌──────────────────────────────────────────────────────────────────╮
+│ NVIDIA GeForce RTX 5090   util  86%   50°C  319/600W  SM 2857MHz  fan 31%   │
+│ ⣿⣿⣿⣿ … braille utilisation chart …                                          │
+│ VRAM 27.3GB/31.8GB ████████████████████░░░  86%                             │
+│ PWR  ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░  53%                             │
+╰─────────────────────────────────────────────────────────────────────────────╯
+╭─┐² throughput ┌────────────╮╭─┐³ requests ┌──────────────╮
+│ gen 149 tok/s   ⣀⣤⣶⣿        ││ running ████░░ 1            │
+│ prompt 3.5k tok/s          ││ waiting ██████ 2            │
+╰─┘ tok/s └──────────────────╯╰─┘ queue └───────────────────╯
+╭─┐⁴ latency ┌───────────────╮╭─┐⁵ cache ┌──────────────────╮
+│ TTFT 964ms  TPOT 6ms …     ││ KV █░░░  3%  prefix 0.0%    │
+╰─┘ recent avg └─────────────╯╰─────────────────────────────╯
+```
+
+Rounded corners, superscript panel numbers in the title tabs, and a secondary
+label on the bottom edge — matching [btop](https://github.com/aristocratos/btop)'s box style.
+
+## What it shows
+
+- **GPU** (via NVML / `pynvml`): utilisation %, VRAM used/total, temperature,
+  power draw vs. limit, SM clock, fan — with green/yellow/red thresholds.
+- **Throughput**: generation tok/s and prompt tok/s (rates derived from vLLM
+  counters), as big numbers + braille charts.
+- **Requests / Queue**: running vs. waiting requests and preemptions.
+- **Latency** (recent average over the last poll interval — far more useful live
+  than the cumulative average): TTFT, inter-token (TPOT), end-to-end, queue time.
+- **Cache**: KV-cache usage % and prefix-cache hit rate.
+
+Data comes from vLLM's Prometheus `/metrics` endpoint plus in-process NVML
+polling. If vLLM goes away (e.g. a container restart) the UI shows a disconnect
+banner and keeps the GPU panel live, then reconnects automatically.
+
+## Install
+
+Requires Python 3.10+ on Linux (curses is stdlib). A working NVIDIA driver is
+needed for the GPU panel.
+
+```bash
+pip install .
+# or, for development:
+pip install -e ".[dev]"
+```
+
+Dependencies: `nvidia-ml-py` (NVML bindings) and `prometheus-client` (exposition
+parser). The `/metrics` fetch uses stdlib `urllib`.
+
+## Usage
+
+```bash
+vllmtop                              # monitor http://localhost:8000
+vllmtop --url http://host:8000       # a remote vLLM server
+vllmtop --interval 0.5               # poll twice a second
+vllmtop --no-gpu                     # skip the GPU panel
+python -m vllmtop                    # same thing, without the entry point
+```
+
+The server URL can also be set via the `VLLMTOP_URL` environment variable.
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--url` | `http://localhost:8000` | vLLM base URL (env `VLLMTOP_URL`) |
+| `--interval` | `1.0` | poll interval in seconds |
+| `--gpu-index` | `0` | NVML GPU index |
+| `--no-gpu` | off | disable the GPU panel |
+| `--dump-json` | off | collect one snapshot, print JSON, exit (no TTY) |
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` / `Esc` | quit |
+| `+` / `-` | faster / slower refresh |
+| `p` | pause / resume polling |
+| `1`–`5` | toggle a panel on/off (¹gpu ²throughput ³requests ⁴latency ⁵cache) |
+| `h` / `?` | toggle help overlay |
+
+Each panel's title carries a superscript number (btop-style) showing the key
+that toggles it. Hiding panels reflows the rest to fill the freed space.
+
+### Headless smoke test
+
+`--dump-json` collects two snapshots an interval apart (so rates are populated),
+prints the result as JSON, and exits. Works without a TTY — handy for CI or
+verifying connectivity:
+
+```bash
+python -m vllmtop --dump-json --url http://localhost:8000
+```
+
+## How it works
+
+- A **background poller thread** scrapes `/metrics` and polls NVML every
+  `interval` seconds, storing the latest combined snapshot under a lock. This
+  keeps all I/O latency off the render path.
+- The **UI loop** wakes on a short tick (250 ms), reads the latest snapshot,
+  appends derived values (rates, recent-average latencies) to per-series ring
+  buffers, and redraws — so render cadence is independent of poll cadence.
+- **Counters → rates**: `Δvalue / Δt`, guarded against `Δt ≤ 0` and counter
+  resets. **Histograms → recent average**: `Δsum / Δcount` between polls.
+- **Braille charts**: each cell is a 2×4 Unicode braille dot matrix, giving
+  `2w × 4h`-dot resolution for the smooth btop look.
+
+## Development
+
+```bash
+pytest        # parser-against-fixture, rate math, braille rendering
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vllmpytop-0.1.0/README.md

@@ -0,0 +1,122 @@
+# vllmtop
+
+A **btop-style terminal UI** for monitoring a running [vLLM](https://github.com/vllm-project/vllm)
+instance and its GPU in real time. Hand-rolled braille charts, a responsive
+curses layout, and a non-blocking background poller so the UI never stalls on
+network or NVML latency.
+
+```
+╭─┐¹ gpu ┌──────────────────────────────────────────────────────────────────╮
+│ NVIDIA GeForce RTX 5090   util  86%   50°C  319/600W  SM 2857MHz  fan 31%   │
+│ ⣿⣿⣿⣿ … braille utilisation chart …                                          │
+│ VRAM 27.3GB/31.8GB ████████████████████░░░  86%                             │
+│ PWR  ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░  53%                             │
+╰─────────────────────────────────────────────────────────────────────────────╯
+╭─┐² throughput ┌────────────╮╭─┐³ requests ┌──────────────╮
+│ gen 149 tok/s   ⣀⣤⣶⣿        ││ running ████░░ 1            │
+│ prompt 3.5k tok/s          ││ waiting ██████ 2            │
+╰─┘ tok/s └──────────────────╯╰─┘ queue └───────────────────╯
+╭─┐⁴ latency ┌───────────────╮╭─┐⁵ cache ┌──────────────────╮
+│ TTFT 964ms  TPOT 6ms …     ││ KV █░░░  3%  prefix 0.0%    │
+╰─┘ recent avg └─────────────╯╰─────────────────────────────╯
+```
+
+Rounded corners, superscript panel numbers in the title tabs, and a secondary
+label on the bottom edge — matching [btop](https://github.com/aristocratos/btop)'s box style.
+
+## What it shows
+
+- **GPU** (via NVML / `pynvml`): utilisation %, VRAM used/total, temperature,
+  power draw vs. limit, SM clock, fan — with green/yellow/red thresholds.
+- **Throughput**: generation tok/s and prompt tok/s (rates derived from vLLM
+  counters), as big numbers + braille charts.
+- **Requests / Queue**: running vs. waiting requests and preemptions.
+- **Latency** (recent average over the last poll interval — far more useful live
+  than the cumulative average): TTFT, inter-token (TPOT), end-to-end, queue time.
+- **Cache**: KV-cache usage % and prefix-cache hit rate.
+
+Data comes from vLLM's Prometheus `/metrics` endpoint plus in-process NVML
+polling. If vLLM goes away (e.g. a container restart) the UI shows a disconnect
+banner and keeps the GPU panel live, then reconnects automatically.
+
+## Install
+
+Requires Python 3.10+ on Linux (curses is stdlib). A working NVIDIA driver is
+needed for the GPU panel.
+
+```bash
+pip install .
+# or, for development:
+pip install -e ".[dev]"
+```
+
+Dependencies: `nvidia-ml-py` (NVML bindings) and `prometheus-client` (exposition
+parser). The `/metrics` fetch uses stdlib `urllib`.
+
+## Usage
+
+```bash
+vllmtop                              # monitor http://localhost:8000
+vllmtop --url http://host:8000       # a remote vLLM server
+vllmtop --interval 0.5               # poll twice a second
+vllmtop --no-gpu                     # skip the GPU panel
+python -m vllmtop                    # same thing, without the entry point
+```
+
+The server URL can also be set via the `VLLMTOP_URL` environment variable.
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--url` | `http://localhost:8000` | vLLM base URL (env `VLLMTOP_URL`) |
+| `--interval` | `1.0` | poll interval in seconds |
+| `--gpu-index` | `0` | NVML GPU index |
+| `--no-gpu` | off | disable the GPU panel |
+| `--dump-json` | off | collect one snapshot, print JSON, exit (no TTY) |
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` / `Esc` | quit |
+| `+` / `-` | faster / slower refresh |
+| `p` | pause / resume polling |
+| `1`–`5` | toggle a panel on/off (¹gpu ²throughput ³requests ⁴latency ⁵cache) |
+| `h` / `?` | toggle help overlay |
+
+Each panel's title carries a superscript number (btop-style) showing the key
+that toggles it. Hiding panels reflows the rest to fill the freed space.
+
+### Headless smoke test
+
+`--dump-json` collects two snapshots an interval apart (so rates are populated),
+prints the result as JSON, and exits. Works without a TTY — handy for CI or
+verifying connectivity:
+
+```bash
+python -m vllmtop --dump-json --url http://localhost:8000
+```
+
+## How it works
+
+- A **background poller thread** scrapes `/metrics` and polls NVML every
+  `interval` seconds, storing the latest combined snapshot under a lock. This
+  keeps all I/O latency off the render path.
+- The **UI loop** wakes on a short tick (250 ms), reads the latest snapshot,
+  appends derived values (rates, recent-average latencies) to per-series ring
+  buffers, and redraws — so render cadence is independent of poll cadence.
+- **Counters → rates**: `Δvalue / Δt`, guarded against `Δt ≤ 0` and counter
+  resets. **Histograms → recent average**: `Δsum / Δcount` between polls.
+- **Braille charts**: each cell is a 2×4 Unicode braille dot matrix, giving
+  `2w × 4h`-dot resolution for the smooth btop look.
+
+## Development
+
+```bash
+pytest        # parser-against-fixture, rate math, braille rendering
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vllmpytop-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vllmpytop"
+version = "0.1.0"
+description = "A btop-style terminal UI for monitoring a vLLM instance and its GPU in real time."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Theodore Kirby", email = "theo@kirby.dev" }]
+keywords = ["vllm", "gpu", "monitoring", "tui", "terminal", "btop", "nvml", "prometheus", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "nvidia-ml-py>=12.0",
+    "prometheus-client>=0.20",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build>=1.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/theo-kirby/vllmtop"
+Repository = "https://github.com/theo-kirby/vllmtop"
+Issues = "https://github.com/theo-kirby/vllmtop/issues"
+
+[project.scripts]
+vllmtop = "vllmtop.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vllmtop*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vllmpytop-0.1.0/setup.cfg

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

vllmpytop-0.1.0/tests/test_prometheus.py

@@ -0,0 +1,42 @@
+import math
+from pathlib import Path
+
+from vllmtop.collectors.vllm import parse_metrics
+
+FIXTURE = Path(__file__).parent / "metrics_fixture.txt"
+
+
+def _snap():
+    return parse_metrics(FIXTURE.read_text())
+
+
+def test_reachable_and_model():
+    snap = _snap()
+    assert snap.reachable is True
+    assert snap.model_name == "Qwen/Qwen3.6-35B-A3B"
+
+
+def test_scalar_values():
+    snap = _snap()
+    assert snap.num_requests_running == 0.0
+    assert snap.num_requests_waiting == 0.0
+    assert snap.kv_cache_usage_perc == 0.0
+    # 5.7351109e+07 from the fixture.
+    assert snap.prompt_tokens_total == 57351109.0
+    assert snap.generation_tokens_total == 1799939.0
+    assert snap.num_preemptions_total == 0.0
+
+
+def test_histograms_parsed():
+    snap = _snap()
+    # Histograms exist with a +Inf bucket and consistent count.
+    for hist in (snap.ttft, snap.inter_token, snap.e2e, snap.queue_time):
+        assert math.inf in hist.buckets
+        # The +Inf bucket count equals the total observation count.
+        assert hist.buckets[math.inf] == hist.count
+
+
+def test_prefix_cache_hit_rate_guarded():
+    snap = _snap()
+    # queries_total is 0 in the fixture -> guarded to 0, no ZeroDivisionError.
+    assert snap.prefix_cache_hit_rate == 0.0

vllmpytop-0.1.0/tests/test_state.py

@@ -0,0 +1,86 @@
+import math
+
+from vllmtop.config import HISTORY_LEN
+from vllmtop.state import (
+    GpuSnapshot,
+    Histogram,
+    History,
+    Series,
+    Snapshot,
+    VllmSnapshot,
+    compute_rate,
+    histogram_quantile,
+    histogram_recent_avg,
+)
+from vllmtop.ui.widgets import braille_chart
+
+
+def test_compute_rate_basic():
+    assert compute_rate(100.0, 10.0, 200.0, 12.0) == 50.0
+
+
+def test_compute_rate_guards():
+    # Non-positive dt -> 0.
+    assert compute_rate(100.0, 10.0, 200.0, 10.0) == 0.0
+    # Counter reset (value decreased) -> 0, not negative.
+    assert compute_rate(200.0, 10.0, 50.0, 12.0) == 0.0
+
+
+def test_histogram_recent_avg():
+    prev = Histogram(count=10.0, sum=5.0)
+    cur = Histogram(count=14.0, sum=13.0)
+    # (13-5)/(14-10) = 2.0
+    assert histogram_recent_avg(prev, cur) == 2.0
+    # No new observations -> 0.
+    assert histogram_recent_avg(cur, cur) == 0.0
+
+
+def test_histogram_quantile():
+    # Buckets le=1 -> 0, le=2 -> 0, le=5 -> 10 new obs in window.
+    prev = Histogram(count=0.0, buckets={1.0: 0.0, 2.0: 0.0, 5.0: 0.0, math.inf: 0.0})
+    cur = Histogram(count=10.0, buckets={1.0: 0.0, 2.0: 0.0, 5.0: 10.0, math.inf: 10.0})
+    q = histogram_quantile(prev, cur, 0.5)
+    # All mass in (2, 5]; median interpolates inside that bucket.
+    assert 2.0 <= q <= 5.0
+
+
+def test_series_ring_buffer():
+    s = Series(maxlen=3)
+    for i in range(5):
+        s.append(i)
+    assert s.values() == [2, 3, 4]
+    assert s.last == 4
+
+
+def _snap(t, gen_total, running, gpu_util):
+    return Snapshot(
+        monotonic=t,
+        vllm=VllmSnapshot(
+            reachable=True,
+            generation_tokens_total=gen_total,
+            num_requests_running=running,
+        ),
+        gpu=GpuSnapshot(available=True, util_gpu=gpu_util),
+    )
+
+
+def test_history_rate_from_two_samples():
+    h = History(HISTORY_LEN)
+    h.update(_snap(0.0, 1000.0, 1, 10.0))
+    h.update(_snap(2.0, 1200.0, 2, 20.0))
+    # (1200-1000)/2 = 100 tok/s
+    assert h.derived["gen_tok_s"] == 100.0
+    assert h.derived["running"] == 2.0
+    assert h.derived["gpu_util"] == 20.0
+    assert h.series["gen_tok_s"].values() == [0.0, 100.0]
+
+
+def test_braille_chart_shape():
+    series = [math.sin(i / 5.0) for i in range(100)]
+    w, height = 20, 4
+    rows = braille_chart(series, w, height, 0.0, 1.0)
+    assert len(rows) == height
+    for row in rows:
+        assert len(row) == w
+        # Every cell is a braille glyph in the U+2800 block.
+        assert all(0x2800 <= ord(ch) <= 0x28FF for ch in row)

vllmpytop-0.1.0/vllmpytop.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: vllmpytop
+Version: 0.1.0
+Summary: A btop-style terminal UI for monitoring a vLLM instance and its GPU in real time.
+Author-email: Theodore Kirby <theo@kirby.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theo-kirby/vllmtop
+Project-URL: Repository, https://github.com/theo-kirby/vllmtop
+Project-URL: Issues, https://github.com/theo-kirby/vllmtop/issues
+Keywords: vllm,gpu,monitoring,tui,terminal,btop,nvml,prometheus,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nvidia-ml-py>=12.0
+Requires-Dist: prometheus-client>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# vllmtop
+
+A **btop-style terminal UI** for monitoring a running [vLLM](https://github.com/vllm-project/vllm)
+instance and its GPU in real time. Hand-rolled braille charts, a responsive
+curses layout, and a non-blocking background poller so the UI never stalls on
+network or NVML latency.
+
+```
+╭─┐¹ gpu ┌──────────────────────────────────────────────────────────────────╮
+│ NVIDIA GeForce RTX 5090   util  86%   50°C  319/600W  SM 2857MHz  fan 31%   │
+│ ⣿⣿⣿⣿ … braille utilisation chart …                                          │
+│ VRAM 27.3GB/31.8GB ████████████████████░░░  86%                             │
+│ PWR  ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░  53%                             │
+╰─────────────────────────────────────────────────────────────────────────────╯
+╭─┐² throughput ┌────────────╮╭─┐³ requests ┌──────────────╮
+│ gen 149 tok/s   ⣀⣤⣶⣿        ││ running ████░░ 1            │
+│ prompt 3.5k tok/s          ││ waiting ██████ 2            │
+╰─┘ tok/s └──────────────────╯╰─┘ queue └───────────────────╯
+╭─┐⁴ latency ┌───────────────╮╭─┐⁵ cache ┌──────────────────╮
+│ TTFT 964ms  TPOT 6ms …     ││ KV █░░░  3%  prefix 0.0%    │
+╰─┘ recent avg └─────────────╯╰─────────────────────────────╯
+```
+
+Rounded corners, superscript panel numbers in the title tabs, and a secondary
+label on the bottom edge — matching [btop](https://github.com/aristocratos/btop)'s box style.
+
+## What it shows
+
+- **GPU** (via NVML / `pynvml`): utilisation %, VRAM used/total, temperature,
+  power draw vs. limit, SM clock, fan — with green/yellow/red thresholds.
+- **Throughput**: generation tok/s and prompt tok/s (rates derived from vLLM
+  counters), as big numbers + braille charts.
+- **Requests / Queue**: running vs. waiting requests and preemptions.
+- **Latency** (recent average over the last poll interval — far more useful live
+  than the cumulative average): TTFT, inter-token (TPOT), end-to-end, queue time.
+- **Cache**: KV-cache usage % and prefix-cache hit rate.
+
+Data comes from vLLM's Prometheus `/metrics` endpoint plus in-process NVML
+polling. If vLLM goes away (e.g. a container restart) the UI shows a disconnect
+banner and keeps the GPU panel live, then reconnects automatically.
+
+## Install
+
+Requires Python 3.10+ on Linux (curses is stdlib). A working NVIDIA driver is
+needed for the GPU panel.
+
+```bash
+pip install .
+# or, for development:
+pip install -e ".[dev]"
+```
+
+Dependencies: `nvidia-ml-py` (NVML bindings) and `prometheus-client` (exposition
+parser). The `/metrics` fetch uses stdlib `urllib`.
+
+## Usage
+
+```bash
+vllmtop                              # monitor http://localhost:8000
+vllmtop --url http://host:8000       # a remote vLLM server
+vllmtop --interval 0.5               # poll twice a second
+vllmtop --no-gpu                     # skip the GPU panel
+python -m vllmtop                    # same thing, without the entry point
+```
+
+The server URL can also be set via the `VLLMTOP_URL` environment variable.
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--url` | `http://localhost:8000` | vLLM base URL (env `VLLMTOP_URL`) |
+| `--interval` | `1.0` | poll interval in seconds |
+| `--gpu-index` | `0` | NVML GPU index |
+| `--no-gpu` | off | disable the GPU panel |
+| `--dump-json` | off | collect one snapshot, print JSON, exit (no TTY) |
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` / `Esc` | quit |
+| `+` / `-` | faster / slower refresh |
+| `p` | pause / resume polling |
+| `1`–`5` | toggle a panel on/off (¹gpu ²throughput ³requests ⁴latency ⁵cache) |
+| `h` / `?` | toggle help overlay |
+
+Each panel's title carries a superscript number (btop-style) showing the key
+that toggles it. Hiding panels reflows the rest to fill the freed space.
+
+### Headless smoke test
+
+`--dump-json` collects two snapshots an interval apart (so rates are populated),
+prints the result as JSON, and exits. Works without a TTY — handy for CI or
+verifying connectivity:
+
+```bash
+python -m vllmtop --dump-json --url http://localhost:8000
+```
+
+## How it works
+
+- A **background poller thread** scrapes `/metrics` and polls NVML every
+  `interval` seconds, storing the latest combined snapshot under a lock. This
+  keeps all I/O latency off the render path.
+- The **UI loop** wakes on a short tick (250 ms), reads the latest snapshot,
+  appends derived values (rates, recent-average latencies) to per-series ring
+  buffers, and redraws — so render cadence is independent of poll cadence.
+- **Counters → rates**: `Δvalue / Δt`, guarded against `Δt ≤ 0` and counter
+  resets. **Histograms → recent average**: `Δsum / Δcount` between polls.
+- **Braille charts**: each cell is a 2×4 Unicode braille dot matrix, giving
+  `2w × 4h`-dot resolution for the smooth btop look.
+
+## Development
+
+```bash
+pytest        # parser-against-fixture, rate math, braille rendering
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

vllmpytop-0.1.0/vllmpytop.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_prometheus.py
+tests/test_state.py
+vllmpytop.egg-info/PKG-INFO
+vllmpytop.egg-info/SOURCES.txt
+vllmpytop.egg-info/dependency_links.txt
+vllmpytop.egg-info/entry_points.txt
+vllmpytop.egg-info/requires.txt
+vllmpytop.egg-info/top_level.txt
+vllmtop/__init__.py
+vllmtop/__main__.py
+vllmtop/cli.py
+vllmtop/config.py
+vllmtop/state.py
+vllmtop/collectors/__init__.py
+vllmtop/collectors/gpu.py
+vllmtop/collectors/vllm.py
+vllmtop/ui/__init__.py
+vllmtop/ui/app.py
+vllmtop/ui/layout.py
+vllmtop/ui/panels.py
+vllmtop/ui/theme.py
+vllmtop/ui/widgets.py

vllmpytop-0.1.0/vllmpytop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vllmpytop-0.1.0/vllmpytop.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vllmtop = vllmtop.cli:main