chipwright 0.2.0__py3-none-any.whl

chipwright/resolver.py

@@ -0,0 +1,197 @@
+"""Resolver — match registry variants against a board's TargetKey, with an explicit miss path.
+
+The resolution rules, in order:
+
+  1. Exact match on arch, quant, shape; SDK inside the compatible range  -> USE
+  2. Match, but SDK outside the tested point (still in range)            -> USE_WITH_WARN
+  3. No artifact, but a recipe whose target can be built                 -> BUILD (offer, estimate)
+  4. Nothing                                                             -> FAIL, name the axis
+
+Never silently downgrade to a near-miss artifact. The arch axis is hard (a mismatch fails at load);
+the SDK axis is a range, not a point (warn outside the tested point, don't refuse).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .env import TargetKey
+
+
+class Outcome(Enum):
+    USE = "use"                   # exact match — run it
+    USE_WITH_WARN = "use_warn"    # in-range but outside the tested SDK point
+    BUILD = "build"               # no artifact, but a recipe can produce one
+    FAIL = "fail"                 # nothing — the named axis is why
+
+
+@dataclass
+class Variant:
+    """One build variant from the registry (the registry's unit is a variant, not a model)."""
+    model: str
+    version: str
+    arch: str
+    quant: str
+    shape: str
+    sdk_tested: str                      # e.g. "2.37.1"
+    sdk_compatible: str                  # e.g. ">=2.34,<2.40"
+    ext: str = "qnnctx"
+    url: Optional[str] = None            # present => a built artifact exists (remote)
+    sha256: Optional[str] = None
+    local: Optional[str] = None          # present => an artifact file on disk (not yet hosted)
+    run: Optional[dict] = None           # how `run` executes it: {modality, meta, cpu_onnx, board_name, input}
+    recipe: Optional[str] = None         # present => can be built when no artifact matches
+    verified: Optional[dict] = None      # the verification record (loads / cosine / task / latency)
+    precision_support: Optional[dict] = None  # LLM: {precision: "supported"|"blocked:<r>"|"unsupported:<r>"}
+
+    @property
+    def has_artifact(self) -> bool:
+        return bool(self.url or self.local)
+
+    @property
+    def has_recipe(self) -> bool:
+        return bool(self.recipe)
+
+
+@dataclass
+class Decision:
+    outcome: Outcome
+    variant: Optional[Variant] = None
+    reason: str = ""
+    axis: Optional[str] = None        # on FAIL: which axis could not be satisfied
+    warning: Optional[str] = None     # on USE_WITH_WARN
+
+    @property
+    def ok(self) -> bool:
+        return self.outcome in (Outcome.USE, Outcome.USE_WITH_WARN)
+
+
+# --- precision-support axis (LLM) -------------------------------------------------------------
+# Not every precision survives the qai-hub -> Genie pipeline (spec 002, FR-L06): w4a16 is supported,
+# w8a16 is blocked on a KV-cache-encoding divergence at convert, fp16 is unsupported because Genie's
+# transformer path is integer-only. A recipe declares this per model; `resolve` refuses a non-supported
+# precision and NAMES the reason — the same discipline as FAIL-names-the-axis, applied one axis earlier.
+_SUPPORTED = "supported"
+
+
+def precision_refusal(precision: Optional[str], support: Optional[dict]) -> Optional[str]:
+    """Return the named reason to refuse `precision`, or None if it is supported / not constrained.
+
+    Pure and tiny so it is trivial to test. A precision absent from the matrix is *not* refused here
+    (the matrix only constrains what it declares); the normal variant/quant matching handles the rest.
+    A declared non-"supported" status (e.g. "blocked:kv-cache-encoding") is returned verbatim so the
+    caller can quote the reason by name.
+    """
+    if not precision or not support:
+        return None
+    status = support.get(precision)
+    if status is None or status == _SUPPORTED:
+        return None
+    return str(status)
+
+
+# --- tiny semver range check (enough for QAIRT x.y.z) -----------------------------------------
+def _ver(v: str):
+    return tuple(int(x) for x in (v.split("-")[0].split("+")[0].split(".") + ["0", "0"])[:3])
+
+
+def _in_range(point: str, rng: str) -> bool:
+    """point like '2.37.1' against a comma range like '>=2.34,<2.40'."""
+    p = _ver(point)
+    for clause in rng.split(","):
+        clause = clause.strip()
+        for op in (">=", "<=", "==", ">", "<"):
+            if clause.startswith(op):
+                bound = _ver(clause[len(op):])
+                ok = {">=": p >= bound, "<=": p <= bound, "==": p == bound,
+                      ">": p > bound, "<": p < bound}[op]
+                if not ok:
+                    return False
+                break
+    return True
+
+
+def resolve(target: TargetKey, variants: List[Variant],
+            want_quant: Optional[str] = None, want_shape: Optional[str] = None,
+            precision_support: Optional[dict] = None) -> Decision:
+    """Return the single Decision for this board. Pure function — easy to test without a board."""
+    if not variants:
+        return Decision(Outcome.FAIL, reason="no variants registered for this model", axis="model")
+
+    # Axis 0 (LLM precision-support): if the caller asked for a precision the model declares as
+    # blocked/unsupported, refuse up front and name the reason — before arch/SDK matching, because the
+    # precision is unavailable through the pipeline regardless of which board is in hand. The matrix may
+    # be passed explicitly or carried on the variants (the registry populates it per model).
+    if want_quant:
+        support = precision_support
+        if support is None:
+            support = next((v.precision_support for v in variants if v.precision_support), None)
+        reason = precision_refusal(want_quant, support)
+        if reason:
+            return Decision(Outcome.FAIL, axis="precision",
+                            reason=f"precision {want_quant} is not available: {reason}")
+
+    # Axis 1 (hard): Hexagon architecture must match exactly, or the binary fails at load.
+    arch_ok = [v for v in variants if v.arch == target.htp_arch]
+    if not arch_ok:
+        have = sorted({v.arch for v in variants})
+        return Decision(Outcome.FAIL, axis="htp_arch",
+                        reason=f"no variant for arch {target.htp_arch}; registry has {have}")
+
+    # Optional narrowing on quant / shape when the caller asked for a specific one.
+    cand = arch_ok
+    if want_quant:
+        c2 = [v for v in cand if v.quant == want_quant]
+        if not c2:
+            have = sorted({v.quant for v in cand})
+            return Decision(Outcome.FAIL, axis="quant",
+                            reason=f"no {want_quant} for {target.htp_arch}; have {have}")
+        cand = c2
+    if want_shape:
+        c2 = [v for v in cand if v.shape == want_shape]
+        if not c2:
+            have = sorted({v.shape for v in cand})
+            return Decision(Outcome.FAIL, axis="shape",
+                            reason=f"no shape {want_shape} for {target.htp_arch}; have {have}")
+        cand = c2
+
+    built = [v for v in cand if v.has_artifact]
+
+    # Axis: SDK range. If we don't know the board's QAIRT (offline), we can't check the point —
+    # prefer a built artifact and warn that the SDK match is unverified.
+    if built:
+        if target.qairt is None:
+            v = built[0]
+            return Decision(Outcome.USE_WITH_WARN, variant=v,
+                            warning="board QAIRT unknown (offline) — SDK compatibility unverified",
+                            reason="artifact matches arch/quant/shape")
+        in_range = [v for v in built if _in_range(target.qairt, v.sdk_compatible)]
+        if in_range:
+            exact = [v for v in in_range if _ver(v.sdk_tested) == _ver(target.qairt)]
+            if exact:
+                return Decision(Outcome.USE, variant=exact[0], reason="exact match")
+            v = in_range[0]
+            return Decision(Outcome.USE_WITH_WARN, variant=v,
+                            warning=(f"board QAIRT {target.qairt} is in range {v.sdk_compatible} "
+                                     f"but the artifact was tested at {v.sdk_tested}"),
+                            reason="in-range, outside tested point")
+        # artifact exists but SDK is out of every range -> fall through to recipe/fail on the SDK axis
+        sdk_axis = True
+    else:
+        sdk_axis = False
+
+    # Axis 3: no usable artifact, but a recipe can build one for this target.
+    buildable = [v for v in cand if v.has_recipe]
+    if buildable:
+        return Decision(Outcome.BUILD, variant=buildable[0],
+                        reason=("no artifact matches the board SDK; a recipe can build one"
+                                if sdk_axis else "no built artifact, but a recipe exists"))
+
+    # Axis 4: nothing.
+    if sdk_axis:
+        ranges = sorted({v.sdk_compatible for v in built})
+        return Decision(Outcome.FAIL, axis="qairt",
+                        reason=f"board QAIRT {target.qairt} outside every artifact range {ranges}, and no recipe")
+    return Decision(Outcome.FAIL, axis="artifact",
+                    reason="arch matches but no artifact and no recipe for this target")

chipwright/run.py

@@ -0,0 +1,173 @@
+"""The `run` verb — resolve → fetch/locate the artifact → push + execute on the board → verify.
+
+Ties the resolver, the device transport and a modality runner together, and ends in the thing that
+makes the whole framework trustworthy: a cosine against a CPU reference, so a fast wrong answer is
+caught here instead of shipped.
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import os
+
+from . import verify
+from .device import RemoteQNN
+
+
+def _board_env():
+    return dict(host=os.environ.get("CW_BOARD_HOST"),
+                user=os.environ.get("CW_BOARD_USER", "root"),
+                pw=os.environ.get("CW_BOARD_PASS"),
+                port=int(os.environ.get("CW_BOARD_PORT", 22)))
+
+
+def _looks_url(s):
+    return isinstance(s, str) and s.startswith(("http://", "https://"))
+
+
+def _locate_ref(r, key, override=None):
+    """Locate a run-block reference (cpu_onnx / input / meta): a local path, or a HOSTED url fetched into
+    the cache so a stranger's `run` works, not only the author's.
+
+    A url value is sha-verified via a companion `<key>_sha256` (refusing by name if absent — never an
+    unverified reference) and fetched with its original filename so an ONNX's external-data sidecar
+    resolves; declare sidecars under `<key>_sidecars: [{url, sha256, name}]`.
+    """
+    val = override if override is not None else r.get(key)
+    if val is None:
+        return None
+    if _looks_url(val):
+        sha = r.get(f"{key}_sha256")
+        if not sha:
+            raise RuntimeError(
+                f"run block {key} is a url but carries no {key}_sha256 — refusing to fetch an unverified "
+                f"reference (a reference the gate can't trust is worse than none).")
+        from . import cache
+        sidecars = [(s["url"], s["sha256"], s["name"]) for s in (r.get(f"{key}_sidecars") or [])]
+        name = val.rsplit("/", 1)[-1]
+        return cache.fetch_named(val, sha, name, sidecars)
+    return os.path.expanduser(val)
+
+
+def run_variant(variant, input_path=None):
+    """Execute a resolved variant on the board and return the verification report."""
+    r = variant.run or {}
+    if not r.get("modality"):
+        raise RuntimeError(f"variant for {variant.model} has no run block (modality/meta/cpu_onnx)")
+
+    # an LLM variant generates and gates against a PINNED reference (not a live cosine) — its own path.
+    if r["modality"] == "llm":
+        return run_llm_variant(variant, r)
+
+    # locate the artifact: a local file, or fetched by hash into the content-addressed cache
+    if not variant.local and not variant.url:
+        raise RuntimeError(
+            f"{variant.model}: this variant carries a verification record but no runnable artifact "
+            f"in the active registry (no hosted url, no local path). Build it with "
+            f"`chipwright build {variant.model}`, or set CW_REGISTRY to a registry that has the "
+            f"artifact (the author's dev registry is registry/index.dev.yaml).")
+    if variant.local:
+        art = os.path.expanduser(variant.local)
+        if not os.path.exists(art):
+            raise RuntimeError(f"local artifact not found: {art}")
+    else:
+        from . import cache
+        art = cache.fetch(variant.url, variant.sha256)
+
+    b = _board_env()
+    if not (b["host"] and b["pw"]):
+        raise RuntimeError("no board configured — set CW_BOARD_HOST / CW_BOARD_PASS")
+    dev = RemoteQNN(b["host"], b["user"], b["pw"], b["port"])
+
+    board_name = r.get("board_name", os.path.basename(art))
+    print(f"  pushing artifact to board ({board_name}) …", flush=True)
+    ctx_board = dev.ensure_ctx(art, board_name)
+
+    mod = importlib.import_module(f".modalities.{r['modality']}", __package__)
+    if not r.get("cpu_onnx") or not (input_path or r.get("input")):
+        raise RuntimeError(
+            f"{variant.model}: the run block has no CPU reference (cpu_onnx) and/or input in the "
+            f"active registry, so the verification gate can't run. Pass --input, or use a registry "
+            f"that carries the reference (registry/index.dev.yaml).")
+    meta = _locate_ref(r, "meta") or ""
+    cpu_onnx = _locate_ref(r, "cpu_onnx")
+    inp = _locate_ref(r, "input", override=input_path)
+    print("  running on NPU + CPU reference …", flush=True)
+    npu_out, cpu_out = mod.run(dev, ctx_board, meta, cpu_onnx, inp)
+    return verify.report(npu_out, cpu_out, threshold=float(r.get("threshold", 0.99)))
+
+
+def _looks_refused(text: str) -> bool:
+    """Heuristic: does a generation read as a refusal? (behavioral probe, v1 classifier)
+
+    A coarse marker match over the opening of the generated text — enough to tell "I can't help with
+    that" from a compliant answer. The reference's own refusal labels are pinned (computed on the CPU
+    reference at pin time); this classifies the on-chip side the same way for a relative comparison.
+    """
+    if not text:
+        return False
+    head = text.strip().lower()[:200]
+    markers = ("i can't", "i cannot", "i can not", "i won't", "i will not", "i'm sorry",
+               "i am sorry", "i'm unable", "i am unable", "cannot help", "can't help",
+               "not able to", "against my", "i must decline", "i'm not able")
+    return any(m in head for m in markers)
+
+
+def run_llm_variant(variant, r):
+    """Generate on the NPU and gate against the PINNED reference (FR-L03/L04/L10).
+
+    The LLM path differs from CV/ASR: it drives Genie over **adb**, generates from a fixed prompt set,
+    and compares the on-chip greedy tokens to a reference that was computed once on the build host and
+    **pinned** into the record (`r["reference"]`) — never a live CPU call on the board. v1 gates on the
+    greedy token-match (Layer-1 1a) and records the behavioral refusal probe; top-1/KL/PPL (1b/1c) are
+    marked not-measured-on-chip because `genie-t2t-run` emits tokens, not per-step logits.
+    """
+    from . import verify_llm
+    from .device_adb import AdbDevice
+
+    bundle = os.path.expanduser(variant.local or "")
+    if not bundle or not os.path.isdir(bundle):
+        raise RuntimeError(
+            f"{variant.model}: this LLM variant has no runnable Genie bundle directory in the active "
+            f"registry (no `local` bundle dir). Build it with `chipwright build {variant.model}`, or set "
+            f"CW_REGISTRY to a registry that carries the bundle (registry/index.dev.yaml).")
+    ref_path = os.path.expanduser(r.get("reference") or "")
+    if not ref_path or not os.path.exists(ref_path):
+        raise RuntimeError(
+            f"{variant.model}: the run block has no pinned reference (`reference`) in the active "
+            f"registry, so the generative gate can't run (a pass is never reported without the gate). "
+            f"Use a registry that carries the pinned reference (registry/index.dev.yaml).")
+
+    with open(ref_path) as f:
+        pin = json.load(f)                       # {prompts, tokens, [logits], [ppl], reference_logits_sha256}
+    prompts = pin["prompts"]
+    ref_tokens = pin["tokens"]
+    meta = r.get("meta") or {}
+
+    serial = os.environ.get("CW_BOARD_SERIAL")   # adb picks the device by serial; None == the one attached
+    dev = AdbDevice(serial)
+    mod = importlib.import_module(".modalities.llm", __package__)
+
+    print(f"  generating on NPU over {len(prompts)} prompt(s) …", flush=True)
+    matches, latency = [], {}
+    for prompt, ref_toks in zip(prompts, ref_tokens):
+        on = mod.run(dev, bundle, meta, prompt)
+        matches.append(verify_llm.token_match(on.get("tokens") or [], ref_toks))
+        latency = on.get("latency") or latency   # last prompt's profile is representative
+    token_match = float(sum(matches) / len(matches)) if matches else 0.0
+
+    tripwire = {
+        "token_match": token_match, "top1_agreement": None, "mean_kl_nats": None,
+        "ppl_delta_pct": None,                   # 1b/1c not measured on-chip in v1 (Genie emits tokens, not logits)
+        "thresholds": {"token_match": verify_llm.TOKEN_MATCH_MIN, "ppl_delta_pct": verify_llm.PPL_DELTA_MAX_PCT},
+        "pass": bool(token_match >= verify_llm.TOKEN_MATCH_MIN),
+    }
+    report = {"tripwire": tripwire, "latency": latency, "pass": tripwire["pass"]}
+
+    # Layer-2 behavioral probe — only when the run block carries the harmful/benign sets + pinned labels.
+    beh = r.get("behavior")
+    if beh and pin.get("ref_refused") is not None:
+        onchip_refused = [_looks_refused(mod.run(dev, bundle, meta, p).get("text")) for p in beh["harmful"]]
+        benign_answered = [not _looks_refused(mod.run(dev, bundle, meta, p).get("text")) for p in beh["benign"]]
+        report["behavior"] = verify_llm.behavior_report(onchip_refused, pin["ref_refused"], benign_answered)
+    return report

chipwright/sdk.py

@@ -0,0 +1,140 @@
+"""SDK knowledge — the pre-build op-support gate and a thin docs lookup.
+
+`will_it_run(onnx_path, target)` scans an ONNX graph's op types against a small built-in table of ops
+known-problematic on the HTP and returns an `OpReport` *before* any QAIRT tool is shelled out. It is a
+gate, not a converter: a fast, honest "this won't convert cleanly" beats a 20-minute build that dies at
+the context stage. It degrades gracefully — with no `onnx` installed it parses what it can from the raw
+file and says so, rather than throwing.
+
+The rules encode what the recipe's `adaptations` exist to fix (data-model Recipe): a surviving FP16
+tensor on a v68 context, `Erf` with no HTP layout inferer, an on-chip integer `Gather`.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class OpReport:
+    supported: bool
+    unsupported: List[str] = field(default_factory=list)      # op types with no HTP support at all
+    flags: List[Dict[str, str]] = field(default_factory=list)  # {op, reason} — problematic but adaptable
+    note: Optional[str] = None                                 # set when the scan degraded (no onnx, etc.)
+
+    def __bool__(self) -> bool:
+        return self.supported
+
+
+# Ops that HTP cannot run at all (the converter will reject them outright).
+_UNSUPPORTED = {
+    "NonMaxSuppression": "no HTP implementation",
+    "RoiAlign": "no HTP implementation",
+    "GridSample": "no HTP implementation",
+}
+
+# Ops that convert only with a declared adaptation. reason -> what the recipe must carry.
+_PROBLEMATIC = {
+    "Erf": "Erf has no HTP layout inferer — rewrite GELU via tanh (adaptation: erf_to_tanh)",
+    "Gather": "integer Gather lands on-chip and is slow/unsupported for a large table — split the embed to host (adaptation: host_embed_split)",
+    "Pad": "some Pad configs are rejected by the converter — pin mode=constant (adaptation: pad_fix)",
+}
+
+
+def _onnx_op_types(onnx_path: str) -> (List[str], Dict[str, Any], Optional[str]):
+    """Return (op_types, tensor_dtype_info, note). Uses onnx if available; else a lightweight byte scan."""
+    try:
+        import onnx  # type: ignore
+        m = onnx.load(onnx_path)
+        ops = [n.op_type for n in m.graph.node]
+        # look for a float16 value_info / initializer surviving into the graph
+        fp16 = 1  # onnx.TensorProto.FLOAT16
+        has_fp16 = any(getattr(i, "data_type", None) == fp16 for i in m.graph.initializer)
+        for vi in list(m.graph.value_info) + list(m.graph.input) + list(m.graph.output):
+            if vi.type.tensor_type.elem_type == fp16:
+                has_fp16 = True
+                break
+        # Reshape allowzero=1 — qairt-converter rejects it (ViT / detector exports hit this)
+        allowzero = any(n.op_type == "Reshape" and any(a.name == "allowzero" and a.i == 1
+                                                       for a in n.attribute) for n in m.graph.node)
+        return ops, {"fp16": has_fp16, "reshape_allowzero": allowzero}, None
+    except ImportError:
+        pass
+    except Exception as e:  # a corrupt/partial file — degrade rather than crash the whole gate
+        return [], {"fp16": False}, f"onnx failed to parse ({e}); op scan skipped"
+
+    # Lightweight fallback: scan the raw protobuf bytes for op-type strings we know about.
+    try:
+        with open(onnx_path, "rb") as f:
+            blob = f.read()
+    except OSError as e:
+        return [], {"fp16": False}, f"could not read {onnx_path} ({e})"
+    known = list(_UNSUPPORTED) + list(_PROBLEMATIC) + [
+        "Conv", "MatMul", "Add", "Mul", "Softmax", "LayerNormalization", "Relu", "Transpose"]
+    found = [op for op in known if op.encode() in blob]
+    # a byte scan cannot reliably tell a tensor's dtype, so fp16 is left undetected here
+    return found, {"fp16": False}, "lightweight byte scan (install `onnx` for a full op + dtype gate)"
+
+
+def will_it_run(onnx_path: str, target: Any) -> OpReport:
+    """Scan `onnx_path` for ops problematic on `target` (a TargetKey or any obj with `.htp_arch`).
+
+    Returns an OpReport: `supported=False` if any op has no HTP path at all; otherwise `supported=True`
+    with `flags` for ops that need a declared adaptation. Never raises for a missing graph/tool — it
+    reports the degradation in `note`.
+    """
+    arch = getattr(target, "htp_arch", None) or (target.get("arch") if isinstance(target, dict) else None) or "?"
+
+    if not onnx_path or not os.path.exists(onnx_path):
+        return OpReport(supported=True, note=f"onnx not found at {onnx_path!r}; op gate skipped (degraded)")
+
+    ops, info, note = _onnx_op_types(onnx_path)
+    if not ops and note is None:
+        note = "no op types recognised; using a lightweight byte scan (install `onnx` for a full gate)"
+
+    unsupported = sorted({op for op in ops if op in _UNSUPPORTED})
+    flags: List[Dict[str, str]] = []
+    for op in sorted(set(ops)):
+        if op in _PROBLEMATIC:
+            flags.append({"op": op, "reason": _PROBLEMATIC[op]})
+    # a surviving FP16 tensor on a v68/v6x context overflows the attention mask fill and loses range
+    if info.get("fp16") and str(arch).startswith("v6"):
+        flags.append({"op": "<fp16-tensor>",
+                      "reason": f"a surviving FP16 tensor on an {arch} context — clamp the mask "
+                                f"(-3.4e38 → -1e4) and quantize (adaptation: mask_clamp)"})
+    # Reshape allowzero=1 — the converter rejects it outright; lossless to clear (no literal-0 dim)
+    if info.get("reshape_allowzero"):
+        flags.append({"op": "Reshape(allowzero=1)",
+                      "reason": "qairt-converter rejects allowzero=1; set it to 0 (adaptation: reshape_allowzero)"})
+
+    return OpReport(supported=not unsupported, unsupported=unsupported, flags=flags, note=note)
+
+
+def docs(query: str, sdk_root: Optional[str] = None) -> dict:
+    """Thin docs lookup: grep the SDK docs dir for `query` when an SDK root is present.
+
+    A stub by design — returns matching lines (capped) or a clear 'no SDK docs' result. Wraps the
+    skills' `extract-sdk-docs.py` surface without taking a hard dependency on the SDK being installed.
+    """
+    root = sdk_root or os.environ.get("QNN_SDK_ROOT") or os.environ.get("QAIRT_SDK_ROOT")
+    if not root or not os.path.isdir(root):
+        return {"query": query, "sdk_root": root, "found": False,
+                "note": "no SDK docs dir (set QNN_SDK_ROOT); docs lookup unavailable"}
+    docs_dir = next((d for d in (os.path.join(root, "docs"), root) if os.path.isdir(d)), root)
+    hits: List[Dict[str, str]] = []
+    for base, _dirs, files in os.walk(docs_dir):
+        for fn in files:
+            if not fn.lower().endswith((".txt", ".md", ".html", ".rst")):
+                continue
+            path = os.path.join(base, fn)
+            try:
+                with open(path, errors="ignore") as f:
+                    for i, line in enumerate(f, 1):
+                        if query.lower() in line.lower():
+                            hits.append({"file": path, "line": str(i), "text": line.strip()[:200]})
+                            if len(hits) >= 20:
+                                return {"query": query, "sdk_root": root, "found": True, "hits": hits}
+            except OSError:
+                continue
+    return {"query": query, "sdk_root": root, "found": bool(hits), "hits": hits}

chipwright/tags.py

@@ -0,0 +1,56 @@
+"""Artifact tags — the wheel-tag grammar for QNN artifacts.
+
+A QNN context binary is valid for exactly one combination of five axes. We name that combination
+in the filename (the parts a resolver matches on) and expand the rest in the manifest, the same way
+a PyPI wheel names `cp312-manylinux_x86_64` and leaves the rest to metadata.
+
+    whisper-small-en-1.2.0+qnn2.37-htpv68-w8a16-win30s.qnnctx
+    └──────┬───────┘ └─┬─┘ └──┬──┘ └──┬──┘ └─┬─┘ └─┬─┘ └─┬──┘
+         name       version  sdk    arch   quant  shape  ext
+
+Filename carries arch + quant + shape + a coarse SDK (brief lean); the manifest carries the full
+SDK compatibility range and everything else. Parsing is deliberately strict: a tag that doesn't
+parse is a bug, not a near-miss to paper over.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_EXT = ("qnnctx", "dlc", "bin")
+# name is greedy up to the LAST "-<semver>+"; version is semver; then the +qnn... compat tag.
+_RE = re.compile(
+    r"^(?P<name>.+?)-(?P<version>\d+\.\d+\.\d+)"
+    r"\+qnn(?P<sdk>\d+\.\d+)"
+    r"-htp(?P<arch>v\d+)"
+    r"-(?P<quant>w\d+a\d+|fp16|fp32)"
+    r"-(?P<shape>[A-Za-z0-9]+)"
+    r"\.(?P<ext>" + "|".join(_EXT) + r")$"
+)
+
+
+@dataclass(frozen=True)
+class ArtifactTag:
+    name: str
+    version: str
+    sdk: str        # coarse, e.g. "2.37" — the manifest holds the full compatible range
+    arch: str       # Hexagon arch, e.g. "v68"
+    quant: str      # e.g. "w8a16"
+    shape: str      # shape profile, e.g. "win30s"
+    ext: str        # "qnnctx" | "dlc" | "bin"
+
+    @classmethod
+    def parse(cls, filename: str) -> "ArtifactTag":
+        m = _RE.match(filename.strip())
+        if not m:
+            raise ValueError(f"not a valid QNN artifact tag: {filename!r}")
+        return cls(**m.groupdict())
+
+    def __str__(self) -> str:
+        return (f"{self.name}-{self.version}+qnn{self.sdk}"
+                f"-htp{self.arch}-{self.quant}-{self.shape}.{self.ext}")
+
+    @property
+    def is_context_binary(self) -> bool:
+        """Context binaries are brittle (pinned to arch×SDK×backend); DLCs are forward-compatible."""
+        return self.ext in ("qnnctx", "bin")