tan-cli 0.7.0__py3-none-any.whl

tan/model/targets.py

@@ -0,0 +1,374 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Derive .alpmodel compile targets from a SoM SKU (silicon-determined).
+
+Targets come from the host SoC's npus[] *and* from any on-module discrete
+accelerator (e.g. the DEEPX DX-M1 on V2M SoMs). A discrete accelerator is any
+*other* SoC JSON whose variants[].alp_module_skus lists this SKU -- so the SoC
+JSON's alp_module_skus stays the single source of truth (no hardcoded
+backend->silicon map)."""
+from __future__ import annotations
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NamedTuple
+
+from tan.soc_ref import resolve_soc_path
+
+
+@dataclass(frozen=True)
+class TargetSpec:
+    backend: str            # cpu | ethos_u | drpai | deepx_dxm1
+    silicon_ref: str        # SoC ref e.g. "alif:ensemble:e7" | "deepx:dx:m1" | "*"
+    accel_config: str       # vela accel-config e.g. "ethos-u55-256"; "" when N/A
+    # The SILICON's vela invocation profile, from the SoC spec's
+    # `npu_toolchain.vela` block (alp-sdk #1470) -- ethos_u targets only, None
+    # everywhere else. Optional with None defaults so no existing TargetSpec
+    # construction site has to change, and so a SoC spec that predates the
+    # block resolves to "pass no profile flag", which is exactly today's
+    # behaviour rather than a guess.
+    vela_memory_mode: str | None = None      # Arm built-in, e.g. "Sram_Only"
+    vela_system_config: str | None = None    # ONLY when it needs no vendor config
+    # The other half of that block: the vendor-gated System_Config and the file
+    # that defines it. Carried SEPARATELY from `vela_system_config` -- which
+    # stays "safe to put on a command line alone" by construction -- because
+    # these two are legal only TOGETHER and only alongside a `--config` the
+    # customer supplies through `ALP_VELA_CONFIG`
+    # (`tan.model.adapters.ethos_u`). None for every part shipped today: no SoC
+    # spec names a `system_config` at all.
+    vela_vendor_system_config: str | None = None
+    # The vendor `.ini`'s FILENAME as metadata declares it
+    # (`vendor_config_filename`, e.g. `ensemble_vela.ini`) -- a DIAGNOSTIC
+    # fact, never a path: `tan.model.adapters.ethos_u`'s footprint refusal
+    # names it to explain why tan cannot resolve a complete profile for this
+    # part. A part whose metadata declares none gets no file named, so no
+    # customer is ever sent after another vendor's download.
+    vela_vendor_config_filename: str | None = None
+    # Does this SoC declare ANY external DRAM interface
+    # (`external_memory_interfaces[].kind`)? `False` is the machine-checkable
+    # evidence behind the zero-SRAM refusal: vela's default profiles are
+    # DRAM-backed, and a working set placed in DRAM on a part that declares no
+    # DRAM interface describes memory the module does not have. `None` means
+    # the spec says nothing, and an unknown must never be reported as a "no"
+    # -- see `_soc_declares_dram`.
+    soc_declares_dram: bool | None = None
+    # Which CPU core drives this accelerator, from the SoC spec's own
+    # `npus[].paired_core` -- `m55_hp` for the E8's high-perf Ethos-U55,
+    # `m55_he` for its high-efficiency one. `None` where the spec declares no
+    # pairing (the E8's Ethos-U85 today), and that `None` is a real answer, not
+    # a gap to fill in: the metadata does not know which core drives it, so
+    # nothing downstream may infer one. A bench-measured perf point's identity
+    # includes the core (alp-sdk `f724d3e4`), and this is the only sourced
+    # answer tan has for it.
+    paired_core: str | None = None
+
+
+class _VelaProfile(NamedTuple):
+    """What one SoC spec's `npu_toolchain.vela` block resolves to, split by
+    what is SAFE TO PASS: `system_config` is an Arm built-in that vela accepts
+    on its own, `vendor_system_config` is a name that exists only inside
+    `vendor_config_filename` and is rc=1 without it."""
+    memory_mode: str | None
+    system_config: str | None
+    vendor_system_config: str | None
+    vendor_config_filename: str | None
+
+
+#: Substrings that make an `external_memory_interfaces[].kind` a DRAM
+#: interface, matched case-insensitively against the declared kind. Covers
+#: every DRAM spelling in metadata today -- `LPDDR4/4X` (renesas:rzv2n:n44), `LPDDR4X / LPDDR5` (deepx:dx:m1) -- and nothing else:
+#: `HexSPI`, `OctalSPI`, `FlexSPI`, `xSPI` and `SD/eMMC` (the ONLY kinds the
+#: six Alif Ensemble parts declare) are not DRAM.
+#:
+#: Matched on `kind` alone and NOT on the interface's `supports` list, which
+#: is where the Alif parts carry `HyperBus`. A HyperBus port can host HyperRAM,
+#: but that is a populated-device question this spec does not answer, and vela's
+#: `Dram` memory area is not it -- reading `supports` here would turn an
+#: attachable-bus fact into a "this part has DRAM" claim nothing sourced.
+_DRAM_INTERFACE_TOKENS = ("DDR", "DRAM")
+
+
+def _soc_declares_dram(soc: dict) -> bool | None:
+    """Does this SoC spec declare an external DRAM interface? `None` when it
+    declares no `external_memory_interfaces` at all.
+
+    THE `None` IS THE POINT, and it fails closed. The consumer
+    (`tan.model.adapters.ethos_u._refuse_zero_sram_footprint`) states "this SoC
+    declares no DRAM interface" as EVIDENCE in a refusal a customer sizes
+    hardware from, so it may only ever say that on an explicit `False`. A spec
+    that carries no interface list has not declared the absence of DRAM; it has
+    said nothing, and saying nothing back is the only honest answer. Same
+    reading for an EMPTY list, which is a stub far more often than a positive
+    statement that a part has no external memory at all."""
+    interfaces = soc.get("external_memory_interfaces")
+    if not isinstance(interfaces, list) or not interfaces:
+        return None
+    for iface in interfaces:
+        kind = str(iface.get("kind", "")) if isinstance(iface, dict) else ""
+        if any(token in kind.upper() for token in _DRAM_INTERFACE_TOKENS):
+            return True
+    return False
+
+
+def _vela_profile(soc: dict) -> _VelaProfile:
+    """How to invoke vela for THIS SoC, read from its `npu_toolchain.vela`
+    block. All-None for a spec that carries no block -- never a guessed
+    profile; a wrong one compiles a command stream for memory the module does
+    not have.
+
+    THE SYSTEM_CONFIG GUARD IS LOAD-BEARING. `--memory-mode` values are Arm
+    built-ins (the SoC schema constrains `memory_mode` to the `[Memory_Mode.*]`
+    sections `ethos-u-vela` 5.1.0 ships), so passing one always works. A
+    `System_Config` name usually is NOT: the Alif Ensemble parts' own
+    `Ethos_U85_SRAM_Only` / `RTSS_HE_SRAM_Only` live only in the proprietary
+    `ensemble_vela.ini`, and handing vela a section it cannot resolve is a hard
+    rc=1, measured verbatim:
+
+        ethosu.vela.errors.CliOptionError: 'Error: Incorrect argument to CLI
+        option --system-config=Ethos_U85_SRAM_Only: Section
+        System_Config.Ethos_U85_SRAM_Only not found in Vela config file'
+
+    So a `system_config` is carried ONLY when the block declares
+    `system_config_requires_vendor_config` EXPLICITLY FALSE. It fails CLOSED,
+    not open: an ABSENT key withholds the name, exactly as `true` does. The
+    defence for reading it as falsy was that alp-sdk's SoC schema makes the key
+    `required` -- true today, but enforced in the OTHER repo, against a
+    checkout tan binds at an arbitrary version (`ALP_SDK_ROOT`, any tag or
+    branch a user has on disk). That is the same cross-repo drift class
+    `tests/gates/test_planner_relocation_freshness.py` exists for, and here the
+    failure mode is not a stale hash: an unannotated `system_config` would walk
+    straight onto vela's command line and turn a build into a hard rc=1. `is
+    False` is the only reading under which a spec that never made the promise
+    cannot make it by omission.
+
+    An ABSENT `system_config` is likewise "nothing to pass", never "no vendor
+    config needed": no Alif spec names one today (an Alif System_Config
+    describes one CORE SUBSYSTEM, not a die), so this branch yields None for
+    every part currently shipped -- correct, and the mechanism is here for the
+    spec that eventually does carry a built-in one.
+
+    A vendor-gated name is WITHHELD FROM `system_config` AND CARRIED ON
+    `vendor_system_config`, rather than dropped. The two fields are exactly
+    "safe alone" versus "legal only with its `.ini`": the adapter may put the
+    first on a command line unconditionally, and the second only alongside a
+    `--config` pointing at a file the customer supplied through
+    `ALP_VELA_CONFIG`. Splitting them here rather than passing one name plus a
+    boolean keeps the fail-closed guard above the only place that decides which
+    is which: an adapter cannot accidentally pass a vendor name by reading a
+    flag the wrong way round, because it is never handed one in the field it
+    passes freely."""
+    block = soc.get("npu_toolchain")
+    vela = block.get("vela") if isinstance(block, dict) else None
+    if not isinstance(vela, dict):
+        return _VelaProfile(None, None, None, None)
+    memory_mode = vela.get("memory_mode") or None
+    system_config = vela.get("system_config") or None
+    if vela.get("system_config_requires_vendor_config") is not False:
+        # The filename rides ONLY on this branch. A spec that declares it needs
+        # no vendor config has no vendor file to name, and a contradictory spec
+        # (`false` plus a filename) must not have that filename quoted at a
+        # customer as something they need -- the refusal clause it feeds calls
+        # the file proprietary and undistributed, which would then be advice
+        # about a download nobody has to make.
+        return _VelaProfile(memory_mode, None, system_config,
+                            vela.get("vendor_config_filename") or None)
+    return _VelaProfile(memory_mode, system_config, None, None)
+
+
+def _npu_backend(npu_type: str, subtype: str) -> str | None:
+    if npu_type.startswith("ethos-u"):
+        return "ethos_u"
+    if "drp" in npu_type or "drp" in subtype:   # renesas DRP-AI ("drp-ai" / "ai-mac+drp")
+        return "drpai"
+    if npu_type.startswith("dx") or "deepx" in npu_type:
+        return "deepx_dxm1"
+    return None
+
+
+def _soc_targets(soc: dict, silicon_ref: str) -> list[TargetSpec]:
+    """One TargetSpec per mappable NPU in a SoC's npus[] (deduped by the caller)."""
+    out: list[TargetSpec] = []
+    profile = _vela_profile(soc)
+    declares_dram = _soc_declares_dram(soc)
+    npus = soc.get("npus", [])
+    if not isinstance(npus, list):
+        # `npus` is schema-typed `"type": "array"` but unvalidated on read
+        # (tan-cli#964 is the read-path schema check; this is the last line
+        # of defence, not a substitute). A schema-invalid SoC JSON can hand
+        # this key a non-list scalar, which `for npu in npus` would raise
+        # `TypeError: ... is not iterable` on. Same "no mappable NPUs"
+        # outcome a genuinely-absent `npus` key already produces.
+        npus = []
+    for npu in npus:
+        if not isinstance(npu, dict):
+            # One level below the `npus` guard above: an ELEMENT of a
+            # schema-valid `npus` array can itself be a non-dict scalar on a
+            # schema-invalid SoC JSON (tan-cli#967 review -- the guard below
+            # protected `npu.get("type")`'s return value but not the
+            # `npu.get` CALL, one line above where the review found it).
+            # Skip the element -- the identical "no mappable backend for
+            # this entry" outcome an unresolvable `type` already produces
+            # two blocks down.
+            continue
+        # `.get("type", "")`'s default fires only when the key is ABSENT --
+        # never when it is present with the wrong type -- so a schema-invalid
+        # SoC JSON (unvalidated on read; the real fix is tan-cli#964) can hand
+        # a non-string straight into `_npu_backend`'s `.startswith`/`in`
+        # calls (tan-cli#965). Guard to the same "" unresolved sentinel the
+        # #957 family (cores[] `type`) settled on: an unrecognised/
+        # unresolvable type falls back to the identical "no mappable
+        # backend, skip this npu" outcome a genuinely-absent `type` key
+        # already produces, rather than a fourth behaviour. `.lower()` is
+        # deliberately NOT applied here (unlike #965's own snippet): it would
+        # newly match e.g. "Ethos-U55" and flip `accel_config` from
+        # "Ethos-U55-256" to "ethos-u55-256", which check.py:540-542's
+        # `accel_config.startswith(f"ethos-{variant}-")` reads -- exactly the
+        # fourth behaviour this guard exists to rule out, not a bug fix.
+        raw_type = npu.get("type")
+        npu_type = raw_type if isinstance(raw_type, str) else ""
+        raw_subtype = npu.get("subtype")
+        subtype = raw_subtype if isinstance(raw_subtype, str) else ""
+        backend = _npu_backend(npu_type, subtype)
+        if backend is None:
+            continue
+        ethos_u = backend == "ethos_u"
+        mac_per_cycle = npu.get("mac_per_cycle")
+        if ethos_u and not isinstance(mac_per_cycle, int):
+            # `mac_per_cycle` is OPTIONAL in `$defs/npu` -- only `type` plus
+            # `anyOf(gops, tops)` are required, so a SCHEMA-VALID SoC JSON
+            # (e.g. `{"type": "ethos-u55", "gops": 100}`, no `mac_per_cycle`
+            # at all) reaches here with nothing to build `accel_config` from.
+            # #964 (read-path schema validation) cannot fix this one: the
+            # document already passes the schema. There is no honest partial
+            # value to fall back to -- an incomplete string like
+            # "ethos-u55-" would be a NEW, un-degradeable shape reaching
+            # `check.py`'s `accel_config.startswith(...)` reader, worse than
+            # either resolving cleanly or not resolving at all. So this NPU
+            # is unmappable for the same reason an unrecognised `type` is:
+            # skip it, the identical "no mappable backend for this entry"
+            # outcome `backend is None` above already produces (this SoC's
+            # OTHER npus[] entries, and the always-present `cpu` target,
+            # still resolve).
+            continue
+        accel = f"{npu_type}-{mac_per_cycle}" if ethos_u else ""
+        # The profile is a vela flag, so it rides only on the targets vela
+        # compiles: a DRP-AI or DEEPX target on the same die must not carry
+        # (and its adapter must never be handed) an Ethos-U memory mode. The
+        # DRAM fact is NOT a vela flag -- it is a property of the silicon this
+        # target runs on, like `silicon_ref` -- so it rides on every target the
+        # spec produces, whether or not any adapter reads it today.
+        out.append(TargetSpec(backend=backend, silicon_ref=silicon_ref, accel_config=accel,
+                              vela_memory_mode=profile.memory_mode if ethos_u else None,
+                              vela_system_config=profile.system_config if ethos_u else None,
+                              vela_vendor_system_config=(
+                                  profile.vendor_system_config if ethos_u else None),
+                              vela_vendor_config_filename=(
+                                  profile.vendor_config_filename if ethos_u else None),
+                              soc_declares_dram=declares_dram,
+                              paired_core=npu.get("paired_core") or None))
+    return out
+
+
+def _discrete_socs(sku: str, host_ref: str, metadata_root: Path) -> list[tuple[str, dict]]:
+    """SoCs (other than the host) whose variants[].alp_module_skus list this SKU --
+    i.e. on-module discrete accelerators wired to the host (DEEPX DX-M1 on V2M)."""
+    found: list[tuple[str, dict]] = []
+    for path in sorted((metadata_root / "socs").glob("**/*.json")):
+        soc = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(soc, dict):
+            # A SoC JSON that parses but is not an object (e.g. a bare
+            # array) -- every read below is `soc.get(...)`/`v.get(...)`.
+            # This is an ENUMERATION over every file under `socs/`, the same
+            # shape `analyze.py`'s `_load_table` guards for a single lookup
+            # ("letting a list or scalar through turns a downstream `.get()`
+            # into an uncaught AttributeError"): skip the one bad file, don't
+            # abort the sweep over the rest of them.
+            continue
+        ref = soc.get("ref")
+        if not ref or ref == host_ref:
+            continue
+        variants = soc.get("variants", [])
+        if not isinstance(variants, list):
+            variants = []
+        # `variants[]` elements are schema-typed as objects but unvalidated
+        # on read, the same element-type gap `_soc_targets`'s `npus[]` guard
+        # covers above (tan-cli#967 review, folded in here rather than filed
+        # separately -- same file, same defect) -- a non-dict element must
+        # not reach `v.get(...)`.
+        skus = {s for v in variants if isinstance(v, dict)
+                for s in v.get("alp_module_skus", [])}
+        if sku in skus:
+            found.append((ref, soc))
+    return found
+
+
+def resolve_targets(sku: str, *, metadata_root: Path) -> list[TargetSpec]:
+    preset_path = metadata_root / "e1m_modules" / f"{sku}.yaml"
+    if not preset_path.is_file():
+        raise FileNotFoundError(f"no SoM preset for SKU {sku} at {preset_path}")
+    import yaml  # noqa: PLC0415 -- deferred (tan-cli#810); see sdk_cmd's `_releases_opener`
+
+    preset = yaml.safe_load(preset_path.read_text(encoding="utf-8"))
+    if not isinstance(preset, dict):
+        # Mirrors the `host_soc` guard below (tan-cli#964/#965): a preset
+        # YAML that parses but is not a mapping (e.g. a bare list or a bare
+        # scalar) must not reach the bare `preset["silicon"]` subscript --
+        # that raises a raw TypeError ("list indices must be integers or
+        # slices, not str" / "string indices must be integers, not 'str'")
+        # instead of a curated error a caller can distinguish from any other
+        # TypeError in the call stack (tan-cli#1010).
+        raise ValueError(
+            f"malformed SoM preset at {preset_path}: expected a YAML "
+            f"mapping, got {type(preset).__name__}"
+        )
+
+    # `.get(...)`, not a bare subscript: `preset` is now known to be a
+    # mapping (guard above) but `silicon:` is schema-REQUIRED, not merely
+    # unvalidated-optional -- a preset that omits it must still fall into
+    # the curated `resolve_soc_path()` ValueError path below (a missing key
+    # becomes silicon=None, which is not a valid 3-part ref) rather than
+    # raising a raw KeyError from this line (tan-cli#1018 review).
+    silicon = preset.get("silicon")                              # host SoC, e.g. "alif:ensemble:e7"
+    # resolve_soc_path() returns None where the old inline 3-tuple unpack
+    # raised ValueError, so re-raise it here: callers distinguish a
+    # malformed ref (ValueError) from a well-formed ref naming a spec that
+    # isn't on disk (FileNotFoundError, below), and collapsing the two
+    # would be a behaviour change, not a refactor (#1096).
+    soc_path = resolve_soc_path(silicon, metadata_root)
+    if soc_path is None:
+        raise ValueError(
+            f"malformed silicon ref {silicon!r} in {preset_path}: expected "
+            f"exactly 3 colon-separated parts (<vendor>:<family>:<part>)"
+        )
+    if not soc_path.is_file():
+        raise FileNotFoundError(f"no SoC spec for {silicon} at {soc_path}")
+    host_soc = json.loads(soc_path.read_text(encoding="utf-8"))
+    if not isinstance(host_soc, dict):
+        # Unlike `_discrete_socs`'s enumeration over every socs/*.json below
+        # (where one bad file is skipped and the sweep continues), this IS
+        # THE ONE host SoC spec `silicon:` names -- there is no "skip it and
+        # try the next one". Malformed content at a path that exists is
+        # reported the same way this function already reports a malformed
+        # ref (above) or a missing path (just above this): raise, don't let
+        # it flow into `_soc_targets`'s `.get()` calls as a different,
+        # uncaught exception shape.
+        raise ValueError(
+            f"malformed SoC spec at {soc_path}: expected a JSON object, "
+            f"got {type(host_soc).__name__}"
+        )
+
+    specs: list[TargetSpec] = []
+    seen: set[tuple[str, str]] = set()
+
+    def _add(spec: TargetSpec) -> None:
+        key = (spec.backend, spec.accel_config)
+        if key not in seen:
+            seen.add(key)
+            specs.append(spec)
+
+    for spec in _soc_targets(host_soc, silicon):                   # host SoC NPUs
+        _add(spec)
+    for ref, dsoc in _discrete_socs(sku, silicon, metadata_root):  # on-module discrete NPUs
+        for spec in _soc_targets(dsoc, ref):
+            _add(spec)
+    _add(TargetSpec(backend="cpu", silicon_ref="*", accel_config=""))  # CPU always present
+    return specs

tan/model/tensorio.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Extract model tensor + operator descriptors from a TFLite flatbuffer.
+
+`extract_io` feeds the `.alpmodel` manifest (Stage-1a `Tensor` records,
+dtype/rank/shape/scale/zp -> mirrors alp_inference_tensor_t). `extract_ops`
+feeds `tan.model.analyze`'s static NPU-eligibility screen (ADR-0028 amendment):
+per-operator name + shape/const-ness + a best-effort MAC estimate, so the
+screen can weight coverage by compute rather than by op count.
+
+Both raise `OSError` when the source cannot be read (missing file,
+permission error, ...) -- that is a real failure, never swallowed. Otherwise
+both are best-effort: `[]` (or `[], []`) for a source that IS readable but
+isn't a .tflite, for a missing `tflite` reader (from the `model-io` extra),
+or for bytes that don't parse. The model still packages (or scores as
+`undetermined`), just without this metadata (compile-what's-available)."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from pathlib import Path
+from .manifest import Tensor
+
+# Shared TFLite TensorType -> SDK dtype-string mapping. Honest about the gap:
+# an unmapped type (e.g. INT64/BOOL) reads as "tflite:<code>" rather than a
+# silently wrong "f32" -- the SDK Tensor.dtype vocabulary has no such types.
+# Built by reflecting on tflite.TensorType rather than hand-transcribing the
+# numeric codes: the codes are non-contiguous with the SDK dtype vocabulary
+# (six wanted types out of eleven declared), so a hand-maintained literal
+# would need to track schema.fbs by hand for no benefit over reflection.
+_DTYPE_WANTED = {"FLOAT32": "f32", "FLOAT16": "f16", "INT32": "int32",
+                  "UINT8": "uint8", "INT16": "int16", "INT8": "int8"}
+
+
+def tflite_reader_available() -> bool:
+    """True when the `tflite` reader (the `model-io` extra) is importable on
+    this host. `extract_io`/`extract_ops` deliberately swallow a missing
+    reader into an empty best-effort result -- the right contract for
+    `build_model`'s "compile what's available" stance -- but a caller that
+    needs to tell "the reader isn't installed" apart from "this model
+    genuinely has no operators" (both look like `[]` from `extract_ops`,
+    `tan.model.check`'s MAJOR 2 review) reads this directly instead of
+    re-deriving it from an empty list, which the second case returns too."""
+    try:
+        import tflite  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _dtype_names(tflite) -> dict[int, str]:
+    tt = tflite.TensorType
+    return {getattr(tt, k): v for k, v in _DTYPE_WANTED.items()}
+
+
+def _dtype_name(dtype_names: dict[int, str], code: int) -> str:
+    return dtype_names.get(code, f"tflite:{code}")
+
+
+def extract_io(source: Path, *, raw: bytes | None = None) -> tuple[list[Tensor], list[Tensor]]:
+    # Reuse the caller's already-read bytes when provided (build_model reads the
+    # source once for the manifest sha); an OSError on our own read is a real
+    # failure, not a parse problem -- read (or take the caller's bytes) BEFORE
+    # *any* format-dependent short-circuit below (the suffix check included),
+    # so "the source is unreadable" is never masked by "the reader isn't
+    # installed" OR by "this isn't a .tflite source". All three would
+    # otherwise collapse to the identical `[], []`, which silently hides a
+    # real missing/unreadable source -- on a bare-install host (no `model-io`
+    # extra) for .tflite, and on EVERY host for .onnx, since ONNX I/O
+    # extraction has no reader yet at all.
+    if raw is None:
+        raw = source.read_bytes()
+    if source.suffix.lower() != ".tflite":
+        return [], []                       # ONNX I/O extraction is a later follow-up
+    try:
+        import tflite
+    except ImportError:
+        return [], []                       # parser not installed -> skip
+    try:
+        model = tflite.Model.GetRootAs(raw, 0)
+        if model.SubgraphsLength() == 0:
+            return [], []
+        g = model.Subgraphs(0)
+        dtype_names = _dtype_names(tflite)
+        ins = [_describe(g, g.Inputs(i), dtype_names) for i in range(g.InputsLength())]
+        outs = [_describe(g, g.Outputs(i), dtype_names) for i in range(g.OutputsLength())]
+        return ins, outs
+    except Exception:
+        return [], []                       # malformed / unexpected schema -> no metadata
+
+
+def _describe(g, idx: int, dtype_names: dict[int, str]) -> Tensor:
+    ten = g.Tensors(idx)
+    shape = [int(ten.Shape(i)) for i in range(ten.ShapeLength())]
+    qp = ten.Quantization()
+    scale = float(qp.Scale(0)) if qp is not None and qp.ScaleLength() else 0.0
+    zp = int(qp.ZeroPoint(0)) if qp is not None and qp.ZeroPointLength() else 0
+    return Tensor(dtype=_dtype_name(dtype_names, ten.Type()), rank=len(shape), shape=shape,
+                  scale=scale, zp=zp)
+
+
+@dataclass(frozen=True)
+class TensorDesc:
+    """One operator's input/output tensor, static-shape only (no runtime data)."""
+
+    shape: list[int]
+    dtype: str
+    nbytes: int          # 0 for a non-const (activation) tensor
+    is_const: bool        # True when the flatbuffer carries baked-in data (weights/bias)
+
+
+@dataclass(frozen=True)
+class OpDesc:
+    """One model operator, as spelled in its own source vocabulary (TFLite
+    builtin-op name today; an ONNX op-type string once ONNX extraction lands)."""
+
+    op: str
+    inputs: list[TensorDesc] = field(default_factory=list)
+    outputs: list[TensorDesc] = field(default_factory=list)
+    macs: int = 0          # best-effort static estimate; 0 when not computable
+    # The vocabulary `op` is spelled in -- "tflite" (the only extractor that
+    # exists today) or "onnx" once ONNX extraction lands. `tan.model.analyze`
+    # compares THIS against a support table's own `op_namespace`, never the
+    # caller-supplied `src_format`, so a mislabelled format cannot make two
+    # incomparable op vocabularies look like a match. Required kw_only, no
+    # default: a silent "tflite" default let a caller build an ONNX-spelled
+    # OpDesc that still claimed the TFLite vocabulary, which the namespace
+    # guard in analyze.py then trusted -- every construction site (extractor
+    # or test) must say which vocabulary it means.
+    op_namespace: str = field(kw_only=True)
+
+
+def extract_ops(source: Path, *, raw: bytes | None = None) -> list[OpDesc]:
+    """Walk a TFLite flatbuffer's first subgraph into `OpDesc`s for the static
+    NPU-eligibility screen. Raises `OSError` when @source cannot be read --
+    a real failure, surfaced regardless of format. Otherwise best-effort:
+    `[]` for a readable non-.tflite source (ONNX extraction is a follow-on),
+    a missing `tflite` reader, or unparseable bytes."""
+    # Read (or take the caller's bytes) BEFORE any format-dependent
+    # short-circuit -- suffix check included -- so an unreadable/missing
+    # source raises regardless of extension, rather than a `.onnx` source
+    # reading identically to "this model genuinely has no operators".
+    if raw is None:
+        raw = source.read_bytes()
+    if source.suffix.lower() != ".tflite":
+        return []
+    try:
+        import tflite
+    except ImportError:
+        return []
+    try:
+        model = tflite.Model.GetRootAs(raw, 0)
+        if model.SubgraphsLength() == 0:
+            return []
+        g = model.Subgraphs(0)
+        opcodes = [model.OperatorCodes(i) for i in range(model.OperatorCodesLength())]
+        names = _builtin_op_names(tflite)
+        dtype_names = _dtype_names(tflite)
+        custom_code = tflite.BuiltinOperator.CUSTOM
+        ops: list[OpDesc] = []
+        for i in range(g.OperatorsLength()):
+            op = g.Operators(i)
+            oc = opcodes[op.OpcodeIndex()]
+            code = oc.BuiltinCode() or oc.DeprecatedBuiltinCode()
+            if code == custom_code:
+                raw_name = oc.CustomCode()
+                name = raw_name.decode("utf-8", "replace") if raw_name else "CUSTOM"
+            else:
+                name = names.get(code, f"tflite:{code}")
+            in_tensors = [_tensor_desc(model, g, op.Inputs(j), dtype_names)
+                          for j in range(op.InputsLength()) if op.Inputs(j) >= 0]
+            # -1 marks an absent optional input (e.g. a bias-less CONV_2D).
+            out_tensors = [_tensor_desc(model, g, op.Outputs(j), dtype_names)
+                           for j in range(op.OutputsLength()) if op.Outputs(j) >= 0]
+            ops.append(OpDesc(op=name, inputs=in_tensors, outputs=out_tensors,
+                               macs=_estimate_macs(name, in_tensors, out_tensors),
+                               op_namespace="tflite"))
+        return ops
+    except Exception:
+        return []                       # malformed / unexpected schema -> no metadata
+
+
+def _builtin_op_names(tflite) -> dict[int, str]:
+    bo = tflite.BuiltinOperator
+    return {getattr(bo, n): n for n in dir(bo) if n.isupper() and isinstance(getattr(bo, n), int)}
+
+
+def _tensor_desc(model, g, idx: int, dtype_names: dict[int, str]) -> TensorDesc:
+    ten = g.Tensors(idx)
+    shape = [int(ten.Shape(i)) for i in range(ten.ShapeLength())]
+    buf = model.Buffers(ten.Buffer())
+    nbytes = buf.DataLength() if buf is not None else 0
+    return TensorDesc(shape=shape, dtype=_dtype_name(dtype_names, ten.Type()), nbytes=nbytes,
+                       is_const=nbytes > 0)
+
+
+# Positional index of the filter/weights input tensor per TFLite operator
+# kernel (kFilterTensor / kWeightsTensor in the TFLite C++ kernels), keyed by
+# builtin-op name. NOT "the first const input of the expected rank" -- that
+# heuristic silently grabs whichever constant happens to come first once a
+# graph has been const-folded, which shadows the real filter and can inflate
+# the MAC estimate by many times (see test_conv_2d_filter_is_selected_
+# positionally_not_by_first_matching_const). Every op below carries a
+# MANDATORY (never optional) tensor at index 0 -- the activation for
+# FULLY_CONNECTED/CONV_2D/DEPTHWISE_CONV_2D, kOutputShapeTensor for
+# TRANSPOSE_CONV -- so the filter index below never shifts under an
+# absent-optional-input reindex; only the trailing bias tensor is ever
+# optional (see _ACTIVATION_INPUT_INDEX below for TRANSPOSE_CONV's one
+# further wrinkle: its activation isn't at index 0 the way it is here).
+_FILTER_INPUT_INDEX = {
+    "FULLY_CONNECTED": 1,     # kInputTensor=0, kWeightsTensor=1, kBiasTensor=2 (optional)
+    "CONV_2D": 1,             # kInputTensor=0, kFilterTensor=1, kBiasTensor=2 (optional)
+    "DEPTHWISE_CONV_2D": 1,   # kInputTensor=0, kFilterTensor=1, kBiasTensor=2 (optional)
+    "TRANSPOSE_CONV": 1,      # kOutputShapeTensor=0, kWeightsTensor=1, kDataInputTensor=2, kBiasTensor=3 (optional)
+}
+
+# TRANSPOSE_CONV alone needs the INPUT activation positionally too (its
+# filter is applied per input position, not per output position -- see the
+# formula below), and that activation is not at index 0 the way it is for
+# every other op here.
+_ACTIVATION_INPUT_INDEX = {
+    "TRANSPOSE_CONV": 2,      # kDataInputTensor
+}
+
+
+def _filter_weight(op_name: str, inputs: list[TensorDesc], rank: int) -> TensorDesc | None:
+    idx = _FILTER_INPUT_INDEX.get(op_name)
+    if idx is None or idx >= len(inputs):
+        return None
+    w = inputs[idx]
+    return w if w.is_const and len(w.shape) == rank else None
+
+
+def _elem_count(shape: list[int]) -> int:
+    n = 1
+    for d in shape:
+        n *= max(int(d), 0)
+    return n
+
+
+def _estimate_macs(op_name: str, inputs: list[TensorDesc], outputs: list[TensorDesc]) -> int:
+    """Best-effort MAC count from static shapes for the compute-dominant op
+    kinds (conv/dense); 0 for everything else. MAC weighting exists to stop
+    op-count coverage from hiding a conv backbone behind a wall of cheap
+    elementwise ops, not to model every op's cost exactly -- an upper-bound
+    screening heuristic, same stance as the rest of this module."""
+    if not outputs:
+        return 0
+
+    if op_name == "TRANSPOSE_CONV":
+        # Unlike CONV_2D, the filter slides over the INPUT (the op upsamples:
+        # output is stride-larger than input), so costing off the output
+        # element count -- as CONV_2D correctly does -- over-counts by
+        # stride^2. Cost off the actual input-activation tensor's element
+        # count instead -- this branch never reads out_elems, so it must sit
+        # ahead of (not behind) the out_elems==0 guard below: an output shape
+        # that happens to compute to 0 elements (e.g. a dynamic dim) must not
+        # zero out a fully-computable in_elems * kh * kw * out_c estimate.
+        w = _filter_weight(op_name, inputs, 4)              # [out_c, kh, kw, in_c] (OHWI)
+        if w is None:
+            return 0
+        out_c, kh, kw, _ = w.shape
+        act_idx = _ACTIVATION_INPUT_INDEX[op_name]
+        if act_idx >= len(inputs):
+            return 0
+        in_elems = _elem_count(inputs[act_idx].shape)
+        if in_elems == 0:
+            return 0
+        return in_elems * kh * kw * out_c
+
+    out_elems = _elem_count(outputs[0].shape)
+    if out_elems == 0:
+        return 0
+
+    if op_name == "FULLY_CONNECTED":
+        w = _filter_weight(op_name, inputs, 2)             # [out_features, in_features]
+        return out_elems * w.shape[-1] if w else 0
+    if op_name == "CONV_2D":
+        w = _filter_weight(op_name, inputs, 4)              # [out_c, kh, kw, in_c] (OHWI)
+        if w is None:
+            return 0
+        _, kh, kw, in_c = w.shape
+        return out_elems * kh * kw * in_c
+    if op_name == "DEPTHWISE_CONV_2D":
+        w = _filter_weight(op_name, inputs, 4)              # [1, kh, kw, out_c]
+        if w is None:
+            return 0
+        _, kh, kw, _ = w.shape
+        return out_elems * kh * kw
+    return 0