# ml-explore/mlx-swift-examples architecture

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

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

## Overview

This repository is a collection of MLX Swift example applications, command-line tools, numerical-computing demos, and two reusable model libraries—not one end-user product. Its principal workflow is prompt-to-result: an app or CLI accepts a prompt, obtains a model, runs generation, and presents or saves output. Other documented workflows cover fine-tuning, MNIST training, embedding search, and numerical simulations. The source index and excerpts support only selected internal connections; unsampled branches are shown as capabilities without guessed call chains.

Main entry points: [`Tools/image-tool/ImageTool.swift`](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/image-tool/ImageTool.swift) (Image CLI), [`Applications/LLMEval/ViewModels/LLMEvaluator.swift`](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/ViewModels/LLMEvaluator.swift) (LLM Evaluation), [`Applications/MLXChatExample/Services/MLXService.swift`](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Services/MLXService.swift) (LLM/VLM Chat), [`Applications/StableDiffusionExample/ContentView.swift`](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/StableDiffusionExample/ContentView.swift) (Image Generation App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["ML Applications"]
  node_llmbasic["Minimal LLM Chat<br/>[ChatModel.swift]"]
  node_lleval["LLM Evaluation<br/>[LLMEvaluator.swift]"]
  node_evalprompts["Preset Prompts"]
  node_evaltools["Tool Execution<br/>[ToolExecutor.swift]"]
  node_mlxchat["LLM/VLM Chat<br/>[MLXService.swift]"]
  node_chatmodel["Chat Model Types<br/>[LMModel.swift]"]
  node_chatmessages["Chat Messages<br/>[Message.swift]"]
  node_loraapp["LoRA Fine-Tuning<br/>[ContentView.swift]"]
  node_sdapp["Image Generation App<br/>[ContentView.swift]"]
  node_mnistapp["MNIST Trainer<br/>[ContentView.swift]"]
  node_mnistprediction["MNIST Prediction"]
end

subgraph group_libs["Reusable Libraries"]
  node_sdlib["Stable Diffusion"]
  node_sdimage["Image Conversion<br/>[Image.swift]"]
  node_mnistlib["MNIST Library<br/>[MNIST.swift]"]
end

subgraph group_tools["Command-Line Tools"]
  node_llmcli["LLM CLI<br/>[LLMTool.swift]"]
  node_llmchat["CLI Chat Generation<br/>[Chat.swift]"]
  node_llmlist["Model Listing<br/>[ListCommands.swift]"]
  node_imagecli["Image CLI<br/>[ImageTool.swift]"]
  node_mnistcli["MNIST CLI<br/>[MNISTTool.swift]"]
  node_embedcommand["Embedder Commands"]
  node_embedruntime["Embedding Runtime"]
  node_embedsearch["Vector Search"]
  node_embedvectors["Vector Operations"]
end

subgraph group_numerical["Numerical Demos"]
  node_curvefit["Curve Fitting<br/>[Gradient.swift]"]
  node_heat["Heat Transfer<br/>[Jacobi+MLX.swift]"]
  node_heatrender["Heat Renderer<br/>[Renderer.swift]"]
  node_mandelbrot["Mandelbrot Renderer"]
end

node_user(("User"))

node_user -->|"prompts"| node_llmbasic
node_user -->|"evaluates prompt"| node_lleval
node_user -->|"chats"| node_mlxchat
node_user -->|"fine-tunes"| node_loraapp
node_user -->|"requests image"| node_sdapp
node_user -->|"trains model"| node_mnistapp
node_user -->|"runs generation"| node_llmcli
node_user -->|"requests image"| node_imagecli
node_user -->|"trains model"| node_mnistcli
node_user -.->|"runs commands"| node_embedcommand
node_user -->|"views fitting"| node_curvefit
node_user -->|"views simulation"| node_heat
node_user -->|"views rendering"| node_mandelbrot
node_lleval -->|"uses presets"| node_evalprompts
node_lleval -->|"executes tools"| node_evaltools
node_mlxchat -->|"loads configuration"| node_chatmodel
node_mlxchat -->|"generates from"| node_chatmessages
node_sdapp -->|"loads and generates"| node_sdlib
node_sdapp -->|"uses image type"| node_sdimage
node_mnistapp -->|"presents prediction"| node_mnistprediction
node_llmcli -->|"registers commands"| node_llmlist
node_llmchat -.->|"references image type"| node_imagecli
node_imagecli -->|"generates images"| node_sdlib
node_imagecli -->|"uses image type"| node_sdimage
node_embedcommand -.->|"uses runtime"| node_embedruntime
node_embedsearch -->|"implements command"| node_embedcommand
node_embedsearch -->|"scores vectors"| node_embedvectors
node_curvefit -.->|"shows fit"| node_user

click node_llmbasic "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMBasic/ChatModel.swift"
click node_lleval "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/ViewModels/LLMEvaluator.swift"
click node_evalprompts "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/Models/PresetPrompts.swift"
click node_evaltools "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/Services/ToolExecutor.swift"
click node_mlxchat "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Services/MLXService.swift"
click node_chatmodel "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Models/LMModel.swift"
click node_chatmessages "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Models/Message.swift"
click node_loraapp "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LoRATrainingExample/ContentView.swift"
click node_sdapp "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/StableDiffusionExample/ContentView.swift"
click node_mnistapp "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MNISTTrainer/ContentView.swift"
click node_mnistprediction "https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MNISTTrainer/PredictionView.swift"
click node_sdlib "https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/StableDiffusion/StableDiffusion.swift"
click node_sdimage "https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/StableDiffusion/Image.swift"
click node_mnistlib "https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/MLXMNIST/MNIST.swift"
click node_llmcli "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/LLMTool.swift"
click node_llmchat "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/Chat.swift"
click node_llmlist "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/ListCommands.swift"
click node_imagecli "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/image-tool/ImageTool.swift"
click node_mnistcli "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/mnist-tool/MNISTTool.swift"
click node_embedcommand "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/EmbedderCommand.swift"
click node_embedruntime "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/EmbedderRuntime%2BEmbedding.swift"
click node_embedsearch "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/SearchCommand.swift"
click node_embedvectors "https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/VectorOperations.swift"
click node_curvefit "https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/CurveFit/Algorithm/Gradient.swift"
click node_heat "https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/HeatTransfer/Algorithm/Jacobi%2BMLX.swift"
click node_heatrender "https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/HeatTransfer/Renderer.swift"
click node_mandelbrot "https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/Mandelbrot/Algorithm/Mandelbrot%2BMLX.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_llmbasic,node_lleval,node_evalprompts,node_evaltools,node_mlxchat,node_chatmodel,node_chatmessages,node_loraapp,node_sdapp,node_mnistapp,node_mnistprediction,node_user toneBlue
class node_sdlib,node_sdimage,node_mnistlib toneAmber
class node_llmcli,node_llmchat,node_llmlist,node_imagecli,node_mnistcli,node_embedcommand,node_embedruntime,node_embedsearch,node_embedvectors toneMint
class node_curvefit,node_heat,node_heatrender,node_mandelbrot toneRose
```

## Components

### ML Applications

- [Minimal LLM Chat](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMBasic/ChatModel.swift): `Applications/LLMBasic/ChatModel.swift`
- [LLM Evaluation](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/ViewModels/LLMEvaluator.swift): `Applications/LLMEval/ViewModels/LLMEvaluator.swift`
- [Preset Prompts](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/Models/PresetPrompts.swift): `Applications/LLMEval/Models/PresetPrompts.swift`
- [Tool Execution](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LLMEval/Services/ToolExecutor.swift): `Applications/LLMEval/Services/ToolExecutor.swift`
- [LLM/VLM Chat](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Services/MLXService.swift): `Applications/MLXChatExample/Services/MLXService.swift`
- [Chat Model Types](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Models/LMModel.swift): `Applications/MLXChatExample/Models/LMModel.swift`
- [Chat Messages](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MLXChatExample/Models/Message.swift): `Applications/MLXChatExample/Models/Message.swift`
- [LoRA Fine-Tuning](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/LoRATrainingExample/ContentView.swift): `Applications/LoRATrainingExample/ContentView.swift`
- [Image Generation App](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/StableDiffusionExample/ContentView.swift): `Applications/StableDiffusionExample/ContentView.swift`
- [MNIST Trainer](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MNISTTrainer/ContentView.swift): `Applications/MNISTTrainer/ContentView.swift`
- [MNIST Prediction](https://github.com/ml-explore/mlx-swift-examples/blob/main/Applications/MNISTTrainer/PredictionView.swift): `Applications/MNISTTrainer/PredictionView.swift`

### Reusable Libraries

- [Stable Diffusion](https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/StableDiffusion/StableDiffusion.swift): `Libraries/StableDiffusion/StableDiffusion.swift`
- [Image Conversion](https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/StableDiffusion/Image.swift): `Libraries/StableDiffusion/Image.swift`
- [MNIST Library](https://github.com/ml-explore/mlx-swift-examples/blob/main/Libraries/MLXMNIST/MNIST.swift): `Libraries/MLXMNIST/MNIST.swift`

### Command-Line Tools

- [LLM CLI](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/LLMTool.swift): `Tools/llm-tool/LLMTool.swift`
- [CLI Chat Generation](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/Chat.swift): `Tools/llm-tool/Chat.swift`
- [Model Listing](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/llm-tool/ListCommands.swift): `Tools/llm-tool/ListCommands.swift`
- [Image CLI](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/image-tool/ImageTool.swift): `Tools/image-tool/ImageTool.swift`
- [MNIST CLI](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/mnist-tool/MNISTTool.swift): `Tools/mnist-tool/MNISTTool.swift`
- [Embedder Commands](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/EmbedderCommand.swift): `Tools/embedder-tool/EmbedderCommand.swift`
- [Embedding Runtime](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/EmbedderRuntime%2BEmbedding.swift): `Tools/embedder-tool/EmbedderRuntime+Embedding.swift`
- [Vector Search](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/SearchCommand.swift): `Tools/embedder-tool/SearchCommand.swift`
- [Vector Operations](https://github.com/ml-explore/mlx-swift-examples/blob/main/Tools/embedder-tool/VectorOperations.swift): `Tools/embedder-tool/VectorOperations.swift`

### Numerical Demos

- [Curve Fitting](https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/CurveFit/Algorithm/Gradient.swift): `Numerical/CurveFit/Algorithm/Gradient.swift`
- [Heat Transfer](https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/HeatTransfer/Algorithm/Jacobi%2BMLX.swift): `Numerical/HeatTransfer/Algorithm/Jacobi+MLX.swift`
- [Heat Renderer](https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/HeatTransfer/Renderer.swift): `Numerical/HeatTransfer/Renderer.swift`
- [Mandelbrot Renderer](https://github.com/ml-explore/mlx-swift-examples/blob/main/Numerical/Mandelbrot/Algorithm/Mandelbrot%2BMLX.swift): `Numerical/Mandelbrot/Algorithm/Mandelbrot+MLX.swift`

### Other components

- **User**

## Connections

- User → Minimal LLM Chat: prompts (evidence: `README.md`)
- User → LLM Evaluation: evaluates prompt (evidence: `README.md`)
- User → LLM/VLM Chat: chats (evidence: `README.md`)
- User → LoRA Fine-Tuning: fine-tunes (evidence: `README.md`)
- User → Image Generation App: requests image (evidence: `README.md`)
- User → MNIST Trainer: trains model (evidence: `README.md`)
- User → LLM CLI: runs generation (evidence: `README.md`)
- User → Image CLI: requests image (evidence: `README.md`)
- User → MNIST CLI: trains model (evidence: `README.md`)
- User → Embedder Commands: runs commands
- User → Curve Fitting: views fitting (evidence: `README.md`)
- User → Heat Transfer: views simulation (evidence: `README.md`)
- User → Mandelbrot Renderer: views rendering (evidence: `README.md`)
- LLM Evaluation → Preset Prompts: uses presets (evidence: `Applications/LLMEval/ViewModels/LLMEvaluator.swift`)
- LLM Evaluation → Tool Execution: executes tools (evidence: `Applications/LLMEval/ViewModels/LLMEvaluator.swift`)
- LLM/VLM Chat → Chat Model Types: loads configuration (evidence: `Applications/MLXChatExample/Services/MLXService.swift`)
- LLM/VLM Chat → Chat Messages: generates from (evidence: `Applications/MLXChatExample/Services/MLXService.swift`)
- Image Generation App → Stable Diffusion: loads and generates (evidence: `Applications/StableDiffusionExample/ContentView.swift`)
- Image Generation App → Image Conversion: uses image type (evidence: `Applications/StableDiffusionExample/ContentView.swift`)
- MNIST Trainer → MNIST Prediction: presents prediction (evidence: `Applications/MNISTTrainer/ContentView.swift`)
- LLM CLI → Model Listing: registers commands (evidence: `Tools/llm-tool/LLMTool.swift`)
- CLI Chat Generation → Image CLI: references image type
- Image CLI → Stable Diffusion: generates images (evidence: `Tools/image-tool/ImageTool.swift`)
- Image CLI → Image Conversion: uses image type (evidence: `Tools/image-tool/ImageTool.swift`)
- Embedder Commands → Embedding Runtime: uses runtime
- Vector Search → Embedder Commands: implements command (evidence: `Tools/embedder-tool/SearchCommand.swift`)
- Vector Search → Vector Operations: scores vectors (evidence: `Tools/embedder-tool/SearchCommand.swift`)
- Curve Fitting → User: shows fit
