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
85#[cfg(feature = "async")]
86#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
87pub mod async_api;
88
89pub use content::{
90    Decimal, FromGeneratedContent, GeneratedContent, GeneratedContentKind, GenerationId,
91    ToGeneratedContent,
92};
93pub use error::{
94    AdapterAssetErrorContext, FMError, GenerationErrorContext, Refusal, SchemaErrorContext,
95    ToolCallError, Unavailability,
96};
97pub use generation::{GenerationOptions, SamplingMode};
98pub use model::{
99    Adapter, Availability, ConfiguredSystemLanguageModel, Guardrails, SystemLanguageModel, UseCase,
100};
101pub use prompt::{
102    Instructions, Prompt, ResponseFormat, Segment, StructuredSegment, TextSegment, ToInstructions,
103    ToPrompt, ToolDefinition,
104};
105pub use schema::{
106    DynamicGenerationProperty, DynamicGenerationSchema, Generable, GenerationGuide,
107    GenerationSchema,
108};
109pub use session::{
110    FeedbackAttachmentRequest, FeedbackIssue, FeedbackIssueCategory, FeedbackSentiment,
111    LanguageModelSession, SessionBuilder, SessionResponse, StreamEvent, StructuredStreamEvent,
112    StructuredStreamSnapshot,
113};
114pub use tool::{Tool, ToolOutput, ToolSpec};
115pub use transcript::{
116    Entry as TranscriptEntry, ToolCall, ToolCalls, ToolOutput as TranscriptToolOutput, Transcript,
117    TranscriptInstructions, TranscriptPrompt, TranscriptResponse,
118};
119
120/// Common imports for users of this crate.
121pub mod prelude {
122    pub use crate::content::{
123        Decimal, FromGeneratedContent, GeneratedContent, GeneratedContentKind, GenerationId,
124        ToGeneratedContent,
125    };
126    pub use crate::error::{
127        AdapterAssetErrorContext, FMError, GenerationErrorContext, Refusal, SchemaErrorContext,
128        ToolCallError, Unavailability,
129    };
130    pub use crate::generation::{GenerationOptions, SamplingMode};
131    pub use crate::model::{
132        Adapter, Availability, ConfiguredSystemLanguageModel, Guardrails, SystemLanguageModel,
133        UseCase,
134    };
135    pub use crate::prompt::{
136        Instructions, Prompt, ResponseFormat, Segment, StructuredSegment, TextSegment,
137        ToInstructions, ToPrompt, ToolDefinition,
138    };
139    pub use crate::schema::{
140        DynamicGenerationProperty, DynamicGenerationSchema, Generable, GenerationGuide,
141        GenerationSchema,
142    };
143    pub use crate::session::{
144        FeedbackAttachmentRequest, FeedbackIssue, FeedbackIssueCategory, FeedbackSentiment,
145        LanguageModelSession, SessionBuilder, SessionResponse, StreamEvent, StructuredStreamEvent,
146        StructuredStreamSnapshot,
147    };
148    pub use crate::tool::{Tool, ToolOutput, ToolSpec};
149    pub use crate::transcript::{
150        Entry as TranscriptEntry, ToolCall, ToolCalls, ToolOutput as TranscriptToolOutput,
151        Transcript, TranscriptInstructions, TranscriptPrompt, TranscriptResponse,
152    };
153}
foundation_models/lib.rs

foundation_models/
lib.rs
