Metadata-Version: 2.4
Name: windowsml
Version: 2.9.36a0
Summary: Python bindings for Windows AI Machine Learning catalogs and Runtime
License: MICROSOFT SOFTWARE LICENSE TERMS
        Microsoft Windows ML Runtime
        ________________________________________
        IF YOU LIVE IN (OR ARE A BUSINESS WITH A PRINCIPAL PLACE OF BUSINESS IN) THE UNITED STATES, PLEASE READ THE “BINDING ARBITRATION AND CLASS ACTION WAIVER” SECTION BELOW. IT AFFECTS HOW DISPUTES ARE RESOLVED.
        ________________________________________
        These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.
            1. INSTALLATION AND USE RIGHTS.
                a) General. Subject to the terms of this agreement, you may install and use any number of copies of the software to develop and test your applications, solely for use on Windows. When building Generative AI applications follow the guidelines in https://learn.microsoft.com/windows/ai/rai.
                b) Included Microsoft Applications. The software may include other Microsoft applications. These license terms apply to those included applications, if any, unless other license terms are provided with the other Microsoft applications.
                c) Microsoft Platforms. The software may include components from Microsoft Windows. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the “Licenses” folder accompanying the software.
                d) Third Party Materials. The software may use or include source code, object code, or data available under an open source or open data license (“Open Source Materials”) or a proprietary license from a third party (with Open Source Materials, collectively, “Third Party Materials”) that are licensed under the specific license terms applicable to the Third Party Materials (an “Third Party License Agreement”). To the extent that any Third Party License Agreement requires that the corresponding Third Party Materials be licensed under terms that are different from the terms set forth in this Agreement, then such Third Party Materials are licensed under the terms of that Third Party License Agreement and the other terms and conditions in this Agreement will not apply with respect to those Third Party Materials. You (a) acknowledge that any such Third Party License Agreement is solely between Licensee and the applicable licensor of the Third Party Materials, and (b) will comply with the terms of any such Third Party License Agreement. Without limitation to the foregoing, the licenses referenced on these websites (https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/supported-execution-providers and https://aka.ms/winml-licenses) are deemed to be “Third Party Materials.”
            2. DATA.
                a) Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation. There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices.
                b) Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Online Services Terms to all customers effective May 25, 2018, at https://docs.microsoft.com/en-us/legal/gdpr.
            3. PRE-RELEASE SOFTWARE. The software may include pre-release software. The pre-release software may not operate correctly and may be different from the commercially released version. Microsoft may not release a commercial version.
            4. FEEDBACK. If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because Microsoft includes your feedback in them. These rights survive this agreement.
            5. DISTRIBUTABLE CODE. The software may contain code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section.
                a) Distribution Rights. The code and test files described below are distributable if included with the software.
                    i. Any files that are binplaced with your application by the WindowsAppSDK NuGet package are, by definition, permitted to be redistributed.  This applies to both framework package dependent and self-contained deployments.
                    ii. Image Library. You may copy and distribute images, graphics, and animations in the Image Library as described in the software documentation; and
                    iii. Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications.
                b) Distribution Requirements. For any code you distribute, you must:
                    i. add significant primary functionality to it in your applications;
                    ii. require distributors and external end users to agree to terms that protect it and Microsoft at least as much as this agreement; and
                    iii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code.
                c) Distribution Restrictions. You may not:
                    i. use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or
                    ii. modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it.
            6. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
                a) work around any technical limitations in the software that only allow you to use it in certain ways;
                b) reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included in the software;
                c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
                d) use the software in any way that is against the law or to create or propagate malware; or
                e) share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party.
            7. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting.
            8. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
            9. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.
            10. BINDING ARBITRATION AND CLASS ACTION WAIVER. This Section applies if you live in (or, if a business, your principal place of business is in) the United States. If you and Microsoft have a dispute, you and Microsoft agree to try for 60 days to resolve it informally. If you and Microsoft can’t, you and Microsoft agree to binding individual arbitration before the American Arbitration Association under the Federal Arbitration Act (“FAA”), and not to sue in court in front of a judge or jury. Instead, a neutral arbitrator will decide. Class action lawsuits, class-wide arbitrations, private attorney-general actions, and any other proceeding where someone acts in a representative capacity are not allowed; nor is combining individual proceedings without the consent of all parties. The complete Arbitration Agreement contains more terms and is at https://aka.ms/arb-agreement-4. You and Microsoft agree to these terms.
            11. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.
            12. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration).
            13. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
                a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
                b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
                c) Germany and Austria.
                    i. Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
                    ii. Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
                        Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
            14. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
            15. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES.
        
        This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
        
        It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.
        
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: comtypes>=1.4.0; platform_system == "Windows"
Provides-Extra: with-ort
Requires-Dist: onnxruntime-windowsml==1.30.1.202610302006; extra == "with-ort"
Provides-Extra: llama
Requires-Dist: windowsml-llama-core==2.9.36a0; extra == "llama"
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist

# 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 `onnxruntime-windowsml` package, use the
`with-ort` extra:

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

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

The Runtime 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.

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

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

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

### Runtime - target-bound tensors

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

```bash
pip install numpy pillow
```

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

| Ingress | Ownership and copy behavior |
|---|---|
| `tensor_from_numpy` | Runtime-owned tensor; source data is copied synchronously |
| `tensor_from_buffer(..., COPY)` | Runtime-owned packed copy |
| `tensor_from_buffer(..., READ)` | Borrowed contiguous view; tensor retains the Python buffer export |
| `tensor_from_buffer(..., READWRITE)` | Borrowed writable view; mutations are shared |
| image/audio/token helpers | Native conversion creates a target-bound Runtime tensor |

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

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

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

```python
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.encoder_decoder_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_encoder_input` and `session.supports_live_input` for
non-mutating capability QI. The composed Whisper session accepts its log-mel
encoder input but not live input. `session.transcribe_encoder_input(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.

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