Struct LanguageModelSession 

pub struct LanguageModelSession { /* private fields */ }

A session for interacting with Apple’s Foundation Models

This provides access to on-device language models via the FoundationModels framework. Requires macOS 26+ or iOS 26+ with Apple Intelligence enabled.

Session State

Each session maintains a transcript of all interactions (prompts, responses, etc.). The transcript can be serialized to JSON for persistence and used to restore sessions across app launches.

Creating Sessions

• LanguageModelSession::new() - Create without instructions
• LanguageModelSession::with_instructions() - Create with system prompt
• LanguageModelSession::from_transcript_json() - Restore from saved transcript

Getting Responses

• response() - Blocking response (waits for completion)
• stream_response() - Streaming response (real-time chunks)
• cancel_stream() - Cancel ongoing stream

Examples

See the method-level documentation for detailed examples:

• new() and response() for basic usage
• stream_response() for streaming
• transcript_json() and from_transcript_json() for persistence

Implementations

impl LanguageModelSession

pub fn new() -> Result<Self>

Creates a new language model session without instructions

This is equivalent to calling with_instructions(None).

Errors

Returns Error::ModelNotAvailable if Apple Intelligence is not enabled or the system model is unavailable.

pub fn with_instructions(instructions: &str) -> Result<Self>

Creates a new language model session with instructions

Instructions define the model’s persona, behavior, and guidelines for the entire session. They are always the first entry in the session transcript.

Arguments

• instructions - System prompt that guides the model’s behavior

Errors

• Error::ModelNotAvailable - If Apple Intelligence is not enabled
• Error::InvalidInput - If instructions contain a null byte

Examples

let session = LanguageModelSession::with_instructions(
    "You are a helpful coding assistant. Provide concise answers."
)?;

Examples found in repository

examples/transcript_persistence.rs (lines 31-33)

fn create_and_save() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new session with instructions
    let session = LanguageModelSession::with_instructions(
        "You are a knowledgeable travel guide specializing in Japanese culture and tourism.",
    )?;
    println!("Created new session with travel guide persona.\n");

    // Have a conversation
    println!("User: Tell me about Tokyo.");
    let response1 = session.response("Tell me about Tokyo.")?;
    println!("Assistant: {}\n", response1);

    println!("User: What's the best time to visit?");
    let response2 = session.response("What's the best time to visit?")?;
    println!("Assistant: {}\n", response2);

    // Save the transcript
    let transcript_json = session.transcript_json()?;
    fs::write(TRANSCRIPT_FILE, &transcript_json)?;
    println!("--- Session saved to {} ---", TRANSCRIPT_FILE);
    println!("Run this example again to restore and continue the conversation.\n");

    Ok(())
}

examples/stream_response.rs (lines 17-19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Foundation Models - Streaming Response Example ===\n");

    // Create a new session with instructions
    println!("Creating session...");
    let session = LanguageModelSession::with_instructions(
        "You are a creative storyteller. Write engaging, vivid narratives.",
    )?;
    println!("Session created!\n");

    // Define the prompt
    let prompt = "Tell me a short story about a robot learning to paint.";
    println!("Prompt: \"{}\"\n", prompt);
    println!("Streaming response:\n");
    println!("---");

    // Stream the response chunk by chunk
    // The callback is called for each chunk as it's generated
    session.stream_response(prompt, |chunk| {
        // Print each chunk immediately
        print!("{}", chunk);

        // Flush stdout to ensure immediate display
        io::stdout().flush().unwrap();
    })?;

    // Print completion message
    println!("\n---");
    println!("\n=== Stream Complete ===");

    Ok(())
}

examples/response.rs (lines 15-17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Foundation Models - Blocking Response Example ===\n");

    // Create a new session with instructions
    println!("Creating session with instructions...");
    let session = LanguageModelSession::with_instructions(
        "You are a helpful assistant. Provide concise, accurate answers.",
    )?;
    println!("Session created!\n");

    // Define the prompt
    let prompt = "What is Rust programming language? Please explain in 2-3 sentences.";
    println!("Prompt: \"{}\"\n", prompt);
    println!("Generating response...\n");

    // Get the complete response
    // This blocks until the entire response is generated
    let response = session.response(prompt)?;

    // Print the response
    println!("Response:\n{}\n", response);

    // Multi-turn conversation example
    println!("--- Multi-turn conversation ---\n");

    let follow_up = "What are its main advantages?";
    println!("Follow-up: \"{}\"\n", follow_up);

    let response2 = session.response(follow_up)?;
    println!("Response:\n{}\n", response2);

    println!("=== Complete ===");

    Ok(())
}

pub fn from_transcript_json(transcript_json: &str) -> Result<Self>

Creates a session from a serialized transcript JSON

This restores a previous session state, including the original instructions and full conversation history. Use this to resume conversations across app launches.

Arguments

• transcript_json - JSON string from transcript_json()

Errors

• Error::ModelNotAvailable - If Apple Intelligence is not enabled
• Error::InvalidInput - If JSON contains a null byte or is invalid

Examples

let json = std::fs::read_to_string("session.json")?;
let session = LanguageModelSession::from_transcript_json(&json)?;

Examples found in repository

examples/transcript_persistence.rs (line 59)

fn restore_and_continue() -> Result<(), Box<dyn std::error::Error>> {
    // Load the saved transcript
    let transcript_json = fs::read_to_string(TRANSCRIPT_FILE)?;

    // Restore the session
    let session = LanguageModelSession::from_transcript_json(&transcript_json)?;
    println!("Session restored with previous conversation context.\n");

    // Continue the conversation - the model remembers the previous context
    println!("User: What about the food there?");
    let response = session.response("What about the food there?")?;
    println!("Assistant: {}\n", response);

    println!("User: Any restaurant recommendations?");
    let response2 = session.response("Any restaurant recommendations?")?;
    println!("Assistant: {}\n", response2);

    // Clean up the saved file
    fs::remove_file(TRANSCRIPT_FILE)?;
    println!("--- Cleaned up saved session ---\n");

    Ok(())
}

pub fn transcript_json(&self) -> Result<String>

Gets the current session transcript as JSON

The returned JSON can be persisted and later passed to from_transcript_json() to restore the session state.

Returns

JSON string representing the full transcript (instructions, prompts, responses)

Errors

• Error::InternalError - If transcript serialization fails

Examples

let session = LanguageModelSession::new()?;
let _ = session.response("Hello")?;

let json = session.transcript_json()?;
std::fs::write("session.json", &json)?;

Examples found in repository

examples/transcript_persistence.rs (line 46)

fn create_and_save() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new session with instructions
    let session = LanguageModelSession::with_instructions(
        "You are a knowledgeable travel guide specializing in Japanese culture and tourism.",
    )?;
    println!("Created new session with travel guide persona.\n");

    // Have a conversation
    println!("User: Tell me about Tokyo.");
    let response1 = session.response("Tell me about Tokyo.")?;
    println!("Assistant: {}\n", response1);

    println!("User: What's the best time to visit?");
    let response2 = session.response("What's the best time to visit?")?;
    println!("Assistant: {}\n", response2);

    // Save the transcript
    let transcript_json = session.transcript_json()?;
    fs::write(TRANSCRIPT_FILE, &transcript_json)?;
    println!("--- Session saved to {} ---", TRANSCRIPT_FILE);
    println!("Run this example again to restore and continue the conversation.\n");

    Ok(())
}

pub fn response(&self, prompt: &str) -> Result<String>

Generates a complete response to the given prompt

This method blocks until the entire response is generated and returned as a String. The prompt and response are added to the session transcript.

For a better user experience with incremental updates, use stream_response instead.

Arguments

• prompt - The input text to send to the model

Errors

• Error::InvalidInput - If the prompt is empty or contains a null byte
• Error::GenerationError - If an error occurs during generation

Examples

let session = LanguageModelSession::new()?;
let response = session.response("Explain Rust ownership")?;
println!("Response: {}", response);

Examples found in repository

examples/transcript_persistence.rs (line 38)

fn create_and_save() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new session with instructions
    let session = LanguageModelSession::with_instructions(
        "You are a knowledgeable travel guide specializing in Japanese culture and tourism.",
    )?;
    println!("Created new session with travel guide persona.\n");

    // Have a conversation
    println!("User: Tell me about Tokyo.");
    let response1 = session.response("Tell me about Tokyo.")?;
    println!("Assistant: {}\n", response1);

    println!("User: What's the best time to visit?");
    let response2 = session.response("What's the best time to visit?")?;
    println!("Assistant: {}\n", response2);

    // Save the transcript
    let transcript_json = session.transcript_json()?;
    fs::write(TRANSCRIPT_FILE, &transcript_json)?;
    println!("--- Session saved to {} ---", TRANSCRIPT_FILE);
    println!("Run this example again to restore and continue the conversation.\n");

    Ok(())
}

fn restore_and_continue() -> Result<(), Box<dyn std::error::Error>> {
    // Load the saved transcript
    let transcript_json = fs::read_to_string(TRANSCRIPT_FILE)?;

    // Restore the session
    let session = LanguageModelSession::from_transcript_json(&transcript_json)?;
    println!("Session restored with previous conversation context.\n");

    // Continue the conversation - the model remembers the previous context
    println!("User: What about the food there?");
    let response = session.response("What about the food there?")?;
    println!("Assistant: {}\n", response);

    println!("User: Any restaurant recommendations?");
    let response2 = session.response("Any restaurant recommendations?")?;
    println!("Assistant: {}\n", response2);

    // Clean up the saved file
    fs::remove_file(TRANSCRIPT_FILE)?;
    println!("--- Cleaned up saved session ---\n");

    Ok(())
}

examples/response.rs (line 27)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Foundation Models - Blocking Response Example ===\n");

    // Create a new session with instructions
    println!("Creating session with instructions...");
    let session = LanguageModelSession::with_instructions(
        "You are a helpful assistant. Provide concise, accurate answers.",
    )?;
    println!("Session created!\n");

    // Define the prompt
    let prompt = "What is Rust programming language? Please explain in 2-3 sentences.";
    println!("Prompt: \"{}\"\n", prompt);
    println!("Generating response...\n");

    // Get the complete response
    // This blocks until the entire response is generated
    let response = session.response(prompt)?;

    // Print the response
    println!("Response:\n{}\n", response);

    // Multi-turn conversation example
    println!("--- Multi-turn conversation ---\n");

    let follow_up = "What are its main advantages?";
    println!("Follow-up: \"{}\"\n", follow_up);

    let response2 = session.response(follow_up)?;
    println!("Response:\n{}\n", response2);

    println!("=== Complete ===");

    Ok(())
}

pub fn stream_response<F>(&self, prompt: &str, on_chunk: F) -> Result<()>

where F: FnMut(&str),

Generates a streaming response to the given prompt

This method calls the provided callback for each chunk as it’s generated, providing immediate feedback to the user. The prompt and complete response are added to the session transcript.

Arguments

• prompt - The input text to send to the model
• on_chunk - Callback function called for each generated chunk

Errors

• Error::InvalidInput - If the prompt is empty or contains a null byte
• Error::GenerationError - If an error occurs during generation

Examples

let session = LanguageModelSession::new()?;

session.stream_response("Tell me a story", |chunk| {
    print!("{}", chunk);
    let _ = io::stdout().flush();
})?;

println!(); // newline after stream completes

Examples found in repository

examples/stream_response.rs (lines 30-36)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Foundation Models - Streaming Response Example ===\n");

    // Create a new session with instructions
    println!("Creating session...");
    let session = LanguageModelSession::with_instructions(
        "You are a creative storyteller. Write engaging, vivid narratives.",
    )?;
    println!("Session created!\n");

    // Define the prompt
    let prompt = "Tell me a short story about a robot learning to paint.";
    println!("Prompt: \"{}\"\n", prompt);
    println!("Streaming response:\n");
    println!("---");

    // Stream the response chunk by chunk
    // The callback is called for each chunk as it's generated
    session.stream_response(prompt, |chunk| {
        // Print each chunk immediately
        print!("{}", chunk);

        // Flush stdout to ensure immediate display
        io::stdout().flush().unwrap();
    })?;

    // Print completion message
    println!("\n---");
    println!("\n=== Stream Complete ===");

    Ok(())
}

pub fn cancel_stream(&self)

Cancels the current streaming response

This method immediately cancels any ongoing streaming operation. The streaming callback will stop receiving tokens and the stream will complete with the tokens received so far.

Notes

• Safe to call even if no stream is active
• After cancellation, stream_response will return normally

Examples

let session = Arc::new(LanguageModelSession::new()?);
let session_clone = Arc::clone(&session);

// Start streaming in a thread
let handle = thread::spawn(move || {
    session_clone.stream_response("Write a long essay...", |chunk| {
        print!("{}", chunk);
    })
});

// Cancel after a delay
thread::sleep(Duration::from_secs(2));
session.cancel_stream();

handle.join().unwrap()?;

Trait Implementations

impl Drop for LanguageModelSession

fn drop(&mut self)

Executes the destructor for this type.

impl Send for LanguageModelSession

impl Sync for LanguageModelSession