# Agent brief: What the GPU actually runs

- **Lesson id:** 01-metal-shaders
- **Goal:** Explain why Metal and Apple silicon execution are the bottom limit for Core AI, then grow the map from a Metal op to a graph, `.aimodel`, and app.
- **Prerequisites:** Read the course `SKILL.md`; know the original course's pipeline and conversion lessons.
- **Inputs:** Apple-silicon Mac context, Core AI graph, `clothing.aimodel`, and custom Metal concepts.
- **Outputs/artifacts:** Human explanation of GPU, CPU, and Neural Engine roles; progressive HTML `.flow` diagrams; illustrative custom-kernel registration sketch.
- **Concrete steps:**
  1. Start with a typed Metal operation and explain buffers, shape, and element type.
  2. Add a graph layer, then `clothing.aimodel`, then the Core AI app in separate diagrams.
  3. Explain `TorchMetalKernel` and `register_custom_kernels` as custom Metal ideas that can change by release.
  4. State that custom kernels register before `add_exported_program`, without inventing exact signatures.
  5. Link to the original conversion and pipeline lessons.
- **Constraints:** Mac and Apple silicon only; no CUDA; no fake APIs; mention Apple Core AI, `coreai-torch`, and [WWDC25 session 325](https://developer.apple.com/videos/play/wwdc2025/325/) conceptually; no Mermaid, quizzes, or em dashes.
- **Acceptance checks:** Four progressive `.flow` diagrams exist; the custom sketch is labelled illustrative; hardware roles and lower-layer needs are clear; Agent brief link is present on the human page.
- **Human lesson:** [01-metal-shaders.html](01-metal-shaders.html)

## 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, and use CPU as the fallback. Do not add CUDA.

## Key concepts

- A Metal op needs buffers, thread layout, and a typed shape. It cannot take a vague image.
- Core AI turns supported graph ops into work on CPU, GPU, or Neural Engine.
- Custom Metal kernels are optional and must be registered before conversion.
- The portable file wraps a graph the runtime can lower to Apple silicon. No CUDA-only paths.

## Takeaways

- A graph is only useful when its steps can become real hardware work.
- `clothing.aimodel` with `main`, `image`, and `logits` is a contract around ops the chip can run.
- Later lessons stay accurate only if they keep known ops, clear shapes, and Apple-silicon compilation.