chipwright 0.2.6__tar.gz → 0.2.7__tar.gz

{chipwright-0.2.6 → chipwright-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipwright
-Version: 0.2.6
+Version: 0.2.7
 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

{chipwright-0.2.6 → chipwright-0.2.7}/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.6"
+__version__ = "0.2.7"

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright/cli.py

@@ -234,7 +234,8 @@ def cmd_resolve(args):
     if args.model not in reg.models():
         return _unknown_model(args, reg)
     target = _get_target(args)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     if getattr(args, "json", False):
         _emit_json(jsonout.decision_to_dict(args.model, target, d))
     else:
@@ -307,6 +308,22 @@ def _render_run_report(rep, d):
     """Print a run's verification report (human door) and return its exit code. Shape-safe: the LLM
     generative gate reports a `tripwire` (token-match), CV/ASR a cosine — the human door must not diverge
     from the already-shape-safe `--json` projection (Principle IV, and never a KeyError traceback)."""
+    if rep.get("runtime") == "llamacpp-htp":     # runtime path: a silicon record + the host recipe (FR-RT07)
+        rec = rep.get("record") or {}
+        d_ = rec.get("dispatch") or {}
+        q_ = rec.get("quality") or {}
+        print(f"\n{GREEN}✔ cached + hash-verified{RST}  {rep.get('artifact')}")
+        print(f"{YELLOW}runtime = llamacpp-htp{RST}  (on-device execution via the recipe below — not the Genie transport)")
+        if d_:
+            print(f"    on-silicon record ({rec.get('board')}, {rec.get('htp_arch')}, {rec.get('date')}): "
+                  f"Q8_0 dispatched to HTP0 — prefill {d_.get('htp0_prefill_tps')} vs CPU "
+                  f"{d_.get('cpu_prefill_tps')} t/s = {d_.get('prefill_speedup')}×")
+        if q_:
+            print(f"    quality: PPL(WikiText) = {q_.get('ppl_wikitext_q8_0')} (near-lossless)")
+        print(f"    recipe: ADSP_LIBRARY_PATH=<lib> " + " ".join(rep.get("recipe") or []))
+        if rep.get("warn"):
+            print(f"{DIM}    note: {rep['warn']}{RST}")
+        return jsonout.EXIT_USE_WITH_WARN
     mark = f"{GREEN}✔ VERIFIED{RST}" if rep["pass"] else f"{RED}✗ MISMATCH{RST}"
     if "tripwire" in rep:                        # LLM generative gate (token-match), not a cosine
         tw = rep["tripwire"]
@@ -332,7 +349,8 @@ def cmd_run(args):
     target = _get_target(args)
     if getattr(args, "json", False):
         return _run_json(args, reg, target)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     _print_decision(args.model, target, d)
     if not d.ok:
         if d.outcome == Outcome.BUILD:
@@ -340,7 +358,9 @@ def cmd_run(args):
         return jsonout.exit_code_for(d)
     # USE / USE_WITH_WARN: execute on the board and verify against a CPU reference.
     v = d.variant
-    if not (v.run and v.run.get("modality")):
+    # the llama.cpp-HTP runtime has its own run path (fetch + silicon record + recipe, FR-RT07) and no
+    # cosine run block — route it through run_variant instead of the no-run-block short-circuit.
+    if not (v.run and v.run.get("modality")) and v.effective_runtime != "llamacpp-htp":
         print(f"{DIM}artifact resolves, but this variant has no run block (modality/meta/cpu_onnx) — "
               f"resolve-only.{RST}")
         if v.url:
@@ -363,13 +383,14 @@ def _run_json(args, reg, target) -> int:
     """
     # Everything human — the decision render and the runner's progress lines — to stderr.
     with contextlib.redirect_stdout(sys.stderr):
-        d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+        d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
         _print_decision(args.model, target, d)
         if not d.ok:
             doc, code = jsonout.decision_to_dict(args.model, target, d), jsonout.exit_code_for(d)
         else:
             v = d.variant
-            if not (v.run and v.run.get("modality")):
+            if not (v.run and v.run.get("modality")) and v.effective_runtime != "llamacpp-htp":
                 print(f"artifact resolves, but this variant has no run block — resolve-only.")
                 doc = jsonout.decision_to_dict(args.model, target, d)
                 doc["verified"] = None
@@ -378,7 +399,10 @@ def _run_json(args, reg, target) -> int:
                 from . import run as runner
                 rep = runner.run_variant(v, args.input)   # may raise → caught by the --json wrapper in main
                 doc = jsonout.run_to_dict(args.model, target, d, rep)
-                code = jsonout.exit_code_for(d) if rep.get("pass") else jsonout.EXIT_VERIFY_MISMATCH
+                if rep.get("runtime") == "llamacpp-htp":
+                    code = jsonout.EXIT_USE_WITH_WARN     # usable, with the documented recipe caveat (FR-RT07)
+                else:
+                    code = jsonout.exit_code_for(d) if rep.get("pass") else jsonout.EXIT_VERIFY_MISMATCH
     _emit_json(doc)
     return code
 
@@ -437,7 +461,8 @@ def cmd_build(args):
     if args.model not in reg.models():
         return _unknown_model(args, reg)
     target = _get_target(args)
-    d = resolve(target, reg.variants(args.model), args.quant, args.shape)
+    d = resolve(target, reg.variants(args.model), args.quant, args.shape,
+                want_runtime=getattr(args, "runtime", None), priority=getattr(args, "priority", None))
     _print_decision(args.model, target, d)
     if d.ok:
         print(f"{DIM}already resolves to USE — nothing to build.{RST}")
@@ -501,6 +526,9 @@ def main(argv=None):
     ap.add_argument("--target", help="offline target, e.g. 'htpv68,qnn2.37'")
     ap.add_argument("--quant", help="narrow to a quant, e.g. w8a16")
     ap.add_argument("--shape", help="narrow to a shape profile, e.g. win30s")
+    ap.add_argument("--runtime", help="pick an inference runtime, e.g. llamacpp-htp (default: the genie floor)")
+    ap.add_argument("--priority", choices=["quality", "decode-latency"],
+                    help="when a model spans runtimes, prefer quality (llamacpp-htp) or decode-latency (genie)")
     ap.add_argument("--json", action="store_true",
                     help="emit one JSON document to stdout (resolve/run/list); human text → stderr, "
                          "always plain. Exit codes follow the table below.")

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright/data/index.yaml

@@ -142,6 +142,50 @@ models:
     sdk_compatible: '>=2.34,<2.40'
     ext: qnnctx
     recipe: recipes/qwen2.5-1.5b/1.0.0.yaml
+  # The llama.cpp-HTP runtime variant — a >4-bit integer route (Q8_0) that classic Genie structurally
+  # lacks. Silicon-verified on v73 (spec 004 Track 2). On-device execution is via the documented
+  # llama.cpp-HTP recipe (staged glibc loader + ADSP_LIBRARY_PATH + libggml-htp-v73.so); chipwright-run
+  # CLI integration for this runtime is pending (T-RT11), so `run` here fetches + hash-verifies the GGUF
+  # and surfaces the recipe + this record (FR-RT07), rather than driving the board itself.
+  - arch: v73
+    quant: Q8_0
+    shape: ctx4096
+    runtime: llamacpp-htp
+    sdk_tested: b3278e921
+    sdk_compatible: llama.cpp-HTP (no QAIRT dependency)
+    ext: gguf
+    url: https://huggingface.co/nameissakthi/chipwright-llm/resolve/main/qwen2.5-1.5b-Q8_0.gguf
+    sha256: cedde4175edae2e9467d8b98d70843e57c8fb101afd54ca773bce022e80f7e4e
+    runtime_support:
+      llamacpp-htp:
+        v68: 'unsupported:needs-v73-or-newer-hexagon'
+        v73: supported
+      genie:
+        v68: supported
+        v73: supported
+    verified:
+      'on': QCS9075 (Dragonwing IQ-9075, soc_id 676, Hexagon v73)
+      date: 2026-10-24
+      loads: true
+      runtime: llamacpp-htp
+      vs_reference:
+        backend: llama.cpp-cpu (same Q8_0 GGUF, GGML_HEXAGON_NDEV=0)
+        metric: dispatch+ppl
+        dispatch:
+          device: HTP0
+          htp0_prefill_tps: 592.82
+          cpu_prefill_tps: 217.55
+          prefill_speedup: 2.72
+          note: Q8_0 MUL_MAT dispatched to HTP0 on the compute-DSP (_dom=cdsp), not CPU fallback (SC-RT03)
+        quality:
+          metric: ppl_wikitext
+          chunks: 16
+          ppl_q8_0: 11.6631
+          ppl_stderr: 0.49427
+          ppl_f16_baseline: 11.6388
+          note: near-lossless vs the model's own f16
+        llamacpp_build: b3278e921
+      note: the >4-bit integer route Genie lacks; on-device exec via the llama.cpp-HTP recipe (CLI integration T-RT11)
 - model: qwen2.5-7b-instruct
   source: Qwen/Qwen2.5-7B-Instruct
   license: apache-2.0

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright/jsonout.py

@@ -100,6 +100,13 @@ def run_to_dict(model: str, target, d: Decision, report: dict) -> dict:
     rec["outputs"] = dict(report.get("per_output") or {})
     if "tripwire" in report:           # LLM path: a generative tripwire, not a cosine
         rec["tripwire"] = report["tripwire"]
+    if report.get("runtime") == "llamacpp-htp":   # runtime path: a silicon record + the host recipe
+        rec["runtime"] = report["runtime"]
+        rec["record"] = report.get("record")
+        rec["recipe"] = report.get("recipe")
+        rec["cli_execution"] = report.get("cli_execution")
+        if report.get("warn"):
+            rec.setdefault("warnings", []).append(report["warn"])
     return rec
 
 

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright/resolver.py

@@ -285,6 +285,17 @@ def resolve(target: TargetKey, variants: List[Variant],
 
     built = [v for v in cand if v.has_artifact]
 
+    # The QAIRT SDK range is a genie/QNN concept — a GGUF on the llama.cpp-HTP runtime has no QAIRT
+    # dependency, its "sdk" is the llama.cpp build, which is not comparable to the board's QAIRT. So skip
+    # the QAIRT axis for it: a matching built artifact on this arch is USE (carry any runtime warning).
+    if built and built[0].effective_runtime == "llamacpp-htp":
+        v = built[0]
+        if runtime_warning:
+            return Decision(Outcome.USE_WITH_WARN, variant=v, warning=runtime_warning,
+                            reason=f"artifact matches arch/quant/shape; runtime llamacpp-htp (llama.cpp {v.sdk_tested})")
+        return Decision(Outcome.USE, variant=v,
+                        reason=f"artifact matches arch/quant/shape; runtime llamacpp-htp (llama.cpp {v.sdk_tested})")
+
     # 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:

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright/run.py

@@ -46,11 +46,52 @@ def _emit_npu_record(variant, npu_out):
         print(f"        # saved locally: {fn}", flush=True)
 
 
+def run_llamacpp_htp_variant(variant):
+    """The llama.cpp-HTP runtime path (spec 004 FR-RT07) — surface the prereqs, don't fail opaquely.
+
+    This runtime does NOT go through the Genie/QNN device transport. v1 does the honest runnable-today
+    part: fetch + hash-verify the hosted GGUF (proving the artifact is real + intact), then surface the
+    on-device *recipe* (staged glibc loader + ADSP_LIBRARY_PATH + libggml-htp-<arch>.so) and the
+    on-silicon record (`SILICON_RECORD` — dispatch 2.72×, PPL 11.6631). Driving the loader-staging +
+    exec from the CLI is T-RT11; until then `run` names the prereq rather than pretending. A caller gets
+    USE_WITH_WARN: the variant is silicon-verified and fetchable, with the one documented caveat.
+    """
+    from . import cache
+    from .runtimes import llamacpp_htp as lh
+
+    if not variant.url and not variant.local:
+        raise RuntimeError(
+            f"{variant.model} [llamacpp-htp]: this variant carries a silicon record but no GGUF artifact "
+            f"in the active registry (no hosted url, no local path).")
+    if variant.url:
+        art = cache.fetch(variant.url, variant.sha256)   # fetch + sha-verify (refuses on mismatch)
+    else:
+        art = os.path.expanduser(variant.local)
+        if not os.path.exists(art):
+            raise RuntimeError(f"local GGUF not found: {art}")
+    recipe = lh.bench_command(os.path.basename(art), "./pkg-snapdragon/lib", "./glibc238")
+    return {
+        "runtime": "llamacpp-htp",
+        "artifact": art,
+        "artifact_verified": True,
+        "record": lh.SILICON_RECORD,
+        "recipe": recipe,
+        "host_prereqs": list(lh.REQUIRED_LOADER_LIBS),
+        "cli_execution": "recipe",                       # not driven by `run` yet — spec 004 T-RT11
+        "pass": True,                                    # verified on record + artifact integrity ok
+        "warn": ("on-device execution is via the documented llama.cpp-HTP recipe (shown); chipwright-run "
+                 "CLI integration for this runtime is pending (spec 004 T-RT11)"),
+    }
+
+
 def run_variant(variant, input_path=None, emit_record=False):
     """Execute a resolved variant on the board and return the verification report.
 
     `emit_record=True` also captures the on-device output tensor(s) for a reproducible record (FR-RR05).
     """
+    # the llama.cpp-HTP runtime has its own path (no Genie/QNN transport) — handle before the modality logic.
+    if variant.effective_runtime == "llamacpp-htp":
+        return run_llamacpp_htp_variant(variant)
     r = variant.run or {}
     if not r.get("modality"):
         raise RuntimeError(f"variant for {variant.model} has no run block (modality/meta/cpu_onnx)")

chipwright-0.2.7/chipwright/runtimes/__init__.py

@@ -0,0 +1,40 @@
+"""Runtime adapters — the seam the runtime axis resolves onto (spec 004, T-RT03).
+
+The resolver (`resolver.py`) picks a *runtime* ({genie, geniex-qairt, llamacpp-htp}) as one axis of a
+Decision; an adapter is the thing that then actually stages and runs a variant on that runtime and proves
+it ran. The resolver stays pure and offline — adapters are where the on-device, runtime-specific work lives
+(Principle IV: one implementation; the CLI/app call the adapter, they never fork its logic).
+
+Only the adapters that are *silicon-verified* are registered here. `llamacpp-htp` is registered because its
+Q8_0-on-HTP route is proven on v73 (see `llamacpp_htp.SILICON_RECORD`). `genie` / `geniex-qairt` are named
+by the resolver but have no adapter yet — `get_adapter` refuses them by name rather than pretending.
+"""
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+from . import llamacpp_htp
+
+# name -> the adapter module (each exposes dispatch_proof / host_preflight / bench_command / SILICON_RECORD)
+_ADAPTERS: Dict[str, object] = {
+    "llamacpp-htp": llamacpp_htp,
+}
+
+
+def get_adapter(runtime: str):
+    """Return the adapter module for `runtime`, or raise with a named reason if none is wired yet.
+
+    Refuse-by-name, not a KeyError traceback — the same discipline the resolver uses (Principle II).
+    """
+    adapter = _ADAPTERS.get(runtime)
+    if adapter is None:
+        known = sorted(_ADAPTERS)
+        raise NotImplementedError(
+            f"no silicon-verified adapter for runtime {runtime!r}; wired runtimes: {known}. "
+            f"(the resolver may still *select* {runtime!r} offline, but running it needs an adapter)")
+    return adapter
+
+
+def wired_runtimes():
+    """The runtimes that have a real, silicon-verified adapter."""
+    return sorted(_ADAPTERS)

chipwright-0.2.7/chipwright/runtimes/llamacpp_htp.py

@@ -0,0 +1,178 @@
+"""The llama.cpp-HTP runtime adapter (spec 004 T-RT07; FR-RT06 / SC-RT03).
+
+This is the route Genie structurally lacks: a >4-bit integer quant (Q8_0, Q4_0) dispatched to the Hexagon
+HTP through the llama.cpp Hexagon backend. Classic Genie is w4a16-only; llama.cpp-HTP runs Q8_0 MUL_MAT on
+the NPU on v73+, which is the quality/prefill win.
+
+Two pieces are the adapter's contract, and both are pure + offline-testable:
+
+  * `host_preflight(probe)` — refuse-by-name if the board lacks what the route needs (fastrpc / libcdsprpc,
+    the matching-arch HTP lib, the staged glibc loader). The llama.cpp-HTP binaries are built against a
+    newer glibc than the QDC board ships, so they run under an injected loader (`ld-linux-aarch64.so.1
+    --library-path <staged-glibc>:<pkg-lib>:...`). If the loader or the arch lib isn't staged, we say so by
+    name rather than letting the dynamic linker emit a raw error on-device.
+
+  * `dispatch_proof(stdout)` — THE gate (SC-RT03). "It ran" is not "it ran on the NPU": llama.cpp silently
+    falls back to CPU when the Hexagon registry is disabled (`GGML_HEXAGON_NDEV=0`) or a session can't open.
+    This parses the ggml-hex log + the llama-bench table and returns `dispatched=True` ONLY when an HTP0
+    session was opened on the compute-DSP (`_dom=cdsp`) AND a bench row actually executed on device `HTP0`.
+    The CPU-fallback output (ndev 0, no HTP0 session, no `dev` column) returns `dispatched=False` — the gate
+    distinguishes the two, the way the CV gate must FAIL random-noise.
+
+SILICON_RECORD is the proof this adapter is wired on (Principle III: tested-is-a-record, not a badge).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+# --- the proven on-silicon record (Principle I + III) ------------------------------------------------
+# Re-verified on a fresh v73 board through this adapter's recipe on 2026-10-24 (Track 2). The dispatch
+# proof and the PPL both reproduce the earlier sweep: PPL identical to 4 decimals, prefill speedup even
+# larger on this part. This is what promotes the Q8_0-HTP variant from "proven@sweep" to silicon-backed.
+SILICON_RECORD = {
+    "runtime": "llamacpp-htp",
+    "model": "qwen2.5-1.5b",
+    "precision": "Q8_0",
+    "board": "QCS9075 (Dragonwing IQ-9075)",
+    "soc_id": 676,
+    "htp_arch": "v73",
+    "date": "2026-10-24",
+    "gguf_sha256": "cedde4175edae2e9467d8b98d70843e57c8fb101afd54ca773bce022e80f7e4e",
+    "llamacpp_build": "3278e921b",
+    "dispatch": {                      # SC-RT03: Q8_0 MUL_MAT on HTP0, not CPU fallback
+        "htp0_prefill_tps": 592.82,
+        "cpu_prefill_tps": 217.55,
+        "prefill_speedup": 2.72,
+        "htp0_decode_tps": 23.51,      # decode regresses vs CPU on a model this small (memory-bound) — recorded, not hidden
+        "cpu_decode_tps": 28.99,
+    },
+    "quality": {                       # near-lossless vs the model's own f16 (11.6388)
+        "ppl_wikitext_q8_0": 11.6631,
+        "ppl_stderr": 0.49427,
+        "chunks": 16,
+    },
+    # also proven on the earlier sweep: QCS8550 (soc_id 603, v73), PPL 11.6631, prefill 266.74 vs 152.93.
+}
+
+# The glibc the container-built binaries need, staged next to the package (loader injection).
+LOADER = "ld-linux-aarch64.so.1"
+REQUIRED_LOADER_LIBS = ("ld-linux-aarch64.so.1", "libc.so.6", "libstdc++.so.6", "libm.so.6")
+
+
+@dataclass
+class DispatchProof:
+    """The verdict of the on-device dispatch check (SC-RT03)."""
+    dispatched: bool
+    arch: Optional[str] = None            # 'v73' etc., from the ggml-hex log
+    ndev: Optional[int] = None            # Hexagon registry device count (0 => CPU-only)
+    on_cdsp: bool = False                 # an HTP0 session opened on the compute-DSP domain
+    device_rows: List[Dict] = field(default_factory=list)   # bench rows that ran on dev=HTP0
+    reason: str = ""
+
+    def as_record(self) -> Dict:
+        return {"dispatched": self.dispatched, "arch": self.arch, "ndev": self.ndev,
+                "on_cdsp": self.on_cdsp, "device_rows": self.device_rows, "reason": self.reason}
+
+
+_ARCH_RE = re.compile(r"Hexagon Arch version (v\d+)")
+_NDEV_RE = re.compile(r"\bndev (\d+)\b")
+_SESSION_RE = re.compile(r"HTP0 new session")
+_CDSP_RE = re.compile(r"_dom=cdsp")
+
+
+def _parse_bench_rows(stdout: str) -> List[Dict]:
+    """Parse the llama-bench markdown table; return one dict per data row with its columns.
+
+    The table has a header row, a separator row, then data rows, all `|`-delimited. The HTP build names a
+    `dev` column only when a Hexagon device is in play; CPU-fallback output omits it. We key rows by header.
+    """
+    header: Optional[List[str]] = None
+    rows: List[Dict] = []
+    for line in stdout.splitlines():
+        if "|" not in line:
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if set("".join(cells)) <= set("-: "):      # the |---|---| separator
+            continue
+        if header is None:
+            header = cells
+            continue
+        if len(cells) == len(header):
+            rows.append(dict(zip(header, cells)))
+    return rows
+
+
+def dispatch_proof(stdout: str) -> DispatchProof:
+    """THE gate (SC-RT03). Return a DispatchProof: did Q8_0 actually run on the HTP, or fall back to CPU?
+
+    `dispatched` is True only when ALL of: the Hexagon registry had a device (ndev >= 1), an HTP0 session
+    opened on the compute-DSP (`_dom=cdsp`), and at least one bench row executed on device `HTP0`. Any one
+    missing => CPU fallback (or no run), and we say which. This is pure: feed it captured stdout.
+    """
+    arch_m = _ARCH_RE.search(stdout)
+    ndev_m = _NDEV_RE.search(stdout)
+    arch = arch_m.group(1) if arch_m else None
+    ndev = int(ndev_m.group(1)) if ndev_m else None
+    on_cdsp = bool(_SESSION_RE.search(stdout) and _CDSP_RE.search(stdout))
+
+    rows = _parse_bench_rows(stdout)
+    # a device column may be named 'dev' or 'device'
+    def devcell(r: Dict) -> str:
+        return (r.get("dev") or r.get("device") or "").strip()
+    device_rows = [r for r in rows if devcell(r).upper() == "HTP0"]
+
+    if ndev == 0:
+        return DispatchProof(False, arch, ndev, on_cdsp, device_rows,
+                             "Hexagon registry disabled (ndev 0) — ran on CPU, not the NPU")
+    if not on_cdsp:
+        return DispatchProof(False, arch, ndev, on_cdsp, device_rows,
+                             "no HTP0 session opened on the compute-DSP (_dom=cdsp) — not dispatched to the NPU")
+    if not device_rows:
+        return DispatchProof(False, arch, ndev, on_cdsp, device_rows,
+                             "HTP session opened but no bench row executed on device HTP0 — nothing dispatched")
+    tests = ", ".join(f"{r.get('test','?')}={r.get('t/s','?')}t/s" for r in device_rows)
+    return DispatchProof(True, arch, ndev, on_cdsp, device_rows,
+                         f"Q8_0 dispatched to HTP0 on Hexagon {arch} ({tests})")
+
+
+def host_preflight(probe: Dict) -> Tuple[bool, Optional[str]]:
+    """Refuse-by-name if the board can't host the llama.cpp-HTP route. Pure: `probe` is a board capability dict.
+
+    Expected keys: `has_fastrpc` (bool), `has_cdsprpc` (bool), `htp_arch` (str, e.g. 'v73'),
+    `staged_htp_libs` (iterable of arch tags present, e.g. {'v73'}), `staged_loader_libs` (iterable of
+    loader lib filenames staged). Returns (ok, reason-if-not).
+    """
+    if not probe.get("has_fastrpc") or not probe.get("has_cdsprpc"):
+        return False, ("runtime=llamacpp-htp needs fastrpc + libcdsprpc on the board to reach the Hexagon "
+                       "DSP; this image has neither")
+    arch = probe.get("htp_arch")
+    staged = set(probe.get("staged_htp_libs") or ())
+    if arch not in staged:
+        return False, (f"runtime=llamacpp-htp needs libggml-htp-{arch}.so staged for this board's arch "
+                       f"({arch}); staged: {sorted(staged) or 'none'}")
+    missing = [lib for lib in REQUIRED_LOADER_LIBS if lib not in set(probe.get("staged_loader_libs") or ())]
+    if missing:
+        return False, (f"runtime=llamacpp-htp binaries need an injected glibc loader; missing staged libs: "
+                       f"{missing}")
+    return True, None
+
+
+def bench_command(gguf: str, lib_dir: str, loader_dir: str, *, device: str = "HTP0",
+                  ndev: Optional[int] = None, p: int = 64, n: int = 32, r: int = 2) -> List[str]:
+    """The exact loader-injected llama-bench argv proven on silicon. `ndev=0` forces the CPU reference.
+
+    Grounded in the verified run:
+        ADSP_LIBRARY_PATH=<lib_dir> <loader_dir>/ld-linux-aarch64.so.1 \\
+          --library-path <loader_dir>:<lib_dir>:/usr/lib:/lib \\
+          <bin>/llama-bench -m <gguf> [--device HTP0] -p <p> -n <n> -r <r>
+    The caller sets ADSP_LIBRARY_PATH and (for CPU) GGML_HEXAGON_NDEV in the environment.
+    """
+    bin_dir = lib_dir.rsplit("/lib", 1)[0] + "/bin"
+    argv = [f"{loader_dir}/{LOADER}", "--library-path",
+            f"{loader_dir}:{lib_dir}:/usr/lib:/lib", f"{bin_dir}/llama-bench", "-m", gguf]
+    if ndev != 0:
+        argv += ["--device", device]
+    argv += ["-p", str(p), "-n", str(n), "-r", str(r)]
+    return argv

chipwright-0.2.7/chipwright/tests/test_llamacpp_htp.py

@@ -0,0 +1,143 @@
+"""The llama.cpp-HTP adapter: the dispatch gate + host preflight (spec 004 T-RT07 / SC-RT03).
+
+Layer 1 (these tests) proves the LOGIC: the dispatch gate must separate a real HTP0 dispatch from a silent
+CPU fallback, and preflight must refuse-by-name. The fixtures below are the ACTUAL stdout captured on
+silicon (QCS9075 / v73, 2026-10-24) — the HTP run and the `GGML_HEXAGON_NDEV=0` CPU run of the same Q8_0
+model. Layer 2 (the record the fixtures come from) is `llamacpp_htp.SILICON_RECORD`. A gate that can't FAIL
+the CPU-fallback case isn't a gate — so that negative is the central assertion, mirroring the CV gate on
+random noise.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from chipwright import runtimes
+from chipwright.runtimes import llamacpp_htp as lh
+
+# --- real captured stdout (QCS9075 / v73, 2026-10-24) ------------------------------------------------
+HTP_STDOUT = """\
+ggml-hex: Loading driver libcdsprpc.so
+ggml-hex: Hexagon backend (experimental) : allocating new registry : ndev 1
+ggml-hex: Hexagon Arch version v73
+ggml-hex: HTP0 allocating new session
+ggml-hex: HTP0 hwinfo: threads 4, hvx 4, hmx 1, vtcm 8 MB
+ggml-hex: HTP0 new session : session-id 0 domain-id 3 uri file:///libggml-htp-v73.so?htp_iface_skel_handle_invoke&_modver=1.0&_dom=cdsp&_session=0 handle 0x556115f200
+ggml-hex: HTP0 op batching: n-bufs 16 n-tensors 7168 n-ops 1024 vmem 3145728000
+| model                          |       size |     params | backend    | ngl | dev          |            test |                  t/s |
+| ------------------------------ | ---------: | ---------: | ---------- | --: | ------------ | --------------: | -------------------: |
+| qwen2 1.5B Q8_0                |   1.53 GiB |     1.54 B | HTP        |  -1 | HTP0         |            pp64 |       592.82 ± 20.43 |
+| qwen2 1.5B Q8_0                |   1.53 GiB |     1.54 B | HTP        |  -1 | HTP0         |            tg32 |         23.51 ± 0.04 |
+
+build: 3278e921b (10049)
+"""
+
+CPU_STDOUT = """\
+ggml-hex: Loading driver libcdsprpc.so
+ggml-hex: Hexagon backend (experimental) : allocating new registry : ndev 0
+ggml-hex: Hexagon Arch version v73
+| model                          |       size |     params | backend    | ngl |            test |                  t/s |
+| ------------------------------ | ---------: | ---------: | ---------- | --: | --------------: | -------------------: |
+| qwen2 1.5B Q8_0                |   1.53 GiB |     1.54 B | HTP        |  -1 |            pp64 |        217.55 ± 0.02 |
+| qwen2 1.5B Q8_0                |   1.53 GiB |     1.54 B | HTP        |  -1 |            tg32 |         28.99 ± 0.01 |
+
+build: 3278e921b (10049)
+"""
+
+
+def test_dispatch_gate_confirms_real_htp_run():
+    proof = lh.dispatch_proof(HTP_STDOUT)
+    assert proof.dispatched is True
+    assert proof.arch == "v73"
+    assert proof.ndev == 1
+    assert proof.on_cdsp is True
+    # the pp/tg rows actually executed on device HTP0
+    tests = {r["test"] for r in proof.device_rows}
+    assert "pp64" in tests and "tg32" in tests
+
+
+def test_dispatch_gate_FAILS_cpu_fallback():
+    """The whole point: NDEV=0 ran on CPU. The gate must NOT call that an NPU dispatch."""
+    proof = lh.dispatch_proof(CPU_STDOUT)
+    assert proof.dispatched is False
+    assert proof.ndev == 0
+    assert "CPU" in proof.reason or "ndev 0" in proof.reason
+    assert proof.device_rows == []          # no row ran on HTP0
+
+
+def test_dispatch_gate_FAILS_session_without_device_row():
+    """A session can open yet nothing dispatch — still not a pass."""
+    stdout = ("ggml-hex: allocating new registry : ndev 1\n"
+              "ggml-hex: Hexagon Arch version v73\n"
+              "ggml-hex: HTP0 new session : uri file:///libggml-htp-v73.so?_dom=cdsp&_session=0\n"
+              "| model | backend | test | t/s |\n| --- | --- | --- | --- |\n")
+    proof = lh.dispatch_proof(stdout)
+    assert proof.dispatched is False
+    assert "no bench row" in proof.reason
+
+
+def test_silicon_prefill_speedup_is_a_real_win():
+    d = lh.SILICON_RECORD["dispatch"]
+    assert d["htp0_prefill_tps"] > d["cpu_prefill_tps"]      # the Q8_0 route Genie lacks, faster on-chip
+    assert round(d["htp0_prefill_tps"] / d["cpu_prefill_tps"], 2) == d["prefill_speedup"]
+
+
+def test_quality_is_near_lossless():
+    assert abs(lh.SILICON_RECORD["quality"]["ppl_wikitext_q8_0"] - 11.6631) < 1e-4
+
+
+# --- host preflight: refuse-by-name -----------------------------------------------------------------
+_OK_PROBE = {"has_fastrpc": True, "has_cdsprpc": True, "htp_arch": "v73",
+             "staged_htp_libs": {"v73", "v75", "v79", "v81"},
+             "staged_loader_libs": set(lh.REQUIRED_LOADER_LIBS)}
+
+
+def test_preflight_passes_on_the_verified_board():
+    ok, reason = lh.host_preflight(_OK_PROBE)
+    assert ok is True and reason is None
+
+
+def test_preflight_refuses_missing_fastrpc_by_name():
+    probe = dict(_OK_PROBE, has_cdsprpc=False)
+    ok, reason = lh.host_preflight(probe)
+    assert ok is False and "libcdsprpc" in reason
+
+
+def test_preflight_refuses_wrong_arch_lib_by_name():
+    probe = dict(_OK_PROBE, htp_arch="v68", staged_htp_libs={"v73"})
+    ok, reason = lh.host_preflight(probe)
+    assert ok is False and "v68" in reason and "libggml-htp-v68.so" in reason
+
+
+def test_preflight_refuses_missing_loader_by_name():
+    probe = dict(_OK_PROBE, staged_loader_libs={"libc.so.6"})
+    ok, reason = lh.host_preflight(probe)
+    assert ok is False and "loader" in reason
+
+
+# --- adapter registry seam (T-RT03) -----------------------------------------------------------------
+def test_llamacpp_htp_adapter_is_wired():
+    assert "llamacpp-htp" in runtimes.wired_runtimes()
+    assert runtimes.get_adapter("llamacpp-htp") is lh
+
+
+def test_unwired_runtime_refuses_by_name_not_keyerror():
+    import pytest
+    with pytest.raises(NotImplementedError) as ei:
+        runtimes.get_adapter("genie")
+    assert "genie" in str(ei.value)
+
+
+def test_bench_command_matches_the_verified_recipe():
+    argv = lh.bench_command("qwen2.5-1.5b-Q8_0.gguf",
+                            "./pkg-snapdragon/lib", "./glibc238", p=64, n=32, r=2)
+    joined = " ".join(argv)
+    assert argv[0] == "./glibc238/ld-linux-aarch64.so.1"
+    assert "--device HTP0" in joined
+    assert "./pkg-snapdragon/bin/llama-bench" in joined
+    assert "-m qwen2.5-1.5b-Q8_0.gguf" in joined
+
+
+def test_bench_command_cpu_reference_drops_device_flag():
+    argv = lh.bench_command("m.gguf", "./pkg-snapdragon/lib", "./glibc238", ndev=0)
+    assert "--device" not in argv          # the CPU reference run (GGML_HEXAGON_NDEV=0) has no HTP device

chipwright-0.2.7/chipwright/tests/test_runtime_run.py

@@ -0,0 +1,103 @@
+"""The llama.cpp-HTP runtime's resolve + run path, end to end (spec 004 FR-RT07, public promotion).
+
+Layer 1: the public index now carries a silicon-verified Q8_0 llamacpp-htp variant. These assert that
+(a) it resolves USE on v73 when the runtime is chosen and FAILs by name on v68, and (b) `run_variant`
+routes it to the runtime path — fetch/verify + surface the recipe + the record — instead of the Genie
+transport, with no board and no network (a local artifact). The on-silicon proof is the record itself
+(`llamacpp_htp.SILICON_RECORD`), re-verified 2026-10-24 on QCS9075/v73.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from chipwright import cli, jsonout, run as runner
+from chipwright.env import TargetKey
+from chipwright.registry import Registry
+from chipwright.resolver import Outcome, Variant, resolve
+
+
+def _htp_variant(local_path):
+    return Variant(
+        model="qwen2.5-1.5b-instruct", version="1.0.0", arch="v73", quant="Q8_0", shape="ctx4096",
+        sdk_tested="b3278e921", sdk_compatible="llama.cpp-HTP (no QAIRT dependency)", ext="gguf",
+        local=local_path, runtime="llamacpp-htp",
+        runtime_support={"llamacpp-htp": {"v68": "unsupported:needs-v73", "v73": "supported"},
+                         "genie": {"v68": "supported", "v73": "supported"}})
+
+
+# --- resolve (the public variant) -------------------------------------------------------------------
+def test_public_index_has_silicon_verified_q8_0_llamacpp_htp_variant():
+    reg = Registry(None)                              # the bundled public index
+    vs = reg.variants("qwen2.5-1.5b-instruct")
+    htp = [v for v in vs if v.effective_runtime == "llamacpp-htp"]
+    assert htp, "public index must carry the llamacpp-htp variant"
+    v = htp[0]
+    assert v.quant == "Q8_0" and v.arch == "v73" and v.url and v.sha256
+    assert v.verified and v.verified.get("runtime") == "llamacpp-htp"
+
+
+def test_resolve_use_on_v73_when_runtime_chosen():
+    reg = Registry(None)
+    d = resolve(TargetKey("v73", None), reg.variants("qwen2.5-1.5b-instruct"),
+                want_runtime="llamacpp-htp")
+    assert d.outcome == Outcome.USE
+    assert d.variant.effective_runtime == "llamacpp-htp" and d.variant.quant == "Q8_0"
+
+
+def test_resolve_refuses_llamacpp_htp_on_v68_by_name():
+    reg = Registry(None)
+    d = resolve(TargetKey("v68", None), reg.variants("qwen2.5-1.5b-instruct"),
+                want_runtime="llamacpp-htp")
+    assert d.outcome == Outcome.FAIL and d.axis == "runtime"
+    assert "v68" in d.reason and "genie" in d.reason
+
+
+def test_default_runtime_is_the_genie_floor_not_llamacpp():
+    """No --runtime, no priority: the conservative genie floor is chosen (and the user is told to choose)."""
+    reg = Registry(None)
+    d = resolve(TargetKey("v73", None), reg.variants("qwen2.5-1.5b-instruct"))
+    assert d.variant.effective_runtime == "genie"     # Q8_0-HTP is opt-in, never the silent default
+
+
+# --- run (the runtime path) -------------------------------------------------------------------------
+def test_run_variant_routes_llamacpp_htp_to_record_and_recipe(tmp_path):
+    gguf = tmp_path / "qwen2.5-1.5b-Q8_0.gguf"
+    gguf.write_bytes(b"GGUF\x00dummy")
+    rep = runner.run_variant(_htp_variant(str(gguf)))
+    assert rep["runtime"] == "llamacpp-htp" and rep["pass"] is True
+    assert rep["record"]["quality"]["ppl_wikitext_q8_0"] == 11.6631
+    assert "--device" in " ".join(rep["recipe"]) and "HTP0" in " ".join(rep["recipe"])
+    assert rep["cli_execution"] == "recipe" and rep.get("warn")
+
+
+def test_run_variant_refuses_when_no_artifact():
+    import pytest
+    v = _htp_variant(None)
+    v.local = None
+    with pytest.raises(RuntimeError) as ei:
+        runner.run_variant(v)
+    assert "no GGUF artifact" in str(ei.value)
+
+
+def test_human_render_returns_use_with_warn(tmp_path, capsys):
+    from chipwright.resolver import Decision
+    gguf = tmp_path / "m.gguf"
+    gguf.write_bytes(b"GGUF\x00")
+    rep = runner.run_variant(_htp_variant(str(gguf)))
+    code = cli._render_run_report(rep, Decision(Outcome.USE))
+    out = capsys.readouterr().out
+    assert code == jsonout.EXIT_USE_WITH_WARN
+    assert "llamacpp-htp" in out and "2.72" in out and "11.6631" in out
+    assert "Traceback" not in out
+
+
+def test_json_projection_carries_runtime_record(tmp_path):
+    from chipwright.resolver import Decision
+    gguf = tmp_path / "m.gguf"
+    gguf.write_bytes(b"GGUF\x00")
+    rep = runner.run_variant(_htp_variant(str(gguf)))
+    doc = jsonout.run_to_dict("qwen2.5-1.5b-instruct", "v73", Decision(Outcome.USE), rep)
+    assert doc["runtime"] == "llamacpp-htp"
+    assert doc["record"]["dispatch"]["prefill_speedup"] == 2.72
+    assert any("recipe" in w for w in doc.get("warnings", []))

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chipwright
-Version: 0.2.6
+Version: 0.2.7
 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

{chipwright-0.2.6 → chipwright-0.2.7}/chipwright.egg-info/SOURCES.txt

@@ -35,6 +35,8 @@ chipwright/modalities/__init__.py
 chipwright/modalities/asr_encoder.py
 chipwright/modalities/cv.py
 chipwright/modalities/llm.py
+chipwright/runtimes/__init__.py
+chipwright/runtimes/llamacpp_htp.py
 chipwright/tests/conftest.py
 chipwright/tests/test_adapt.py
 chipwright/tests/test_build.py
@@ -46,6 +48,7 @@ chipwright/tests/test_emit_record.py
 chipwright/tests/test_env.py
 chipwright/tests/test_env_adb.py
 chipwright/tests/test_json_cli.py
+chipwright/tests/test_llamacpp_htp.py
 chipwright/tests/test_llm_modality.py
 chipwright/tests/test_packaging.py
 chipwright/tests/test_precision_registry.py
@@ -55,6 +58,7 @@ chipwright/tests/test_replay.py
 chipwright/tests/test_resolver.py
 chipwright/tests/test_run_llm.py
 chipwright/tests/test_run_render.py
+chipwright/tests/test_runtime_run.py
 chipwright/tests/test_runtime_support.py
 chipwright/tests/test_security.py
 chipwright/tests/test_tags.py

{chipwright-0.2.6 → chipwright-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chipwright"
-version = "0.2.6"
+version = "0.2.7"
 description = "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."
 readme = "README.md"
 license = "MIT"
@@ -41,7 +41,7 @@ Specification = "https://github.com/nameissakthi25/chipwright-speckit"
 chipwright = "chipwright.cli:main"
 
 [tool.setuptools]
-packages = ["chipwright", "chipwright.modalities", "chipwright.tests"]
+packages = ["chipwright", "chipwright.modalities", "chipwright.runtimes", "chipwright.tests"]
 
 [tool.setuptools.package-data]
 # The portable public registry index ships inside the package (see registry.py::DEFAULT_INDEX).