Crate aimx

Expand description

AIMX: safe Rust bindings for Apple’s FoundationModels on-device language model framework, also known as Apple Intelligence.

aimx is a small, safe Rust API over the system FoundationModels.framework. The model runs locally on supported Apple hardware, so prompts and responses do not require API keys, network requests, or a hosted inference provider.

§API overview

The crate is organized around a few public concepts:

AppleIntelligenceModels starts session builders with AppleIntelligenceModels::session.
LanguageModelSession owns a stateful LanguageModelSession transcript.
GenerationOptions configures per-request temperature and token limits.
ResponseStream implements futures_core::Stream for incremental text.
GenerationSchema and GenerationSchemaProperty mirror Apple’s guided-generation schema vocabulary for structured JSON responses.
ToolDefinition registers Rust callbacks the model can call during a response.
Prompt, SystemInstructions, Temperature, and MaxTokens make important FFI and generation boundaries explicit.

Top-level helpers such as respond are available for one-off prompts, but production code should usually build a LanguageModelSession so instructions, tools, and defaults are visible in one place.

§Learning model

AIMX is easiest to learn as three decisions:

Ask whether Apple Intelligence is available with availability or AppleIntelligenceModels::availability.
Choose either a one-shot helper such as respond or a reusable LanguageModelSession.
Convert application input into typed boundaries such as Prompt, SystemInstructions, Temperature, MaxTokens, and GenerationSchema before it reaches the Swift bridge.

This is the main safety rule of the crate. Raw strings and numbers can enter at your program boundary; after that, AIMX carries meaning with Rust types and returns Error when a value cannot safely cross into FoundationModels.

§Platform requirements

Requirement	Value
macOS	26 (Tahoe) or later
Hardware	Apple Silicon (M1 or later)
System setting	Apple Intelligence enabled
Build tool	Xcode with the macOS 26 SDK

The crate still compiles on unsupported hosts. When the Swift bridge cannot be built, or when the current machine cannot run Apple Intelligence, public model APIs return Error::Unavailable instead of panicking or failing to link.

§Quick start

use aimx::{is_available, respond};

if !is_available() {
    eprintln!("Apple Intelligence not available on this device");
    return Ok(());
}

let answer = respond("What is the capital of France?").await?;
println!("{answer}");

§Builder-style sessions

use aimx::{MaxTokens, AppleIntelligenceModels, Temperature};

let session = AppleIntelligenceModels::default()
    .session()
    .instructions("You are a concise Rust expert.")
    .temperature(Temperature::new(0.2)?)
    .max_tokens(MaxTokens::new(256)?)
    .build()?;
let r1 = session.respond_to("What is ownership?").await?;
let r2 = session.respond_to("Give me a one-line example.").await?;
println!("{r1}\n{r2}");

§Generation options

Use GenerationOptions::new with Temperature and MaxTokens to keep generation defaults type-safe after input has crossed your application boundary.

use aimx::{GenerationOptions, MaxTokens, Temperature};

let precise = GenerationOptions::new()
    .temperature(Temperature::new(0.2)?)
    .max_tokens(MaxTokens::new(256)?);

§Streaming

use aimx::LanguageModelSession;

let session = LanguageModelSession::new()?;
let stream = session.stream_response("Tell me a short story.")?;

§Structured generation

use serde::Deserialize;
use aimx::{LanguageModelSession, GenerationSchema, GenerationSchemaProperty, GenerationSchemaPropertyType};

#[derive(Deserialize)]
struct CityInfo { name: String, population: f64, country: String }

let session = LanguageModelSession::new()?;
let schema = GenerationSchema::new("CityInfo")
    .property(GenerationSchemaProperty::new("name", GenerationSchemaPropertyType::String))
    .property(GenerationSchemaProperty::new("population", GenerationSchemaPropertyType::Double))
    .property(GenerationSchemaProperty::new("country", GenerationSchemaPropertyType::String));

let info: CityInfo = session.respond_generating("Describe Paris.", &schema).await?;
println!("{} has {} people", info.name, info.population);

§Tool calling

use aimx::{
    AppleIntelligenceModels, GenerationSchema, GenerationSchemaProperty, GenerationSchemaPropertyType, ToolDefinition, ToolOutput,
};

let tool = ToolDefinition::builder(
    "get_weather",
    "Get current weather for a city",
    GenerationSchema::new("GetWeatherArgs")
        .property(GenerationSchemaProperty::new("city", GenerationSchemaPropertyType::String)
            .description("City name")),
)
.handler(|args| {
    let city = args["city"].as_str().unwrap_or("unknown");
    Ok(ToolOutput::from(format!("Weather in {city}: sunny, 72°F")))
});

let session = AppleIntelligenceModels::default()
    .session()
    .instructions("You are a weather assistant.")
    .tool(tool)
    .build()?;
let response = session.respond_to("What's the weather in Tokyo?").await?;
println!("{response}");

§Errors

All fallible APIs use Error. The most common variants are:

Error::Unavailable when Apple Intelligence cannot run on this machine.
Error::NullByte when prompt or instruction text cannot cross the C FFI boundary.
Error::InvalidTemperature or Error::InvalidMaxTokens when generation options are outside the bridge-supported range.
Error::Generation for model or bridge failures during generation.
Error::Json for schema serialization or structured-response decoding.

§Panics

Public APIs in this crate are designed not to panic for user-provided input. Validation errors are reported through Error. Panics inside user-provided tool handlers are caught and returned as ToolCallError.

§Safety

This is a safe Rust wrapper. The private FFI layer owns all unsafe calls to Swift-exported C functions, validates string inputs before crossing the boundary, and stores opaque Swift handles behind an owned SessionHandle. Callers do not need to uphold any unsafe preconditions.

§Documentation style

The public docs intentionally follow the shape recommended by the rustdoc book and the Rust API Guidelines: a crate-level overview, examples that compile where possible, intra-doc links, and explicit error, panic, and safety sections for fallible or boundary-sensitive APIs. Conceptual docs use the same teaching order as the tutorial: introduce one idea, show the smallest useful example, then name the invariant that keeps the example safe.

Structs§

AppleIntelligenceModels: Handle for Apple’s default on-device system language model.
GenerationError: Error returned by the model or bridge during generation.
GenerationOptions: Tuning parameters for a single generation request.
GenerationSchema: Describes the JSON object shape that the model must produce for structured generation.
GenerationSchemaName: Name of a structured-generation schema.
GenerationSchemaProperty: A single property within a GenerationSchema.
GenerationSchemaPropertyName: Name of a property in a structured-generation schema.
InstructionsText: Developer-provided system instructions for a session.
LanguageModelSession: A stateful conversation session backed by a LanguageModelSession.
LanguageModelSessionBuilder: Builder for LanguageModelSession.
MaxTokens: Maximum number of response tokens requested from the model.
Prompt: Prompt text that has been checked for C-FFI compatibility.
PromptText: UTF-8 prompt text sent to the model.
ResponseStream: An async stream of text chunks produced by LanguageModelSession::stream.
ResponseText: Text returned by the model.
SchemaDescription: Human-readable description attached to a schema or schema property.
SystemInstructions: LanguageModelSession instructions that have been checked for C-FFI compatibility.
Temperature: Valid model temperature in the inclusive range 0.0..=2.0.
ToolCallError: Error returned by a Rust tool handler.
ToolDefinition: A function that the model can invoke when responding to a prompt.
ToolDefinitionBuilder: Builder for ToolDefinition.
ToolDescription: Human-readable description of a tool.
ToolName: Name the model uses to invoke a tool.
ToolOutput: Successful output returned from a tool call.

Enums§

AvailabilityError: Reasons why Apple Intelligence is not available on the current device.
Error: Errors returned by this crate.
GenerationSchemaPropertyRequirement: Whether a GenerationSchemaProperty must appear in structured output.
GenerationSchemaPropertyType: The type of a single property in a GenerationSchema.

Traits§

CompletionModel: Compatibility trait for older completion-oriented naming.
GenerateText: Convenience trait for sending prompts with default generation options.
LanguageModel: Provider-agnostic language-model boundary used by sessions and provider handles.
Tool: Trait boundary implemented by callable Rust tools.
WasmCompatSend: Send on native targets and a no-op marker on WebAssembly.
WasmCompatSync: Sync on native targets and a no-op marker on WebAssembly.

Functions§

availability: Returns Ok(()) if Apple Intelligence is ready.
generate: MLX-style top-level text generation helper.
generate_with_options: MLX-style top-level generation helper with explicit generation options.
is_available: Returns true if Apple Intelligence is available and ready on this device.
respond: Sends a single prompt to the model and returns the response text.
respond_with_options: Like respond but allows tuning generation via GenerationOptions.
stream_generate: MLX-style top-level streaming helper.
stream_generate_with_options: MLX-style top-level streaming helper with explicit generation options.

Type Aliases§

Client: Compatibility alias for the older provider handle name.
FoundationModels: Compatibility alias for the earlier provider handle name.
GeneratedText: MLX-style alias for text generated by the model.
Instructions: Compatibility alias for the older system-instructions boundary name.
PromptInput: Compatibility alias for the older prompt boundary name.
ResponseField: Compatibility alias for the older structured-generation property name.
ResponseFieldName: Compatibility alias for the earlier structured-generation field-name type.
ResponseFieldType: Compatibility alias for the older structured-generation property type name.
ResponseSchema: Compatibility alias for the older structured-generation schema name.
ResponseSchemaName: Compatibility alias for the earlier structured-generation schema-name type.
Schema: Compatibility alias for the oldest structured-generation schema name.
SchemaName: Compatibility alias for the older structured-generation schema-name type.
SchemaProperty: Compatibility alias for the oldest structured-generation property name.
SchemaPropertyName: Compatibility alias for the older structured-generation field-name type.
SchemaPropertyType: Compatibility alias for the oldest structured-generation property type name.
Session: Compatibility alias for the older session type name.
SessionBuilder: Compatibility alias for the older session-builder name.
SystemLanguageModel: Compatibility alias for Apple’s framework-facing system-language-model name.
ToolResult: Result type returned by tool handlers.
UnavailabilityReason: Compatibility alias for the older availability error name.

Crate aimx

Crate aimx Copy item path

§API overview

§Learning model

§Platform requirements

§Quick start

§Builder-style sessions

§Generation options

§Streaming

§Structured generation

§Tool calling

§Errors

§Panics

§Safety

§Documentation style

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate aimx