---
name: MLX Swift in production
description: >-
  Teach an Edge FDE to register a custom MLX Swift architecture (Gemma 4
  style), load weights safely, and gate Metal inference on scenePhase so
  generation does not die when the app backgrounds.
---
# MLX Swift in production

Use this course when an MLX Swift demo works in Xcode and then fails in a real session. Two common causes: the type registry does not know the family (Gemma 4 and other new `model_type` values), and Metal work keeps running after the scene leaves the foreground.

Core AI is the official App Store path for a baked custom neural model. This course is for the case where you already chose MLX Swift as the runtime and you need that path to stay up.

## End-to-end agent recipe

1. Start with [lesson 01](01-xcode-is-not-production.llms.md). A Run in Xcode keeps the scene active. Production users background the app. MLX uses Metal. iOS can take the GPU or jetsam the process. Draw two or three progressive Mermaid diagrams of active generate, then background, then Metal death.
2. Use [lesson 02](02-set-up-xcode-and-mlx-swift.llms.md) for environment setup before any generate call. Xcode 27. iOS 27 or macOS 27. Apple silicon Mac. Add `mlx-swift` and `mlx-swift-lm`. Be honest: Mac can run the GPU; the iOS Simulator is for compile and UI; a real device is the iOS Metal path.
3. Use [lesson 03](03-register-custom-architecture.llms.md) for registration. The factory keys on `config.json` `model_type`, not the Hugging Face id. Check `contains`, then `registerModelType` if missing, then `loadContainer`. Confirm names in the pinned mlx-swift-lm docs. Do not invent APIs.
4. Use [lesson 04](04-gate-on-scene-phase.llms.md) to observe `scenePhase`, cancel generation when the phase is not `.active`, and resume only in the foreground. Never leave Metal work running when inactive.
5. Use [lesson 05](05-production-checklist.llms.md) for memory, cancellation, logging, and the related-course list.
6. Keep these links exact: [Core AI vs Core ML vs MLX](../core-ai-vs-core-ml-vs-mlx/), [Route work to the right Apple model](../on-device-model-router/), [Stream tokens and measure speed](../on-device-streaming-metrics/), [PyTorch to Core AI in Xcode](../pytorch-core-ai-xcode/), and [The agent harness (and how to improve it)](../agent-harness-improve-loop/).
7. Use the human HTML pages for the reader. Use the `.llms.md` briefs for agent steps and acceptance checks.

## Constraints

- Plain spoken English for a non-native reader.
- Literal sentences. No flourish, no quizzes.
- Do not use em dashes.
- Brand Edge FDE only. Do not name a course author.
- Small progressive Mermaid diagrams. Do not build one mega diagram.
- Do not invent WWDC sessions. Do not use YouTube for Apple talks. Link `developer.apple.com` only for real API docs you mention, such as `scenePhase`.
- Teach public MLX Swift APIs. If a name varies by package release, teach the concept and tell the reader to verify in the docs they pinned. Do not invent factory methods.
- Environment setup in lesson 02, before the first runnable Swift example in lesson 03.

## Key concepts

- MLX Swift inference runs on Metal. A backgrounded scene can lose the GPU or the process.
- The loader looks up `model_type` in a type registry. Gemma 4 and other new families fail if that type is missing.
- Register the architecture, then load weights. Do not invent API names. Confirm them in the mlx-swift-lm docs you pinned.
- Observe `scenePhase`. Cancel generation when the phase is not `.active`. Resume only in the foreground.

## Takeaways

- You can tell a demo from a shippable MLX Swift path.
- You can set up Xcode 27 and the MLX Swift packages without treating Simulator as a device GPU.
- You can register a missing architecture and load weights without guessing factory names.
- You can stop Metal work when the app backgrounds and start it again only when the scene is active.

## Acceptance checks

- Every human lesson HTML has **Key concepts** and **Takeaways** sections before lesson-nav. The course home has the same two headings for the whole course.
- Five human lessons exist with the requested basenames.
- Five matching `.llms.md` briefs exist and link to their human HTML pages.
- Every human lesson has its Agent brief link.
- The course index lists all five lessons, the course SKILL.md, and all five briefs.
- Lesson 01 has two or three progressive Mermaid diagrams. Lesson 03 has a progressive registry diagram.
- Lesson 02 has an Environment setup section and language-tagged bash before any generate example.
- Lessons 03 and 04 have language-tagged Swift. Lesson 02 may have Swift package sketches after setup.
- There is no em dash, no quiz, no paywall, and no invented WWDC session.

## Environment setup

Lesson 02 needs Xcode 27 on an Apple silicon Mac. Add the `mlx-swift` and `mlx-swift-lm` packages. Create an iOS 27 or macOS 27 SwiftUI app target. Confirm Metal on a Mac or a real device. Do not treat the iOS Simulator as the production GPU.