foundation_models/
lib.rs

1#![doc = include_str!("../README.md")]
2//!
3//! ---
4//!
5//! # API Documentation
6//!
7//! Safe, idiomatic Rust bindings for Apple's [FoundationModels] framework —
8//! the on-device large language model that ships with Apple Intelligence.
9//!
10//! Generate text, hold multi-turn conversations, and stream tokens from the
11//! system language model on macOS 26.0+.
12//!
13//! [FoundationModels]: https://developer.apple.com/documentation/foundationmodels
14//!
15//! # Quick start
16//!
17//! ```rust,no_run
18//! use foundation_models::{LanguageModelSession, SystemLanguageModel};
19//!
20//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
21//! if !SystemLanguageModel::is_available() {
22//!     eprintln!("Model unavailable: {:?}", SystemLanguageModel::availability());
23//!     return Ok(());
24//! }
25//!
26//! let session = LanguageModelSession::new();
27//! let reply = session.respond("Name three Norse gods.")?;
28//! println!("{reply}");
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! # Streaming
34//!
35//! ```rust,no_run
36//! use foundation_models::{LanguageModelSession, StreamEvent};
37//! use std::io::Write;
38//!
39//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
40//! let session = LanguageModelSession::new();
41//! session.stream("Tell me a haiku about Rust.", |event| match event {
42//!     StreamEvent::Chunk(s) => {
43//!         print!("{s}");
44//!         std::io::stdout().flush().ok();
45//!     }
46//!     StreamEvent::Done => println!(),
47//!     StreamEvent::Error(e) => eprintln!("\nstream error: {e}"),
48//!     _ => {}
49//! })?;
50//! # Ok(())
51//! # }
52//! ```
53
54#![cfg_attr(docsrs, feature(doc_cfg))]
55#![allow(
56    clippy::derive_partial_eq_without_eq,
57    clippy::doc_markdown,
58    clippy::map_unwrap_or,
59    clippy::missing_const_for_fn,
60    clippy::missing_errors_doc,
61    clippy::missing_fields_in_debug,
62    clippy::missing_panics_doc,
63    clippy::needless_pass_by_value,
64    clippy::new_without_default,
65    clippy::option_if_let_else,
66    clippy::ref_option,
67    clippy::semicolon_if_nothing_returned,
68    clippy::significant_drop_in_scrutinee,
69    clippy::struct_field_names,
70    clippy::unnecessary_map_or,
71    clippy::use_self
72)]
73
74pub mod content;
75pub mod error;
76pub mod ffi;
77pub mod generation;
78pub mod model;
79pub mod prompt;
80pub mod schema;
81pub mod session;
82pub mod tool;
83pub mod transcript;
84
85pub use content::{FromGeneratedContent, GeneratedContent, ToGeneratedContent};
86pub use error::{FMError, Unavailability};
87pub use generation::{GenerationOptions, SamplingMode};
88pub use model::{
89    Adapter, Availability, ConfiguredSystemLanguageModel, Guardrails, SystemLanguageModel, UseCase,
90};
91pub use prompt::{
92    Instructions, Prompt, ResponseFormat, Segment, StructuredSegment, TextSegment, ToInstructions,
93    ToPrompt, ToolDefinition,
94};
95pub use schema::{
96    DynamicGenerationProperty, DynamicGenerationSchema, Generable, GenerationGuide,
97    GenerationSchema,
98};
99pub use session::{
100    FeedbackAttachmentRequest, FeedbackIssue, FeedbackIssueCategory, FeedbackSentiment,
101    LanguageModelSession, SessionBuilder, SessionResponse, StreamEvent, StructuredStreamEvent,
102    StructuredStreamSnapshot,
103};
104pub use tool::{Tool, ToolOutput, ToolSpec};
105pub use transcript::{
106    Entry as TranscriptEntry, ToolCall, ToolCalls, ToolOutput as TranscriptToolOutput, Transcript,
107    TranscriptInstructions, TranscriptPrompt, TranscriptResponse,
108};
109
110/// Common imports for users of this crate.
111pub mod prelude {
112    pub use crate::content::{FromGeneratedContent, GeneratedContent, ToGeneratedContent};
113    pub use crate::error::{FMError, Unavailability};
114    pub use crate::generation::{GenerationOptions, SamplingMode};
115    pub use crate::model::{
116        Adapter, Availability, ConfiguredSystemLanguageModel, Guardrails, SystemLanguageModel,
117        UseCase,
118    };
119    pub use crate::prompt::{
120        Instructions, Prompt, ResponseFormat, Segment, StructuredSegment, TextSegment,
121        ToInstructions, ToPrompt, ToolDefinition,
122    };
123    pub use crate::schema::{
124        DynamicGenerationProperty, DynamicGenerationSchema, Generable, GenerationGuide,
125        GenerationSchema,
126    };
127    pub use crate::session::{
128        FeedbackAttachmentRequest, FeedbackIssue, FeedbackIssueCategory, FeedbackSentiment,
129        LanguageModelSession, SessionBuilder, SessionResponse, StreamEvent, StructuredStreamEvent,
130        StructuredStreamSnapshot,
131    };
132    pub use crate::tool::{Tool, ToolOutput, ToolSpec};
133    pub use crate::transcript::{
134        Entry as TranscriptEntry, ToolCall, ToolCalls, ToolOutput as TranscriptToolOutput,
135        Transcript, TranscriptInstructions, TranscriptPrompt, TranscriptResponse,
136    };
137}
foundation_models/lib.rs

foundation_models/
lib.rs
