ManifoldKit

ManifoldKit

[](https://github.com/ManifoldKit/ManifoldKit/actions/workflows/ci.yml) [](https://github.com/ManifoldKit/ManifoldKit/releases/latest) [](LICENSE) [](https://swift.org) [](#requirements) [](#install) [](https://docs.manifoldkit.com/documentation/manifoldkit/)

The only open-source Swift package that bundles UI, turn-loop runtime, persistence, and multi-backend inference into one drop-in chat product for Apple platforms.

New here? Start with [Why ManifoldKit — and how it's built to last](docs/WHY-MANIFOLDKIT.md) for the honest "what it solves and why trust it" narrative, or jump to the [docs index](docs/README.md) for the full guided path from install to first token. Prefer rendered API reference? The full DocC documentation site ties every module's reference together under one navigable root.

ManifoldKit is a full-stack, multi-backend AI chat framework for iOS 18+ / macOS 15+. Import one umbrella package and you get a SwiftUI ChatView, the ConversationRuntime turn loop (send / regenerate / edit / cancel / branch), SwiftData persistence, and the in-core inference backends (Apple Foundation Models, OpenAI, Anthropic, Ollama / LAN) — all behind one InferenceBackend protocol. Model browser / download UI is the opt-in ManifoldUIModelManagement product; on-device MLX and llama.cpp ship as the manifold-mlx / manifold-llama companion packages. Competitors ship a single layer; ManifoldKit ships the assembled product and the wiring between layers. It survives real failures — streaming retries, latest-wins model handoff, memory admission, certificate pinning, and a mock backend for app-level testing. See [docs/RELIABILITY.md](docs/RELIABILITY.md) for the source-backed contract, or [docs/POSITIONING.md](docs/POSITIONING.md) for the full "why ManifoldKit vs. the field" rationale.

Hello World

Add ManifoldKit (core), then drop this into your app entry point. ManifoldKit.quickStart() builds the SwiftData container and registers the compiled-in backends. On devices with an available Foundation Model, a stored local model that a registered backend can load, or a saved endpoint it selects that model; otherwise, configure a backend or use the optional GGUF starter below. Errors surface as [ManifoldKitError](Sources/ManifoldModelCatalog/ManifoldKitError.swift).

.package(url: "https://github.com/ManifoldKit/ManifoldKit.git", from: "0.75.0"), // x-release-please-version
// target dependencies: "ManifoldKit"

import SwiftUI
import SwiftData
import ManifoldKit

@main
struct MyChatApp: App {
    @State private var result: QuickStartResult?
    @State private var error: ManifoldKitError?
    @State private var showModelManagement = false

    var body: some Scene {
        WindowGroup {
            if let result {
                ChatView(showModelManagement: $showModelManagement)
                    .environment(result.viewModel)
                    .modelContainer(result.bootstrap.modelContainer)
            } else if let error {
                ContentUnavailableView("Failed to start", systemImage: "exclamationmark.triangle", description: Text(error.errorDescription ?? ""))
            } else {
                ProgressView().task {
                    do {
                        result = try await ManifoldKit.quickStart()
                    }
                    catch let e as ManifoldKitError { error = e }
                    catch { self.error = .from(error) }
                }
            }
        }
    }
}

Optional: on-device GGUF starter

Want the on-device GGUF starter model instead of relying on Foundation Models / a manually-loaded backend? Add the manifold-llama companion package and pass its registrar — otherwise quickStart logs and skips the GGUF seed, because no registered backend can load it:

```swift,no-build:pulls in the manifold-llama companion package, which is a separate SwiftPM dependency the snippet harness (core-only) does not resolve // + .package(url: "https://github.com/ManifoldKit/manifold-llama.git", from: "0.2.14") // + target dependency: .product(name: "ManifoldLlama", package: "manifold-llama") import ManifoldLlama

result = try await ManifoldKit.quickStart( backends: [LlamaBackends.self], seed: .recommendedSmallModel() )

#### One-shot response

Already have a `QuickStartResult` with a loaded model and just want one reply as a `String`? `respond(to:)` sends the message, drives the turn, and returns the assistant's text — no `inputText`/observation plumbing:

```swift
import ManifoldKit

func oneShot(using kit: QuickStartResult) async throws -> String {
    return try await kit.respond(to: "Explain monads in one sentence.")
}

> About seed: — with the manifold-llama companion's LlamaBackends registrar, .recommendedSmallModel() downloads Qwen3-0.6B (~484 MB) in the background before returning, so the composer is generating the moment the view appears. Without that registrar the GGUF seed is skipped. The download is also skipped when a model is already available (Foundation on iOS/macOS 26+, or a local model on disk), and it accepts a { progress in … } closure for a progress indicator. > > No starter download? quickStart registers the backends but loads none when no Foundation Model, compatible stored local model, or saved endpoint is available, so on first run the composer reads "No model loaded" and the empty-state Select Model button only flips showModelManagement — nothing is presented until you attach a sheet to that binding. Fastest route: present ModelManagementSheet (from the opt-in ManifoldUIModelManagement module) with .sheet(isPresented: $showModelManagement), or pass the LlamaBackends registrar with seed:. Step-by-step: [First-launch backend selection](docs/QUICKSTART.md#first-launch-backend-selection).

Value-typed front door: LLM

Want the LLM.swift feel — construct a value, call .respond(to:)? LLM(from:template:backends:) wraps the same quickStart plumbing in a value type. backends: is a required parameter (no default — explicit registrars over implicit ones, see [docs/API-DESIGN.md](docs/API-DESIGN.md)); pass a registrar that can load the seed type:

```swift,no-build:uses the manifold-llama companion package, which is not linked by the core-only snippet harness import ManifoldKit import ManifoldLlama

func twoLine() async throws -> String { let llm = try await LLM( from: .recommendedSmallModel(), backends: [LlamaBackends.self] ) return try await llm.respond(to: "Explain monads in one sentence.") }

> **Local models need a companion registrar.** `ManifoldKit.defaultBackendRegistrars` covers cloud (Ollama / OpenAI / Anthropic) and Apple Foundation Models. For an on-device model, add the `manifold-llama` (GGUF) or `manifold-mlx` package and pass its registrar instead — `backends: [LlamaBackends.self]` — plus the matching `import`. Pass an optional `template: ChatTemplate` to override formatting for built-in (enum) templates.

See [docs/QUICKSTART.md](docs/QUICKSTART.md) for backend selection and configuration.
Building a multi-session SwiftUI app with a sidebar, persisted chats, and relaunch restore? See [docs/SWIFTUI-MULTI-SESSION.md](docs/SWIFTUI-MULTI-SESSION.md) — the canonical end-to-end guide.
Building a CLI, server, or non-SwiftUI consumer? See [docs/QUICKSTART-CLI.md](docs/QUICKSTART-CLI.md) — compile-tested Foundation Models, local GGUF, and Ollama / OpenAI examples.
Running ManifoldKit as a standalone OpenAI-compatible server (for Cursor, Continue, or any OpenAI SDK)? Install via `brew tap manifoldkit/manifoldkit https://github.com/ManifoldKit/ManifoldKit.git && brew install manifold-server` and see [docs/QUICKSTART-SERVER.md](docs/QUICKSTART-SERVER.md).
Want the inference layer with a fully custom SwiftUI UI (no `ChatView`)? See [docs/QUICKSTART-BRING-YOUR-OWN-UI.md](docs/QUICKSTART-BRING-YOUR-OWN-UI.md).
Registering tools the model can call? See [docs/QUICKSTART-TOOLS.md](docs/QUICKSTART-TOOLS.md) — `ToolRegistry`, the local-model tool ceiling, approval gates, and streaming results.
Exposing an `AppIntent` to the model? See [docs/QUICKSTART-APPINTENTS.md](docs/QUICKSTART-APPINTENTS.md).
Full runnable: [`Example/Examples/MinimalExample`](Example/Examples/MinimalExample).

## Where each backend lives

As of v0.48 the heavy on-device backends ship as **companion packages** so a
core-only app never resolves llama.cpp or mlx-swift (SwiftPM traits gate
link, not fetch — see
[docs/TRAIT-COSTS.md](docs/TRAIT-COSTS.md#faq-why-not-keep-the-glue-in-core-and-only-externalize-the-engines)).
Module names are stable — only the `.package(…)` line differs. Migrating from
a trait-based 0.47 setup? **[docs/MIGRATION-0.48.md](docs/MIGRATION-0.48.md)**
is the error-message-indexed guide.

| You want | Module to import | Package |
|---|---|---|
| MLX on-device inference (+ image gen) | `ManifoldMLX` | [`ManifoldKit/manifold-mlx`](https://github.com/ManifoldKit/manifold-mlx) |
| llama.cpp / GGUF on-device inference | `ManifoldLlama` | [`ManifoldKit/manifold-llama`](https://github.com/ManifoldKit/manifold-llama) |
| Apple Foundation Models (iOS/macOS 26+) | `ManifoldKit` umbrella (or `ManifoldFoundation`) | ManifoldKit (core) |
| OpenAI / Anthropic / LM Studio / custom endpoints | `ManifoldKit` umbrella (or `ManifoldCloudSaaS`) | ManifoldKit (core) |
| Ollama / LAN | `ManifoldKit` umbrella (or `ManifoldOllama`) | ManifoldKit (core) |
| xAI, Groq, Mistral, OpenRouter — incl. Gemini models via OpenRouter (OpenAI-compatible endpoint) | `ManifoldKit` umbrella (or `ManifoldCloudSaaS`), `APIProvider.custom` + `OpenAIBackend` | ManifoldKit (core) |
| MCP client / host | `ManifoldMCP` / `ManifoldMCPHost` | ManifoldKit (core) |

Companion backends register through `quickStart(backends: [MLXBackends.self, LlamaBackends.self])` (or `MLXBackends.register(with:)` on a hand-assembled service). The `manifold-mlx` / `manifold-llama` packages tag 0.1.0 alongside the core v0.48.0 release.

Building a new backend companion package? See [docs/COMPANION-BACKENDS.md](docs/COMPANION-BACKENDS.md) for the product/contract-adoption/release-lifecycle guide, and [docs/HARDWARE-TOOLCHAIN.md](docs/HARDWARE-TOOLCHAIN.md) for the cross-repo hardware/CI constraints.

## Why ManifoldKit

**Full-stack altitude.** Import one umbrella package and ship a multi-backend chat app: SwiftUI `ChatView`, the `ConversationRuntime` turn loop, SwiftData persistence, and the in-core backends — already wired together. Model browser UI is the opt-in `ManifoldUIModelManagement` product; MLX / llama.cpp are companion packages. Most alternatives hand you one layer (a UI kit, an engine wrapper, or a thin cloud client) and leave the rest as an exercise. Here the integration is the product.

**Backend portability.** MLX, llama.cpp/GGUF, Apple Foundation Models, and cloud (OpenAI Chat + Responses, Anthropic, Ollama, LAN, and any OpenAI-compatible endpoint — xAI, Groq, Mistral, OpenRouter via `APIProvider.custom`, including Gemini models through OpenRouter) all sit behind one `InferenceBackend` protocol. Streaming, tool calling, thinking/reasoning tokens, RAG, and structured output behave identically across every backend, so swapping engines is a config change, not a rewrite. See [How ManifoldKit compares to AnyLanguageModel](#how-manifoldkit-compares-to-anylanguagemodel).

**n-1 OS reach — everything above the model layer.** At WWDC 2026 Apple opened the Foundation Models framework to any LLM provider via the `LanguageModel` protocol, with first-party Claude (`anthropics/ClaudeForFoundationModels`, beta) and Gemini (via Firebase, preview) packages arriving on top. That validates the multi-backend idea — and commoditizes it: model *access* is becoming a platform primitive. But it all lands on the newest OS only — Foundation Models itself is iOS 26+ / macOS 26+, and the opened provider layer is iOS 27+ (in beta now) — while ManifoldKit already serves the iOS 18 / macOS 15 installed base those APIs can't reach, wrapping Foundation Models as just one more backend behind `InferenceBackend`. ManifoldKit's value was never the abstraction; it's everything above the model layer: the turn loop, persistence, MCP client+server, tool approval, and RAG. The companion-package split means one codebase yields either an App-Store-lean build with no heavy ML dependencies at all (core only — just don't add the companion packages) or the full local + cloud + RAG + voice stack, and the pre-wired stub traits (`SystemAIProviderExtension`, `CoreAI`) mean adopting Apple's new provider protocols is one more backend, not a migration. See [AGENTS.md → Platform policy](AGENTS.md#platform-policy).

**Reliability and security as product.** TLS pinning, SSRF and DNS-rebind guards, a throwing Keychain, a documented [threat model](docs/THREAT_MODEL.md), a fuzz harness, 6,500+ tests, capability-routed structured output, human-in-the-loop tool approval (`ToolApprovalGate`), and cost/metrics observability ship in the box. These are the things that go wrong between the demo and App Store review — see [docs/RELIABILITY.md](docs/RELIABILITY.md) for the implementation-backed guarantees.

ManifoldKit is **decomposable, not monolithic**: 28 libraries across a layered module graph. Take just the engine ([CLI / server path](docs/QUICKSTART-CLI.md)), just the UI (bring-your-own-runtime), or the whole stack — the umbrella is a convenience, not a requirement.

### Drop in `ChatView`, or compose the primitives

`ChatView` is a complete reference integration, not the only door in. `ManifoldUI` ships as composable pieces you can assemble into a custom layout while still driving the same `ChatViewModel` / `ConversationRuntime` (`SessionListView` and `SessionManagerViewModel` are also in the [Key Types](#key-types) table below):

- **Message rendering** — `MessageBubbleView`, the `MessageBubbleStyle` protocol (with `PlainMessageBubbleStyle`, `IMessageMessageBubbleStyle`, `CardMessageBubbleStyle` built in), `StreamingCursorView`, `ToolInvocationView`, `CitationsView`.
- **Input** — `ChatInputBar`, `VisionInputButton` (cross-platform), `PhotoAttachmentButton` (**iOS only** — prefer `VisionInputButton` for a codebase that also targets macOS).
- **Session chrome** — `SessionListView`, `SessionRowView`, backed by `SessionManagerViewModel`; `ContextIndicatorView`, `MemoryIndicatorView`, `ModelLoadingIndicatorView`, `TypingIndicatorView`.
- **Pickers & sheets** — `PersonaPickerView`, `SamplerPresetPickerView`, `VoicePickerView`, `ChatExportSheet`, `SessionExportSheet`.

Bring your own layout and swap in only the pieces you need — a custom message list with `MessageBubbleView` and a bespoke input bar is a valid integration, not an unsupported one.

## What's already in the box

Table-stakes capabilities that ship today (verified in source):

- **Token streaming** across every backend (`GenerationStream` / `GenerationEvent`).
- **Multi-provider abstraction** — one `InferenceBackend` protocol, local + cloud.
- **Tool / function calling** with a per-request tool ceiling guide for local models.
- **Tool-call evaluation & conformance** — score how reliably a model calls tools (incl. a bundled BFCL AST track) via the `manifold-tools` CLI and `ConformanceScorer`, plus a bootstrap-exposed, SwiftData-backed `ToolCallConformanceCache` port for persisting verdicts. See [Beyond chat](#beyond-chat).
- **Structured / typed output**, capability-routed by `StructuredOutputRouter` across GBNF, Foundation guided-generation, JSON-Schema, and JSON-prompting.
- **Reasoning / thinking tokens** surfaced as first-class events.
- **MCP client *and* server** ([ManifoldMCP](Sources/ManifoldMCP) + the `Server` trait).
- **On-device RAG with citations** — a full document subsystem (parse `.txt`/`.md`/`.pdf` → chunk → embed → retrieve), wired into the turn loop, with an optional c

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ManifoldKit](https://github.com/ManifoldKit)
- **Source:** [ManifoldKit/ManifoldKit](https://github.com/ManifoldKit/ManifoldKit)
- **License:** MIT
- **Homepage:** https://manifoldkit.github.io/ManifoldKit/

Install and usage instructions live in the source repository linked above.