---
title: "Register a custom architecture"
lesson_id: "03"
---

# Register a custom architecture

- **Lesson ID:** 03
- **Goal:** Teach that load keys on `model_type`. Check the registry, register if missing, then load weights. Verify names against pinned docs.
- **Human lesson:** [03-register-custom-architecture.html](03-register-custom-architecture.html)

## Prerequisites

- Lesson 02 environment: Xcode 27, mlx-swift, mlx-swift-lm, empty app builds.
- A `config.json` the reader can open.

## Inputs, outputs, and artifacts

- **Inputs:** A Hub or local model directory with `config.json` and safetensors.
- **Outputs:** A registered type and a `ModelContainer` load that no longer fails on unknown architecture.
- **Artifacts:** Three progressive Mermaid diagrams and a language-tagged Swift sketch.

## Agent build steps

1. Say the key is `config.json` `model_type`, not the Hugging Face id.
2. Say `LLMModelFactory` asks `LLMTypeRegistry` / `ModelTypeRegistry` to construct the class.
3. Name Gemma 4 as the example. Current pins may already list `gemma4`, `gemma4_text`, and `gemma4_unified`. Older pins and other subtypes may not.
4. Teach `contains`, then `registerModelType`, then `loadContainer`. Mark the sketch as something to verify. The registry may be an actor.
5. If the family is absent from MLXLLM, port a `Module` + `LLMModel` class using the public porting guide. Do not invent APIs.
6. Link the porting docs and [Route work to the right Apple model](../on-device-model-router/).

## Constraints

Keep the language simple, friendly, and literal. No quizzes, no em dashes, no invented WWDC sessions. Brand Edge FDE only. Do not invent factory methods. If a name may differ by release, say so and point at mlx-swift-lm DocC.

## Key concepts

- The factory keys on `config.json` `model_type`, not the Hugging Face id.
- A missing type throws unsupported model type. Gemma 4 and newer strings need a registry entry.
- `contains` then `registerModelType` then `loadContainer` is the production order.
- API names vary by release. Verify against the mlx-swift-lm docs you pinned.

## Takeaways

- Do not debug Metal until the architecture constructs.
- Port a class only when MLXLLM does not already ship that type.
- Keep the register call next to app startup, before the first load.

## Acceptance checks

- `model_type` vs repo id is the main claim.
- Progressive Mermaid diagrams and a Swift sketch are present.
- Verify-against-docs is explicit. No invented APIs.
- [ ] Proceed to [lesson 04 brief](04-gate-on-scene-phase.llms.md).