windowsml 1.8.2192__py3-none-win_arm64.whl

windowsml-1.8.2192.data/purelib/windowsml/__init__.py

@@ -0,0 +1,973 @@
+# Copyright (C) Microsoft Corporation. All rights reserved.
+"""Python bindings for the Windows AI Machine Learning API."""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Callable, Optional
+
+from windowsml._bindings import (
+    AsyncBlock,
+    AsyncCompletionCallback,
+    AsyncProgressCallback,
+    CatalogModelInfoEnumCallback,
+    CatalogModelInfoHandle,
+    CatalogModelInstanceHandle,
+    CatalogModelInstanceResult,
+    CatalogModelInstanceStatus,
+    CatalogModelStatus,
+    EpCatalogHandle,
+    EpCertification,
+    EpEnumCallback,
+    EpReadyState,
+    ModelCatalogHandle,
+    ModelCatalogSourceHandle,
+    StringEnumCallback,
+    WinMLAsyncCancel,
+    WinMLAsyncClose,
+    WinMLAsyncGetStatus,
+    WinMLCatalogModelInfoEnumExecutionProviders,
+    WinMLCatalogModelInfoGetId,
+    WinMLCatalogModelInfoGetIdSize,
+    WinMLCatalogModelInfoGetInstanceAsync,
+    WinMLCatalogModelInfoGetInstanceResult,
+    WinMLCatalogModelInfoGetInstanceWithHeadersAsync,
+    WinMLCatalogModelInfoGetLicense,
+    WinMLCatalogModelInfoGetLicenseSize,
+    WinMLCatalogModelInfoGetLicenseText,
+    WinMLCatalogModelInfoGetLicenseTextSize,
+    WinMLCatalogModelInfoGetLicenseUri,
+    WinMLCatalogModelInfoGetLicenseUriSize,
+    WinMLCatalogModelInfoGetModelSizeInBytes,
+    WinMLCatalogModelInfoGetName,
+    WinMLCatalogModelInfoGetNameSize,
+    WinMLCatalogModelInfoGetPublisher,
+    WinMLCatalogModelInfoGetPublisherSize,
+    WinMLCatalogModelInfoGetSourceId,
+    WinMLCatalogModelInfoGetSourceIdSize,
+    WinMLCatalogModelInfoGetStatus,
+    WinMLCatalogModelInfoGetUri,
+    WinMLCatalogModelInfoGetUriSize,
+    WinMLCatalogModelInfoGetVersion,
+    WinMLCatalogModelInfoGetVersionSize,
+    WinMLCatalogModelInfoRelease,
+    WinMLCatalogModelInstanceClose,
+    WinMLCatalogModelInstanceEnumModelPaths,
+    WinMLCatalogModelInstanceGetModelInfo,
+    WinMLCatalogModelInstanceRelease,
+    WinMLEpCatalogCreate,
+    WinMLEpCatalogEnumProviders,
+    WinMLEpCatalogRelease,
+    WinMLEpEnsureReady,
+    WinMLEpEnsureReadyAsync,
+    WinMLEpGetCertification,
+    WinMLEpGetLibraryPath,
+    WinMLEpGetLibraryPathSize,
+    WinMLEpGetName,
+    WinMLEpGetNameSize,
+    WinMLEpGetPackageFamilyName,
+    WinMLEpGetPackageFamilyNameSize,
+    WinMLEpGetPackageRootPath,
+    WinMLEpGetPackageRootPathSize,
+    WinMLEpGetReadyState,
+    WinMLEpGetVersion,
+    WinMLEpGetVersionSize,
+    WinMLModelCatalogCreate,
+    WinMLModelCatalogEnumExecutionProviders,
+    WinMLModelCatalogFindAllModels,
+    WinMLModelCatalogFindAllModelsAsync,
+    WinMLModelCatalogFindAllModelsGetResult,
+    WinMLModelCatalogFindModel,
+    WinMLModelCatalogFindModelAsync,
+    WinMLModelCatalogFindModelGetResult,
+    WinMLModelCatalogGetAvailableModel,
+    WinMLModelCatalogGetAvailableModels,
+    WinMLModelCatalogRelease,
+    WinMLModelCatalogSetExecutionProviders,
+    WinMLModelCatalogSourceCreateFromUri,
+    WinMLModelCatalogSourceCreateFromUriAsync,
+    WinMLModelCatalogSourceCreateFromUriWithHeaders,
+    WinMLModelCatalogSourceCreateFromUriWithHeadersAsync,
+    WinMLModelCatalogSourceGetId,
+    WinMLModelCatalogSourceGetIdSize,
+    WinMLModelCatalogSourceGetResult,
+    WinMLModelCatalogSourceGetUri,
+    WinMLModelCatalogSourceGetUriSize,
+    WinMLModelCatalogSourceRelease,
+)
+
+__all__ = [
+    "EpReadyState",
+    "EpCertification",
+    "CatalogModelInstanceStatus",
+    "CatalogModelStatus",
+    "ExecutionProvider",
+    "EpCatalog",
+    "AsyncOperation",
+    "ModelCatalogSource",
+    "ModelCatalog",
+    "CatalogModelInfo",
+    "CatalogModelInstance",
+]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_ep_string(handle, get_size_fn, get_fn) -> str:
+    """Read a variable-length string property from an EP handle."""
+    size = ctypes.c_size_t()
+    get_size_fn(handle, ctypes.byref(size))
+    if size.value == 0:
+        return ""
+    buf = ctypes.create_string_buffer(size.value)
+    used = ctypes.c_size_t()
+    get_fn(handle, size.value, buf, ctypes.byref(used))
+    return buf.value.decode("utf-8")
+
+
+def _enum_strings(handle, enum_fn) -> list[str]:
+    """Collect strings from a WinMLStringEnumCallback-based enumeration."""
+    results: list[str] = []
+
+    @StringEnumCallback
+    def _callback(value, context):
+        try:
+            results.append(value.decode("utf-8"))
+        except Exception:
+            return False
+        return True
+
+    enum_fn(handle, _callback, None)
+    return results
+
+
+def _make_header_arrays(headers: dict[str, str]):
+    """Convert a dict of headers to ctypes arrays for C API calls."""
+    keys = list(headers.keys())
+    values = list(headers.values())
+    count = len(keys)
+    keys_arr = (ctypes.c_char_p * count)(*(k.encode("utf-8") for k in keys))
+    values_arr = (ctypes.c_char_p * count)(*(v.encode("utf-8") for v in values))
+    return count, keys_arr, values_arr
+
+
+# ---------------------------------------------------------------------------
+# ExecutionProvider
+# ---------------------------------------------------------------------------
+
+class ExecutionProvider:
+    """Handle to a discovered Windows ML execution provider.
+
+    Instances are obtained from :meth:`EpCatalog.find_provider`.
+    The handle is owned by the catalog and must not outlive it.
+    """
+
+    def __init__(self, handle) -> None:
+        self._handle = handle
+
+    @property
+    def name(self) -> str:
+        return _get_ep_string(self._handle, WinMLEpGetNameSize, WinMLEpGetName)
+
+    @property
+    def version(self) -> str:
+        return _get_ep_string(self._handle, WinMLEpGetVersionSize, WinMLEpGetVersion)
+
+    @property
+    def package_family_name(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLEpGetPackageFamilyNameSize, WinMLEpGetPackageFamilyName
+        )
+
+    @property
+    def library_path(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLEpGetLibraryPathSize, WinMLEpGetLibraryPath
+        )
+
+    @property
+    def package_root_path(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLEpGetPackageRootPathSize, WinMLEpGetPackageRootPath
+        )
+
+    @property
+    def ready_state(self) -> EpReadyState:
+        state = ctypes.c_int()
+        WinMLEpGetReadyState(self._handle, ctypes.byref(state))
+        return EpReadyState(state.value)
+
+    @property
+    def certification(self) -> EpCertification:
+        cert = ctypes.c_int()
+        WinMLEpGetCertification(self._handle, ctypes.byref(cert))
+        return EpCertification(cert.value)
+
+    def ensure_ready(self) -> None:
+        """Block until the execution provider is ready.
+
+        Raises :class:`OSError` on failure.
+        """
+        WinMLEpEnsureReady(self._handle)
+
+    def ensure_ready_async(
+        self,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Start an asynchronous readiness check.
+
+        Returns an :class:`AsyncOperation` that can be used to poll, wait,
+        or cancel the operation.
+        """
+        return AsyncOperation(
+            WinMLEpEnsureReadyAsync, self._handle,
+            on_complete=on_complete, on_progress=on_progress,
+        )
+
+    def __repr__(self) -> str:
+        return f"ExecutionProvider(name={self.name!r})"
+
+
+# ---------------------------------------------------------------------------
+# AsyncOperation
+# ---------------------------------------------------------------------------
+
+# Prevent GC of in-flight async operations.  The completion callback removes
+# the entry once the native operation finishes.
+_live_operations: set["AsyncOperation"] = set()
+
+
+class AsyncOperation:
+    """Wraps a ``WinMLAsyncBlock`` for asynchronous operations."""
+
+    def __init__(
+        self,
+        start_fn,
+        *args,
+        result_fn: Optional[Callable] = None,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        """Create and start an async operation.
+
+        Args:
+            start_fn: Native function that initiates the async work. It must
+                accept ``(*args, async_block)`` - i.e. the caller-supplied
+                positional arguments followed by a pointer to a
+                ``WinMLAsyncBlock`` as the **last** parameter.
+            *args: Positional arguments forwarded to *start_fn* before the
+                async block.
+            result_fn: Optional callable to extract a result from the
+                completed async block. If provided, :meth:`get_result`
+                becomes available.
+            on_complete: Optional callback invoked when the operation finishes.
+            on_progress: Optional callback invoked with progress (0.0-1.0).
+        """
+        self._closed = False
+        self._result_fn = result_fn
+
+        # Track live operations so the GC cannot destroy an AsyncOperation
+        # (and its native AsyncBlock) while the native thread is still running.
+        _live_operations.add(self)
+
+        # Build native callbacks.  Must be stored as instance attributes to
+        # prevent garbage collection while the async operation is in flight.
+        # Exceptions in user callbacks are caught to avoid propagating Python
+        # exceptions through native call frames (undefined behavior).
+        if on_complete is not None:
+            _user_complete = on_complete
+
+            @AsyncCompletionCallback
+            def _on_complete(async_ptr):
+                try:
+                    _user_complete()
+                except Exception:
+                    pass
+                finally:
+                    _live_operations.discard(self)
+
+            self._completion_cb = _on_complete
+        else:
+            @AsyncCompletionCallback
+            def _on_complete_default(async_ptr):
+                _live_operations.discard(self)
+
+            self._completion_cb = _on_complete_default
+
+        if on_progress is not None:
+            _user_progress = on_progress
+
+            @AsyncProgressCallback
+            def _on_progress(async_ptr, value):
+                try:
+                    _user_progress(value)
+                except Exception:
+                    pass
+
+            self._progress_cb = _on_progress
+        else:
+            self._progress_cb = AsyncProgressCallback()
+
+        self._block = AsyncBlock()
+        self._block.context = None
+        self._block.callback = self._completion_cb
+        self._block.progress = self._progress_cb
+
+        try:
+            start_fn(*args, ctypes.byref(self._block))
+        except BaseException:
+            _live_operations.discard(self)
+            raise
+
+    def get_status(self, wait: bool = False) -> None:
+        """Poll or wait for the async operation status.
+
+        Raises :class:`OSError` if the operation failed.
+        """
+        WinMLAsyncGetStatus(ctypes.byref(self._block), wait)
+
+    def wait(self) -> None:
+        """Block until the async operation completes.
+
+        Raises :class:`OSError` if the operation failed.
+        """
+        self.get_status(wait=True)
+
+    def cancel(self) -> None:
+        """Request cancellation of the async operation."""
+        WinMLAsyncCancel(ctypes.byref(self._block))
+
+    def get_result(self):
+        """Extract the result after the async operation has completed.
+
+        Only available for operations started with a *result_fn*.
+
+        Raises:
+            RuntimeError: If no result function was provided.
+        """
+        if self._result_fn is None:
+            raise RuntimeError("This operation does not produce a result")
+        return self._result_fn(ctypes.byref(self._block))
+
+    def close(self) -> None:
+        """Release async resources.
+
+        Waits for the operation to complete before releasing the async block
+        to avoid destroying it while the native thread is still running.
+        """
+        if not self._closed:
+            # Wait for the native operation to finish before freeing the block.
+            try:
+                WinMLAsyncGetStatus(ctypes.byref(self._block), True)
+            except OSError:
+                pass
+            WinMLAsyncClose(ctypes.byref(self._block))
+            self._closed = True
+            _live_operations.discard(self)
+
+    def __enter__(self) -> "AsyncOperation":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# EpCatalog
+# ---------------------------------------------------------------------------
+
+class EpCatalog:
+    """Windows ML Execution Provider Catalog.
+
+    Use as a context manager::
+
+        with EpCatalog() as catalog:
+            for ep in catalog.find_all_providers():
+                print(ep.name, ep.ready_state)
+    """
+
+    def __init__(self) -> None:
+        handle = EpCatalogHandle()
+        WinMLEpCatalogCreate(ctypes.byref(handle))
+        self._handle = handle
+
+    def find_all_providers(self) -> list[ExecutionProvider]:
+        """Discover all registered execution providers.
+
+        Returns a list of :class:`ExecutionProvider` handles.
+
+        Raises:
+            RuntimeError: If the catalog has been closed.
+        """
+        if not self._handle:
+            raise RuntimeError("EpCatalog has been closed")
+        providers: list[ExecutionProvider] = []
+
+        @EpEnumCallback
+        def _callback(ep, info_ptr, context):
+            try:
+                providers.append(ExecutionProvider(ep))
+            except Exception:
+                return False
+            return True
+
+        WinMLEpCatalogEnumProviders(self._handle, _callback, None)
+
+        return providers
+
+    def close(self) -> None:
+        """Release the catalog and all associated EP handles."""
+        if self._handle:
+            WinMLEpCatalogRelease(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "EpCatalog":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# ModelCatalogSource
+# ---------------------------------------------------------------------------
+
+class ModelCatalogSource:
+    """Represents a model catalog source endpoint.
+
+    Create from a URI::
+
+        source = ModelCatalogSource.create_from_uri("https://example.com/catalog")
+
+    Or with custom headers::
+
+        source = ModelCatalogSource.create_from_uri_with_headers(
+            "https://example.com/catalog",
+            {"Authorization": "Bearer token"},
+        )
+    """
+
+    def __init__(self, handle) -> None:
+        self._handle = handle
+
+    @staticmethod
+    def create_from_uri(uri: str) -> "ModelCatalogSource":
+        """Create a catalog source from a URI (blocking)."""
+        handle = ModelCatalogSourceHandle()
+        WinMLModelCatalogSourceCreateFromUri(
+            uri.encode("utf-8"), ctypes.byref(handle)
+        )
+        return ModelCatalogSource(handle)
+
+    @staticmethod
+    def create_from_uri_async(
+        uri: str,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Create a catalog source from a URI (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        the :class:`ModelCatalogSource`.
+        """
+        def _extract(block_ptr):
+            handle = ModelCatalogSourceHandle()
+            WinMLModelCatalogSourceGetResult(block_ptr, ctypes.byref(handle))
+            return ModelCatalogSource(handle)
+
+        return AsyncOperation(
+            WinMLModelCatalogSourceCreateFromUriAsync,
+            uri.encode("utf-8"),
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    @staticmethod
+    def create_from_uri_with_headers(
+        uri: str, headers: dict[str, str],
+    ) -> "ModelCatalogSource":
+        """Create a catalog source from a URI with custom HTTP headers (blocking)."""
+        count, keys_arr, values_arr = _make_header_arrays(headers)
+        handle = ModelCatalogSourceHandle()
+        WinMLModelCatalogSourceCreateFromUriWithHeaders(
+            uri.encode("utf-8"), count, keys_arr, values_arr, ctypes.byref(handle)
+        )
+        return ModelCatalogSource(handle)
+
+    @staticmethod
+    def create_from_uri_with_headers_async(
+        uri: str,
+        headers: dict[str, str],
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Create a catalog source from a URI with custom HTTP headers (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        the :class:`ModelCatalogSource`.
+        """
+        count, keys_arr, values_arr = _make_header_arrays(headers)
+
+        def _extract(block_ptr):
+            handle = ModelCatalogSourceHandle()
+            WinMLModelCatalogSourceGetResult(block_ptr, ctypes.byref(handle))
+            return ModelCatalogSource(handle)
+
+        return AsyncOperation(
+            WinMLModelCatalogSourceCreateFromUriWithHeadersAsync,
+            uri.encode("utf-8"), count, keys_arr, values_arr,
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    @property
+    def id(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLModelCatalogSourceGetIdSize, WinMLModelCatalogSourceGetId
+        )
+
+    @property
+    def uri(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLModelCatalogSourceGetUriSize, WinMLModelCatalogSourceGetUri
+        )
+
+    def close(self) -> None:
+        """Release the catalog source handle."""
+        if self._handle:
+            WinMLModelCatalogSourceRelease(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "ModelCatalogSource":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        return f"ModelCatalogSource(id={self.id!r})"
+
+
+# ---------------------------------------------------------------------------
+# ModelCatalog
+# ---------------------------------------------------------------------------
+
+class ModelCatalog:
+    """Windows ML Model Catalog.
+
+    Use as a context manager::
+
+        with ModelCatalogSource.create_from_uri(uri) as source:
+            with ModelCatalog([source]) as catalog:
+                for model in catalog.find_all_models():
+                    print(model.name)
+    """
+
+    def __init__(self, sources: list[ModelCatalogSource]) -> None:
+        count = len(sources)
+        arr = (ModelCatalogSourceHandle * count)(
+            *(s._handle for s in sources)
+        )
+        handle = ModelCatalogHandle()
+        WinMLModelCatalogCreate(count, arr, ctypes.byref(handle))
+        self._handle = handle
+
+    @property
+    def execution_providers(self) -> list[str]:
+        """List the execution providers configured on this catalog."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        return _enum_strings(self._handle, WinMLModelCatalogEnumExecutionProviders)
+
+    def set_execution_providers(self, providers: list[str]) -> None:
+        """Set the execution providers to use for model queries."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        count = len(providers)
+        arr = (ctypes.c_char_p * count)(*(p.encode("utf-8") for p in providers))
+        WinMLModelCatalogSetExecutionProviders(self._handle, count, arr)
+
+    def get_available_model(self, id_or_name: str) -> "CatalogModelInfo":
+        """Look up a single available model by ID or name."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        handle = CatalogModelInfoHandle()
+        WinMLModelCatalogGetAvailableModel(
+            self._handle, id_or_name.encode("utf-8"), ctypes.byref(handle)
+        )
+        return CatalogModelInfo(handle)
+
+    def get_available_models(self) -> list["CatalogModelInfo"]:
+        """Enumerate all available models."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        models: list[CatalogModelInfo] = []
+
+        @CatalogModelInfoEnumCallback
+        def _callback(model_info, context):
+            try:
+                models.append(CatalogModelInfo(model_info))
+            except Exception:
+                return False
+            return True
+
+        WinMLModelCatalogGetAvailableModels(self._handle, _callback, None)
+        return models
+
+    def find_model(self, id_or_name: str) -> "CatalogModelInfo":
+        """Find a model by ID or name (blocking)."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        handle = CatalogModelInfoHandle()
+        WinMLModelCatalogFindModel(
+            self._handle, id_or_name.encode("utf-8"), ctypes.byref(handle)
+        )
+        return CatalogModelInfo(handle)
+
+    def find_model_async(
+        self,
+        id_or_name: str,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Find a model by ID or name (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        the :class:`CatalogModelInfo`.
+        """
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+
+        def _extract(block_ptr):
+            handle = CatalogModelInfoHandle()
+            WinMLModelCatalogFindModelGetResult(block_ptr, ctypes.byref(handle))
+            return CatalogModelInfo(handle)
+
+        return AsyncOperation(
+            WinMLModelCatalogFindModelAsync,
+            self._handle, id_or_name.encode("utf-8"),
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    def find_all_models(self) -> list["CatalogModelInfo"]:
+        """Find all models (blocking)."""
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+        models: list[CatalogModelInfo] = []
+
+        @CatalogModelInfoEnumCallback
+        def _callback(model_info, context):
+            try:
+                models.append(CatalogModelInfo(model_info))
+            except Exception:
+                return False
+            return True
+
+        WinMLModelCatalogFindAllModels(self._handle, _callback, None)
+        return models
+
+    def find_all_models_async(
+        self,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Find all models (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        a list of :class:`CatalogModelInfo`.
+        """
+        if not self._handle:
+            raise RuntimeError("ModelCatalog has been closed")
+
+        def _extract(block_ptr):
+            models: list[CatalogModelInfo] = []
+
+            @CatalogModelInfoEnumCallback
+            def _callback(model_info, context):
+                try:
+                    models.append(CatalogModelInfo(model_info))
+                except Exception:
+                    return False
+                return True
+
+            WinMLModelCatalogFindAllModelsGetResult(block_ptr, _callback, None)
+            return models
+
+        return AsyncOperation(
+            WinMLModelCatalogFindAllModelsAsync,
+            self._handle,
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    def close(self) -> None:
+        """Release the model catalog."""
+        if self._handle:
+            WinMLModelCatalogRelease(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "ModelCatalog":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# CatalogModelInfo
+# ---------------------------------------------------------------------------
+
+class CatalogModelInfo:
+    """Metadata about a model in the catalog.
+
+    Obtained from :meth:`ModelCatalog.find_model` or enumeration methods.
+    """
+
+    def __init__(self, handle) -> None:
+        self._handle = handle
+
+    @property
+    def id(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLCatalogModelInfoGetIdSize, WinMLCatalogModelInfoGetId
+        )
+
+    @property
+    def name(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLCatalogModelInfoGetNameSize, WinMLCatalogModelInfoGetName
+        )
+
+    @property
+    def publisher(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetPublisherSize,
+            WinMLCatalogModelInfoGetPublisher,
+        )
+
+    @property
+    def source_id(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetSourceIdSize,
+            WinMLCatalogModelInfoGetSourceId,
+        )
+
+    @property
+    def version(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetVersionSize,
+            WinMLCatalogModelInfoGetVersion,
+        )
+
+    @property
+    def license(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetLicenseSize,
+            WinMLCatalogModelInfoGetLicense,
+        )
+
+    @property
+    def license_uri(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetLicenseUriSize,
+            WinMLCatalogModelInfoGetLicenseUri,
+        )
+
+    @property
+    def license_text(self) -> str:
+        return _get_ep_string(
+            self._handle,
+            WinMLCatalogModelInfoGetLicenseTextSize,
+            WinMLCatalogModelInfoGetLicenseText,
+        )
+
+    @property
+    def uri(self) -> str:
+        return _get_ep_string(
+            self._handle, WinMLCatalogModelInfoGetUriSize, WinMLCatalogModelInfoGetUri
+        )
+
+    @property
+    def model_size_in_bytes(self) -> int:
+        size = ctypes.c_uint64()
+        WinMLCatalogModelInfoGetModelSizeInBytes(self._handle, ctypes.byref(size))
+        return size.value
+
+    @property
+    def execution_providers(self) -> list[str]:
+        return _enum_strings(
+            self._handle, WinMLCatalogModelInfoEnumExecutionProviders
+        )
+
+    @property
+    def status(self) -> CatalogModelStatus:
+        val = ctypes.c_int()
+        WinMLCatalogModelInfoGetStatus(self._handle, ctypes.byref(val))
+        return CatalogModelStatus(val.value)
+
+    def get_instance_async(
+        self,
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Download or prepare a model instance (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        the :class:`CatalogModelInstance`.
+        """
+        def _extract(block_ptr):
+            result = CatalogModelInstanceResult()
+            WinMLCatalogModelInfoGetInstanceResult(block_ptr, ctypes.byref(result))
+            if result.extendedError < 0:
+                raise OSError(
+                    f"GetInstance failed: 0x{result.extendedError & 0xFFFFFFFF:08X}"
+                )
+            return CatalogModelInstance(result.instance)
+
+        return AsyncOperation(
+            WinMLCatalogModelInfoGetInstanceAsync,
+            self._handle,
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    def get_instance_with_headers_async(
+        self,
+        headers: dict[str, str],
+        on_complete: Optional[Callable[[], None]] = None,
+        on_progress: Optional[Callable[[float], None]] = None,
+    ) -> "AsyncOperation":
+        """Download or prepare a model instance with custom HTTP headers (async).
+
+        Call :meth:`AsyncOperation.get_result` after completion to obtain
+        the :class:`CatalogModelInstance`.
+        """
+        count, keys_arr, values_arr = _make_header_arrays(headers)
+
+        def _extract(block_ptr):
+            result = CatalogModelInstanceResult()
+            WinMLCatalogModelInfoGetInstanceResult(block_ptr, ctypes.byref(result))
+            if result.extendedError < 0:
+                raise OSError(
+                    f"GetInstance failed: 0x{result.extendedError & 0xFFFFFFFF:08X}"
+                )
+            return CatalogModelInstance(result.instance)
+
+        return AsyncOperation(
+            WinMLCatalogModelInfoGetInstanceWithHeadersAsync,
+            self._handle, count, keys_arr, values_arr,
+            result_fn=_extract,
+            on_complete=on_complete,
+            on_progress=on_progress,
+        )
+
+    def close(self) -> None:
+        """Release the model info handle."""
+        if self._handle:
+            WinMLCatalogModelInfoRelease(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "CatalogModelInfo":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        return f"CatalogModelInfo(name={self.name!r})"
+
+
+# ---------------------------------------------------------------------------
+# CatalogModelInstance
+# ---------------------------------------------------------------------------
+
+class CatalogModelInstance:
+    """A downloaded or local instance of a catalog model.
+
+    Obtained from :meth:`CatalogModelInfo.get_instance_async`.
+    """
+
+    def __init__(self, handle) -> None:
+        self._handle = handle
+
+    @property
+    def model_paths(self) -> list[str]:
+        """List of local file paths for the model files."""
+        return _enum_strings(
+            self._handle, WinMLCatalogModelInstanceEnumModelPaths
+        )
+
+    @property
+    def model_info(self) -> CatalogModelInfo:
+        """Get the model info associated with this instance."""
+        handle = CatalogModelInfoHandle()
+        WinMLCatalogModelInstanceGetModelInfo(self._handle, ctypes.byref(handle))
+        return CatalogModelInfo(handle)
+
+    def close(self) -> None:
+        """Close and release the model instance."""
+        if self._handle:
+            try:
+                WinMLCatalogModelInstanceClose(self._handle)
+            except OSError:
+                pass
+            WinMLCatalogModelInstanceRelease(self._handle)
+            self._handle = None
+
+    def __enter__(self) -> "CatalogModelInstance":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        paths = self.model_paths
+        return f"CatalogModelInstance(paths={paths!r})"