Metadata-Version: 2.4
Name: winml-cli
Version: 0.2.0
Summary: Accelerate Model Deployment on WinML
Author: WinML Team
License: MIT
Project-URL: Bug Tracker, https://github.com/microsoft/winml-cli/issues
Project-URL: Documentation, https://github.com/microsoft/winml-cli/blob/main/README.md
Project-URL: Homepage, https://github.com/microsoft/winml-cli
Project-URL: Repository, https://github.com/microsoft/winml-cli.git
Keywords: onnx,winml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.12,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click>=8.4
Requires-Dist: colorama>=0.4.6
Requires-Dist: datasets>=4.1.1
Requires-Dist: pyarrow==23.0.1
Requires-Dist: diffusers>=0.36
Requires-Dist: evaluate>=0.4.6
Requires-Dist: fastapi>=0.135.3
Requires-Dist: hf_xet>=1.1.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: jsonschema>=4.23
Requires-Dist: mcp>=0.1.0
Requires-Dist: ml-dtypes>=0.5.3
Requires-Dist: numpy<2.3,>=2.2
Requires-Dist: onnx==1.18
Requires-Dist: onnx-ir>=0.1
Requires-Dist: onnxruntime-windowsml==1.24.5.202604171637
Requires-Dist: onnxscript>=0.2
Requires-Dist: opentelemetry-sdk>=1.39.1
Requires-Dist: optimum>=2
Requires-Dist: optimum-onnx>=0.1
Requires-Dist: plotext>=5.3.2
Requires-Dist: pandas==2.3.3
Requires-Dist: psutil>=7
Requires-Dist: pydantic>=2
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: rapidfuzz>=3.9
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=14
Requires-Dist: scikit-learn>=1.7
Requires-Dist: scipy<1.16,>=1.15
Requires-Dist: sentencepiece>=0.2.1
Requires-Dist: seqeval>=1.2.2
Requires-Dist: snakemd>=2
Requires-Dist: timm>=1.0.22
Requires-Dist: tokenizers>=0.22
Requires-Dist: torch>=2.9
Requires-Dist: torchinfo>=1.8
Requires-Dist: torchmetrics[detection]>=1.0
Requires-Dist: torchvision>=0.24
Requires-Dist: tqdm>=4.67
Requires-Dist: transformers>=4.57
Requires-Dist: uvicorn[standard]>=0.42.0
Requires-Dist: windowsml==2.0.300
Provides-Extra: dev
Requires-Dist: ipykernel>=6.30.1; extra == "dev"
Requires-Dist: ipywidgets>=8.1.7; extra == "dev"
Requires-Dist: jupyter>=1.1.1; extra == "dev"
Requires-Dist: markdown-it-py>=3; extra == "dev"
Requires-Dist: matplotlib>=3.10; extra == "dev"
Requires-Dist: mkdocs-jupyter>=0.25; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: mypy>=1.18; extra == "dev"
Requires-Dist: nbconvert>=7.16; extra == "dev"
Requires-Dist: pymdown-extensions>=10.7; extra == "dev"
Requires-Dist: pytest>=8.4; extra == "dev"
Requires-Dist: pytest-cov>=7; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: seaborn>=0.13; extra == "dev"
Requires-Dist: timm>=1.0.20; extra == "dev"
Requires-Dist: types-colorama>=0.4.15.20250801; extra == "dev"
Provides-Extra: audio
Requires-Dist: soundfile>=0.13; extra == "audio"
Provides-Extra: openvino
Requires-Dist: openvino>=2023; extra == "openvino"
Provides-Extra: qnn
Requires-Dist: onnxruntime-qnn>=1.24.1; python_version >= "3.11" and extra == "qnn"
Dynamic: license-file

# WinML CLI

[![WinML CLI CI](https://github.com/microsoft/winml-cli/actions/workflows/modelkit-ci.yml/badge.svg)](https://github.com/microsoft/winml-cli/actions/workflows/modelkit-ci.yml)
![Status](https://img.shields.io/badge/status-preview-blue)
[![PyPI release](https://img.shields.io/pypi/v/winml-cli)](https://pypi.org/project/winml-cli/)
![License](https://img.shields.io/badge/license-MIT-green)

**Windows ML CLI** is a command line tool for building **portable, performant, and high-quality** AI models for Windows ML. It takes you from a source model — whether from Hugging Face or your own pipeline — to a hardware-optimized artifact in a reproducible workflow.

Purpose-built for Windows hardware diversity, the CLI handles conversion, graph optimization, and compilation across AMD, Intel, NVIDIA, and Qualcomm targets. The CLI fits naturally into CI/CD pipelines so teams can validate and ship models easily.

---

## What you can do

- **Build once, run across hardwares.** Compose your own workflow from primitive commands (`export`, `analyze`, `optimize`, `quantize`, `compile`), or use an auto-generated config with `winml build` - both produce portable models that run across hardware.
- **Drill into the details.** Deep insights into operator compatibility, shape mismatches, graph optimizations, and EP-aware tuning at any stage of the pipeline.
- **AI-ready.** CLI-driven tools with built-in skills, friendly to work with mainstream agents.

## What you get out of the box

- **All Windows ML EPs supported.** Every [supported execution provider](https://microsoft.github.io/winml-cli/latest/concepts/eps-and-devices/#eps-winml-cli-supports) is available behind the same commands.
- **Curated model catalog.** A [verified set of models](https://microsoft.github.io/winml-cli/latest/reference/supported-models/) that run across all Windows ML EPs - a reliable starting point.
- **Bring your own ONNX.** Not only for converting from PyTorch - bring an [existing ONNX model](https://microsoft.github.io/winml-cli/latest/tutorials/build-from-onnx/) to get operator-compatibility insights and optimize it based on the analysis.

---

## 🎯 Getting Started

### Prerequisites

| Component | Details |
|---|---|
| Windows | Windows 11 24H2 or later (required for NPU support; earlier versions work for CPU/GPU) |
| Python | 3.11 |
| Package manager | [uv](https://github.com/astral-sh/uv) |
| WinML CLI | [PyPI](https://pypi.org/project/winml-cli/) |

### Installation

WinML CLI requires **Python 3.11** and is distributed as a Python wheel. We recommend [uv](https://docs.astral.sh/uv/) for fast, reproducible environment setup.

**1. Create an environment**

```bash
uv venv --python 3.11
```

Activate it:

```bash
# Windows (PowerShell)
.venv\Scripts\activate

# Windows (Git Bash / WSL)
source .venv/Scripts/activate
```

**2. Install winml-cli**

```bash
uv pip install winml-cli
```

**3. Verify your environment**

```bash
uv run winml sys --list-device --list-ep
```

This command enumerates available compute devices and execution providers on your machine. If an expected device or execution provider is missing, `winml sys` is the right place to diagnose it. See [winml sys](https://microsoft.github.io/winml-cli/latest/commands/sys/) for the full flag reference and troubleshooting tips.

## 🚀 Quick Start

### Inspect the model

Before downloading any models, confirm that winml-cli recognises the model:

```bash
uv run winml inspect -m microsoft/resnet-50
```

💡 Tip: Always inspect before build to catch unsupported architectures early.

### Build the model

```bash
uv run winml build -m microsoft/resnet-50 -o resnet_out/ --no-quant
```

`winml build` runs all pipeline steps in sequence — export, optimize, quantize. You can start a model build without a config file, or provide one to configure each step in the sequence (see [`winml config`](https://microsoft.github.io/winml-cli/latest/commands/config/) to customize). All intermediate artifacts land in `resnet_out/`. For more details, see [Output Layout - Windows ML CLI](https://microsoft.github.io/winml-cli/latest/reference/output-layout/#file-categories).

### Benchmark the model

```bash
uv run winml perf -m resnet_out/model.onnx --device auto --iterations 50 --monitor
```

`--device auto` lets the CLI resolve the best available device on your machine — NPU first, then GPU, then CPU.

---

## 🔀 Try Other Ways

- **Use with AI Agent** — See details at [Use with AI Agent - Windows ML CLI](https://microsoft.github.io/winml-cli/latest/getting-started/agent-skill/).
- **UI Quickstart** — See also [UI Quickstart - Windows ML CLI](https://microsoft.github.io/winml-cli/latest/getting-started/ui-quickstart/).

---

## 📚 Learn More
- **[Full Documentation](https://microsoft.github.io/winml-cli/latest/)** — Access the complete wiki for detailed guides, API references, and troubleshooting.
- **[Supported Models](https://microsoft.github.io/winml-cli/latest/reference/supported-models/)** — Browse the curated catalog of verified models that run across all Windows ML EPs.
- **[Execution provider compatibility](https://microsoft.github.io/winml-cli/latest/reference/supported-models/#execution-provider-compatibility)** — Browse the compatible EP alias and device combinations.


---

## 🔒 Privacy & Telemetry

Official WinML CLI releases can collect **unlinked pseudonymized** usage telemetry
to help improve the product. Telemetry is classified as **Optional**. A one-time
prompt on your first run asks for consent (default: accept — press **Enter** to
enable, type `n` to decline).

**Control** — edit `%USERPROFILE%\.winml\config.json`:

- Set `telemetry.consent` to `"disabled"` to opt out
- Set `telemetry.consent` to `"enabled"` to opt in
- Delete the file to re-show the first-run prompt on the next run

See [docs/Privacy.md](docs/Privacy.md) for the full list of what is and is not
collected, event schemas, CI auto-disable behavior, and storage locations.

---

## 🤝 Contributing

We welcome contributions! Please see the [contribution guidelines](CONTRIBUTING.md).

For feature requests or bug reports, please file a [GitHub Issue](https://github.com/microsoft/winml-cli/issues).

### Code of Conduct

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

### License

This project is licensed under the [MIT License](LICENSE.txt).

### Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft
sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
