gpu-container 0.1.0__py3-none-any.whl

gpu_container/__init__.py

@@ -0,0 +1,9 @@
+"""gpu-container — a model-aware inference memory-placement planner for single-GPU rigs.
+
+Phase 1 starts with the profiler (this package's `profiler` module): it emits the
+profile JSON that every downstream component (planner, receipt) reads. Knowledge that
+grounds the measurement methodology lives in the docker-knowledge KB
+(readouts/docker-knowledge), seeded by the feasibility study-swarm.
+"""
+
+__version__ = "0.1.0"

gpu_container/__main__.py

@@ -0,0 +1,60 @@
+"""Unified `gpu-container <command>` entry — the single-binary / npm-launcher dispatcher.
+
+`pip install gpu-container` lays down five console scripts (`gpu-container-profile`, `-plan`,
+`-receipt`, `-concentration`, `-watchdog`). This dispatcher exposes the same five as subcommands of
+one `gpu-container` command, which is what the PyInstaller binary and the npm launcher run:
+
+    gpu-container profile ...
+    gpu-container plan ...
+    gpu-container watchdog run -- <cmd...>
+
+Subcommand modules are imported lazily so a fast path (`--help`) never imports the whole package,
+and so a frozen binary only pulls what the chosen command needs.
+"""
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from . import __version__
+
+_SUB = {
+    "profile": "gpu_container.profiler.cli",
+    "plan": "gpu_container.planner.cli",
+    "receipt": "gpu_container.planner.receipt_cli",
+    "concentration": "gpu_container.planner.concentration_cli",
+    "watchdog": "gpu_container.watchdog",
+}
+
+_USAGE = (
+    "usage: gpu-container <command> [args...]\n\n"
+    "commands:\n"
+    "  profile        profile the rig (+ model) -> profile.json\n"
+    "  plan           plan an MoE placement (llama.cpp --n-cpu-moe) from a profile\n"
+    "  receipt        verify a plan against a real llama-bench run\n"
+    "  concentration  per-expert-cache de-risk gate (routing concentration)\n"
+    "  watchdog       rig-safety control plane (monitor, or `run -- <cmd>`)\n\n"
+    "run `gpu-container <command> --help` for per-command help.\n"
+    "(each command is also installed standalone as `gpu-container-<command>`.)"
+)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print(_USAGE)
+        return 0
+    if argv[0] in ("-V", "--version"):
+        print(__version__)   # static — works in a frozen binary (no importlib.metadata lookup)
+        return 0
+    cmd, rest = argv[0], argv[1:]
+    mod = _SUB.get(cmd)
+    if mod is None:
+        print(f"gpu-container: unknown command '{cmd}'\n\n{_USAGE}", file=sys.stderr)
+        return 2
+    import importlib
+    return importlib.import_module(mod).main(rest)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gpu_container/errors.py

@@ -0,0 +1,72 @@
+"""Structured errors + a CLI guard — the shipcheck B1/B3 contract.
+
+Every user-facing failure carries a stable `{code, message, hint, cause?, retryable?}` shape
+(`GpuContainerError`) and renders as a few clean lines — never a raw traceback. `guard()` wraps a
+CLI's body so an *unexpected* exception also becomes one clean line + exit 2; the full traceback
+appears only with `--debug`.
+
+Error `code`s are namespaced and stable once released (treat like API). Prefixes:
+  INPUT_  bad user input / validation      IO_      filesystem / paths
+  DEP_    a missing optional dependency     RUNTIME_ unexpected failure
+  STATE_  corrupt / stale internal state
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+
+@dataclass
+class GpuContainerError(Exception):
+    """A user-facing error with a structured, stable shape. Raise it from a CLI body; `guard`
+    renders it and returns `exit_code` (default 2 — distinct from the planners' verdict codes)."""
+    code: str
+    message: str
+    hint: Optional[str] = None
+    cause: Optional[str] = None
+    retryable: bool = False
+    exit_code: int = 2
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+    def to_dict(self) -> dict:
+        return {"code": self.code, "message": self.message, "hint": self.hint,
+                "cause": self.cause, "retryable": self.retryable}
+
+    def render(self) -> str:
+        lines = [f"ERROR [{self.code}]: {self.message}"]
+        if self.hint:
+            lines.append(f"  hint: {self.hint}")
+        if self.cause:
+            lines.append(f"  cause: {self.cause}")
+        if self.retryable:
+            lines.append("  retryable: yes")
+        return "\n".join(lines)
+
+
+def guard(run: Callable[[Optional[List[str]]], int], argv: Optional[List[str]] = None) -> int:
+    """Run a CLI body, turning failures into clean structured output and never leaking a raw
+    traceback unless `--debug` is present.
+
+    - `GpuContainerError` -> render it, return its `exit_code` (an expected error; no trace).
+    - any other Exception  -> with `--debug`, re-raise (show the trace); else one clean line + exit 2.
+    Normal returns (the verdict codes 0/3/4/5/7) pass straight through. argparse's own usage exits
+    (SystemExit) are not caught — they keep argparse's message + exit 2.
+    """
+    debug = "--debug" in (argv if argv is not None else sys.argv[1:])
+    try:
+        return run(argv)
+    except GpuContainerError as e:
+        print(e.render(), file=sys.stderr)
+        return e.exit_code
+    except KeyboardInterrupt:
+        print("ERROR [RUNTIME_INTERRUPTED]: interrupted by user", file=sys.stderr)
+        return 130
+    except Exception as e:  # noqa: BLE001 — deliberate: no raw stack without --debug (gate B3)
+        if debug:
+            raise
+        print(f"ERROR [RUNTIME_UNEXPECTED]: {type(e).__name__}: {e}\n"
+              "  hint: re-run with --debug for the full traceback", file=sys.stderr)
+        return 2

gpu_container/planner/__init__.py

@@ -0,0 +1,17 @@
+"""The placement planner: a profile + model -> an explicit tiered placement plan for a runtime.
+
+Phase-1 target: llama.cpp `--n-cpu-moe N` (the first N MoE layers' expert weights live in CPU
+RAM and are computed on CPU; attention/router/shared/embeddings/head stay on the GPU — the
+KTransformers-style "compute where the weights are", NOT per-token PCIe streaming; verified in
+tensor-engine-knowledge). The planner finds the minimal N that fits VRAM, predicts the memory
+map + decode throughput, and REFUSES below the >1 tok/s floor with a contrastive frame.
+"""
+from .calibration import (  # noqa: F401
+    CalibrationModel,
+    CalibrationPoint,
+    CalibrationStore,
+    EfficiencyEstimate,
+    load_seed_points,
+)
+from .placement import DEFAULT_CPU_BW_GBPS, DEFAULT_VRAM_BW_GBPS, plan_llama_cpp  # noqa: F401
+from .receipt import build_receipt, parse_llama_bench, plan_to_calibration_point  # noqa: F401

gpu_container/planner/activation.py

@@ -0,0 +1,225 @@
+"""Activation-trace concentration analysis — does per-expert caching even help?
+
+The throughput half ([`calibration.py`]) turns receipts into a tok/s forecast. THIS module answers a
+PRIOR, go/no-go question for the per-expert lane: given a captured activation trace (which experts
+fired, per layer, over a representative workload), is the routing CONCENTRATED enough that a small
+hot-expert VRAM cache would hit often — or is it so uniform that the cache (llama.cpp #20757) isn't
+worth building?
+
+It is the de-risk gate for ADR-0001 (`docs/decisions/0001-per-expert-cache-build-vs-upstream.md`):
+build the runtime expert cache only where the trace shows a small fraction of experts captures most
+of the routing.
+
+Grounded in docker-knowledge wave-4 (moe-placement):
+  - Per-LAYER *total* activation is ~uniform — every token hits every layer's top-k experts — so the
+    signal is PER-EXPERT concentration WITHIN a layer, not which layer. Only the runtime cache can
+    exploit per-expert skew; `-ot` is per-layer (llamacpp-experts-fused-per-layer-not-per-expert).
+  - Skew is request-level and flattens to uniform across diverse prompts (MoE-Infinity,
+    arXiv:2401.14361) — so concentration is WORKLOAD-DEPENDENT: a trace is only valid for the
+    workload it was cut from. The report says so; a diverse-prompt trace reads LESS concentrated.
+  - The trace is an L×E count matrix captured via an eval-callback (activation-trace-via-eval-callback);
+    THIS module only CONSUMES it. None-not-guess: no trace -> no verdict (the planner stays per-layer).
+
+Two measures, deliberately:
+  - `hot_frac_for_coverage` — the fraction of a layer's experts that must be resident to capture
+    `coverage_target` (default 90%) of its routing. The ACTIONABLE number; maps straight to #20757
+    `--moe-expert-cache-size`.
+  - `concentration_score = 1 - normalized_entropy` — a threshold-free [0,1] skew measure
+    (0 = uniform, 1 = one expert), robust to the arbitrary coverage target.
+
+`cache_helps` is a convenience gate on the numbers, never a substitute for them.
+"""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import asdict, dataclass, field
+from statistics import median
+from typing import List, Optional
+
+DEFAULT_COVERAGE_TARGET = 0.90
+# If fewer than this fraction of a layer's experts cover `coverage_target` of its routing, a hot-expert
+# cache buys real VRAM back — so a cache "helps". Tunable; the numbers are reported regardless.
+DEFAULT_CACHE_HELPS_THRESHOLD = 0.50
+
+
+@dataclass
+class LayerActivation:
+    """One MoE layer's routing counts: expert_counts[i] = tokens routed to expert i in this layer."""
+    layer_index: int
+    expert_counts: List[int] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return sum(self.expert_counts)
+
+
+@dataclass
+class ActivationTrace:
+    """An L×E activation trace captured over a representative workload (the eval-callback's output).
+
+    Persists only measured facts; concentration is DERIVED by `analyze_concentration` so the verdict
+    is always re-derivable from the counts, never a number we can silently get wrong.
+    """
+    model: str
+    num_experts: int                 # E (routed experts per MoE layer)
+    experts_per_token: int           # top-k (sanity: each layer total ~= n_tokens * k)
+    n_tokens: int                    # decode tokens the trace covers
+    layers: List[LayerActivation] = field(default_factory=list)
+    gate_weighted: bool = False      # counts are gate-mass-weighted (else raw selection counts)
+    created: Optional[str] = None    # ISO date (passed in; the capture harness has no clock)
+    rig: Optional[str] = None
+    source: Optional[str] = None     # provenance (which workload / run produced it)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ActivationTrace":
+        known = set(cls.__dataclass_fields__)  # type: ignore[attr-defined]
+        kw = {k: v for k, v in d.items() if k in known}
+        kw["layers"] = [
+            LayerActivation(layer_index=l.get("layer_index"),
+                            expert_counts=[int(c) for c in (l.get("expert_counts") or [])])
+            for l in (d.get("layers") or []) if isinstance(l, dict)
+        ]
+        return cls(**kw)
+
+    @classmethod
+    def from_json(cls, s: str) -> "ActivationTrace":
+        return cls.from_dict(json.loads(s))
+
+
+@dataclass
+class LayerConcentration:
+    layer_index: int
+    total_mass: int                  # sanity: ~= n_tokens * top_k (per-layer totals are ~uniform)
+    top1_share: float                # routing share of the single hottest expert
+    hot_frac_for_coverage: float     # fraction of experts needed to reach coverage_target
+    concentration_score: float       # 1 - normalized entropy (0 = uniform, 1 = fully concentrated)
+
+
+@dataclass
+class ConcentrationReport:
+    """The de-risk verdict: would a per-expert cache help, and by how much, for THIS workload."""
+    model: str
+    num_experts: int
+    n_layers: int                    # layers with routing mass that were analyzed
+    n_tokens: int
+    coverage_target: float
+    threshold: float
+    cache_helps: bool
+    hot_frac_for_coverage: float     # median over layers — the headline cache-size number
+    concentration_score: float       # mean over layers
+    top1_share: float                # median over layers
+    per_layer: List[LayerConcentration] = field(default_factory=list)
+    basis: str = ""
+    notes: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+
+def _normalized_entropy(counts: List[int]) -> float:
+    """Shannon entropy of the routing distribution, normalized to [0,1] by log(E).
+
+    1.0 = perfectly uniform (every expert equally used); 0.0 = all mass on one expert. Caller
+    guarantees total > 0. A single expert (or a single active expert) is fully concentrated (0.0)."""
+    total = sum(counts)
+    nz = [c for c in counts if c > 0]
+    E = len(counts)
+    if E <= 1 or len(nz) <= 1:
+        return 0.0
+    H = -sum((c / total) * math.log(c / total) for c in nz)
+    return H / math.log(E)
+
+
+def _hot_frac_for_coverage(counts: List[int], target: float) -> float:
+    """Fraction of experts (resident, hottest-first) needed to capture `target` of routing mass.
+
+    Low = concentrated (a small cache covers most routing); ~target = uniform (no cache win)."""
+    total = sum(counts)
+    E = len(counts)
+    if total <= 0 or E <= 0:
+        return 1.0
+    need = target * total
+    cum = 0
+    for i, c in enumerate(sorted(counts, reverse=True), start=1):
+        cum += c
+        if cum >= need:
+            return i / E
+    return 1.0
+
+
+def analyze_layer(layer: LayerActivation, coverage_target: float) -> Optional[LayerConcentration]:
+    """Per-layer concentration, or None for a zero-mass layer (skipped, never guessed)."""
+    counts = layer.expert_counts
+    total = sum(counts)
+    if total <= 0 or not counts:
+        return None
+    return LayerConcentration(
+        layer_index=layer.layer_index,
+        total_mass=total,
+        top1_share=max(counts) / total,
+        hot_frac_for_coverage=_hot_frac_for_coverage(counts, coverage_target),
+        concentration_score=1.0 - _normalized_entropy(counts),
+    )
+
+
+def analyze_concentration(
+    trace: ActivationTrace,
+    coverage_target: float = DEFAULT_COVERAGE_TARGET,
+    cache_helps_threshold: float = DEFAULT_CACHE_HELPS_THRESHOLD,
+) -> ConcentrationReport:
+    """Aggregate a trace into the per-expert-cache de-risk verdict. Never raises; honest on empty data."""
+    per_layer = [c for c in (analyze_layer(l, coverage_target) for l in trace.layers) if c is not None]
+    notes: List[str] = []
+
+    if not per_layer:
+        return ConcentrationReport(
+            model=trace.model, num_experts=trace.num_experts, n_layers=0, n_tokens=trace.n_tokens,
+            coverage_target=coverage_target, threshold=cache_helps_threshold,
+            cache_helps=False, hot_frac_for_coverage=1.0, concentration_score=0.0, top1_share=0.0,
+            per_layer=[], basis="no layers with routing mass — cannot assess (treated as 'cache not justified')",
+            notes=["empty or zero-mass trace — capture a real workload trace before deciding"],
+        )
+
+    hot = float(median(c.hot_frac_for_coverage for c in per_layer))
+    conc = sum(c.concentration_score for c in per_layer) / len(per_layer)
+    top1 = float(median(c.top1_share for c in per_layer))
+    cache_helps = hot < cache_helps_threshold
+
+    # Sanity: per-layer totals should be ~uniform (every token hits every layer's top-k). A large
+    # spread hints at a malformed trace, a wrong experts_per_token/n_tokens, or unequal expert counts.
+    masses = [c.total_mass for c in per_layer]
+    if max(masses) and (max(masses) - min(masses)) / max(masses) > 0.2:
+        notes.append("per-layer totals vary >20% — check experts_per_token/n_tokens, or layers may "
+                     "carry differing expert counts")
+    notes.append("concentration is WORKLOAD-DEPENDENT: request-level skew flattens across diverse "
+                 "prompts (MoE-Infinity); this verdict is valid only for the workload this trace covers")
+
+    basis = (f"{len(per_layer)} layers; hot_frac = median experts for {coverage_target:.0%} routing "
+             f"coverage; concentration = 1 - normalized_entropy (mean); "
+             f"cache_helps = hot_frac < {cache_helps_threshold:.0%}")
+
+    return ConcentrationReport(
+        model=trace.model, num_experts=trace.num_experts, n_layers=len(per_layer),
+        n_tokens=trace.n_tokens, coverage_target=coverage_target, threshold=cache_helps_threshold,
+        cache_helps=cache_helps, hot_frac_for_coverage=hot, concentration_score=conc,
+        top1_share=top1, per_layer=per_layer, basis=basis, notes=notes,
+    )
+
+
+def load_trace(path) -> Optional[ActivationTrace]:
+    """Load a trace JSON (the capture harness's output). Returns None on any error — never raises."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return ActivationTrace.from_dict(json.load(f))
+    except (OSError, ValueError, TypeError):
+        return None

gpu_container/planner/calibration.py

@@ -0,0 +1,224 @@
+"""Receipt-driven recalibration — turn measured receipts into a calibrated forecast.
+
+The planner emits a roofline CEILING (peak bandwidth, zero overhead): a true upper bound on
+decode tok/s, but real decode runs at a fraction of it (Qwen3-30B-A3B realized 41% in-VRAM,
+56-61% offloaded — milestone 2-3 live receipt). This module closes that static-prediction gap:
+
+    receipt  ->  CalibrationPoint (realized efficiency at a known shape)
+              ->  CalibrationStore (a JSON dir; append-only, auditable)
+              ->  CalibrationModel (efficiency = f(regime, offload-fraction), with a band)
+              ->  planner emits  ceiling x efficiency  +/- band   (the calibrated forecast)
+
+Two regimes, because they are bound by different things (placement.py `basis`):
+  - `in_vram`  (N = 0): overhead-bound — small-active MoE spends most of its time NOT moving
+    bytes, so realized efficiency is low (~41%) and roughly flat.
+  - `offload`  (N > 0): CPU-RAM-bandwidth-bound — the roofline fits better (~56-61%) and tracks
+    the offload fraction N / n_moe_layers.
+
+Sparse-data-honest by construction: we bucket by regime and interpolate within `offload` only
+when there are >= 2 distinct offload fractions; otherwise we report the regime's central
+efficiency. The band never narrows below +/-`default_margin` (we cannot claim more confidence
+than the data supports), and it always contains every observed point in the regime. With NO
+points for a regime, `estimate()` returns None and the planner falls back to the raw ceiling --
+the honest "uncalibrated" path. This mirrors the feasibility verdict's calibration #2: the
++/-10% receipt is scoped to the regimes we have measured; everywhere else is ceiling + band.
+
+The model never grades its own forecast: the points come from llama-bench (a real GPU run, a
+DIFFERENT mechanism than the planner's closed form) -- the EXTERNAL_VERIFIER discipline.
+"""
+from __future__ import annotations
+
+import json
+import os
+from collections import defaultdict
+from dataclasses import asdict, dataclass
+from statistics import median
+from typing import Iterable, List, Optional
+
+# Bundled seed: the measured Qwen3-30B-A3B receipts that ship with the package so a known shape
+# is calibrated out-of-the-box. Lives next to this module.
+_SEED_PATH = os.path.join(os.path.dirname(__file__), "calibration_seed.json")
+
+DEFAULT_MARGIN = 0.25  # +/-25% efficiency band (feasibility #11: heavy offload can miss 2-3x; this
+                       # is the *calibrated* band, far tighter than that worst case, but never tighter
+                       # than the data supports)
+
+
+@dataclass
+class CalibrationPoint:
+    """One receipt's realized efficiency, tagged with the shape it was measured at.
+
+    `efficiency`, `regime`, and `offload_fraction` are DERIVED (properties) -- we persist only the
+    measured facts (ceiling, measured tok/s, the N/L shape, the bandwidth assumptions) so a point is
+    auditable and re-derivable, never a number we can silently get wrong.
+    """
+    model: str
+    n_cpu_moe: int
+    n_moe_layers: int
+    ceiling_tok_s: float
+    measured_tok_s: float
+    quant: Optional[str] = None
+    cpu_bw_gbps: Optional[float] = None
+    vram_bw_gbps: Optional[float] = None
+    ctx_len: Optional[int] = None
+    created: Optional[str] = None        # ISO date (passed in; runners have no clock)
+    rig: Optional[str] = None
+    source: Optional[str] = None         # provenance (which run / receipt)
+
+    @property
+    def regime(self) -> str:
+        return "in_vram" if self.n_cpu_moe == 0 else "offload"
+
+    @property
+    def offload_fraction(self) -> float:
+        return (self.n_cpu_moe / self.n_moe_layers) if self.n_moe_layers else 0.0
+
+    @property
+    def efficiency(self) -> Optional[float]:
+        if not self.ceiling_tok_s:
+            return None
+        return self.measured_tok_s / self.ceiling_tok_s
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CalibrationPoint":
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+@dataclass
+class EfficiencyEstimate:
+    """A calibrated efficiency (measured / ceiling) for a shape, with an honest band."""
+    efficiency: float        # central estimate
+    low: float               # band low (efficiency units)
+    high: float              # band high (efficiency units, capped at 1.0 -- can't beat the ceiling)
+    n_samples: int
+    regime: str
+    basis: str               # human-readable provenance of the estimate
+
+
+class CalibrationStore:
+    """Append-only JSON-directory persistence for calibration points.
+
+    A point is one `.json` file (so concurrent writers never clobber each other); a file may also
+    hold a LIST of points (the bundled seed is one such file). Reading tolerates both shapes and
+    skips anything malformed -- a corrupt point degrades the calibration, it never crashes a plan.
+    """
+
+    def __init__(self, path: str):
+        self.path = path
+
+    def add(self, point: CalibrationPoint, filename: Optional[str] = None) -> str:
+        os.makedirs(self.path, exist_ok=True)
+        if filename is None:
+            # Stable, collision-resistant name from the shape + provenance (no clock dependency).
+            stamp = (point.created or "nodate").replace(":", "-")
+            safe_model = "".join(c if c.isalnum() else "-" for c in point.model)[:40]
+            filename = f"{stamp}_{safe_model}_n{point.n_cpu_moe}.json"
+        dest = os.path.join(self.path, filename)
+        with open(dest, "w", encoding="utf-8") as f:
+            json.dump(point.to_dict(), f, indent=2, ensure_ascii=False)
+        return dest
+
+    def points(self) -> List[CalibrationPoint]:
+        out: List[CalibrationPoint] = []
+        if not os.path.isdir(self.path):
+            return out
+        for name in sorted(os.listdir(self.path)):
+            if not name.endswith(".json"):
+                continue
+            out.extend(_load_points_file(os.path.join(self.path, name)))
+        return out
+
+
+def _load_points_file(path: str) -> List[CalibrationPoint]:
+    """Load a JSON file holding either one point (dict) or many (list). Never raises on bad data."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return []
+    records = data if isinstance(data, list) else [data]
+    out: List[CalibrationPoint] = []
+    for rec in records:
+        if isinstance(rec, dict):
+            try:
+                out.append(CalibrationPoint.from_dict(rec))
+            except (TypeError, ValueError):
+                continue
+    return out
+
+
+def load_seed_points() -> List[CalibrationPoint]:
+    """The measured receipts bundled with the package (Qwen3-30B-A3B, milestone 2-3)."""
+    return _load_points_file(_SEED_PATH)
+
+
+class CalibrationModel:
+    """Fits realized efficiency from calibration points, bucketed by regime.
+
+    `estimate(regime, offload_fraction)` returns an `EfficiencyEstimate` or None (no data for that
+    regime -> the planner falls back to the ceiling). Within `offload`, it interpolates piecewise-
+    linearly over the offload fraction when >= 2 distinct fractions are known; otherwise it uses the
+    regime's median efficiency. The band is +/-`margin`, widened so it always contains every observed
+    point in the regime, and capped at efficiency 1.0.
+    """
+
+    def __init__(self, points: Iterable[CalibrationPoint], margin: float = DEFAULT_MARGIN):
+        self.points = [p for p in points if p.efficiency is not None]
+        self.margin = margin
+
+    @classmethod
+    def from_seed(cls, extra: Optional[Iterable[CalibrationPoint]] = None,
+                  margin: float = DEFAULT_MARGIN) -> "CalibrationModel":
+        pts = list(load_seed_points())
+        if extra:
+            pts.extend(extra)
+        return cls(pts, margin=margin)
+
+    def has_data(self) -> bool:
+        return bool(self.points)
+
+    def estimate(self, regime: str, offload_fraction: float = 0.0) -> Optional[EfficiencyEstimate]:
+        pts = [p for p in self.points if p.regime == regime]
+        if not pts:
+            return None
+        effs = [p.efficiency for p in pts]  # type: ignore[misc]  (filtered to non-None in __init__)
+
+        # group efficiencies by offload fraction (average repeated runs at the same fraction)
+        by_frac = defaultdict(list)
+        for p in pts:
+            by_frac[round(p.offload_fraction, 4)].append(p.efficiency)
+        curve = sorted((f, sum(v) / len(v)) for f, v in by_frac.items())
+
+        if regime == "offload" and len(curve) >= 2:
+            central = _interp(curve, offload_fraction)
+            basis = (f"calibrated: piecewise-linear over {len(curve)} offload fractions "
+                     f"({len(pts)} receipt(s)) at frac={offload_fraction:.2f}")
+        else:
+            central = float(median(effs))
+            basis = f"calibrated: median of {len(pts)} '{regime}' receipt(s)"
+
+        # band: never tighter than +/-margin, always contains every observed point in the regime
+        spread = max((abs(e - central) / central for e in effs), default=0.0) if central else 0.0
+        rel = max(self.margin, spread)
+        low = max(central * (1.0 - rel), 1e-4)
+        high = min(central * (1.0 + rel), 1.0)
+        return EfficiencyEstimate(efficiency=central, low=low, high=high,
+                                  n_samples=len(pts), regime=regime, basis=basis)
+
+
+def _interp(curve: List[tuple], x: float) -> float:
+    """Piecewise-linear interpolation over a sorted [(x, y), ...] curve, clamped at both ends
+    (NO extrapolation -- beyond the measured fractions we hold the nearest observed efficiency)."""
+    if x <= curve[0][0]:
+        return curve[0][1]
+    if x >= curve[-1][0]:
+        return curve[-1][1]
+    for (x0, y0), (x1, y1) in zip(curve, curve[1:]):
+        if x0 <= x <= x1:
+            t = (x - x0) / (x1 - x0) if x1 > x0 else 0.0
+            return y0 + t * (y1 - y0)
+    return curve[-1][1]

gpu_container/planner/calibration_seed.json

@@ -0,0 +1,44 @@
+[
+  {
+    "model": "Qwen3-30B-A3B",
+    "n_cpu_moe": 0,
+    "n_moe_layers": 48,
+    "ceiling_tok_s": 737.56,
+    "measured_tok_s": 302.4,
+    "quant": "gguf-q4_k_m",
+    "cpu_bw_gbps": 40.7,
+    "vram_bw_gbps": 1790.0,
+    "ctx_len": 4096,
+    "created": "2026-06-04",
+    "rig": "RTX 5090 (sm_120) WSL2 Docker, driver 610.47, CUDA 12.8",
+    "source": "milestone 2-3 live receipt: Qwen3-30B-A3B Q4_K_M, llama-bench -p 512 -n 128"
+  },
+  {
+    "model": "Qwen3-30B-A3B",
+    "n_cpu_moe": 24,
+    "n_moe_layers": 48,
+    "ceiling_tok_s": 69.02,
+    "measured_tok_s": 41.9,
+    "quant": "gguf-q4_k_m",
+    "cpu_bw_gbps": 40.7,
+    "vram_bw_gbps": 1790.0,
+    "ctx_len": 4096,
+    "created": "2026-06-04",
+    "rig": "RTX 5090 (sm_120) WSL2 Docker, driver 610.47, CUDA 12.8",
+    "source": "milestone 2-3 live receipt: Qwen3-30B-A3B Q4_K_M, llama-bench -p 512 -n 128"
+  },
+  {
+    "model": "Qwen3-30B-A3B",
+    "n_cpu_moe": 48,
+    "n_moe_layers": 48,
+    "ceiling_tok_s": 36.2,
+    "measured_tok_s": 20.4,
+    "quant": "gguf-q4_k_m",
+    "cpu_bw_gbps": 40.7,
+    "vram_bw_gbps": 1790.0,
+    "ctx_len": 4096,
+    "created": "2026-06-04",
+    "rig": "RTX 5090 (sm_120) WSL2 Docker, driver 610.47, CUDA 12.8",
+    "source": "milestone 2-3 live receipt: Qwen3-30B-A3B Q4_K_M, llama-bench -p 512 -n 128"
+  }
+]