hex/src/apple_intelligence.rs
Dax 3fc14b5ec9
labs: neutral voice for chosen modes (#2043) (#2049)
* labs: neutral voice for chosen modes (#2043)

* labs: tighten neutral voice guard and reuse cleanup helpers

* labs: share neutral voice quote and fallback helpers

* labs: keep folder paths protected in neutral voice
2026-11-20 11:51:08 -05:00

306 lines
10 KiB
Rust
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! The FoundationModels adapter: Apple's on-device language model behind a
//! small C bridge in `apple_intelligence.swift`.
use std::ffi::{CStr, CString, c_char};
use std::ptr;
use std::sync::Mutex;
use std::time::{Duration, Instant};
use serde::Deserialize;
use crate::meeting::generator::{
GeneratedChapter, GeneratedChapterLines, GeneratedNotes, GenerationError,
};
unsafe extern "C" {
fn hex_apple_intelligence_availability() -> i32;
fn hex_apple_intelligence_context_size() -> isize;
fn hex_apple_intelligence_notes(
instructions: *const c_char,
prompt: *const c_char,
title_only: bool,
timeout_ms: u64,
error: *mut *mut c_char,
) -> *mut c_char;
fn hex_apple_intelligence_chapter(
instructions: *const c_char,
prompt: *const c_char,
timeout_ms: u64,
error: *mut *mut c_char,
) -> *mut c_char;
fn hex_apple_intelligence_chapter_lines(
instructions: *const c_char,
prompt: *const c_char,
timeout_ms: u64,
error: *mut *mut c_char,
) -> *mut c_char;
fn hex_apple_intelligence_text(
instructions: *const c_char,
prompt: *const c_char,
temperature: f64,
timeout_ms: u64,
error: *mut *mut c_char,
) -> *mut c_char;
fn hex_apple_intelligence_free_string(string: *mut c_char);
}
const AVAILABILITY_TTL: Duration = Duration::from_secs(10);
const CONTEXT_WINDOW_MARKER: &str = "context-window:";
const REFUSAL_MARKER: &str = "refused:";
/// A plain-text answer, as `hex_apple_intelligence_text` encodes it.
#[derive(Deserialize)]
struct GeneratedText {
text: String,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Availability {
Available,
DeviceNotEligible,
AppleIntelligenceNotEnabled,
ModelNotReady,
UnsupportedSystem,
Unknown,
}
impl Availability {
fn from_code(code: i32) -> Self {
match code {
0 => Self::Available,
1 => Self::DeviceNotEligible,
2 => Self::AppleIntelligenceNotEnabled,
3 => Self::ModelNotReady,
4 => Self::UnsupportedSystem,
_ => Self::Unknown,
}
}
pub fn is_available(self) -> bool {
self == Self::Available
}
pub fn description(self) -> &'static str {
match self {
Self::Available => "Meeting titles and short summaries, written on this Mac",
Self::DeviceNotEligible => "This Mac does not support Apple Intelligence",
Self::AppleIntelligenceNotEnabled => {
"Turn on Apple Intelligence in System Settings to use this"
}
Self::ModelNotReady => "The Apple Intelligence model is still downloading",
Self::UnsupportedSystem => "Requires macOS 26 or later",
Self::Unknown => "Apple Intelligence is unavailable",
}
}
}
/// The cached system availability; refreshed at most every ten seconds so
/// render paths can ask freely.
pub fn availability() -> Availability {
static CACHE: Mutex<Option<(Instant, Availability)>> = Mutex::new(None);
let mut cache = CACHE.lock().unwrap_or_else(|error| error.into_inner());
if let Some((checked, availability)) = *cache
&& checked.elapsed() < AVAILABILITY_TTL
{
return availability;
}
// SAFETY: A synchronous property read without arguments.
let availability = Availability::from_code(unsafe { hex_apple_intelligence_availability() });
*cache = Some((Instant::now(), availability));
availability
}
/// The model's context window in tokens, or zero when unavailable or
/// unknown to this build's SDK.
pub fn context_tokens() -> usize {
// SAFETY: A synchronous property read without arguments.
usize::try_from(unsafe { hex_apple_intelligence_context_size() }).unwrap_or(0)
}
/// Generates a meeting title and short summary with guided generation.
/// Blocks the calling thread for at most `timeout`; the bridge runs at
/// utility priority.
pub fn generate_notes(
instructions: &str,
prompt: &str,
timeout: Duration,
) -> Result<GeneratedNotes, GenerationError> {
generate(instructions, prompt, false, timeout)
}
/// Generates only a meeting title, which needs far fewer output tokens.
pub fn generate_title(
instructions: &str,
prompt: &str,
timeout: Duration,
) -> Result<String, GenerationError> {
generate(instructions, prompt, true, timeout).map(|notes| notes.title)
}
/// Decides one live chapter pass over new transcript lines.
pub fn generate_chapter(
instructions: &str,
prompt: &str,
timeout: Duration,
) -> Result<GeneratedChapter, GenerationError> {
call(instructions, prompt, |instructions, prompt, error| {
// SAFETY: Both strings outlive the call and the bridge writes only `error`.
unsafe { hex_apple_intelligence_chapter(instructions, prompt, timeout_ms(timeout), error) }
})
}
/// The L numbers of the lines about the chapter after a boundary.
pub fn generate_chapter_lines(
instructions: &str,
prompt: &str,
timeout: Duration,
) -> Result<Vec<i64>, GenerationError> {
call(instructions, prompt, |instructions, prompt, error| {
// SAFETY: Both strings outlive the call and the bridge writes only `error`.
unsafe {
hex_apple_intelligence_chapter_lines(instructions, prompt, timeout_ms(timeout), error)
}
})
.map(|generated: GeneratedChapterLines| generated.lines)
}
/// One plain-text answer: no guided structure, so the caller judges the text
/// itself. `temperature` varies the wording per call (the cleanup stays at
/// 0.2; Labs › Neutral voice asks for 0.7). Blocks the calling thread for at
/// most `timeout`; the bridge runs at utility priority.
pub fn generate_text(
instructions: &str,
prompt: &str,
temperature: f64,
timeout: Duration,
) -> Result<String, GenerationError> {
call(instructions, prompt, |instructions, prompt, error| {
// SAFETY: Both strings outlive the call and the bridge writes only `error`.
unsafe {
hex_apple_intelligence_text(
instructions,
prompt,
temperature,
timeout_ms(timeout),
error,
)
}
})
.map(|generated: GeneratedText| generated.text)
}
fn timeout_ms(timeout: Duration) -> u64 {
timeout.as_millis().min(u64::MAX as u128) as u64
}
fn generate(
instructions: &str,
prompt: &str,
title_only: bool,
timeout: Duration,
) -> Result<GeneratedNotes, GenerationError> {
call(instructions, prompt, |instructions, prompt, error| {
// SAFETY: Both strings outlive the call and the bridge writes only `error`.
unsafe {
hex_apple_intelligence_notes(
instructions,
prompt,
title_only,
timeout_ms(timeout),
error,
)
}
})
}
/// Runs one bridge call and decodes its JSON result.
fn call<T: for<'de> Deserialize<'de>>(
instructions: &str,
prompt: &str,
bridge: impl FnOnce(*const c_char, *const c_char, *mut *mut c_char) -> *mut c_char,
) -> Result<T, GenerationError> {
let instructions =
CString::new(instructions).map_err(|error| GenerationError::Failed(error.to_string()))?;
let prompt = CString::new(prompt.replace('\0', ""))
.map_err(|e| GenerationError::Failed(e.to_string()))?;
let mut error = ptr::null_mut();
let json = bridge(instructions.as_ptr(), prompt.as_ptr(), &mut error);
if json.is_null() {
let message = take_string(error).unwrap_or_else(|| "Apple Intelligence failed".into());
return Err(classify_error(message));
}
let text = take_string(json).unwrap_or_default();
serde_json::from_str(&text).map_err(|error| GenerationError::Failed(error.to_string()))
}
fn classify_error(message: String) -> GenerationError {
if message.starts_with(CONTEXT_WINDOW_MARKER) || message.contains("context window") {
GenerationError::ContextWindow
} else if message.starts_with(REFUSAL_MARKER) {
GenerationError::Refused
} else {
GenerationError::Failed(message)
}
}
fn take_string(string: *mut c_char) -> Option<String> {
if string.is_null() {
return None;
}
// SAFETY: The bridge returns NUL-terminated strings from `strdup`.
let value = unsafe { CStr::from_ptr(string) }
.to_string_lossy()
.into_owned();
// SAFETY: Ownership returns to the bridge allocator exactly once.
unsafe { hex_apple_intelligence_free_string(string) };
Some(value)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn only_an_available_model_is_used() {
assert!(Availability::from_code(0).is_available());
for (code, expected) in [
(1, Availability::DeviceNotEligible),
(2, Availability::AppleIntelligenceNotEnabled),
(3, Availability::ModelNotReady),
(4, Availability::UnsupportedSystem),
(99, Availability::Unknown),
(-1, Availability::Unknown),
] {
let availability = Availability::from_code(code);
assert_eq!(availability, expected);
assert!(!availability.is_available());
}
assert_eq!(
Availability::AppleIntelligenceNotEnabled.description(),
"Turn on Apple Intelligence in System Settings to use this"
);
}
#[test]
fn context_overflow_is_distinguished_from_other_failures() {
assert_eq!(
classify_error("context-window: 9000 tokens".into()),
GenerationError::ContextWindow
);
assert_eq!(
classify_error("Apple Intelligence timed out.".into()),
GenerationError::Failed("Apple Intelligence timed out.".into())
);
assert_eq!(
classify_error("refused: guardrail context".into()),
GenerationError::Refused
);
}
/// `generate_text` reads the one field the Swift bridge encodes.
#[test]
fn a_plain_text_answer_reads_its_text() {
let answer: GeneratedText = serde_json::from_str(r#"{"text":"Ship it."}"#).unwrap();
assert_eq!(answer.text, "Ship it.");
}
}