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

foundation_models/
lib.rs
