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 every artifact format because the native load call detects the 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.onnx",
        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.

Optional native Task component

Wheels that include the native Task component also expose windowsml.tasks. Task IDLs for Text Generation, Chat Completion, and Automatic Speech Recognition are included in the generated low-level projection. The idiomatic facade covers all three families and executes entirely in the bundled native WinMLTasks.dll.

from windowsml.tasks import (
    Tasks,
    TextGenerationOptions,
    TextGenerationOutputKind,
)

with Tasks(runtime) as tasks:
    configuration = (
        tasks.create_text_generation_configuration()
        .configure_unified(
            pipeline=pipeline,
            token_input_stage=stage,
            token_input_index=0,
            output_stage=stage,
            output_index=0,
            output_kind=TextGenerationOutputKind.LOGITS,
            state_owner_stage=stage,
            token_target=cpu,
            tokenizer=tokenizer,
        )
    )
    with tasks.create_text_generation_task(
        tokenizer,
        default_configuration=configuration,
    ) as task:
        result = task.generate(
            "Write one short greeting.",
            TextGenerationOptions(max_new_tokens=32),
        )
        print(result.text)

Use task.stream(...) for token/text deltas, or disclose task.default_session and call generate_tokens / continue_tokens for raw token control. Sessions, streams, configurations, and the owning Runtime remain available through exact native-backed wrapper properties.

Task metadata and explicit session/configuration creation have no Task-creation-thread affinity. Supplied and retained collaborators retain their own contracts, and each session belongs to its creation thread. Convenience APIs share one lazy default_session; callers synchronize default-configuration changes, lazy cache access, and shared convenience use. close() must not overlap any operation on the same Task wrapper, including through reentrant callbacks. No concurrent Close or mutation safety is provided.

With a live cached session, call Task close() on that session's creation thread; without one, Task close() has no creation-thread restriction. Call session, stream, and live-input close() on their owning creation thread. Final native Release is free-threaded, and immutable Text and Chat results have no creation-thread affinity. Stream cancel() may be called from another thread and signals a separate native cancellation source; it does not marshal close() to the creation thread.

ONNX stages expose stage.symbolic_dimensions before pipeline construction. For example, a Whisper encoder with symbolic feature axes can be specialized without changing the model:

encoder_stage.symbolic_dimensions["feature_size"] = 80
encoder_stage.symbolic_dimensions["encoder_sequence_length"] = 3000
encoder_pipeline = encoder_builder.build()

ASR runtime configurations are created by their owning Task. Assign the validated configuration back to that same Task before using the convenience methods:

configuration = task.create_configuration()
configuration.configure_whisper(
    encoder_pipeline=encoder_pipeline,
    encoder_stage=encoder_stage,
    decoder_pipeline=decoder_pipeline,
    decoder_stage=decoder_stage,
    tensor_target=cpu,
)
configuration.validate()
task.default_configuration = configuration
result = task.transcribe(waveform, metadata)

configure_whisper uses one atomic typed native binding call. A failed replacement leaves the previous bindings unchanged; successful session creation consumes the configuration. session.configuration.whisper_bindings returns an immutable record of independently owned Pipeline, Stage and ExecutionTarget wrappers over the actual native collaborators, including optional preprocessing and force_encoder_output_copy.

Use session.supports_whisper_log_mel and session.supports_live_input for non-mutating capability QI. Current Whisper supports log-mel input but not live input. session.transcribe_whisper_log_mel(features) requires the exact FLOAT32 [1,80,3000] Whisper preprocessing semantics documented in the ASR API reference; shape alone does not establish those semantics. No feature GUID, lengths tensor, implementation selector or runtime-object bag is required.

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.