# ml-explore/mlx-swift-lm architecture

> Architecture diagram of the GitHub repository ml-explore/mlx-swift-lm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ml-explore/mlx-swift-lm
- Repository: https://github.com/ml-explore/mlx-swift-lm

## Overview

MLX Swift LM is a Swift library for loading and running LLMs and vision-language models on MLX, with related embedding, reranking, fine-tuning, guided-generation, and Foundation Models integrations. The principal workflow configures a model, loads its weights and tokenizer into a container, then generates conversational responses. README capabilities inform branches whose implementation wiring was not sampled; those branches are shown at API level rather than with inferred internal call chains.

Main entry points: [`Libraries/MLXLMCommon/ModelContainer.swift`](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ModelContainer.swift) (Model container), [`Libraries/MLXLMCommon/Load.swift`](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Load.swift) (Model loading), [`Libraries/MLXLLM/LLMModelFactory.swift`](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLLM/LLMModelFactory.swift) (LLM registry), [`Libraries/MLXLMCommon/GenerationComponents.swift`](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/GenerationComponents.swift) (Generation runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Model runtime"]
  node_config["Model configuration"]
  node_factory["LLM registry"]
  node_loader["Model loading<br/>[Load.swift]"]
  node_downloader["Downloader integration<br/>[Downloader.swift]"]
  node_tokenizer["Tokenizer integration"]
  node_container["Model container"]
  node_llm["LLM architectures"]
  node_chat["Chat session<br/>[ChatSession.swift]"]
  node_generation["Generation runtime"]
end

subgraph group_integrations["User-facing integrations"]
  node_guided["Constrained generation"]
  node_foundation["Foundation Models bridge"]
  node_toolrouting["Tool-call routing"]
end

subgraph group_specialized["Specialized models"]
  node_vlm["Vision architectures"]
  node_embeddings["Embedding models"]
  node_reranker["Reranking<br/>[Reranker.swift]"]
  node_finetuning["LoRA and training<br/>[LoraTrain.swift]"]
end

node_developer(("Application developer"))
node_huggingface["Hugging Face services"]

node_developer -->|"selects"| node_config
node_developer -->|"loads model"| node_factory
node_factory -->|"uses"| node_config
node_factory -->|"creates model"| node_loader
node_loader -->|"loads weights"| node_downloader
node_loader -->|"loads tokenizer"| node_tokenizer
node_loader -->|"builds"| node_container
node_container -->|"hosts"| node_llm
node_container -->|"hosts"| node_vlm
node_developer -->|"starts conversation"| node_chat
node_chat -->|"generates with"| node_container
node_container -->|"runs inference"| node_generation
node_developer -->|"constrains output"| node_guided
node_guided -->|"constrains"| node_generation
node_developer -->|"uses bridge"| node_foundation
node_foundation -->|"adapts model"| node_container
node_generation -->|"routes tool output"| node_toolrouting
node_developer -->|"creates embeddings"| node_embeddings
node_developer -->|"reranks"| node_reranker
node_developer -->|"fine-tunes"| node_finetuning
node_huggingface -.->|"provides weights"| node_downloader
node_huggingface -.->|"provides tokenizer"| node_tokenizer

click node_config "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ModelConfiguration.swift"
click node_factory "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLLM/LLMModelFactory.swift"
click node_loader "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Load.swift"
click node_downloader "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Downloader.swift"
click node_tokenizer "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/TokenizerLoader.swift"
click node_container "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ModelContainer.swift"
click node_llm "https://github.com/ml-explore/mlx-swift-lm/tree/main/Libraries/MLXLLM/Models"
click node_vlm "https://github.com/ml-explore/mlx-swift-lm/tree/main/Libraries/MLXVLM/Models"
click node_chat "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ChatSession.swift"
click node_generation "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/GenerationComponents.swift"
click node_guided "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXGuidedGeneration/GuidedGenerationLoop.swift"
click node_foundation "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXFoundationModels/MLXLanguageModel.swift"
click node_toolrouting "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Tool/ToolCallProcessor.swift"
click node_embeddings "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXEmbedders/EmbeddingModel.swift"
click node_reranker "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXEmbedders/Reranker.swift"
click node_finetuning "https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLLM/LoraTrain.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_factory,node_loader,node_downloader,node_tokenizer,node_container,node_llm,node_chat,node_generation toneBlue
class node_guided,node_foundation,node_toolrouting toneAmber
class node_vlm,node_embeddings,node_reranker,node_finetuning toneMint
class node_developer,node_huggingface toneIndigo
```

## Components

### Model runtime

- [Model configuration](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ModelConfiguration.swift): `Libraries/MLXLMCommon/ModelConfiguration.swift`
- [LLM registry](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLLM/LLMModelFactory.swift): `Libraries/MLXLLM/LLMModelFactory.swift`
- [Model loading](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Load.swift): `Libraries/MLXLMCommon/Load.swift`
- [Downloader integration](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Downloader.swift): `Libraries/MLXLMCommon/Downloader.swift`
- [Tokenizer integration](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/TokenizerLoader.swift): `Libraries/MLXLMCommon/TokenizerLoader.swift`
- [Model container](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ModelContainer.swift): `Libraries/MLXLMCommon/ModelContainer.swift`
- [LLM architectures](https://github.com/ml-explore/mlx-swift-lm/tree/main/Libraries/MLXLLM/Models): `Libraries/MLXLLM/Models`
- [Chat session](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/ChatSession.swift): `Libraries/MLXLMCommon/ChatSession.swift`
- [Generation runtime](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/GenerationComponents.swift): `Libraries/MLXLMCommon/GenerationComponents.swift`

### User-facing integrations

- [Constrained generation](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXGuidedGeneration/GuidedGenerationLoop.swift): `Libraries/MLXGuidedGeneration/GuidedGenerationLoop.swift`
- [Foundation Models bridge](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXFoundationModels/MLXLanguageModel.swift): `Libraries/MLXFoundationModels/MLXLanguageModel.swift`
- [Tool-call routing](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLMCommon/Tool/ToolCallProcessor.swift): `Libraries/MLXLMCommon/Tool/ToolCallProcessor.swift`

### Specialized models

- [Vision architectures](https://github.com/ml-explore/mlx-swift-lm/tree/main/Libraries/MLXVLM/Models): `Libraries/MLXVLM/Models`
- [Embedding models](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXEmbedders/EmbeddingModel.swift): `Libraries/MLXEmbedders/EmbeddingModel.swift`
- [Reranking](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXEmbedders/Reranker.swift): `Libraries/MLXEmbedders/Reranker.swift`
- [LoRA and training](https://github.com/ml-explore/mlx-swift-lm/blob/main/Libraries/MLXLLM/LoraTrain.swift): `Libraries/MLXLLM/LoraTrain.swift`

### Other components

- **Application developer**
- **Hugging Face services**

## Connections

- Application developer → Model configuration: selects
- Application developer → LLM registry: loads model
- LLM registry → Model configuration: uses
- LLM registry → Model loading: creates model
- Model loading → Downloader integration: loads weights
- Model loading → Tokenizer integration: loads tokenizer
- Model loading → Model container: builds
- Model container → LLM architectures: hosts
- Model container → Vision architectures: hosts
- Application developer → Chat session: starts conversation
- Chat session → Model container: generates with
- Model container → Generation runtime: runs inference
- Application developer → Constrained generation: constrains output
- Constrained generation → Generation runtime: constrains
- Application developer → Foundation Models bridge: uses bridge
- Foundation Models bridge → Model container: adapts model
- Generation runtime → Tool-call routing: routes tool output
- Application developer → Embedding models: creates embeddings
- Application developer → Reranking: reranks
- Application developer → LoRA and training: fine-tunes
- Hugging Face services → Downloader integration: provides weights
- Hugging Face services → Tokenizer integration: provides tokenizer