mblt-npu-python 0.0.0__tar.gz → 0.0.2__tar.gz

{mblt_npu_python-0.0.0/mblt_npu_python.egg-info → mblt_npu_python-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mblt-npu-python
-Version: 0.0.0
+Version: 0.0.2
 Summary: Shared NPU access for the Mobilint Python packages
 Author: Mobilint
 License: BSD-3-Clause
@@ -28,6 +28,16 @@ Dynamic: license-file
 
 # Mobilint NPU Python
 
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+<p>
+<a href="https://www.mobilint.com/" target="_blank">
+<img src="https://raw.githubusercontent.com/mobilint/.github/main/assets/Mobilint_Logo_Primary.png" alt="Mobilint Logo" width="60%">
+</a>
+</p>
+</div>
+<!-- markdownlint-enable MD033 -->
+
 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
@@ -41,6 +51,10 @@ a `MobilintNPUBackend`'s fields.
 
 ## Installation
 
+[![PyPI - Version](https://img.shields.io/pypi/v/mblt-npu-python?logo=pypi&logoColor=white)](https://pypi.org/project/mblt-npu-python/)
+[![PyPI Downloads](https://static.pepy.tech/badge/mblt-npu-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://clickpy.clickhouse.com/dashboard/mblt-npu-python)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mblt-npu-python?logo=python&logoColor=gold)](https://pypi.org/project/mblt-npu-python/)
+
 ```bash
 pip install mblt-npu-python
 ```
@@ -76,6 +90,20 @@ remain accepted when loading older configurations.
 `backend_class_for()` and `BACKEND_CLASSES` are available for integrations that
 need to inspect the supported targets.
 
+### Multi-slot MXQ execution
+
+`max_batch_size` is aggregate capacity. At `create()`, the backend probes the
+compiled per-model capacity `K` and loads `ceil(max_batch_size / K)` model slots.
+Slots are distributed round-robin over the devices named by canonical target
+strings and reuse one accelerator per device. `mxq_model` and `acc` continue to
+refer to slot zero for compatibility; concurrent callers can use
+`infer_slot(slot_index, inputs)`. Allocation failures dispose all created slots
+and raise `MobilintBackendAllocError` with the failed slot and device.
+
+Hub-backed configurations retain `name_or_path`, `revision`, and `commit_hash`
+through `to_dict()` / `from_dict()`. Artifact lookup never substitutes an
+unpinned revision or an unrelated cached MXQ.
+
 For ONNX inference, install the optional runtime extra and use `ONNXBackend`:
 
 ```bash

{mblt_npu_python-0.0.0 → mblt_npu_python-0.0.2}/README.md

@@ -1,5 +1,15 @@
 # Mobilint NPU Python
 
+<!-- markdownlint-disable MD033 -->
+<div align="center">
+<p>
+<a href="https://www.mobilint.com/" target="_blank">
+<img src="https://raw.githubusercontent.com/mobilint/.github/main/assets/Mobilint_Logo_Primary.png" alt="Mobilint Logo" width="60%">
+</a>
+</p>
+</div>
+<!-- markdownlint-enable MD033 -->
+
 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
@@ -13,6 +23,10 @@ a `MobilintNPUBackend`'s fields.
 
 ## Installation
 
+[![PyPI - Version](https://img.shields.io/pypi/v/mblt-npu-python?logo=pypi&logoColor=white)](https://pypi.org/project/mblt-npu-python/)
+[![PyPI Downloads](https://static.pepy.tech/badge/mblt-npu-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://clickpy.clickhouse.com/dashboard/mblt-npu-python)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mblt-npu-python?logo=python&logoColor=gold)](https://pypi.org/project/mblt-npu-python/)
+
 ```bash
 pip install mblt-npu-python
 ```
@@ -48,6 +62,20 @@ remain accepted when loading older configurations.
 `backend_class_for()` and `BACKEND_CLASSES` are available for integrations that
 need to inspect the supported targets.
 
+### Multi-slot MXQ execution
+
+`max_batch_size` is aggregate capacity. At `create()`, the backend probes the
+compiled per-model capacity `K` and loads `ceil(max_batch_size / K)` model slots.
+Slots are distributed round-robin over the devices named by canonical target
+strings and reuse one accelerator per device. `mxq_model` and `acc` continue to
+refer to slot zero for compatibility; concurrent callers can use
+`infer_slot(slot_index, inputs)`. Allocation failures dispose all created slots
+and raise `MobilintBackendAllocError` with the failed slot and device.
+
+Hub-backed configurations retain `name_or_path`, `revision`, and `commit_hash`
+through `to_dict()` / `from_dict()`. Artifact lookup never substitutes an
+unpinned revision or an unrelated cached MXQ.
+
 For ONNX inference, install the optional runtime extra and use `ONNXBackend`:
 
 ```bash

{mblt_npu_python-0.0.0 → mblt_npu_python-0.0.2}/mblt_npu/__init__.py

@@ -12,6 +12,7 @@ log_model_details reads a MobilintNPUBackend's fields.
 from .npu_backend import (
     BACKEND_CLASSES,
     DEFAULT_TARGET_DEVICE,
+    MobilintBackendAllocError,
     MobilintAriesBackend,
     MobilintNPUBackend,
     MobilintRegulusBackend,
@@ -21,11 +22,12 @@ from .npu_backend import (
 from .logging import log_model_details
 from .onnx_backend import ONNXBackend
 
-__version__ = "0.0.0"
+__version__ = "0.0.2"
 
 __all__ = [
     "BACKEND_CLASSES",
     "DEFAULT_TARGET_DEVICE",
+    "MobilintBackendAllocError",
     "MobilintAriesBackend",
     "MobilintNPUBackend",
     "MobilintRegulusBackend",

mblt_npu_python-0.0.2/mblt_npu/core_mode.py

@@ -0,0 +1,27 @@
+"""Shared core-mode typing and validation helpers."""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+
+CoreMode = Literal["auto", "single", "multi", "global4", "global8"]
+
+
+def normalize_core_mode(core_mode: str) -> CoreMode:
+    """Narrow a validated core mode string to the supported literal type.
+
+    Args:
+        core_mode: Core mode string from user input or configuration.
+
+    Returns:
+        The same value narrowed to ``CoreMode``.
+
+    Raises:
+        ValueError: If ``core_mode`` is not one of the supported values.
+    """
+    valid_modes = {"auto", "single", "multi", "global4", "global8"}
+    if core_mode not in valid_modes:
+        raise ValueError(
+            f"Invalid core mode '{core_mode}'. Expected one of {sorted(valid_modes)}."
+        )
+    return cast(CoreMode, core_mode)

mblt_npu_python-0.0.2/mblt_npu/logging.py

@@ -0,0 +1,77 @@
+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.
+
+    When the backend hosts multiple slots (``n_models > 1``), an aggregate
+    summary is printed once (slot count, device distribution, compiled batch
+    axis ``K``, total capacity ``N * K``). Per-variant input/output shapes
+    are read from slot 0 because every slot loads the same MXQ artifact.
+    """
+    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}")
+            by_device = npu_backend.target_cores_by_device
+            if len(by_device) > 1:
+                for dev in sorted(by_device):
+                    print(f"\tDevice {dev} Cores: {by_device[dev]}")
+        else:
+            print(f"Target Clusters: {npu_backend.target_clusters}")
+            by_device = npu_backend.target_clusters_by_device
+            if len(by_device) > 1:
+                for dev in sorted(by_device):
+                    print(f"\tDevice {dev} Clusters: {by_device[dev]}")
+        n_models = getattr(npu_backend, "n_models", 0) or 0
+        if n_models > 0:
+            k_per_model = getattr(npu_backend, "k_per_model", 1) or 1
+            model_dev_no = getattr(npu_backend, "model_dev_no", [])
+            print(f"Backend Slots: {n_models}")
+            print(f"Slot Device Assignment: {list(model_dev_no)}")
+            print(f"K per Slot: {k_per_model}")
+            print(f"Total Capacity (N*K): {n_models * k_per_model}")
+        mxq_model = npu_backend.mxq_model
+        if mxq_model is None:
+            return
+        if mxq_model.get_num_model_variants() == 1:
+            print(f"Model Input Shape: {mxq_model.get_model_input_shape()}")
+            print(f"Model Output Shape: {mxq_model.get_model_output_shape()}")
+        else:
+            for i in range(mxq_model.get_num_model_variants()):
+                print(f"Model Variant {i}")
+                print(
+                    f"\tInput Shape: {mxq_model.get_model_variant_handle(i).get_model_input_shape()}"
+                )
+                print(
+                    f"\tOutput Shape: {mxq_model.get_model_variant_handle(i).get_model_output_shape()}"
+                )