chipwright 0.2.0__py3-none-any.whl

chipwright/env.py

@@ -0,0 +1,229 @@
+"""Board probe → TargetKey. The thing the resolver matches artifacts against.
+
+On Qualcomm silicon the question that decides everything is *which chip* — specifically the Hexagon
+architecture, the installed QAIRT version, and the SoC. `chipwright doctor` reads those off the board (over
+SSH/ADB) rather than guessing. This mirrors the `qualcomm-env-discovery` skill's `probe-env.sh`, kept
+self-contained here so chipwright-core has no hard dependency on a skill checkout.
+
+Offline (no board reachable) is a first-class state, not an error: resolution can still run against a
+TargetKey the user names by hand (`--target htpv68,qnn2.37`).
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Optional
+
+# soc_id -> (marketing name, Hexagon HTP arch). Extend as boards are added.
+SOC_ID = {
+    498: ("QCS6490 / RB3 Gen2", "v68"),
+    35:  ("QCS6490 (Advantech)", "v68"),
+    30:  ("QCS8250 / RB5", "v66"),
+    57:  ("QCS8550", "v73"),
+    69:  ("QCS8650", "v75"),
+    # QDC fleet soc_ids (verified on-device via `chipwright doctor`):
+    603: ("QCS8550 / kalama", "v73"),
+    660: ("SM8850 / Snapdragon 8 Elite Gen 5", "v81"),
+    # Snapdragon 8 Elite (SM8750) — Hexagon v79, the arch the LLM path reaches over adb. The arch is the
+    # load-bearing fact (it is what fails at load and the resolver's hard axis); the on-device lib-name
+    # fallback in `probe`/`probe_adb` recovers it even if this marketing soc_id drifts across images.
+    618: ("SM8750 / Snapdragon 8 Elite", "v79"),
+}
+
+
+@dataclass(frozen=True)
+class TargetKey:
+    """What an artifact must be compatible with to load on this board."""
+    htp_arch: str                 # e.g. "v68" — the axis that most often fails at load
+    qairt: Optional[str] = None   # on-device QAIRT version, e.g. "2.37.1"
+    soc_id: Optional[int] = None
+    soc_name: Optional[str] = None
+    reachable: bool = False
+    qnn_libs: tuple = field(default_factory=tuple)   # e.g. ("libQnnHtpV68.so",)
+    thermal_c: Optional[float] = None
+    ram_kb: Optional[int] = None    # MemTotal from the board — an LLM bundle's load headroom check
+
+    def __str__(self) -> str:
+        sdk = f", qnn{self.qairt}" if self.qairt else ""
+        soc = f" [{self.soc_name}]" if self.soc_name else ""
+        return f"htp{self.htp_arch}{sdk}{soc}"
+
+    @classmethod
+    def manual(cls, spec: str) -> "TargetKey":
+        """Build from a hand-typed spec like 'htpv68,qnn2.37' — for offline resolution."""
+        arch, qairt = None, None
+        for tok in spec.replace(" ", "").split(","):
+            if tok.startswith("htp"):
+                arch = tok[3:]
+            elif tok.startswith("qnn"):
+                qairt = tok[3:]
+        if not arch:
+            raise ValueError(f"target spec must name an arch, e.g. 'htpv68': got {spec!r}")
+        return cls(htp_arch=arch, qairt=qairt)
+
+
+def _arch_from_libs(libs) -> Optional[str]:
+    """Recover the Hexagon arch from the on-device HTP lib names, or None when it is ambiguous.
+
+    A board carrying one `libQnnHtpV<NN>.so` answers the arch (libQnnHtpV68.so -> v68). We strip any
+    suffix (…Stub, …CalculatorStub) so we never emit a garbage arch like "v68CalculatorStub", and we
+    return None unless *every* HTP arch lib agrees on one version — a board with multiple arch stubs is
+    ambiguous and we must NOT guess. Shared by the SSH probe and the adb probe so the hardened fallback
+    behaves identically on both transports.
+    """
+    found = set()
+    for lib in libs:
+        if lib.startswith("libQnnHtpV"):
+            digits = ""
+            for ch in lib[len("libQnnHtpV"):]:
+                if ch.isdigit():
+                    digits += ch
+                else:
+                    break
+            if digits:
+                found.add("v" + digits)
+    return found.pop() if len(found) == 1 else None
+
+
+def _ssh_opts(pw):
+    return ["sshpass", "-p", pw, "ssh", "-o", "StrictHostKeyChecking=no",
+            "-o", "UserKnownHostsFile=/dev/null", "-o", "ConnectTimeout=15",
+            "-o", "PreferredAuthentications=password", "-o", "PubkeyAuthentication=no"]
+
+
+def probe(host: str, user: str, pw: str, port: int = 22) -> TargetKey:
+    """SSH to a board and read SoC id, Hexagon arch, on-device QNN libs, temperature.
+
+    Returns a TargetKey with reachable=False (and whatever it could read) if the board is down.
+    """
+    dest = f"{user}@{host}"
+    script = (
+        "echo SOC=$(cat /sys/devices/soc0/soc_id 2>/dev/null); "
+        "echo NETRUN=$(command -v qnn-net-run); "
+        "echo LIBS=$(ls /usr/lib/libQnnHtpV*.so 2>/dev/null | xargs -n1 basename 2>/dev/null | tr '\\n' ' '); "
+        # QAIRT version from the device runtime: 'QNN SDK v2.38.0.<build>' -> 2.38.0 (printed to stderr)
+        "echo QAIRT=$(qnn-net-run --version 2>&1 | grep -oE 'v[0-9]+\\.[0-9]+\\.[0-9]+' | head -n 1 | tr -d v); "
+        "echo TEMP=$(cat /sys/class/thermal/thermal_zone0/temp 2>/dev/null)"
+    )
+    try:
+        r = subprocess.run(_ssh_opts(pw) + ["-p", str(port), dest, script],
+                           capture_output=True, text=True, timeout=30)
+    except Exception:
+        return TargetKey(htp_arch="unknown", reachable=False)
+    if r.returncode != 0:
+        return TargetKey(htp_arch="unknown", reachable=False)
+
+    out = dict(line.split("=", 1) for line in r.stdout.strip().splitlines() if "=" in line)
+    soc_id = int(out["SOC"]) if out.get("SOC", "").strip().isdigit() else None
+    soc_name, arch = SOC_ID.get(soc_id, (None, "unknown"))
+    libs = tuple(out.get("LIBS", "").split()) if out.get("LIBS", "").strip() else ()
+    # arch fallback from the on-device lib name (libQnnHtpV68.so -> v68) — only when unambiguous.
+    if arch == "unknown":
+        arch = _arch_from_libs(libs) or arch
+    temp = None
+    if out.get("TEMP", "").strip().isdigit():
+        temp = round(int(out["TEMP"]) / 1000.0, 1)
+    qairt = out.get("QAIRT", "").strip() or None
+    return TargetKey(htp_arch=arch, qairt=qairt, soc_id=soc_id, soc_name=soc_name,
+                     reachable=True, qnn_libs=libs, thermal_c=temp)
+
+
+# --- adb (Android) probe ------------------------------------------------------------------------
+# A Snapdragon *phone*-class target (the LLM path) is reached over `adb`, not SSH. The question is the
+# same — which chip, which arch, which QAIRT — so probe_adb mirrors `probe` and returns the same
+# TargetKey; only the transport (an `adb -s <serial> shell …`) and the extra RAM read differ.
+
+def _adb_base(serial, adb_bin="adb"):
+    return [adb_bin] + (["-s", serial] if serial else [])
+
+
+def probe_adb(serial: Optional[str] = None, adb_bin: str = "adb") -> TargetKey:
+    """adb to a board and read SoC id, Hexagon arch, on-device QNN libs, RAM, temperature.
+
+    The adb parallel of `probe`. Returns a TargetKey with reachable=False (and whatever it could read)
+    if the board is down or `adb` is missing — offline is a first-class state, not an error, exactly as
+    on the SSH path. RAM (`MemTotal`) is read too: an LLM Genie bundle is GBs of context binaries, so the
+    load-headroom number is worth carrying in the key.
+    """
+    script = (
+        "echo SOC=$(cat /sys/devices/soc0/soc_id 2>/dev/null); "
+        "echo NETRUN=$(command -v qnn-net-run); "
+        "echo LIBS=$(ls /usr/lib/libQnnHtpV*.so 2>/dev/null | xargs -n1 basename 2>/dev/null | tr '\\n' ' '); "
+        "echo QAIRT=$(qnn-net-run --version 2>&1 | grep -oE 'v[0-9]+\\.[0-9]+\\.[0-9]+' | head -n 1 | tr -d v); "
+        "echo RAM=$(grep -oE '[0-9]+' /proc/meminfo 2>/dev/null | head -n 1); "
+        "echo TEMP=$(cat /sys/class/thermal/thermal_zone0/temp 2>/dev/null)"
+    )
+    try:
+        r = subprocess.run(_adb_base(serial, adb_bin) + ["shell", script],
+                           capture_output=True, text=True, timeout=30)
+    except Exception:
+        return TargetKey(htp_arch="unknown", reachable=False)
+    if r.returncode != 0:
+        return TargetKey(htp_arch="unknown", reachable=False)
+
+    out = dict(line.split("=", 1) for line in r.stdout.strip().splitlines() if "=" in line)
+    soc_id = int(out["SOC"]) if out.get("SOC", "").strip().isdigit() else None
+    soc_name, arch = SOC_ID.get(soc_id, (None, "unknown"))
+    libs = tuple(out.get("LIBS", "").split()) if out.get("LIBS", "").strip() else ()
+    if arch == "unknown":
+        arch = _arch_from_libs(libs) or arch
+    temp = None
+    if out.get("TEMP", "").strip().isdigit():
+        temp = round(int(out["TEMP"]) / 1000.0, 1)
+    ram_kb = int(out["RAM"]) if out.get("RAM", "").strip().isdigit() else None
+    qairt = out.get("QAIRT", "").strip() or None
+    return TargetKey(htp_arch=arch, qairt=qairt, soc_id=soc_id, soc_name=soc_name,
+                     reachable=True, qnn_libs=libs, thermal_c=temp, ram_kb=ram_kb)
+
+
+# --- skel-load capability -----------------------------------------------------------------------
+# Some device images (observed: SM8750/v79 on QDC) block loading the unsigned DSP skel — a trivial
+# backend init dies with "Failed to load skel, error 4000" and the LLM simply cannot run there. This is
+# a *device-capability* fact, not a model fault: we detect it up front and report a clean FAIL (naming
+# the axis) instead of letting a run hang on a backend that will never initialize.
+
+SKEL_ERR_CODE = 4000
+
+
+@dataclass(frozen=True)
+class SkelCheck:
+    """The result of a trivial on-device backend init. `ok=False` => the DSP skel would not load."""
+    ok: bool
+    code: Optional[int] = None     # the error code when it failed (4000 = skel lockdown)
+    reason: str = ""               # a plain, axis-naming sentence
+    raw: str = ""                  # the tail of the init output, for the record
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+# The default trivial init: force the HTP backend (and thus the fastRPC DSP skel) to load. On a locked
+# image this is exactly where "Failed to load skel, error 4000" surfaces, before any model is involved.
+_SKEL_INIT_CMD = ("export ADSP_LIBRARY_PATH=/usr/lib/rfsa/adsp:/usr/lib LD_LIBRARY_PATH=/usr/lib && "
+                  "qnn-net-run --backend /usr/lib/libQnnHtp.so --version 2>&1")
+
+
+def detect_skel_load(shell, init_cmd: str = _SKEL_INIT_CMD, timeout: int = 60) -> SkelCheck:
+    """Run a trivial backend init through `shell` and classify whether the DSP skel loads.
+
+    `shell` is any callable `shell(cmd, timeout=…) -> CompletedProcess` — it duck-types to both
+    `AdbDevice.shell` and the SSH transport, so the same detector serves either board. A
+    `Failed to load skel … 4000` in the output is a device-capability FAIL (named, not a hang); a
+    timeout or an unreachable shell is reported as its own FAIL rather than being swallowed.
+    """
+    try:
+        r = shell(init_cmd, timeout=timeout)
+    except Exception as e:
+        return SkelCheck(ok=False, reason=f"could not run the backend-init probe on the board ({e})")
+    if r is None:
+        return SkelCheck(ok=False, reason="backend-init probe returned no result (board unreachable?)")
+
+    raw = ((getattr(r, "stdout", "") or "") + (getattr(r, "stderr", "") or ""))
+    low = raw.lower()
+    if "failed to load skel" in low or f"error {SKEL_ERR_CODE}" in low or f"0x{SKEL_ERR_CODE:04x}" in low:
+        return SkelCheck(
+            ok=False, code=SKEL_ERR_CODE,
+            reason=("device image blocks loading the DSP skel (Failed to load skel, error 4000) — the "
+                    "LLM cannot run on this board; this is a device-capability FAIL, not a model fault"),
+            raw=raw[-500:])
+    return SkelCheck(ok=True, reason="DSP skel loads; backend initialises", raw=raw[-500:])

chipwright/errors.py

@@ -0,0 +1,41 @@
+"""Typed build errors — the build verb fails by naming the axis, never by a bare traceback.
+
+A build shells out to the QAIRT toolchain, which may be absent (no x86_64-linux host, no SDK) or may
+reject the graph. Each failure mode is a distinct type so the route orchestrator can stop at the right
+stage, set `BuildResult.failed_axis`, and let the CLI print an honest reason — the same name-the-axis
+discipline the resolver uses for a FAIL.
+"""
+from __future__ import annotations
+
+
+class BuildError(Exception):
+    """Base for every typed build failure. `axis` names the stage that stopped the route.
+
+    The specific subclasses fix `axis` at the class level; a bare `BuildError` may name its stage
+    per-instance (e.g. the convert/quantize executors, which have no dedicated subclass)."""
+    axis: str = "build"
+
+    def __init__(self, *args, axis: str = None):
+        super().__init__(*args)
+        if axis is not None:
+            self.axis = axis
+
+
+class PreflightError(BuildError):
+    """A required host tool (qairt-converter / -quantizer / context-binary-generator) is missing."""
+    axis = "preflight"
+
+
+class OpUnsupported(BuildError):
+    """The op-support gate found an op that will not run on the target HTP (before any tool runs)."""
+    axis = "op_support"
+
+
+class ContextGenError(BuildError):
+    """qnn-context-binary-generator failed (e.g. SDK×arch mismatch, VTCM sizing, missing backend .so)."""
+    axis = "context"
+
+
+class FidelityBelowThreshold(BuildError):
+    """The built artifact loaded but missed its cosine / task-metric gate — never published."""
+    axis = "fidelity"

chipwright/llm_reference.py

@@ -0,0 +1,114 @@
+"""The CPU reference decoder — what "correct" means for every LLM run, and the pinned reference.
+
+The Layer-1 tripwire (`verify_llm.py`) needs something to compare the chip against. That something is
+the **same quantized artifact** (the w4a16 ONNX) run greedily on CPU through onnxruntime — the qai-hub
+`onnxruntime_genai` path. Because it is the same quantized model, a token mismatch isolates the
+backend (the chip), not the quantization. This file is the reference the whole gate trusts, so it must
+match the Genie decode semantics exactly: same tokenizer, same chat template, same KV layout, greedy.
+
+**Why it is pinned (FR-L10).** The CPU reference runs on the x86-linux *build host*, not on the host
+that drives the board over adb. So v1 computes the reference greedy tokens/logits **once** and records
+them (with a `sha256`) in the artifact's provenance block; the on-device run compares against that pin
+rather than re-running the CPU reference live over the board transport. `pin_reference` below emits
+that pin and its hash.
+
+The ORT-GenAI model load is validated on hardware later (checkpoint C2). Here the decode-loop
+*structure* is written cleanly, and the pin/hash emit is made unit-testable by injecting the decode fn
+(`decode` parameter) — so the provenance shape can be tested without onnxruntime or a model present.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+
+import numpy as np
+
+
+# --- the greedy decode loop (structure; model load validated on hardware) -------------------------
+
+def greedy_decode(session, tokenizer, prompt_ids, max_new_tokens=64, eos_id=None):
+    """Greedy-decode one prompt through the w4a16 prefill/decode split with KV-cache + host embedding.
+
+    This is the structure of the qai-hub `onnxruntime_genai` path:
+      1. **Prefill** — run the prompt token ids through the prefill graph (seq-N, the VTCM-fitting
+         length the artifact was exported at), seeding the KV-cache. The embedding lookup is done on
+         the host (host embedding) and the hidden states fed in.
+      2. **Decode** — autoregressively run the decode graph one token at a time: pick argmax (greedy,
+         deterministic — sampling OFF so a mismatch is signal, not sampler noise), append to the
+         KV-cache, feed back, until EOS or `max_new_tokens`.
+
+    Returns (tokens, logits): the generated token ids [T] and the per-step next-token logits [T, vocab].
+    `session` is an onnxruntime-genai-style handle exposing `.prefill(ids)->(logits, kv)` and
+    `.decode(token, kv)->(logits, kv)`; it is injected so the loop is testable with a fake.
+    """
+    logits0, kv = session.prefill(prompt_ids)          # [vocab], seeded KV-cache
+    tokens, logits = [], []
+    nxt = int(np.argmax(logits0))                      # greedy: argmax, no sampling
+    for _ in range(max_new_tokens):
+        tokens.append(nxt)
+        if eos_id is not None and nxt == eos_id:       # terminate cleanly on EOS
+            break
+        step_logits, kv = session.decode(nxt, kv)
+        logits.append(np.asarray(step_logits, dtype=np.float64))
+        nxt = int(np.argmax(step_logits))
+    return tokens, (np.stack(logits) if logits else np.zeros((0, 0)))
+
+
+# --- the pinned reference + its hash (provenance; unit-testable with a fake decoder) --------------
+
+def _canonical_bytes(tokens_per_prompt, logits_per_prompt) -> bytes:
+    """Deterministic byte serialization of the reference, so the sha256 is stable across runs/hosts.
+
+    Logits are rounded to float32 and dumped in a fixed, sorted-key JSON envelope; token ids are plain
+    ints. Rounding to float32 keeps the hash reproducible across numpy/BLAS builds that differ only in
+    float64 noise below the precision the chip could ever match.
+    """
+    env = {
+        "tokens": [[int(t) for t in toks] for toks in tokens_per_prompt],
+        "logits": [np.asarray(lg, dtype=np.float32).round(6).tolist() for lg in logits_per_prompt],
+    }
+    return json.dumps(env, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def pin_reference(prompt_set, decode, max_new_tokens=64, eos_id=None) -> dict:
+    """Compute the pinned reference for a fixed prompt set and emit it with its sha256 (FR-L10 / T-L08b).
+
+    `prompt_set` is the fixed list of (already tokenized) prompts. `decode` is the decode function —
+    `greedy_decode` bound to a real session on the build host, or a fake in tests; injecting it makes
+    the pin/hash emit testable without onnxruntime or a model. The returned dict is the provenance
+    payload the record carries: the greedy tokens + per-step logits per prompt and the hash the board
+    compares against.
+
+      {
+        "prompts": <N>,
+        "decode": "greedy",
+        "tokens": [[...], ...],              # per prompt
+        "logits": [<np.ndarray [T, vocab]>, ...],
+        "reference_logits_sha256": "<hex>",  # goes into provenance.reference_logits_sha256
+      }
+    """
+    tokens_per_prompt, logits_per_prompt = [], []
+    for ids in prompt_set:
+        toks, lg = decode(ids, max_new_tokens=max_new_tokens, eos_id=eos_id)
+        tokens_per_prompt.append([int(t) for t in toks])
+        logits_per_prompt.append(np.asarray(lg))
+
+    digest = hashlib.sha256(_canonical_bytes(tokens_per_prompt, logits_per_prompt)).hexdigest()
+    return {
+        "prompts": len(prompt_set),
+        "decode": "greedy",
+        "tokens": tokens_per_prompt,
+        "logits": logits_per_prompt,
+        "reference_logits_sha256": digest,
+    }
+
+
+def verify_pin_hash(pin: dict) -> bool:
+    """Recompute the sha256 from a pin's tokens/logits and check it matches the recorded hash.
+
+    Lets a reader confirm the board compared against the reference the provenance block names — the
+    reproducibility guarantee of rule 5 (the record is reproducible from its provenance block).
+    """
+    expect = pin.get("reference_logits_sha256")
+    actual = hashlib.sha256(_canonical_bytes(pin["tokens"], pin["logits"])).hexdigest()
+    return expect == actual

chipwright/modalities/__init__.py

@@ -0,0 +1,3 @@
+"""Modality runners — the per-task glue (frontend, decoders, CPU reference) that a
+`chipwright-<modality>` package owns. The core calls them through a uniform `run(device, ...)`.
+"""

chipwright/modalities/asr_encoder.py

@@ -0,0 +1,90 @@
+"""ASR streaming-encoder modality runner (a slice of what a `chipwright-asr` package would own).
+
+Runs ONE encoder window two ways on the same input and hands back both outputs for the verifier:
+  - NPU: quantize inputs with the artifact's own I/O scales, execute the w8a16 context binary.
+  - CPU: the float ONNX through ONNX Runtime — the reference.
+
+The streaming encoder takes an audio feature window plus cached state. For a single window the
+state is zero, which sidesteps the quant-layout transposes the per-chunk loop needs — enough to
+prove the Run verb and produce an honest cosine.
+"""
+from __future__ import annotations
+
+import json
+import numpy as np
+
+_NPDT = {"QNN_DATATYPE_UFIXED_POINT_16": np.uint16, "QNN_DATATYPE_INT_32": np.int32,
+         "QNN_DATATYPE_FLOAT_32": np.float32}
+
+
+def _dims(d):
+    return [1 if (isinstance(x, str) or x in (0, None)) else x for x in d]
+
+
+def _load_meta(meta_path):
+    g = json.load(open(meta_path))["info"]["graphs"][0]["info"]
+    def tl(key):
+        out = []
+        for t in g[key]:
+            i = t["info"]; qp = i.get("quantizeParams", {}) or {}
+            so = qp.get("scaleOffset") if isinstance(qp, dict) else None
+            out.append(dict(name=i["name"], dtype=i["dataType"], dims=list(i["dimensions"]),
+                            scale=(so or {}).get("scale"), offset=(so or {}).get("offset")))
+        return out
+    return g["graphName"], tl("graphInputs"), tl("graphOutputs")
+
+
+def _q16(real, scale, offset):
+    return np.clip(np.rint(real / scale) - offset, 0, 65535).astype(np.uint16)
+
+
+def _dq16(q, scale, offset):
+    return (q.astype(np.float32) + offset) * scale
+
+
+def run(device, ctx_board_path, meta_path, cpu_onnx, input_npy, window=39):
+    """Return (npu_out, cpu_out) dicts keyed by 'encoder_out'."""
+    import onnxruntime as ort
+
+    gname, gin, gout = _load_meta(meta_path)
+    imap = {t["name"]: t for t in gin}
+    enc_out_spec = next(t for t in gout if t["name"] == "encoder_out")
+
+    feats = np.load(input_npy).astype(np.float32)             # [frames, 80]
+    if feats.shape[0] < window:
+        feats = np.pad(feats, ((0, window - feats.shape[0]), (0, 0)), constant_values=feats.min())
+    x = feats[:window][None, :, :]                            # [1, 39, 80] (float, onnx layout)
+
+    # ---- CPU reference (float ONNX) --------------------------------------------------------------
+    sess = ort.InferenceSession(cpu_onnx, providers=["CPUExecutionProvider"])
+    cpu_feeds = {"x": x.astype(np.float32)}
+    for i in sess.get_inputs():
+        if i.name == "x":
+            continue
+        shp = _dims(i.shape)
+        cpu_feeds[i.name] = np.zeros(shp, np.float32 if i.type == "tensor(float)" else np.int64)
+    onames = [o.name for o in sess.get_outputs()]
+    cpu_vals = dict(zip(onames, sess.run(None, cpu_feeds)))
+    cpu_out = {"encoder_out": cpu_vals["encoder_out"]}
+
+    # ---- NPU (quantize with the artifact's scales, run the context binary) -----------------------
+    native = {}
+    xi = imap["x"]
+    native["x"] = _q16(np.transpose(x, (0, 2, 1)), xi["scale"], xi["offset"])  # -> [1,80,39]
+    for t in gin:
+        n = t["name"]
+        if n == "x":
+            continue
+        shp = _dims(t["dims"])
+        if t["dtype"] == "QNN_DATATYPE_INT_32":
+            native[n] = np.zeros(shp, np.int32)
+        else:                                                 # zero state -> quantize zeros
+            native[n] = _q16(np.zeros(shp, np.float32), t["scale"], t["offset"])
+    out_shape = tuple(_dims(enc_out_spec["dims"]))
+    raw = device.run(ctx_board_path, native,
+                     [{"name": "encoder_out", "dtype": "uint16", "shape": out_shape}])
+    npu_eo = _dq16(raw["encoder_out"], enc_out_spec["scale"], enc_out_spec["offset"])
+    # align shapes (CPU may be [1,T,512]; NPU dims from meta) for a fair cosine
+    npu_out = {"encoder_out": npu_eo.reshape(cpu_out["encoder_out"].shape)
+               if npu_eo.size == cpu_out["encoder_out"].size else npu_eo}
+    return npu_out, cpu_out

chipwright/modalities/cv.py

@@ -0,0 +1,34 @@
+"""Single-image CV modality runner (first slice of a `chipwright-cv` package).
+
+Works for any model whose input is one preprocessed image tensor and whose output is a single tensor
+— classifier logits, a super-resolved image, a segmentation map, a depth field. Runs it two ways on
+the same input and hands both outputs to the verifier:
+  - NPU: the quantized context binary, float I/O (qnn-net-run quantizes the input and dequantizes the
+    output), so the runner needs no per-tensor scales.
+  - CPU: the float ONNX through ONNX Runtime — the reference.
+
+A single-graph image model is the cheapest clean end-to-end proof: fixed input shape, one output, a
+cosine that directly measures how faithful the quantized graph is to float.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def run(device, ctx_board_path, meta, cpu_onnx, input_npy):
+    """Return (npu_out, cpu_out) dicts keyed by the model's output name. `meta` is unused (float I/O
+    needs no scales); kept for a uniform modality signature."""
+    import onnxruntime as ort
+
+    x = np.load(input_npy).astype(np.float32)        # [1, C, H, W]
+
+    sess = ort.InferenceSession(cpu_onnx, providers=["CPUExecutionProvider"])
+    in_name = sess.get_inputs()[0].name
+    out_names = [o.name for o in sess.get_outputs()]
+    cpu_vals = sess.run(None, {in_name: x})
+    cpu_out = {n: v for n, v in zip(out_names, cpu_vals)}
+
+    specs = [{"name": n, "dtype": "float32", "shape": tuple(cpu_out[n].shape)} for n in out_names]
+    npu = device.run(ctx_board_path, {in_name: x}, specs, native_io=False)
+    npu_out = {n: npu[n].reshape(cpu_out[n].shape) for n in out_names}
+    return npu_out, cpu_out