foundation_models/
error.rs

1//! Errors produced by the `FoundationModels` bridge.
2
3use core::ffi::c_char;
4use core::fmt;
5
6use crate::ffi;
7
8/// Top-level error type returned by all fallible APIs in this crate.
9#[derive(Debug, Clone, PartialEq, Eq)]
10#[non_exhaustive]
11pub enum FMError {
12    /// `FoundationModels` is not available on this device.
13    ///
14    /// See [`Unavailability`] for the specific reason.
15    ModelUnavailable {
16        reason: Unavailability,
17        message: String,
18    },
19    /// The model refused to produce a response because the prompt or
20    /// generated content tripped a safety guardrail.
21    GuardrailViolation(String),
22    /// The combined prompt + history exceeds the model's context window.
23    ContextWindowExceeded(String),
24    /// The requested locale or language is not supported by the on-device model.
25    UnsupportedLanguage(String),
26    /// On-device model assets are still downloading or otherwise unavailable.
27    AssetsUnavailable(String),
28    /// The session was rate-limited (typically only relevant on Mac with
29    /// extended generation budgets).
30    RateLimited(String),
31    /// Structured generation failed to decode the model's output into the
32    /// requested `Generable` schema.
33    DecodingFailure(String),
34    /// The model refused the request (distinct from a guardrail violation —
35    /// the model itself declined to answer).
36    Refusal(String),
37    /// Too many concurrent generation requests against the same session.
38    ConcurrentRequests(String),
39    /// The supplied [`GenerationGuide`] is unsupported by the on-device model.
40    UnsupportedGuide(String),
41    /// A tool invocation failed while the model was using `Tool` calling.
42    ToolCallFailed(String),
43    /// An adapter asset pack was invalid.
44    AdapterInvalidAsset(String),
45    /// The requested adapter name was invalid.
46    AdapterInvalidName(String),
47    /// No compatible adapter could be found for the requested name.
48    AdapterCompatibleNotFound(String),
49    /// The generation Task was cancelled before completion.
50    Cancelled,
51    /// An invalid argument crossed the FFI boundary (e.g. a NUL byte in a prompt).
52    InvalidArgument(String),
53    /// Catch-all for unmapped Swift errors. Inspect [`code`](Self::code) and
54    /// [`message`](Self::message) for diagnostics.
55    Unknown { code: i32, message: String },
56}
57
58/// Reason why [`SystemLanguageModel`](crate::SystemLanguageModel) is unavailable.
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60#[non_exhaustive]
61pub enum Unavailability {
62    /// The hardware does not support Apple Intelligence (e.g. Intel Mac, M1).
63    DeviceNotEligible,
64    /// Apple Intelligence is supported but disabled in System Settings.
65    AppleIntelligenceNotEnabled,
66    /// Model assets are still downloading.
67    ModelNotReady,
68    /// The host OS is older than macOS 26.0.
69    OsTooOld,
70    /// `FoundationModels` reported an unavailability reason this crate doesn't
71    /// recognise — most likely added in a newer SDK.
72    Unknown,
73}
74
75impl FMError {
76    /// Numeric status code reported by the Swift bridge. Useful for matching
77    /// against [`crate::ffi::status`] constants.
78    #[must_use]
79    pub const fn code(&self) -> i32 {
80        match self {
81            Self::ModelUnavailable { .. } => ffi::status::MODEL_UNAVAILABLE,
82            Self::GuardrailViolation(_) => ffi::status::GUARDRAIL_VIOLATION,
83            Self::ContextWindowExceeded(_) => ffi::status::CONTEXT_WINDOW_EXCEEDED,
84            Self::UnsupportedLanguage(_) => ffi::status::UNSUPPORTED_LANGUAGE,
85            Self::AssetsUnavailable(_) => ffi::status::ASSETS_UNAVAILABLE,
86            Self::RateLimited(_) => ffi::status::RATE_LIMITED,
87            Self::DecodingFailure(_) => ffi::status::DECODING_FAILURE,
88            Self::Refusal(_) => ffi::status::REFUSAL,
89            Self::ConcurrentRequests(_) => ffi::status::CONCURRENT_REQUESTS,
90            Self::UnsupportedGuide(_) => ffi::status::UNSUPPORTED_GUIDE,
91            Self::ToolCallFailed(_) => ffi::status::TOOL_CALL_FAILED,
92            Self::AdapterInvalidAsset(_) => ffi::status::ADAPTER_INVALID_ASSET,
93            Self::AdapterInvalidName(_) => ffi::status::ADAPTER_INVALID_NAME,
94            Self::AdapterCompatibleNotFound(_) => ffi::status::ADAPTER_COMPATIBLE_NOT_FOUND,
95            Self::Cancelled => ffi::status::CANCELLED,
96            Self::InvalidArgument(_) => ffi::status::INVALID_ARGUMENT,
97            Self::Unknown { code, .. } => *code,
98        }
99    }
100
101    /// Human-readable description (forwarded from `Error.localizedDescription`).
102    #[must_use]
103    pub fn message(&self) -> &str {
104        match self {
105            Self::ModelUnavailable { message, .. }
106            | Self::GuardrailViolation(message)
107            | Self::ContextWindowExceeded(message)
108            | Self::UnsupportedLanguage(message)
109            | Self::AssetsUnavailable(message)
110            | Self::RateLimited(message)
111            | Self::DecodingFailure(message)
112            | Self::Refusal(message)
113            | Self::ConcurrentRequests(message)
114            | Self::UnsupportedGuide(message)
115            | Self::ToolCallFailed(message)
116            | Self::AdapterInvalidAsset(message)
117            | Self::AdapterInvalidName(message)
118            | Self::AdapterCompatibleNotFound(message)
119            | Self::InvalidArgument(message)
120            | Self::Unknown { message, .. } => message,
121            Self::Cancelled => "generation cancelled",
122        }
123    }
124}
125
126impl fmt::Display for FMError {
127    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
128        write!(f, "{} (code {})", self.message(), self.code())
129    }
130}
131
132impl std::error::Error for FMError {}
133
134/// Build an `FMError` from a status code + error message returned by Swift.
135///
136/// Takes ownership of `error_str` (a heap-allocated C string from the
137/// Swift bridge) and frees it via `fm_string_free` after copying.
138pub(crate) fn from_swift(status: i32, error_str: *mut c_char) -> FMError {
139    let message = if error_str.is_null() {
140        String::new()
141    } else {
142        let s = unsafe { core::ffi::CStr::from_ptr(error_str) }
143            .to_string_lossy()
144            .into_owned();
145        unsafe { ffi::fm_string_free(error_str) };
146        s
147    };
148
149    match status {
150        ffi::status::MODEL_UNAVAILABLE => FMError::ModelUnavailable {
151            reason: Unavailability::Unknown,
152            message,
153        },
154        ffi::status::GUARDRAIL_VIOLATION => FMError::GuardrailViolation(message),
155        ffi::status::CONTEXT_WINDOW_EXCEEDED => FMError::ContextWindowExceeded(message),
156        ffi::status::UNSUPPORTED_LANGUAGE => FMError::UnsupportedLanguage(message),
157        ffi::status::ASSETS_UNAVAILABLE => FMError::AssetsUnavailable(message),
158        ffi::status::RATE_LIMITED => FMError::RateLimited(message),
159        ffi::status::DECODING_FAILURE => FMError::DecodingFailure(message),
160        ffi::status::REFUSAL => FMError::Refusal(message),
161        ffi::status::CONCURRENT_REQUESTS => FMError::ConcurrentRequests(message),
162        ffi::status::UNSUPPORTED_GUIDE => FMError::UnsupportedGuide(message),
163        ffi::status::TOOL_CALL_FAILED => FMError::ToolCallFailed(message),
164        ffi::status::ADAPTER_INVALID_ASSET => FMError::AdapterInvalidAsset(message),
165        ffi::status::ADAPTER_INVALID_NAME => FMError::AdapterInvalidName(message),
166        ffi::status::ADAPTER_COMPATIBLE_NOT_FOUND => FMError::AdapterCompatibleNotFound(message),
167        ffi::status::CANCELLED => FMError::Cancelled,
168        ffi::status::INVALID_ARGUMENT => FMError::InvalidArgument(message),
169        code => FMError::Unknown { code, message },
170    }
171}
foundation_models/error.rs

foundation_models/
error.rs
