skills/apple-foundation-models/references/api_reference.md

API Reference

SystemLanguageModel

The SystemLanguageModel class provides access to Apple's on-device language models optimized for efficiency and privacy.

Overview

SystemLanguageModel is the main entry point for interacting with Apple's Foundation Models. It provides:

• On-device inference with no data leaving the device
• Optimized for Apple Silicon (A17 Pro and M-series chips)
• Session-based conversation management
• Built-in safety guardrails

Initialization

import Foundation
import SystemLanguageModel

// Get the default system model
let model = try await SystemLanguageModel()

// Check if model is available
if SystemLanguageModel.isAvailable {
    let model = try await SystemLanguageModel()
} else {
    print("Model not available on this device")
}

Properties

isAvailable

static var isAvailable: Bool { get }

Returns true if the system language model is available on the current device. Available on devices with A17 Pro or M-series chips running iOS 18.1+, macOS 15.1+, or iPadOS 18.1+.

sessionTokenLimit

var sessionTokenLimit: Int { get }

The maximum number of tokens allowed in a session, including both input and output tokens.

Creating Sessions

session(with:)

func session(with guardrails: Guardrails = .automatic) async throws -> LanguageModelSession

Creates a new conversation session with optional safety guardrails.

Parameters:

• guardrails: The level of content filtering to apply (default: .automatic)

Returns: A LanguageModelSession instance for managing the conversation

Example:

// Create session with automatic guardrails
let session = try await model.session()

// Create session with custom guardrails
let session = try await model.session(with: .automatic)

Guardrails

enum Guardrails {
    case automatic
    case disabled
}

Controls content filtering and safety features:

• .automatic: Applies Apple's default content filtering
• .disabled: Disables content filtering (use with caution)

---

LanguageModelSession

Manages a conversation with the language model, maintaining context across multiple turns.

Overview

A session maintains conversation history and manages the interaction with the model. Sessions are tied to the model's token limit and automatically handle context management.

Creating Prompts

// Create a simple prompt
let prompt = Prompt(text: "What is Swift?")

// Create a prompt with system instructions
let prompt = Prompt {
    Instructions("You are a helpful coding assistant")
    "Explain closures in Swift"
}

Generating Responses

respond(to:)

func respond(to prompt: Prompt) async throws -> String

Generates a complete response to a prompt.

Parameters:

• prompt: The input prompt

Returns: The complete generated response as a String

Throws: Errors if generation fails or content is filtered

Example:

let session = try await model.session()
let prompt = Prompt(text: "Explain Swift's type system")
let response = try await session.respond(to: prompt)
print(response)

streamResponse(to:)

func streamResponse(to: Prompt) -> AsyncThrowingStream<String, Error>

Streams the response token-by-token as it's generated.

Parameters:

• prompt: The input prompt

Returns: An async stream of String tokens

Example:

let session = try await model.session()
let prompt = Prompt(text: "Write a short story")

for try await token in session.streamResponse(to: prompt) {
    print(token, terminator: "")
}
print() // New line after complete response

Guided Generation

respond(to:using:)

func respond<T: Generable>(to prompt: Prompt, using schema: T.Type) async throws -> T

Generates structured output conforming to a Swift type.

Type Parameters:

• T: A type conforming to Generable

Parameters:

• prompt: The input prompt
• schema: The type to generate

Returns: An instance of type T

Example:

struct Recipe: Generable {
    var title: String
    var ingredients: [String]
    var steps: [String]
}

let session = try await model.session()
let prompt = Prompt(text: "Give me a simple pasta recipe")
let recipe = try await session.respond(to: prompt, using: Recipe.self)
print(recipe.title)

Tool Calling

respond(to:withTools:)

func respond(to prompt: Prompt, withTools tools: [Tool]) async throws -> String

Generates a response with access to custom tools.

Parameters:

• prompt: The input prompt
• tools: Array of tools the model can use

Returns: The generated response as a String

Example:

struct WeatherTool: Tool {
    static let description = "Gets current weather for a location"
    
    struct Arguments: Decodable {
        let location: String
    }
    
    func call(arguments: Arguments) async throws -> String {
        // Fetch weather data
        return "Sunny, 72°F"
    }
}

let session = try await model.session()
let prompt = Prompt(text: "What's the weather in San Francisco?")
let response = try await session.respond(to: prompt, withTools: [WeatherTool()])

Session Management

Sessions automatically manage conversation history within the token limit. When the limit is approached, older messages are removed to make room for new ones.

// Sessions maintain context across multiple interactions
let session = try await model.session()

let response1 = try await session.respond(to: Prompt(text: "My name is Alice"))
let response2 = try await session.respond(to: Prompt(text: "What's my name?"))
// response2 will reference "Alice" from the conversation history

---

GenerationOptions

Control how the model generates responses with temperature, sampling mode, and token limits.

Overview

Options that control how the model generates its response to a prompt.

struct GenerationOptions {
    var sampling: SamplingMode
    var temperature: Double
    var maximumResponseTokens: Int?
}

Creating Options

let options = GenerationOptions(
    sampling: .greedy,
    temperature: 0.7,
    maximumResponseTokens: 500
)

let response = try await session.respond(
    options: options,
    prompt: Prompt("Write a short story")
)

Properties

sampling - Sampling strategy for token selection

• .greedy - Always pick most likely token (deterministic)
• .topK(k: Int) - Sample from top K most likely tokens
• .topP(p: Double) - Nucleus sampling (cumulative probability)

temperature - Influences confidence (0.0 to 1.0)

• 0.0 - Very deterministic, conservative
• 0.5 - Balanced (default)
• 1.0 - More creative, random

maximumResponseTokens - Limit response length

• nil - Use model default
• 100-2000 - Typical range

Usage Examples

// Deterministic, factual responses
let factualOptions = GenerationOptions(
    sampling: .greedy,
    temperature: 0.0,
    maximumResponseTokens: 200
)

// Creative writing
let creativeOptions = GenerationOptions(
    sampling: .topP(p: 0.9),
    temperature: 0.8,
    maximumResponseTokens: 1000
)

// Balanced
let balancedOptions = GenerationOptions(
    sampling: .topK(k: 50),
    temperature: 0.5,
    maximumResponseTokens: 500
)

---

Error Handling

do {
    let session = try await model.session()
    let response = try await session.respond(to: prompt)
} catch LanguageModelSession.GenerationError.guardrailViolation {
    // Content was filtered by safety guardrails
    print("Response blocked by guardrails")
} catch let error as SystemLanguageModelError {
    switch error {
    case .modelUnavailable:
        print("Model not available on this device")
    case .tokenLimitExceeded:
        print("Prompt exceeds token limit")
    default:
        print("Error: \(error)")
    }
}

Common Errors:

• GenerationError.guardrailViolation - Content filtered for safety
• GenerationError.tokenLimitExceeded - Too many tokens
• GenerationError.modelUnavailable - Model not ready
• ToolCallError - Tool execution failed