gpu-container 0.1.0__py3-none-any.whl

gpu_container/profiler/model.py

@@ -0,0 +1,178 @@
+"""Model profiler — analyze a model's architecture + memory growth before loading.
+
+What's REAL here today (closed-form, deterministic — docker-knowledge throughput-prediction
+finding "Memory is exact"):
+  - KV-cache bytes/token and at a given context (linear in context).
+  - dense vs MoE detection, expert structure, from a HuggingFace config dict.
+
+What's STUBBED (needs the file on disk / a download — a later Phase-1 step):
+  - total_params and per-layer/per-expert byte accounting from safetensors/GGUF headers.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .schema import ExpertInfo, ModelProfile
+
+# dtype name -> bytes per element
+_DTYPE_BYTES = {
+    "float32": 4.0, "float": 4.0, "fp32": 4.0,
+    "float16": 2.0, "fp16": 2.0, "half": 2.0,
+    "bfloat16": 2.0, "bf16": 2.0,
+    "float8": 1.0, "fp8": 1.0, "e4m3": 1.0, "e5m2": 1.0,
+}
+
+
+def kv_bytes_per_token(n_layers: int, n_kv_heads: int, head_dim: int, dtype_bytes: float = 2.0) -> int:
+    """Closed-form KV-cache size per token, in bytes.
+
+        bytes/token = 2 (K and V) * n_layers * n_kv_heads * head_dim * dtype_bytes
+
+    Per NVIDIA "Mastering LLM Techniques: Inference Optimization" (docker-knowledge
+    throughput-prediction). GQA/MQA shrink this via n_kv_heads < n_attention_heads.
+    """
+    return int(2 * n_layers * n_kv_heads * head_dim * dtype_bytes)
+
+
+def _dtype_bytes_from(cfg: dict) -> float:
+    td = str(cfg.get("torch_dtype") or cfg.get("dtype") or "bfloat16").lower()
+    return _DTYPE_BYTES.get(td, 2.0)
+
+
+# Effective GGUF bits-per-weight (incl. quant metadata overhead) — llama.cpp quant tables.
+# Used to turn a closed-form param count into a realistic on-device byte footprint.
+_BPW = {
+    "q2_k": 3.35, "q3_k_s": 3.50, "q3_k_m": 3.91, "q3_k_l": 4.27,
+    "q4_0": 4.55, "q4_1": 4.78, "q4_k_s": 4.57, "q4_k_m": 4.83,
+    "q5_0": 5.54, "q5_1": 6.00, "q5_k_s": 5.52, "q5_k_m": 5.67,
+    "q6_k": 6.56, "q8_0": 8.50,
+    "iq2_xxs": 2.06, "iq3_xxs": 3.06, "iq4_xs": 4.25, "iq4_nl": 4.50,
+    "mxfp4": 4.25, "fp8": 8.0, "f16": 16.0, "bf16": 16.0, "f32": 32.0,
+}
+
+
+def bytes_per_weight(quant: Optional[str], dtype_bytes: float = 2.0) -> float:
+    """Bytes per weight for a quant tag (e.g. 'gguf-q4_k_m' -> 0.60), or the dtype default."""
+    if quant:
+        k = quant.lower().replace("gguf-", "").replace("-", "_").strip()
+        if k in _BPW:
+            return _BPW[k] / 8.0
+    return dtype_bytes
+
+
+# Quants that quantize ONLY the routed experts, leaving attention/router/embeddings/head near f16
+# (notably MXFP4 / gpt-oss). For these the always-resident non-expert weights are far heavier per
+# parameter than the headline quant implies, so budgeting the GPU floor at the expert bpw would
+# UNDER-count VRAM (the optimistic, OOM-prone direction). The split keeps None-not-guess honest.
+_EXPERT_ONLY_QUANTS = {"mxfp4"}
+
+
+def non_expert_bytes_per_weight(quant: Optional[str], dtype_bytes: float = 2.0) -> float:
+    """Bytes/weight for the ALWAYS-RESIDENT (non-expert) tensors.
+
+    Equal to the expert bpw for whole-model quants (Q4_K_M, Q8_0, ...). For expert-only quants
+    (MXFP4) the non-expert tensors stay near f16, so this returns 2.0 — a conservative upper bound
+    on the GPU floor (slightly over-budgets VRAM, which is the SAFE side for a must-offload plan).
+    """
+    if quant:
+        k = quant.lower().replace("gguf-", "").replace("-", "_").strip()
+        if k in _EXPERT_ONLY_QUANTS:
+            return max(2.0, _BPW.get(k, 8.0) / 8.0)
+    return bytes_per_weight(quant, dtype_bytes)
+
+
+def estimate_param_split(cfg: dict, num_experts: Optional[int]) -> Optional[dict]:
+    """Closed-form param split from a HF config — no safetensors needed.
+
+    Returns the two quantities the placement planner keys off:
+      - `expert_total` / `expert_each` — routed-expert params (`--n-cpu-moe` can move these to CPU),
+      - `non_expert` — attention + router + embeddings + head + shared experts + dense layers
+        (ALWAYS on the GPU), plus `total` and `n_moe_layers`.
+    Approximations (documented, receipt-confirmed): SwiGLU expert = 3·H·I; biases/norms omitted
+    (sub-1%); a real GGUF may keep embeddings/output at higher precision than the headline quant.
+    """
+    H = cfg.get("hidden_size")
+    L = cfg.get("num_hidden_layers")
+    if not (H and L):
+        return None
+    n_heads = cfg.get("num_attention_heads") or 0
+    n_kv = cfg.get("num_key_value_heads") or n_heads
+    head_dim = cfg.get("head_dim") or (H // n_heads if n_heads else 0)
+    vocab = cfg.get("vocab_size") or 0
+    inter = cfg.get("intermediate_size") or 0
+    moe_inter = cfg.get("moe_intermediate_size") or inter
+    tied = bool(cfg.get("tie_word_embeddings", False))
+    n_dense = cfg.get("first_k_dense_replace") or cfg.get("num_dense_layers") or 0
+    n_shared = cfg.get("n_shared_experts") or cfg.get("num_shared_experts") or 0
+    shared_inter = cfg.get("shared_expert_intermediate_size") or moe_inter
+
+    n_moe_layers = max(0, L - n_dense) if num_experts else 0
+    dense_count = L - n_moe_layers  # dense FFN layers (= n_dense for MoE, = L for dense models)
+
+    expert_each = 3 * H * moe_inter if (num_experts and moe_inter) else 0
+    expert_total = (num_experts or 0) * expert_each * n_moe_layers
+
+    attn_total = (2 * H * n_heads * head_dim + 2 * H * n_kv * head_dim) * L  # q,o + k,v
+    router_total = (num_experts or 0) * H * n_moe_layers
+    shared_total = (n_shared * 3 * H * shared_inter) * n_moe_layers if n_shared else 0
+    dense_ffn_total = (3 * H * inter) * dense_count
+    embed = vocab * H
+    head = 0 if tied else vocab * H
+    non_expert = attn_total + router_total + shared_total + dense_ffn_total + embed + head
+    return {
+        "expert_total": int(expert_total), "expert_each": int(expert_each),
+        "non_expert": int(non_expert), "total": int(non_expert + expert_total),
+        "n_moe_layers": int(n_moe_layers),
+    }
+
+
+def analyze_config(config: dict, name: Optional[str] = None, quant: Optional[str] = None) -> ModelProfile:
+    """Build a ModelProfile from a HuggingFace-style config.json dict.
+
+    Recognizes the common MoE keys across Mixtral / Qwen-MoE / DeepSeek-V2/V3 / OLMoE.
+    Fields it cannot determine are left None (never guessed).
+    """
+    name = name or config.get("_name_or_path") or config.get("model_type") or "unknown"
+    n_layers = config.get("num_hidden_layers")
+    n_attn_heads = config.get("num_attention_heads")
+    n_kv_heads = config.get("num_key_value_heads") or n_attn_heads
+    hidden = config.get("hidden_size")
+    head_dim = config.get("head_dim")
+    if head_dim is None and hidden and n_attn_heads:
+        head_dim = hidden // n_attn_heads
+    dtype_bytes = _dtype_bytes_from(config)
+
+    # MoE detection — the key name varies by family
+    num_experts = (config.get("num_local_experts") or config.get("num_experts")
+                   or config.get("n_routed_experts"))
+    experts_per_token = (config.get("num_experts_per_tok") or config.get("num_experts_per_token")
+                         or config.get("moe_topk"))
+    is_moe = num_experts is not None
+    split = estimate_param_split(config, num_experts)
+    expert = ExpertInfo(
+        is_moe=is_moe,
+        num_experts=num_experts,
+        experts_per_token=experts_per_token,
+        shared_params=config.get("n_shared_experts"),
+        expert_params_each=(split or {}).get("expert_each") or None,
+    )
+
+    kvbpt = None
+    if n_layers and n_kv_heads and head_dim:
+        kvbpt = kv_bytes_per_token(n_layers, n_kv_heads, head_dim, dtype_bytes)
+
+    return ModelProfile(
+        name=name,
+        architecture="moe" if is_moe else ("dense" if n_layers else "unknown"),
+        total_params=(split or {}).get("total"),
+        n_layers=n_layers,
+        n_kv_heads=n_kv_heads,
+        head_dim=head_dim,
+        dtype_bytes=dtype_bytes,
+        quant=quant,
+        expert=expert,
+        kv_bytes_per_token=kvbpt,
+        expert_params_total=(split or {}).get("expert_total"),
+        non_expert_params=(split or {}).get("non_expert"),
+        n_moe_layers=(split or {}).get("n_moe_layers"),
+    )

gpu_container/profiler/nvme_bench.py

@@ -0,0 +1,158 @@
+"""NVMe benchmark via fio — sequential AND random-QD1, on the path that actually matters.
+
+docker-knowledge wave-2 `hw-measurement` spec:
+  - Two passes: SEQUENTIAL (`--rw=read --bs=256k --iodepth=64`) and RANDOM-QD1
+    (`--rw=randread --bs=4k --iodepth=1`). QD1 4k is the latency-bound figure the
+    cold-expert / KV-spill streaming path actually hits; the sequential headline overstates
+    offload throughput by ~10x, so the planner keys streaming math off the QD1 number.
+  - `--direct=1 --ioengine=libaio` is mandatory to bypass the OS page cache (otherwise we
+    measure RAM, not the SSD). If O_DIRECT is unsupported we REFUSE — never a silent
+    buffered fallback that reports a dishonest number.
+  - Target a bind-mounted / named volume on the ext4 vdisk. The container's overlay2 layer
+    breaks O_DIRECT and mismeasures; a `/mnt/<letter>` drvfs/9p path is ~5-10x slower than
+    real ext4. We detect the mount type and refuse the wrong filesystem rather than lie.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from typing import Optional, Tuple
+
+# Filesystems we must NOT measure on (they produce dishonest numbers).
+_BAD_FS = {"overlay", "overlayfs", "9p", "drvfs", "v9fs", "fuse.drvfs"}
+
+
+def _mount_for(path: str) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    """Return (mountpoint, fstype, device) for the filesystem backing `path`.
+
+    Reads /proc/mounts and picks the longest mountpoint that is a prefix of `path`.
+    Returns (None, None, None) where /proc/mounts is unavailable (e.g. a Windows host).
+    """
+    try:
+        with open("/proc/mounts", "r", encoding="utf-8", errors="ignore") as f:
+            entries = []
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 3:
+                    entries.append((parts[1], parts[2], parts[0]))  # mountpoint, fstype, device
+    except OSError:
+        return (None, None, None)
+    target = os.path.abspath(path)
+    best = (None, None, None)
+    best_len = -1
+    for mp, fstype, dev in entries:
+        if (target == mp or target.startswith(mp.rstrip("/") + "/") or mp == "/") and len(mp) > best_len:
+            best, best_len = (mp, fstype, dev), len(mp)
+    return best
+
+
+def resolve_bench_dir(explicit: Optional[str] = None) -> Tuple[Optional[str], Optional[str]]:
+    """Pick the directory to benchmark. Returns (dir, reason_if_none)."""
+    candidate = explicit or os.environ.get("GPU_CONTAINER_BENCH_DIR")
+    if candidate:
+        return (candidate, None)
+    if os.path.isdir("/bench"):  # the conventional bind-mount target (see Dockerfile)
+        return ("/bench", None)
+    return (None, "no bench dir: pass --bench-dir or mount an ext4 volume at /bench "
+                  "(-v <host-nvme-path>:/bench)")
+
+
+def _run_fio(fio: str, testfile: str, rw: str, bs: str, qd: int,
+             size_gib: int, runtime_s: int, ramp_s: int) -> dict:
+    cmd = [
+        fio, "--name=gpc", f"--filename={testfile}",
+        "--direct=1", "--ioengine=libaio",
+        f"--rw={rw}", f"--bs={bs}", f"--iodepth={qd}", "--numjobs=1",
+        f"--size={size_gib}G", "--time_based", f"--runtime={runtime_s}",
+        f"--ramp_time={ramp_s}", "--group_reporting", "--output-format=json",
+    ]
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=runtime_s + ramp_s + 180)
+    except (FileNotFoundError, subprocess.SubprocessError) as e:
+        return {"error": f"fio invocation failed: {e}"}
+
+    blob = (p.stdout or "") + "\n" + (p.stderr or "")
+    if "O_DIRECT" in blob or "does not support" in blob or "Operation not supported" in blob:
+        return {"error": "O_DIRECT unsupported on this path (overlay fs?) — refusing buffered "
+                         "fallback; mount an ext4 volume", "stderr": (p.stderr or "")[:400]}
+    if p.returncode != 0:
+        return {"error": f"fio exit {p.returncode}", "stderr": (p.stderr or "")[:400]}
+
+    try:
+        j = json.loads(p.stdout)
+        r = j["jobs"][0]["read"]
+    except (ValueError, KeyError, IndexError) as e:
+        return {"error": f"could not parse fio json: {e}"}
+
+    lat = r.get("lat_ns") or r.get("clat_ns") or {}
+    return {
+        "bw_bytes": r.get("bw_bytes"),          # bytes/sec
+        "iops": r.get("iops"),
+        "lat_us_mean": round(lat["mean"] / 1000.0, 2) if lat.get("mean") is not None else None,
+    }
+
+
+def measure_nvme(bench_dir: Optional[str] = None, size_gib: int = 4,
+                 runtime_s: int = 8, ramp_s: int = 2) -> dict:
+    """Run the seq + random-QD1 fio passes on a validated mount. Honest dict, never raises."""
+    out: dict = {
+        "seq_read_gbps": None, "rand_qd1_iops": None, "rand_qd1_mbps": None,
+        "rand_qd1_lat_us": None, "fs_type": None, "mount": None, "bench_dir": None,
+        "direct": True, "ioengine": "libaio", "size_gib": size_gib,
+    }
+    fio = shutil.which("fio")
+    if not fio:
+        out["error"] = "fio not found (install fio in the container)"
+        return out
+
+    target, reason = resolve_bench_dir(bench_dir)
+    if target is None:
+        out["error"] = reason
+        return out
+    out["bench_dir"] = target
+
+    try:
+        os.makedirs(target, exist_ok=True)
+    except OSError as e:
+        out["error"] = f"bench dir not writable: {e}"
+        return out
+
+    mp, fstype, _dev = _mount_for(target)
+    out["mount"], out["fs_type"] = mp, fstype
+    if fstype and fstype.lower() in _BAD_FS:
+        out["error"] = (f"refusing to benchmark fs '{fstype}' at {mp}: overlay/drvfs/9p "
+                        f"mismeasure NVMe — mount an ext4 volume at {target}")
+        return out
+    if target.startswith("/mnt/") and fstype not in (None,):
+        out["error"] = f"refusing /mnt drvfs path {target} (~5-10x slower than ext4)"
+        return out
+
+    testfile = os.path.join(target, ".gpu_container_fio_test.bin")
+    try:
+        seq = _run_fio(fio, testfile, "read", "256k", 64, size_gib, runtime_s, ramp_s)
+        qd1 = _run_fio(fio, testfile, "randread", "4k", 1, size_gib, runtime_s, ramp_s)
+    finally:
+        try:
+            if os.path.exists(testfile):
+                os.remove(testfile)
+        except OSError:
+            pass
+
+    errors = []
+    if "error" in seq:
+        errors.append("seq: " + seq["error"])
+    elif seq.get("bw_bytes"):
+        out["seq_read_gbps"] = round(seq["bw_bytes"] / 1e9, 3)
+    if "error" in qd1:
+        errors.append("qd1: " + qd1["error"])
+    else:
+        if qd1.get("iops") is not None:
+            out["rand_qd1_iops"] = round(qd1["iops"], 1)
+        if qd1.get("bw_bytes"):
+            out["rand_qd1_mbps"] = round(qd1["bw_bytes"] / 1e6, 2)
+        out["rand_qd1_lat_us"] = qd1.get("lat_us_mean")
+    if errors:
+        out["error"] = " | ".join(errors)
+    return out

gpu_container/profiler/schema.py

@@ -0,0 +1,245 @@
+"""Profile schema — the contract every downstream component (planner, receipt) reads.
+
+A `Profile` = `HardwareProfile` + optional `ModelProfile` + provenance, fully
+JSON-serializable. Measurement fields are `Optional` and default to `None`: a value
+of `None` means "not measured / unknown", and the planner MUST NOT treat it as zero
+or assume a spec-sheet number (docker-knowledge wave-1, lane `hw-measurement`: honest
+refusal depends on honest inputs; consumer cards are PCIe-bound and NVMe random-QD1 is
+far below sequential, so guessing here silently corrupts every downstream plan).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from typing import Any, List, Optional
+
+SCHEMA_VERSION = "0.1.0"
+
+
+@dataclass
+class GpuInfo:
+    name: str
+    vram_total_mib: Optional[int] = None
+    vram_free_mib: Optional[int] = None
+    vram_reserved_mib: Optional[int] = None     # driver-reserved (pynvml v2 only); v1 folds this into 'used'
+    driver_version: Optional[str] = None
+    cuda_version: Optional[str] = None
+    compute_capability: Optional[str] = None   # e.g. "12.0" for sm_120 (desktop Blackwell)
+    pcie_gen: Optional[int] = None
+    pcie_width: Optional[int] = None            # lanes, e.g. 16
+    vram_source: Optional[str] = None           # "pynvml-v2" | "pynvml-v1" | "nvidia-smi" (provenance)
+
+
+@dataclass
+class PlatformInfo:
+    os: str                                     # "windows" | "linux"
+    in_container: bool = False
+    wsl2: bool = False
+    container_runtime: Optional[str] = None     # "docker" | None
+    nvidia_runtime: Optional[bool] = None       # NVIDIA Container Toolkit wired in
+    # The load-bearing positioning (docker-knowledge lane `container-runtime`):
+    # CUDA UVM oversubscription is unavailable on windows/wsl2 -> explicit placement only.
+    uvm_oversubscription: Optional[bool] = None
+
+
+@dataclass
+class BandwidthInfo:
+    """Measured, never spec-sheet. None until benchmarked (hardened in docker-knowledge wave-2)."""
+    pcie_h2d_gbps: Optional[float] = None              # achieved pinned (~50-55 on Gen5; never the 64 theoretical)
+    pcie_d2h_gbps: Optional[float] = None              # measured separately — asymmetry is real
+    nvme_seq_read_gbps: Optional[float] = None         # optimistic ceiling only
+    nvme_rand_qd1_read_iops: Optional[float] = None   # the one a sequential assumption gets wrong
+    nvme_rand_qd1_read_mbps: Optional[float] = None   # what cold-expert / KV-spill streaming math keys off
+    method: Optional[str] = None                       # how it was measured (provenance summary)
+    details: Optional[dict] = None                     # structured provenance: buffer sizes, fs, samples, flags
+
+
+@dataclass
+class MemoryInfo:
+    ram_total_gib: Optional[float] = None
+    ram_available_gib: Optional[float] = None
+    pinnable_ceiling_gib: Optional[float] = None       # WSL2 limits this (docker-knowledge container-runtime)
+    pinnable_method: Optional[str] = None              # how the ceiling was probed (provenance)
+    pinnable_capped: Optional[bool] = None             # True => probe hit its max; ceiling is a lower bound
+    cpu_mem_bw_gbps: Optional[float] = None            # measured CPU RAM bandwidth — the MoE-offload throughput input
+    cpu_mem_bw_method: Optional[str] = None            # how it was measured (provenance)
+
+
+@dataclass
+class HardwareProfile:
+    gpu: GpuInfo
+    platform: PlatformInfo
+    bandwidth: BandwidthInfo = field(default_factory=lambda: BandwidthInfo())
+    memory: MemoryInfo = field(default_factory=lambda: MemoryInfo())
+
+
+@dataclass
+class ExpertInfo:
+    is_moe: bool = False
+    num_experts: Optional[int] = None
+    experts_per_token: Optional[int] = None     # top-k
+    shared_params: Optional[int] = None
+    expert_params_each: Optional[int] = None
+
+
+@dataclass
+class ModelProfile:
+    name: str
+    architecture: str = "unknown"               # "dense" | "moe" | "unknown"
+    total_params: Optional[int] = None
+    n_layers: Optional[int] = None
+    n_kv_heads: Optional[int] = None
+    head_dim: Optional[int] = None
+    dtype_bytes: float = 2.0                     # fp16/bf16 default
+    quant: Optional[str] = None                  # "gguf-q4_k_m" | "gptq" | "awq" | "fp8" | None
+    expert: ExpertInfo = field(default_factory=ExpertInfo)
+    kv_bytes_per_token: Optional[int] = None     # closed-form; see model.kv_bytes_per_token()
+    # Closed-form param split (model.analyze_config) — the planner's placement math keys off these.
+    # `expert_params_total` is the part `--n-cpu-moe` can move to CPU; `non_expert_params` (attention,
+    # router, embeddings, head, shared experts, dense layers) ALWAYS stays on the GPU.
+    expert_params_total: Optional[int] = None
+    non_expert_params: Optional[int] = None
+    n_moe_layers: Optional[int] = None           # layers that actually carry routed experts
+
+    def kv_bytes_at(self, context_tokens: int, batch: int = 1) -> Optional[int]:
+        """KV-cache bytes at a given context — linear in context (docker-knowledge throughput-prediction)."""
+        if self.kv_bytes_per_token is None:
+            return None
+        return self.kv_bytes_per_token * context_tokens * batch
+
+
+@dataclass
+class Profile:
+    schema_version: str
+    created: str                                 # ISO date, passed in (workflows/runners have no clock)
+    hardware: HardwareProfile
+    model: Optional[ModelProfile] = None
+    notes: List[str] = field(default_factory=list)
+
+    # --- serialization -------------------------------------------------------
+    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) -> "Profile":
+        return _build(cls, d)
+
+    @classmethod
+    def from_json(cls, s: str) -> "Profile":
+        return cls.from_dict(json.loads(s))
+
+
+@dataclass
+class PlacementPlan:
+    """The planner's output: how to place an MoE model across VRAM/RAM for a runtime, with a
+    predicted memory map + throughput and an honest ship/refuse verdict (>1 tok/s floor)."""
+    fits: bool
+    verdict: str                                 # "ship" | "refuse"
+    runtime: str = "llama.cpp"
+    n_cpu_moe: Optional[int] = None              # the --n-cpu-moe value (MoE layers whose experts -> CPU RAM)
+    n_moe_layers: Optional[int] = None
+    llama_flags: Optional[str] = None            # the exact flag string to launch with
+    vram_budget_mib: Optional[float] = None
+    vram_used_mib: Optional[float] = None
+    ram_used_mib: Optional[float] = None         # CPU-resident expert bytes (regular host RAM)
+    predicted_decode_tok_s: Optional[float] = None   # the CALIBRATED forecast (== ceiling when uncalibrated)
+    ceiling_decode_tok_s: Optional[float] = None     # the roofline upper bound (real decode is a fraction of it)
+    predicted_band_low_tok_s: Optional[float] = None   # calibrated band low (None when uncalibrated)
+    predicted_band_high_tok_s: Optional[float] = None  # calibrated band high
+    throughput_basis: Optional[str] = None       # "in-VRAM (±10%)" | "cpu-offload estimate — confirmed by receipt"
+    calibration_basis: Optional[str] = None      # how the forecast was derived (calibrated vs raw ceiling)
+    calibration_n_samples: Optional[int] = None  # receipts informing the forecast (None/0 = uncalibrated)
+    floor_tok_s: float = 1.0
+    message: Optional[str] = None                # plan summary / contrastive refusal frame
+    assumptions: Optional[dict] = None           # cpu_mem_bw_gbps, vram_bw_gbps, bpw, ctx, overhead_mib
+
+    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) -> "PlacementPlan":
+        return _build(cls, d)
+
+    @classmethod
+    def from_json(cls, s: str) -> "PlacementPlan":
+        return cls.from_dict(json.loads(s))
+
+
+@dataclass
+class Receipt:
+    """The measured proof — a DIFFERENT mechanism (measurement) verifying the planner's forecast."""
+    runtime: str = "llama.cpp"
+    n_cpu_moe: Optional[int] = None
+    measured_decode_tok_s: Optional[float] = None
+    measured_prefill_tok_s: Optional[float] = None
+    measured_vram_used_mib: Optional[float] = None
+    predicted_decode_tok_s: Optional[float] = None    # the plan's CALIBRATED forecast
+    ceiling_decode_tok_s: Optional[float] = None      # the plan's roofline upper bound
+    decode_error_pct: Optional[float] = None     # 100*(measured-predicted)/predicted vs the calibrated forecast
+    realized_efficiency_pct: Optional[float] = None   # 100*measured/ceiling — the calibration seed
+    within_band: Optional[bool] = None           # did measured land inside the calibrated band? (the proof)
+    cleared_floor: Optional[bool] = None
+    # Optional per-expert routing de-risk (set when the receipt is built with --trace; activation.py gate):
+    routing_cache_helps: Optional[bool] = None        # would a hot-expert cache help THIS workload?
+    routing_hot_frac_for_coverage: Optional[float] = None  # fraction of experts for the routing-coverage target
+    routing_concentration: Optional[float] = None     # 1 - normalized entropy (0 uniform, 1 peaked)
+    # Optional safety envelope (set when the receipt is built with --peaks from a supervised run; watchdog.py):
+    peak_gpu_power_pct: Optional[float] = None         # worst GPU power draw % observed during the run
+    peak_gpu_temp_c: Optional[float] = None
+    peak_gpu_vram_used_mib: Optional[float] = None
+    peak_host_mem_pct: Optional[float] = None          # THE incident metric — worst host memory % during the run
+    min_host_avail_mib: Optional[float] = None         # lowest free host RAM seen
+    safety_samples: Optional[int] = None               # how many watchdog polls backed the envelope
+    stayed_within_envelope: Optional[bool] = None      # True => no watchdog abort fired across the run
+    method: Optional[str] = None                 # how it was measured (provenance)
+    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 _build(dc_type: Any, value: Any) -> Any:
+    """Recursively reconstruct a (possibly nested) dataclass from plain dicts.
+
+    Tolerant: ignores unknown keys and leaves missing fields at their defaults, so an
+    older profile.json still loads against a newer schema.
+    """
+    if not is_dataclass(dc_type) or value is None:
+        return value
+    kwargs = {}
+    type_by_name = {f.name: f.type for f in fields(dc_type)}
+    known = set(type_by_name)
+    for k, v in value.items():
+        if k not in known:
+            continue
+        ftype = type_by_name[k]
+        # nested dataclass fields are referenced by their global type here
+        nested = _GLOBALS.get(_strip_optional(ftype))
+        kwargs[k] = _build(nested, v) if (nested and isinstance(v, dict)) else v
+    return dc_type(**kwargs)
+
+
+def _strip_optional(t: Any) -> str:
+    """Best-effort: map a field's type annotation to a bare dataclass name for nesting."""
+    s = t if isinstance(t, str) else getattr(t, "__name__", str(t))
+    # annotations may arrive as "Optional[ExpertInfo]" / "ExpertInfo" depending on import style
+    for name in _GLOBALS:
+        if name in s:
+            return name
+    return s
+
+
+_GLOBALS = {
+    "GpuInfo": GpuInfo, "PlatformInfo": PlatformInfo, "BandwidthInfo": BandwidthInfo,
+    "MemoryInfo": MemoryInfo, "HardwareProfile": HardwareProfile, "ExpertInfo": ExpertInfo,
+    "ModelProfile": ModelProfile,
+}