# Documentation

- [Introduction](/docs): AI features for iOS and macOS apps, in plain Swift.
- [Getting started](/docs/getting-started): Add the package and stream a first response.
- [Agent skill](/docs/agent-skill): Teach your coding agent to build with swift-ai-sdk.
- Guides
  - [Guides](/docs/guides): Build real things, step by step, with the final code included.
  - [Your first request](/docs/guides/first-request): Generate, stream, and swap providers in five minutes.
  - [A chat screen](/docs/guides/chat-screen): ChatSession plus SwiftUI, against your route or fully local.
  - [An agent with tools](/docs/guides/agent-with-tools): Give the model functions, bound the loop, delegate to subagents.
  - [Structured data](/docs/guides/structured-data): Typed Codable output, streamed partials, and the Schema DSL.
  - [Vision and files](/docs/guides/vision-and-files): Send photos and PDFs, tune sampling, stream reasoning.
  - [Human-in-the-loop approvals](/docs/guides/approvals): Dangerous tools pause until the user says yes.
  - [Drive a computer-use agent](/docs/guides/computer-use): Let a model click, type, and read the screen, feeding screenshots back each turn.
  - [Recover from bad model output](/docs/guides/self-repair): Fix malformed tool calls and unparseable JSON without failing the request.
  - [Search and server tools](/docs/guides/search-and-server-tools): Combine your Swift tools with provider-hosted search, files, and code execution.
  - [A voice assistant](/docs/guides/voice-assistant): Live speech both ways, with a client-side tool.
  - [Transcribe and summarize audio](/docs/guides/transcribe-and-summarize): Turn a recording into timestamped text, typed notes, and optional speech.
  - [Generate images and video](/docs/guides/image-and-video-pipeline): Create a still, edit it, animate it, and persist the generated media.
  - [Build semantic search](/docs/guides/semantic-search): Embed a knowledge base, rerank candidates, and answer from retrieved context.
  - [Use custom endpoints and gateways](/docs/guides/custom-endpoints): Connect a company gateway, self-hosted server, or OpenAI-compatible proxy.
  - [Production reliability](/docs/guides/production-reliability): Add retries, caching, telemetry, typed errors, cancellation, and safe fallback.
  - [Offline first](/docs/guides/offline-first): Apple Intelligence on device, cloud as the fallback.
  - [Serving and testing](/docs/guides/server-and-testing): Build UI message streams by hand, and test without a network.
  - [Media and embeddings](/docs/guides/media-and-embeddings): Images, speech, transcription, video, search, and reranking.
- API reference: Every public function and type, with signatures generated from the source.
  - [API reference](/docs/reference): Every public function and type, with signatures generated from the source.

  - **Text**
  - [generateText](/docs/reference/generate-text): Generate text and run the tool loop to completion, returning one finished result.
  - [streamText](/docs/reference/stream-text): Stream text, reasoning, tool calls, and results as they arrive.
  - [streamTextDeltas](/docs/reference/stream-text-deltas): A minimal text-only stream, without the tool loop.

  - **Structured output**
  - [generateEnum](/docs/reference/generate-enum): Pick exactly one value from a fixed set.
  - [generateJSON](/docs/reference/generate-json): Generate free-form JSON with no schema.
  - [generateObject](/docs/reference/generate-object): Generate a typed value validated against a JSON schema.
  - [generateObjectArray](/docs/reference/generate-object-array): Generate a typed array, validating each element against a schema.
  - [streamObject](/docs/reference/stream-object): Stream a structured object as its fields fill in.

  - **Embeddings and ranking**
  - [cosineSimilarity](/docs/reference/cosine-similarity): Cosine similarity between two vectors.
  - [embed](/docs/reference/embed): Embed a single string into a vector.
  - [embedMany](/docs/reference/embed-many): Embed many strings, batching automatically.
  - [rerank](/docs/reference/rerank): Reorder candidate documents against a query.

  - **Images, audio, and video**
  - [detectAudioMediaType](/docs/reference/detect-audio-media-type): Identify an audio format from its bytes.
  - [detectImageMediaType](/docs/reference/detect-image-media-type): Read an image's media type from its magic bytes.
  - [generateImage](/docs/reference/generate-image): Generate or edit images.
  - [generateSpeech](/docs/reference/generate-speech): Synthesize speech from text.
  - [generateVideo](/docs/reference/generate-video): Generate video, polling until the job completes.
  - [streamTranscribe](/docs/reference/stream-transcribe): Transcribe live audio as it arrives.
  - [transcribe](/docs/reference/transcribe): Transcribe an audio file to text.

  - **Loop control**
  - [hasToolCall](/docs/reference/has-tool-call): Stop once a named tool has been called.
  - [isLoopFinished](/docs/reference/is-loop-finished): Stop when the model stops asking for tools.
  - [isStepCount](/docs/reference/is-step-count): Stop on an exact step number.
  - [stepCountIs](/docs/reference/step-count-is): Stop the tool loop after a number of steps.

  - **Context**
  - [filterActiveTools](/docs/reference/filter-active-tools): Narrow a tool list to a named subset.
  - [pruneMessages](/docs/reference/prune-messages): Drop old tool traffic and reasoning from a history.

  - **Middleware and providers**
  - [customProvider](/docs/reference/custom-provider): Build a provider from your own model lookups.
  - [wrapEmbeddingModel](/docs/reference/wrap-embedding-model): Wrap an embedding model with middleware.
  - [wrapImageModel](/docs/reference/wrap-image-model): Wrap an image model with middleware.
  - [wrapLanguageModel](/docs/reference/wrap-language-model): Wrap a language model with middleware.
  - [wrapProvider](/docs/reference/wrap-provider): Wrap every model a provider produces.

  - **UI and transports**
  - [consumeStream](/docs/reference/consume-stream): Drain a stream to completion, discarding output.
  - [convertToModelMessages](/docs/reference/convert-to-model-messages): Convert UI messages to model messages.
  - [lastAssistantMessageIsCompleteWithApprovalResponses](/docs/reference/last-assistant-message-is-complete-with-approval-responses): Check whether pending tool approvals have been answered.
  - [lastAssistantMessageIsCompleteWithToolCalls](/docs/reference/last-assistant-message-is-complete-with-tool-calls): Check whether the last assistant turn has all its tool results.
  - [readUIMessageStream](/docs/reference/read-ui-message-stream): Turn a UI message stream into message snapshots.
  - [safeValidateUIMessages](/docs/reference/safe-validate-ui-messages): Validate UI messages without throwing.
  - [smoothStream](/docs/reference/smooth-stream): Re-chunk a text stream by word or line.
  - [validateUIMessages](/docs/reference/validate-ui-messages): Validate incoming UI messages, throwing on bad input.

  - **MCP**
  - [detectToolDrift](/docs/reference/detect-tool-drift): Compare tool fingerprints against an approved baseline.
  - [fingerprintTools](/docs/reference/fingerprint-tools): Snapshot tool definitions so changes can be detected.

  - **Audio buffers**
  - [decodePCM16](/docs/reference/decode-pcm16): Decode 16-bit PCM into samples.
  - [encodePCM16](/docs/reference/encode-pcm16): Encode samples as 16-bit PCM.
  - [resampleAudio](/docs/reference/resample-audio): Resample PCM audio between sample rates.

  - **Utilities**
  - [createIdGenerator](/docs/reference/create-id-generator): Build an id generator with a prefix and alphabet.
  - [generateId](/docs/reference/generate-id): Generate an id in the SDK default format.
  - [getRealtimeToolDefinitions](/docs/reference/get-realtime-tool-definitions): Convert tools into realtime session definitions.
  - [uploadFile](/docs/reference/upload-file): Upload a file to a provider and get a reference back.

  - **Building blocks**
  - [Agent](/docs/reference/agent): A model, its instructions, and its tools bundled into one reusable object.
  - [ContentPart](/docs/reference/content-part): One piece of a message: text, an image, a file, a tool call, a result, or reasoning.
  - [Message](/docs/reference/message): One turn in a conversation: a role and the content parts that make it up.
  - [Tool](/docs/reference/tool): A function the model can call, with a name, a description, and a parameter schema.

  - **Results**
  - [GenerateTextResult](/docs/reference/generate-text-result): Everything one finished generateText call produced.
  - [StreamTextResult](/docs/reference/stream-text-result): A live stream of one generation, plus the finished result once it lands.

  - **Configuration**
  - [CompactedContext](/docs/reference/compacted-context): The structured summary compaction produces: goal, decisions, dead ends, and facts.
  - [Compaction](/docs/reference/compaction): Automatic context compaction: when to compress a conversation, and how hard.
  - [GenerationTimeout](/docs/reference/generation-timeout): Deadlines for a generation: total wall clock, and how long a silent stream may stall.
  - [StopCondition](/docs/reference/stop-condition): When the tool loop should stop taking another step.
  - [TelemetrySettings](/docs/reference/telemetry-settings): What the SDK records about a run, and where it sends it.
  - [ToolApprovalPolicy](/docs/reference/tool-approval-policy): Which tool calls need a human yes before they run.
  - [ToolChoice](/docs/reference/tool-choice): Whether the model may call tools, must call one, or must call a specific one.

  - **UI**
  - [ChatSession](/docs/reference/chat-session): An observable chat you can bind a SwiftUI view to.

  - **Values**
  - [JSONValue](/docs/reference/json-value): A JSON value: object, array, string, number, boolean, or null.
  - [MCPClient](/docs/reference/mcp-client): A connection to an MCP server, and the tools it exposes.

  - **Errors**
  - [Errors](/docs/reference/errors): Every AIError case, what throws it, and what to do about it.
- Troubleshooting: Specific symptoms, why they happen, and what to change.
  - [Troubleshooting](/docs/troubleshooting): Specific symptoms, why they happen, and what to change.

  - **Tools**
  - [AIError.invalidToolApproval](/docs/troubleshooting/invalid-tool-approval): An approval response failed verification.
  - [AIError.invalidToolInput](/docs/troubleshooting/invalid-tool-input): Tool arguments failed schema validation, so the tool never ran.
  - [AIError.missingToolResults](/docs/troubleshooting/missing-tool-results): A conversation was sent on with tool calls that have no matching results.
  - [A tool is offered but never runs](/docs/troubleshooting/tool-never-executes): The model calls a tool and the loop stops instead of executing it.
  - [AIError.unknownTool](/docs/troubleshooting/unknown-tool): The model called a tool that was not in the tools array.

  - **Output**
  - [AIError.decoding](/docs/troubleshooting/decoding-error): A response arrived but did not match the expected shape.
  - [AIError.noObjectGenerated](/docs/troubleshooting/no-object-generated): Structured output did not parse or validate.

  - **Limits and timeouts**
  - [Running out of context on a long run](/docs/troubleshooting/context-window-exceeded): A long agent loop fails or degrades once the history outgrows the window.
  - [AIError.timedOut](/docs/troubleshooting/timed-out): A timeout fired. The scope tells you which one and what to change.

  - **Providers and auth**
  - [HTTP 401 from a provider](/docs/troubleshooting/http-401-unauthorized): The API key is missing, wrong, or not reaching the provider.
  - [AIError.authorizationRequired from an MCP server](/docs/troubleshooting/mcp-authorization-required): A hosted MCP server needs an OAuth sign-in that could not be refreshed.
  - [Cannot reach a local model server](/docs/troubleshooting/ollama-connection-refused): Ollama or another local server is not running, or is on a different port.
  - [Apple on-device model is unavailable](/docs/troubleshooting/on-device-model-unavailable): Foundation Models is not ready on this machine.

  - **Streaming and UI**
  - [Tool parts overwrite each other in the UI](/docs/troubleshooting/duplicate-tool-parts-in-ui): A repeated tool call id collapses two calls into one card.
  - [A stream stops before the answer finishes](/docs/troubleshooting/stream-ends-early): Output is cut off mid-sentence with no error.

- **Concepts**
- Foundations
  - [Foundations](/docs/foundations): The ideas the rest of the docs assume you already have.
  - [The loop](/docs/foundations/the-loop): Call, run tools, feed the results back, repeat. The shape of every generation.
  - [Models and tokens](/docs/foundations/models-and-tokens): Context windows, why the same prompt gives different answers, and what temperature does.
  - [Prompts and messages](/docs/foundations/prompts-and-messages): Why history is a list, what roles are for, and why the model has no memory.
  - [Tool calling](/docs/foundations/tool-calling): The model never runs your code. What it actually emits, and who executes it.
  - [Streaming](/docs/foundations/streaming): What a stream carries besides text, and why it changes how you write the call.

- **Core**
- [Generating text](/docs/generating-text): generateText, streamText, and the agentic loop underneath them.
- [Messages and multimodal](/docs/messages): Message construction, content parts, vision input, and JSONValue.
- [Structured output](/docs/structured-output): Get typed Codable values back instead of parsing prose.
- [Tools](/docs/tools): Typed tools, execution context, approvals, and client-side calls.
- [MCP](/docs/mcp): Connect Model Context Protocol servers and bridge their tools into the loop.
- [Agents](/docs/agents): The Agent abstraction, subagents, and agents as chat transports.
- [Timeouts and approvals](/docs/timeouts-and-approvals): Bound every call with total, step, stall, and tool timeouts, and gate sensitive tools with an approval policy that can be cryptographically signed.
- [Context management](/docs/context-management): Keep a long run inside the context window with pruning, compaction, and model context windows.
- [Reasoning](/docs/reasoning): One portable parameter for thinking across every provider.
- Providers: Every pack, its setup, features, and models.
  - [Providers](/docs/providers): First-class model packs, custom compatible endpoints, the registry, and reasoning translation.
  - [Compatibility](/docs/providers/compatibility): Every provider, what it supports, and the models the library special-cases.
  - [OpenAI](/docs/providers/openai): Responses API by default, chat completions when you ask, plus embeddings, images, speech, transcription, and realtime.
  - [Anthropic](/docs/providers/anthropic): The Messages API with adaptive thinking, tool use, vision, and prompt caching.
  - [Google](/docs/providers/google): Gemini over the Interactions API and generateContent, plus embeddings, files, caching, batch, Imagen, Veo, and Gemini Live.
  - [Azure OpenAI](/docs/providers/azure): Deployment-based routing over the OpenAI wire.
  - [Amazon Bedrock](/docs/providers/bedrock): The bedrock-mantle endpoint (Responses, Chat Completions, Messages) and the Converse API over AWS event-stream framing.
  - [xAI](/docs/providers/xai): Grok over the Responses API, typed live search, image/speech/video generation, and realtime voice.
  - [Meta](/docs/providers/meta): Muse Spark over the Responses API, with search grounding, tool search, and a 1M-token context window.
  - [Groq](/docs/providers/groq): Fast open models on the chat-completions wire, with reasoning deltas.
  - [DeepSeek](/docs/providers/deepseek): Chat and reasoner models with reasoning_content streaming.
  - [Mistral](/docs/providers/mistral): Mistral and Magistral models on the chat-completions wire.
  - [Perplexity](/docs/providers/perplexity): Search-grounded answers with citations as sources.
  - [Moonshot AI](/docs/providers/moonshot): Kimi models over a first-class Swift provider pack.
  - [Alibaba](/docs/providers/alibaba): Qwen chat and embeddings through Alibaba's OpenAI-compatible mode.
  - [Hugging Face](/docs/providers/huggingface): Open models through the Hugging Face inference router.
  - [Cohere](/docs/providers/cohere): Command models, embeddings, and the reranker.
  - [Voyage AI](/docs/providers/voyage): Retrieval embeddings and reranking from Voyage.
  - [Together AI](/docs/providers/together-ai): Run Together AI models through a first-class Swift provider pack.
  - [Fireworks](/docs/providers/fireworks): Stream Fireworks models with tools, structured output, and reasoning.
  - [Cerebras](/docs/providers/cerebras): Use Cerebras inference models through a dedicated Swift model type.
  - [OpenRouter](/docs/providers/openrouter): Access OpenRouter's multi-provider model catalog from Swift.
  - [DeepInfra](/docs/providers/deepinfra): Run DeepInfra chat models through a dedicated Swift provider pack.
  - [Baseten](/docs/providers/baseten): Call Baseten model deployments through a first-class Swift model.
  - [Vercel](/docs/providers/vercel): Generate with Vercel's v0 model endpoint from Swift.
  - [AI Gateway](/docs/providers/ai-gateway): Route models through Vercel AI Gateway with a dedicated Swift type.
  - [Sarvam](/docs/providers/sarvam): Indic-language chat, speech synthesis, and transcription across 10+ Indian languages.
  - [fal](/docs/providers/fal): Image generation through fal models.
  - [Luma](/docs/providers/luma): Image and video generation through Dream Machine.
  - [Replicate](/docs/providers/replicate): Image generation with Replicate-hosted models.
  - [Black Forest Labs](/docs/providers/black-forest-labs): FLUX image generation with async polling.
  - [ByteDance](/docs/providers/bytedance): Seedream image and Seedance video on the BytePlus Ark API.
  - [Kling AI](/docs/providers/kling): Kling video generation with JWT authentication.
  - [Prodia](/docs/providers/prodia): Fast image generation on Prodia's v2 inference API.
  - [QuiverAI](/docs/providers/quiverai): Prompt-to-SVG generation.
  - [ElevenLabs](/docs/providers/elevenlabs): Speech synthesis and audio transcription.
  - [LMNT](/docs/providers/lmnt): Text-to-speech through LMNT models and voices.
  - [Hume](/docs/providers/hume): Expressive text-to-speech with Hume voices.
  - [Cartesia](/docs/providers/cartesia): Sonic text-to-speech and Ink transcription.
  - [Deepgram](/docs/providers/deepgram): Aura speech synthesis and Nova transcription.
  - [AssemblyAI](/docs/providers/assemblyai): Asynchronous audio transcription behind one await.
  - [Rev.ai](/docs/providers/rev-ai): Asynchronous Rev.ai transcription behind one await.
  - [Gladia](/docs/providers/gladia): Asynchronous prerecorded-audio transcription behind one await.
  - [Ollama](/docs/providers/ollama): Run local Ollama models with the same generation APIs as cloud providers.
  - [LM Studio](/docs/providers/lm-studio): Connect Swift apps to models served locally by LM Studio.
  - [Custom OpenAI-compatible endpoints](/docs/providers/openai-compatible): Connect custom gateways, proxies, and model servers that speak chat completions.
  - [Media providers](/docs/providers/media): Provider index for image, speech, transcription, and video models.
- [On-device models](/docs/on-device): Apple Foundation Models through the same LanguageModel protocol.

- **UI**
- [Chat UI](/docs/chat-ui): ChatSession, CompletionSession, and ObjectSession for SwiftUI.
- [Terminal UI](/docs/terminal-ui): Run an Agent or a ChatTransport in an interactive terminal with streamed markdown, tool cards, reasoning sections, and approval prompts.
- [Streaming protocol](/docs/streaming-protocol): The UI message stream on the wire, and the server-side builders.
- [Realtime voice](/docs/realtime): Live speech conversations over WebSockets with OpenAI, Google, and xAI.

- **Beyond text**
- [Embeddings](/docs/embeddings): Embed one or many values and compare vectors with cosine similarity.
- [Reranking](/docs/reranking): Reorder candidate documents by relevance with a reranking model.
- [Image generation](/docs/image-generation): Generate and edit images with a shared ImageModel API.
- [Speech generation](/docs/speech-generation): Turn text into audio with a shared SpeechModel API.
- [Transcription](/docs/transcription): Turn audio into text with a shared TranscriptionModel API.
- [Video generation](/docs/video-generation): Generate video and animate still images with a shared VideoModel API.
- [Files and skills](/docs/files-and-skills): Upload provider-hosted files and reusable Anthropic skills.
- [Media overview](/docs/media): Image generation, speech synthesis, transcription, and video generation.

- **More**
- [Middleware](/docs/middleware): Wrap a model to intercept requests and stream parts, for caching, reasoning extraction, defaults, and custom hooks.
- [Runtime context](/docs/runtime-context): Carry server-side state through a run without putting it in the prompt, and mark tools whose schema is only known at runtime.
- [Telemetry](/docs/telemetry): Forward spans into OSLog, OpenTelemetry, or your analytics, and control what each call records.
- [Errors and retries](/docs/errors): The typed AIError cases, and the automatic retry behavior behind every request.
- [Testing](/docs/testing): The AITesting kit: mock models, scripted loops, stream simulators.
- Changelog: What shipped in each release.
  - [Changelog](/docs/changelog): What shipped in each release of swift-ai-sdk.