flashruntime 0.3.0__py3-none-any.whl

flashruntime/planner/catalog.py

@@ -0,0 +1,129 @@
+"""Reference data the estimators consult: known models, GPU classes, links.
+
+Everything here is an *approximation with a source-of-truth elsewhere* —
+model cards, vendor datasheets, measured benchmarks. Values are deliberately
+conservative; the ledger (measured runs) is meant to override them over
+time. Adding an entry is the supported way to extend planner coverage — no
+code changes required.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    """Structural facts about a known transformer, for estimation only."""
+
+    parameters_b: float
+    hidden_size: int
+    num_layers: int
+
+
+# Keys are matched case-insensitively on the trailing path component, so
+# "Qwen/Qwen2.5-7B", "qwen2.5-7b" and "Qwen2.5-7B-Instruct" all resolve.
+# Parameter counts are the published totals (approximate).
+MODEL_CATALOG: dict[str, ModelInfo] = {
+    "qwen2.5-0.5b": ModelInfo(0.49, 896, 24),
+    "qwen2.5-1.5b": ModelInfo(1.54, 1536, 28),
+    "qwen2.5-3b": ModelInfo(3.09, 2048, 36),
+    "qwen2.5-7b": ModelInfo(7.62, 3584, 28),
+    "qwen2.5-14b": ModelInfo(14.7, 5120, 48),
+    "qwen2.5-32b": ModelInfo(32.8, 5120, 64),
+    "qwen2.5-72b": ModelInfo(72.7, 8192, 80),
+    "llama-3.1-8b": ModelInfo(8.03, 4096, 32),
+    "llama-3.1-70b": ModelInfo(70.6, 8192, 80),
+    "llama-3.2-1b": ModelInfo(1.24, 2048, 16),
+    "llama-3.2-3b": ModelInfo(3.21, 3072, 28),
+    "mistral-7b": ModelInfo(7.25, 4096, 32),
+    "gemma-2-9b": ModelInfo(9.24, 3584, 42),
+    "gpt2": ModelInfo(0.124, 768, 12),
+}
+
+
+def lookup_model(name: str) -> ModelInfo | None:
+    """Resolve a model name to catalog info; forgiving about org prefixes
+    and -Instruct/-Chat suffixes."""
+    tail = name.strip().lower().split("/")[-1]
+    for suffix in ("-instruct", "-chat", "-base", "-hf"):
+        tail = tail.removesuffix(suffix)
+    return MODEL_CATALOG.get(tail)
+
+
+def derive_transformer_shape(parameters_b: float) -> tuple[int, int]:
+    """Guess (hidden_size, num_layers) from parameter count when the user
+    gave neither. Dense-transformer typicals; the activation estimate built
+    on this is labeled as derived. [assumption]"""
+    table = [
+        (0.2, (768, 12)),
+        (0.7, (1024, 24)),
+        (2.0, (2048, 24)),
+        (4.0, (3072, 28)),
+        (9.0, (4096, 32)),
+        (16.0, (5120, 40)),
+        (40.0, (6656, 60)),
+        (90.0, (8192, 80)),
+    ]
+    for ceiling, shape in table:
+        if parameters_b <= ceiling:
+            return shape
+    return (12288, 96)
+
+
+@dataclass(frozen=True)
+class GPUInfo:
+    """One GPU class. `bf16_tflops` is a *conservative dense* figure — never
+    the sparsity marketing number."""
+
+    vram_gb: float
+    bf16_tflops: float
+
+
+GPU_CATALOG: dict[str, GPUInfo] = {
+    "h100": GPUInfo(80, 700),
+    "a100-80gb": GPUInfo(80, 312),
+    "a100-40gb": GPUInfo(40, 312),
+    "a100": GPUInfo(40, 312),
+    "l40s": GPUInfo(48, 362),
+    "rtx4090": GPUInfo(24, 165),
+    "rtx3090": GPUInfo(24, 71),
+    "a10": GPUInfo(24, 125),
+    "l4": GPUInfo(24, 121),
+    "v100": GPUInfo(16, 112),
+    "t4": GPUInfo(16, 65),
+}
+
+
+def lookup_gpu(gpu_type: str | None) -> GPUInfo | None:
+    if not gpu_type:
+        return None
+    return GPU_CATALOG.get(gpu_type.strip().lower())
+
+
+# Effective point-to-point bandwidth per interconnect class, GB/s, and a
+# per-collective latency floor in seconds. Conservative effective figures,
+# not line rates. [assumption — FlashNode's network benchmark replaces these
+# with measurements per pool]
+INTERCONNECT_GBPS: dict[str, tuple[float, float]] = {
+    "same_host_nvlink": (250.0, 0.00001),
+    "same_host_pcie": (20.0, 0.00002),
+    "multi_node_ib": (25.0, 0.00005),
+    "multi_node_100g": (10.0, 0.0001),
+    "multi_node_10g": (1.1, 0.0003),
+    "wan": (0.05, 0.03),
+}
+
+# Model-FLOPs-utilization assumed for static throughput estimates.
+# Real MFU varies 0.2–0.5 by model/kernel/stack; 0.30 is a defensible
+# middle. [assumption — profiling replaces this]
+ASSUMED_MFU = 0.30
+
+# Flat per-GPU overhead: CUDA context + NCCL buffers + framework workspace.
+# [assumption]
+FLAT_OVERHEAD_GB = 2.5
+
+# Static-only safety bands (ADR-0003 / evaluation §D): auto-launch below
+# AUTO_OK, require profiling in the band, infeasible above HARD_LIMIT.
+AUTO_OK_FRACTION = 0.80
+HARD_LIMIT_FRACTION = 0.95

flashruntime/planner/comm.py

@@ -0,0 +1,95 @@
+"""Communication feasibility: is the network good enough for this strategy?
+
+First-order per-step traffic model (evaluation §E):
+
+- DDP: one gradient all-reduce per optimizer step. Ring all-reduce moves
+  ≈ 2·(N−1)/N · gradient_bytes per GPU. For PEFT the gradients are only the
+  adapters' — which is why LoRA+DDP tolerates weak links that full
+  fine-tuning cannot.
+- FSDP2/ZeRO-3: per layer, all-gather params (forward), re-gather
+  (backward), reduce-scatter grads ⇒ ≈ 3× sharded-parameter bytes per step
+  in ~3·L latency-sensitive collectives.
+
+Verdict = scaling efficiency E = t_compute / (t_compute + t_exposed_comm),
+with half the compute assumed overlappable. E < REJECT ⇒ infeasible on this
+link; REJECT ≤ E < WARN ⇒ feasible with a warning. Thresholds are starting
+values to be recalibrated from ledger data. [assumption]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from flashruntime.planner.catalog import INTERCONNECT_GBPS
+from flashruntime.planner.resolve import GB
+
+E_REJECT = 0.5
+E_WARN = 0.7
+OVERLAP_FRACTION = 0.5  # fraction of comm hidden under backward compute [assumption]
+
+
+@dataclass(frozen=True)
+class CommVerdict:
+    efficiency: float  # 0..1; 1.0 = no visible communication cost
+    feasible: bool
+    note: str
+
+
+def _link(interconnect: str) -> tuple[float, float]:
+    return INTERCONNECT_GBPS[interconnect]
+
+
+def ddp_efficiency(
+    grad_bytes: float,
+    world: int,
+    interconnect: str,
+    compute_time_per_step_s: float,
+) -> CommVerdict:
+    """Efficiency of DDP's per-step gradient all-reduce on this link."""
+    if world <= 1:
+        return CommVerdict(1.0, True, "single worker — no collective traffic")
+    bw, lat = _link(interconnect)
+    volume = 2.0 * (world - 1) / world * grad_bytes
+    t_comm = volume / (bw * GB) + lat
+    return _verdict(t_comm, compute_time_per_step_s, interconnect, volume)
+
+
+def fsdp_efficiency(
+    param_bytes: float,
+    layers: int,
+    world: int,
+    interconnect: str,
+    compute_time_per_step_s: float,
+) -> CommVerdict:
+    """Efficiency of FSDP2/ZeRO-3 per-layer all-gather + reduce-scatter."""
+    if world <= 1:
+        return CommVerdict(1.0, True, "single worker — no collective traffic")
+    bw, lat = _link(interconnect)
+    volume = 3.0 * param_bytes * (world - 1) / world
+    t_comm = volume / (bw * GB) + 3.0 * layers * lat
+    return _verdict(t_comm, compute_time_per_step_s, interconnect, volume)
+
+
+def _verdict(t_comm: float, t_compute: float, interconnect: str, volume: float) -> CommVerdict:
+    if t_compute <= 0:
+        # No throughput estimate available: fall back to a link-class gate.
+        ok = interconnect not in ("wan",)
+        return CommVerdict(
+            1.0 if ok else 0.0,
+            ok,
+            "no compute-time estimate — verdict from link class only",
+        )
+    exposed = max(0.0, t_comm - OVERLAP_FRACTION * t_compute)
+    e = t_compute / (t_compute + exposed)
+    mb = volume / 1e6
+    if e < E_REJECT:
+        note = (
+            f"scaling efficiency {e:.2f} < {E_REJECT} on {interconnect} "
+            f"({mb:.0f} MB/step) — communication dominates"
+        )
+        return CommVerdict(round(e, 2), False, note)
+    if e < E_WARN:
+        note = f"scaling efficiency {e:.2f} on {interconnect} — workable but wasteful"
+    else:
+        note = f"scaling efficiency {e:.2f} on {interconnect}"
+    return CommVerdict(round(e, 2), True, note)

flashruntime/planner/explain.py

@@ -0,0 +1,109 @@
+"""Render a PlanReport as human-readable text (the CLI's output).
+
+The explanation is half the product: the selected plan with its arithmetic,
+then every other candidate with why it lost, was infeasible, or violated a
+constraint. Nothing is hidden — a user who can audit the rejections trusts
+the selection.
+"""
+
+from __future__ import annotations
+
+from flashruntime.protocol.plan_v1alpha1 import CandidateVerdict, PlanReport, StrategyPlan
+
+_STATUS_LABEL = {
+    "selected": "SELECTED",
+    "feasible": "feasible (not chosen)",
+    "infeasible": "INFEASIBLE",
+    "rejected_policy": "rejected (constraint)",
+    "rejected_dominated": "rejected (dominated)",
+}
+
+
+def render_report(report: PlanReport) -> str:
+    lines: list[str] = []
+    if report.selected is not None:
+        lines.extend(_render_plan(report.selected))
+    else:
+        lines.append("NO VALID STRATEGY")
+        if report.no_valid_strategy_hint:
+            lines.append(f"  hint: {report.no_valid_strategy_hint}")
+    lines.append("")
+    lines.append(f"Candidates evaluated ({len(report.candidates)}):")
+    for c in sorted(report.candidates, key=_candidate_order):
+        lines.extend(_render_candidate(c))
+    if report.warnings:
+        lines.append("")
+        lines.append("Notes:")
+        lines.extend(f"  - {w}" for w in report.warnings)
+    lines.append("")
+    lines.append(f"planner {report.planner_version} · request {report.request_digest} · all estimates static unless labeled")
+    return "\n".join(lines)
+
+
+def _render_plan(p: StrategyPlan) -> list[str]:
+    lines = [
+        f"SELECTED PLAN  {p.plan_id}",
+        f"  mode      : {p.workload_mode}",
+        f"  strategy  : {p.strategy_family}"
+        + (f" + {p.peft}" if p.peft else "")
+        + (f" + {p.quantization} quantization" if p.quantization else ""),
+        f"  topology  : {p.workers} worker(s)"
+        + (f" × {p.gpus_per_worker} GPU" if p.gpus_per_worker else " (CPU)")
+        + (", colocated" if p.colocated and p.workers > 1 else ""),
+        f"  launcher  : {p.launcher}",
+    ]
+    knobs = []
+    if p.precision:
+        knobs.append(f"precision={p.precision}")
+    if p.micro_batch_per_gpu:
+        knobs.append(f"micro_batch={p.micro_batch_per_gpu}")
+    if p.grad_accum:
+        knobs.append(f"grad_accum={p.grad_accum}")
+    if p.activation_checkpointing is not None:
+        knobs.append(f"activation_checkpointing={p.activation_checkpointing}")
+    if p.offload != "none":
+        knobs.append(f"offload={p.offload}")
+    if knobs:
+        lines.append(f"  knobs     : {', '.join(knobs)}")
+    if p.memory:
+        m = p.memory
+        lines.append(
+            f"  memory/GPU: {m.total_gb} GB  (weights {m.weights_gb} + grads {m.gradients_gb} + "
+            f"optimizer {m.optimizer_gb} + activations {m.activations_gb} + transient {m.transient_gb} "
+            f"+ overhead {m.overhead_gb})"
+            + (f"  [+{m.cpu_offload_gb} GB host RAM]" if m.cpu_offload_gb else "")
+        )
+    if p.est_time_min:
+        lines.append(f"  est. time : {p.est_time_min.value:.0f} min  ({p.est_time_min.note})")
+    if p.est_cost_usd:
+        lines.append(f"  est. cost : ${p.est_cost_usd.value:.2f}")
+    if p.scaling_efficiency is not None and p.workers > 1:
+        lines.append(f"  scaling   : {p.scaling_efficiency:.2f} efficiency")
+    if p.checkpoint:
+        lines.append(f"  checkpoint: {p.checkpoint.backend} every {p.checkpoint.interval_seconds}s")
+    if p.profiling_required:
+        lines.append("  ⚠ profiling required before launch (memory estimate inside the caution band)")
+    lines.append("  libraries :")
+    lines.extend(f"    - {ref.name:<28} {ref.role:<10} {ref.purpose}" for ref in p.libraries)
+    lines.append("  because   :")
+    lines.extend(f"    - {r}" for r in p.selected_because)
+    return lines
+
+
+def _render_candidate(c: CandidateVerdict) -> list[str]:
+    head = f"  [{_STATUS_LABEL[c.status]}] {c.name} ({c.workers} worker(s))"
+    if c.memory:
+        head += f" — {c.memory.total_gb} GB/GPU"
+    if c.est_time_min:
+        head += f", ~{c.est_time_min.value:.0f} min"
+    if c.est_cost_usd:
+        head += f", ~${c.est_cost_usd.value:.2f}"
+    lines = [head]
+    if c.status != "selected":  # the winner's reasons already shown in the plan
+        lines.extend(f"      {r}" for r in c.reasons)
+    return lines
+
+
+def _candidate_order(c: CandidateVerdict):
+    order = {"selected": 0, "feasible": 1, "rejected_policy": 2, "rejected_dominated": 3, "infeasible": 4}
+    return (order[c.status], c.workers, c.name)

flashruntime/planner/memory.py

@@ -0,0 +1,166 @@
+"""Static per-GPU memory estimation for training strategies.
+
+The component model (evaluation §D). All figures are *lower bounds by
+construction* plus a flat overhead; the safety bands in `catalog` — not the
+formulas — are what make launch decisions safe. Real memory depends on
+fragmentation, kernel workspace, and framework version; an OOM in a launched
+job is treated as a planner defect and logged as a regression case.
+
+Baseline (mixed-precision AdamW, bytes per parameter):
+  weights 2 (bf16) + gradients 2 + fp32 master 4 + Adam m 4 + Adam v 4 = 16
+— the ZeRO paper's classic 16 bytes/param. PEFT changes *which* parameters
+train: frozen weights keep their 2 (or ~0.55 quantized NF4) bytes, while the
+16-byte training state applies only to the small trainable set. Sharding
+divides state across N GPUs; offloading moves it to host RAM (which must
+also be checked — planners that only check VRAM kill hosts).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from flashruntime.planner.catalog import FLAT_OVERHEAD_GB
+from flashruntime.planner.resolve import GB, ResolvedTransformer
+from flashruntime.protocol.plan_v1alpha1 import MemoryBreakdown, TransformerFineTune
+
+# Bytes per parameter by dtype.
+_BYTES = {"bf16": 2.0, "fp16": 2.0, "fp32": 4.0}
+# NF4 4-bit quantized frozen weights incl. quantization constants. [assumption]
+_QLORA_FROZEN_BYTES = 0.55
+
+# Optimizer-state bytes per *trainable* parameter (fp32 master + moments).
+_OPTIMIZER_BYTES = {
+    "adamw": 12.0,  # 4 master + 4 m + 4 v
+    "adamw_8bit": 6.0,  # 4 master + 1 m + 1 v (bitsandbytes 8-bit) [assumption]
+    "sgd_momentum": 8.0,  # 4 master + 4 momentum
+}
+
+# Activation bytes per (token × hidden) per layer, bf16 + flash-attention era.
+# The single least-predictable constant in this file — pessimistic on
+# purpose; profiling replaces it. [assumption]
+_ACT_BYTES_PER_LAYER = 18.0
+
+
+@dataclass(frozen=True)
+class ShardingConfig:
+    """How a strategy family divides training state across `world` GPUs.
+
+    zero1: optimizer sharded. zero2: + gradients. fsdp2/zero3: + weights
+    (with a transient per-layer all-gather peak). `offload_optimizer` moves
+    optimizer state to host RAM instead.
+    """
+
+    world: int = 1
+    shard_weights: bool = False
+    shard_gradients: bool = False
+    shard_optimizer: bool = False
+    offload_optimizer: bool = False
+
+
+def transformer_memory(
+    w: TransformerFineTune,
+    rt: ResolvedTransformer,
+    sharding: ShardingConfig,
+    activation_checkpointing: bool,
+) -> MemoryBreakdown:
+    """Estimate per-GPU peak memory for one transformer training candidate."""
+    n = max(1, sharding.world)
+    quantized = w.method == "qlora"
+
+    # --- weights -----------------------------------------------------------
+    frozen_bytes = _QLORA_FROZEN_BYTES if quantized else _BYTES[w.precision]
+    if w.method == "full":
+        weights = rt.params * _BYTES[w.precision]
+    else:
+        # frozen base + LoRA adapters at compute precision
+        weights = rt.params * frozen_bytes + rt.trainable_params * _BYTES[w.precision]
+    if sharding.shard_weights:
+        weights /= n
+
+    # --- gradients + optimizer (trainable params only) ---------------------
+    gradients = rt.trainable_params * _BYTES[w.precision]
+    if sharding.shard_gradients:
+        gradients /= n
+    optimizer = rt.trainable_params * _OPTIMIZER_BYTES[w.optimizer]
+    cpu_offload = 0.0
+    if sharding.offload_optimizer:
+        cpu_offload = optimizer / n if sharding.shard_optimizer else optimizer
+        optimizer = 0.0
+    elif sharding.shard_optimizer:
+        optimizer /= n
+
+    # --- activations -------------------------------------------------------
+    # Full: L layers × seq × micro_batch × hidden × const.
+    # With activation checkpointing only layer *inputs* (2 bytes/elem) are
+    # kept plus one live layer's activations; recompute costs ~+30% step
+    # time (charged in timecost). [assumption]
+    tokens = w.seq_len * w.micro_batch_per_gpu
+    per_layer = tokens * rt.hidden * _ACT_BYTES_PER_LAYER
+    if activation_checkpointing:
+        activations = rt.layers * tokens * rt.hidden * 2.0 + per_layer
+    else:
+        activations = rt.layers * per_layer
+
+    # --- transient sharding peak ------------------------------------------
+    # FSDP2/ZeRO-3 re-materialize one layer group's full parameters during
+    # forward/backward all-gather.
+    transient = 0.0
+    if sharding.shard_weights:
+        layer_params = rt.params / rt.layers
+        transient = layer_params * _BYTES[w.precision] * 2.0
+
+    total = weights + gradients + optimizer + activations + transient + FLAT_OVERHEAD_GB * GB
+
+    return MemoryBreakdown(
+        weights_gb=round(weights / GB, 2),
+        gradients_gb=round(gradients / GB, 2),
+        optimizer_gb=round(optimizer / GB, 2),
+        activations_gb=round(activations / GB, 2),
+        transient_gb=round(transient / GB, 2),
+        overhead_gb=FLAT_OVERHEAD_GB,
+        total_gb=round(total / GB, 2),
+        cpu_offload_gb=round(cpu_offload / GB, 2),
+        basis="static",
+    )
+
+
+def generic_training_memory(
+    parameters_m: float,
+    trainable_fraction: float,
+    precision: str,
+    optimizer: str,
+    activation_gb: float,
+    sharding: ShardingConfig,
+) -> MemoryBreakdown:
+    """Same component model for non-transformer PyTorch training, with
+    user-supplied (or pessimistic-default) activation memory."""
+    n = max(1, sharding.world)
+    params = parameters_m * 1e6
+    trainable = params * trainable_fraction
+
+    weights = params * _BYTES[precision]
+    if sharding.shard_weights:
+        weights /= n
+    gradients = trainable * _BYTES[precision]
+    if sharding.shard_gradients:
+        gradients /= n
+    optimizer_b = trainable * _OPTIMIZER_BYTES[optimizer]
+    cpu_offload = 0.0
+    if sharding.offload_optimizer:
+        cpu_offload = optimizer_b / n if sharding.shard_optimizer else optimizer_b
+        optimizer_b = 0.0
+    elif sharding.shard_optimizer:
+        optimizer_b /= n
+
+    total = weights + gradients + optimizer_b + activation_gb * GB + FLAT_OVERHEAD_GB * GB
+    return MemoryBreakdown(
+        weights_gb=round(weights / GB, 2),
+        gradients_gb=round(gradients / GB, 2),
+        optimizer_gb=round(optimizer_b / GB, 2),
+        activations_gb=round(activation_gb, 2),
+        transient_gb=0.0,
+        overhead_gb=FLAT_OVERHEAD_GB,
+        total_gb=round(total / GB, 2),
+        cpu_offload_gb=round(cpu_offload / GB, 2),
+        basis="static",
+    )

flashruntime/planner/resolve.py

@@ -0,0 +1,120 @@
+"""Resolve a PlanRequest into the concrete numbers the estimators need.
+
+Turns "Qwen/Qwen2.5-7B, LoRA r=16, 4×24 GB" into parameter counts, model
+shape, trainable-parameter counts, and per-GPU VRAM — recording which values
+were user-given, catalog-known, or derived, so estimates can say so.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from flashruntime.planner import catalog
+from flashruntime.protocol.plan_v1alpha1 import PlanRequest, Resources, TransformerFineTune
+
+GB = 1e9  # this module talks in GB = 1e9 bytes throughout
+
+
+@dataclass
+class ResolvedTransformer:
+    """A TransformerFineTune with every blank filled in."""
+
+    params: float  # absolute parameter count
+    hidden: int
+    layers: int
+    trainable_params: float  # LoRA adapters, or all params for full FT
+    shape_derived: bool  # True when hidden/layers came from a heuristic
+    notes: list[str] = field(default_factory=list)
+
+
+def resolve_transformer(w: TransformerFineTune) -> ResolvedTransformer:
+    """Fill parameter count and shape from (in priority order) user input,
+    the model catalog, or the size-class heuristic."""
+    notes: list[str] = []
+    info = catalog.lookup_model(w.model)
+
+    if w.parameters_b is not None:
+        params_b = w.parameters_b
+    elif info is not None:
+        params_b = info.parameters_b
+        notes.append(f"parameter count {params_b}B taken from model catalog for '{w.model}'")
+    else:
+        raise ValueError(
+            f"model '{w.model}' is not in the planner catalog — set workload.parameters_b "
+            "(billions of parameters) explicitly"
+        )
+
+    shape_derived = False
+    if w.hidden_size and w.num_layers:
+        hidden, layers = w.hidden_size, w.num_layers
+    elif info is not None:
+        hidden, layers = info.hidden_size, info.num_layers
+    else:
+        hidden, layers = catalog.derive_transformer_shape(params_b)
+        shape_derived = True
+        notes.append(
+            f"model shape derived from size class ({hidden} hidden × {layers} layers) [assumption]"
+        )
+
+    params = params_b * 1e9
+    if w.method == "full":
+        trainable = params
+    else:
+        # LoRA on the four attention projections (q,k,v,o), the common
+        # default: each gets A(h×r)+B(r×h) = 2·h·r params → 8·h·r per layer.
+        # [assumption: adapters on attention only; all-linear LoRA is ~2–3×]
+        trainable = 8.0 * hidden * w.lora_rank * layers
+        notes.append(
+            f"LoRA trainable params ≈ {trainable / 1e6:.1f}M "
+            f"(8·hidden·rank·layers, attention projections) [assumption]"
+        )
+
+    return ResolvedTransformer(
+        params=params,
+        hidden=hidden,
+        layers=layers,
+        trainable_params=trainable,
+        shape_derived=shape_derived,
+        notes=notes,
+    )
+
+
+@dataclass
+class ResolvedGPU:
+    """Per-GPU capability actually used by the estimators."""
+
+    vram_gb: float
+    bf16_tflops: float
+    tflops_known: bool
+    notes: list[str] = field(default_factory=list)
+
+
+def resolve_gpu(r: Resources) -> ResolvedGPU:
+    """VRAM: user value wins, then catalog. Throughput: catalog only —
+    without it, time/cost estimates are skipped rather than invented."""
+    info = catalog.lookup_gpu(r.gpu_type)
+    notes: list[str] = []
+
+    if r.vram_gb is not None:
+        vram = r.vram_gb
+    elif info is not None:
+        vram = info.vram_gb
+        notes.append(f"VRAM {vram} GB taken from GPU catalog for '{r.gpu_type}'")
+    else:
+        raise ValueError(
+            f"unknown GPU type '{r.gpu_type}' — set resources.vram_gb explicitly"
+        )
+
+    if info is not None:
+        return ResolvedGPU(vram, info.bf16_tflops, True, notes)
+    notes.append("GPU throughput unknown — time/cost estimates unavailable")
+    return ResolvedGPU(vram, 0.0, False, notes)
+
+
+def request_digest(req: PlanRequest, planner_version: str) -> str:
+    """Stable content hash over the request + planner version — the identity
+    of a planning decision (same inputs ⇒ same digest ⇒ same plan)."""
+    import hashlib
+
+    payload = req.model_dump_json() + planner_version
+    return hashlib.sha256(payload.encode()).hexdigest()[:16]