vllmstat 0.1.0__py3-none-any.whl

vllmstat/__init__.py

@@ -0,0 +1,3 @@
+"""vllmstat — an interactive terminal dashboard for vLLM serving performance."""
+
+__version__ = "0.1.0"

vllmstat/__main__.py

@@ -0,0 +1,4 @@
+from vllmstat.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vllmstat/app.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import time
+
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.timer import Timer
+from textual.widgets import Footer
+
+from vllmstat import render
+from vllmstat.config import Config
+from vllmstat.core.history import History
+from vllmstat.core.metrics import MetricsEngine
+from vllmstat.core.parse import parse_metrics
+from vllmstat.core.state import Snapshot
+from vllmstat.model_dims import load_model_dims
+from vllmstat.providers.gpu import GpuProvider
+from vllmstat.providers.mock import MockProvider, mock_gpu_snapshot
+from vllmstat.providers.vllm import VllmProvider
+from vllmstat.widgets import Panel
+
+
+class VllmStatApp(App):
+    CSS = """
+    Panel { border: round $primary; padding: 0 1; height: auto; }
+    #row1 { height: auto; }
+    #row1 Panel { width: 1fr; }
+    #gpu { height: auto; }
+    """
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("p", "toggle_pause", "Pause"),
+        ("g", "toggle_gpu", "GPU"),
+        ("plus,equals_sign", "faster", "Faster"),
+        ("minus", "slower", "Slower"),
+    ]
+
+    def __init__(self, cfg: Config) -> None:
+        super().__init__()
+        self.cfg = cfg
+        self.paused = False
+        self.snapshot: Snapshot | None = None
+        self._history = History()
+        self._engine = MetricsEngine()
+        self._gpu = GpuProvider(enabled=cfg.gpu)
+        self._mock = MockProvider() if cfg.mock else None
+        self._vllm = (
+            None
+            if cfg.mock
+            else VllmProvider(base_url=cfg.url, metrics_path=cfg.metrics_path, api_key=cfg.api_key)
+        )
+        self._model_names: list[str] = []
+        self._dims_loaded = cfg.mock  # mock keeps the plain engine; nothing to fetch
+        self._start = time.monotonic()
+        self._tick_n = 0
+        self._timer: Timer | None = None
+        self._in_tick = False
+
+    def compose(self) -> ComposeResult:
+        self.p_header = Panel(id="hdr")
+        self.p_conc = Panel(id="conc")
+        self.p_tput = Panel(id="tput")
+        self.p_lat = Panel(id="lat")
+        self.p_cache = Panel(id="cache")
+        self.p_eff = Panel(id="eff")
+        self.p_spec = Panel(id="spec")
+        self.p_gpu = Panel(id="gpu")
+        yield self.p_header
+        with Horizontal(id="row1"):
+            yield self.p_conc
+            yield self.p_tput
+            yield self.p_lat
+        yield self.p_cache
+        yield self.p_eff
+        yield self.p_spec
+        yield self.p_gpu
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._timer = self.set_interval(self.cfg.interval, self.tick)
+        self.call_later(self.tick)
+
+    async def _ensure_dims(self) -> None:
+        """Once, in vLLM mode, fetch model info and rebuild the engine with KV dims."""
+        if self._dims_loaded or self._vllm is None:
+            return
+        self._dims_loaded = True  # set before await so we only attempt once
+        info = await self._vllm.fetch_model_info()
+        md = load_model_dims(info.root, info.max_model_len)
+        self._engine = MetricsEngine(dims=md.dims, max_model_len=md.max_model_len)
+        self._model_names = info.model_names
+
+    async def _sample_text(self) -> tuple[str, bool, str | None]:
+        if self._mock is not None:
+            return self._mock.metrics_text(), True, None
+        assert self._vllm is not None
+        raw = await self._vllm.fetch_metrics()
+        return raw.text, raw.fetched_ok, raw.error
+
+    async def tick(self) -> None:
+        if self.paused or self._in_tick:
+            return
+        self._in_tick = True
+        try:
+            await self._tick_body()
+        finally:
+            self._in_tick = False
+
+    async def _tick_body(self) -> None:
+        await self._ensure_dims()
+        self._tick_n += 1
+        text, ok, err = await self._sample_text()
+        now = time.monotonic()
+        if ok and text:
+            fam = parse_metrics(text)
+            snap = self._engine.derive(fam, now=now)
+        else:
+            snap = self.snapshot or Snapshot(ts=now, connected=False, error=err)
+            snap.connected = False
+            snap.error = err
+        if self._mock is not None and self._gpu.enabled:
+            snap.gpu = mock_gpu_snapshot(self._tick_n)
+        else:
+            snap.gpu = self._gpu.sample()
+        self._push_history(snap)
+        self.snapshot = snap
+        self._refresh(snap)
+
+    def _push_history(self, s: Snapshot) -> None:
+        self._history.push("running", s.running)
+        self._history.push("waiting", s.waiting)
+        self._history.push("gen_tps", s.gen_tps)
+        self._history.push("prompt_tps", s.prompt_tps)
+        if s.prefix_hit_window is not None:
+            self._history.push("prefix_hit", s.prefix_hit_window)
+
+    def _uptime(self) -> str:
+        secs = int(time.monotonic() - self._start)
+        h, rem = divmod(secs, 3600)
+        m, _ = divmod(rem, 60)
+        return f"{h}h{m:02d}m"
+
+    def _refresh(self, s: Snapshot) -> None:
+        self.p_header.update(
+            render.header(s, url=self.cfg.url, interval=self.cfg.interval, uptime=self._uptime())
+        )
+        self.p_conc.update(render.concurrency(s, self._history))
+        self.p_tput.update(render.throughput(s, self._history))
+        self.p_lat.update(render.latency(s))
+        self.p_cache.update(render.cache_kv(s, self._history))
+        eff = render.efficiency(s)
+        self.p_eff.display = bool(eff)
+        self.p_eff.update(eff)
+        spec = render.specdecode(s)
+        self.p_spec.display = bool(spec)
+        self.p_spec.update(spec)
+        self.p_gpu.update(render.gpu(s))
+
+    def action_toggle_pause(self) -> None:
+        self.paused = not self.paused
+
+    def action_toggle_gpu(self) -> None:
+        self._gpu.enabled = not self._gpu.enabled
+
+    def action_faster(self) -> None:
+        self.cfg.interval = max(0.1, self.cfg.interval / 2)
+        self._reschedule()
+
+    def action_slower(self) -> None:
+        self.cfg.interval = min(10.0, self.cfg.interval * 2)
+        self._reschedule()
+
+    def _reschedule(self) -> None:
+        # restart the interval timer at the new cadence (Textual >=8: Timer.stop + recreate)
+        if self._timer is not None:
+            self._timer.stop()
+        self._timer = self.set_interval(self.cfg.interval, self.tick)
+
+
+def run_app(cfg: Config) -> int:
+    VllmStatApp(cfg).run()
+    return 0

vllmstat/cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+from vllmstat.config import Config
+from vllmstat.core.metrics import MetricsEngine
+from vllmstat.core.parse import parse_metrics
+from vllmstat.providers.mock import MockProvider
+from vllmstat.snapshot_json import snapshot_to_dict
+
+
+def run_once_json(argv: list[str]) -> int:
+    cfg = Config.from_sources(argv, dict(os.environ))
+    if cfg.mock:
+        eng = MetricsEngine(dims=None, max_model_len=None)
+        mp = MockProvider()
+        eng.derive(parse_metrics(mp.metrics_text()), now=0.0)
+        snap = eng.derive(parse_metrics(mp.metrics_text()), now=1.0)
+    else:
+        import asyncio
+
+        from vllmstat.model_dims import load_model_dims
+        from vllmstat.providers.vllm import VllmProvider
+
+        async def _go():
+            p = VllmProvider(base_url=cfg.url, metrics_path=cfg.metrics_path, api_key=cfg.api_key)
+            info = await p.fetch_model_info()
+            r0 = await p.fetch_metrics()
+            time.sleep(min(cfg.interval, 1.0))
+            r1 = await p.fetch_metrics()
+            await p.aclose()
+            return info, r0, r1
+
+        info, r0, r1 = asyncio.run(_go())
+        if not r1.fetched_ok:
+            print(json.dumps({"error": r1.error}), file=sys.stderr)
+            return 1
+        md = load_model_dims(info.root, info.max_model_len)
+        eng = MetricsEngine(dims=md.dims, max_model_len=md.max_model_len)
+        eng.derive(parse_metrics(r0.text), now=0.0)
+        snap = eng.derive(parse_metrics(r1.text), now=1.0)
+    print(json.dumps(snapshot_to_dict(snap), default=str))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cfg = Config.from_sources(argv, dict(os.environ))
+    if cfg.once and cfg.json:
+        return run_once_json(argv)
+    from vllmstat.app import run_app  # imported lazily so --once/--json needs no Textual
+
+    return run_app(cfg)

vllmstat/config.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+
+from vllmstat import __version__
+
+
+@dataclass
+class Config:
+    url: str = "http://localhost:8000"
+    metrics_path: str = "/metrics"
+    interval: float = 1.0
+    api_key: str | None = None
+    gpu: bool = True
+    mock: bool = False
+    once: bool = False
+    json: bool = False
+
+    @staticmethod
+    def build_parser() -> argparse.ArgumentParser:
+        p = argparse.ArgumentParser(prog="vllmstat", description="nvtop for vLLM")
+        p.add_argument("-u", "--url", default="http://localhost:8000")
+        p.add_argument("--metrics-path", default="/metrics")
+        p.add_argument("-i", "--interval", type=float, default=1.0)
+        p.add_argument("--api-key", default=None)
+        p.add_argument("--no-gpu", dest="gpu", action="store_false", default=True)
+        p.add_argument("--mock", action="store_true", default=False)
+        p.add_argument("--once", action="store_true", default=False)
+        p.add_argument("--json", action="store_true", default=False)
+        p.add_argument("--version", action="version", version=f"vllmstat {__version__}")
+        return p
+
+    @classmethod
+    def from_sources(cls, argv: list[str], env: dict[str, str]) -> Config:
+        ns = cls.build_parser().parse_args(argv)
+        api_key = ns.api_key or env.get("VLLM_API_KEY")
+        return cls(
+            url=ns.url,
+            metrics_path=ns.metrics_path,
+            interval=ns.interval,
+            api_key=api_key,
+            gpu=ns.gpu,
+            mock=ns.mock,
+            once=ns.once,
+            json=ns.json,
+        )

vllmstat/core/histogram.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+
+def histogram_quantile(buckets: list[tuple[float, float]], q: float) -> float | None:
+    """Prometheus-style quantile from cumulative buckets [(le, cum_count), ...] sorted asc."""
+    if not buckets:
+        return None
+    total = buckets[-1][1]
+    if total <= 0:
+        return None
+    target = q * total
+    prev_le = 0.0
+    prev_count = 0.0
+    for le, count in buckets:
+        if count >= target:
+            if le == float("inf"):
+                return prev_le
+            bucket_count = count - prev_count
+            if bucket_count <= 0:
+                return le
+            frac = (target - prev_count) / bucket_count
+            return prev_le + frac * (le - prev_le)
+        prev_le, prev_count = le, count
+    return buckets[-1][0]
+
+
+def windowed_buckets(
+    prev: list[tuple[float, float]], cur: list[tuple[float, float]]
+) -> list[tuple[float, float]]:
+    """Per-`le` delta cur-prev. If any delta is negative (counter reset), return cur."""
+    prev_map = dict(prev)
+    out: list[tuple[float, float]] = []
+    for le, count in cur:
+        delta = count - prev_map.get(le, 0.0)
+        if delta < 0:
+            return cur
+        out.append((le, delta))
+    return out

vllmstat/core/history.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections import deque
+
+
+class Series:
+    def __init__(self, maxlen: int = 120) -> None:
+        self.values: deque[float] = deque(maxlen=maxlen)
+
+    def push(self, v: float) -> None:
+        self.values.append(v)
+
+
+class History:
+    def __init__(self, maxlen: int = 120) -> None:
+        self._maxlen = maxlen
+        self._series: dict[str, Series] = {}
+
+    def series(self, name: str) -> Series:
+        if name not in self._series:
+            self._series[name] = Series(self._maxlen)
+        return self._series[name]
+
+    def push(self, name: str, value: float) -> None:
+        self.series(name).push(value)

vllmstat/core/kv.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_FP16 = {"auto", "fp16", "float16", "bf16", "bfloat16", "half"}
+
+
+def parse_kv_bits(dtype: str | None) -> tuple[int, int] | None:
+    if not dtype:
+        return None
+    d = dtype.lower()
+    if d in _FP16:
+        return (16, 16)
+    if "fp8" in d or "int8" in d or "e4m3" in d or "e5m2" in d:
+        return (8, 8)
+    m = re.search(r"k(\d+)v(\d+)", d)
+    if m:
+        return (int(m.group(1)), int(m.group(2)))
+    return None
+
+
+def nominal_ratio(dtype: str | None) -> float | None:
+    bits = parse_kv_bits(dtype)
+    if not bits:
+        return None
+    bk, bv = bits
+    return (16 + 16) / (bk + bv)
+
+
+def fp16_bytes_per_token(layers: int, kv_heads: int, head_dim: int) -> int:
+    return 2 * layers * kv_heads * head_dim * 2
+
+
+@dataclass
+class KvInfo:
+    dtype: str | None
+    capacity_tokens: int | None
+    used_tokens: int | None
+    ratio: float | None
+    ratio_kind: str  # "achieved" | "nominal" | "none"
+    fp16_equiv_tokens: int | None
+    fp16_full_ctx_gb: float | None
+
+
+def compute_kv(
+    *,
+    cache_dtype: str | None,
+    num_gpu_blocks: int | None,
+    block_size: int | None,
+    kv_usage: float,
+    kv_cache_memory_bytes: int | None,
+    dims: dict[str, int] | None,
+    max_model_len: int | None,
+) -> KvInfo:
+    capacity = None
+    if num_gpu_blocks and block_size:
+        capacity = num_gpu_blocks * block_size
+    used = round(capacity * kv_usage) if capacity is not None else None
+
+    bpt = None
+    if dims and all(k in dims for k in ("layers", "kv_heads", "head_dim")):
+        bpt = fp16_bytes_per_token(dims["layers"], dims["kv_heads"], dims["head_dim"])
+
+    ratio: float | None = None
+    kind = "none"
+    if capacity and bpt and kv_cache_memory_bytes:
+        ratio = (capacity * bpt) / kv_cache_memory_bytes
+        kind = "achieved"
+    else:
+        nominal = nominal_ratio(cache_dtype)
+        if nominal is not None:
+            ratio, kind = nominal, "nominal"
+
+    fp16_equiv = round(capacity / ratio) if (capacity and ratio) else None
+    fp16_full_ctx_gb = (max_model_len * bpt / 1e9) if (max_model_len and bpt) else None
+
+    return KvInfo(
+        dtype=cache_dtype,
+        capacity_tokens=capacity,
+        used_tokens=used,
+        ratio=ratio,
+        ratio_kind=kind,
+        fp16_equiv_tokens=fp16_equiv,
+        fp16_full_ctx_gb=fp16_full_ctx_gb,
+    )

vllmstat/core/metrics.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from vllmstat.core.histogram import histogram_quantile, windowed_buckets
+from vllmstat.core.kv import compute_kv
+from vllmstat.core.parse import (
+    Families,
+    first_value,
+    get_buckets,
+    info_labels,
+    sum_value,
+)
+from vllmstat.core.rates import Rate
+from vllmstat.core.state import Quantiles, Snapshot
+
+_LAT = {
+    "ttft": "vllm:time_to_first_token_seconds",
+    "tpot": "vllm:request_time_per_output_token_seconds",
+    "e2e": "vllm:e2e_request_latency_seconds",
+    "queue": "vllm:request_queue_time_seconds",
+}
+
+
+def _int(s: str | None) -> int | None:
+    try:
+        return int(s) if s not in (None, "None", "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+class MetricsEngine:
+    def __init__(
+        self,
+        *,
+        alpha: float = 0.3,
+        dims: dict[str, int] | None = None,
+        max_model_len: int | None = None,
+    ) -> None:
+        self.dims = dims
+        self.max_model_len = max_model_len
+        self._gen = Rate(alpha)
+        self._prompt = Rate(alpha)
+        self._req = Rate(alpha)
+        self._preempt = Rate(alpha)
+        self._flops = Rate(alpha)
+        self._rbytes = Rate(alpha)
+        self._wbytes = Rate(alpha)
+        self._prev: Families | None = None
+
+    def _quantiles(self, fam: Families, base: str) -> Quantiles:
+        cur = get_buckets(fam, base)
+        if not cur:
+            return Quantiles()
+        buckets = cur
+        if self._prev is not None:
+            prev = get_buckets(self._prev, base)
+            if prev:
+                delta = windowed_buckets(prev, cur)
+                if delta and delta[-1][1] > 0:
+                    buckets = delta
+        return Quantiles(
+            p50=histogram_quantile(buckets, 0.50),
+            p90=histogram_quantile(buckets, 0.90),
+            p99=histogram_quantile(buckets, 0.99),
+        )
+
+    def derive(self, fam: Families, now: float) -> Snapshot:
+        labels = info_labels(fam, "vllm:cache_config_info")
+        model_names = sorted(
+            {lbl.get("model_name", "") for lbl, _ in fam.get("vllm:num_requests_running", [])}
+            - {""}
+        )
+        engines = {lbl.get("engine") for lbl, _ in fam.get("vllm:num_requests_running", [])}
+
+        # throughput rates
+        gen = self._gen.update(sum_value(fam, "vllm:generation_tokens_total") or 0.0, now)
+        prompt = self._prompt.update(sum_value(fam, "vllm:prompt_tokens_total") or 0.0, now)
+        req = self._req.update(sum_value(fam, "vllm:request_success_total") or 0.0, now)
+        preempt = self._preempt.update(sum_value(fam, "vllm:num_preemptions_total") or 0.0, now)
+
+        # tokens/iter mean
+        it_sum = sum_value(fam, "vllm:iteration_tokens_total_sum")
+        it_cnt = sum_value(fam, "vllm:iteration_tokens_total_count")
+        tokens_per_iter = (it_sum / it_cnt) if (it_sum and it_cnt) else None
+
+        # cache reuse
+        q = sum_value(fam, "vllm:prefix_cache_queries_total") or 0.0
+        h = sum_value(fam, "vllm:prefix_cache_hits_total") or 0.0
+        hit_life = (h / q) if q > 0 else None
+        hit_win = None
+        if self._prev is not None:
+            pq = sum_value(self._prev, "vllm:prefix_cache_queries_total") or 0.0
+            ph = sum_value(self._prev, "vllm:prefix_cache_hits_total") or 0.0
+            dq, dh = q - pq, h - ph
+            if dq > 0:
+                hit_win = max(0.0, min(1.0, dh / dq))
+
+        # token sources
+        src = {lbl.get("source"): v for lbl, v in fam.get("vllm:prompt_tokens_by_source_total", [])}
+        src_total = sum(src.values()) or 0.0
+        frac = lambda k: (src.get(k, 0.0) / src_total) if src_total > 0 else None  # noqa: E731
+
+        ext_q = sum_value(fam, "vllm:external_prefix_cache_queries_total") or 0.0
+        external_active = ext_q > 0 or (src.get("external_kv_transfer", 0.0) > 0)
+
+        # kv memory
+        kv_usage = first_value(fam, "vllm:kv_cache_usage_perc") or 0.0
+        kv = compute_kv(
+            cache_dtype=labels.get("cache_dtype"),
+            num_gpu_blocks=_int(labels.get("num_gpu_blocks")),
+            block_size=_int(labels.get("block_size")),
+            kv_usage=kv_usage,
+            kv_cache_memory_bytes=_int(labels.get("kv_cache_memory_bytes")),
+            dims=self.dims,
+            max_model_len=self.max_model_len,
+        )
+
+        # spec decode
+        drafts = sum_value(fam, "vllm:spec_decode_num_drafts_total")
+        draft_tokens = sum_value(fam, "vllm:spec_decode_num_draft_tokens_total")
+        accepted = sum_value(fam, "vllm:spec_decode_num_accepted_tokens_total")
+        spec_active = bool(drafts and draft_tokens)
+        spec_acceptance = (
+            (accepted / draft_tokens)
+            if (spec_active and accepted is not None and draft_tokens is not None)
+            else None
+        )
+        spec_per_draft = (
+            (accepted / drafts) if (spec_active and drafts and accepted is not None) else None
+        )
+
+        # efficiency (conditional)
+        flops = self._flops.update(sum_value(fam, "vllm:estimated_flops_per_gpu_total") or 0.0, now)
+        rbytes = self._rbytes.update(
+            sum_value(fam, "vllm:estimated_read_bytes_per_gpu_total") or 0.0, now
+        )
+        wbytes = self._wbytes.update(
+            sum_value(fam, "vllm:estimated_write_bytes_per_gpu_total") or 0.0, now
+        )
+        eff_active = (flops > 0) or (rbytes + wbytes > 0)
+
+        snap = Snapshot(
+            ts=now,
+            connected=True,
+            model_names=model_names or ([mn] if (mn := labels.get("model_name")) else []),
+            engine_count=len([e for e in engines if e is not None]) or 1,
+            running=sum_value(fam, "vllm:num_requests_running") or 0.0,
+            waiting=sum_value(fam, "vllm:num_requests_waiting") or 0.0,
+            preempt_rate=preempt,
+            gen_tps=gen,
+            prompt_tps=prompt,
+            req_rate=req,
+            tokens_per_iter=tokens_per_iter,
+            prefix_hit_window=hit_win,
+            prefix_hit_lifetime=hit_life,
+            src_compute=frac("local_compute"),
+            src_cache_hit=frac("local_cache_hit"),
+            src_external=frac("external_kv_transfer"),
+            cached_tokens_total=sum_value(fam, "vllm:prompt_tokens_cached_total") or 0.0,
+            recomputed_tokens_total=sum_value(fam, "vllm:prompt_tokens_recomputed_total") or 0.0,
+            external_kv_active=external_active,
+            kv_usage=kv_usage,
+            kv_capacity_tokens=kv.capacity_tokens,
+            kv_used_tokens=kv.used_tokens,
+            kv_dtype=kv.dtype,
+            kv_ratio=kv.ratio,
+            kv_ratio_kind=kv.ratio_kind,
+            kv_fp16_equiv_tokens=kv.fp16_equiv_tokens,
+            kv_fp16_full_ctx_gb=kv.fp16_full_ctx_gb,
+            ttft=self._quantiles(fam, _LAT["ttft"]),
+            tpot=self._quantiles(fam, _LAT["tpot"]),
+            e2e=self._quantiles(fam, _LAT["e2e"]),
+            queue=self._quantiles(fam, _LAT["queue"]),
+            spec_active=spec_active,
+            spec_acceptance=spec_acceptance,
+            spec_accepted_per_draft=spec_per_draft,
+            eff_active=eff_active,
+            gflops=(flops / 1e9) if eff_active else None,
+            gbps=((rbytes + wbytes) / 1e9) if eff_active else None,
+        )
+        self._prev = fam
+        return snap

vllmstat/core/parse.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from prometheus_client.parser import text_string_to_metric_families
+
+Families = dict[str, list[tuple[dict[str, str], float]]]
+
+
+def parse_metrics(text: str) -> Families:
+    """Parse Prometheus exposition text into {sample_name: [(labels, value), ...]}."""
+    families: Families = {}
+    for family in text_string_to_metric_families(text):
+        for sample in family.samples:
+            families.setdefault(sample.name, []).append((dict(sample.labels), sample.value))
+    return families
+
+
+def sum_value(families: Families, name: str) -> float | None:
+    rows = families.get(name)
+    if not rows:
+        return None
+    return sum(v for _, v in rows)
+
+
+def first_value(families: Families, name: str) -> float | None:
+    rows = families.get(name)
+    if not rows:
+        return None
+    return rows[0][1]
+
+
+def info_labels(families: Families, name: str) -> dict[str, str]:
+    rows = families.get(name)
+    return rows[0][0] if rows else {}
+
+
+def get_buckets(families: Families, base: str) -> list[tuple[float, float]]:
+    """Aggregate `<base>_bucket` samples across labels, summing counts per `le`."""
+    rows = families.get(base + "_bucket", [])
+    agg: dict[float, float] = {}
+    for labels, value in rows:
+        le = float(labels["le"])
+        agg[le] = agg.get(le, 0.0) + value
+    return sorted(agg.items())
+
+
+def hist_count(families: Families, base: str) -> float | None:
+    return sum_value(families, base + "_count")
+
+
+def hist_sum(families: Families, base: str) -> float | None:
+    return sum_value(families, base + "_sum")