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

mblt_vision/__init__.py

@@ -0,0 +1,86 @@
+"""MBLT vision task exports and discovery helpers.
+
+The vision package keeps task subpackages as the preferred import surface while
+also supporting legacy top-level model imports such as
+``from mblt_model_zoo.vision import ResNet50``.
+"""
+
+from __future__ import annotations
+
+from . import depth_estimation as depth_estimation
+from . import face_detection as face_detection
+from . import image_classification as image_classification
+from . import instance_segmentation as instance_segmentation
+from . import obb as obb
+from . import object_detection as object_detection
+from . import pose_estimation as pose_estimation
+from . import semantic_segmentation as semantic_segmentation
+from ._api import list_models as list_models
+from ._api import list_tasks as list_tasks
+from .wrapper import MBLT_Engine as MBLT_Engine
+
+__version__ = "0.0.0"
+
+_TASK_MODULES = (
+    face_detection,
+    depth_estimation,
+    image_classification,
+    instance_segmentation,
+    object_detection,
+    obb,
+    pose_estimation,
+    semantic_segmentation,
+)
+
+_LEGACY_MODEL_EXPORTS: dict[str, object] = {}
+for _task_module in _TASK_MODULES:
+    for _export_name in getattr(_task_module, "__all__", ()):
+        if _export_name in _LEGACY_MODEL_EXPORTS:
+            raise RuntimeError(
+                f"Duplicate vision export detected for '{_export_name}'."
+            )
+        _LEGACY_MODEL_EXPORTS[_export_name] = _task_module
+
+_PUBLIC_EXPORTS = [
+    "MBLT_Engine",
+    "list_models",
+    "list_tasks",
+    "face_detection",
+    "depth_estimation",
+    "image_classification",
+    "instance_segmentation",
+    "object_detection",
+    "obb",
+    "pose_estimation",
+    "semantic_segmentation",
+] + sorted(_LEGACY_MODEL_EXPORTS)
+# Keep legacy compatibility exports synchronized with their task packages.
+__all__: list[str] = _PUBLIC_EXPORTS  # pyright: ignore[reportUnsupportedDunderAll]
+
+
+def __getattr__(name: str) -> object:
+    """Lazily resolve legacy top-level model exports.
+
+    Args:
+        name: Attribute requested from the vision package.
+
+    Returns:
+        The exported model wrapper class for the requested legacy name.
+
+    Raises:
+        AttributeError: If the requested name is not exported by the package.
+    """
+
+    task_module = _LEGACY_MODEL_EXPORTS.get(name)
+    if task_module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    value = getattr(task_module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return package attributes including lazy legacy exports."""
+
+    return sorted(set(globals()) | set(__all__))

mblt_vision/_api.py

@@ -0,0 +1,53 @@
+"""Public helpers for discovering available vision tasks and models."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from typing import Iterable
+
+from ._tasks import VISION_TASKS, normalize_vision_task
+from .wrapper import MBLT_Engine
+
+
+def list_tasks() -> list[str]:
+    """Lists the available vision tasks."""
+
+    return list(VISION_TASKS)
+
+
+def list_models(tasks: str | Iterable[str] | None = None) -> dict[str, list[str]]:
+    """Lists available models for the selected vision tasks.
+
+    Args:
+        tasks: Task name or names to inspect. When omitted, all tasks are used.
+
+    Returns:
+        A mapping of task name to exported model class names.
+
+    Raises:
+        ValueError: If an unknown task name is provided.
+    """
+
+    if tasks is None:
+        task_list = list(VISION_TASKS)
+    elif isinstance(tasks, str):
+        task_list = [tasks]
+    else:
+        task_list = list(tasks)
+
+    available_models: dict[str, list[str]] = {}
+    for task in task_list:
+        module_name = normalize_vision_task(task)
+        module = importlib.import_module(
+            f".{module_name}", package=__name__.replace("._api", "")
+        )
+        available_models[task] = sorted(
+            name
+            for name, obj in inspect.getmembers(module, inspect.isclass)
+            if issubclass(obj, MBLT_Engine)
+            and obj is not MBLT_Engine
+            and not getattr(obj, "_yaml_missing", False)
+        )
+
+    return available_models

mblt_vision/_compat.py

@@ -0,0 +1,227 @@
+"""Compatibility helpers for YAML-backed vision model exports.
+
+This module rebuilds the legacy task package exports that were removed during
+the YAML migration. The generated classes keep the familiar import paths and
+constructor shape while delegating model loading to ``MBLT_Engine``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Iterable, Sequence, TypeAlias, cast
+
+from ._model_paths import uses_shifted_compat_model_path_layout
+from .wrapper import CoreMode, MBLT_Engine
+
+_MODEL_DIR = Path(__file__).parent / "models"
+
+
+class CompatMBLTEngine(MBLT_Engine):
+    """Typed base for dynamically generated legacy compatibility wrappers."""
+
+    def __init__(
+        self,
+        local_path: str | None = None,
+        model_type: str = "DEFAULT",
+        infer_mode: CoreMode = "global8",
+        product: str = "aries",
+        dev_no: int = 0,
+        target_cores: Sequence[str] | None = None,
+        target_clusters: Sequence[int] | None = None,
+        mxq_path: str | None = None,
+        onnx_path: str | None = None,
+        framework: str | None = None,
+        model_path: str | None = None,
+    ) -> None:
+        """Type-only constructor matching the generated legacy wrappers."""
+        del (
+            local_path,
+            model_type,
+            infer_mode,
+            product,
+            dev_no,
+            target_cores,
+            target_clusters,
+            model_path,
+            mxq_path,
+            onnx_path,
+            framework,
+        )
+        raise NotImplementedError
+
+
+CompatMBLTEngineClass: TypeAlias = type[CompatMBLTEngine]
+
+
+def _normalize_name(value: str) -> str:
+    """Returns an alphanumeric-only, case-insensitive identifier."""
+
+    return "".join(char for char in value.lower() if char.isalnum())
+
+
+def _resolve_yaml_name(class_name: str) -> str:
+    """Resolves the YAML config stem associated with a legacy class name.
+
+    Args:
+        class_name: Exported legacy class name.
+
+    Returns:
+        The YAML filename stem without the ``.yaml`` suffix.
+
+    Raises:
+        ValueError: If no unique matching YAML file can be determined.
+    """
+
+    yaml_stems = [path.stem for path in _MODEL_DIR.glob("*.yaml")]
+
+    exact_matches = [stem for stem in yaml_stems if stem.lower() == class_name.lower()]
+    if len(exact_matches) == 1:
+        return exact_matches[0]
+
+    normalized_name = _normalize_name(class_name)
+    normalized_matches = [
+        stem for stem in yaml_stems if _normalize_name(stem) == normalized_name
+    ]
+    if len(normalized_matches) == 1:
+        return normalized_matches[0]
+
+    if not normalized_matches:
+        raise ValueError(
+            f"Could not find a YAML config for legacy class '{class_name}'."
+        )
+
+    raise ValueError(
+        f"Found multiple YAML configs for legacy class '{class_name}': {sorted(normalized_matches)}."
+    )
+
+
+def _build_init(yaml_name: str) -> Callable[..., None]:
+    """Builds a legacy-compatible ``__init__`` implementation."""
+
+    def __init__(
+        self,
+        local_path: str | None = None,
+        model_type: str = "DEFAULT",
+        infer_mode: CoreMode = "global8",
+        product: str = "aries",
+        dev_no: int = 0,
+        target_cores: Sequence[str] | None = None,
+        target_clusters: Sequence[int] | None = None,
+        mxq_path: str | None = None,
+        onnx_path: str | None = None,
+        framework: str | None = None,
+        model_path: str | None = None,
+    ) -> None:
+        """Initializes a YAML-backed compatibility wrapper.
+
+        Args:
+            local_path: Deprecated legacy MXQ path alias. Prefer ``model_path``
+                for generic MXQ or ONNX loading, or ``mxq_path`` for an
+                explicit MXQ-only override.
+            model_type: YAML config variant to load.
+            infer_mode: Execution mode forwarded to ``MBLT_Engine``.
+            product: Legacy product/board value forwarded as ``target_device``.
+            dev_no: Accelerator device number.
+            target_cores: Optional core selection for single-core mode.
+            target_clusters: Optional cluster selection for multi/global modes.
+            mxq_path: Optional explicit MXQ path alias.
+            onnx_path: Optional explicit ONNX path.
+            framework: Execution framework, either ``"mxq"`` or ``"onnx"``. When
+                omitted, ``model_path`` suffix is used first, then MXQ is the fallback.
+            model_path: Optional explicit local model path for MXQ or ONNX.
+        """
+
+        if uses_shifted_compat_model_path_layout(
+            model_path, mxq_path, onnx_path, framework
+        ):
+            model_path, mxq_path, onnx_path, framework = (
+                mxq_path,
+                onnx_path,
+                framework,
+                cast(str | None, model_path),
+            )
+        MBLT_Engine.__init__(
+            self,
+            model_cls=yaml_name,
+            model_type=model_type,
+            model_path=model_path or "",
+            mxq_path=mxq_path or local_path or "",
+            onnx_path=onnx_path or "",
+            dev_no=dev_no,
+            core_mode=infer_mode,
+            target_cores=list(target_cores) if target_cores is not None else None,
+            target_clusters=list(target_clusters)
+            if target_clusters is not None
+            else None,
+            target_device=product,
+            framework=framework,
+        )
+
+    return __init__
+
+
+def _build_missing_init(class_name: str, reason: str) -> Callable[..., None]:
+    """Builds an ``__init__`` that fails with a clear compatibility message."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Raises an informative error for removed YAML-backed models."""
+
+        del args, kwargs
+        raise ValueError(
+            f"Legacy vision model '{class_name}' is not available in the YAML model registry: {reason}"
+        )
+
+    return __init__
+
+
+def create_model_class(class_name: str, module_name: str) -> CompatMBLTEngineClass:
+    """Creates a legacy model class that delegates to ``MBLT_Engine``.
+
+    Args:
+        class_name: Class name to expose from the task module.
+        module_name: Module path that should own the generated class.
+
+    Returns:
+        A dynamically generated ``MBLT_Engine`` subclass.
+    """
+
+    class_doc = f"Compatibility wrapper for the legacy ``{class_name}`` vision model."
+    try:
+        yaml_name = _resolve_yaml_name(class_name)
+    except ValueError as exc:
+        return type(
+            class_name,
+            (CompatMBLTEngine,),
+            {
+                "__doc__": class_doc,
+                "__init__": _build_missing_init(class_name, str(exc)),
+                "__module__": module_name,
+                "_yaml_missing": True,
+            },
+        )
+
+    return type(
+        class_name,
+        (CompatMBLTEngine,),
+        {
+            "__doc__": class_doc,
+            "__init__": _build_init(yaml_name),
+            "__module__": module_name,
+            "_yaml_name": yaml_name,
+        },
+    )
+
+
+def export_model_classes(
+    namespace: dict[str, Any], class_names: Iterable[str], module_name: str
+) -> None:
+    """Populates a module namespace with generated model classes.
+
+    Args:
+        namespace: Target module globals.
+        class_names: Legacy class names to generate.
+        module_name: Import path for generated classes.
+    """
+
+    for class_name in class_names:
+        namespace[class_name] = create_model_class(class_name, module_name)

mblt_vision/_model_paths.py

@@ -0,0 +1,137 @@
+"""Framework and local-artifact path resolution for vision engines."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+SUPPORTED_FRAMEWORKS = {"mxq", "onnx"}
+
+
+def framework_from_model_path(model_path: str) -> str | None:
+    """Infer the runtime framework from a local model path suffix."""
+
+    suffix = Path(model_path).suffix.lower()
+    if suffix == ".mxq":
+        return "mxq"
+    if suffix == ".onnx":
+        return "onnx"
+    return None
+
+
+def uses_shifted_engine_model_path_layout(
+    model_path: object,
+    mxq_path: object,
+    dev_no: object,
+    core_mode: object,
+    target_cores: object,
+    postprocess_kwargs: object,
+    framework: object,
+    onnx_providers: object,
+) -> bool:
+    """Return whether engine arguments use the model-path-first layout.
+
+    Public constructor layouts have used the third positional argument for
+    either ``mxq_path`` or ``model_path``. An ONNX suffix identifies the
+    model-path-first layout because it changes runtime routing. For MXQ,
+    remapping is needed only when later values have the types produced by a
+    one-slot positional shift; a path by itself behaves identically as the
+    ``mxq_path`` alias.
+    """
+
+    if not isinstance(mxq_path, str):
+        return False
+    inferred_framework = framework_from_model_path(mxq_path)
+    if inferred_framework not in SUPPORTED_FRAMEWORKS:
+        return False
+    if (
+        isinstance(model_path, str)
+        and model_path
+        and model_path.lower() not in SUPPORTED_FRAMEWORKS
+    ):
+        return False
+    return (
+        isinstance(dev_no, str)
+        or isinstance(core_mode, int)
+        or isinstance(target_cores, str)
+        or (postprocess_kwargs is not None and not isinstance(postprocess_kwargs, dict))
+        or isinstance(framework, dict)
+        or isinstance(onnx_providers, str)
+        or (model_path is not None and not isinstance(model_path, str))
+        or (isinstance(model_path, str) and model_path.lower() in SUPPORTED_FRAMEWORKS)
+    )
+
+
+def uses_shifted_compat_model_path_layout(
+    model_path: object,
+    mxq_path: object,
+    onnx_path: object,
+    framework: object,
+) -> bool:
+    """Return whether generated-wrapper arguments use a shifted model-path tail."""
+
+    if not isinstance(mxq_path, str):
+        return False
+    inferred_framework = framework_from_model_path(mxq_path)
+    if inferred_framework not in SUPPORTED_FRAMEWORKS:
+        return False
+    if (
+        isinstance(model_path, str)
+        and model_path
+        and model_path.lower() not in SUPPORTED_FRAMEWORKS
+    ):
+        return False
+    if inferred_framework == "onnx":
+        return True
+    return (
+        (isinstance(model_path, str) and model_path.lower() in SUPPORTED_FRAMEWORKS)
+        or (
+            isinstance(onnx_path, str) and framework_from_model_path(onnx_path) == "mxq"
+        )
+        or (
+            isinstance(framework, str)
+            and framework_from_model_path(framework) is not None
+        )
+    )
+
+
+def resolve_framework(framework: str | None, model_path: str = "") -> str:
+    """Resolve the execution framework from explicit input and model path."""
+
+    normalized_framework = framework.lower() if framework is not None else None
+    if (
+        normalized_framework is not None
+        and normalized_framework not in SUPPORTED_FRAMEWORKS
+    ):
+        raise ValueError(
+            f"Unsupported framework: {framework}. Must be one of {sorted(SUPPORTED_FRAMEWORKS)}."
+        )
+    inferred_framework = framework_from_model_path(model_path) if model_path else None
+    if (
+        normalized_framework
+        and inferred_framework
+        and normalized_framework != inferred_framework
+    ):
+        raise ValueError(
+            f"Framework `{normalized_framework}` conflicts with model path `{model_path}`. "
+            f"Use framework `{inferred_framework}` or remove the explicit framework."
+        )
+    return inferred_framework or normalized_framework or "mxq"
+
+
+def split_model_paths(
+    *, framework: str, model_path: str = "", mxq_path: str = "", onnx_path: str = ""
+) -> tuple[str, str]:
+    """Resolve generic and framework-specific local model path arguments."""
+
+    resolved_mxq_path = mxq_path
+    resolved_onnx_path = onnx_path
+    if not model_path:
+        return resolved_mxq_path, resolved_onnx_path
+    inferred_framework = framework_from_model_path(model_path)
+    if inferred_framework == "mxq":
+        resolved_mxq_path = resolved_mxq_path or model_path
+    elif inferred_framework == "onnx" or framework == "onnx":
+        resolved_onnx_path = resolved_onnx_path or model_path
+    else:
+        resolved_mxq_path = resolved_mxq_path or model_path
+    return resolved_mxq_path, resolved_onnx_path

mblt_vision/_tasks.py

@@ -0,0 +1,30 @@
+"""Canonical task names used by the standalone Vision processing API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+VISION_TASKS: tuple[str, ...] = (
+    "image_classification",
+    "depth_estimation",
+    "object_detection",
+    "instance_segmentation",
+    "semantic_segmentation",
+    "obb",
+    "pose_estimation",
+    "face_detection",
+)
+
+
+def normalize_vision_task(task: str, *, supported: Iterable[str] | None = None) -> str:
+    """Normalize a Vision task name and validate it against supported tasks."""
+
+    if not isinstance(task, str):
+        raise TypeError(f"Vision task must be a string, got {type(task).__name__}.")
+    normalized = task.lower()
+    supported_tasks = tuple(VISION_TASKS if supported is None else supported)
+    if normalized not in supported_tasks:
+        raise ValueError(
+            f"Unsupported Vision task {task!r}; expected one of {sorted(supported_tasks)}."
+        )
+    return normalized

mblt_vision/benchmark/__init__.py

@@ -0,0 +1 @@
+"""Reusable benchmark reporting and command support for Mobilint Vision."""

mblt_vision/benchmark/argparse_utils.py

@@ -0,0 +1,106 @@
+"""Shared argparse validators for benchmark scripts."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def parse_positive_int(raw: str) -> int:
+    """Parses a positive integer for argparse.
+
+    Args:
+        raw: Raw command-line value.
+
+    Returns:
+        Parsed positive integer.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a positive integer.
+    """
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as e:
+        raise argparse.ArgumentTypeError("expected a positive integer") from e
+    if value <= 0:
+        raise argparse.ArgumentTypeError("expected a positive integer")
+    return value
+
+
+def parse_positive_int_optional(raw: str | None) -> int | None:
+    """Parses an optional positive integer for argparse.
+
+    Args:
+        raw: Raw command-line value or ``None``.
+
+    Returns:
+        Parsed positive integer, or ``None`` for empty input.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not empty and not a positive integer.
+    """
+    if raw is None or raw == "":
+        return None
+    return parse_positive_int(raw)
+
+
+def parse_range_arg(raw: str) -> tuple[int, int, int]:
+    """Parses ``start:end:step`` or ``start,end,step`` positive integer ranges.
+
+    Args:
+        raw: Raw command-line value.
+
+    Returns:
+        Parsed ``(start, end, step)`` tuple.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is malformed.
+    """
+    sep = ":" if ":" in raw else ("," if "," in raw else None)
+    if sep is None:
+        raise argparse.ArgumentTypeError(
+            "expected format 'start:end:step' or 'start,end,step'"
+        )
+    parts = [part.strip() for part in raw.split(sep)]
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError(
+            "expected exactly 3 integers: 'start:end:step' or 'start,end,step'"
+        )
+    try:
+        start, end, step = (int(part) for part in parts)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError("range values must be integers") from e
+    if start <= 0 or end <= 0 or step <= 0:
+        raise argparse.ArgumentTypeError("range values must be positive integers")
+    if start > end:
+        raise argparse.ArgumentTypeError("range start must be <= end")
+    return start, end, step
+
+
+def parse_int_csv(
+    raw: str, *, unique_sorted: bool = True, allow_empty: bool = False
+) -> list[int]:
+    """Parses comma-separated positive integers.
+
+    Args:
+        raw: Raw command-line value.
+        unique_sorted: Whether to sort and de-duplicate parsed values.
+        allow_empty: Whether an empty input should return an empty list.
+
+    Returns:
+        Parsed positive integers.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is malformed.
+    """
+    parts = [item.strip() for item in str(raw).split(",") if item.strip()]
+    if not parts:
+        if allow_empty:
+            return []
+        raise argparse.ArgumentTypeError("expected at least one integer")
+    try:
+        values = [int(item) for item in parts]
+    except ValueError as e:
+        raise argparse.ArgumentTypeError("all values must be integers") from e
+    if any(value <= 0 for value in values):
+        raise argparse.ArgumentTypeError("all values must be positive integers")
+    return sorted(set(values)) if unique_sorted else values