gpu-container 0.1.0__py3-none-any.whl

gpu_container/planner/cli.py

@@ -0,0 +1,101 @@
+"""`gpu-container-plan` — turn a profile (+ model) into a llama.cpp `--n-cpu-moe` placement plan.
+
+  gpu-container-plan --profile profile.json --model-config qwen3.json --quant gguf-q4_k_m --ctx 4096
+
+Exit code is verdict-coded (ANDON): 0 = ship, 3 = refuse. The profile.json comes from
+`gpu-container-profile` (run in-container for honest VRAM/CPU-bandwidth inputs).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from ..errors import GpuContainerError, guard
+from ..profiler import model as model_mod
+from ..profiler.schema import Profile
+from .calibration import CalibrationModel, CalibrationStore
+from .placement import plan_llama_cpp
+
+
+def _main(argv: Optional[List[str]] = None) -> int:
+    for _stream in (sys.stdout, sys.stderr):
+        try:
+            _stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+
+    ap = argparse.ArgumentParser(
+        prog="gpu-container-plan",
+        description="Plan an MoE placement (llama.cpp --n-cpu-moe) from a rig+model profile.",
+    )
+    ap.add_argument("--debug", action="store_true", help="show the full traceback on an unexpected error")
+    ap.add_argument("--profile", required=True, help="profile.json from gpu-container-profile")
+    ap.add_argument("--model-config", help="HF config.json to (re)profile the model side into the plan")
+    ap.add_argument("--model-name", help="override the model name")
+    ap.add_argument("--quant", help="quant tag, e.g. gguf-q4_k_m (drives bytes/weight + footprint)")
+    ap.add_argument("--ctx", type=int, default=4096, help="context length for the KV-cache budget")
+    ap.add_argument("--batch", type=int, default=1)
+    ap.add_argument("--cpu-bw", type=float, help="override CPU RAM bandwidth (GB/s)")
+    ap.add_argument("--non-expert-bpw", type=float,
+                    help="bytes/weight for always-resident weights (auto: f16 for mxfp4, else the quant bpw)")
+    ap.add_argument("--floor", type=float, default=1.0, help="refuse below this decode tok/s")
+    ap.add_argument("--hf", help="model ref for the launch command, e.g. unsloth/Qwen3-30B-A3B-GGUF:Q4_K_M")
+    ap.add_argument("--calibration-dir", help="extra calibration receipts to fold in (atop the bundled seed)")
+    ap.add_argument("--no-calibration", action="store_true",
+                    help="forecast the raw roofline ceiling only (skip the calibrated band)")
+    ap.add_argument("-o", "--out", help="write the plan JSON here (default: stdout)")
+    args = ap.parse_args(argv)
+
+    try:
+        with open(args.profile, "r", encoding="utf-8") as f:
+            prof = Profile.from_json(f.read())
+    except FileNotFoundError:
+        raise GpuContainerError("IO_PROFILE_NOT_FOUND", f"profile not found: {args.profile}",
+                                hint="run `gpu-container-profile -o profile.json` first (in-container)")
+    except (ValueError, OSError) as e:
+        raise GpuContainerError("INPUT_BAD_PROFILE", f"could not read {args.profile}",
+                                hint="expected a profile.json from gpu-container-profile", cause=str(e))
+
+    if args.model_config:
+        try:
+            with open(args.model_config, "r", encoding="utf-8") as f:
+                cfg = json.load(f)
+        except (OSError, ValueError) as e:
+            raise GpuContainerError("INPUT_BAD_MODEL_CONFIG", f"could not read {args.model_config}",
+                                    hint="expected a HuggingFace config.json", cause=str(e))
+        prof.model = model_mod.analyze_config(cfg, name=args.model_name, quant=args.quant or "gguf-q4_k_m")
+    elif args.quant and prof.model is not None:
+        prof.model.quant = args.quant
+
+    # Calibration: bundled seed + any extra receipts, unless disabled. With no data for the shape's
+    # regime the planner falls back to the raw ceiling on its own.
+    calibration = None
+    if not args.no_calibration:
+        extra = CalibrationStore(args.calibration_dir).points() if args.calibration_dir else None
+        calibration = CalibrationModel.from_seed(extra=extra)
+
+    plan = plan_llama_cpp(
+        prof, ctx_len=args.ctx, batch=args.batch,
+        cpu_mem_bw_gbps=args.cpu_bw, non_expert_bpw=args.non_expert_bpw,
+        floor_tok_s=args.floor, model_ref=args.hf, calibration=calibration,
+    )
+
+    js = plan.to_json()
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(js + "\n")
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        print(js)
+    print(plan.message, file=sys.stderr)
+    return 0 if plan.verdict == "ship" else 3
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    return guard(_main, argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gpu_container/planner/concentration_cli.py

@@ -0,0 +1,120 @@
+"""`gpu-container-concentration` — the per-expert-cache de-risk gate, as a command.
+
+Given an activation trace (which experts fired, per layer), score routing CONCENTRATION and answer
+the prior question for the per-expert lane: would a hot-expert VRAM cache (the llama.cpp #20757 lane)
+actually help, or is routing too uniform to bother? Backs ADR-0001; logic in `activation.py`.
+
+  gpu-container-concentration --trace trace.json
+  gpu-container-concentration --imatrix imatrix.gguf --model-name Qwen3-30B-A3B   # needs the `gguf` pkg
+
+`--imatrix` reads a `llama-imatrix` output directly (per-layer `ffn_down_exps.weight.counts`); the
+`gguf` package is an OPTIONAL dependency — only that path needs it. `--trace` keeps the core dep-free.
+
+Exit code (ANDON-style, scriptable):
+  0 = analyzed; a per-expert cache is NOT justified (routing too uniform — the common 'hold' outcome)
+  5 = analyzed; routing concentrates enough that a cache could help (worth weighing #20757)
+  2 = usage / input error
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from ..errors import GpuContainerError, guard
+from .activation import ActivationTrace, analyze_concentration, load_trace
+
+
+def _trace_from_imatrix(path: str, model_name: str, topk: int) -> ActivationTrace:
+    """Build an ActivationTrace from a llama-imatrix `imatrix.gguf` (per-expert `.counts`).
+
+    Raises ValueError on a missing `gguf` package or a non-MoE / unexpected imatrix (the caller maps
+    that to exit 2)."""
+    try:
+        import gguf  # optional dependency — only the --imatrix path needs it
+    except ImportError:
+        raise ValueError("--imatrix needs the 'gguf' package (pip install gguf); "
+                         "or extract a trace.json yourself and pass --trace.")
+    reader = gguf.GGUFReader(path)
+    counts = {}
+    for t in reader.tensors:
+        nm = t.name.strip()
+        if nm.endswith("ffn_down_exps.weight.counts") and nm.startswith("blk."):
+            layer = int(nm.split(".")[1])
+            counts[layer] = [int(round(float(x))) for x in list(t.data.flatten())]
+    if not counts:
+        raise ValueError("no per-expert counts (ffn_down_exps.weight.counts) in this imatrix — "
+                         "is it a llama-imatrix .gguf for an MoE model?")
+    E = len(next(iter(counts.values())))
+    layers = [{"layer_index": L, "expert_counts": counts[L]} for L in sorted(counts)]
+    n_tokens = (sum(layers[0]["expert_counts"]) // topk) if topk else 0
+    return ActivationTrace.from_dict({
+        "model": model_name, "num_experts": E, "experts_per_token": topk,
+        "n_tokens": n_tokens, "layers": layers, "source": f"llama-imatrix per-expert counts: {path}",
+    })
+
+
+def _main(argv: Optional[List[str]] = None) -> int:
+    for _stream in (sys.stdout, sys.stderr):
+        try:
+            _stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+
+    ap = argparse.ArgumentParser(
+        prog="gpu-container-concentration",
+        description="Per-expert-cache de-risk gate: does this model's routing concentrate enough to cache?",
+    )
+    ap.add_argument("--debug", action="store_true", help="show the full traceback on an unexpected error")
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--trace", help="ActivationTrace JSON (L×E per-expert counts)")
+    src.add_argument("--imatrix", help="llama-imatrix imatrix.gguf (extract per-expert counts; needs `gguf`)")
+    ap.add_argument("--model-name", default="model", help="model name (for the --imatrix path / the report)")
+    ap.add_argument("--topk", type=int, default=8, help="experts/token, for the --imatrix n_tokens estimate")
+    ap.add_argument("--coverage", type=float, default=0.90, help="routing-mass coverage target (default 0.90)")
+    ap.add_argument("--threshold", type=float, default=0.50,
+                    help="cache_helps if < this fraction of experts cover the target (default 0.50)")
+    ap.add_argument("-o", "--out", help="write the report JSON here (default: stdout)")
+    args = ap.parse_args(argv)
+
+    if args.imatrix:
+        try:
+            trace = _trace_from_imatrix(args.imatrix, args.model_name, args.topk)
+        except (ValueError, OSError) as e:
+            raise GpuContainerError("INPUT_BAD_IMATRIX", str(e),
+                                    hint="pass --trace with an L×E counts JSON instead, "
+                                         "or `pip install gguf` for the --imatrix path")
+    else:
+        trace = load_trace(args.trace)
+        if trace is None:
+            raise GpuContainerError("IO_TRACE_UNREADABLE", f"could not load a trace from {args.trace}",
+                                    hint="expected an ActivationTrace JSON "
+                                         "(model, num_experts, experts_per_token, layers[])")
+
+    rep = analyze_concentration(trace, coverage_target=args.coverage, cache_helps_threshold=args.threshold)
+
+    js = rep.to_json()
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(js + "\n")
+        print(f"wrote {args.out}", file=sys.stderr)
+    else:
+        print(js)
+
+    need = rep.hot_frac_for_coverage * rep.num_experts
+    verdict = "CACHE COULD HELP" if rep.cache_helps else "cache NOT justified"
+    print(f"{rep.model}: {verdict} — {need:.0f}/{rep.num_experts} experts ({rep.hot_frac_for_coverage:.0%}) "
+          f"resident for {rep.coverage_target:.0%} routing coverage; concentration {rep.concentration_score:.2f}, "
+          f"top expert {rep.top1_share:.1%} ({rep.n_layers} layers, ~{rep.n_tokens} tok).", file=sys.stderr)
+    for n in rep.notes:
+        print(f"  note: {n}", file=sys.stderr)
+
+    return 5 if rep.cache_helps else 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    return guard(_main, argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gpu_container/planner/placement.py

@@ -0,0 +1,198 @@
+"""llama.cpp `--n-cpu-moe` placement planner.
+
+Closed-form, deterministic, reversible (a plan is a file). The math:
+
+  VRAM_used(N) = non_expert_bytes + (per_moe_layer_expert_bytes · (L_moe − N)) + KV_bytes + overhead
+
+`--n-cpu-moe N` moves the first N MoE layers' experts to CPU RAM, so raising N lowers VRAM use
+(more experts off the GPU) and lowers throughput (CPU computes them at RAM bandwidth, far below
+the GPU's). We pick the SMALLEST N that fits — maximal GPU residency, maximal speed — and refuse
+if even N = L_moe (all experts on CPU) cannot fit the always-resident footprint.
+
+Decode is bandwidth-bound at batch 1 (feasibility #10): per token the GPU reads its resident
+weights + active experts at VRAM bandwidth while the CPU reads its N layers' active experts at
+RAM bandwidth. Throughput ≈ 1 / (t_gpu + t_cpu). This is an ESTIMATE for N>0 (heavy-offload
+prediction misses up to ~2-3× — feasibility #11), labelled and confirmed by the receipt; the
+N=0 in-VRAM case is the ±10% regime.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..profiler import model as model_mod
+from ..profiler.schema import PlacementPlan, Profile
+from .calibration import CalibrationModel
+
+_MIB = 1024 * 1024
+_GB = 1e9
+
+# Labelled defaults when the profile hasn't measured them (the planner flags the assumption).
+DEFAULT_CPU_BW_GBPS = 80.0      # DDR5 dual-channel, conservative (measure via the profiler to override)
+DEFAULT_VRAM_BW_GBPS = 1790.0  # RTX 5090 GDDR7 512-bit (~1.79 TB/s)
+
+
+def plan_llama_cpp(
+    profile: Profile,
+    ctx_len: int = 4096,
+    batch: int = 1,
+    cpu_mem_bw_gbps: Optional[float] = None,
+    vram_bw_gbps: Optional[float] = None,
+    non_expert_bpw: Optional[float] = None,
+    overhead_mib: float = 1024.0,
+    floor_tok_s: float = 1.0,
+    model_ref: Optional[str] = None,
+    force_n_cpu_moe: Optional[int] = None,
+    calibration: Optional[CalibrationModel] = None,
+) -> PlacementPlan:
+    """Plan an MoE placement for llama.cpp `--n-cpu-moe`. Honest verdict, never raises."""
+    hw, model = profile.hardware, profile.model
+
+    if model is None or not model.expert.is_moe:
+        return PlacementPlan(fits=False, verdict="refuse",
+                             message="Not an MoE model (or no model profiled) — the --n-cpu-moe lane "
+                                     "is MoE-only. Dense offload is a separate (refusal-prone) lane.")
+    if model.expert_params_total is None or model.non_expert_params is None or not model.n_moe_layers:
+        return PlacementPlan(fits=False, verdict="refuse",
+                             message="model profile lacks the closed-form param split — re-run the "
+                                     "profiler with --model-config <config.json>.")
+    vram_budget = hw.gpu.vram_free_mib or hw.gpu.vram_total_mib
+    if not vram_budget:
+        return PlacementPlan(fits=False, verdict="refuse",
+                             message="VRAM unknown (profiler returned None) — cannot place honestly.")
+
+    bpw = model_mod.bytes_per_weight(model.quant, model.dtype_bytes)
+    cpu_bw = (cpu_mem_bw_gbps or getattr(hw.memory, "cpu_mem_bw_gbps", None) or DEFAULT_CPU_BW_GBPS) * _GB
+    vram_bw = (vram_bw_gbps or DEFAULT_VRAM_BW_GBPS) * _GB
+    cpu_bw_measured = bool(cpu_mem_bw_gbps or getattr(hw.memory, "cpu_mem_bw_gbps", None))
+
+    # Non-expert (always-resident) weights may carry a heavier precision than the experts: MXFP4
+    # quantizes experts only, leaving attention/embeddings near f16. Budget the GPU floor at that
+    # precision so the plan doesn't under-count VRAM (model.non_expert_bytes_per_weight default;
+    # `non_expert_bpw` overrides). Whole-model quants (Q4_K_M, ...) resolve to the same bpw.
+    ne_bpw = (non_expert_bpw if non_expert_bpw is not None
+              else model_mod.non_expert_bytes_per_weight(model.quant, model.dtype_bytes))
+    Lm = model.n_moe_layers
+    expert_total_bytes = model.expert_params_total * bpw
+    non_expert_bytes = model.non_expert_params * ne_bpw
+    per_layer_expert_bytes = expert_total_bytes / Lm
+    kv_bytes = model.kv_bytes_at(ctx_len, batch) or 0
+
+    def vram_used_mib(n: int) -> float:
+        gpu_expert_bytes = per_layer_expert_bytes * (Lm - n)
+        return (non_expert_bytes + gpu_expert_bytes + kv_bytes) / _MIB + overhead_mib
+
+    assumptions = {
+        "cpu_mem_bw_gbps": round(cpu_bw / _GB, 1), "cpu_bw_measured": cpu_bw_measured,
+        "vram_bw_gbps": round(vram_bw / _GB, 1), "bytes_per_weight": round(bpw, 3),
+        "non_expert_bpw": round(ne_bpw, 3),
+        "ctx_len": ctx_len, "batch": batch, "overhead_mib": overhead_mib,
+        "kv_dtype": "f16", "model_total_b": model.total_params,
+        "forced_n": force_n_cpu_moe,
+    }
+
+    if force_n_cpu_moe is not None:
+        # explore a specific N (what-if / receipt scoring) instead of the auto-minimal one
+        N = max(0, min(int(force_n_cpu_moe), Lm))
+        if vram_used_mib(N) > vram_budget:
+            return PlacementPlan(
+                fits=False, verdict="refuse", n_cpu_moe=N, n_moe_layers=Lm,
+                vram_budget_mib=round(vram_budget, 1), vram_used_mib=round(vram_used_mib(N), 1),
+                assumptions=assumptions, floor_tok_s=floor_tok_s,
+                message=f"REFUSE: forced --n-cpu-moe {N} still needs ~{vram_used_mib(N):.0f} MiB "
+                        f"> {vram_budget:.0f} MiB free VRAM.")
+    else:
+        # smallest N in [0, Lm] that fits — maximal GPU residency, maximal speed
+        n_fit = next((n for n in range(0, Lm + 1) if vram_used_mib(n) <= vram_budget), None)
+        if n_fit is None:
+            floor_vram = vram_used_mib(Lm)
+            return PlacementPlan(
+                fits=False, verdict="refuse", n_cpu_moe=Lm, n_moe_layers=Lm,
+                vram_budget_mib=round(vram_budget, 1), vram_used_mib=round(floor_vram, 1),
+                assumptions=assumptions, floor_tok_s=floor_tok_s,
+                message=(f"REFUSE: even with ALL experts on CPU (--cpu-moe), the always-resident footprint "
+                         f"(attention + router + embeddings + output head + {ctx_len}-tok KV) needs "
+                         f"~{floor_vram:.0f} MiB > {vram_budget:.0f} MiB free VRAM. You probably expected "
+                         f"{model.name} to fit; it cannot, because the non-expert weights alone exceed VRAM. "
+                         f"Options: shorter --ctx, q8_0 KV cache, a smaller/more-quantized model, or more VRAM."),
+            )
+        N = n_fit
+    ram_used_mib = per_layer_expert_bytes * N / _MIB
+    ram_avail_mib = (hw.memory.ram_available_gib or hw.memory.ram_total_gib or 0) * 1024
+    ram_ok = (ram_used_mib <= ram_avail_mib) if ram_avail_mib else True
+
+    # bandwidth-bound decode estimate
+    topk = model.expert.experts_per_token or 0
+    active_each = (model.expert.expert_params_each or 0) * bpw
+    gpu_active_expert = active_each * topk * (Lm - N)
+    cpu_active_expert = active_each * topk * N
+    # per-token GPU read ≈ all non-expert weights (attention/router/head) + GPU-resident active
+    # experts + the KV cache (attention reads it every decode step). CPU reads its active experts.
+    # This is a ROOFLINE CEILING (peak bandwidth, no kernel/launch/attention-compute overhead): a
+    # true UPPER BOUND on decode tok/s. Real decode runs at a fraction of it; the receipt measures
+    # the actual efficiency and closes the gap. Refusal is conservative — it fires only when even
+    # this optimistic ceiling cannot clear the floor.
+    t_gpu = (non_expert_bytes + gpu_active_expert + kv_bytes) / vram_bw
+    t_cpu = cpu_active_expert / cpu_bw
+    ceiling = (1.0 / (t_gpu + t_cpu)) if (t_gpu + t_cpu) > 0 else None
+    basis = ("roofline ceiling, in-VRAM (active-weight bandwidth; real decode is a fraction of this -- "
+             "small-active MoE is largely overhead-bound -- confirmed by receipt)" if N == 0
+             else "roofline ceiling, CPU-offload (real well below; heavy-offload can miss 2-3x -- confirmed by receipt)")
+
+    # Calibrated forecast (opt-in): scale the ceiling by the measured realized efficiency for this
+    # regime (calibration.py). With no calibration data the forecast IS the ceiling -- the honest
+    # uncalibrated path. The ceiling is retained as the upper bound AND the refusal floor below.
+    calibrated, band_low, band_high, calib_n = ceiling, None, None, 0
+    calib_basis = ("uncalibrated: the roofline ceiling is the upper bound -- real decode is a fraction; "
+                   "run a receipt (gpu-container-receipt) to calibrate this shape")
+    if calibration is not None and ceiling is not None:
+        est = calibration.estimate("in_vram" if N == 0 else "offload", (N / Lm) if Lm else 0.0)
+        if est is not None:
+            calibrated = ceiling * est.efficiency
+            band_low, band_high = ceiling * est.low, ceiling * est.high
+            calib_n, calib_basis = est.n_samples, est.basis
+
+    # Refusal floor keys on the CEILING (conservative ANDON): refuse only when even the optimistic
+    # upper bound cannot clear the floor -- never refuse a model that might be usable.
+    below_floor = ceiling is not None and ceiling < floor_tok_s
+    verdict = "refuse" if (below_floor or not ram_ok) else "ship"
+    vu = vram_used_mib(N)
+
+    # -fa on (not bare -fa): current llama.cpp made flash-attn a tri-state (on|off|auto) and rejects
+    # a value-less -fa. Confirmed against the ghcr.io/ggml-org/llama.cpp:full-cuda help (2026-06-04).
+    flags = f"-ngl 99 --n-cpu-moe {N} -c {ctx_len} -fa on"
+    cmd_model = f"-hf {model_ref}" if model_ref else "-m <model.gguf>"
+
+    if verdict == "refuse" and below_floor:
+        msg = (f"REFUSE: even the roofline CEILING for the best plan (--n-cpu-moe {N}) is "
+               f"~{ceiling:.2f} tok/s < {floor_tok_s} floor — real decode is lower still. "
+               f"You probably expected {model.name} to be usable; with {N}/{Lm} expert layers on CPU "
+               f"(RAM bandwidth ~{cpu_bw/_GB:.0f} GB/s) it cannot clear the floor. "
+               f"Options: a smaller model, fewer active experts, or more VRAM to keep N low.")
+    elif verdict == "refuse":
+        msg = (f"REFUSE: plan needs {ram_used_mib/1024:.1f} GiB CPU RAM for {N} expert layers but only "
+               f"~{ram_avail_mib/1024:.1f} GiB available.")
+    else:
+        tier = "fully in VRAM" if N == 0 else f"{N}/{Lm} expert layers on CPU RAM"
+        if calib_n:
+            forecast = (f"~{calibrated:.0f} tok/s (calibrated, band [{band_low:.0f}, {band_high:.0f}]; "
+                        f"roofline ceiling {ceiling:.0f}, from {calib_n} receipt(s))")
+        else:
+            forecast = f"<= {ceiling:.0f} tok/s (roofline ceiling — real is a fraction; run a receipt to calibrate)"
+        msg = (f"SHIP: {model.name} {tier}. Decode {forecast}. "
+               f"VRAM ~{vu:.0f}/{vram_budget:.0f} MiB, CPU-expert RAM ~{ram_used_mib/1024:.1f} GiB. "
+               f"Launch: llama-cli {cmd_model} {flags}")
+        if calib_n and calibrated < floor_tok_s <= ceiling:
+            msg += (f" — borderline: the calibrated forecast (~{calibrated:.1f}) dips below the {floor_tok_s} "
+                    f"tok/s floor though the ceiling clears it; the receipt will settle it.")
+
+    return PlacementPlan(
+        fits=True, verdict=verdict, n_cpu_moe=N, n_moe_layers=Lm, llama_flags=flags,
+        vram_budget_mib=round(vram_budget, 1), vram_used_mib=round(vu, 1),
+        ram_used_mib=round(ram_used_mib, 1),
+        predicted_decode_tok_s=round(calibrated, 2) if calibrated else None,
+        ceiling_decode_tok_s=round(ceiling, 2) if ceiling else None,
+        predicted_band_low_tok_s=round(band_low, 2) if band_low else None,
+        predicted_band_high_tok_s=round(band_high, 2) if band_high else None,
+        throughput_basis=basis, calibration_basis=calib_basis, calibration_n_samples=calib_n,
+        floor_tok_s=floor_tok_s, message=msg, assumptions=assumptions,
+    )

gpu_container/planner/receipt.py

@@ -0,0 +1,155 @@
+"""The receipt — a DIFFERENT mechanism (measurement) verifying the planner's forecast.
+
+llama-bench emits per-test rows (`pp###` = prefill, `tg###` = token-generation/decode) with an
+`avg_ts` tokens/sec. We parse that, pair it with the plan's predicted CEILING, and record the
+realized efficiency (measured ÷ ceiling) + whether the >1 tok/s floor actually cleared. That
+efficiency is the calibration seed that closes the static-prediction gap (the architecture's loop).
+The model never grades its own forecast: the generator is the planner's closed form; the verifier
+is a real run on the GPU.
+"""
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from ..profiler.schema import PlacementPlan, Receipt
+from .activation import ConcentrationReport
+from .calibration import CalibrationPoint
+
+
+def parse_llama_bench(stdout: str) -> List[dict]:
+    """Parse `llama-bench -o json` output into [{test, n_cpu_moe, n_gpu_layers, avg_ts}, ...]."""
+    # The JSON array may be embedded in other log lines; extract the outermost [...] span.
+    s, e = stdout.find("["), stdout.rfind("]")
+    if s < 0 or e < 0 or e <= s:
+        return []
+    try:
+        rows = json.loads(stdout[s:e + 1])
+    except ValueError:
+        return []
+    out = []
+    for r in rows:
+        if not isinstance(r, dict):
+            continue
+        out.append({
+            "test": r.get("test") or r.get("n_prompt") or "?",
+            "n_cpu_moe": r.get("n_cpu_moe"),
+            "n_gpu_layers": r.get("n_gpu_layers"),
+            "avg_ts": r.get("avg_ts"),
+            "model": r.get("model_filename") or r.get("model_type"),
+        })
+    return out
+
+
+def _pick(rows: List[dict], prefix: str) -> Optional[float]:
+    """Average tok/s for the first row whose `test` starts with `prefix` (tg=decode, pp=prefill)."""
+    for r in rows:
+        t = str(r.get("test", ""))
+        if t.startswith(prefix) and r.get("avg_ts") is not None:
+            return float(r["avg_ts"])
+    return None
+
+
+def build_receipt(
+    plan: PlacementPlan,
+    decode_tok_s: Optional[float],
+    prefill_tok_s: Optional[float] = None,
+    vram_used_mib: Optional[float] = None,
+    method: Optional[str] = None,
+    concentration: Optional[ConcentrationReport] = None,
+    peaks: Optional[dict] = None,
+) -> Receipt:
+    """Pair a measured run with the plan's forecast(s) -> a Receipt.
+
+    The plan now carries two forecasts, so the receipt makes two comparisons:
+      - realized efficiency = measured / CEILING  -> the calibration seed for the next plan,
+      - decode error        = (measured - CALIBRATED) / CALIBRATED -> was the calibrated forecast right?,
+      - within_band         = measured inside the plan's calibrated band -> the loop's proof.
+    `ceiling` falls back to the calibrated field for plans predating the ceiling split.
+
+    `peaks` (a dict from `gpu-container-watchdog run --peaks-out`) folds the run's SAFETY ENVELOPE
+    into the receipt — peak power / host-mem / VRAM — proving the run stayed inside the rig's limits.
+    """
+    pred = plan.predicted_decode_tok_s                                    # calibrated forecast
+    ceiling = plan.ceiling_decode_tok_s or plan.predicted_decode_tok_s    # roofline upper bound
+    err = round(100.0 * (decode_tok_s - pred) / pred, 1) if (decode_tok_s and pred) else None
+    eff_pct = round(100.0 * decode_tok_s / ceiling, 1) if (decode_tok_s and ceiling) else None
+    lo, hi = plan.predicted_band_low_tok_s, plan.predicted_band_high_tok_s
+    within = (lo <= decode_tok_s <= hi) if (decode_tok_s and lo is not None and hi is not None) else None
+
+    notes: List[str] = []
+    if eff_pct is not None:
+        notes.append(f"realized {eff_pct:.0f}% of the roofline ceiling ({decode_tok_s:.1f} of {ceiling:.0f} tok/s) "
+                     f"— this efficiency is the calibration seed for the next plan.")
+        if decode_tok_s > ceiling:
+            notes.append("ANDON: measured EXCEEDS the ceiling — the bandwidth model is wrong (check "
+                         "vram_bw / bytes_per_weight assumptions), not just inefficient.")
+    if within is not None:
+        notes.append(f"calibrated forecast {pred:.1f} tok/s, band [{lo:.1f}, {hi:.1f}] — measured "
+                     f"{decode_tok_s:.1f} {'LANDED INSIDE' if within else 'FELL OUTSIDE'} the band "
+                     f"({'loop closed' if within else 'recalibrate: ingest this receipt and refit'}).")
+    if plan.vram_used_mib and vram_used_mib:
+        dv = 100.0 * (vram_used_mib - plan.vram_used_mib) / plan.vram_used_mib
+        notes.append(f"VRAM predicted {plan.vram_used_mib:.0f} MiB vs measured {vram_used_mib:.0f} MiB ({dv:+.0f}%).")
+    if concentration is not None:
+        helps = ("a per-expert cache COULD help this workload" if concentration.cache_helps
+                 else "routing is near-uniform — a per-expert cache would NOT help this workload")
+        notes.append(f"routing de-risk: {helps} (need {concentration.hot_frac_for_coverage:.0%} of experts for "
+                     f"{concentration.coverage_target:.0%} coverage; concentration {concentration.concentration_score:.2f}, "
+                     f"top expert {concentration.top1_share:.1%}).")
+    if peaks:
+        env = []
+        if peaks.get("peak_host_mem_pct") is not None:
+            env.append(f"peak host-mem {peaks['peak_host_mem_pct']:.0f}%")
+        if peaks.get("peak_gpu_power_pct") is not None:
+            env.append(f"peak power {peaks['peak_gpu_power_pct']:.0f}%")
+        if peaks.get("peak_gpu_vram_used_mib") is not None:
+            env.append(f"peak VRAM {peaks['peak_gpu_vram_used_mib'] / 1024:.1f} GiB")
+        stayed = peaks.get("stayed_within_envelope")
+        tail = ("stayed within the safety envelope" if stayed else
+                "BREACHED the safety envelope — aborted mid-run") if stayed is not None else "envelope recorded"
+        notes.append(f"safety: {', '.join(env) or 'no peaks'} over {peaks.get('samples', 0)} watchdog polls "
+                     f"— {tail}.")
+    return Receipt(
+        runtime=plan.runtime, n_cpu_moe=plan.n_cpu_moe,
+        measured_decode_tok_s=round(decode_tok_s, 2) if decode_tok_s else None,
+        measured_prefill_tok_s=round(prefill_tok_s, 2) if prefill_tok_s else None,
+        measured_vram_used_mib=round(vram_used_mib, 1) if vram_used_mib else None,
+        predicted_decode_tok_s=pred, ceiling_decode_tok_s=round(ceiling, 2) if ceiling else None,
+        decode_error_pct=err, realized_efficiency_pct=eff_pct, within_band=within,
+        cleared_floor=(decode_tok_s >= plan.floor_tok_s) if decode_tok_s else None,
+        routing_cache_helps=concentration.cache_helps if concentration else None,
+        routing_hot_frac_for_coverage=round(concentration.hot_frac_for_coverage, 3) if concentration else None,
+        routing_concentration=round(concentration.concentration_score, 3) if concentration else None,
+        peak_gpu_power_pct=(peaks or {}).get("peak_gpu_power_pct"),
+        peak_gpu_temp_c=(peaks or {}).get("peak_gpu_temp_c"),
+        peak_gpu_vram_used_mib=(peaks or {}).get("peak_gpu_vram_used_mib"),
+        peak_host_mem_pct=(peaks or {}).get("peak_host_mem_pct"),
+        min_host_avail_mib=(peaks or {}).get("min_host_avail_mib"),
+        safety_samples=(peaks or {}).get("samples"),
+        stayed_within_envelope=(peaks or {}).get("stayed_within_envelope"),
+        method=method, notes=notes,
+    )
+
+
+def plan_to_calibration_point(
+    plan: PlacementPlan,
+    measured_decode_tok_s: float,
+    model_name: str,
+    quant: Optional[str] = None,
+    created: Optional[str] = None,
+    rig: Optional[str] = None,
+    source: Optional[str] = None,
+) -> CalibrationPoint:
+    """Distill a (plan, measured-decode) pair into a CalibrationPoint for the store — the loop's
+    write-back. The ceiling comes from the plan (so efficiency is measured/ceiling); the bandwidth
+    assumptions ride along as provenance so the point stays auditable."""
+    a = plan.assumptions or {}
+    return CalibrationPoint(
+        model=model_name, quant=quant,
+        n_cpu_moe=plan.n_cpu_moe or 0, n_moe_layers=plan.n_moe_layers or 0,
+        ceiling_tok_s=plan.ceiling_decode_tok_s or plan.predicted_decode_tok_s or 0.0,
+        measured_tok_s=measured_decode_tok_s,
+        cpu_bw_gbps=a.get("cpu_mem_bw_gbps"), vram_bw_gbps=a.get("vram_bw_gbps"),
+        ctx_len=a.get("ctx_len"), created=created, rig=rig, source=source,
+    )