Claude for Foundation Models

This package provides conformance to Apple's Foundation Models provider. It is not a general-purpose Anthropic Messages API client.

The primary public types are:

• ClaudeLanguageModel
• ClaudeModel
• AuthMode
• ClaudeServerTool

Add the package to your Package.swift dependencies or via Xcode's File ▸ Add Package Dependencies… using the repository URL.

After adding the dependency, import both FoundationModels and ClaudeForFoundationModels in your Swift files.

// Package.swift
dependencies: [
  .package(url: "https://github.com/anthropics/ClaudeForFoundationModels.git", from: "0.1.0")
]

// In your Swift file
import FoundationModels
import ClaudeForFoundationModels

To use Claude, initialize a ClaudeLanguageModel with a model name (from the ClaudeModel enum) and an authentication method. Pass this model to a LanguageModelSession to interact with the model using the standard LanguageModelSession API, such as respond(to:).

import FoundationModels
import ClaudeForFoundationModels

let model = ClaudeLanguageModel(
  name: .sonnet5,
  auth: .apiKey(ProcessInfo.processInfo.environment["ANTHROPIC_API_KEY"] ?? "")
)

let session = LanguageModelSession(model: model)
let response = try await session.respond(to: "Plan a 4-day trip to Buenos Aires.")
print(response.content)

The library uses two main error categories:

1. LanguageModelError: Covers Foundation Models specific issues like guardrails, context length, and decoding errors.
2. ClaudeError: Covers provider-specific errors that do not map to LanguageModelError (e.g., authentication issues).

Use pattern matching to drive specific product flows, such as prompting for an API key when a credential is missing.

do {
  let response = try await session.respond(to: prompt)
  print(response.content)
} catch ClaudeError.missingCredential {
  // Prompt for an API key.
} catch {
  // Foundation Models errors (guardrails, context length, decoding) and transport errors.
}

To render searches and tool activities inline while the answer is still streaming, iterate over the session.streamResponse(to:) async sequence and walk the snapshot.transcriptEntries similarly to how you would walk a static transcript.

for try await snapshot in session.streamResponse(to: prompt) {
  for case .response(let entry) in snapshot.transcriptEntries {
    for segment in entry.segments {
      // Handle text or activity as shown in transcript examples
    }
  }
}

Server-side tools (web search, web fetch, and code execution) run on Anthropic's infrastructure within a single round-trip. You configure them per model using the serverTools: parameter in the ClaudeLanguageModel initializer.

Note that serverTools: is distinct from the framework's tools: array; tools: is used for client-side tools that the framework invokes on the device, whereas serverTools: are managed by Anthropic.

Supported tools include:

• .webSearch(maxUses: Int?, domains: DomainFilter)
• .webFetch(domains: DomainFilter)
• .codeExecution

For .webSearch and .webFetch, the domains: filter can be:

• .unrestricted (default)
• .allowing([...])
• .blocking([...])

let model = ClaudeLanguageModel(
  name: .sonnet5,
  auth: auth,
  serverTools: [
    .webSearch(maxUses: 5),
    .codeExecution,
  ]
)

You can pin a specific Claude effort level for every request using the fixedEffort: parameter in ClaudeLanguageModel.

Supported levels are low, medium, high, xhigh, and max. The API defaults to high if no effort is specified. The framework's reasoning levels map to Claude effort as follows:

• .light → low
• .moderate → medium
• .deep → high
• .custom → accepts a direct string like "xhigh" or "max".

ClaudeLanguageModel(name: .opus5, auth: auth, fixedEffort: .xhigh)

To receive model responses incrementally, use session.streamResponse(to:). Each element in the resulting stream is a cumulative snapshot of the content.

let stream = session.streamResponse(to: "Summarize today's top science stories.")
for try await partial in stream {
  print(partial.content)
}

Depending on your environment, use one of the following authentication methods:

• .apiKey("..."): Best for simulator development. Do not ship with a bundled key in production.
• .proxied(headers: [...], baseURL: ...): Use this if you route requests through your own backend. The relay at baseURL adds the credentials. Ensure your relay forwards the anthropic-beta header for fallbacks and the anthropic-user-profile-id header for user profiles.

// For simulator iteration
ClaudeLanguageModel(name: .sonnet5, auth: .apiKey("..."))

// For custom backend relays
ClaudeLanguageModel(
  name: .sonnet5,
  auth: .proxied(headers: ["X-App-Token": "..."]),
  baseURL: URL(string: "https://api.yourapp.com/claude")!
)