chipwright 0.2.1__tar.gz → 0.2.3__tar.gz

{chipwright-0.2.1 → chipwright-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipwright
-Version: 0.2.1
+Version: 0.2.3
 Summary: A verified package manager for Qualcomm NPUs — resolve the artifact that loads on your exact chip, run it, and prove it against a CPU reference.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nameissakthi25/chipwright
@@ -79,10 +79,35 @@ Chipwright closes that gap. Think of it as **PyPI wheel tags for NPUs**: the chi
 
 ## Quickstart
 
+### Offline — no board, in under a minute
+
+```bash
+pip install chipwright
+```
+
+Resolve a hosted model against a hand-named target. No board, no QAIRT SDK on the machine:
+
 ```bash
-pip install -e .
+chipwright --target htpv68 resolve mobilenet-v2
 ```
 
+```text
+model   : mobilenet-v2
+target  : htpv68
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  warning: board QAIRT unknown (offline) — SDK compatibility unverified
+```
+
+That offline-SDK warning is **expected**: with no board to probe, Chipwright confirms the arch/quant/shape match but can't check the exact SDK point, so it says so rather than pretend. Global flags — `--target`, `--registry`, `--quant`, `--shape` — go **before** the subcommand.
+
+The `run` verb and its verification gate need a real board (set `CW_BOARD_HOST` / `CW_BOARD_PASS`, below), and the CV verify demo needs the CPU-reference runner:
+
+```bash
+pip install 'chipwright[cv]'   # onnxruntime + pillow for the ONNX reference
+```
+
+### On a board
+
 Point Chipwright at a board (over SSH) and probe it:
 
 ```bash
@@ -103,32 +128,38 @@ chipwright doctor
 Resolve a model against that exact board — no guessing:
 
 ```bash
-chipwright resolve whisper-small-en
+chipwright resolve mobilenet-v2
 ```
 
 ```text
-model   : whisper-small-en
+model   : mobilenet-v2
 target  : htpv68,qnn2.38
-▲ USE (warn)  whisper-small-en-1.2.0  htpv68/w8a16/win30s
-  warning: artifact tested at qnn2.37.1; board runs 2.38.0 — inside compatible range >=2.34,<2.40
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  warning: board QAIRT 2.38 is in range >=2.34,<2.40 but the artifact was tested at 2.37.1
 ```
 
-Then run it on the board and verify the NPU output against a CPU reference:
+Then run it on the board and verify the NPU output against a CPU reference (the input ships with the variant, so no `--input` is needed):
 
 ```bash
-chipwright run zipformer-enin --input utterance.npy
+chipwright run mobilenet-v2
 ```
 
 ```text
-model   : zipformer-enin
+model   : mobilenet-v2
 target  : htpv68,qnn2.38
-✔ USE    zipformer-enin-7.0.0  htpv68/w8a16/win39  qnn2.37.1  (exact match)
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  pushing artifact to board (mobilenet) …
+  running on NPU + CPU reference …
 
-✔ VERIFIED  NPU vs CPU-reference  cosine_min = 0.98800  (threshold 0.95)
-    encoder: 0.98800
+✔ VERIFIED  NPU vs CPU-reference  cosine_min = 0.95600  (threshold 0.95)
 ```
 
-That `0.98800` is not a claim in a README. It is the number Chipwright measured on a live QCS6490 against an ONNX-Runtime reference, on the input you gave it, this run.
+That `0.95600` is not a claim in a README. It is the number Chipwright measured on a live QCS6490 against an ONNX-Runtime reference, on the input in the variant, this run.
+
+### Targets and registries
+
+- `--target <arch[,sdk]>` — resolve **offline** against a hand-named target instead of a probed board, e.g. `--target htpv68` or `--target htpv68,qnn2.37`. The arch is required; the SDK is optional — omit it and the SDK axis is reported unverified rather than guessed. It is a global flag, so it goes before the subcommand (`chipwright --target htpv68 resolve …`).
+- `CW_REGISTRY` — point the client at an alternate index (a local path or a URL) instead of the public index bundled in the wheel. Use it to resolve/run against a dev or private registry; the author's development overlay is `registry/index.dev.yaml`.
 
 ---
 
@@ -138,7 +169,7 @@ That `0.98800` is not a claim in a README. It is the number Chipwright measured
 | --- | --- |
 | **resolve** | Match a registry variant to your board's target key. If nothing matches, name the axis that failed — never silently downgrade to a near-miss. |
 | **run** | `resolve` → fetch (or locate) the artifact → push and execute on the board → compare the NPU output to a CPU reference and report the cosine. |
-| **build** | Produce the artifact from a recipe when no hosted variant matches your chip — op pre-check, host preflight, convert → quantize → on-board context, then gate on the verification before publishing. |
+| **build** | Produce the artifact from a recipe when no hosted variant matches your chip — op pre-check, host preflight, convert → quantize → on-board context, then gate on the verification before publishing. *(Specified and partial in 0.2.x — see [Status](#status); not yet a working end-to-end verb.)* |
 
 ---
 
@@ -241,7 +272,9 @@ registry/
   | `movenet` | pose estimation (17 keypoints) | w8a16 | **0.916** |
 
   Two input modalities, five CV tasks, two quant profiles — the quant axis is real, and every run ends in a measured number. The gate earns its keep: a random-noise input to MobileNet correctly **FAILs** at 0.776, and a MediaPipe face detector surfaced a genuine w8a8 fidelity loss on its secondary score head (0.80 vs 0.98 elsewhere) — caught, not shipped. The cosine spread is itself the signal: a ViT depth head converts near-perfectly (0.99996), while a pose keypoint+confidence head shows real quant softness (0.916) yet still clears the bar — the number tells you which is which. Getting that Depth-Anything ViT to convert at all needed a recipe adaptation (an unsupported `Reshape allowzero` attribute, patched across 29 nodes) — the honest boundary, handled rather than papered over.
-- ✅ **build** — **verified end-to-end**: `chipwright build mobilenet-cv` on a real x86_64-linux QAIRT host produced a w8a16 DLC (`…+qnn2.34-htpv68-w8a16-img224.dlc`) via `qairt-converter`, and `chipwright run` then verified that *built* artifact on the board — **cosine 0.956**. The full `resolve → build → run → verify` loop. Op pre-check, host preflight, declared graph adaptations, and a fidelity gate before publish are all in; on a machine without QAIRT the CLI says so plainly instead of pretending.
+
+  **What runs on a clean `pip install`:** `mobilenet-v2` is hosted in the bundled public registry — artifact, CPU reference and input all fetched by hash — so `chipwright run mobilenet-v2` works end-to-end on any board out of the box. The other five rows ship their **verification records** in the public index; their artifacts live in the author's development registry (point at it with `CW_REGISTRY`). The records are what the resolver and `list` surface; the artifacts travel separately.
+- ⚠️ **build** — **specified and partial, not yet end-to-end in 0.2.x.** The `build` verb resolves a model, reports host preflight, and loads the recipe, but on a machine without the QAIRT toolchain it stops plainly — e.g. `chipwright build laya-intent` prints `▲ build host not ready — missing: qairt-converter, qairt-quantizer, qnn-context-binary-generator` and exits on the `preflight` axis instead of pretending. The convert → quantize → on-board-context pipeline, op pre-check, declared graph adaptations and the pre-publish fidelity gate are designed and in the recipes, but building a fresh artifact still requires an x86_64-linux QAIRT host and is not wired as a turnkey command yet. `mobilenet-cv-built` in the registry is the record of one artifact produced this way and then verified on the board (cosine 0.956); reproducing that build from a clean checkout is not a one-liner today. What is solid in 0.2.x is **resolve + run + verify**.
 
 **SDK-range in practice:** that same board runs QAIRT **2.38.0** while the artifact was tested at **2.37.1**, both inside the compatible range `>=2.34,<2.40`. It ran correctly — and `resolve` says so plainly (USE-with-warning), rather than pretending the tested point and the board agree.
 
@@ -265,4 +298,4 @@ The specification lives in a separate repo, the **spec kit** (`chipwright-specki
 
 ## License
 
-MIT — see [LICENSE](LICENSE). Contributions welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).
+The Chipwright **framework** is MIT — see [LICENSE](LICENSE). The **models** it resolves and runs carry their own upstream licenses, recorded per entry in the registry index (for example the Qualcomm AI Hub CV models are `bsd-3-clause`, Whisper is `mit`, and the LLMs are `apache-2.0`); the MIT license covers this tool, not the model weights. Contributions welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).

{chipwright-0.2.1 → chipwright-0.2.3}/README.md

@@ -43,10 +43,35 @@ Chipwright closes that gap. Think of it as **PyPI wheel tags for NPUs**: the chi
 
 ## Quickstart
 
+### Offline — no board, in under a minute
+
+```bash
+pip install chipwright
+```
+
+Resolve a hosted model against a hand-named target. No board, no QAIRT SDK on the machine:
+
 ```bash
-pip install -e .
+chipwright --target htpv68 resolve mobilenet-v2
 ```
 
+```text
+model   : mobilenet-v2
+target  : htpv68
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  warning: board QAIRT unknown (offline) — SDK compatibility unverified
+```
+
+That offline-SDK warning is **expected**: with no board to probe, Chipwright confirms the arch/quant/shape match but can't check the exact SDK point, so it says so rather than pretend. Global flags — `--target`, `--registry`, `--quant`, `--shape` — go **before** the subcommand.
+
+The `run` verb and its verification gate need a real board (set `CW_BOARD_HOST` / `CW_BOARD_PASS`, below), and the CV verify demo needs the CPU-reference runner:
+
+```bash
+pip install 'chipwright[cv]'   # onnxruntime + pillow for the ONNX reference
+```
+
+### On a board
+
 Point Chipwright at a board (over SSH) and probe it:
 
 ```bash
@@ -67,32 +92,38 @@ chipwright doctor
 Resolve a model against that exact board — no guessing:
 
 ```bash
-chipwright resolve whisper-small-en
+chipwright resolve mobilenet-v2
 ```
 
 ```text
-model   : whisper-small-en
+model   : mobilenet-v2
 target  : htpv68,qnn2.38
-▲ USE (warn)  whisper-small-en-1.2.0  htpv68/w8a16/win30s
-  warning: artifact tested at qnn2.37.1; board runs 2.38.0 — inside compatible range >=2.34,<2.40
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  warning: board QAIRT 2.38 is in range >=2.34,<2.40 but the artifact was tested at 2.37.1
 ```
 
-Then run it on the board and verify the NPU output against a CPU reference:
+Then run it on the board and verify the NPU output against a CPU reference (the input ships with the variant, so no `--input` is needed):
 
 ```bash
-chipwright run zipformer-enin --input utterance.npy
+chipwright run mobilenet-v2
 ```
 
 ```text
-model   : zipformer-enin
+model   : mobilenet-v2
 target  : htpv68,qnn2.38
-✔ USE    zipformer-enin-7.0.0  htpv68/w8a16/win39  qnn2.37.1  (exact match)
+▲ USE (warn)  mobilenet-v2-1.0.0  htpv68/w8a16/img224
+  pushing artifact to board (mobilenet) …
+  running on NPU + CPU reference …
 
-✔ VERIFIED  NPU vs CPU-reference  cosine_min = 0.98800  (threshold 0.95)
-    encoder: 0.98800
+✔ VERIFIED  NPU vs CPU-reference  cosine_min = 0.95600  (threshold 0.95)
 ```
 
-That `0.98800` is not a claim in a README. It is the number Chipwright measured on a live QCS6490 against an ONNX-Runtime reference, on the input you gave it, this run.
+That `0.95600` is not a claim in a README. It is the number Chipwright measured on a live QCS6490 against an ONNX-Runtime reference, on the input in the variant, this run.
+
+### Targets and registries
+
+- `--target <arch[,sdk]>` — resolve **offline** against a hand-named target instead of a probed board, e.g. `--target htpv68` or `--target htpv68,qnn2.37`. The arch is required; the SDK is optional — omit it and the SDK axis is reported unverified rather than guessed. It is a global flag, so it goes before the subcommand (`chipwright --target htpv68 resolve …`).
+- `CW_REGISTRY` — point the client at an alternate index (a local path or a URL) instead of the public index bundled in the wheel. Use it to resolve/run against a dev or private registry; the author's development overlay is `registry/index.dev.yaml`.
 
 ---
 
@@ -102,7 +133,7 @@ That `0.98800` is not a claim in a README. It is the number Chipwright measured
 | --- | --- |
 | **resolve** | Match a registry variant to your board's target key. If nothing matches, name the axis that failed — never silently downgrade to a near-miss. |
 | **run** | `resolve` → fetch (or locate) the artifact → push and execute on the board → compare the NPU output to a CPU reference and report the cosine. |
-| **build** | Produce the artifact from a recipe when no hosted variant matches your chip — op pre-check, host preflight, convert → quantize → on-board context, then gate on the verification before publishing. |
+| **build** | Produce the artifact from a recipe when no hosted variant matches your chip — op pre-check, host preflight, convert → quantize → on-board context, then gate on the verification before publishing. *(Specified and partial in 0.2.x — see [Status](#status); not yet a working end-to-end verb.)* |
 
 ---
 
@@ -205,7 +236,9 @@ registry/
   | `movenet` | pose estimation (17 keypoints) | w8a16 | **0.916** |
 
   Two input modalities, five CV tasks, two quant profiles — the quant axis is real, and every run ends in a measured number. The gate earns its keep: a random-noise input to MobileNet correctly **FAILs** at 0.776, and a MediaPipe face detector surfaced a genuine w8a8 fidelity loss on its secondary score head (0.80 vs 0.98 elsewhere) — caught, not shipped. The cosine spread is itself the signal: a ViT depth head converts near-perfectly (0.99996), while a pose keypoint+confidence head shows real quant softness (0.916) yet still clears the bar — the number tells you which is which. Getting that Depth-Anything ViT to convert at all needed a recipe adaptation (an unsupported `Reshape allowzero` attribute, patched across 29 nodes) — the honest boundary, handled rather than papered over.
-- ✅ **build** — **verified end-to-end**: `chipwright build mobilenet-cv` on a real x86_64-linux QAIRT host produced a w8a16 DLC (`…+qnn2.34-htpv68-w8a16-img224.dlc`) via `qairt-converter`, and `chipwright run` then verified that *built* artifact on the board — **cosine 0.956**. The full `resolve → build → run → verify` loop. Op pre-check, host preflight, declared graph adaptations, and a fidelity gate before publish are all in; on a machine without QAIRT the CLI says so plainly instead of pretending.
+
+  **What runs on a clean `pip install`:** `mobilenet-v2` is hosted in the bundled public registry — artifact, CPU reference and input all fetched by hash — so `chipwright run mobilenet-v2` works end-to-end on any board out of the box. The other five rows ship their **verification records** in the public index; their artifacts live in the author's development registry (point at it with `CW_REGISTRY`). The records are what the resolver and `list` surface; the artifacts travel separately.
+- ⚠️ **build** — **specified and partial, not yet end-to-end in 0.2.x.** The `build` verb resolves a model, reports host preflight, and loads the recipe, but on a machine without the QAIRT toolchain it stops plainly — e.g. `chipwright build laya-intent` prints `▲ build host not ready — missing: qairt-converter, qairt-quantizer, qnn-context-binary-generator` and exits on the `preflight` axis instead of pretending. The convert → quantize → on-board-context pipeline, op pre-check, declared graph adaptations and the pre-publish fidelity gate are designed and in the recipes, but building a fresh artifact still requires an x86_64-linux QAIRT host and is not wired as a turnkey command yet. `mobilenet-cv-built` in the registry is the record of one artifact produced this way and then verified on the board (cosine 0.956); reproducing that build from a clean checkout is not a one-liner today. What is solid in 0.2.x is **resolve + run + verify**.
 
 **SDK-range in practice:** that same board runs QAIRT **2.38.0** while the artifact was tested at **2.37.1**, both inside the compatible range `>=2.34,<2.40`. It ran correctly — and `resolve` says so plainly (USE-with-warning), rather than pretending the tested point and the board agree.
 
@@ -229,4 +262,4 @@ The specification lives in a separate repo, the **spec kit** (`chipwright-specki
 
 ## License
 
-MIT — see [LICENSE](LICENSE). Contributions welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).
+The Chipwright **framework** is MIT — see [LICENSE](LICENSE). The **models** it resolves and runs carry their own upstream licenses, recorded per entry in the registry index (for example the Qualcomm AI Hub CV models are `bsd-3-clause`, Whisper is `mit`, and the LLMs are `apache-2.0`); the MIT license covers this tool, not the model weights. Contributions welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).

{chipwright-0.2.1 → chipwright-0.2.3}/chipwright/__init__.py

@@ -8,4 +8,4 @@ from .resolver import Decision, Outcome, Variant, resolve
 from .tags import ArtifactTag
 
 __all__ = ["TargetKey", "probe", "Registry", "Decision", "Outcome", "Variant", "resolve", "ArtifactTag"]
-__version__ = "0.2.1"
+__version__ = "0.2.3"

chipwright-0.2.3/chipwright/cache.py

@@ -0,0 +1,111 @@
+"""Content-addressed artifact cache at ~/.cache/chipwright/.
+
+Addressed by sha256 so two models that share a build never store it twice (brief §"The manifest and
+the registry"). Verifies the hash on fetch and on read — a corrupted or truncated download is caught
+here, not at load on the board where the error reads like file corruption.
+
+Hardening (spec 001, "refuse rather than guess", at the fetch boundary): every sha is validated as
+64-hex before it is trusted (a url with no/!bad sha is refused by name, never fetched); a reference's
+filename is confined to its cache dir (a registry-supplied `name` with a separator or `..` cannot write
+outside the cache); and a remote url must be https unless CW_ALLOW_INSECURE=1 (so an http CW_REGISTRY /
+artifact cannot be silently MITM'd — the sha only protects you over a trusted transport).
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import urllib.request
+from urllib.parse import urlparse
+
+CACHE_DIR = os.environ.get("CW_CACHE", os.path.expanduser("~/.cache/chipwright"))
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _require_sha(sha256, what: str = "artifact") -> str:
+    """A fetch target MUST carry a 64-hex sha256. Refuse by name rather than fetch unverified bytes."""
+    if not isinstance(sha256, str) or not _HEX64.match(sha256):
+        raise RuntimeError(
+            f"refusing to fetch an unverified {what}: expected a 64-hex sha256, got {sha256!r}")
+    return sha256
+
+
+def _safe_name(name: str) -> str:
+    """A reference filename must be a plain basename inside its cache dir — no separator, no `..`, not
+    absolute. A registry-supplied name that escapes the cache is refused (it could otherwise land
+    sha-matching bytes at an arbitrary host path during a normal run)."""
+    if (not isinstance(name, str) or name in ("", ".", "..")
+            or os.path.isabs(name) or os.path.basename(name) != name):
+        raise RuntimeError(f"unsafe reference filename {name!r}: must be a plain name with no path separator or '..'")
+    return name
+
+
+def _check_scheme(url: str) -> None:
+    """A remote fetch must be https (the sha pins integrity only over a transport you trust; over http a
+    MITM can serve a matching (url, sha) pair). Local paths pass; opt out with CW_ALLOW_INSECURE=1."""
+    scheme = urlparse(url).scheme.lower()
+    if scheme in ("", "file"):
+        return
+    if scheme != "https" and os.environ.get("CW_ALLOW_INSECURE") != "1":
+        raise RuntimeError(
+            f"refusing an insecure {scheme or 'no'}-scheme url ({url}): remote artifacts/references must be "
+            f"https (set CW_ALLOW_INSECURE=1 to override)")
+
+
+def _sha256(path: str, buf: int = 1 << 20) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for b in iter(lambda: f.read(buf), b""):
+            h.update(b)
+    return h.hexdigest()
+
+
+def path_for(sha256: str) -> str:
+    return os.path.join(CACHE_DIR, "blobs", sha256[:2], sha256)
+
+
+def have(sha256: str) -> bool:
+    p = path_for(sha256)
+    return os.path.exists(p) and _sha256(p) == sha256
+
+
+def _ensure(url: str, sha256: str, dst: str) -> str:
+    """Download url to dst (verified by sha256), skipping if dst already matches. Returns dst."""
+    _require_sha(sha256, "artifact")
+    _check_scheme(url)
+    if os.path.exists(dst) and _sha256(dst) == sha256:
+        return dst
+    os.makedirs(os.path.dirname(dst), exist_ok=True)
+    tmp = dst + ".part"
+    urllib.request.urlretrieve(url, tmp)
+    got = _sha256(tmp)
+    if got != sha256:
+        os.remove(tmp)
+        raise RuntimeError(f"sha256 mismatch for {url}: got {got}, expected {sha256}")
+    os.replace(tmp, dst)
+    return dst
+
+
+def fetch(url: str, sha256: str) -> str:
+    """Download url into the content-addressed cache, verify the hash, return the local path."""
+    _require_sha(sha256, "artifact")
+    return _ensure(url, sha256, path_for(sha256))
+
+
+def fetch_named(url: str, sha256: str, name: str, sidecars=None) -> str:
+    """Fetch a reference file (verified) into a per-reference dir, KEEPING its original filename, so an
+    ONNX's external-data sidecar (`model.data` beside `model.onnx`) resolves. `sidecars` = an iterable of
+    (url, sha256, name) fetched into the same dir. Returns the local path to `name`.
+
+    The content-addressed `fetch` names a blob by its hash, which breaks a model that loads a neighbour
+    by filename — so a run reference (cpu_onnx / input / meta) uses this instead. Every `name` is confined
+    to the cache dir (`_safe_name`) so a registry entry cannot write outside it.
+    """
+    _require_sha(sha256, "reference")
+    d = os.path.join(CACHE_DIR, "refs", sha256[:12])
+    main = _ensure(url, sha256, os.path.join(d, _safe_name(name)))
+    for s_url, s_sha, s_name in (sidecars or []):
+        _require_sha(s_sha, "reference sidecar")
+        _ensure(s_url, s_sha, os.path.join(d, _safe_name(s_name)))
+    return main

{chipwright-0.2.1 → chipwright-0.2.3}/chipwright/cli.py

@@ -11,7 +11,9 @@ plainly rather than guessing.
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import os
+import re
 import sys
 
 from . import cache
@@ -21,6 +23,55 @@ from .resolver import Outcome, resolve
 
 GREEN, YELLOW, RED, DIM, RST = "\033[32m", "\033[33m", "\033[31m", "\033[2m", "\033[0m"
 
+# A bare Hexagon arch (what `list` and FAIL messages print, e.g. "v68") looks like a target but is
+# missing the mandatory `htp` prefix. Used to turn a malformed --target into a helpful suggestion.
+_ARCH_LIKE = re.compile(r"^v\d+$", re.IGNORECASE)
+
+# Modality extras → the key top-level imports that must resolve for that verify path to work. The
+# package list behind each extra is in pyproject.toml ([project.optional-dependencies]); here we name
+# the IMPORT each pip package provides (pillow → PIL). `doctor` reports these so a user learns an extra
+# is missing up front, not when a run fails.
+_MODALITY_EXTRAS = {
+    "cv":  ["onnxruntime", "PIL"],          # image classifiers (onnxruntime + pillow)
+    "asr": ["onnxruntime"],                 # streaming encoder/decoder/joiner
+    "tts": ["onnxruntime"],                 # text-to-speech reference
+    "llm": ["onnxruntime", "tokenizers"],   # CPU-reference decoder + genie retokenise
+}
+
+
+def _can_import(module: str) -> bool:
+    """True if `module` is importable — a read-only probe (find_spec, never actually imports)."""
+    try:
+        return importlib.util.find_spec(module) is not None
+    except Exception:
+        return False
+
+
+def _manual_target(spec: str) -> TargetKey:
+    """Turn --target into a TargetKey, refusing a malformed spec cleanly instead of a traceback.
+
+    The tool prints bare archs (`v68`) in `list` and in FAIL messages, so a user naturally copies
+    `v68` into --target. Rather than crash, we name the axis and — when the token looks like a known
+    arch missing its `htp` prefix — suggest the corrected form. Exits 2, matching `refuse rather than
+    guess`.
+    """
+    try:
+        return TargetKey.manual(spec)
+    except ValueError:
+        suggestion = None
+        for tok in spec.replace(" ", "").split(","):
+            if _ARCH_LIKE.match(tok):
+                suggestion = "htp" + tok.lower()
+                break
+        if suggestion:
+            msg = (f"target {spec!r} — did you mean {suggestion!r}? "
+                   f"(an arch must start with 'htp', e.g. htpv68,qnn2.37)")
+        else:
+            msg = (f"target {spec!r} — expected an arch starting with 'htp', "
+                   f"e.g. htpv68,qnn2.37")
+        print(f"{RED}✗ {msg}{RST}", file=sys.stderr)
+        sys.exit(2)
+
 
 def _board_from(args) -> dict:
     return {
@@ -40,28 +91,47 @@ def _get_target(args) -> TargetKey:
             return t
         print(f"{YELLOW}board {b['host']} not reachable{RST}", file=sys.stderr)
     if args.target:
-        return TargetKey.manual(args.target)
+        return _manual_target(args.target)
     print(f"{RED}no board reachable and no --target given{RST}", file=sys.stderr)
     sys.exit(2)
 
 
+def _print_extras_report():
+    """Report, per modality extra, whether its verify-path imports resolve. Read-only and safe with
+    nothing installed: base `pip install chipwright` ships no onnxruntime/pillow/tokenizers, so a user
+    told the product `proves it against a CPU reference` learns here — not mid-run — which extra to add.
+    """
+    print(f"\n{DIM}modality extras (the verify / CPU-reference path needs these){RST}")
+    for extra in ("cv", "asr", "tts", "llm"):
+        mods = _MODALITY_EXTRAS[extra]
+        missing = [m for m in mods if not _can_import(m)]
+        if missing:
+            print(f"  {RED}✗{RST} {extra:3s}  missing {', '.join(missing)}  "
+                  f"— pip install chipwright[{extra}]")
+        else:
+            print(f"  {GREEN}✓{RST} {extra:3s}  installed ({', '.join(mods)})")
+
+
 def cmd_doctor(args):
     b = _board_from(args)
+    rc = 0
     if not (b["host"] and b["pw"]):
         print(f"{YELLOW}no board configured{RST} — set CW_BOARD_HOST / CW_BOARD_PASS (or --host/--pw)")
-        return 0
-    t = probe(b["host"], b["user"], b["pw"], b["port"])
-    if not t.reachable:
-        print(f"{RED}● unreachable{RST}  {b['user']}@{b['host']}:{b['port']}")
-        return 1
-    print(f"{GREEN}● board reachable{RST}  {b['user']}@{b['host']}:{b['port']}")
-    print(f"  SoC         : {t.soc_name or '?'}" + (f" (soc_id {t.soc_id})" if t.soc_id else ""))
-    print(f"  Hexagon arch: {t.htp_arch}")
-    print(f"  QNN libs    : {', '.join(t.qnn_libs) or '(none found)'}")
-    if t.thermal_c is not None:
-        print(f"  temperature : {t.thermal_c} °C")
-    print(f"  target key  : {t}")
-    return 0
+    else:
+        t = probe(b["host"], b["user"], b["pw"], b["port"])
+        if not t.reachable:
+            print(f"{RED}● unreachable{RST}  {b['user']}@{b['host']}:{b['port']}")
+            rc = 1
+        else:
+            print(f"{GREEN}● board reachable{RST}  {b['user']}@{b['host']}:{b['port']}")
+            print(f"  SoC         : {t.soc_name or '?'}" + (f" (soc_id {t.soc_id})" if t.soc_id else ""))
+            print(f"  Hexagon arch: {t.htp_arch}")
+            print(f"  QNN libs    : {', '.join(t.qnn_libs) or '(none found)'}")
+            if t.thermal_c is not None:
+                print(f"  temperature : {t.thermal_c} °C")
+            print(f"  target key  : {t}")
+    _print_extras_report()
+    return rc
 
 
 def _print_decision(model, target, d):
@@ -144,7 +214,7 @@ def cmd_list(args):
         if t.reachable:
             target = t
     if target is None and args.target:
-        target = TargetKey.manual(args.target)
+        target = _manual_target(args.target)
 
     head = f"{target}" if target else "no target — pass --target or configure a board to resolve"
     print(f"{DIM}catalogue · {len(reg.models())} models · {head}{RST}")

{chipwright-0.2.1 → chipwright-0.2.3}/chipwright/data/index.yaml

@@ -212,11 +212,21 @@ models:
     sdk_tested: 2.37.1
     sdk_compatible: '>=2.34,<2.40'
     ext: dlc
+    url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/quicksrnet-small/quicksrnet_w8a8.dlc
+    sha256: 9ca46d230bd79205f103144df526eeedc47c505b7558d97d157a6ec46f493115
     run:
       modality: cv
       board_name: quicksrnet
       meta: ''
       threshold: 0.9
+      cpu_onnx: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/quicksrnet-small/quicksrnetsmall.onnx
+      cpu_onnx_sha256: 8ef99aecf6ea37c3da18eef6bcac94327cc3ead7069e55743425eb912dc2d941
+      cpu_onnx_sidecars:
+        - url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/quicksrnet-small/quicksrnetsmall.data
+          sha256: e377c1bfc040561b28b4931e7c4b27e6df39d8848addb25ebdeee3071b45dd64
+          name: quicksrnetsmall.data
+      input: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/quicksrnet-small/input.npy
+      input_sha256: 28eb37c45cfcc4c3b8f22e982af24d4df33f2f06ec0701fc535150973fdc5850
     verified:
       'on': QCS6490 (soc_id 498)
       date: 2026-10-09
@@ -240,11 +250,21 @@ models:
     sdk_tested: 2.37.1
     sdk_compatible: '>=2.34,<2.40'
     ext: dlc
+    url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/fcn-resnet50/fcn_w8a8.dlc
+    sha256: 98c0a2700f48f800859972d580b931d058d58a4ae699e1b4612c994fc947c65a
     run:
       modality: cv
       board_name: fcn
       meta: ''
       threshold: 0.9
+      cpu_onnx: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/fcn-resnet50/fcn_resnet50.onnx
+      cpu_onnx_sha256: 05eaf5a4d40915f3681aac3ae7ae0119ba9e8c5e9e753f1f1d9369023762b00f
+      cpu_onnx_sidecars:
+        - url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/fcn-resnet50/fcn_resnet50.data
+          sha256: 95e4a28fc598875a2cd836f96e808441954bea5df942b385e30304564ca8e8e1
+          name: fcn_resnet50.data
+      input: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/fcn-resnet50/input.npy
+      input_sha256: 08f15b114922848ef54c41f6ea240a99ca9a4f5c4708c256065c7f7c437c5b6a
     verified:
       'on': QCS6490 (soc_id 498)
       date: 2026-10-09
@@ -297,11 +317,21 @@ models:
     sdk_tested: 2.37.1
     sdk_compatible: '>=2.34,<2.40'
     ext: dlc
+    url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/depth-anything-v2/depth_w8a16.dlc
+    sha256: 051e9ff31c35cc093fae4601275337d6d3f6dcc7f9d06d3e219e5042c92936e3
     run:
       modality: cv
       board_name: depth
       meta: ''
       threshold: 0.9
+      cpu_onnx: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/depth-anything-v2/depth_anything_v2.onnx
+      cpu_onnx_sha256: 70f3afea5df1a1115f066d75ff40f35c95ec710e6609fb06533dc928f6769696
+      cpu_onnx_sidecars:
+        - url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/depth-anything-v2/depth_anything_v2.data
+          sha256: 1cd4366ce17bae5da226e58a3c0618d22ea128c12831cd6538aebe9fc5a3905d
+          name: depth_anything_v2.data
+      input: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/depth-anything-v2/input.npy
+      input_sha256: 8415c599c901a49cb5e1ad12d594b0d3c8e909af27ba0208183f2d161ff79418
     verified:
       "on": QCS6490 (soc_id 498)
       date: 2026-10-09
@@ -322,11 +352,21 @@ models:
     sdk_tested: 2.37.1
     sdk_compatible: '>=2.34,<2.40'
     ext: dlc
+    url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/movenet/pose_w8a16.dlc
+    sha256: 061187349f6890b9af6445f3bae998570ccfcd6516e93e5c41346b20e62cf33b
     run:
       modality: cv
       board_name: pose
       meta: ''
       threshold: 0.9
+      cpu_onnx: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/movenet/movenet.onnx
+      cpu_onnx_sha256: 77668290aba4913b0ffa58b6b526df2dddb871d695889428295182ca03ebcb0d
+      cpu_onnx_sidecars:
+        - url: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/movenet/movenet.data
+          sha256: 0032a7960d9730794c02ea8c7e2ab3483db5f8f9474c0e5c3f5bb4cef6384272
+          name: movenet.data
+      input: https://huggingface.co/nameissakthi/chipwright-cv/resolve/main/movenet/input.npy
+      input_sha256: 6fd2bba24a2c5fe0662930ff0cef5472b2fb4bd8a7413853ff40d560bd1689b2
     verified:
       "on": QCS6490 (soc_id 498)
       date: 2026-10-09

{chipwright-0.2.1 → chipwright-0.2.3}/chipwright/device.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import glob
 import os
+import re
 import shutil
 import subprocess
 import tempfile
@@ -16,6 +17,20 @@ import time
 
 import numpy as np
 
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def _safe_board_name(name):
+    """`board_name` comes from the registry and is interpolated into on-board shell commands (and used
+    as a board path), so it MUST be a plain identifier. A name with a shell metacharacter, space, slash
+    or `..` is refused — otherwise a crafted registry entry could run arbitrary commands as root on the
+    board (`board_name = 'x; curl … | sh'`)."""
+    if not isinstance(name, str) or name in (".", "..") or not _SAFE_NAME.match(name):
+        raise RuntimeError(
+            f"unsafe board_name {name!r}: must match [A-Za-z0-9._-]+ (it is interpolated into on-board "
+            f"shell commands — a separator or shell metacharacter is refused)")
+    return name
+
 
 def _require_sshpass():
     """`sshpass` is a system binary (not a pip package) the SSH transport shells out to.
@@ -67,15 +82,23 @@ class RemoteQNN:
             time.sleep(wait)
         return last
 
-    def ensure_ctx(self, local_path, name):
+    def ensure_ctx(self, local_path, name, ext=None):
         """Push an artifact to the board and return a runnable context-binary path (cached).
 
         A DLC is the durable artifact; the HTP context binary is per-target, so a `.dlc` is compiled
         into a context binary ON the board (2 MB VTCM) — regenerate, don't ship brittle. A prebuilt
         context binary (`.bin`/`.qnnctx`) is pushed as-is.
+
+        `ext` is the registry-declared artifact kind ("dlc"/"bin"/…). It is authoritative: a hosted
+        artifact is fetched into the content-addressed cache under a HASHED filename with no extension,
+        so inferring "is this a DLC?" from `local_path` wrongly treats a fetched DLC as a prebuilt
+        context binary (skips context-gen → "Could not create context from binary" on-device). When
+        `ext` is given we trust it; only when it is absent do we fall back to the filename suffix.
         """
+        name = _safe_board_name(name)  # registry-sourced; confine before it reaches any shell string
         self._retry(lambda: _ssh(self.pw, self.port, self.dest, f"mkdir -p {self.board_dir}", timeout=40))
-        if local_path.endswith(".dlc"):
+        is_dlc = (ext == "dlc") if ext is not None else local_path.endswith(".dlc")
+        if is_dlc:
             dlc_board = f"{self.board_dir}/{name}"
             ctx_board = f"{self.board_dir}/ctx_{name}/{name}_ctx.bin"
             present = _ssh(self.pw, self.port, self.dest, f"test -f {ctx_board} && echo OK", timeout=40)

{chipwright-0.2.1 → chipwright-0.2.3}/chipwright/registry.py

@@ -22,6 +22,12 @@ DEFAULT_INDEX = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data",
 
 def _load_yaml(src: str) -> dict:
     if src.startswith(("http://", "https://")):
+        # The index is the root of trust — it carries every artifact's sha256 — so a plaintext fetch is
+        # MITM-able (swap the index, swap the shas). Require https unless explicitly opted out.
+        if src.startswith("http://") and os.environ.get("CW_ALLOW_INSECURE") != "1":
+            raise RuntimeError(
+                f"refusing to load the registry index over insecure http ({src}): it carries the shas "
+                f"that pin every artifact (set CW_ALLOW_INSECURE=1 to override)")
         with urllib.request.urlopen(src, timeout=30) as r:
             return yaml.safe_load(r.read())
     with open(src) as f: