windowsml

Python bindings for the Windows AI Machine Learning API.

This package provides a ctypes-based wrapper around the WinML flat C API, enabling Python applications to discover and manage execution providers and model catalogs for ONNX Runtime on Windows.

Installation

pip install windowsml

ONNX Runtime dependency

To automatically install a matching onnxruntime-windowsml package, use the with-ort extra:

pip install windowsml[with-ort]

If you choose not to use [with-ort], install a compatible version of onnxruntime-windowsml separately for Runtime preview ONNX workloads. Catalog APIs do not require this optional dependency.

The Runtime preview projection does not import ONNX Runtime or load its native sidecar during module import. At the first model load, [with-ort] loads the exact native sidecar when Python ONNX Runtime is not already present. To share a manually registered execution provider, import onnxruntime and complete registration before calling any Runtime model-load entry point. The projection applies this guard to ONNX, CGC, and opaque artifacts because the native load call detects the artifact format. Runtime then uses the same process-loaded ONNX Runtime instance and registration state for ORT-backed stages.

import onnxruntime as ort
from windowsml.runtime import Runtime

provider_path = r"C:\path\to\provider.dll"
ort.register_execution_provider_library("MyExecutionProvider", provider_path)

with Runtime() as runtime, runtime.load_model("model.onnx") as model:
    ...

The loader choice is process-wide. RuntimeCore finalizes its ORT API selection when an ORT-backed operation first needs it.

Raw artifacts with external resources can supply a generic mapping of resource names to contiguous buffer-protocol values. Runtime retains each zero-copy buffer export through the model and its dependent stages:

import mmap

from windowsml.runtime import Runtime

with open("weights.bin", "rb") as weights_file:
    weights = mmap.mmap(weights_file.fileno(), 0, access=mmap.ACCESS_READ)
    with Runtime() as runtime, runtime.load_model(
        "model.mlir",
        resources={"model.weight": memoryview(weights)},
    ) as model:
        ...
    weights.close()

Quick Start

EP Catalog — discover execution providers

from windowsml import EpCatalog

with EpCatalog() as catalog:
    for ep in catalog.find_all_providers():
        print(f"{ep.name} v{ep.version} - {ep.ready_state.name}")

        # Ensure the provider is ready (downloads/installs if needed)
        ep.ensure_ready()

Model Catalog — discover and download models

from windowsml import ModelCatalogSource, ModelCatalog

with ModelCatalogSource.create_from_uri("https://example.com/catalog.json") as source:
    with ModelCatalog([source]) as catalog:
        for model in catalog.find_all_models():
            print(f"{model.name} v{model.version} by {model.publisher}")
            print(f"  Size: {model.model_size_in_bytes} bytes")
            print(f"  EPs:  {model.execution_providers}")

Runtime preview — target-bound tensors

Dev-profile wheels also expose windowsml.runtime. NumPy and Pillow are optional ecosystem dependencies; install only what the application uses:

pip install numpy pillow

import numpy as np
from windowsml.runtime import (
    ImageTensorOptions,
    Runtime,
    TensorAccessMode,
    TensorDataType,
)

with Runtime() as runtime, runtime.create_cpu_target() as cpu:
    dense = runtime.tensor_from_numpy(
        np.zeros((1, 3, 224, 224), dtype=np.float32),
        target=cpu,
    )

    storage = bytearray(np.arange(4, dtype=np.float32).tobytes())
    borrowed = runtime.tensor_from_buffer(
        storage,
        TensorDataType.FLOAT32,
        (2, 2),
        access=TensorAccessMode.READWRITE,
        target=cpu,
    )

    image = runtime.tensor_from_image(
        np.zeros((224, 224, 3), dtype=np.uint8),
        options=ImageTensorOptions(size=(224, 224)),
        target=cpu,
    )

    image.close()
    borrowed.close()
    dense.close()

Close tensors before resizing or releasing borrowed storage. Context managers and explicit close() calls release native references deterministically.

API Reference

Enums

• EpReadyState — Ready, NotReady, NotPresent
• EpCertification — Unknown, Certified, Uncertified
• CatalogModelStatus — Ready, NotReady
• CatalogModelInstanceStatus — Available, InProgress, Unavailable

Classes

EpCatalog()

Context manager for the EP catalog.

ExecutionProvider

Handle to a discovered EP (owned by the catalog).

ModelCatalogSource

Represents a catalog source endpoint. Create via static factory methods.

ModelCatalog(sources)

Context manager for the model catalog. Created from a list of ModelCatalogSource.

CatalogModelInfo

Metadata about a model in the catalog.

CatalogModelInstance

A downloaded or local instance of a catalog model.

AsyncOperation

Returned by async methods. Supports context-manager usage.