# Convert ClothingCNN with coreai-torch

- **Lesson ID:** 03
- **Goal:** Export the trained CPU model, decompose the graph, and save `clothing.aimodel` with stable Core AI names.
- **Human lesson:** [03-convert-with-coreai-torch.html](03-convert-with-coreai-torch.html)

## Prerequisites

- `clothing.pt` and the exact `ClothingCNN` class from lesson 02.
- A compatible installed `coreai-torch` package and its `TorchConverter` APIs.

## Inputs, outputs, and artifacts

- **Inputs:** CPU-loaded `ClothingCNN`; zero example tensor `[1,1,28,28]` float32.
- **Outputs:** Exported/decomposed program; converter model with function `main`.
- **Artifacts:** `clothing.aimodel` and the conversion script/log.

## Agent build steps

1. Recreate `ClothingCNN`, load `clothing.pt` with `map_location="cpu"`, and call `eval()`.
2. Create `torch.zeros(1, 1, 28, 28, dtype=torch.float32)` and run `torch.export.export(model, args=(example,))`.
3. Call `ep.run_decompositions(get_decomp_table())` before conversion. Do not skip or reorder this step.
4. Create `TorchConverter().add_exported_program(ep, input_names=["image"], output_names=["logits"])`.
5. Call `to_coreai()`, then `optimize()`, then `save_asset("clothing.aimodel")`.
6. Inspect the file in Xcode's model viewer. If the installed package has a runtime smoke test, run a zero image through it.

## Constraints

Conversion runs on CPU and needs no CUDA. Contract is float32 NCHW `[1,1,28,28]` → `[1,10]`, input name `image`, output name `logits`. Use Core AI, not Core ML. Keep decomposition before `to_coreai()` and keep the ten-class order.

## Key concepts

- Load `ClothingCNN` and `clothing.pt` on CPU, then `torch.export.export` with a float32 `[1, 1, 28, 28]` example.
- Run `run_decompositions(get_decomp_table())` before `TorchConverter` and `to_coreai()`.
- Name the tensors `image` and `logits`. The exported function is `main`.
- Install the Metal Toolchain in Xcode before you build the app target.

## Takeaways

- `clothing.aimodel` is the portable Core AI file you add to the project.
- Check function name, tensor names, shapes, and types in the Xcode model viewer.
- Python conversion can succeed while the app build fails if the Metal Toolchain is missing.

## Acceptance checks

- `clothing.aimodel` exists and is non-empty.
- The model viewer shows `main`, `image`, `logits`, expected shapes, and float32 types.
- A zero-image or equivalent smoke test completes if the installed release supports it.
- Install the Xcode Metal Toolchain before moving to [Xcode integration](04-xcode-and-core-ai.llms.md).

## Environment setup

Use macOS with Python 3.11+ and `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
mkdir -p clothing-coreai && cd clothing-coreai
uv init --python 3.11
uv venv
uv add torch torchvision coreai-torch
uv run python -c "import torch, torchvision; print(torch.__version__, torchvision.__version__); print('MPS:', torch.backends.mps.is_available())"
uv run python train.py
```

Run lesson scripts with `uv run`. Prefer MPS on Apple silicon. Use CPU if MPS is missing. Do not add CUDA.