ort-vision-sdk 0.2.0__tar.gz

ort_vision_sdk-0.2.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Models and assets (keep repo lean)
+*.onnx
+*.pt
+*.pth
+*.h5
+*.pb
+models/
+assets/
+data/
+
+# Local env
+.env
+.env.local

ort_vision_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to `ort-vision-sdk` (Python) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-02
+
+This release brings the public API in line with the Ultralytics / PyTorch
+idiom, so code ported from those ecosystems works with minimal changes.
+
+### Added
+
+- **Per-image `Results` envelopes** (`DetectionResults`, `ClassificationResults`,
+  `SegmentationResults`) returned by every `predict()` call as a 1-element
+  list, mirroring `YOLO("img.jpg")`. Each envelope holds:
+  - `boxes` / `probs` / `masks` — bulk numpy views with Ultralytics-style
+    accessors (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`, `data`,
+    `top1`, `top1conf`, `top5`, `top5conf`).
+  - `detections` — tuple of per-instance dataclasses (the previous return
+    type).
+  - `names` — `dict[int, str]` matching `model.names`.
+  - `orig_img`, `orig_shape`, `path`, `speed`.
+- **Ultralytics-style aliases** on `BoundingBox`, `ClassProbability`,
+  `ClassificationResult`, `DetectionResult`, `SegmentationResult`:
+  `cls`, `conf`, `name`, `box`, `xyxy`, `xywh` (center coords),
+  plus `xyxyn(orig_shape)` / `xywhn(orig_shape)` methods on `BoundingBox`.
+- **`__call__` on every task class** — `Detector(model)(image)` now works
+  like `torch.nn.Module.__call__`, delegating to `predict()`.
+- **`names: dict[int, str]` property** on every task class alongside
+  `labels: tuple[str, ...]`.
+- **Short device aliases** in `providers=` — `"cpu"`, `"cuda"`, `"gpu"`,
+  `"tensorrt"` / `"trt"`, `"coreml"` / `"mps"`, `"dml"` / `"directml"`,
+  `"openvino"` are expanded to the canonical `*ExecutionProvider` names.
+  New helper `normalize_provider(name)`.
+- **Explicit `head=` parameter** on `Detector` and `Segmenter` constructors —
+  caller declares which decoder family the model uses (`"yolo"` for
+  detect heads of v8/v9/v10/v11/v12/v26; `"yolo-seg"` for the matching
+  seg heads). The SDK does **not** auto-detect — wrong head raises
+  `ValueError`. New types `DetectorHead`, `SegmenterHead`.
+- **`classes` filter** on `Detector.predict()` / `Detector.__call__()` and
+  `Segmenter.predict()` / `Segmenter.__call__()` — keeps only results whose
+  `class_id` is in the supplied list, matching Ultralytics'
+  `model.predict(img, classes=[0, 16])`.
+- **`postprocess.batched_nms(boxes, scores, idxs, iou_threshold)`** matching
+  `torchvision.ops.batched_nms`.
+- **Generic YOLO decoder names**: `decode_yolo`, `decode_yolo_anchors`,
+  `decode_yolo_seg` — same code, accurate name (covers v8/v9/v10/v11/v12).
+- **Preprocess helpers** mirroring torchvision/OpenCV:
+  - `to_tensor(image)` → CHW `float32 / 255` (ToTensor parity).
+  - `from_cv2(bgr)` / `to_cv2(rgb)` — channel-order bridges.
+
+### Changed
+
+- `Detector.predict(img)` now returns `list[DetectionResults]` (1 element)
+  instead of `list[DetectionResult]`. Iterate the envelope to recover the
+  old shape: `for d in detector.predict(img)[0]: ...`.
+- `Classifier.predict(img)` now returns `list[ClassificationResults]`.
+- `Segmenter.predict(img)` now returns `list[SegmentationResults]`.
+- `nms(boxes, scores, iou_threshold)` — first parameter renamed from
+  `boxes_xyxy` to `boxes` for `torchvision.ops.nms` parity.
+- The detection decoder no longer applies the per-class loop inline — it
+  delegates to `batched_nms`.
+
+### Deprecated
+
+- `decode_yolov8`, `decode_yolov8_anchors`, `decode_yolov8_seg` — emit
+  `DeprecationWarning`; will be removed in 0.3.0. Use `decode_yolo`,
+  `decode_yolo_anchors`, `decode_yolo_seg` instead.
+
+### Migration
+
+```python
+# Before (0.1.0)
+detections = detector.predict("street.jpg")
+for d in detections:
+    print(d.class_id, d.class_name, d.confidence, d.bbox.as_xyxy())
+
+# After (0.2.0)
+results = detector.predict("street.jpg")  # list[DetectionResults], len 1
+r = results[0]
+
+# Per-instance dataclasses (legacy fields still work):
+for d in r:
+    print(d.class_id, d.class_name, d.confidence, d.bbox.as_xyxy())
+# or with the new short aliases:
+for d in r:
+    print(d.cls, d.name, d.conf, d.box.xyxy)
+
+# Bulk numpy access (matches Ultralytics):
+print(r.boxes.xyxy.shape, r.boxes.cls, r.boxes.conf, r.names)
+```
+
+## [0.1.0] - 2026-05-02
+
+### Added
+
+- Initial alpha release.
+- `Classifier` and `Detector` task classes wrapping `onnxruntime.InferenceSession`.
+- Image I/O helpers (`load_image`, `ImageInput`).
+- Default label maps (`COCO_CLASSES`, ImageNet via `resolve_labels`).
+- Public types: `BoundingBox`, `ClassProbability`, `ClassificationResult`, `DetectionResult`, `ImageArray`.
+- Optional extras: `gpu` (onnxruntime-gpu), `opencv` (opencv-python), `dev` (test/lint tooling).
+
+[Unreleased]: https://github.com/mauriciobenjamin700/ort-vision-sdk/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mauriciobenjamin700/ort-vision-sdk/releases/tag/v0.2.0
+[0.1.0]: https://github.com/mauriciobenjamin700/ort-vision-sdk/releases/tag/v0.1.0

ort_vision_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Benjamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ort_vision_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: ort-vision-sdk
+Version: 0.2.0
+Summary: High-level Python SDK for computer vision inference with ONNX Runtime.
+Project-URL: Homepage, https://github.com/mauriciobenjamin700/ort-vision-sdk
+Project-URL: Repository, https://github.com/mauriciobenjamin700/ort-vision-sdk
+Project-URL: Issues, https://github.com/mauriciobenjamin700/ort-vision-sdk/issues
+Project-URL: Changelog, https://github.com/mauriciobenjamin700/ort-vision-sdk/blob/main/CHANGELOG.md
+Author-email: Mauricio Benjamin <mauriciobenjamin700@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: computer-vision,inference,onnx,onnxruntime,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: onnxruntime>=1.17.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu>=1.17.0; extra == 'gpu'
+Provides-Extra: opencv
+Requires-Dist: opencv-python>=4.8.0; extra == 'opencv'
+Description-Content-Type: text/markdown
+
+# ort-vision-sdk
+
+High-level Python SDK for computer vision inference on top of [ONNX Runtime](https://onnxruntime.ai/).
+
+Wraps the low-level `InferenceSession` API with task-oriented classes (`Classifier`, `Detector`, ...) that handle preprocessing, execution provider selection, and postprocessing — so you go from an image to a typed result in one call.
+
+## Installation
+
+```bash
+pip install ort-vision-sdk          # CPU only
+pip install ort-vision-sdk[gpu]     # CUDA
+pip install ort-vision-sdk[opencv]  # adds cv2 image backend
+```
+
+## Quick start
+
+```python
+from ort_vision_sdk import Classifier
+
+clf = Classifier("resnet50.onnx", labels="imagenet")
+result = clf.predict("dog.jpg")
+
+print(result.class_name, result.confidence)
+print(result.probabilities[:5])  # top-5 ClassProbability tuples
+```
+
+```python
+from ort_vision_sdk import Detector
+
+det = Detector("yolov8n.onnx", labels="coco")
+detections = det.predict("street.jpg")
+
+for d in detections:
+    print(d.class_name, d.confidence, d.bbox.as_xyxy())
+    # d.cropped_image is a np.ndarray (HWC, RGB, uint8)
+```
+
+## Status
+
+Alpha — API may change. See [`pyproject.toml`](pyproject.toml) for supported Python and dependency versions.

ort_vision_sdk-0.2.0/README.md

@@ -0,0 +1,40 @@
+# ort-vision-sdk
+
+High-level Python SDK for computer vision inference on top of [ONNX Runtime](https://onnxruntime.ai/).
+
+Wraps the low-level `InferenceSession` API with task-oriented classes (`Classifier`, `Detector`, ...) that handle preprocessing, execution provider selection, and postprocessing — so you go from an image to a typed result in one call.
+
+## Installation
+
+```bash
+pip install ort-vision-sdk          # CPU only
+pip install ort-vision-sdk[gpu]     # CUDA
+pip install ort-vision-sdk[opencv]  # adds cv2 image backend
+```
+
+## Quick start
+
+```python
+from ort_vision_sdk import Classifier
+
+clf = Classifier("resnet50.onnx", labels="imagenet")
+result = clf.predict("dog.jpg")
+
+print(result.class_name, result.confidence)
+print(result.probabilities[:5])  # top-5 ClassProbability tuples
+```
+
+```python
+from ort_vision_sdk import Detector
+
+det = Detector("yolov8n.onnx", labels="coco")
+detections = det.predict("street.jpg")
+
+for d in detections:
+    print(d.class_name, d.confidence, d.bbox.as_xyxy())
+    # d.cropped_image is a np.ndarray (HWC, RGB, uint8)
+```
+
+## Status
+
+Alpha — API may change. See [`pyproject.toml`](pyproject.toml) for supported Python and dependency versions.

ort_vision_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,123 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ort-vision-sdk"
+version = "0.2.0"
+description = "High-level Python SDK for computer vision inference with ONNX Runtime."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Mauricio Benjamin", email = "mauriciobenjamin700@gmail.com" },
+]
+keywords = ["onnx", "onnxruntime", "computer-vision", "inference", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "onnxruntime>=1.17.0",
+    "numpy>=1.24.0",
+    "pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+gpu = ["onnxruntime-gpu>=1.17.0"]
+opencv = ["opencv-python>=4.8.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/mauriciobenjamin700/ort-vision-sdk"
+Repository = "https://github.com/mauriciobenjamin700/ort-vision-sdk"
+Issues = "https://github.com/mauriciobenjamin700/ort-vision-sdk/issues"
+Changelog = "https://github.com/mauriciobenjamin700/ort-vision-sdk/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ort_vision_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/ort_vision_sdk",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/CHANGELOG.md",
+    "/pyproject.toml",
+]
+exclude = [
+    "/dist",
+    "**/__pycache__",
+    "**/*.py[cod]",
+    "**/.mypy_cache",
+    "**/.pytest_cache",
+    "**/.ruff_cache",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "N",   # pep8-naming
+    "D",   # pydocstyle
+    "ANN", # flake8-annotations
+    "RUF",
+]
+ignore = [
+    "D203",  # one-blank-line-before-class (conflicts with D211)
+    "D213",  # multi-line-summary-second-line (conflicts with D212)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = ["onnxruntime.*", "cv2.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+pythonpath = ["src"]
+addopts = "-ra --strict-markers"
+filterwarnings = [
+    "default::DeprecationWarning:ort_vision_sdk.*",
+]

ort_vision_sdk-0.2.0/src/ort_vision_sdk/__init__.py

@@ -0,0 +1,57 @@
+"""ort-vision-sdk: high-level Python SDK for computer vision inference with ONNX Runtime."""
+
+from ort_vision_sdk.io import ImageInput, load_image
+from ort_vision_sdk.labels import COCO_CLASSES, LabelSpec, resolve_labels
+from ort_vision_sdk.results import (
+    Boxes,
+    ClassificationResults,
+    DetectionResults,
+    Masks,
+    Probs,
+    SegmentationResults,
+)
+from ort_vision_sdk.tasks import (
+    Classifier,
+    Detector,
+    DetectorHead,
+    Segmenter,
+    SegmenterHead,
+    VisionTask,
+)
+from ort_vision_sdk.types import (
+    BoundingBox,
+    ClassificationResult,
+    ClassProbability,
+    DetectionResult,
+    ImageArray,
+    SegmentationResult,
+)
+
+__version__: str = "0.2.0"
+
+__all__: list[str] = [
+    "COCO_CLASSES",
+    "BoundingBox",
+    "Boxes",
+    "ClassProbability",
+    "ClassificationResult",
+    "ClassificationResults",
+    "Classifier",
+    "DetectionResult",
+    "DetectionResults",
+    "Detector",
+    "DetectorHead",
+    "ImageArray",
+    "ImageInput",
+    "LabelSpec",
+    "Masks",
+    "Probs",
+    "SegmentationResult",
+    "SegmentationResults",
+    "Segmenter",
+    "SegmenterHead",
+    "VisionTask",
+    "__version__",
+    "load_image",
+    "resolve_labels",
+]

ort_vision_sdk-0.2.0/src/ort_vision_sdk/core/__init__.py

@@ -0,0 +1,24 @@
+"""Core building blocks: ORT session wrapper, provider resolution, and exceptions."""
+
+from ort_vision_sdk.core.exceptions import (
+    ImageLoadError,
+    InferenceError,
+    LabelMapError,
+    ModelLoadError,
+    OrtVisionError,
+    ProviderNotAvailableError,
+)
+from ort_vision_sdk.core.providers import available_providers, resolve_providers
+from ort_vision_sdk.core.session import OrtSession
+
+__all__: list[str] = [
+    "ImageLoadError",
+    "InferenceError",
+    "LabelMapError",
+    "ModelLoadError",
+    "OrtSession",
+    "OrtVisionError",
+    "ProviderNotAvailableError",
+    "available_providers",
+    "resolve_providers",
+]

ort_vision_sdk-0.2.0/src/ort_vision_sdk/core/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions raised by the SDK.
+
+All exceptions inherit from :class:`OrtVisionError`, so callers can catch the
+base class to handle any SDK-originated failure uniformly.
+"""
+
+from __future__ import annotations
+
+
+class OrtVisionError(Exception):
+    """Base class for all ort-vision-sdk errors."""
+
+
+class ModelLoadError(OrtVisionError):
+    """Raised when an ONNX model cannot be loaded into an inference session."""
+
+
+class InferenceError(OrtVisionError):
+    """Raised when ONNX Runtime fails while executing a model."""
+
+
+class ProviderNotAvailableError(OrtVisionError):
+    """Raised when a requested execution provider is not available in this ORT build."""
+
+
+class ImageLoadError(OrtVisionError):
+    """Raised when an input image cannot be decoded into the canonical array format."""
+
+
+class LabelMapError(OrtVisionError):
+    """Raised when class labels cannot be resolved from the supplied spec."""

ort_vision_sdk-0.2.0/src/ort_vision_sdk/core/providers.py

@@ -0,0 +1,104 @@
+"""Execution-provider resolution for ONNX Runtime sessions.
+
+Encapsulates the logic of picking the best available accelerator (CUDA,
+TensorRT, CoreML, DirectML, OpenVINO) and falling back to CPU. Callers can
+pass an explicit list of providers when they need full control.
+
+Short Ultralytics-style aliases (``"cpu"``, ``"cuda"``, ``"tensorrt"``,
+``"coreml"``, ``"dml"`` / ``"directml"``, ``"openvino"``) are accepted in
+addition to the canonical ORT names (``"CPUExecutionProvider"``,
+``"CUDAExecutionProvider"``, ...).
+"""
+
+from __future__ import annotations
+
+import onnxruntime as ort
+
+from ort_vision_sdk.core.exceptions import ProviderNotAvailableError
+
+_PRIORITY: tuple[str, ...] = (
+    "TensorrtExecutionProvider",
+    "CUDAExecutionProvider",
+    "CoreMLExecutionProvider",
+    "DmlExecutionProvider",
+    "OpenVINOExecutionProvider",
+    "CPUExecutionProvider",
+)
+"""Default preference order, from most to least accelerated."""
+
+_ALIASES: dict[str, str] = {
+    "cpu": "CPUExecutionProvider",
+    "cuda": "CUDAExecutionProvider",
+    "gpu": "CUDAExecutionProvider",
+    "tensorrt": "TensorrtExecutionProvider",
+    "trt": "TensorrtExecutionProvider",
+    "coreml": "CoreMLExecutionProvider",
+    "mps": "CoreMLExecutionProvider",
+    "dml": "DmlExecutionProvider",
+    "directml": "DmlExecutionProvider",
+    "openvino": "OpenVINOExecutionProvider",
+}
+"""Short device aliases → canonical ORT provider names. Lookup is case-insensitive."""
+
+
+def available_providers() -> list[str]:
+    """Return the execution providers available in this ORT build.
+
+    Returns:
+        List of provider names exactly as ONNX Runtime reports them.
+    """
+    return list(ort.get_available_providers())
+
+
+def normalize_provider(name: str) -> str:
+    """Expand a short device alias to its canonical ORT provider name.
+
+    Names that already end in ``ExecutionProvider`` are returned unchanged
+    (case-preserving). Short aliases are looked up case-insensitively.
+
+    Args:
+        name: Either a short alias (``"cpu"``, ``"cuda"``, ``"tensorrt"``,
+            ``"coreml"``, ``"dml"``, ``"openvino"``, ...) or a canonical ORT
+            provider name (``"CPUExecutionProvider"`` etc.).
+
+    Returns:
+        The canonical ORT provider name. If ``name`` is already canonical,
+        it is returned as-is.
+    """
+    if name.endswith("ExecutionProvider"):
+        return name
+    return _ALIASES.get(name.lower(), name)
+
+
+def resolve_providers(requested: list[str] | None = None) -> list[str]:
+    """Resolve the execution providers to use for an inference session.
+
+    Args:
+        requested: Explicit list of providers in preference order. Each entry
+            may be a canonical ORT name (``"CUDAExecutionProvider"``) or a
+            short alias (``"cuda"``, ``"cpu"``, ``"tensorrt"``, ...). ``None``
+            (default) auto-selects the best available accelerator with CPU
+            as the final fallback.
+
+    Returns:
+        Ordered list of canonical providers to pass to
+        ``onnxruntime.InferenceSession``. Always non-empty (CPU is always
+        available).
+
+    Raises:
+        ProviderNotAvailableError: If any explicitly requested provider is
+            not available in this ORT build.
+    """
+    available = set(available_providers())
+    if requested is None:
+        ordered = [p for p in _PRIORITY if p in available]
+        return ordered or ["CPUExecutionProvider"]
+
+    canonical = [normalize_provider(p) for p in requested]
+    missing = [p for p in canonical if p not in available]
+    if missing:
+        raise ProviderNotAvailableError(
+            f"Requested execution provider(s) not available: {missing}. "
+            f"Available providers: {sorted(available)}."
+        )
+    return canonical