# huggingface/swift-transformers architecture

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

- Interactive diagram: https://gitdiagram.com/huggingface/swift-transformers
- Repository: https://github.com/huggingface/swift-transformers

## Overview

swift-transformers is a Swift library for using language models in apps, especially tokenization, Hugging Face Hub downloads, and CoreML inference and generation. A typical workflow loads tokenizer assets (from the Hub or local files), formats and tokenizes text or chat messages, runs a model to generate token IDs, then decodes them. The graph preserves the documented Hub, tokenizer, model, and generation capabilities. Some internal wiring is based on README and package-level evidence because the sampled source excerpts are partial.

Main entry points: [`Sources/Tokenizers/Tokenizer.swift`](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Tokenizer.swift) (AutoTokenizer), [`Sources/Models/LanguageModel.swift`](https://github.com/huggingface/swift-transformers/blob/main/Sources/Models/LanguageModel.swift) (LanguageModel), [`Sources/Generation/Generation.swift`](https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/Generation.swift) (Generation loop), [`Sources/Tokenizers/PreTokenizer.swift`](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/PreTokenizer.swift) (Pre-tokenization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hub["Hub access"]
  node_hub["Hub API<br/>[HubApi.swift]"]
  node_hubfacade["Hub downloads<br/>[Hub.swift]"]
  node_hubconfig["Hub config<br/>[Config.swift]"]
end

subgraph group_tokenizers["Tokenization"]
  node_tokenizer["AutoTokenizer<br/>[Tokenizer.swift]"]
  node_pretoken["Pre-tokenization<br/>[PreTokenizer.swift]"]
  node_tokenizerimpl["Tokenizer algorithms"]
  node_textprocessing["Text processing<br/>[Normalizer.swift]"]
  node_chat["Chat templates<br/>[Tokenizer.swift]"]
end

subgraph group_models["Models"]
  node_model["LanguageModel"]
  node_weights["Weight loading<br/>[Weights.swift]"]
end

subgraph group_generation["Generation"]
  node_generation["Generation loop<br/>[Generation.swift]"]
  node_processors["Logits processors"]
  node_decoders["Token selection<br/>[Decoders.swift]"]
end

node_app(("Swift app"))
node_hubservice["Hugging Face Hub"]
node_coreml["CoreML runtime"]

node_app -->|"loads tokenizer"| node_tokenizer
node_tokenizer -->|"requests assets"| node_hubconfig
node_hubconfig -->|"resolves files"| node_hubfacade
node_hubfacade -->|"downloads files"| node_hub
node_hub -->|"requests files"| node_hubservice
node_tokenizer -->|"splits text"| node_pretoken
node_pretoken -->|"normalizes text"| node_textprocessing
node_pretoken -->|"feeds segments"| node_tokenizerimpl
node_app -->|"formats messages"| node_chat
node_chat -->|"encodes template"| node_tokenizer
node_app -->|"loads model"| node_model
node_app -->|"loads weights"| node_weights
node_model -->|"runs inference"| node_coreml
node_app -->|"requests generation"| node_model
node_model -->|"delegates generation"| node_generation
node_generation -->|"requests logits"| node_model
node_generation -->|"processes logits"| node_processors
node_generation -->|"selects token"| node_decoders
node_app -->|"decodes output"| node_tokenizer

click node_hub "https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/HubApi.swift"
click node_hubfacade "https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/Hub.swift"
click node_hubconfig "https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/Config.swift"
click node_tokenizer "https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Tokenizer.swift"
click node_pretoken "https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/PreTokenizer.swift"
click node_tokenizerimpl "https://github.com/huggingface/swift-transformers/tree/main/Sources/Tokenizers"
click node_textprocessing "https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Normalizer.swift"
click node_chat "https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Tokenizer.swift"
click node_model "https://github.com/huggingface/swift-transformers/blob/main/Sources/Models/LanguageModel.swift"
click node_weights "https://github.com/huggingface/swift-transformers/blob/main/Sources/Models/Weights.swift"
click node_generation "https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/Generation.swift"
click node_processors "https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/LogitsWarper/LogitsProcessor.swift"
click node_decoders "https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/Decoders.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_hub,node_hubfacade,node_hubconfig toneBlue
class node_tokenizer,node_pretoken,node_tokenizerimpl,node_textprocessing,node_chat toneAmber
class node_model,node_weights toneMint
class node_generation,node_processors,node_decoders toneRose
class node_app,node_hubservice,node_coreml toneIndigo
```

## Components

### Hub access

- [Hub API](https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/HubApi.swift): `Sources/Hub/HubApi.swift`
- [Hub downloads](https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/Hub.swift): `Sources/Hub/Hub.swift`
- [Hub config](https://github.com/huggingface/swift-transformers/blob/main/Sources/Hub/Config.swift): `Sources/Hub/Config.swift`

### Tokenization

- [AutoTokenizer](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Tokenizer.swift): `Sources/Tokenizers/Tokenizer.swift`
- [Pre-tokenization](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/PreTokenizer.swift): `Sources/Tokenizers/PreTokenizer.swift`
- [Tokenizer algorithms](https://github.com/huggingface/swift-transformers/tree/main/Sources/Tokenizers): `Sources/Tokenizers`
- [Text processing](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Normalizer.swift): `Sources/Tokenizers/Normalizer.swift`
- [Chat templates](https://github.com/huggingface/swift-transformers/blob/main/Sources/Tokenizers/Tokenizer.swift): `Sources/Tokenizers/Tokenizer.swift`

### Models

- [LanguageModel](https://github.com/huggingface/swift-transformers/blob/main/Sources/Models/LanguageModel.swift): `Sources/Models/LanguageModel.swift`
- [Weight loading](https://github.com/huggingface/swift-transformers/blob/main/Sources/Models/Weights.swift): `Sources/Models/Weights.swift`

### Generation

- [Generation loop](https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/Generation.swift): `Sources/Generation/Generation.swift`
- [Logits processors](https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/LogitsWarper/LogitsProcessor.swift): `Sources/Generation/LogitsWarper/LogitsProcessor.swift`
- [Token selection](https://github.com/huggingface/swift-transformers/blob/main/Sources/Generation/Decoders.swift): `Sources/Generation/Decoders.swift`

### Other components

- **Swift app**
- **Hugging Face Hub**
- **CoreML runtime**

## Connections

- Swift app → AutoTokenizer: loads tokenizer
- AutoTokenizer → Hub config: requests assets
- Hub config → Hub downloads: resolves files
- Hub downloads → Hub API: downloads files
- Hub API → Hugging Face Hub: requests files
- AutoTokenizer → Pre-tokenization: splits text
- Pre-tokenization → Text processing: normalizes text
- Pre-tokenization → Tokenizer algorithms: feeds segments
- Swift app → Chat templates: formats messages
- Chat templates → AutoTokenizer: encodes template
- Swift app → LanguageModel: loads model
- Swift app → Weight loading: loads weights
- LanguageModel → CoreML runtime: runs inference
- Swift app → LanguageModel: requests generation
- LanguageModel → Generation loop: delegates generation
- Generation loop → LanguageModel: requests logits
- Generation loop → Logits processors: processes logits
- Generation loop → Token selection: selects token
- Swift app → AutoTokenizer: decodes output