Metadata-Version: 2.1
Name: windowsml
Version: 1.8.2192
Summary: Python bindings for the Windows AI Machine Learning EP Catalog API
License: Copyright (C) Microsoft Corporation. All rights reserved.
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: with-ort
Requires-Dist: onnxruntime-windowsml ==1.23.5.202603312053 ; extra == 'with-ort'

# 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

```bash
pip install windowsml
```

### ONNX Runtime dependency

To automatically install a matching version of ONNX Runtime, use the
`with-ort` extra:

```bash
pip install windowsml[with-ort]
```

If you choose **not** to use `[with-ort]`, you must install a compatible version
of `onnxruntime` separately and ensure it matches the version expected by this
package.

## Quick Start

### EP Catalog — discover execution providers

```python
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

```python
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}")
```

## 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.

| Method | Description |
|---|---|
| `find_all_providers()` | Returns `list[ExecutionProvider]` |
| `close()` | Release the catalog |

#### `ExecutionProvider`

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

| Property / Method | Type |
|---|---|
| `name` | `str` |
| `version` | `str` |
| `package_family_name` | `str` |
| `library_path` | `str` |
| `package_root_path` | `str` |
| `ready_state` | `EpReadyState` |
| `certification` | `EpCertification` |
| `ensure_ready()` | Blocks until ready |
| `ensure_ready_async(on_complete, on_progress)` | Returns `AsyncOperation` |

#### `ModelCatalogSource`

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

| Method / Property | Description |
|---|---|
| `create_from_uri(uri)` | Create from a URI or local path (blocking) |
| `create_from_uri_async(uri, ...)` | Create from a URI (async) |
| `create_from_uri_with_headers(uri, headers)` | Create with custom HTTP headers (blocking) |
| `create_from_uri_with_headers_async(uri, headers, ...)` | Create with custom HTTP headers (async) |
| `id` | `str` — source identifier |
| `uri` | `str` — source URI |
| `close()` | Release the source |

#### `ModelCatalog(sources)`

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

| Method / Property | Description |
|---|---|
| `execution_providers` | `list[str]` — configured EPs |
| `set_execution_providers(providers)` | Set EP filter for queries |
| `get_available_model(id_or_name)` | Returns `CatalogModelInfo` |
| `get_available_models()` | Returns `list[CatalogModelInfo]` |
| `find_model(id_or_name)` | Find a model (blocking) |
| `find_model_async(id_or_name, ...)` | Find a model (async) |
| `find_all_models()` | Find all models (blocking) |
| `find_all_models_async(...)` | Find all models (async) |
| `close()` | Release the catalog |

#### `CatalogModelInfo`

Metadata about a model in the catalog.

| Property / Method | Type |
|---|---|
| `id` | `str` |
| `name` | `str` |
| `publisher` | `str` |
| `source_id` | `str` |
| `version` | `str` |
| `license` | `str` |
| `license_uri` | `str` |
| `license_text` | `str` |
| `uri` | `str` |
| `model_size_in_bytes` | `int` |
| `execution_providers` | `list[str]` |
| `status` | `CatalogModelStatus` |
| `get_instance_async(...)` | Returns `AsyncOperation` → `CatalogModelInstance` |
| `get_instance_with_headers_async(headers, ...)` | Returns `AsyncOperation` → `CatalogModelInstance` |
| `close()` | Release the model info |

#### `CatalogModelInstance`

A downloaded or local instance of a catalog model.

| Property / Method | Type |
|---|---|
| `model_paths` | `list[str]` — local file paths |
| `model_info` | `CatalogModelInfo` |
| `close()` | Release the instance |

#### `AsyncOperation`

Returned by async methods. Supports context-manager usage.

| Method | Description |
|---|---|
| `wait()` | Block until complete |
| `get_status(wait=False)` | Poll or wait for status |
| `get_result()` | Extract the typed result (if applicable) |
| `cancel()` | Request cancellation |
| `close()` | Release async resources |
