chipwright 0.2.0__py3-none-any.whl

chipwright/data/index.yaml

@@ -0,0 +1,327 @@
+# Chipwright registry — the index is a single reviewable file; artifacts live by hash in object storage.
+# The registry's unit is a BUILD VARIANT, not a model: one model version fans out to many artifacts,
+# one per (arch × quant × shape × SDK-range). "verified:" is a record, not a badge — the evidence of
+# the run that validated the variant, so a reader who distrusts the claim can check the inputs.
+#
+# Board context for every verified record below: QCS6490 / RB3 Gen2, Hexagon v68, QAIRT 2.38.0.
+# The HTP is w8a16-only on v68 (no fp16); LLMs go all-integer w4a16. Our artifacts are built and
+# tested at QAIRT 2.37.1 with a compatible range >=2.34,<2.40, so the board's in-field 2.38.0 is
+# in-range (resolves USE_WITH_WARN, not a refusal).
+registry_schema: 1
+models:
+- model: laya-decision
+  source: convaiinnovations/laya
+  license: apache-2.0
+  modality: typed-decision
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: win256
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    url: https://huggingface.co/nameissakthi/laya-qcs6490-encoder/resolve/main/ctx/laya_encoder_256_sqnr_ctx.bin
+    sha256: b338a4067e9d9d3147aa8e016892450e51018de6db425ef2e3a4e533a4548a54
+    verified:
+      'on': QCS6490
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu
+        metric: hidden_state_pearson
+        value: 0.88
+      latency_ms:
+        p50: 84
+- model: laya-intent
+  source: convaiinnovations/laya
+  license: apache-2.0
+  modality: intent-slot
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: win256
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/laya-intent/1.0.0.yaml
+    verified:
+      'on': QCS6490 (soc_id 498)
+      loads: true
+      vs_reference:
+        metric: top1_vs_fp32
+        value: 1.0
+        ptq_baseline: 0.425
+      task_metric:
+        name: intent_top1
+        value: 1.0
+        note: held-out synthetic test; fp32 also ~100% — proves QAT removed the on-device quantization loss, not real-world accuracy
+      latency_ms:
+        note: 120 inputs in ~3s on-device
+- model: zipformer-enin
+  source: nameissakthi/zipformer-enin-qairt-aimet
+  license: apache-2.0
+  modality: asr
+  version: 7.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: win39
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    run:
+      modality: asr_encoder
+      board_name: zipformer_encoder_w8a16_ctx.bin
+      threshold: 0.95
+    recipe: recipes/zipformer-enin/7.0.0.yaml
+    verified:
+      'on': QCS6490 (soc_id 498)
+      date: 2026-10-08
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu-float
+        metric: wer_delta
+        htp_wer: 0.27
+        cpu_float_wer: 0.287
+        note: w8a16 ~lossless vs float
+      latency_ms:
+        note: enc ~16.4 ms/chunk, RTF ~0.05 persistent-context
+- model: supertonic-tts
+  source: supertonic/supertonic-tts
+  license: apache-2.0
+  modality: tts
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: multigraph
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/supertonic-tts/1.0.0.yaml
+    verified:
+      'on': QCS6490 (soc_id 498)
+      loads: true
+      vs_reference:
+        metric: logmel_corr_dtw
+        value: 0.77
+      latency_ms:
+        note: ~3.8s wall / 3.07s audio, cold
+      note: small residual buzz; w8a16 flow-matching vocoder
+- model: whisper-small-en
+  source: openai/whisper-small.en
+  license: mit
+  modality: asr
+  version: 1.2.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: win30s
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/whisper-small-en/1.2.0.yaml
+- model: qwen2.5-1.5b-instruct
+  source: Qwen/Qwen2.5-1.5B-Instruct
+  license: apache-2.0
+  modality: llm
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w4a16
+    shape: ctx4096
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/qwen2.5-1.5b/1.0.0.yaml
+  - arch: v73
+    quant: w4a16
+    shape: ctx4096
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/qwen2.5-1.5b/1.0.0.yaml
+- model: qwen2.5-7b-instruct
+  source: Qwen/Qwen2.5-7B-Instruct
+  license: apache-2.0
+  modality: llm
+  version: 1.0.0
+  variants:
+  - arch: v73
+    quant: w4a16
+    shape: ctx4096
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/qwen2.5-7b/1.0.0.yaml
+  - arch: v75
+    quant: w4a16
+    shape: ctx4096
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: qnnctx
+    recipe: recipes/qwen2.5-7b/1.0.0.yaml
+- model: mobilenet-v2
+  source: qualcomm/MobileNet-v2
+  license: bsd-3-clause
+  modality: cv-classifier
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: img224
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: mobilenet
+      meta: ''
+      threshold: 0.95
+    verified:
+      'on': QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu-float
+        metric: cosine_min
+        value: 0.956
+        note: real image (ImageNet 'Samoyed'); random-noise input gives 0.776 and the gate correctly FAILs it
+      latency_ms:
+        note: single 224x224 image; DLC compiled to context on-board
+- model: quicksrnet-small
+  source: qualcomm/QuickSRNetSmall
+  license: bsd-3-clause
+  modality: cv-superres
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a8
+    shape: img128
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: quicksrnet
+      meta: ''
+      threshold: 0.9
+    verified:
+      'on': QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu-float
+        metric: cosine_min
+        value: 0.9999
+        note: 4x super-resolution; w8a8 upscaled image is near-lossless vs float
+      latency_ms:
+        note: 128x128 -> 512x512; DLC compiled to context on-board
+- model: fcn-resnet50
+  source: qualcomm/FCN-ResNet50
+  license: bsd-3-clause
+  modality: cv-segmentation
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a8
+    shape: img520
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: fcn
+      meta: ''
+      threshold: 0.9
+    verified:
+      'on': QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu-float
+        metric: cosine_min
+        value: 0.998
+        note: per-pixel semantic mask; w8a8 near-lossless vs float
+      latency_ms:
+        note: 520x520; DLC compiled to context on-board (spills to DDR)
+- model: mobilenet-cv-built
+  source: qualcomm/MobileNet-v2
+  license: bsd-3-clause
+  modality: cv-classification
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: img224
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: mobilenet_built
+      meta: ''
+      threshold: 0.95
+    verified:
+      'on': QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu-float
+        metric: cosine_min
+        value: 0.956
+        note: the artifact chipwright BUILT (real qairt-converter on the A100) then verified on the board — full build->run->verify
+          loop
+      latency_ms:
+        note: built via dlc_route; context compiled on-board
+- model: depth-anything-v2
+  source: qualcomm/Depth-Anything-V2
+  license: apache-2.0
+  modality: cv-depth
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: img518
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: depth
+      meta: ''
+      threshold: 0.9
+    verified:
+      "on": QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu
+        metric: depth_cosine
+        value: 0.99996
+- model: movenet
+  source: qualcomm/MoveNet
+  license: apache-2.0
+  modality: cv-pose
+  version: 1.0.0
+  variants:
+  - arch: v68
+    quant: w8a16
+    shape: img192
+    sdk_tested: 2.37.1
+    sdk_compatible: '>=2.34,<2.40'
+    ext: dlc
+    run:
+      modality: cv
+      board_name: pose
+      meta: ''
+      threshold: 0.9
+    verified:
+      "on": QCS6490 (soc_id 498)
+      date: 2026-10-09
+      loads: true
+      vs_reference:
+        backend: onnxruntime-cpu
+        metric: keypoint_cosine
+        value: 0.91607

chipwright/device.py

@@ -0,0 +1,143 @@
+"""Remote QNN runner — push a context binary to the board and execute it over SSH.
+
+The device transport the `run` verb uses. It is deliberately quantization-agnostic: it moves raw
+bytes in the graph's native dtype and runs `qnn-net-run --retrieve_context`. Quant/dequant belongs
+to the modality runner, which owns the artifact's I/O scales. (Generalized from the proven
+board-side driver; here it drives the board from the host.)
+"""
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+
+import numpy as np
+
+
+def _require_sshpass():
+    """`sshpass` is a system binary (not a pip package) the SSH transport shells out to.
+
+    Fail here, by name, with the install hint — not later with a cryptic FileNotFoundError from
+    subprocess — so a missing system dependency is reported the way the framework reports everything:
+    plainly, naming the fix.
+    """
+    if shutil.which("sshpass") is None:
+        raise RuntimeError(
+            "chipwright run needs the `sshpass` system binary to reach the board over SSH, and it "
+            "is not on PATH. Install it: `brew install hudochenkov/sshpass/sshpass` (macOS) or "
+            "`apt-get install sshpass` (Debian/Ubuntu).")
+
+
+def _ssh(pw, port, dest, *cmd, timeout=600, capture=True):
+    base = ["sshpass", "-p", pw, "ssh", "-o", "StrictHostKeyChecking=no",
+            "-o", "UserKnownHostsFile=/dev/null", "-o", "ConnectTimeout=20",
+            "-o", "PreferredAuthentications=password", "-o", "PubkeyAuthentication=no",
+            "-p", str(port), dest, *cmd]
+    return subprocess.run(base, capture_output=capture, text=True, timeout=timeout)
+
+
+def _scp(pw, port, *args, timeout=1800):
+    base = ["sshpass", "-p", pw, "scp", "-P", str(port), "-o", "StrictHostKeyChecking=no",
+            "-o", "UserKnownHostsFile=/dev/null", "-o", "ConnectTimeout=20",
+            "-o", "PreferredAuthentications=password", "-o", "PubkeyAuthentication=no", *args]
+    return subprocess.run(base, capture_output=True, text=True, timeout=timeout)
+
+
+class RemoteQNN:
+    def __init__(self, host, user, pw, port=22, backend="/usr/lib/libQnnHtp.so",
+                 board_dir="/opt/chipwright"):
+        _require_sshpass()
+        self.host, self.user, self.pw, self.port = host, user, pw, int(port)
+        self.backend, self.board_dir = backend, board_dir
+        self.dest = f"{user}@{host}"
+
+    def _retry(self, fn, tries=4, wait=3):
+        last = None
+        for i in range(tries):
+            try:
+                r = fn()
+                if getattr(r, "returncode", 0) == 0:
+                    return r
+                last = r
+            except Exception as e:  # pragma: no cover
+                last = e
+            time.sleep(wait)
+        return last
+
+    def ensure_ctx(self, local_path, name):
+        """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.
+        """
+        self._retry(lambda: _ssh(self.pw, self.port, self.dest, f"mkdir -p {self.board_dir}", timeout=40))
+        if local_path.endswith(".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)
+            if "OK" not in (present.stdout or ""):
+                r = self._retry(lambda: _scp(self.pw, self.port, local_path, f"{self.dest}:{dlc_board}"))
+                if getattr(r, "returncode", 1) != 0:
+                    raise RuntimeError(f"failed to push DLC: {getattr(r,'stderr','')}")
+                env = "export ADSP_LIBRARY_PATH=/usr/lib/rfsa/adsp:/usr/lib LD_LIBRARY_PATH=/usr/lib"
+                gen = (f"cd {self.board_dir} && {env} && rm -rf ctx_{name} && "
+                       f"qnn-context-binary-generator --backend {self.backend} "
+                       f"--model /usr/lib/libQnnModelDlc.so --dlc_path {name} "
+                       f"--binary_file {name}_ctx --output_dir ctx_{name}")
+                g = self._retry(lambda: _ssh(self.pw, self.port, self.dest, gen, timeout=1200))
+                check = _ssh(self.pw, self.port, self.dest, f"test -f {ctx_board} && echo OK", timeout=40)
+                if "OK" not in (check.stdout or ""):
+                    raise RuntimeError("on-board context-gen failed:\n" + (getattr(g, "stdout", "") or "")[-500:])
+            return ctx_board
+        board_path = f"{self.board_dir}/{name}"
+        present = _ssh(self.pw, self.port, self.dest, f"test -f {board_path} && echo OK", timeout=40)
+        if "OK" not in (present.stdout or ""):
+            r = self._retry(lambda: _scp(self.pw, self.port, local_path, f"{self.dest}:{board_path}"))
+            if getattr(r, "returncode", 1) != 0:
+                raise RuntimeError(f"failed to push context binary: {getattr(r,'stderr','')}")
+        return board_path
+
+    def run(self, ctx_board_path, feeds_native, outputs, native_io=True):
+        """feeds_native: {name: ndarray}. outputs: [{name,dtype,shape}]. Returns {name: ndarray[shape]}.
+
+        native_io=True: raws are the graph's native quantized dtype (the modality quantizes/dequantizes).
+        native_io=False: feed float32, let qnn-net-run quantize the input and dequantize the output —
+        the simple path for graphs with float I/O semantics (e.g. an image classifier).
+        """
+        dt = {"uint16": np.uint16, "int32": np.int32, "float32": np.float32}
+        with tempfile.TemporaryDirectory() as td:
+            parts = []
+            for n, a in feeds_native.items():
+                np.ascontiguousarray(a).tofile(f"{td}/{n}.raw")
+                parts.append(f"{n}:={n}.raw")
+            open(f"{td}/il.txt", "w").write(" ".join(parts) + "\n")
+            rdir = f"{self.board_dir}/req_{int(time.time()*1000)}"
+            self._retry(lambda: _ssh(self.pw, self.port, self.dest, f"mkdir -p {rdir}", timeout=40))
+            files = [f"{td}/{f}" for f in os.listdir(td)]
+            r = self._retry(lambda: _scp(self.pw, self.port, *files, f"{self.dest}:{rdir}/"))
+            if getattr(r, "returncode", 1) != 0:
+                raise RuntimeError("failed to push inputs")
+            env = "export ADSP_LIBRARY_PATH=/usr/lib/rfsa/adsp:/usr/lib LD_LIBRARY_PATH=/usr/lib"
+            flags = " --use_native_input_files --use_native_output_files" if native_io else ""
+            cmd = (f"cd {rdir} && {env} && qnn-net-run --backend {self.backend} "
+                   f"--retrieve_context {ctx_board_path} --input_list il.txt --output_dir out" + flags)
+            run = self._retry(lambda: _ssh(self.pw, self.port, self.dest, cmd, timeout=600))
+            if getattr(run, "returncode", 1) != 0:
+                _ssh(self.pw, self.port, self.dest, f"rm -rf {rdir}", timeout=30)
+                raise RuntimeError("qnn-net-run failed:\n" + (getattr(run, "stdout", "") or "")[-500:])
+            self._retry(lambda: _scp(self.pw, self.port, "-r", f"{self.dest}:{rdir}/out", td))
+            _ssh(self.pw, self.port, self.dest, f"rm -rf {rdir}", timeout=30)
+            res = {}
+            for spec in outputs:
+                nm, d, sh = spec["name"], dt[spec.get("dtype", "float32")], tuple(spec["shape"])
+                fs = (glob.glob(f"{td}/out/**/{nm}_native.raw", recursive=True)
+                      or glob.glob(f"{td}/out/**/{nm}.raw", recursive=True)
+                      or glob.glob(f"{td}/out/**/{nm}*.raw", recursive=True))
+                if not fs:
+                    raise RuntimeError(f"missing output {nm}")
+                res[nm] = np.fromfile(fs[0], d).reshape(sh)
+            return res

chipwright/device_adb.py

@@ -0,0 +1,121 @@
+"""ADB transport — push an LLM bundle to an Android board and drive it over adb.
+
+The device layer the `llm` modality uses. The existing SSH transport (`device.py::RemoteQNN`) reaches
+a Linux board (QCS6490/RB3, the QDC fleet) over `ssh`/`scp`; a Snapdragon *phone* class target speaks
+`adb` instead. This module is the adb parallel — same shape (`shell`/`push`/`pull`/`exists`,
+retry-wrapped, a preflight that fails by name) so the modality can hold one interface and pick a
+transport by target, exactly as the resolver holds one grammar across arches.
+
+Two things are deliberate and load-bearing (both learned on real silicon, see spec 002 edge cases):
+
+  * **push one file at a time.** A single multi-GB `adb push` of a *directory* (an LLM Genie bundle is
+    N context binaries, often several GB) can wedge the device's adb daemon — the push stalls and every
+    later command hangs. `push_file` moves exactly one regular file and refuses a directory by name, so
+    the modality walks the bundle file-by-file rather than handing adb a tree that bricks the session.
+  * **`adb` is a system binary, not a pip dep.** Like `sshpass` for the SSH transport, it is shelled
+    out to; `_require_adb()` fails here, by name, with the install hint — not later with a cryptic
+    FileNotFoundError from subprocess.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import time
+
+
+def _require_adb():
+    """`adb` is a system binary (Android platform-tools), not a pip package, the transport shells to.
+
+    Fail here, by name, with the install hint — mirroring `device.py::_require_sshpass` — so a missing
+    system dependency is reported the way the framework reports everything: plainly, naming the fix.
+    """
+    if shutil.which("adb") is None:
+        raise RuntimeError(
+            "chipwright llm needs the `adb` system binary to reach the board over Android Debug "
+            "Bridge, and it is not on PATH. Install the Android platform-tools: "
+            "`brew install --cask android-platform-tools` (macOS) or "
+            "`apt-get install android-tools-adb` (Debian/Ubuntu).")
+
+
+class AdbDevice:
+    """Drive one Android board over adb. `serial` disambiguates when several are attached.
+
+    The surface the LLM modality calls: `shell(cmd) -> CompletedProcess`, `push_file(local, remote)`
+    (one regular file), `pull(remote, local)`, `exists(remote) -> bool`. Every call is wrapped in the
+    same bounded retry as `RemoteQNN` because adb — like ssh to a thermally-throttling board — drops a
+    command now and then and a blind retry is the right, honest fix.
+    """
+
+    def __init__(self, serial=None, board_dir="/data/local/tmp/chipwright", adb_bin="adb"):
+        _require_adb()
+        self.serial = serial
+        self.board_dir = board_dir
+        self.adb_bin = adb_bin
+
+    # --- plumbing -----------------------------------------------------------------------------
+    def _base(self):
+        """The adb argv prefix, pinned to this device's serial when one was given."""
+        return [self.adb_bin] + (["-s", self.serial] if self.serial else [])
+
+    def _run(self, *args, timeout=600):
+        return subprocess.run(self._base() + list(args), capture_output=True, text=True, timeout=timeout)
+
+    def _retry(self, fn, tries=4, wait=3):
+        """Run `fn` up to `tries` times; return the first returncode==0 result, else the last result/err.
+
+        Identical discipline to `RemoteQNN._retry` — the caller inspects `returncode` and decides; a
+        transport blip is retried, a real failure is returned so it can be reported by name.
+        """
+        last = None
+        for _ in range(tries):
+            try:
+                r = fn()
+                if getattr(r, "returncode", 0) == 0:
+                    return r
+                last = r
+            except Exception as e:  # pragma: no cover
+                last = e
+            time.sleep(wait)
+        return last
+
+    # --- the interface the modality calls -----------------------------------------------------
+    def shell(self, cmd, timeout=600):
+        """Run `cmd` on the board (`adb shell`) and return the CompletedProcess (retry-wrapped)."""
+        return self._retry(lambda: self._run("shell", cmd, timeout=timeout))
+
+    def push_file(self, local, remote, timeout=1800):
+        """Push ONE regular file to `remote`. Refuses a directory by name.
+
+        A directory push is the exact thing that wedges the adb daemon on a multi-GB bundle, so we make
+        it an error here rather than let a caller do it by accident — the modality is expected to walk
+        the bundle and push each file. Ensures the remote parent dir exists first.
+        """
+        if not os.path.isfile(local):
+            if os.path.isdir(local):
+                raise ValueError(
+                    f"push_file is one file at a time by design (a multi-GB directory push wedges the "
+                    f"adb daemon); {local!r} is a directory — walk it and push each file.")
+            raise FileNotFoundError(f"no such file to push: {local!r}")
+        parent = os.path.dirname(remote.rstrip("/"))
+        if parent:
+            self._retry(lambda: self._run("shell", f"mkdir -p {parent}", timeout=40))
+        r = self._retry(lambda: self._run("push", local, remote, timeout=timeout))
+        if getattr(r, "returncode", 1) != 0:
+            raise RuntimeError(f"adb push failed ({local} -> {remote}): {getattr(r, 'stderr', '')}")
+        return remote
+
+    def pull(self, remote, local, timeout=1800):
+        """Pull `remote` off the board to the local path `local` (retry-wrapped)."""
+        parent = os.path.dirname(local.rstrip("/"))
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        r = self._retry(lambda: self._run("pull", remote, local, timeout=timeout))
+        if getattr(r, "returncode", 1) != 0:
+            raise RuntimeError(f"adb pull failed ({remote} -> {local}): {getattr(r, 'stderr', '')}")
+        return local
+
+    def exists(self, remote, timeout=40) -> bool:
+        """True iff `remote` is present on the board (`test -e … && echo OK`)."""
+        r = self.shell(f"test -e {remote} && echo OK", timeout=timeout)
+        return "OK" in (getattr(r, "stdout", "") or "")