mblt-npu-python 0.0.0__py3-none-any.whl

mblt_npu/__init__.py

@@ -0,0 +1,36 @@
+"""Shared NPU access for the mblt Python packages.
+
+`MobilintNPUBackend` is defined exactly once, here, because the alternative
+was a copy in each of mblt-vision-python, mblt-transformers-python and
+mblt-MeloTTS-python that nothing would keep in sync.
+
+`logging` lives here too rather than in vision, its only caller, because the
+two are mutually dependent: npu_backend imports log_model_details and
+log_model_details reads a MobilintNPUBackend's fields.
+"""
+
+from .npu_backend import (
+    BACKEND_CLASSES,
+    DEFAULT_TARGET_DEVICE,
+    MobilintAriesBackend,
+    MobilintNPUBackend,
+    MobilintRegulusBackend,
+    backend_class_for,
+    normalize_target_device,
+)
+from .logging import log_model_details
+from .onnx_backend import ONNXBackend
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "BACKEND_CLASSES",
+    "DEFAULT_TARGET_DEVICE",
+    "MobilintAriesBackend",
+    "MobilintNPUBackend",
+    "MobilintRegulusBackend",
+    "ONNXBackend",
+    "backend_class_for",
+    "log_model_details",
+    "normalize_target_device",
+]

mblt_npu/logging.py

@@ -0,0 +1,54 @@
+import hashlib
+import os
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .npu_backend import MobilintNPUBackend
+
+_VERBOSE_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+
+def _is_verbose_enabled() -> bool:
+    return os.getenv("MBLT_MODEL_ZOO_VERBOSE", "").lower() in _VERBOSE_TRUE_VALUES
+
+
+def _md5_hash_from_file(file_path: str) -> str:
+    hash_md5 = hashlib.md5()
+    with open(file_path, "rb") as file_handle:
+        for chunk in iter(lambda: file_handle.read(8192), b""):
+            hash_md5.update(chunk)
+    return hash_md5.hexdigest()
+
+
+def log_model_details(
+    model_path: str, npu_backend: Optional["MobilintNPUBackend"] = None
+) -> None:
+    """Print model metadata when verbose logging is enabled."""
+    if not _is_verbose_enabled():
+        return
+
+    print("Model Initialized")
+    print(f"Model Size: {os.path.getsize(model_path) / 1024 / 1024:.2f} MB")
+    print(f"Model Hash: {_md5_hash_from_file(model_path)}")
+
+    if npu_backend is not None:
+        print(f"Device Number: {npu_backend.dev_no}")
+        print(f"Core Mode: {npu_backend.core_mode}")
+        if npu_backend.core_mode == "single":
+            print(f"Target Cores: {npu_backend.target_cores}")
+        else:
+            print(f"Target Clusters: {npu_backend.target_clusters}")
+        if npu_backend.mxq_model.get_num_model_variants() == 1:
+            print(f"Model Input Shape: {npu_backend.mxq_model.get_model_input_shape()}")
+            print(
+                f"Model Output Shape: {npu_backend.mxq_model.get_model_output_shape()}"
+            )
+        else:
+            for i in range(npu_backend.mxq_model.get_num_model_variants()):
+                print(f"Model Variant {i}")
+                print(
+                    f"\tInput Shape: {npu_backend.mxq_model.get_model_variant_handle(i).get_model_input_shape()}"
+                )
+                print(
+                    f"\tOutput Shape: {npu_backend.mxq_model.get_model_variant_handle(i).get_model_output_shape()}"
+                )

mblt_npu/npu_backend.py

@@ -0,0 +1,632 @@
+import logging
+import os
+from typing import Any, Dict, List, Literal, Optional, Sequence, Union
+
+from huggingface_hub import HfApi, hf_hub_download
+from huggingface_hub.errors import EntryNotFoundError
+from qbruntime import Accelerator, Cluster, Core, CoreId, Model, ModelConfig
+
+from .logging import log_model_details
+
+logger = logging.getLogger(__name__)
+
+
+def _enum_value(value: Any) -> int:
+    """Return an integer enum value across qbruntime binding versions."""
+
+    while hasattr(value, "value"):
+        value = value.value
+    return int(value)
+
+
+# qbruntime has shipped both a Python enum wrapping a native enum and a direct
+# enum binding. Peel every ``.value`` layer so serialized fields are stable
+# integers across both forms (Cluster0 is 65536; Core0 is 1).
+cluster_map = {
+    _enum_value(cluster): cluster for cluster in (Cluster.Cluster0, Cluster.Cluster1)
+}
+core_map = {
+    _enum_value(core): core for core in (Core.Core0, Core.Core1, Core.Core2, Core.Core3)
+}
+
+DEFAULT_TARGET_DEVICE = "aries-rb"
+"""Default supported Mobilint NPU board."""
+
+_TARGET_DEVICE_ALIASES = {
+    # Configurations written before board-specific target devices were exposed
+    # used these generic product names. Keep them readable, but always serialize
+    # one of the supported board identifiers below.
+    "aries": "aries-rb",
+    "regulus": "regulus-ra",
+}
+
+
+def normalize_target_device(target_device: str) -> str:
+    """Return a supported board identifier, accepting legacy generic product names."""
+
+    if not isinstance(target_device, str):
+        raise TypeError(
+            f"target_device must be a string, got {type(target_device).__name__}."
+        )
+    return _TARGET_DEVICE_ALIASES.get(target_device.lower(), target_device.lower())
+
+
+class MobilintNPUBackend:
+    """Shared NPU access. Subclassed per product, because core allocation differs.
+
+    The SDK exposes every core-mode setter on `ModelConfig` regardless of product
+    and offers no capability query, so "does this device support global8" is only
+    answerable by trying it and reading a load failure. Aries has two clusters of
+    four cores and four modes; Regulus has one core and only single. Encoding that
+    in types is what turns a late `StatusCode(16)` into an argument error.
+
+    Instantiating this class directly selects a backend from ``target_device``.
+    The default is ``aries-rb``; ``regulus-ra`` and ``regulus-rb`` select the
+    Regulus implementation. Existing generic ``aries`` and ``regulus`` config
+    values remain accepted as input compatibility aliases.
+    """
+
+    # Aries geometry. Overridden per product.
+    num_of_clusters = 2
+    num_of_cores_in_cluster = 4
+
+    #: Core modes this product accepts. Empty on the base class, which never runs.
+    supported_core_modes: tuple = ()
+    #: Default board when this subclass is instantiated directly.
+    default_target_device: str = DEFAULT_TARGET_DEVICE
+    #: Board identifiers accepted by this backend implementation.
+    supported_target_devices: tuple[str, ...] = ()
+
+    def __new__(cls, *args, **kwargs):
+        # MobilintNPUBackend(...) remains the public construction point. The
+        # board identifier picks its implementation.
+        if cls is MobilintNPUBackend:
+            # ``target_device`` is the eighth positional parameter of
+            # ``__init__`` as well as a keyword argument. Respect either form
+            # before selecting the product-specific implementation.
+            requested_device = kwargs.get("target_device")
+            if requested_device is None and len(args) > 7:
+                requested_device = args[7]
+            requested_device = requested_device or DEFAULT_TARGET_DEVICE
+            device = normalize_target_device(requested_device)
+            cls = backend_class_for(device)
+        return super().__new__(cls)
+
+    def __init__(
+        self,
+        mxq_path: str = "",
+        dev_no: int = 0,
+        core_mode: Literal["auto", "single", "multi", "global4", "global8"] = "single",
+        target_cores: Optional[List[Union[str, "CoreId"]]] = None,
+        target_clusters: Optional[Sequence[Union[int, "Cluster"]]] = None,
+        revision: Optional[str] = None,
+        commit_hash: Optional[str] = None,
+        target_device: str | None = None,
+        **kwargs,
+    ):
+        resolved_target_device = normalize_target_device(
+            target_device or self.default_target_device
+        )
+        if resolved_target_device not in self.supported_target_devices:
+            raise ValueError(
+                f"target_device {resolved_target_device!r} is not supported by "
+                f"{type(self).__name__}; expected one of "
+                f"{', '.join(self.supported_target_devices)}."
+            )
+
+        # ``from_dict`` supplies a serialized repository name through ``kwargs``.
+        # Keep it so an MXQ path can still be resolved from the Hub after a
+        # backend round trip; model mixins may replace it later when applicable.
+        self.name_or_path: str = kwargs.get("name_or_path", "")
+        self.target_device = resolved_target_device
+        self.revision = revision
+        self._commit_hash = commit_hash
+        self.mxq_path = mxq_path
+        self.dev_no = dev_no
+        self.core_mode = core_mode
+        if core_mode not in self.supported_core_modes:
+            raise ValueError(
+                f"core_mode {core_mode!r} is not available on "
+                f"{self.target_device}; supported: "
+                f"{', '.join(self.supported_core_modes)}. Refusing here rather than "
+                "letting the SDK fail at Model::create, which is where an "
+                "unsupported mode surfaces otherwise."
+            )
+
+        self._target_cores_serialized: List[str] = []
+        self.target_cores = target_cores if target_cores is not None else []
+
+        self._target_clusters_serialized: List[str] = []
+        self.target_clusters = target_clusters if target_clusters is not None else []
+
+    def check_model_path(self, mxq_path: str) -> str:
+        # 1. current relative/absolute path
+        if os.path.exists(mxq_path):
+            return mxq_path
+
+        # 2. inside the local path
+        if os.path.isdir(self.name_or_path):
+            local_path = os.path.join(self.name_or_path, mxq_path)
+            if os.path.exists(local_path):
+                return local_path
+
+        # 3. If none of above, download mxq file from hub
+        else:
+            name_or_path = (
+                self.name_or_path
+                if self.name_or_path.startswith("mobilint/")
+                else "mobilint/" + self.name_or_path
+            )
+            revision = (
+                getattr(self, "revision", None)
+                or getattr(self, "_commit_hash", None)
+                or self._infer_hf_revision_from_cache(name_or_path)
+            )
+            try:
+                return hf_hub_download(
+                    repo_id=name_or_path,
+                    filename=mxq_path,
+                    revision=revision,
+                )
+            except EntryNotFoundError:
+                try:
+                    return hf_hub_download(
+                        repo_id=name_or_path,
+                        filename=mxq_path,
+                        revision=revision,
+                    )
+                except EntryNotFoundError:
+                    cached = self._find_cached_mxq(name_or_path, mxq_path, revision)
+                    if cached is not None:
+                        return cached
+                    mxq_candidate = self._find_mxq_from_hub(
+                        name_or_path, mxq_path, revision
+                    )
+                    if mxq_candidate is None:
+                        raise
+                    return hf_hub_download(
+                        repo_id=name_or_path,
+                        filename=mxq_candidate,
+                        revision=revision,
+                    )
+
+        raise Exception(f"[Mobilint] Error: Could not locate {mxq_path}.")
+
+    @staticmethod
+    def _infer_hf_revision_from_cache(repo_id: str) -> Optional[str]:
+        if not repo_id or "/" not in repo_id:
+            return None
+
+        cache_root = os.getenv("HUGGINGFACE_HUB_CACHE") or os.getenv("HF_HUB_CACHE")
+        if not cache_root:
+            hf_home = os.getenv("HF_HOME") or os.path.join(
+                os.path.expanduser("~"),
+                ".cache",
+                "huggingface",
+            )
+            cache_root = os.path.join(hf_home, "hub")
+
+        repo_dir = os.path.join(cache_root, f"models--{repo_id.replace('/', '--')}")
+        refs_dir = os.path.join(repo_dir, "refs")
+        if os.path.isdir(refs_dir):
+            for ref_name in ("main", "master"):
+                ref_path = os.path.join(refs_dir, ref_name)
+                if os.path.isfile(ref_path):
+                    try:
+                        with open(ref_path, "r", encoding="utf-8") as f:
+                            ref = f.read().strip()
+                        if ref:
+                            return ref
+                    except OSError:
+                        pass
+            try:
+                for entry in os.listdir(refs_dir):
+                    ref_path = os.path.join(refs_dir, entry)
+                    if os.path.isfile(ref_path):
+                        with open(ref_path, "r", encoding="utf-8") as f:
+                            ref = f.read().strip()
+                        if ref:
+                            return ref
+            except OSError:
+                pass
+
+        snapshots_dir = os.path.join(repo_dir, "snapshots")
+        if os.path.isdir(snapshots_dir):
+            try:
+                for entry in os.listdir(snapshots_dir):
+                    if os.path.isdir(os.path.join(snapshots_dir, entry)):
+                        return entry
+            except OSError:
+                pass
+
+        return None
+
+    @staticmethod
+    def _find_cached_mxq(
+        repo_id: str, mxq_path: str, revision: Optional[str] = None
+    ) -> Optional[str]:
+        if not repo_id or "/" not in repo_id:
+            return None
+
+        cache_root = os.getenv("HUGGINGFACE_HUB_CACHE") or os.getenv("HF_HUB_CACHE")
+        if not cache_root:
+            hf_home = os.getenv("HF_HOME") or os.path.join(
+                os.path.expanduser("~"),
+                ".cache",
+                "huggingface",
+            )
+            cache_root = os.path.join(hf_home, "hub")
+
+        repo_dir = os.path.join(cache_root, f"models--{repo_id.replace('/', '--')}")
+        snapshots_dir = os.path.join(repo_dir, "snapshots")
+        if not os.path.isdir(snapshots_dir):
+            return None
+
+        rel_candidates = [mxq_path, os.path.basename(mxq_path)]
+        try:
+            snapshots = os.listdir(snapshots_dir)
+            if revision is not None:
+                snapshots = [snapshot for snapshot in snapshots if snapshot == revision]
+            for snapshot in snapshots:
+                snapshot_dir = os.path.join(snapshots_dir, snapshot)
+                if not os.path.isdir(snapshot_dir):
+                    continue
+                for rel in rel_candidates:
+                    candidate = os.path.join(snapshot_dir, rel)
+                    if os.path.isfile(candidate):
+                        return candidate
+        except OSError:
+            return None
+
+        return None
+
+    @staticmethod
+    def _find_mxq_from_hub(
+        repo_id: str, mxq_path: str, revision: Optional[str] = None
+    ) -> Optional[str]:
+        try:
+            files = HfApi().list_repo_files(repo_id=repo_id, revision=revision)
+        except Exception:
+            return None
+
+        basename = os.path.basename(mxq_path)
+        if basename in files:
+            return basename
+        if mxq_path in files:
+            return mxq_path
+
+        raise ValueError(
+            f"Cannot find {mxq_path} file from HuggingFace repo: f{repo_id}"
+        )
+
+    def _configure_core_mode(self, mc: "ModelConfig") -> None:
+        raise NotImplementedError(
+            "MobilintNPUBackend is a base class; use MobilintAriesBackend, "
+            "MobilintRegulusBackend, or backend_class_for(target_device)."
+        )
+
+    def create(self):
+        self.acc = Accelerator(self.dev_no)
+        mc = ModelConfig()
+        self._configure_core_mode(mc)
+
+        model_path = self.check_model_path(self.mxq_path)
+        self.mxq_model = Model(model_path, mc)
+        log_model_details(model_path, self)
+
+    def launch(self):
+        self.mxq_model.launch(self.acc)
+
+    def __call__(self, x: Any) -> Any:
+        """Run inference with the loaded MXQ model.
+
+        This compatibility entry point is used by the Vision engine and mirrors
+        the historical Model Zoo backend contract.
+        """
+
+        return self.mxq_model.infer(x)
+
+    def get_dtype(self) -> str:
+        """Return the loaded model input data type as a runtime string."""
+
+        return str(self.mxq_model.get_model_input_data_type())
+
+    def dispose(self):
+        self.mxq_model.dispose()
+
+    @property
+    def target_cores(self) -> List["CoreId"]:
+        result = []
+        if not hasattr(self, "_target_cores_serialized"):
+            return []
+
+        for s in self._target_cores_serialized:
+            try:
+                c_val, r_val = map(int, s.split(":"))
+                if c_val in (0, 1):
+                    cluster = (Cluster.Cluster0, Cluster.Cluster1)[c_val]
+                    core = (Core.Core0, Core.Core1, Core.Core2, Core.Core3)[r_val]
+                else:
+                    cluster = cluster_map[c_val]
+                    core = core_map[r_val]
+                core_id_factory: Any = CoreId
+                try:
+                    # qbruntime's current binding exposes a no-argument
+                    # constructor, although older type stubs declare only the
+                    # legacy two-argument form.
+                    core_id = core_id_factory()
+                    core_id.cluster = cluster
+                    core_id.core = core
+                except TypeError:
+                    core_id = CoreId(cluster, core)
+                result.append(core_id)
+            except Exception as e:
+                # Raising rather than warning-and-skipping: this used to drop the
+                # entry and return a shorter list, so a caller who asked for two
+                # specific cores silently got none and ran on whatever the default
+                # allocation gave them.
+                raise ValueError(
+                    f"cannot deserialize target core {s!r}: expected "
+                    f'"<cluster value>:<core value>" with cluster in '
+                    f"{sorted(cluster_map)} and core in {sorted(core_map)}"
+                ) from e
+        return result
+
+    @target_cores.setter
+    def target_cores(self, values: List[Union[str, "CoreId"]]):
+        serialized = []
+        for v in values:
+            if isinstance(v, CoreId):
+                cluster_index = next(
+                    index
+                    for index, cluster in enumerate(
+                        (Cluster.Cluster0, Cluster.Cluster1)
+                    )
+                    if _enum_value(cluster) == _enum_value(v.cluster)
+                )
+                core_index = next(
+                    index
+                    for index, core in enumerate(
+                        (Core.Core0, Core.Core1, Core.Core2, Core.Core3)
+                    )
+                    if _enum_value(core) == _enum_value(v.core)
+                )
+                serialized.append(f"{cluster_index}:{core_index}")
+            elif isinstance(v, str):
+                if ":" in v:
+                    serialized.append(v)
+                else:
+                    raise ValueError(f"Invalid format: {v}")
+            else:
+                raise TypeError(f"Unsupported type: {type(v)}")
+
+        self._target_cores_serialized = serialized
+
+    @property
+    def target_clusters(self) -> List["Cluster"]:
+        result = []
+        if not hasattr(self, "_target_clusters_serialized"):
+            return []
+
+        for s in self._target_clusters_serialized:
+            try:
+                c_val = int(s)
+                result.append(
+                    (Cluster.Cluster0, Cluster.Cluster1)[c_val]
+                    if c_val in (0, 1)
+                    else cluster_map[c_val]
+                )
+            except Exception as e:
+                raise ValueError(
+                    f"cannot deserialize target cluster {s!r}: expected one of "
+                    f"{sorted(cluster_map)}"
+                ) from e
+        return result
+
+    @target_clusters.setter
+    def target_clusters(self, values: Sequence[Union[int, "Cluster"]]):
+        serialized = []
+        for v in values:
+            if isinstance(v, Cluster):
+                serialized.append(
+                    next(
+                        index
+                        for index, cluster in enumerate(
+                            (Cluster.Cluster0, Cluster.Cluster1)
+                        )
+                        if _enum_value(cluster) == _enum_value(v)
+                    )
+                )
+            elif isinstance(v, int):
+                # Callers pass 0 and 1 meaning "first cluster", "second cluster".
+                # Preserve this public serialized form while accepting native enum
+                # values from older callers as well.
+                ordinals = [Cluster.Cluster0, Cluster.Cluster1]
+                if 0 <= v < len(ordinals):
+                    serialized.append(v)
+                elif v in cluster_map:
+                    serialized.append(v)
+                else:
+                    raise ValueError(
+                        f"cluster {v} is neither an index into "
+                        f"{[c.name for c in ordinals]} nor one of {sorted(cluster_map)}"
+                    )
+            else:
+                raise TypeError(f"Unsupported type: {type(v)}")
+
+        self._target_clusters_serialized = serialized
+
+    def to_dict(self, prefix="") -> Dict[str, Any]:
+        p = prefix
+        result = {
+            "name_or_path": self.name_or_path,
+            f"{p}mxq_path": self.mxq_path,
+            f"{p}dev_no": self.dev_no,
+            f"{p}core_mode": self.core_mode,
+            f"{p}revision": self.revision,
+            f"{p}commit_hash": self._commit_hash,
+            f"{p}target_device": self.target_device,
+        }
+
+        if self.core_mode == "single":
+            result[f"{p}target_cores"] = self._target_cores_serialized
+        else:
+            result[f"{p}target_clusters"] = self._target_clusters_serialized
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any], prefix: str = "") -> "MobilintNPUBackend":
+        """Rebuilds a backend from a flat config dict.
+
+        Called as `MobilintNPUBackend.from_dict(...)`, `cls` is the base and
+        `__new__` picks the subclass from `target_device`. Called on a subclass,
+        a serialized board supported by that subclass is retained; a board for a
+        different backend falls back to the subclass default.
+        """
+        p = prefix
+        data = dict(data)
+        if cls is not MobilintNPUBackend:
+            serialized_target_device = data.get(f"{prefix}target_device")
+            if serialized_target_device is None:
+                data[f"{prefix}target_device"] = cls.default_target_device
+            else:
+                target_device = normalize_target_device(serialized_target_device)
+                data[f"{prefix}target_device"] = (
+                    target_device
+                    if target_device in cls.supported_target_devices
+                    else cls.default_target_device
+                )
+        if f"{p}target_cores" in data.keys() and f"{p}target_clusters" in data.keys():
+            logger.warning(f"{p}target_cores and {p}target_clusters are both set!")
+            logger.warning(
+                f"If {p}core_mode is `single`, only {p}target_cores will be used."
+            )
+            logger.warning(
+                f"If {p}core_mode is `multi`, `global4`, or `global8`, only {p}target_clusters will be used."
+            )
+
+        return cls(
+            name_or_path=data.pop("name_or_path", ""),
+            mxq_path=data.pop(f"{p}mxq_path", ""),
+            dev_no=data.pop(f"{p}dev_no", 0),
+            core_mode=data.pop(f"{p}core_mode", "single"),
+            target_cores=data.pop(f"{p}target_cores", None),
+            target_clusters=data.pop(f"{p}target_clusters", None),
+            revision=data.pop(f"{p}revision", None),
+            commit_hash=data.pop(f"{p}commit_hash", None),
+            target_device=data.pop(f"{p}target_device", None),
+        )
+
+
+class MobilintAriesBackend(MobilintNPUBackend):
+    """Aries: two clusters of four cores, four allocation modes plus auto."""
+
+    num_of_clusters = 2
+    num_of_cores_in_cluster = 4
+    supported_core_modes = ("auto", "single", "multi", "global4", "global8")
+    default_target_device = "aries-rb"
+    supported_target_devices = ("aries-rb",)
+
+    def _configure_core_mode(self, mc: "ModelConfig") -> None:
+        if self.core_mode == "auto":
+            # What an unconfigured ModelConfig already is. Named explicitly because
+            # the previous code reached it by doing nothing under the label
+            # "single", and measured, the default is CoreMode.Auto with
+            # num_cores=0 — not single with all cores as its comment claimed.
+            mc.set_auto_core_mode()
+        elif self.core_mode == "single":
+            cores = self.target_cores
+            if cores:
+                mc.set_single_core_mode(core_ids=cores)
+            else:
+                # With no explicit cores, let qbruntime allocate one local core.
+                mc.set_single_core_mode(1)
+        elif self.core_mode == "multi":
+            mc.set_multi_core_mode(self.target_clusters)
+        elif self.core_mode == "global4":
+            mc.set_global4_core_mode(self.target_clusters)
+        elif self.core_mode == "global8":
+            clusters = self.target_clusters
+            expected_clusters = {
+                _enum_value(Cluster.Cluster0),
+                _enum_value(Cluster.Cluster1),
+            }
+            if (
+                len(clusters) != len(expected_clusters)
+                or {_enum_value(cluster) for cluster in clusters} != expected_clusters
+            ):
+                raise ValueError(
+                    "global8 requires target_clusters to select both Aries clusters."
+                )
+            mc.set_global8_core_mode()
+        else:  # unreachable: __init__ validates against supported_core_modes
+            raise ValueError(f"unhandled core_mode {self.core_mode!r}")
+
+
+class MobilintRegulusBackend(MobilintNPUBackend):
+    """Regulus: one core, single only.
+
+    Measured on a board rather than inferred: `global4` is rejected by qbruntime
+    and `global8` fails Model::create with StatusCode(16), while `auto` and
+    `single` both run. Cluster arguments have nothing to address, so they are
+    refused instead of ignored — ignoring them would let a caller believe an
+    allocation happened.
+    """
+
+    num_of_clusters = 1
+    num_of_cores_in_cluster = 1
+    supported_core_modes = ("auto", "single")
+    default_target_device = "regulus-ra"
+    supported_target_devices = ("regulus-ra", "regulus-rb")
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        if self.target_clusters:
+            raise ValueError(
+                "target_clusters is meaningless on regulus, which has a single "
+                f"core: got {self._target_clusters_serialized}. Remove it, or use "
+                "target_device='aries-rb'."
+            )
+        cores = self.target_cores
+        expected_cluster = _enum_value(Cluster.Cluster0)
+        expected_core = _enum_value(Core.Core0)
+        if len(cores) > 1 or any(
+            _enum_value(core.cluster) != expected_cluster
+            or _enum_value(core.core) != expected_core
+            for core in cores
+        ):
+            raise ValueError(
+                "target_cores on regulus may select only its sole core (0:0)."
+            )
+
+    def _configure_core_mode(self, mc: "ModelConfig") -> None:
+        if self.core_mode == "auto":
+            mc.set_auto_core_mode()
+        else:
+            cores = self.target_cores
+            if cores:
+                mc.set_single_core_mode(core_ids=cores)
+            else:
+                mc.set_single_core_mode(1)
+
+
+#: target_device -> backend class. A mapping rather than a chain of ifs so that
+#: adding a product is one entry and an unknown one is an error naming the
+#: choices, instead of silently behaving like Aries.
+BACKEND_CLASSES = {
+    "aries-rb": MobilintAriesBackend,
+    "regulus-ra": MobilintRegulusBackend,
+    "regulus-rb": MobilintRegulusBackend,
+}
+
+
+def backend_class_for(target_device: str):
+    normalized_target_device = normalize_target_device(target_device)
+    try:
+        return BACKEND_CLASSES[normalized_target_device]
+    except KeyError:
+        raise ValueError(
+            f"unknown target_device {target_device!r}; "
+            f"expected one of {', '.join(sorted(BACKEND_CLASSES))}"
+        ) from None

mblt_npu/onnx_backend.py

@@ -0,0 +1,90 @@
+"""Optional ONNX Runtime backend shared by Mobilint Python packages."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from typing import Any
+
+
+class ONNXBackend:
+    """Run an ONNX model through an optional ONNX Runtime installation.
+
+    ``onnxruntime`` is imported only by :meth:`create`, keeping the base NPU
+    package usable for MXQ-only applications.
+    """
+
+    def __init__(
+        self,
+        model_path: str,
+        *,
+        providers: Sequence[str] | None = None,
+        ort_module: Any | None = None,
+    ) -> None:
+        self.model_path = model_path
+        self.providers = (
+            list(providers) if providers is not None else ["CPUExecutionProvider"]
+        )
+        self._ort_module = ort_module
+        self.session: Any | None = None
+
+    def _load_onnxruntime(self) -> Any:
+        if self._ort_module is not None:
+            return self._ort_module
+        try:
+            import onnxruntime
+        except ImportError as exc:
+            raise ImportError(
+                "onnxruntime is required for ONNX inference. "
+                "Install it with `pip install mblt-npu-python[onnxruntime]`."
+            ) from exc
+        return onnxruntime
+
+    def create(self) -> None:
+        """Create the ONNX Runtime inference session for ``model_path``."""
+
+        if not os.path.isfile(self.model_path):
+            raise FileNotFoundError(f"ONNX file not found at: {self.model_path}")
+        self.session = self._load_onnxruntime().InferenceSession(
+            self.model_path, providers=self.providers
+        )
+
+    def launch(self) -> None:
+        """Match the MXQ backend lifecycle; ONNX Runtime needs no launch step."""
+
+        self._require_session()
+
+    def __call__(self, inputs: dict[str, Any]) -> Any:
+        """Run inference and return every model output in ONNX Runtime order."""
+
+        return self._require_session().run(None, inputs)
+
+    def run(self, output_names: Sequence[str] | None, inputs: dict[str, Any]) -> Any:
+        """Run inference for the requested ONNX output names."""
+
+        return self._require_session().run(output_names, inputs)
+
+    def get_inputs(self) -> Any:
+        """Return ONNX Runtime input metadata."""
+
+        return self._require_session().get_inputs()
+
+    def get_outputs(self) -> Any:
+        """Return ONNX Runtime output metadata."""
+
+        return self._require_session().get_outputs()
+
+    def get_dtype(self) -> str:
+        """Return the first ONNX input element type."""
+
+        return str(self.get_inputs()[0].type)
+
+    def dispose(self) -> None:
+        """Release the session reference held by this backend."""
+
+        self.session = None
+
+    def _require_session(self) -> Any:
+        if self.session is None:
+            raise RuntimeError("ONNX backend is not initialized; call create() first.")
+        return self.session

mblt_npu/pytest_plugin.py

@@ -0,0 +1,218 @@
+"""Shared pytest options and fixtures for the mblt packages.
+
+Lives here rather than as a copy in each package's tests/ for the same reason
+npu_backend does: four copies of the NPU option parsing would drift. Each
+package's tests/conftest.py is a star-import of this module, which is what puts
+pytest_addoption in the root conftest namespace where pytest looks for it.
+"""
+
+import warnings
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+import pytest
+
+_WARNED_UNUSED_PREFIXES: set[str] = set()
+
+
+def _parse_target_cores(value: Optional[str]) -> Optional[List[str]]:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    return [item.strip() for item in text.split(";") if item.strip()]
+
+
+def _parse_target_clusters(value: Optional[str]) -> Optional[List[int]]:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    clusters: list[int] = []
+    for item in text.split(";"):
+        item = item.strip()
+        if not item:
+            continue
+        clusters.append(int(item))
+    return clusters
+
+
+def _collect_npu_kwargs(
+    config: pytest.Config, prefix: str
+) -> tuple[dict[str, Any], bool]:
+    opt_prefix = f"--{prefix}-" if prefix else "--"
+    mxq_path = config.getoption(f"{opt_prefix}mxq-path")
+    dev_no = config.getoption(f"{opt_prefix}dev-no")
+    core_mode = config.getoption(f"{opt_prefix}core-mode")
+    target_cores_raw = config.getoption(f"{opt_prefix}target-cores")
+    target_cores = _parse_target_cores(target_cores_raw)
+    target_clusters_raw = config.getoption(f"{opt_prefix}target-clusters")
+    target_clusters = _parse_target_clusters(target_clusters_raw)
+
+    kwargs: dict[str, Any] = {}
+    provided = False
+
+    if mxq_path:
+        kwargs[f"{prefix + '_' if prefix else ''}mxq_path"] = mxq_path
+        provided = True
+    if dev_no is not None:
+        kwargs[f"{prefix + '_' if prefix else ''}dev_no"] = dev_no
+        provided = True
+    if core_mode:
+        kwargs[f"{prefix + '_' if prefix else ''}core_mode"] = core_mode
+        provided = True
+    if target_cores is not None:
+        kwargs[f"{prefix + '_' if prefix else ''}target_cores"] = target_cores
+        provided = True
+    if target_clusters is not None:
+        kwargs[f"{prefix + '_' if prefix else ''}target_clusters"] = target_clusters
+        provided = True
+
+    return kwargs, provided
+
+
+@dataclass(frozen=True)
+class NpuParams:
+    base: dict[str, Any]
+    encoder: dict[str, Any]
+    decoder: dict[str, Any]
+    text: dict[str, Any]
+    vision: dict[str, Any]
+    _provided: dict[str, bool]
+
+    def warn_unused(self, used_prefixes: set[str]) -> None:
+        for prefix, provided in self._provided.items():
+            if (
+                provided
+                and prefix not in used_prefixes
+                and prefix not in _WARNED_UNUSED_PREFIXES
+            ):
+                _WARNED_UNUSED_PREFIXES.add(prefix)
+                warnings.warn(
+                    f"Provided {prefix} NPU backend options will be ignored for this model.",
+                    UserWarning,
+                )
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--mxq-path",
+        action="store",
+        default=None,
+        help="Override default mxq_path for pipeline loading.",
+    )
+    parser.addoption(
+        "--dev-no",
+        action="store",
+        default=None,
+        type=int,
+        help="NPU device number.",
+    )
+    parser.addoption(
+        "--core-mode",
+        action="store",
+        default=None,
+        help="NPU core mode (single, multi, global4, global8).",
+    )
+    parser.addoption(
+        "--target-cores",
+        action="store",
+        default=None,
+        help='Target cores (e.g., "0:0;0:1;0:2;0:3").',
+    )
+    parser.addoption(
+        "--target-clusters",
+        action="store",
+        default=None,
+        help='Target clusters (e.g., "0;1").',
+    )
+    for prefix in ("encoder", "decoder", "vision", "text"):
+        parser.addoption(
+            f"--{prefix}-mxq-path",
+            action="store",
+            default=None,
+            help=f"Override {prefix} mxq_path.",
+        )
+        parser.addoption(
+            f"--{prefix}-dev-no",
+            action="store",
+            default=None,
+            type=int,
+            help=f"{prefix} NPU device number.",
+        )
+        parser.addoption(
+            f"--{prefix}-core-mode",
+            action="store",
+            default=None,
+            help=f"{prefix} NPU core mode (single, multi, global4, global8).",
+        )
+        parser.addoption(
+            f"--{prefix}-target-cores",
+            action="store",
+            default=None,
+            help=f'{prefix} target cores (e.g., "0:0;0:1;0:2;0:3").',
+        )
+        parser.addoption(
+            f"--{prefix}-target-clusters",
+            action="store",
+            default=None,
+            help=f'{prefix} target clusters (e.g., "0;1").',
+        )
+    parser.addoption(
+        "--revision",
+        action="store",
+        default=None,
+        help="Override model revision (e.g., W8).",
+    )
+    parser.addoption(
+        "--embedding-weight",
+        action="store",
+        default=None,
+        help="Path to custom embedding weights.",
+    )
+
+
+@pytest.fixture(scope="module")
+def mxq_path(request):
+    return request.config.getoption("--mxq-path")
+
+
+@pytest.fixture(scope="module")
+def revision(request):
+    return request.config.getoption("--revision")
+
+
+@pytest.fixture(scope="module")
+def embedding_weight(request):
+    return request.config.getoption("--embedding-weight")
+
+
+@pytest.fixture(scope="module")
+def npu_params(request, embedding_weight):
+    config = request.config
+    base_kwargs, base_provided = _collect_npu_kwargs(config, "")
+    if embedding_weight:
+        base_kwargs["embedding_weight"] = embedding_weight
+        base_provided = True
+
+    encoder_kwargs, encoder_provided = _collect_npu_kwargs(config, "encoder")
+    decoder_kwargs, decoder_provided = _collect_npu_kwargs(config, "decoder")
+    vision_kwargs, vision_provided = _collect_npu_kwargs(config, "vision")
+    text_kwargs, text_provided = _collect_npu_kwargs(config, "text")
+
+    return NpuParams(
+        base=base_kwargs,
+        encoder=encoder_kwargs,
+        decoder=decoder_kwargs,
+        text=text_kwargs,
+        vision=vision_kwargs,
+        _provided={
+            "base": base_provided,
+            "encoder": encoder_provided,
+            "decoder": decoder_provided,
+            "vision": vision_provided,
+            "text": text_provided,
+        },
+    )

mblt_npu_python-0.0.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: mblt-npu-python
+Version: 0.0.0
+Summary: Shared NPU access for the Mobilint Python packages
+Author: Mobilint
+License: BSD-3-Clause
+Project-URL: Home, https://www.mobilint.com/
+Project-URL: Repository, https://github.com/mobilint/mblt-npu-python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mobilint-qb-runtime>=1.0.0
+Requires-Dist: huggingface-hub
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: onnxruntime
+Requires-Dist: onnxruntime; extra == "onnxruntime"
+Dynamic: license-file
+
+# Mobilint NPU Python
+
+Shared runtime support for applications that run MXQ models on Mobilint NPUs or ONNX models through ONNX Runtime.
+`mblt-npu-python` provides the common backend, device-selection rules, Hugging Face
+artifact resolution, and model-detail logging used by Mobilint Python packages. It
+is a library dependency, rather than an end-user model catalog.
+
+Version `0.0.0` is the initial standalone release.
+
+`logging` ships here rather than with its only caller because the two are mutually
+dependent — `npu_backend` imports `log_model_details`, and `log_model_details` reads
+a `MobilintNPUBackend`'s fields.
+
+## Installation
+
+```bash
+pip install mblt-npu-python
+```
+
+This package requires a supported Linux environment with
+[`mobilint-qb-runtime`](https://pypi.org/project/mobilint-qb-runtime/) available
+and Python 3.10 through 3.12.
+
+## Public API
+
+Import the backend from `mblt_npu`:
+
+```python
+from mblt_npu import MobilintNPUBackend
+
+backend = MobilintNPUBackend(
+    mxq_path="model.mxq",
+    core_mode="single",
+)
+backend.create()
+try:
+    backend.launch()
+    outputs = backend.mxq_model.infer([input_tensor])
+finally:
+    backend.dispose()
+```
+
+`MobilintNPUBackend` selects the appropriate implementation from
+`target_device` (default: `"aries-rb"`). `"aries-rb"` selects
+`MobilintAriesBackend`; `"regulus-ra"` and `"regulus-rb"` select
+`MobilintRegulusBackend`. The former generic values `"aries"` and `"regulus"`
+remain accepted when loading older configurations.
+`backend_class_for()` and `BACKEND_CLASSES` are available for integrations that
+need to inspect the supported targets.
+
+For ONNX inference, install the optional runtime extra and use `ONNXBackend`:
+
+```bash
+pip install "mblt-npu-python[onnxruntime]"
+```
+
+```python
+from mblt_npu import ONNXBackend
+
+backend = ONNXBackend("model.onnx")
+backend.create()
+outputs = backend({"images": input_array})
+backend.dispose()
+```
+
+`ONNXBackend` imports `onnxruntime` only when it creates a session.
+
+Most users should access the backend through a model package such as
+[`mblt-vision-python`](https://github.com/mobilint/mblt-vision-python), which owns
+model configuration, preprocessing, and postprocessing.
+
+## Testing helpers
+
+The optional `test` extra provides a shared pytest plugin with NPU options and the
+`npu_params` fixture used by Mobilint package test suites:
+
+```bash
+pip install "mblt-npu-python[test]"
+```
+
+Import `mblt_npu.pytest_plugin` from a repository's root `tests/conftest.py` to
+register its options. The plugin is intentionally not auto-registered, so projects
+control when those command-line options are exposed.
+
+## Support and issues
+
+For installation, runtime, or integration support, visit the
+[Mobilint forum](https://discuss.mobilint.com/). Report reproducible package issues in the
+[mblt-npu-python issue tracker](https://github.com/mobilint/mblt-npu-python/issues).
+
+## License
+
+Distributed under the [BSD 3-Clause License](LICENSE).

mblt_npu_python-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mblt_npu/__init__.py,sha256=u19Xfg_XvdmOLGQnTTwR_8g1l2-H_K_Q6vpjHI9w0Xw,1018
+mblt_npu/logging.py,sha256=vmNHi7IgX8PUD58EwyJLtw-g1iJJMt6_Al4xGyLrV0A,2005
+mblt_npu/npu_backend.py,sha256=cKJBNOzUodo_xkIxZTQWLXUy2ZSHGo7YgfadBRXuxuc,25257
+mblt_npu/onnx_backend.py,sha256=kVkGGWxA-QobPADHLxN1wM53XKtyBPUSHxuPboDK2AY,2885
+mblt_npu/pytest_plugin.py,sha256=-qHifafGPmhuh1HDUCGU9i4Kdm5R9c1QoascrvwuUlc,6603
+mblt_npu_python-0.0.0.dist-info/licenses/LICENSE,sha256=uoT2s1wxohq-vNpQBIqumGsAky_kRTLY_LNdSrLjXZM,1501
+mblt_npu_python-0.0.0.dist-info/METADATA,sha256=cIdGQ4_WCrtW8jvTw7vkboJPb_B1i_MA49UJ_lvWwCY,4000
+mblt_npu_python-0.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mblt_npu_python-0.0.0.dist-info/top_level.txt,sha256=Bp6_Sz4yMUXGejQXslSAfoDx8RjPw_WPBkOOFQSLaXk,9
+mblt_npu_python-0.0.0.dist-info/RECORD,,

mblt_npu_python-0.0.0.dist-info/WHEEL

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

mblt_npu_python-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Mobilint, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mblt_npu_python-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mblt_npu