tan-cli 0.7.0__py3-none-any.whl

tan/lazy_typer.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A Typer app / Click group that builds each subcommand on first use.
+
+``tan.cli`` used to import all ~31 command modules at module scope, so every
+invocation -- ``tan --version`` included -- paid for the heaviest of them
+(tan-cli#1505). Here the Click tree is assembled from ``COMMAND_TABLE`` and a
+command's module is imported only when Click asks for that command by name
+(dispatch, ``tan <cmd> --help``) or when something walks the whole tree
+(``tan --help``, a ``--format`` domain check): ``LazyCommands`` is a mapping, so
+every ``group.commands[...]`` / ``sorted(group.commands)`` / ``.items()`` caller
+keeps working unchanged; only ``.items()``/``.values()`` pay for everything.
+
+The loaders in ``tan.command_table`` stay plain static ``from ... import``
+statements, which is what keeps PyInstaller able to see every command module.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, MutableMapping
+from typing import TYPE_CHECKING, Any
+
+import typer
+from typer.core import TyperGroup
+from typer.main import get_command_from_info
+from typer.models import CommandInfo
+
+from tan.command_table import COMMAND_TABLE, CommandSpec
+
+if TYPE_CHECKING:
+    import click
+
+#: Captured at import so a swap of `typer.main.get_command` (see
+#: `LazyTyper.__call__`) can never make this module call itself.
+_REAL_GET_COMMAND = typer.main.get_command
+
+COMMAND_NAMES: tuple[str, ...] = tuple(spec.name for spec in COMMAND_TABLE)
+
+
+_REGISTER_MSG = (
+    "tan commands are not registered with app.command(); add a loader and a "
+    "CommandSpec row to tan.command_table.COMMAND_TABLE"
+)
+
+
+class LazyCommands(MutableMapping):  # type: ignore[type-arg]
+    """name -> Click command, built on first lookup, in ``COMMAND_TABLE`` order."""
+
+    def __init__(self, build: Callable[[CommandSpec], 'click.Command']) -> None:
+        self._build = build
+        self._specs = {spec.name: spec for spec in COMMAND_TABLE}
+        self._built: dict[str, 'click.Command'] = {}
+        self._removed: set[str] = set()
+        self._extra: dict[str, 'click.Command'] = {}
+
+    def __getitem__(self, name: str) -> 'click.Command':
+        if name in self._extra:
+            return self._extra[name]
+        if name in self._built:
+            return self._built[name]
+        if name in self._removed or name not in self._specs:
+            raise KeyError(name)
+        if name not in self._built:
+            self._built[name] = self._build(self._specs[name])
+        return self._built[name]
+
+    def __setitem__(self, name: str, command: 'click.Command') -> None:
+        if name in self._specs:
+            self._removed.discard(name)
+            self._built[name] = command
+            return
+        self._extra[name] = command
+
+    def __delitem__(self, name: str) -> None:
+        if name not in self:
+            raise KeyError(name)
+        self._extra.pop(name, None)
+        self._built.pop(name, None)
+        if name in self._specs:
+            self._removed.add(name)
+
+    def __iter__(self) -> Iterator[str]:
+        for name in self._specs:
+            if name not in self._removed:
+                yield name
+        yield from self._extra
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._extra or (name in self._specs and name not in self._removed)
+
+
+class LazyGroup(TyperGroup):
+    """A ``TyperGroup`` whose ``commands`` is a ``LazyCommands`` when built lazily."""
+
+    def install_lazy_commands(self, build: Callable[[CommandSpec], 'click.Command']) -> None:
+        self.commands = LazyCommands(build)
+
+
+class LazyTyper(typer.Typer):
+    """``typer.Typer`` whose subcommands come from ``COMMAND_TABLE``.
+
+    ``registered_commands`` still answers with the full, ordered list of
+    ``CommandInfo`` (built on first read) so table-derived tests and tools keep
+    their view, and ``typer.main.get_command(app)`` still yields the complete
+    eager tree. Only ``__call__`` -- the real ``tan`` entry -- and
+    ``lazy_group()`` take the lazy path.
+    """
+
+    def __init__(self, *args: Any, command_cls: type | None = None, **kwargs: Any) -> None:
+        self._command_cls = command_cls
+        self._lazy_build = False
+        self._lazy_group: LazyGroup | None = None
+        self._infos: dict[str, CommandInfo] = {}
+        super().__init__(*args, cls=LazyGroup, **kwargs)
+
+    # `Typer.__init__` assigns `self.registered_commands = []`; absorb it.
+    @property
+    def registered_commands(self) -> list[CommandInfo]:  # type: ignore[override]
+        if self._lazy_build:
+            return []
+        return [self.command_info(spec) for spec in COMMAND_TABLE]
+
+    @registered_commands.setter
+    def registered_commands(self, value: list[CommandInfo]) -> None:
+        if value:
+            raise TypeError(_REGISTER_MSG)
+
+    def command(self, *args: Any, **kwargs: Any) -> Any:  # type: ignore[override]
+        raise TypeError(_REGISTER_MSG)
+
+    def command_info(self, spec: CommandSpec) -> CommandInfo:
+        info = self._infos.get(spec.name)
+        if info is None:
+            callback, context_settings = spec.load()
+            info = CommandInfo(
+                name=spec.name,
+                cls=self._command_cls,
+                context_settings=context_settings,
+                callback=callback,
+                rich_help_panel=spec.rich_help_panel,
+            )
+            self._infos[spec.name] = info
+        return info
+
+    def _build_command(self, spec: CommandSpec) -> 'click.Command':
+        return get_command_from_info(
+            self.command_info(spec),
+            pretty_exceptions_short=self.pretty_exceptions_short,
+            rich_markup_mode=self.rich_markup_mode,
+        )
+
+    def lazy_group(self) -> 'click.Command':
+        """The Click tree with subcommand modules deferred until looked up.
+
+        Built once per instance; every caller (dispatch, help envelope, the
+        `--format` domain walk) shares it.
+        """
+        if self._lazy_group is None:
+            self._lazy_build = True
+            try:
+                group = _REAL_GET_COMMAND(self)
+            finally:
+                self._lazy_build = False
+            assert isinstance(group, LazyGroup)
+            group.install_lazy_commands(self._build_command)
+            self._lazy_group = group
+        return self._lazy_group
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        group = self.lazy_group()
+
+        def _get_command(typer_instance: typer.Typer) -> 'click.Command':
+            # `Typer.__call__` rebuilds the tree via `typer.main.get_command(self)`;
+            # hand it the lazy group for THIS app and delegate for anything else.
+            if typer_instance is self:
+                return group
+            return _REAL_GET_COMMAND(typer_instance)
+
+        original = typer.main.get_command
+        typer.main.get_command = _get_command  # type: ignore[assignment]
+        try:
+            return super().__call__(*args, **kwargs)
+        finally:
+            typer.main.get_command = original

tan/model/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan model packaging: .alpmodel writer + manifest model."""

tan/model/_gen_fixture.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generate the canonical test fixtures: a minimal .alpmodel + its C byte
+array, and the issue #1254 onnx_cpu regression fixture (tests/yocto/).
+
+These three committed files (`tests/fixtures/alpmodel/minimal.alpmodel`,
+`tests/unit/alpmodel_reader/src/fixture.h`, `tests/yocto/onnx_cpu_fixture.h`)
+live in alp-sdk, not tan-cli -- `tests/unit/` and `tests/yocto/` are
+Zephyr/Yocto C-test trees with no tan-cli equivalent (ADR-0028 Decision-3:
+the on-device `.alpmodel` C reader, and the tests that exercise it, stay in
+alp-sdk). `python/tests/model/test_package.py` compares the (now relocated)
+Python encoder's output against these files read out of a bound alp-sdk
+checkout, the same way `tests.conftest.sdk_root()` binds every other
+cross-repo test in this suite.
+
+Run as: python -m tan.model._gen_fixture --root <path-to-alp-sdk-checkout>
+        (or set ALP_SDK_ROOT; --root wins when both are given)"""
+from __future__ import annotations
+import argparse
+import os
+import sys
+from pathlib import Path
+from ..core.shapes import SDK_MARKER as _SDK_MARKER
+from .manifest import Manifest, Tensor, Target, Coverage
+from .package import write_package
+
+
+def _manifest() -> Manifest:
+    return Manifest(
+        name="minimal",
+        src_sha=bytes(range(32)),
+        inputs=[Tensor("int8", 4, [1, 96, 96, 1], 0.0078, -1)],
+        outputs=[Tensor("int8", 2, [1, 2], 0.004, 0)],
+        targets=[
+            Target("ethos_u", "alif:ensemble:e8", "vela_tflite", "ethos-u85-256",
+                   65536, {"sram_kib": 256, "op_features": []}, 0, compiler_version="vela 4.1.0"),
+            Target("cpu", "*", "tflite", "", 131072,
+                   {"sram_kib": 0, "op_features": []}, 1, compiler_version="passthrough"),
+        ],
+        coverage=[Coverage("deepx_dxm1", "", "skipped", "dx-compiler not found")],
+    )
+
+
+def build_fixture_bytes() -> bytes:
+    return write_package(_manifest(), [b"VELA\x00\x01\x02\x03", b"TFLITE\x00"])
+
+
+def _onnx_cpu_manifest() -> Manifest:
+    return Manifest(
+        name="onnx_cpu_smoke",
+        src_sha=bytes(range(32)),
+        targets=[
+            Target("cpu", "*", "onnx", "", 65536, {"sram_kib": 0, "op_features": []}, 0,
+                   compiler_version="passthrough"),
+        ],
+    )
+
+
+def build_onnx_cpu_fixture_bytes() -> bytes:
+    """Issue #1254 end-to-end regression fixture (tests/yocto/alpmodel_onnx_cpu.c):
+    an "onnx" blob_format .alpmodel container, decoded by the real
+    zcbor-backed alp_model_parse()."""
+    return write_package(_onnx_cpu_manifest(), [b"\x08\x01\x12\x04test-onnx-blob-placeholder"])
+
+
+def to_c_header(raw: bytes, *, array_name: str = "alp_model_fixture",
+                 guard: str = "ALP_MODEL_FIXTURE_H") -> str:
+    # clang-format guards: the array wrap width is the generator's,
+    # not the formatter's -- without them a repo-wide clang-format
+    # sweep rewraps the rows and the committed-matches-generator
+    # pytest fails.
+    lines = ["/* GENERATED by `python -m tan.model._gen_fixture` -- do not edit. */",
+             "/* clang-format off */",
+             f"#ifndef {guard}", f"#define {guard}",
+             "#include <stddef.h>", "#include <stdint.h>", "",
+             f"static const uint8_t {array_name}[] = {{"]
+    for i in range(0, len(raw), 12):
+        chunk = ", ".join(f"0x{b:02x}" for b in raw[i:i + 12])
+        lines.append(f"    {chunk},")
+    lines += ["};",
+              f"static const size_t {array_name}_len = {len(raw)};",
+              "", f"#endif /* {guard} */",
+              "/* clang-format on */", ""]
+    return "\n".join(lines)
+
+
+def _resolve_sdk_root(explicit: str | None) -> Path:
+    """`--root` wins over `ALP_SDK_ROOT`; either must name a real alp-sdk
+    checkout (the same `scripts/alp_project.py` marker `tan`'s own SDK
+    discovery uses), not just an existing directory -- a typo'd path should
+    fail loudly here, not by writing into the wrong tree."""
+    root = explicit or os.environ.get("ALP_SDK_ROOT")
+    if not root:
+        print("tan.model._gen_fixture: no alp-sdk checkout given -- pass "
+              "--root <path> or set ALP_SDK_ROOT.", file=sys.stderr)
+        raise SystemExit(1)
+    resolved = Path(root).resolve()
+    if not resolved.joinpath(*_SDK_MARKER).is_file():
+        print(f"tan.model._gen_fixture: {resolved} does not look like an "
+              f"alp-sdk checkout (missing {'/'.join(_SDK_MARKER)}).",
+              file=sys.stderr)
+        raise SystemExit(1)
+    return resolved
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", help="alp-sdk checkout to write the fixtures into "
+                                        "(defaults to $ALP_SDK_ROOT)")
+    args = parser.parse_args(argv)
+    sdk_root = _resolve_sdk_root(args.root)
+
+    alpmodel = sdk_root / "tests/fixtures/alpmodel/minimal.alpmodel"
+    header = sdk_root / "tests/unit/alpmodel_reader/src/fixture.h"
+    onnx_cpu_header_path = sdk_root / "tests/yocto/onnx_cpu_fixture.h"
+
+    raw = build_fixture_bytes()
+    alpmodel.parent.mkdir(parents=True, exist_ok=True)
+    header.parent.mkdir(parents=True, exist_ok=True)
+    alpmodel.write_bytes(raw)
+    header.write_text(to_c_header(raw), encoding="utf-8", newline="")
+
+    onnx_cpu_raw = build_onnx_cpu_fixture_bytes()
+    onnx_cpu_header = to_c_header(onnx_cpu_raw, array_name="k_onnx_cpu_alpmodel",
+                                   guard="ALP_MODEL_ONNX_CPU_FIXTURE_H")
+    onnx_cpu_header_path.parent.mkdir(parents=True, exist_ok=True)
+    onnx_cpu_header_path.write_text(onnx_cpu_header, encoding="utf-8", newline="")
+
+    print(f"wrote {alpmodel} ({len(raw)} bytes), {header} and {onnx_cpu_header_path}")
+
+
+if __name__ == "__main__":
+    main()

tan/model/adapters/__init__.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Compiler-adapter interface: one adapter per backend toolchain."""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Blob:
+    """One compiled artifact + the manifest metadata the writer needs."""
+    format: str                 # conventionally one of manifest.VALID_BLOB_FORMATS
+                                 # (vela_tflite | tflite | drpai_dir | dxnn |
+                                 # onnx | executorch); this is a WRITE-side
+                                 # field and is never itself validated -- an
+                                 # unlisted format here is rejected only when
+                                 # the package is later DECODED
+                                 # (Manifest.from_dict), and
+                                 # tests/gates/test_blob_format_producers_stay_in_valid_blob_formats.py
+                                 # is what actually keeps a producer's own
+                                 # literal in sync with the set.
+    payload: bytes
+    arena_bytes: int = 0
+    compiler_version: str = ""
+    req_sram_kib: int = 0
+    # Real per-operator NPU-vs-CPU placement, as the compiler itself reports
+    # it -- today only `VelaAdapter` populates these (parsed from vela's own
+    # "CPU/NPU operators = N (P%)" summary line, `ethos_u._parse_vela_
+    # placement`). None for every other adapter, and None when the compiler
+    # ran but didn't print a placement summary this could parse: a compiler
+    # exiting 0 is NOT proof every op landed on the NPU (vela exits 0 on a
+    # full CPU fallback by design), so a caller that wants "did this compile
+    # actually place anything on the accelerator" must read these, never
+    # infer it from the mere absence of an exception.
+    npu_op_count: int | None = None
+    cpu_op_count: int | None = None
+    # Adapter-authored caveats about THIS compile that a report must not drop
+    # -- each already a complete, customer-readable sentence. Today only
+    # `VelaAdapter` populates them, for the profile flags vela had to default:
+    # `--memory-mode` now comes from the SoC spec (alp-sdk #1470), but
+    # `--system-config` still does not, because the SoM-authoritative names
+    # live only in a proprietary .ini alp-sdk does not redistribute. Surfaced
+    # rather than swallowed so a compile tuned to vela's own bandwidth model
+    # -- or, under a memory mode whose const area sits on the arena's OTHER
+    # AXI port (`Shared_Sram`), one whose WEIGHTS vela's default system config
+    # placed as well, or, when no memory mode was resolvable at all, one sent
+    # to vela's DRAM-backed default on a module that has no DRAM -- cannot be
+    # mistaken for a module-authoritative one; `tan.model.check`'s
+    # `_report_from_vela_compile` carries them into `BackendReport.notes` and
+    # so into the JSON envelope. Never a substitute for failing: a figure that
+    # cannot be derived is refused (`ethos_u._refuse_zero_sram_footprint`),
+    # not caveated.
+    caveats: tuple[str, ...] = ()
+
+
+class CompilerAdapter(ABC):
+    backend: str                # cpu | ethos_u | drpai | deepx_dxm1
+    # True for backends that need a per-model compile config the SDK can't
+    # derive (DEEPX JSON+calibration, DRP-AI spec). build_model records a
+    # "no compile config" coverage skip for these when no opts block is given.
+    requires_compile_opts: bool = False
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True if this backend's compiler is installed/usable on this host."""
+
+    @abstractmethod
+    def accepts(self, src_format: str) -> bool:
+        """True if this adapter can consume the given source format (onnx|tflite)."""
+
+    @abstractmethod
+    def compile(self, source: Path, *, accel_config: str, out_dir: Path,
+                opts: dict | None = None,
+                vela_memory_mode: str | None = None,
+                vela_system_config: str | None = None,
+                vela_vendor_system_config: str | None = None,
+                vela_vendor_config_filename: str | None = None,
+                soc_declares_dram: bool | None = None) -> Blob:
+        """Compile @source for @accel_config; return the Blob.
+
+        @opts is the per-model compile config for this backend
+        (board.yaml `models[].compile.<backend>`), with any path values already
+        resolved to absolute paths by the caller; None when the backend needs
+        no per-model config (cpu, ethos_u).
+
+        @vela_memory_mode / @vela_system_config / @vela_vendor_system_config
+        ARE compile inputs, and the only backend-specific ones on this
+        interface: `TargetSpec.vela_*`, the silicon's own vela invocation
+        profile out of the SoC spec's `npu_toolchain.vela` (alp-sdk #1470).
+        Only `VelaAdapter` acts on them -- every other adapter accepts and
+        ignores them, exactly as `cpu` and `ethos_u` accept and ignore `opts`
+        -- and they are named for vela on purpose, so a future DRP-AI or DEEPX
+        profile cannot be mistaken for being carried by them. `None` means the
+        caller resolved no profile, and an adapter must then invoke its
+        compiler exactly as it did before the profile existed rather than
+        substituting a default of its own: a guessed memory model compiles a
+        command stream for hardware the module does not have. The vendor
+        System_Config is a SEPARATE field from the built-in one because it is
+        legal only alongside a `--config` the customer supplies through
+        `ALP_VELA_CONFIG`; an adapter handed both in one field could put a
+        section name on a command line vela cannot resolve, which is rc=1.
+
+        @vela_vendor_config_filename / @soc_declares_dram are the opposite:
+        DIAGNOSTIC facts about this part, out of the same SoC spec
+        (`npu_toolchain.vela.vendor_config_filename` and
+        `external_memory_interfaces[]`), for an adapter whose ERROR TEXT is
+        part-specific even though its compile is not. Today only `VelaAdapter`
+        reads them -- to name the vendor `.ini` a part actually declares, and
+        to say that a DRAM placement describes memory this part has no
+        interface to. They replaced a `silicon_ref` vendor-prefix match that
+        stood in for both questions (tan-cli#789 review (g)); metadata answers
+        them per part, so no adapter has to know who builds what. `None` means
+        the caller resolved no such fact, and an adapter must then say nothing
+        about it rather than infer one from an accelerator config or a
+        compiler-reported profile name. Neither is a compile input: no adapter
+        may change the artifact it emits based on these."""

tan/model/adapters/cpu.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU/TFLM passthrough adapter: the model runs as-is on reference kernels."""
+from __future__ import annotations
+from pathlib import Path
+from . import CompilerAdapter, Blob
+
+
+class CpuAdapter(CompilerAdapter):
+    backend = "cpu"
+
+    def is_available(self) -> bool:
+        return True              # always available; no external tool
+
+    def accepts(self, src_format: str) -> bool:
+        return src_format == "tflite"
+
+    def compile(self, source: Path, *, accel_config: str, out_dir: Path,
+                opts: dict | None = None,
+                vela_memory_mode: str | None = None,
+                vela_system_config: str | None = None,
+                vela_vendor_system_config: str | None = None,
+                vela_vendor_config_filename: str | None = None,
+                soc_declares_dram: bool | None = None) -> Blob:
+        payload = source.read_bytes()
+        return Blob(format="tflite", payload=payload, arena_bytes=0,
+                    compiler_version="passthrough")

tan/model/adapters/deepx.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""DEEPX DX-M1 compiler adapter (host model compiler).
+
+DEEPX's compiler is the proprietary, license-gated `dx-com` Python wheel
+(console script `dxcom`; `dx-com` 2.3.0 verified -- Linux x86_64, CPython 3.12,
+ONNX frontend, Target Hardware: M1). It compiles an ONNX model into a DEEPX NPU
+model binary:
+    dxcom -m <model.onnx> -c <config.json> -o <output_dir>
+with a per-model JSON config (the calibration dataset is referenced from inside
+that config -- `dxcom` has no separate calibration CLI flag). `-o` is a
+*directory*, but a successful compile writes exactly one canonical artifact into
+it: ``<model_stem>.dxnn`` -- a self-describing flatbuffer (magic ``DXNN`` + a
+JSON header). That single ``.dxnn`` is what the on-device `dx_rt` runtime loads,
+so the adapter returns its raw bytes with `blob_format` ``dxnn`` (matching the
+device-side ALP_INFERENCE_MODEL_DXNN that `alp_model_select` decodes), NOT a tar
+of the directory. (Confirmed against a real `dxcom` 2.3.0 run, 2026-05-27: a
+tiny CNN and a real yolo11n both emit a single ``<stem>.dxnn``; `compiler.log`
+only appears with `--gen_log`. dxcom also requires >15 GB host RAM.)
+
+The wheel is not redistributable, so it is NOT bundled; is_available() is True
+only when `dxcom` is on PATH or ALP_DEEPX_SDK_HOME points at an install. The
+per-model config + calibration come from board.yaml `models[].compile.deepx_dxm1`
+(threaded in as `opts`). The dx_rt A55/PCIe *runtime* backend
+(`src/yocto/inference_deepx.cpp`) is Stage 2 step 4 (bench-gated)."""
+from __future__ import annotations
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from tan.core.subprocess_env import spawn_env
+from . import CompilerAdapter, Blob
+
+# dxcom does post-training quantization + compilation (torch/onnx under the
+# hood); minutes for a real model, but never unbounded in CI.
+_DXCOM_TIMEOUT_S = 1800
+
+
+def _dxcom_version() -> str:
+    """Best-effort compiler version, e.g. 'DX-COM 2.3.0'; 'dxcom' on failure."""
+    try:
+        proc = subprocess.run(
+            ["dxcom", "-v"], capture_output=True, text=True, timeout=60, env=spawn_env()
+        )
+    except (OSError, subprocess.SubprocessError):
+        return "dxcom"
+    m = re.search(r"DX-COM[^\d]*(\d+\.\d+\.\d+)", proc.stdout + proc.stderr)
+    return f"DX-COM {m.group(1)}" if m else "dxcom"
+
+
+class DeepxAdapter(CompilerAdapter):
+    backend = "deepx_dxm1"
+    requires_compile_opts = True          # needs a per-model dxcom JSON config
+
+    def is_available(self) -> bool:
+        if shutil.which("dxcom"):            # the dx-com wheel's console script
+            return True
+        root = os.environ.get("ALP_DEEPX_SDK_HOME")
+        return bool(root) and Path(root).is_dir()
+
+    def accepts(self, src_format: str) -> bool:
+        return src_format == "onnx"          # dxcom is an ONNX frontend
+
+    def compile(self, source: Path, *, accel_config: str, out_dir: Path,
+                opts: dict | None = None,
+                vela_memory_mode: str | None = None,
+                vela_system_config: str | None = None,
+                vela_vendor_system_config: str | None = None,
+                vela_vendor_config_filename: str | None = None,
+                soc_declares_dram: bool | None = None) -> Blob:
+        config = (opts or {}).get("config")
+        if not config:
+            raise RuntimeError(
+                "DEEPX compile needs models[].compile.deepx_dxm1.config "
+                "(a dxcom JSON config; the calibration set is referenced from it)")
+        dst = out_dir / f"{source.stem}_dxnn"
+        dst.mkdir(parents=True, exist_ok=True)
+        cmd = ["dxcom", "-m", str(source), "-c", str(config), "-o", str(dst)]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=_DXCOM_TIMEOUT_S, env=spawn_env()
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(f"dxcom timed out after {exc.timeout}s") from exc
+        if proc.returncode != 0:
+            raise RuntimeError(f"dxcom failed: {proc.stderr.strip() or proc.stdout.strip()}")
+        artifacts = sorted(dst.glob("*.dxnn"))
+        if not artifacts:
+            raise RuntimeError(f"dxcom produced no .dxnn in {dst}")
+        # A single-input compile emits exactly one <stem>.dxnn; prefer the
+        # model-stem-named artifact if dxcom ever emits more than one.
+        canonical = next((p for p in artifacts if p.stem == source.stem), artifacts[0])
+        return Blob(format="dxnn", payload=canonical.read_bytes(),
+                    compiler_version=_dxcom_version())