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

foundation_models/
lib.rs
