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

foundation_models/
lib.rs
