Integrate CGIR workflow (export, perf, eval) into winml-cli

docs/commands/build.md

@@ -22,6 +22,7 @@ $ winml build [options]
 |---|---|---|---|---|
 | `--config` | `-c` | path | `None` | `WinMLBuildConfig` JSON file, generated by `winml config`. If omitted, config is auto-generated from `-m`. |
 | `--model` | `-m` | string | `None` | Hugging Face model ID or path to an existing `.onnx` file. |
+| `--backend` | | choice | `None` | Backend for auto-generated config. `cgc` selects CGC preparation and CGIR conversion; it cannot be combined with `--ep`. |
 | `--export-type` | | choice | `generic` | Output selector: `generic` builds the stock single/composite ONNX model; `optimized` builds the family's registered runtime-optimized recipe (today the onnxruntime-genai CPU/NPU bundle) for the **resolved** `--ep`/`--device`. `optimized` fails fast if the family has no recipe or the resolved target is not one the recipe supports. |
 | `--output-dir` | `-o` | path | `None` | Directory for all build artifacts. Mutually exclusive with `--use-cache`. |
 | `--use-cache/--no-use-cache` | | flag | `false` | Store artifacts in the winml-cli global cache (`~/.cache/winml/`). Mutually exclusive with `--output-dir`. |
@@ -57,6 +58,38 @@ single-pass build. Individual stages can be suppressed with `--no-quant`,
 !!! tip "Reproducible CI/CD builds"
     The config file is a portable, self-contained pipeline specification. Check it into source control and invoke `winml build -c config.json` in CI to produce identical artifacts without manual flag management. Set `"auto": false` in the config to disable the autoconf discovery loop for fully deterministic output.
 
+## Optional ONNX-to-MLIR conversion
+
+Use `winml build -m model.onnx --backend cgc -o output` to auto-generate
+the CGC configuration and build MLIR directly. Use `--ep winmlcg` instead
+to prepare ONNX for WinMLCG EP without converting it to MLIR. These two
+target selectors cannot be combined.
+
+Add a `convert` section to the build config to export the final ONNX model as CGIR:
+
+```json
+{
+  "compile": null,
+  "convert": {
+    "target": "cgir",
+    "options": {
+      "external_weights": true
+    }
+  }
+}
+```
+
+This fragment supplements the existing build config. Export, optimization,
+quantization, and compilation retain their existing configuration controls;
+conversion does not disable compilation automatically. Set `compile` to `null`
+when compilation is not wanted.
+
+The CLI retains `model.onnx` and writes `model.mlir` with the exporter sidecars.
+Conversion also runs when the ONNX build is reused. Omit `convert` or set it to
+`null` to preserve the ordinary ONNX build. This stage runs for single-model and
+composite CLI builds. Module-mode arrays and optimized GenAI bundles accept the
+configuration but do not execute the conversion stage.
+
 ## Genai bundles for decoder LLMs (CPU/NPU)
 
 For a registered decoder-LLM family (currently **Qwen3**), `--export-type

docs/commands/config.md

@@ -29,6 +29,7 @@ $ winml config [options]
 | `--device` | `-d` | `auto\|npu\|gpu\|cpu` | `auto` | Target device. Affects the generated quantization and compilation sub-configs. `auto` leaves those sections unchanged from the kit defaults. |
 | `--ep` | | `TEXT` | *(none)* | Force a specific execution provider (`qnn`, `dml`, `migraphx`, `tensorrt`, `vitisai`, `openvino`, `cpu`). Overrides the device-to-provider mapping. When used without `--device`, the device is inferred from the EP. |
 | `--precision` | `-p` | `TEXT` | `auto` | Target precision: `auto`, `fp32`, `fp16`, `int8`, `int16`, or a mixed format such as `w8a16`. `auto` selects the precision based on the chosen device. |
+| `--backend` | | `ort\|cgc` | *(none)* | `cgc` enables CGC compatibility rules, default FP16 conversion, no compilation, and a CGIR convert stage. Cannot combine `cgc` with `--ep`. Omission or `ort` preserves existing behavior. |
 | `--output` | `-o` | `PATH` | *(stdout)* | Write the generated JSON to this file instead of printing to stdout. |
 | `--library` | | `TEXT` | `transformers` | Source library for `TasksManager` task lookup. Defaults to `transformers`; set to `diffusers` or another Optimum-supported library when needed. |
 | `--quant/--no-quant` | | flag | `true` | Include quantization in the generated config (use `--no-quant` to omit it and set `quant` to `null`). |
@@ -39,6 +40,37 @@ $ winml config [options]
 
 `winml config` queries the HuggingFace `TasksManager` to auto-detect the model's task, class, and ONNX export specification. For known model types it looks up a per-model kit in `MODEL_BUILD_CONFIGS` and uses that as a starting point, layering in your device, precision, and override file on top. When `-m` points to an existing `.onnx` file, the export stage is skipped by setting `export` to `null` in the output. The result is a complete `WinMLBuildConfig` JSON printed to stdout or written to a file, ready to be passed to `winml build`.
 
+## CGC configuration
+
+The config generators use CGC stage settings for `--backend cgc` or
+`--ep winmlcg`: `auto: false`, all registered CGC compatibility rules in
+`optim`, `optim.ort_graph_optimization: false` to skip ORT graph optimization,
+default `quant.mode: "fp16"`, and `compile: null`.
+Only `--backend cgc` automatically adds `convert.target: "cgir"`.
+Choose either `--backend cgc` or `--ep winmlcg`; combining `--backend cgc`
+with any `--ep` is a usage error.
+Explicit `--precision` values are preserved instead of forcing FP16.
+Existing QDQ ONNX inputs and `--no-quant` use `quant: null`.
+Loader and PyTorch-to-ONNX export settings are unchanged; ONNX input retains
+`export: null`.
+
+The compatibility preset includes opset deduplication, scalar initializer Cast
+folding, empty Resize input omission, Tile repeats materialization, supported
+Resize coordinate conversion, cubic-to-linear Resize approximation, identity
+GatherND reshaping, PRelu decomposition, and static DFT decomposition.
+**Cubic-to-linear Resize is lossy and may reduce accuracy.** The optimizer logs
+a warning when it applies this rule. Review accuracy after building; disable
+`optim.approximate_cubic_resize_with_linear` in the generated JSON when needed.
+No `--runtime` option is needed for config generation: Runtime CGC and the
+WinMLCG EP share this offline compatibility and FP16 preparation.
+
+```bash
+winml config -m microsoft/resnet-50 --backend cgc -o config.json
+```
+
+Module and composite configurations receive the same settings. Module-mode build
+currently accepts but does not execute the convert stage.
+
 ## Examples
 
 Generate a config for ResNet-50 with all auto-detected settings:

docs/commands/eval.md

@@ -1,6 +1,6 @@
 # winml eval
 
-> Evaluate ONNX or native Hugging Face PyTorch model accuracy on a standard dataset.
+> Evaluate ONNX, CGC MLIR, or native Hugging Face PyTorch models.
 
 ## When to use this
 
@@ -16,8 +16,8 @@ $ winml eval [options]
 
 | Flag | Short | Type | Default | Description |
 |---|---|---|---|---|
-| `--model` | `-m` | `TEXT` | — | HuggingFace model ID, or path to a local `.onnx` file. Required (unless `--model-id` is provided directly). |
-| `--model-id` | | `TEXT` | — | HuggingFace model ID used for preprocessor and config resolution when `-m` points to an `.onnx` file. Required when `-m` is an ONNX file. |
+| `--model` | `-m` | `TEXT` | — | HuggingFace model ID, or path to a local `.onnx` or `.mlir` file. Required (unless `--model-id` is provided directly). |
+| `--model-id` | | `TEXT` | — | HuggingFace model ID used for preprocessor and config resolution when `-m` points to an ONNX or MLIR file. |
 | `--task` | | `TEXT` | auto-detected | Task name (e.g., `image-classification`). Auto-detected from `--model-id` when not provided. Required when `-m` is an ONNX file and the task cannot be inferred. |
 | `--precision` | | `TEXT` | `auto` | Precision used when building the model from a HuggingFace ID. One of `auto`, `fp32`, `fp16`, `int8`, `int16`, or a mixed `w{x}a{y}` spec (e.g., `w8a16`). `fp16`/`fp32` skip quantization. **Ignored** when `-m` is a pre-built `.onnx` file — the precision is already baked in. |
 | `--device` | | choice | `auto` | Target device. Choices: `auto`, `npu`, `gpu`, `cpu`. `auto` selects the best available device. Combined with `--precision`, this drives the build when `-m` is a HuggingFace ID. |
@@ -27,7 +27,7 @@ $ winml eval [options]
 | `--input-specs` | | `PATH` | — | JSON input tensor specs to merge into the Hugging Face export config. Symbolic string dimensions infer dynamic axes. **Ignored for pre-built `.onnx` inputs**. |
 | `--export-config` | | `PATH` | — | JSON ONNX export config overrides (opset version, constant folding, etc.) to merge into the Hugging Face export config. **Ignored for pre-built `.onnx` inputs**. |
 | `--dynamic-axes` | | `PATH` | — | JSON dynamic axes mapping for Hugging Face ONNX export, for example `{"input_ids": {"0": "batch", "1": "sequence"}}`. **Ignored for pre-built `.onnx` inputs**. |
-| `--runtime` | | `winml-ort\|pytorch` | `winml-ort` | Evaluation runtime. `winml-ort` exports Hugging Face checkpoints to ONNX; `pytorch` evaluates the original checkpoint and supports `auto`, `cpu`, or CUDA-backed `gpu` devices. |
+| `--runtime` | | `winml-ort\|winml-runtime\|pytorch` | `winml-ort` | Evaluation runtime. `winml-ort` exports Hugging Face checkpoints to ONNX; `winml-runtime` loads pre-built CGC MLIR; `pytorch` evaluates the original checkpoint and supports `auto`, `cpu`, or CUDA-backed `gpu` devices. |
 | `--dataset` | | `TEXT` | task default | HuggingFace dataset path (e.g., `imagenet-1k`, `nyu-mll/glue`). If omitted, a default dataset is selected based on the task. |
 | `--dataset-name` | | `TEXT` | — | Dataset configuration name for multi-config datasets. |
 | `--dataset-revision` | | `TEXT` | — | Git revision (branch, tag, or commit) of the dataset to load. Use `refs/convert/parquet` for HF datasets that are only served via the parquet mirror. |
@@ -41,16 +41,16 @@ $ winml eval [options]
 | `--label-mapping` | | `PATH` | — | Path to a JSON file mapping dataset label names to the integer class IDs the model emits: `{"label_name": id}`. |
 | `--output` | `-o` | `PATH` | — | Output JSON file path for the evaluation results. |
 | `--schema` | | flag | `false` | Print the expected dataset schema for the given `--task` and exit. Does not run evaluation. |
-| `--mode` | | `onnx\|compare` | `onnx` | Evaluation mode. `onnx` evaluates the ONNX candidate on a dataset. `compare` runs the ONNX candidate and a reference on identical random inputs and reports per-tensor similarity metrics — no dataset required. The reference is the HuggingFace model from `--model-id` by default, or a second ONNX file when `--reference` is given. |
+| `--mode` | | `onnx\|compare` | `onnx` | Evaluation mode. `onnx` evaluates the candidate model on a dataset. `compare` runs the candidate and a reference on identical random inputs and reports per-tensor similarity metrics — no dataset required. The reference is the HuggingFace model from `--model-id` by default, or an ONNX file when `--reference` is given. |
 | `--input-data` | | `PATH` | — | Path to a `.npz` file of real input tensors to compare with instead of randomly generated ones (used with `--mode compare`). Keys must match the candidate model's input names. The **leading axis of each array is the sample axis**, so an archive shaped `(N, ...)` yields `N` samples (mean/std/min/max are computed across them); all inputs must share the same `N`. Each run is shaped to the candidate's batch size — a dynamic batch runs one row per sample, a static batch `B` chunks the axis into `N // B` batches (trailing rows are dropped with a warning). Note this differs from `winml perf --input-data`, which runs the **whole archive as a single batch**. |
-| `--reference` | | `TEXT` | — | Reference `.onnx` file to compare the candidate against (used with `--mode compare`). Compares two ONNX models on identical random inputs; `--model-id` and `--task` are not required in this mode. |
+| `--reference` | | `TEXT` | — | Reference `.onnx` file to compare against (used with `--mode compare`). `--model-id` and `--task` are not required in this mode. |
 | `--reference-device` | | `cpu\|gpu\|npu\|auto` | `cpu` | Device used for the reference ONNX model. Only valid with `--reference`. |
 | `--reference-device-luid` | | `TEXT` | — | Select a physical adapter for the reference ONNX model using its LUID from `winml sys`. Only valid with `--reference`. |
 | `--reference-ep` | | `TEXT` | — | Explicit execution provider used for the reference ONNX model, for example `dml`. Only valid with `--reference`. |
 
 ## How it works
 
-`winml eval` loads the model and runs the evaluation pipeline via the internal `evaluate` function, then pulls the requested number of samples from a HuggingFace dataset. By default, Hugging Face model IDs and local checkpoints use the `winml-ort` runtime: they are exported to ONNX and evaluated through WinML. With `--runtime pytorch`, the task-resolved PyTorch model and stored dtype are preserved and the same dataset preprocessing, evaluator, and metrics run directly against that model. PyTorch `auto` selects CUDA when available and otherwise CPU; `gpu` requires CUDA. The JSON report identifies the effective runtime as `winml-ort` or `pytorch`.
+`winml eval` loads the model and runs the evaluation pipeline via the internal `evaluate` function, then pulls the requested number of samples from a HuggingFace dataset. By default, Hugging Face model IDs and local checkpoints use the `winml-ort` runtime: they are exported to ONNX and evaluated through WinML. Pre-built CGC MLIR artifacts use `winml-runtime`. With `--runtime pytorch`, the task-resolved PyTorch model and stored dtype are preserved and the same dataset preprocessing, evaluator, and metrics run directly against that model. PyTorch `auto` selects CUDA when available and otherwise CPU; `gpu` requires CUDA. The JSON report identifies the effective runtime as `winml-ort`, `winml-runtime`, or `pytorch`.
 
 Python callers can pass an existing model directly with `evaluate(config, pytorch_model=model)`. An explicit `config.model_id` selects the tokenizer or processor; otherwise evaluation infers it from `model.config._name_or_path` and reports an error if neither source is available.