modelspec-dev 0.1.0__py3-none-any.whl

pipeline/hardware.py

@@ -0,0 +1,434 @@
+"""Compute which models fit on which devices, and how fast they would decode.
+
+Everything here is *computed*, never measured, and is labelled as such all the
+way to the page. A predicted figure presented as a measurement is a lie a reader
+will plan around.
+
+Decode speed for a mixture-of-experts model depends on *active* parameters, not
+total. With no active-parameter data the prediction uses total, which understates
+MoE speed — sometimes by a large factor. Every prediction says so.
+
+Max context is leftover memory after weights and the working allowance, divided
+by the KV-cache bytes per token. That needs layer and head geometry
+(`num_layers`, `num_kv_heads` or `num_attention_heads`, `hidden_size`). The
+schema has no `head_dim`; it is derived as `hidden_size / num_attention_heads`.
+When any of that is missing, `max_context_at_quant` is null — never zero, never
+a guess — and `max_context_missing_geometry` is true so a consumer can tell
+"we do not know" from "it does not fit".
+
+`FITS_ON` is only computed for open-weights models. Asking whether a
+closed-weights model "fits" on your GPU is meaningless — you cannot obtain it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from schema.enums import DeviceClass, ModelType
+from schema.graph import CollectingSink
+
+#: model_type values that autoregressively decode tokens, so a tok/s figure is
+#: a meaningful prediction. Everything else (embeddings, rerankers, safety
+#: classifiers, generation of another modality, OCR, reward models, and the
+#: perception/encoder/time-series types) still gets a capacity FITS_ON answer
+#: — the weights either fit in memory or they don't — but never a decode
+#: speed, because there is no token being decoded. A card with no model_type
+#: is treated the same as a non-token type: absence is not a guess that it
+#: chats. Single source of truth for this distinction — do not scatter
+#: per-type checks elsewhere.
+TOKEN_GENERATING_MODEL_TYPES: frozenset[ModelType] = frozenset({
+    ModelType.LLM_CHAT, ModelType.LLM_REASONING, ModelType.LLM_CODE, ModelType.LLM_BASE,
+    ModelType.VLM, ModelType.MEDICAL, ModelType.LEGAL, ModelType.FINANCIAL,
+    ModelType.AGENT_MODEL, ModelType.ROUTER,
+    ModelType.ADAPTER, ModelType.QUANTIZED_VARIANT, ModelType.DISTILLED, ModelType.MERGED,
+})
+
+
+def is_token_generating(model_type: Any) -> bool:
+    """Whether `model_type` decodes tokens and so gets a decode-speed prediction.
+
+    Accepts the raw `Identity.model_type` (a `ModelType | None`, possibly
+    already a plain string in code that reads snapshots rather than cards).
+    """
+    if model_type is None:
+        return False
+    if isinstance(model_type, ModelType):
+        return model_type in TOKEN_GENERATING_MODEL_TYPES
+    return str(model_type) in {t.value for t in TOKEN_GENERATING_MODEL_TYPES}
+
+
+#: Bytes per parameter at each quantisation, best case. Real files carry
+#: metadata and some layers stay at higher precision, which the working
+#: allowance below absorbs.
+QUANT_BYTES: dict[str, float] = {
+    "fp16": 2.0, "bf16": 2.0, "fp8": 1.0, "int8": 1.0,
+    "q6": 0.75, "q5": 0.625, "int4": 0.5, "q4": 0.5,
+}
+
+#: Preference order when choosing the best quantisation that fits. Higher
+#: precision first: we want the best quality that fits, not the smallest.
+QUANT_PREFERENCE = ("bf16", "fp16", "fp8", "int8", "q6", "q5", "q4")
+
+#: Headroom for activations, the framework and the OS, as a fraction of device
+#: memory. KV-cache size is computed from layer geometry when the card has it;
+#: this allowance is the rest of the working set, not a stand-in for the cache.
+WORKING_ALLOWANCE = 0.25
+
+#: Bytes per KV-cache element. The cache is commonly kept at fp16 even when the
+#: weights are quantised; using QUANT_BYTES for the weight quant would understate
+#: the cache (and overstate how much context fits) at q4/int8.
+KV_BYTES_PER_ELEMENT = 2.0
+
+#: Real bandwidth utilisation. No decoder achieves the theoretical roofline;
+#: measured llama.cpp and vLLM figures typically land in the 60-80% band.
+BANDWIDTH_EFFICIENCY = 0.70
+
+
+@dataclass(frozen=True)
+class Device:
+    id: str
+    display_name: str
+    vendor: str
+    device_class: str
+    bandwidth_gb_s: float
+    capacity_options_gb: tuple[float, ...]
+    precisions_native: tuple[str, ...]
+    unified: bool
+    single_device_fit: bool = True
+    single_device_fit_reason: str | None = None
+
+    @property
+    def max_capacity_gb(self) -> float:
+        return max(self.capacity_options_gb)
+
+
+def _single_device_fit(raw: dict[str, Any], path: Path) -> tuple[bool, str | None]:
+    """DATA flag: false means this part must not answer single-device FITS_ON.
+
+    Default is true (omit the field). false requires a non-empty reason so a
+    reader can see why the layer refused rather than guessing from the device id.
+    """
+    if "single_device_fit" not in raw:
+        return True, None
+    flag = raw["single_device_fit"]
+    if flag is True:
+        reason = raw.get("single_device_fit_reason")
+        if reason is None:
+            return True, None
+        if not isinstance(reason, str) or not reason.strip():
+            raise ValueError(
+                f"{path.name}: single_device_fit_reason must be a non-empty string when present"
+            )
+        return True, reason.strip()
+    if flag is False:
+        reason = raw.get("single_device_fit_reason")
+        if not isinstance(reason, str) or not reason.strip():
+            raise ValueError(
+                f"{path.name}: single_device_fit is false but single_device_fit_reason "
+                "is missing. A part that cannot answer single-device fit must say why."
+            )
+        return False, reason.strip()
+    raise ValueError(
+        f"{path.name}: single_device_fit must be true or false, not {flag!r}"
+    )
+
+
+def _device_class(raw: dict[str, Any], path: Path) -> str:
+    """The record's `device_class`, checked against the vocabulary (MODEL-76).
+
+    The graph groups Hardware nodes by this value, so `datacenter` or `Consumer`
+    would not be a near miss — it would be a sixth class that every query for
+    the real one silently skips. Rejected at load, where the file name is still
+    in hand to name in the error.
+    """
+    value = raw.get("device_class")
+    try:
+        return DeviceClass(value).value
+    except ValueError:
+        allowed = ", ".join(c.value for c in DeviceClass)
+        raise ValueError(
+            f"{path.name}: device_class {value!r} is not one of {allowed}"
+        ) from None
+
+
+@dataclass(frozen=True)
+class MaxContext:
+    """Predicted context length at one (device, quant) pair.
+
+    `tokens` is null only when geometry is missing. Zero means the weights fit
+    but leftover memory cannot hold a single token of KV — that is not the
+    same as "we do not know".
+    """
+    tokens: int | None
+    bound_by: str | None
+    missing_geometry: bool
+    kv_heads_from_attention: bool
+
+
+def load_devices(root: Path) -> list[Device]:
+    """Read hardware/*.yaml. A device without bandwidth is rejected, not defaulted."""
+    out: list[Device] = []
+    for path in sorted((root / "hardware").glob("*.yaml")):
+        if path.name.startswith("_"):
+            continue
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        memory = raw["memory"]
+        bandwidth = memory.get("bandwidth_gb_s")
+        if not bandwidth:
+            raise ValueError(
+                f"{path.name}: no memory.bandwidth_gb_s. A device without bandwidth "
+                "cannot answer how fast a model will run, which is the question this "
+                "layer exists to answer. Fix the definition or remove it."
+            )
+        options = memory.get("capacity_options_gb") or [memory["capacity_gb"]]
+        fit, fit_reason = _single_device_fit(raw, path)
+        out.append(Device(
+            id=raw["id"], display_name=raw["display_name"], vendor=raw["vendor"],
+            device_class=_device_class(raw, path), bandwidth_gb_s=float(bandwidth),
+            capacity_options_gb=tuple(float(c) for c in options),
+            precisions_native=tuple(raw.get("precisions_native") or []),
+            unified=bool(memory.get("unified_with_host")),
+            single_device_fit=fit,
+            single_device_fit_reason=fit_reason,
+        ))
+    return out
+
+
+def device_classes(devices: list[Device]) -> dict[str, str]:
+    """Device id → `DeviceClass` value, for the graph derivation (MODEL-76).
+
+    `schema.graph` sits below this loader and cannot read `hardware/*.yaml`
+    itself, so it takes this mapping and stamps the class onto the Hardware
+    nodes a card's deployment profiles produce. One source of truth for the
+    class, whether the graph is being exported as JSON or ingested into
+    FalkorDB.
+    """
+    return {device.id: device.device_class for device in devices}
+
+
+def weights_gb(params: float, quant: str) -> float:
+    return params * QUANT_BYTES[quant] / 1e9
+
+
+def fitting_quants(params: float, capacity_gb: float) -> list[str]:
+    """Every quantisation whose weights fit in the usable memory, best quality first.
+
+    A quantisation the silicon does not accelerate natively is still allowed — it
+    runs, just without the speed benefit — so this gates on memory, not on
+    `precisions_native`. That field informs the prediction, not the fit.
+    """
+    usable = capacity_gb * (1.0 - WORKING_ALLOWANCE)
+    return [q for q in QUANT_PREFERENCE if weights_gb(params, q) <= usable]
+
+
+def best_quant(params: float, capacity_gb: float, native: tuple[str, ...] = ()) -> str | None:
+    """The highest-quality quantisation that fits, or None."""
+    quants = fitting_quants(params, capacity_gb)
+    return quants[0] if quants else None
+
+
+def predicted_decode_tps(bandwidth_gb_s: float, params: float, quant: str) -> float:
+    """Roofline estimate: bandwidth divided by the bytes read per token.
+
+    `params` must be the parameters actually *read* to emit a token, which for a
+    mixture-of-experts model is its active count, not its total. The difference
+    is not marginal: qwen3-coder-next holds 480B and activates 3.2B, a factor of
+    148. Using total parameters there understates its speed by that factor and
+    makes the architecture built for speed look like the worst local choice.
+    """
+    per_token_gb = weights_gb(params, quant)
+    if per_token_gb <= 0:
+        return 0.0
+    return round(bandwidth_gb_s * BANDWIDTH_EFFICIENCY / per_token_gb, 1)
+
+
+def _kv_geometry(card: Any) -> tuple[float, bool] | None:
+    """(bytes_per_token, kv_heads_taken_from_attention) or None.
+
+    Never infers missing layer counts or hidden size. Absent `num_kv_heads` is
+    MHA, so it falls back to `num_attention_heads` and reports that it did.
+    """
+    arch = card.architecture
+    layers = arch.num_layers
+    attn = arch.num_attention_heads
+    kv = arch.num_kv_heads
+    hidden = arch.hidden_size
+
+    if not layers or layers <= 0:
+        return None
+
+    from_attention = kv is None
+    heads = attn if from_attention else kv
+    if not heads or heads <= 0:
+        return None
+
+    # Schema has no head_dim. For MHA/GQA it is hidden_size / num_attention_heads.
+    if not attn or attn <= 0 or not hidden or hidden <= 0:
+        return None
+    if hidden % attn != 0:
+        return None
+    head_dim = hidden // attn
+    if head_dim <= 0:
+        return None
+
+    bytes_per_token = 2 * layers * heads * head_dim * KV_BYTES_PER_ELEMENT
+    return float(bytes_per_token), from_attention
+
+
+def kv_bytes_per_token(card: Any) -> float | None:
+    """KV-cache bytes per token at KV_BYTES_PER_ELEMENT, or None if geometry is missing.
+
+    Independent of weight quantisation: the cache stays at fp16 even when the
+    weights are q4. GQA/MQA use `num_kv_heads`, not `num_attention_heads`.
+    """
+    geo = _kv_geometry(card)
+    return None if geo is None else geo[0]
+
+
+def predicted_max_context(card: Any, capacity_gb: float, quant: str) -> MaxContext:
+    """How many tokens of context the leftover memory can hold at `quant`.
+
+    `(device_memory - weights - working_allowance) / kv_bytes_per_token`, then
+    clamped to the model's own `context_window`. The clamp, not the raw device
+    figure, is what a reader can actually use.
+    """
+    geo = _kv_geometry(card)
+    if geo is None:
+        return MaxContext(
+            tokens=None,
+            bound_by=None,
+            missing_geometry=True,
+            kv_heads_from_attention=False,
+        )
+    kv_bpt, from_attn = geo
+    params = card.architecture.total_parameters
+    device_memory_bytes = capacity_gb * 1e9
+    weight_bytes = weights_gb(params, quant) * 1e9
+    working_allowance_bytes = device_memory_bytes * WORKING_ALLOWANCE
+    available = device_memory_bytes - weight_bytes - working_allowance_bytes
+    device_tokens = 0 if available <= 0 else int(available / kv_bpt)
+    window = card.modalities.text.context_window
+    if window and window > 0 and device_tokens >= window:
+        return MaxContext(
+            tokens=int(window),
+            bound_by="model",
+            missing_geometry=False,
+            kv_heads_from_attention=from_attn,
+        )
+    return MaxContext(
+        tokens=device_tokens,
+        bound_by="device",
+        missing_geometry=False,
+        kv_heads_from_attention=from_attn,
+    )
+
+
+def compute(sink: CollectingSink, cards: list[Any], devices: list[Device]) -> dict[str, Any]:
+    """Add Hardware nodes and FITS_ON edges. Returns counts for the summary."""
+    for device in devices:
+        sink.node("Hardware", "id", device.id, {
+            "id": device.id,
+            "display_name": device.display_name,
+            "vendor": device.vendor,
+            "device_class": device.device_class,
+            "memory_bandwidth_gb_s": device.bandwidth_gb_s,
+            "memory_gb": device.max_capacity_gb,
+            "memory_options_gb": ",".join(str(c) for c in device.capacity_options_gb),
+            "unified_memory": device.unified,
+        })
+
+    considered = fitted = skipped_closed = skipped_no_params = 0
+    edges = edges_with_max_context = 0
+    decode_predictions_omitted = 0
+
+    used_active = 0
+    for card in cards:
+        params = card.architecture.total_parameters
+        # Capacity and speed read different numbers. Every weight must be
+        # resident, so `fits` uses the total; only the active experts are read
+        # per token, so the decode prediction uses the active count.
+        active = card.architecture.active_parameters or params
+        if not card.licensing.open_weights:
+            skipped_closed += 1
+            continue
+        if not params:
+            skipped_no_params += 1
+            continue
+        considered += 1
+        is_moe = bool(card.architecture.num_experts)
+        has_active = bool(card.architecture.active_parameters)
+        if has_active:
+            used_active += 1
+        fitted_any = False
+        # Whether the weights fit is meaningful for every open-weights model.
+        # Decode tok/s is only meaningful for a model that decodes tokens.
+        decode_eligible = is_token_generating(card.identity.model_type)
+
+        for device in devices:
+            if not device.single_device_fit:
+                continue
+            capacity = device.max_capacity_gb
+            quants = fitting_quants(params, capacity)
+            if not quants:
+                continue
+            fitted_any = True
+            edges += 1
+            # Report the range, not a single "best". Highest quality that fits and
+            # smallest that fits answer different questions, and quoting only the
+            # first makes a large slow machine look worse than a small fast one
+            # purely because it chose a heavier quantisation.
+            best, smallest = quants[0], quants[-1]
+            ctx = predicted_max_context(card, capacity, best)
+            if ctx.tokens is not None:
+                edges_with_max_context += 1
+            if not decode_eligible:
+                decode_predictions_omitted += 1
+            # Store unrounded GB. Rounding to 2 decimals collapsed 616k-param
+            # bf16 weights to 0.0, which the page then printed as "0.0 GB".
+            sink.edge("Model", card.identity.model_id, "FITS_ON", "Hardware", device.id, {
+                "quantization": best,
+                "weights_gb": weights_gb(params, best),
+                "device_memory_gb": capacity,
+                "predicted_decode_tps": predicted_decode_tps(
+                    device.bandwidth_gb_s, active, best) if decode_eligible else None,
+                "decode_reads_params": active if decode_eligible else None,
+                "fastest_quantization": smallest,
+                "fastest_weights_gb": weights_gb(params, smallest),
+                "fastest_predicted_decode_tps": predicted_decode_tps(
+                    device.bandwidth_gb_s, active, smallest) if decode_eligible else None,
+                "quantizations_that_fit": ",".join(quants),
+                "max_context_at_quant": ctx.tokens,
+                "max_context_bound_by": ctx.bound_by,
+                "max_context_missing_geometry": ctx.missing_geometry,
+                "kv_heads_from_attention_heads": ctx.kv_heads_from_attention,
+                # Everything above is arithmetic, not observation. The page and
+                # the export must never render it as a measurement.
+                "basis": "computed",
+                "assumes_working_allowance": WORKING_ALLOWANCE,
+                "assumes_bandwidth_efficiency": BANDWIDTH_EFFICIENCY,
+                # No card carries active_parameters, so an MoE prediction uses
+                # total parameters and understates its real speed.
+                # Only conservative where the active count is still unknown.
+                "moe_prediction_is_conservative": decode_eligible and is_moe and not has_active,
+            })
+        fitted += 1 if fitted_any else 0
+
+    return {
+        "devices": len(devices),
+        "models_considered": considered,
+        "models_fitting_somewhere": fitted,
+        "skipped_closed_weights": skipped_closed,
+        "skipped_no_parameter_count": skipped_no_params,
+        "skipped_single_device_fit": sum(
+            1 for device in devices if not device.single_device_fit),
+        "edges": edges,
+        "edges_with_max_context": edges_with_max_context,
+        "decode_predictions_omitted": decode_predictions_omitted,
+        "working_allowance": WORKING_ALLOWANCE,
+        "bandwidth_efficiency": BANDWIDTH_EFFICIENCY,
+        "used_active_parameters": used_active,
+    }

pipeline/hosts.py

@@ -0,0 +1,247 @@
+"""The host layer (MODEL-26 phase B): offload-aware fit for a (model, device, host).
+
+A host is the machine around an accelerator (`hosts/*.yaml`, see
+docs/host-layer.md). For a discrete host, weights that do not fit in
+accelerator memory can spill to system RAM. Decode is then bounded by the
+slower pool, so the answer is "fits, slowly", not "does not fit".
+
+Three fit states:
+
+* `accelerator`: `W + A <= C_acc`, today's `fits: true`.
+* `offload`: not `accelerator`, `W + A <= C_acc + C_host`, and the host is not
+  unified. It carries `offload_fraction = (W + A - C_acc) / W`.
+* `does_not_fit`: neither. A unified host has `C_host = 0` by definition, so
+  its fit is two-state.
+
+`W` is weights at the quant, `A = WORKING_ALLOWANCE * C_acc`, and
+`C_host = host RAM - OS_RESERVE_GB`. Host RAM is the profile's
+`capacity_max_gb` unless the caller states what this machine has
+(`--host-ram`).
+
+Everything here is computed, never measured. The offload formula assumes
+layer-split offload with the CPU not compute-bound; see "Known wrong" in
+docs/host-layer.md.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pipeline.hardware import (
+    BANDWIDTH_EFFICIENCY,
+    QUANT_PREFERENCE,
+    WORKING_ALLOWANCE,
+    is_token_generating,
+    predicted_decode_tps,
+    weights_gb,
+)
+
+#: RAM held back for the OS and everything that is not model weights. One
+#: constant, not a per-OS table (Jamie, 2026-09-15). `--host-ram` overrides the
+#: RAM figure the reserve is taken from, not the reserve itself.
+OS_RESERVE_GB = 8.0
+
+FIT_ACCELERATOR = "accelerator"
+FIT_OFFLOAD = "offload"
+FIT_NONE = "does_not_fit"
+
+BASIS_ACCELERATOR = "accelerator-roofline"
+BASIS_OFFLOAD = "offload-roofline"
+
+_SECTIONS = {
+    "cpu": {"model", "cores", "threads"},
+    "system_memory": {"type", "channels", "max_speed_mt_s", "capacity_max_gb",
+                      "capacity_options_gb", "bandwidth_gb_s", "bandwidth_derivation"},
+    "pcie": {"cpu_gen", "cpu_lanes_usable", "accelerator_link_gen", "accelerator_link_width"},
+    "storage": {"class", "capacity_options_gb"},
+}
+_TOP = {"id", "display_name", "kind", "unified", "hardware_ref", *_SECTIONS,
+        "field_sources", "figures_are", "notes"}
+
+
+@dataclass(frozen=True)
+class Host:
+    id: str
+    display_name: str
+    kind: str
+    unified: bool
+    hardware_ref: str | None
+    capacity_max_gb: float | None
+    bandwidth_gb_s: float | None
+    raw: dict[str, Any]
+
+
+def _numeric(v: Any) -> bool:
+    if isinstance(v, bool):
+        return False
+    if isinstance(v, (int, float)):
+        return True
+    return isinstance(v, list) and bool(v) and all(_numeric(x) for x in v)
+
+
+def validate(raw: Any, name: str) -> None:
+    """Raise ValueError when a profile breaks hosts/_schema.yaml."""
+    if not isinstance(raw, dict):
+        raise ValueError(f"{name}: a host profile must be a mapping")
+    if set(raw) != _TOP:
+        raise ValueError(f"{name}: top-level keys differ from the schema: {sorted(set(raw) ^ _TOP)}")
+    if raw["kind"] not in {"platform", "system"}:
+        raise ValueError(f"{name}: kind must be platform or system")
+    if not isinstance(raw["unified"], bool):
+        raise ValueError(f"{name}: unified is required and must be a boolean")
+    for section, keys in _SECTIONS.items():
+        if not isinstance(raw[section], dict) or set(raw[section]) != keys:
+            raise ValueError(f"{name}: {section} keys differ from the schema")
+    if raw["unified"] and (raw["system_memory"]["type"] != "unified"
+                           or raw["pcie"]["accelerator_link_gen"] is not None):
+        raise ValueError(f"{name}: a unified host has memory type unified and no accelerator link")
+    sources = raw["field_sources"] or {}
+    numeric = {f"{s}.{k}" for s in _SECTIONS for k, v in raw[s].items() if _numeric(v)}
+    missing = numeric - set(sources)
+    if missing:
+        raise ValueError(f"{name}: unsourced numeric fields {sorted(missing)}")
+
+
+def load_hosts(root: Path) -> list[Host]:
+    """Read and validate hosts/*.yaml. An invalid profile is rejected, not defaulted."""
+    out: list[Host] = []
+    for path in sorted((root / "hosts").glob("*.yaml")):
+        if path.name.startswith("_"):
+            continue
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        validate(raw, path.name)
+        if raw["id"] != path.stem:
+            raise ValueError(f"{path.name}: id {raw['id']!r} does not match the file name")
+        out.append(host_from_raw(raw))
+    return out
+
+
+def host_from_raw(raw: dict[str, Any]) -> Host:
+    mem = raw["system_memory"]
+    return Host(
+        id=raw["id"], display_name=raw["display_name"], kind=raw["kind"],
+        unified=bool(raw["unified"]), hardware_ref=raw.get("hardware_ref"),
+        capacity_max_gb=float(mem["capacity_max_gb"]) if mem.get("capacity_max_gb") else None,
+        bandwidth_gb_s=float(mem["bandwidth_gb_s"]) if mem.get("bandwidth_gb_s") else None,
+        raw=raw,
+    )
+
+
+def host_capacity_gb(host: Host, host_ram_gb: float | None = None) -> float:
+    """`C_host`: host memory available for spilled weights. 0 for a unified host."""
+    if host.unified:
+        return 0.0
+    ram = host_ram_gb if host_ram_gb is not None else host.capacity_max_gb
+    if ram is None:
+        return 0.0
+    return max(0.0, float(ram) - OS_RESERVE_GB)
+
+
+def fit_state(weights: float, accelerator_gb: float, host_gb: float, unified: bool) -> str:
+    need = weights + WORKING_ALLOWANCE * accelerator_gb
+    if need <= accelerator_gb:
+        return FIT_ACCELERATOR
+    if not unified and need <= accelerator_gb + host_gb:
+        return FIT_OFFLOAD
+    return FIT_NONE
+
+
+def offload_fraction(weights: float, accelerator_gb: float) -> float:
+    """`f = (W + A - C_acc) / W`, clamped to [0, 1]. 0 when everything is resident."""
+    if weights <= 0:
+        return 0.0
+    f = (weights + WORKING_ALLOWANCE * accelerator_gb - accelerator_gb) / weights
+    return min(1.0, max(0.0, f))
+
+
+def offload_decode_tps(accelerator_bandwidth: float, host_bandwidth: float,
+                       params: float, quant: str, fraction: float) -> float:
+    """`BANDWIDTH_EFFICIENCY / ((1-f)*P/B_acc + f*P/B_host)`, rounded like the roofline.
+
+    At f = 0 this is exactly `predicted_decode_tps`: the same function answers,
+    so no floating-point path can make the two disagree.
+    """
+    if fraction <= 0:
+        return predicted_decode_tps(accelerator_bandwidth, params, quant)
+    per_token = weights_gb(params, quant)
+    if per_token <= 0:
+        return 0.0
+    seconds = (1 - fraction) * per_token / accelerator_bandwidth + fraction * per_token / host_bandwidth
+    return round(BANDWIDTH_EFFICIENCY / seconds, 1)
+
+
+def assess(*, total_params: float, active_params: float | None, model_type: Any,
+           accelerator_gb: float, accelerator_bandwidth: float,
+           host: Host, host_ram_gb: float | None = None) -> dict[str, Any]:
+    """Fit state and decode prediction for one (model, device, host) triple.
+
+    The quant chosen is the smallest that reaches the best state: for
+    `accelerator` it matches `fastest_quantization`, the figure `fits` carries;
+    for `offload` it spills the least, which is the fastest offload.
+    Decode tps is null for a model that does not decode tokens, and for an
+    offload row whose host has no published bandwidth.
+    """
+    host_gb = host_capacity_gb(host, host_ram_gb)
+    reads = active_params or total_params
+    best: tuple[str, str] | None = None
+    for state in (FIT_ACCELERATOR, FIT_OFFLOAD):
+        ok = [q for q in QUANT_PREFERENCE
+              if fit_state(weights_gb(total_params, q), accelerator_gb, host_gb, host.unified) == state]
+        if ok:
+            best = (state, ok[-1])
+            break
+    if best is None:
+        return {"fit_state": FIT_NONE, "quantization": None, "offload_fraction": None,
+                "predicted_decode_tps": None, "predicted_decode_tps_basis": None}
+    state, quant = best
+    tokens = is_token_generating(model_type)
+    if state == FIT_ACCELERATOR:
+        f = 0.0
+        tps = predicted_decode_tps(accelerator_bandwidth, reads, quant) if tokens else None
+        basis = BASIS_ACCELERATOR
+    else:
+        f = round(offload_fraction(weights_gb(total_params, quant), accelerator_gb), 4)
+        tps = (offload_decode_tps(accelerator_bandwidth, host.bandwidth_gb_s, reads, quant, f)
+               if tokens and host.bandwidth_gb_s else None)
+        basis = BASIS_OFFLOAD
+    return {"fit_state": state, "quantization": quant, "offload_fraction": f,
+            "predicted_decode_tps": tps,
+            "predicted_decode_tps_basis": basis if tps is not None else None}
+
+
+def write_export(api_dir: Path, hosts: list[Host], build_json: dict[str, Any]) -> dict[str, Any]:
+    """Emit `api/hosts.json`: every profile as authored, plus the reserve used."""
+    api_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "build": build_json,
+        "count": len(hosts),
+        "os_reserve_gb": OS_RESERVE_GB,
+        "hosts": [h.raw for h in hosts],
+    }
+    (api_dir / "hosts.json").write_text(
+        json.dumps(payload, indent=1, sort_keys=True, default=str), encoding="utf-8")
+    return {"hosts": len(hosts)}
+
+
+def add_to_graph(sink: Any, hosts: list[Host]) -> int:
+    """`:Host` nodes and `(:Host)-[:HOSTS]->(:Hardware)` for unified hosts only.
+
+    A discrete pairing is a query-time input, not a stored record, so discrete
+    hosts get no node. Not wired into the published graph yet (see
+    docs/graph-ontology.md). Returns the number of HOSTS edges.
+    """
+    edges = 0
+    for host in hosts:
+        if not host.unified:
+            continue
+        sink.node("Host", "id", host.id, {"id": host.id, "display_name": host.display_name,
+                                          "unified": True, "kind": host.kind})
+        if host.hardware_ref:
+            sink.edge("Host", host.id, "HOSTS", "Hardware", host.hardware_ref, {})
+            edges += 1
+    return edges