Guides

Each guide walks one build from empty file to working feature: what to add, what to write, and the complete final code. They line up with the compiled examples in the repository's Examples/ folder, which build on every CI run, so the code can't rot.

Your first request

Generate, stream, and swap providers. The five-minute one.

A chat screen

ChatSession + SwiftUI, against your route or fully local.

An agent with tools

Give the model functions, bound the loop, delegate to subagents.

Structured data

Typed Codable output, streamed partials, and the Schema DSL.

Vision and files

Send photos and PDFs, tune sampling, stream reasoning.

Human-in-the-loop approvals

Dangerous tools pause until the user says yes.

A voice assistant

Live speech both ways with a client-side tool.

Search and server tools

Combine Swift functions with hosted search, files, and code execution.

Semantic search

Embed a knowledge base, rerank candidates, and answer from context.

Transcribe and summarize

Turn recordings into timestamped text, typed notes, and speech.

Images and video

Generate a still, edit it, animate it, and persist the result.

Custom endpoints

Connect company gateways, self-hosted servers, and compatible proxies.

Production reliability

Retries, caching, telemetry, typed errors, cancellation, and fallback.

Offline first

Apple Intelligence on device, cloud as the fallback.

Serving and testing

Build UI message streams by hand and test without a network.

Media and embeddings

Images, speech, transcription, video, search, reranking.

The example files

Every numbered file in Examples/Features/ maps to one or more guides:

Example	Guide
01 GenerateText, 02 StreamText, 04 ProviderSwap	Your first request
09 ChatSession, 19 SessionHooks	A chat screen
05 Tools, 10 Agent, 20 SubagentsAndContext	An agent with tools
06 GenerateObject, 07 StreamObject, 18 Schema	Structured data
17 MultimodalAndSettings	Vision and files
16 ToolApprovals	Approvals
22 Realtime	A voice assistant
03 OnDeviceOrCloud	Offline first
21 UIStreamsAndTesting, 11 Middleware	Serving and testing
08 Embeddings, 12 Image, 13 Speech, 14 Video, 15 Rerank	Media and embeddings
08 Embeddings, 15 Rerank	Build semantic search
13 SpeechAndTranscription	Transcribe and summarize
12 ImageGeneration, 14 VideoGeneration	Generate images and video
04 ProviderSwap	Use custom endpoints and gateways
11 Middleware	Production reliability
23 WorkflowGuides and provider tool examples	Search and server tools

There are also two real apps in Apps/: a ChatGPT-style chat over local Ollama, and a focused realtime voice app covering xAI, OpenAI, and Google. Run them on the iOS simulator after xcodegen generate.