Installation

Butter ships as a SwiftPM package with three products:

Product	Use it for
Butter	The main inference library — Model.load(...), generate(...), KV cache, sampling, tokenizer integration.
IronSwift	Lower-level: the pre-compiled kernels.metallib, PSO cache, and generated typed kernel wrappers. Pulled in transitively by Butter; depend on it directly only when authoring new layers against raw kernels.
butter	Executable target — the butter --model <id> --prompt "..." CLI.

SwiftPM Package.swift

.package(url: "https://github.com/waffuruai/butter", from: "0.1.0"),

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "Butter", package: "Butter"),
    ]
)

Xcode

1. Project → Package Dependencies → +
2. Enter https://github.com/waffuruai/butter and pick a version / branch.
3. Add the Butter product to your target.

Apple’s Adding package dependencies to your app docs cover the UI flow.

Transitive dependencies

Butter itself pulls in:

• swift-huggingface (≥ 0.9.0) — HF Hub snapshot download / cache.
• swift-transformers (≥ 1.3.0) — AutoTokenizer.from(modelFolder:).
• swift-argument-parser (≥ 1.5.0) — only the butter executable target depends on this.

You don’t add these yourself unless you want to use them directly in your own code.

Platform requirements

• macOS 14.0+ / iOS 17+ / visionOS 1+
• Apple Silicon (M-series). Butter is Metal-only in the inference hot path; CPU fallback is for small auxiliary tensors only.

The HuggingFace cache lives at ~/.cache/huggingface/hub/ — same path Python’s huggingface_hub uses, so model snapshots are shared between languages.

Local checkout (contributors)

Cloning the repo to hack on Butter itself requires the sibling iron checkout (the Rust DSL that compiles kernels) and Cargo:

git clone https://github.com/waffuruai/butter
git clone https://github.com/waffuruai/iron
cd Butter
make setup-dev
make install-hooks   # pre-commit / commit-msg / pre-push

make setup-dev (wrapping ./scripts/setup-dev.sh) verifies Xcode CLI tools + xcrun metal + Swift + Cargo + swift-format (auto-installed via Homebrew if missing), resolves SPM deps, and runs the first build to populate kernels.metallib. make install-hooks points git at the in-tree hook scripts — see developing.md for what each one runs.

End users adding Butter as a SwiftPM dependency do not need Cargo, the iron repo, or the hooks — they consume the pre-built metallib bundled into the package.

After install

• Quick start — generate text in 5 lines.
• Models — supported architectures and quantizations.
• KV cache — what’s shipped today.