chipwright 0.2.0__py3-none-any.whl

chipwright-0.2.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: chipwright
+Version: 0.2.0
+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
+Project-URL: Specification, https://github.com/nameissakthi25/chipwright-speckit
+Keywords: npu,qualcomm,hexagon,qnn,edge-ai,quantization,inference,package-manager
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Requires-Dist: numpy>=1.24
+Provides-Extra: asr
+Requires-Dist: onnxruntime>=1.16; extra == "asr"
+Provides-Extra: cv
+Requires-Dist: onnxruntime>=1.16; extra == "cv"
+Requires-Dist: pillow>=10; extra == "cv"
+Provides-Extra: tts
+Requires-Dist: onnxruntime>=1.16; extra == "tts"
+Provides-Extra: llm
+Requires-Dist: onnxruntime>=1.16; extra == "llm"
+Requires-Dist: tokenizers>=0.19; extra == "llm"
+Provides-Extra: eval
+Requires-Dist: qai-hub-models>=4.5; extra == "eval"
+Provides-Extra: build
+Requires-Dist: onnx>=1.14; extra == "build"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# Chipwright
+
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![verified on QCS6490](https://img.shields.io/badge/verified%20on-QCS6490-brightgreen.svg)](#tested-is-a-record-not-a-badge)
+
+**A verified package manager and model hub for NPUs.** Chipwright reads your board, hands you an artifact that will actually load on your exact chip, and proves it against a CPU reference before you trust the output.
+
+`resolve · run · build` — Qualcomm first, cross-vendor by design.
+
+```mermaid
+flowchart LR
+    M([model]):::io
+    B([your board<br/>arch · SDK · SoC]):::io
+    M --> R{{resolve}}:::core
+    B --> R
+    R -->|exact · in-range| RUN[run on the NPU]:::step
+    R -->|no artifact,<br/>recipe exists| BLD[build<br/>convert · quantize<br/>on-board context]:::step
+    R -->|nothing fits| FAIL([refuse —<br/>name the axis]):::bad
+    BLD --> RUN
+    RUN --> V{{verify<br/>NPU vs CPU cosine}}:::core
+    V -->|≥ threshold| OK([trusted artifact]):::good
+    V -->|below| NO([caught, not shipped]):::bad
+
+    classDef io fill:#1f2430,stroke:#8a919e,color:#e8eaee;
+    classDef core fill:#7c3f1d,stroke:#b4632f,color:#fde8d7;
+    classDef step fill:#222a36,stroke:#4b5563,color:#e2e8f0;
+    classDef good fill:#14321f,stroke:#2d7d54,color:#86efac;
+    classDef bad fill:#3b1a16,stroke:#b23a2c,color:#f5a3a3;
+```
+
+---
+
+## The problem
+
+On an NPU, a model isn't a file. It's a context binary pinned to a precise tuple: **architecture × SDK × quantization × shape × backend**. Load it on the wrong chip, or the wrong SDK, and it fails at load — or worse, it loads and quietly returns a fast wrong answer.
+
+A model hub tells you *which model*. It can't tell you *which chip*. The gap between "here is a checkpoint" and "here is something that runs correctly on the board in your hand" is where edge ML projects stall.
+
+Chipwright closes that gap. Think of it as **PyPI wheel tags for NPUs**: the chip is the platform tag. You don't hand-pick a binary and hope — you ask the resolver, and it either gives you one that matches or tells you, by name, the axis that doesn't.
+
+---
+
+## Quickstart
+
+```bash
+pip install -e .
+```
+
+Point Chipwright at a board (over SSH) and probe it:
+
+```bash
+export CW_BOARD_HOST=192.168.1.50
+export CW_BOARD_PASS=…
+
+chipwright doctor
+```
+
+```text
+● board reachable  root@192.168.1.50:22
+  SoC         : QCS6490 (soc_id 498)
+  Hexagon arch: v68
+  QNN libs    : libQnnHtp.so  (QAIRT 2.38.0)
+  target key  : htpv68,qnn2.38
+```
+
+Resolve a model against that exact board — no guessing:
+
+```bash
+chipwright resolve whisper-small-en
+```
+
+```text
+model   : whisper-small-en
+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
+```
+
+Then run it on the board and verify the NPU output against a CPU reference:
+
+```bash
+chipwright run zipformer-enin --input utterance.npy
+```
+
+```text
+model   : zipformer-enin
+target  : htpv68,qnn2.38
+✔ USE    zipformer-enin-7.0.0  htpv68/w8a16/win39  qnn2.37.1  (exact match)
+
+✔ VERIFIED  NPU vs CPU-reference  cosine_min = 0.98800  (threshold 0.95)
+    encoder: 0.98800
+```
+
+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.
+
+---
+
+## The three verbs
+
+| Verb | What it does |
+| --- | --- |
+| **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. |
+
+---
+
+## The four resolve outcomes
+
+The resolver is deliberately honest. Every resolution lands in exactly one of four outcomes:
+
+- **USE** — an exact match on arch, quant, and shape, with the board's SDK inside the compatible range. Run it.
+- **USE-with-warning** — a match, but the board's SDK sits outside the *tested* point while staying inside the compatible range. You get the artifact and the caveat, both.
+- **BUILD** — no hosted artifact for your chip, but a recipe exists that can produce one.
+- **FAIL** — nothing fits, and the message names the axis:
+
+  ```text
+  ✗ FAIL  axis=htp_arch: no variant for v68; registry has [v73]
+  ```
+
+The arch axis is hard — a mismatch fails at load, so the resolver refuses. The SDK axis is a range, not a point — so outside the tested point the resolver warns rather than refuses. That distinction is the whole discipline: **never downgrade to a near-miss artifact silently.**
+
+---
+
+## Artifact tags
+
+An artifact's identity is its name. Chipwright names the five axes a resolver matches on in the filename and expands the rest in the manifest — exactly how a PyPI wheel names `cp312-manylinux_x86_64` and leaves the rest to metadata:
+
+```text
+whisper-small-en-1.2.0+qnn2.37-htpv68-w8a16-win30s.qnnctx
+└──────┬───────┘ └─┬─┘ └──┬──┘ └──┬──┘ └─┬─┘ └─┬─┘ └─┬──┘
+     name       version  sdk    arch   quant  shape  ext
+```
+
+Parsing is strict: a tag that doesn't parse is a bug, not a near-miss to paper over.
+
+---
+
+## Tested is a record, not a badge
+
+Chipwright does not stamp a green checkmark and ask you to believe it. Every registry variant carries a **verification record** — which board it ran on, what it was compared to, and the numbers — so a reader who distrusts the claim can check the inputs.
+
+The record for `zipformer-enin`, from a live run:
+
+```yaml
+verified:
+  on: "QCS6490 (soc_id 498)"
+  date: 2026-10-08
+  loads: true
+  vs_reference:
+    backend: onnxruntime-cpu
+    metric: encoder_cosine
+    value: 0.988           # threshold 0.95 — VERIFIED
+```
+
+A high cosine is necessary, not sufficient — a cosine of 0.99 can still cost task accuracy — so the record keeps the numerical check separate from the task metric. The point is not the badge. The point is that the evidence travels with the artifact.
+
+---
+
+## Architecture
+
+One front door today, one core, three targets.
+
+- **The front door** — the `chipwright` CLI (`doctor · resolve · run · build`), a thin surface over the core. The core is deliberately UI-agnostic so other surfaces (a desktop app, editor integrations) can call the same logic later without reimplementing it; today the CLI is what ships.
+- **One core** — [`chipwright-core`](chipwright/) holds all the logic: tags, board probe, resolver, registry client, cache, device transport, verification, and the run loop.
+- **Three targets** — the core reaches the **registry** (the index of verified variants), the **board** (probe and execute), and the **build-host** (produce an artifact from a recipe).
+
+See [`docs/architecture.md`](docs/architecture.md) for the diagram and the module map.
+
+---
+
+## Repo layout
+
+```text
+chipwright/
+  cli.py          the `chipwright` CLI — doctor · resolve · run · build
+  tags.py         wheel-tag grammar for NPU artifacts (parse / format)
+  env.py          board probe → TargetKey (arch × SDK × SoC)
+  resolver.py     match variants to a target; the four outcomes
+  registry.py     read the index (a git-repo file), list a model's variants
+  cache.py        content-addressed artifact cache (~/.cache/chipwright)
+  device.py       remote QNN runner — push + execute over SSH
+  verify.py       NPU-vs-CPU cosine; the check that catches a fast wrong answer
+  run.py          the run verb — ties resolve · device · modality · verify
+  modalities/     per-task glue (frontend, decoders, CPU reference)
+registry/
+  index.yaml      the registry index — one reviewable file, variants by hash
+```
+
+---
+
+## Status
+
+- ✅ **resolve** — done, with the four honest outcomes, offline targets, and axis-named failures.
+- ✅ **run** — done and **verified on hardware**, six real models pulled from Hugging Face, on a live QCS6490 / RB3 Gen2:
+
+  | model | task | quant | cosine |
+  |---|---|---|---|
+  | `zipformer-enin` | ASR (streaming RNN-T) | w8a16 | **0.988** |
+  | `mobilenet-v2` | image classification | w8a16 | **0.956** |
+  | `quicksrnet-small` | super-resolution | w8a8 | **0.9999** |
+  | `fcn-resnet50` | semantic segmentation | w8a8 | **0.998** |
+  | `depth-anything-v2` | depth estimation (DINOv2 **ViT**) | w8a16 | **0.99996** |
+  | `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.
+
+**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.
+
+### Modality roadmap
+
+```text
+ASR  →  TTS  →  VLM  →  LLM  →  VLA
+ ▲
+ verified on hardware today
+```
+
+---
+
+## Vendor-neutrality
+
+Chipwright is Qualcomm first because that is where the hardware and the proof are today. It is cross-vendor by design: the tag grammar, the resolver's axis model, the verification record, and the device transport are not tied to one silicon vendor. Adding a backend means adding a target adapter and its arch axis — not reworking the framework.
+
+The specification lives in a separate repo, the **spec kit** (`chipwright-speckit`, in GitHub Spec Kit format). Changes are spec-first: the spec kit moves before the code.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Contributions welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).

chipwright-0.2.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+chipwright/__init__.py,sha256=4wfGz68eXNIIBdFbX1gS9_e_XsX0fZdfvRUYmmxWfnM,500
+chipwright/adapt.py,sha256=1MDkDv8S9y9zE9DYD9Tjmq0x79MIQ0ajORu-XaTgjDM,2158
+chipwright/build.py,sha256=Oi1luyiMbYPmPSDX1ui9sJ1br_PBRGqclGaiMlM4M5g,16293
+chipwright/cache.py,sha256=mABbmd1i2_GGyh7PbUWYJaDJ4lynZlmDDcfvYeeUYiA,2457
+chipwright/cli.py,sha256=0HbW4BUFlNmQh61Ue6kUisN9h_X2FrL3QsTSYpooO3A,10319
+chipwright/config.py,sha256=VlXfF6HcuhiuahZ15MrIm6Xw9-5nvZOt7Gm7nk6INTs,4672
+chipwright/device.py,sha256=c_urAp9d3yRLILTI3pJwYNSe91tgu56mh3AVcykodJw,7891
+chipwright/device_adb.py,sha256=_Y_m8azEXz6bPIV7k6ziBrK_RTjSbJso18_9Iu3a-ZA,6264
+chipwright/env.py,sha256=r4REkZXEiVmY00_2pGFMkr1i9LRr9mEO8lkIfN70MiM,11650
+chipwright/errors.py,sha256=F2b7-aUX7ZfCdzGT2cQ6MjXow6Q6K3wMTIhPTo9u-RM,1610
+chipwright/llm_reference.py,sha256=Bd2MhceZdbL-GFSywxbBCuiC3HjlMf6lS6T_Kih_GKQ,5987
+chipwright/recipe.py,sha256=aEaCqk9CZCa0H39Atq0HJ7WGRZB9yXgJUhSx68l5lmc,8723
+chipwright/registry.py,sha256=NzIlv1bcy5pvSHx4Bfh5EuUW7OJQPONPW8JV-xOtNow,2515
+chipwright/resolver.py,sha256=zL6t5KtkuWrg3x4Vb9GXMUbtyznk_bVyW11G2jx5hZw,9175
+chipwright/run.py,sha256=d2QC690RaN-g6IpfO_Jc8YU4YRRPd8ahdbAUduopBd4,8738
+chipwright/sdk.py,sha256=BChTgzRL7yj6QWi3Yg7DH4p0rzECk5nR17gK1AnZQuI,7426
+chipwright/tags.py,sha256=It1CUK_1NwF7jZgDC-JkGBk94QXr6xPrfhTlKsnhOCQ,2271
+chipwright/task_eval.py,sha256=CZl-BI-_BOEKJW_rrCSZG8f8Hbb7engrzCE8vhubEnA,10965
+chipwright/verify.py,sha256=x7KiXYwGUTu3Ux_XCkL0uQkYgdbumO_07ta48CxOltk,1031
+chipwright/verify_llm.py,sha256=wQs85ucmQkDvwuwhXZiAI-6wUAK9mxZPtk1AYl_ThmY,10483
+chipwright/data/behavior_prompts.yaml,sha256=jLFa9sYggY98rxERCBSScjNXp5fHarbBlDrTURMBtIY,7872
+chipwright/data/index.yaml,sha256=CFS6zpdprIcRBCvadQwgNn9Px9_FK8W2__d4Yn6-HhM,8669
+chipwright/modalities/__init__.py,sha256=PjK1e4j4CNz1_hFJ6zR1fctA_dOkPqjBzBZoxj2EyLs,185
+chipwright/modalities/asr_encoder.py,sha256=_yr4qVBn7Qrmtq_pqNvLmcjOLAj-3h4xroZ08XSaAIc,4016
+chipwright/modalities/cv.py,sha256=Wxl_-gmU0E6cqKAPtxnG8mXchlrslzsbcQbUGuHdEzs,1669
+chipwright/modalities/llm.py,sha256=D911Eew_tThZpVRc1hUYSS_2YVZgWijPaR33uSIO0SY,16096
+chipwright/tests/conftest.py,sha256=N1gwwU2odf6HWHdK4gEAOhott36ljMTLmgU4-Yktid8,518
+chipwright/tests/test_adapt.py,sha256=pYK2IESCVxIdpsxIjvVddbETIPJxg9yREAOH6ytD8XY,2236
+chipwright/tests/test_build.py,sha256=BMZvM6rJf-xXFScPEmn3EyMAnU7MI5lKHoVqkkQTX3Y,10757
+chipwright/tests/test_cache.py,sha256=PUirZlCdkvkUL42sTCBHbZF1dxKdk5CdsgQcMgLiqAg,5293
+chipwright/tests/test_device_adb.py,sha256=yJMp7ZGrUWg83WITWO3GPI3r57tb9XTqJQzlXVYJcMk,4800
+chipwright/tests/test_env.py,sha256=Z8Afb3pMNBPWEc2srI8KCy8N2USgZFYTQSazvC7QEuA,2336
+chipwright/tests/test_env_adb.py,sha256=hBZzp8VbP4c3Dl2MAJ9g10u9yO6sV5g4a6LVZHKuT4M,4039
+chipwright/tests/test_llm_modality.py,sha256=orWEpXAPqX8MbX7CLoVTfWdm6PoCEz34SveJUL0nO4Y,10981
+chipwright/tests/test_packaging.py,sha256=v1JDsHnbbzqLeFhKV-rLM0nIux4tvd00f-MV8iuVudE,7260
+chipwright/tests/test_precision_support.py,sha256=QdeX8HiYmsYTSRTRkCExzqrT8xgOPWirbQx2ZbUhigc,5186
+chipwright/tests/test_registry.py,sha256=MlYTo9DmFzf2MDdXMmhqUNGGNK2-0cDDCWKb2Yhq-rs,3475
+chipwright/tests/test_resolver.py,sha256=P335bla-1VXDMq7YeaxaHyQlJw7An-SFT-G92nW1H04,3415
+chipwright/tests/test_run_llm.py,sha256=wkAEFfEibblXh0wkO9mRVyMNIbkBL9cVbvWEAJ_5Iqw,1959
+chipwright/tests/test_tags.py,sha256=Yb7TkewLaDNiAeWqdxaALLDLQKHAOu8lDDnd_9OMIvU,3059
+chipwright/tests/test_task_eval.py,sha256=h3lL67WCrepqhlenhOQy23WP1BXQ1jPPjJ-JvhX6Tuc,6677
+chipwright/tests/test_verify.py,sha256=Foat-s75Atjmn2g9wnU1EmsA_8o34V6YZASIMJDYYiU,3113
+chipwright/tests/test_verify_llm.py,sha256=ifBKBiFqxKNBn9maleRNTFlRwnXqkCtki9A9n4BBhUo,8623
+chipwright-0.2.0.dist-info/licenses/LICENSE,sha256=exndoctXKjFD4v_r8NjB7UKo_5Mr3TNf14TQw5M1e4I,1080
+chipwright-0.2.0.dist-info/METADATA,sha256=ow691sxMlZFgAYX6UJ22n0gTSw6BdfgjNQ4HYiHDN8M,12685
+chipwright-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+chipwright-0.2.0.dist-info/entry_points.txt,sha256=fQ-tHA5T5uWaC8FgxEO-fa7M1p4_azVAQ8YVrqPiuys,51
+chipwright-0.2.0.dist-info/top_level.txt,sha256=ZBNCkKg5jz-2IdPMVWFdBXncwCGFay2yyePdCRk0BWM,11
+chipwright-0.2.0.dist-info/RECORD,,

chipwright-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chipwright-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chipwright = chipwright.cli:main

chipwright-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chipwright contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chipwright-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chipwright