Struct LanguageModelSession 

pub struct LanguageModelSession { /* private fields */ }

A stateful conversation session backed by a LanguageModelSession.

The session automatically maintains a conversation transcript, so each successive call to respond_to has access to the full prior context (subject to the 4 096-token context window limit).

Thread safety

LanguageModelSession is Send + Sync. Concurrent calls are forwarded to the underlying Swift session, which handles them via its internal async actor. Note however that concurrent calls will interleave entries in the transcript in an unspecified order; for predictable multi-turn behaviour call sequentially.

Drop behaviour

Dropping a LanguageModelSession releases the caller’s session reference. In-flight generation futures and active ResponseStreams hold their own cloned handle reference until Swift invokes the completion callback, so cancellation cannot release the Swift session while the bridge still needs it.

Implementations

impl LanguageModelSession

pub fn builder() -> LanguageModelSessionBuilder

Starts building a session.

pub fn new() -> Result<Self, Error>

Creates a new session with no system instructions.

Errors

Returns Error::Unavailable when Apple Intelligence is unavailable.

pub fn with_instructions<I>(instructions: I) -> Result<Self, Error>

where I: TryInto<SystemInstructions>, I::Error: Into<Error>,

Creates a new session with the given system instructions.

SystemInstructions act as a persistent system prompt that guides all subsequent responses in this session. They must come from developer code, never from user input, to prevent prompt-injection attacks.

Errors

Returns Error::NullByte if the instructions cannot cross the C FFI boundary, or Error::Unavailable when Apple Intelligence is unavailable.

pub fn with_tools<I>( instructions: I, tools: Vec<ToolDefinition>, ) -> Result<Self, Error>

where I: TryInto<SystemInstructions>, I::Error: Into<Error>,

Creates a session pre-loaded with the given tools.

The model will use these tools automatically when appropriate during respond calls. Tool names must be unique within the session.

Errors

Returns Error::NullByte if the instructions or serialized tool metadata cannot cross the C FFI boundary, Error::Json if tool metadata serialization fails, or Error::Unavailable when Apple Intelligence is unavailable.

pub async fn respond<P>(&self, prompt: P) -> Result<String, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Sends a prompt and returns the full response text.

The response is appended to this session’s transcript, so subsequent calls have access to prior context.

Errors

Returns Error::NullByte for invalid prompt text, or Error::Generation when the model or bridge fails.

pub async fn respond_to<P>(&self, prompt: P) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style typed response method matching Swift’s respond(to:).

Errors

Returns the same error variants as LanguageModelSession::respond.

pub async fn complete<P>(&self, prompt: P) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Sends a prompt and returns typed response text.

Errors

Returns the same error variants as LanguageModelSession::respond_to.

pub async fn generate<P>(&self, prompt: P) -> Result<GeneratedText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

MLX-style typed response alias.

Errors

Returns the same error variants as LanguageModelSession::respond_to.

pub async fn generate_text<P>(&self, prompt: P) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Generates typed response text and appends the exchange to this session’s transcript.

Errors

Returns the same error variants as LanguageModelSession::respond_to.

pub async fn respond_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<String, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Like respond but allows tuning generation.

Errors

Returns every error documented by LanguageModelSession::respond. It can also return Error::InvalidTemperature or Error::InvalidMaxTokens when options contains out-of-range values.

pub async fn respond_to_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style typed response method with explicit generation options.

Errors

Returns every error documented by LanguageModelSession::respond. It can also return Error::InvalidTemperature or Error::InvalidMaxTokens when options contains out-of-range values.

pub async fn complete_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Like complete but allows tuning generation.

Errors

Returns the same error variants as LanguageModelSession::respond_with_options.

pub async fn generate_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<GeneratedText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

MLX-style typed response alias with explicit generation options.

Errors

Returns the same error variants as LanguageModelSession::respond_to_with_options.

pub async fn generate_text_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseText, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Generates typed response text with explicit generation options.

Errors

Returns the same error variants as LanguageModelSession::respond_with_options.

pub async fn respond_as<T, P>( &self, prompt: P, schema: &GenerationSchema, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Sends a prompt and deserialises the response into T using the provided schema.

The model generates output conforming to schema and this method deserialises it. Derive serde::Deserialize on T and ensure the field names match the schema property names exactly.

Errors

Returns Error::NullByte for invalid prompt text, Error::Json if the schema or model response cannot be serialized or deserialized, or Error::Generation when the model or bridge fails.

pub async fn respond_generating<T, P>( &self, prompt: P, schema: &GenerationSchema, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style guided-generation method for a dynamic GenerationSchema.

This mirrors Swift’s respond(to:generating:) terminology while deserializing the generated JSON into T.

Errors

Returns every error documented by LanguageModelSession::respond_as.

pub async fn generate_object<T, P>( &self, prompt: P, schema: &GenerationSchema, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Generates structured output and deserialises it into T.

Errors

Returns the same error variants as LanguageModelSession::respond_as.

pub async fn respond_as_with_options<T, P>( &self, prompt: P, schema: &GenerationSchema, options: &GenerationOptions, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Like respond_as but allows tuning generation.

Errors

Returns every error documented by LanguageModelSession::respond_as. It can also return Error::InvalidTemperature or Error::InvalidMaxTokens when options contains out-of-range values.

pub async fn respond_generating_with_options<T, P>( &self, prompt: P, schema: &GenerationSchema, options: &GenerationOptions, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style guided-generation method with explicit generation options.

Errors

Returns every error documented by LanguageModelSession::respond_as_with_options.

pub async fn generate_object_with_options<T, P>( &self, prompt: P, schema: &GenerationSchema, options: &GenerationOptions, ) -> Result<T, Error>

where T: DeserializeOwned, P: TryInto<Prompt>, P::Error: Into<Error>,

Generates structured output with explicit generation options.

Errors

Returns the same error variants as LanguageModelSession::respond_as_with_options.

pub fn stream<P>(&self, prompt: P) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Returns a ResponseStream that yields text chunks as the model generates them.

Each yielded chunk is an incremental snapshot of the response text. Drive the stream with your preferred async executor.

use aimx::LanguageModelSession;

let session = LanguageModelSession::new()?;
let stream = session.stream_response("Count to ten.")?;

Errors

Returns Error::NullByte for invalid prompt text, or Error::Generation if stream startup fails. Individual stream items can also yield Error::Generation after the stream has been created.

pub fn stream_response<P>(&self, prompt: P) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style streaming method matching Swift’s streamResponse(to:).

Errors

Returns the same error variants as LanguageModelSession::stream.

pub fn stream_generate<P>(&self, prompt: P) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

MLX-style streaming alias matching stream_generate.

Errors

Returns the same error variants as LanguageModelSession::stream_response.

pub fn stream_text<P>(&self, prompt: P) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Streams response text with this session’s default generation options.

Errors

Returns the same error variants as LanguageModelSession::stream_response.

pub fn stream_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Like stream but allows tuning generation.

Errors

Returns every error documented by LanguageModelSession::stream. It can also return Error::InvalidTemperature or Error::InvalidMaxTokens when options contains out-of-range values.

pub fn stream_response_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Apple-style streaming method with explicit generation options.

Errors

Returns every error documented by LanguageModelSession::stream. It can also return Error::InvalidTemperature or Error::InvalidMaxTokens when options contains out-of-range values.

pub fn stream_generate_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

MLX-style streaming alias with explicit generation options.

Errors

Returns every error documented by LanguageModelSession::stream_response_with_options.

pub fn stream_text_with_options<P>( &self, prompt: P, options: &GenerationOptions, ) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Streams response text with explicit generation options.

Errors

Returns the same error variants as LanguageModelSession::stream_with_options.

Trait Implementations

impl Debug for LanguageModelSession

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl LanguageModel for LanguageModelSession

fn generate_text_with_options<P>( &self, prompt: P, options: GenerationOptions, ) -> impl Future<Output = Result<ResponseText, Error>> + '_

where P: TryInto<Prompt>, P::Error: Into<Error>,

Generates response text for a prompt with explicit generation options.

fn stream_text_with_options<P>( &self, prompt: P, options: GenerationOptions, ) -> Result<ResponseStream, Error>

where P: TryInto<Prompt>, P::Error: Into<Error>,

Streams response text for a prompt with explicit generation options.