swift-transformers

swift-transformers is a collection of utilities to help adopt language models in Swift apps.

Those familiar with the transformers Python library will find a familiar yet idiomatic Swift API.

Rationale & Overview

Check out our v1.0 release post and our original announcement for more context on why we built this library.

Examples

The most commonly used modules from swift-transformers are Tokenizers and Hub, which allow fast tokenization and model downloads from the Hugging Face Hub.

Tokenizing text + chat templating

Tokenizing text should feel very familiar to those who have used the Python transformers library:

let tokenizer = try await AutoTokenizer.from(pretrained: "deepseek-ai/DeepSeek-R1-Distill-Qwen-7B")
let messages = [["role": "user", "content": "Describe the Swift programming language."]]
let encoded = try tokenizer.applyChatTemplate(messages: messages)
let decoded = tokenizer.decode(tokens: encoded)

Tool calling

swift-transformers natively supports formatting inputs for tool calling, allowing for complex interactions with language models:

let tokenizer = try await AutoTokenizer.from(pretrained: "mlx-community/Qwen2.5-7B-Instruct-4bit")

let weatherTool = [
    "type": "function",
    "function": [
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": [
            "type": "object",
            "properties": ["location": ["type": "string", "description": "City and state"]],
            "required": ["location"]
        ]
    ]
]

let tokens = try tokenizer.applyChatTemplate(
    messages: [["role": "user", "content": "What's the weather in Paris?"]],
    tools: [weatherTool]
)

Hub downloads

Downloading models to a user device fast and reliably is a core requirement of on-device ML. swift-transformers provides a simple API to download models from the Hugging Face Hub, with progress reporting, flaky connection handling, and more:

let repo = Hub.Repo(id: "mlx-community/Qwen2.5-0.5B-Instruct-2bit-mlx")
let modelDirectory: URL = try await Hub.snapshot(
    from: repo,
    matching: ["config.json", "*.safetensors"],
    progressHandler: { progress in
        print("Download progress: \(progress.fractionCompleted * 100)%")
    }
)
print("Files downloaded to: \(modelDirectory.path)")

CoreML Integration

The Models and Generation modules provide handy utilities when working with language models in CoreML. Check out our example converting and running Mistral 7B using CoreML here.

The modernization of Core ML and corresponding examples were primarily contributed by @joshnewnham, @1duo, @alejandro-isaza, @aseemw. Thank you 🙏

Offline CoreML tokenizers

When you bundle a compiled CoreML model and tokenizer files with your app, you can skip any network requests by injecting the tokenizer when constructing LanguageModel:

let compiledURL: URL = ... // path to .mlmodelc
let tokenizerFolder: URL = ... // folder containing tokenizer_config.json and tokenizer.json

// Construct the tokenizer from local files (inside an async context)
let tokenizer = try await AutoTokenizer.from(modelFolder: tokenizerFolder)
let model = try LanguageModel.loadCompiled(
    url: compiledURL,
    tokenizer: tokenizer
)

Make sure the tokenizer assets come from the same Hugging Face repo as the original checkpoint or are compatible with the model you use. For the Mistral example in Examples/Mistral7B/, you can fetch the tokenizer like this:

huggingface-cli download \
  mistralai/Mistral-7B-Instruct-v0.3 \
  tokenizer.json tokenizer_config.json \
  --local-dir Examples/Mistral7B/local-tokenizer

If the repo is gated, authenticate with huggingface-cli login first. Both initializers reuse the tokenizer you pass in and never reach out to the Hugging Face Hub.

Usage via SwiftPM

To use swift-transformers with SwiftPM, you can add this to your Package.swift:

dependencies: [
    .package(url: "https://github.com/huggingface/swift-transformers", from: "1.3.0")
]

And then, add the Transformers library as a dependency to your target:

targets: [
    .target(
        name: "YourTargetName",
        dependencies: [
            .product(name: "Transformers", package: "swift-transformers")
        ]
    )
]

Optional Xet trait

swift-transformers includes an Xet package trait that enables fast, parallel downloads from the Hugging Face Hub via swift-xet. Because Xet introduces additional transitive dependencies (including AsyncHTTPClient), it is opt-in.

On Swift 6.1+, enable it in your Package.swift:

dependencies: [
    .package(
        url: "https://github.com/huggingface/swift-transformers",
        from: "1.3.0",
        traits: ["Xet"]
    )
]

Or from the command line:

swift build --traits Xet
swift test --traits Xet

When the trait is not enabled, Hub downloads use the default URLSession-based transport.

On Swift versions earlier than 6.1, package traits are unavailable and Xet transport cannot be enabled.

[!NOTE] Xcode doesn't yet provide a built-in way to declare package dependencies with traits. As a workaround, you can create an internal Swift package that re-exports swift-transformers with the Xet trait enabled, then add that package as a local dependency in your Xcode project.

Projects that use swift-transformers ❤️

• WhisperKit: A Swift Package for state-of-the-art speech-to-text systems from Argmax
• MLX Swift Examples: A Swift Package for integrating MLX models in Swift apps.

Using swift-transformers in your project? Let us know and we'll add you to the list!

Other Tools

• swift-chat, a simple app demonstrating how to use this package.
• exporters, a Core ML conversion package for transformers models, based on Apple's coremltools.

Contributing

Swift Transformers is a community project and we welcome contributions. Please check out Issues tagged with good first issue if you are looking for a place to start!

Before submitting a pull request, please ensure your code:

• Passes the test suite (swift test)
• Passes linting checks (swift format lint --recursive .)

To format your code, run swift format -i --recursive ..

Offline tokenizer tests

TokenizersTests uses in-memory configurations and bundled fixtures. Put tests that download models or other Hub files in TokenizersIntegrationTests, along with any reference fixtures they need. swift test runs both targets; integration tests require network access.

Run just the offline tokenizer tests with:

swift test --filter TokenizersTests

Linux CI runs the offline tests with and without the Xet trait. It skips HubTests and TokenizersIntegrationTests because of the existing FoundationNetworking teardown race. To reproduce the Linux selection locally using Docker:

docker run --rm -t \
  -v "$PWD":/src -w /src \
  -v swift-transformers-tests-spm-cache:/root/.cache/org.swift.swiftpm \
  swift:6.2.3 \
  swift test --scratch-path .build/linux \
    --skip HubTests --skip TokenizersIntegrationTests

Benchmarks

See Benchmarks for standalone tokenizer benchmarks and commands to record and compare performance baselines. The existing Tests/Benchmarks suite covers internal hot paths and input scaling; run it with RUN_BENCHMARKS=1 swift test --filter Benchmarks. It prints timing statistics and will be folded into the standalone package in a follow-up.

License

Apache 2.