fm-rs 0.1.4

Rust bindings for Apple's FoundationModels.framework
Documentation

Requirements

  • macOS 26+ or iOS/iPadOS 26+
  • Apple Intelligence enabled
  • Apple Silicon device
  • Rust 1.85+ (edition 2024)

Installation

[dependencies]
fm-rs = "0.1"

Enable the derive macro if you want compile-time schema generation:

[dependencies]
fm-rs = { version = "0.1", features = ["derive"] }

Quick Start

use fm_rs::{GenerationOptions, Session, SystemLanguageModel};

fn main() -> Result<(), fm_rs::Error> {
    let model = SystemLanguageModel::new()?;
    model.ensure_available()?;

    let session = Session::with_instructions(&model, "You are a helpful assistant.")?;
    let options = GenerationOptions::builder()
        .temperature(0.7)
        .max_response_tokens(500)
        .build();

    let response = session.respond("What is the capital of France?", &options)?;
    println!("{}", response.content());

    Ok(())
}

Key Features

  • Blocking and streaming responses
  • Tool calling with JSON argument schemas
  • Structured JSON output (explicit schemas or derive macro)
  • Transcript persistence and restoration
  • Context usage estimates and compaction helpers
  • Prewarming and timeout-aware respond APIs

Runtime Notes (macOS)

  • FFI calls are synchronous. Use spawn_blocking in async runtimes.
  • If you see libswift_Concurrency.dylib load errors, add Swift rpaths in your binary crate’s build.rs.
use std::process::Command;

fn main() {
    println!("cargo:rustc-link-arg=-Wl,-rpath,/usr/lib/swift");

    if let Ok(output) = Command::new("xcrun")
        .args(["--toolchain", "default", "--find", "swift"])
        .output()
    {
        let swift_path = String::from_utf8_lossy(&output.stdout).trim().to_string();
        if let Some(toolchain) = std::path::Path::new(&swift_path).parent().and_then(|p| p.parent()) {
            let lib_path = toolchain.join("lib/swift/macosx");
            if lib_path.exists() {
                println!("cargo:rustc-link-arg=-Wl,-rpath,{}", lib_path.display());
            }
        }
    }
}

Prompting Guidance

For best results on-device:

  • Keep prompts focused and explicit about length and style.
  • Prefer instructions for stable behavior across prompts.
  • Use small examples when you need consistent formatting.
  • Break complex tasks into smaller steps.
  • Use structured output when you need reliable parsing.

See Apple’s guidance for more detail:

Examples

cargo run --example basic
cargo run --example streaming
cargo run --example tools
cargo run --example structured
cargo run --example context_compaction

Documentation

See API details and advanced usage in the crate docs (docs.rs).

License

MIT License - see LICENSE for details.