Skip to main content

fauna_api/parrot/
generative.rs

1use std::collections::HashMap;
2use std::fmt;
3use std::sync::Arc;
4
5use base64::Engine;
6use base64::engine::general_purpose::STANDARD;
7use chrono::{DateTime, Utc};
8use futures_util::future::BoxFuture;
9use futures_util::stream::BoxStream;
10use serde::{Deserialize, Deserializer, Serialize, Serializer};
11use serde_json::{Map, Value, json};
12
13use super::socket;
14use crate::authentification::{CredentialsOrApiKey, Profile};
15use crate::drive::DriveAuthorization;
16use crate::error::Error;
17use crate::groups::Group;
18use crate::http::{client, ok};
19use crate::shared::schema::Schema;
20
21pub use crate::ant::persona::Demographic;
22use crate::ant::persona::PartialDemographic;
23
24macro_rules! models {
25    ($(#[$meta:meta])* pub enum $name:ident { $($variant:ident = $value:literal,)* }) => {
26        $(#[$meta])*
27        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
28        pub enum $name {
29            $(#[serde(rename = $value)] $variant,)*
30        }
31
32        impl $name {
33            pub(crate) fn as_str(self) -> &'static str {
34                match self {
35                    $($name::$variant => $value,)*
36                }
37            }
38        }
39
40        impl fmt::Display for $name {
41            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
42                f.write_str(self.as_str())
43            }
44        }
45    };
46}
47
48models! {
49    /// Text clients.
50    pub enum Text {
51        Auto = "auto",
52
53        Gpt5_4 = "gpt-5.4",
54        Gpt5_4Mini = "gpt-5.4-mini",
55        Gpt5_4Nano = "gpt-5.4-nano",
56        Gpt5_4Pro = "gpt-5.4-pro",
57        Gpt5_5 = "gpt-5.5",
58        Gpt5_5Pro = "gpt-5.5-pro",
59        Gpt5_6Sol = "gpt-5.6-sol",
60        Gpt5_6Terra = "gpt-5.6-terra",
61        Gpt5_6Luna = "gpt-5.6-luna",
62
63        ClaudeSonnet4_6 = "claude-sonnet-4-6",
64        ClaudeSonnet5 = "claude-sonnet-5",
65        ClaudeOpus4_6 = "claude-opus-4-6",
66        ClaudeOpus4_7 = "claude-opus-4-7",
67        ClaudeOpus4_8 = "claude-opus-4-8",
68        ClaudeOpus5 = "claude-opus-5",
69        ClaudeFable5 = "claude-fable-5",
70
71        Gemini3_1Pro = "gemini-3.1-pro-preview",
72        Gemini3Flash = "gemini-3-flash-preview",
73        Gemini3_1FlashLite = "gemini-3.1-flash-lite",
74        Gemini3_5Flash = "gemini-3.5-flash",
75
76        Grok4_20Reasoning = "grok-4.20-reasoning-latest",
77        Grok4_20NonReasoning = "grok-4.20-non-reasoning-latest",
78        Grok4_3 = "grok-4.3-latest",
79        Grok4_5 = "grok-4.5",
80        Grok4_6 = "grok-4.6",
81        GrokCode4_1Fast = "grok-code-fast-1",
82    }
83}
84
85models! {
86    pub enum Image {
87        GrokImagineImage = "grok-imagine-image",
88        GrokImagineImage2 = "grok-imagine-image-2.0",
89        GrokImagineImageQuality = "grok-imagine-image-quality",
90        GptImage1_5 = "gpt-image-1.5",
91        GptImage1Mini = "gpt-image-1-mini",
92    }
93}
94
95models! {
96    pub enum Video {
97        GrokImagineVideo = "grok-imagine-video",
98        GrokImagineVideo1_5 = "grok-imagine-video-1.5",
99
100        Sora2 = "sora-2",
101        Sora2Pro = "sora-2-pro",
102    }
103}
104
105models! {
106    pub enum Speech {
107        Gpt4oMiniTts = "gpt-4o-mini-tts",
108
109        GrokTts = "grok-tts",
110
111        ElevenV3 = "eleven_v3",
112        ElevenFlashV2_5 = "eleven_flash_v2_5",
113    }
114}
115
116models! {
117    pub enum Transcription {
118        GptTranscribe = "gpt-transcribe",
119
120        GrokStt = "grok-stt",
121
122        ScribeV2 = "scribe_v2",
123    }
124}
125
126models! {
127    /// Embedding clients.
128    pub enum Embedding {
129        TextEmbedding3Small = "text-embedding-3-small",
130        TextEmbedding3Large = "text-embedding-3-large",
131
132        GeminiEmbedding001 = "gemini-embedding-001",
133        GeminiEmbedding2Preview = "gemini-embedding-2-preview",
134
135        Voyage3 = "voyage-3",
136        Voyage3Large = "voyage-3-large",
137        Voyage3Lite = "voyage-3-lite",
138        VoyageCode3 = "voyage-code-3",
139        VoyageFinance2 = "voyage-finance-2",
140        VoyageLaw2 = "voyage-law-2",
141    }
142}
143
144models! {
145    pub enum Voice {
146        GptRealtime = "gpt-realtime-2",
147        GrokVoice = "grok-voice-think-fast-2.0",
148        ElevenV3 = "eleven_v3_conversational",
149    }
150}
151
152models! {
153    pub enum Decision {
154        Jev1_13 = "jev-1.13.0",
155        Jev1_14 = "jev-1.14.0",
156
157        Gpt6Luna = "gpt-6-luna",
158    }
159}
160
161#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
162#[serde(rename_all = "UPPERCASE")]
163pub enum Role {
164    User,
165    Model,
166    System,
167    Tool,
168}
169
170#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
171pub struct TextPart {
172    #[serde(default)]
173    pub text: String,
174}
175
176#[derive(Debug, Clone)]
177pub struct File {
178    pub file: crate::drive::File,
179}
180
181#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
182#[serde(rename_all = "lowercase")]
183pub enum InvocationStatus {
184    Success,
185    Error,
186}
187
188#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
189pub struct Invocation {
190    #[serde(default, skip_serializing_if = "Option::is_none")]
191    pub id: Option<String>,
192    #[serde(default, skip_serializing_if = "Option::is_none")]
193    pub args: Option<Map<String, Value>>,
194    pub name: String,
195    #[serde(default, skip_serializing_if = "Option::is_none")]
196    pub status: Option<InvocationStatus>,
197    #[serde(default, skip_serializing_if = "Option::is_none")]
198    pub result: Option<String>,
199}
200
201#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
202pub struct Result {
203    pub id: String,
204    pub result: String,
205}
206
207/// A reaction to the message at transcript `position`. It travels as its own
208/// USER message; chat UIs fold it onto that message instead of drawing a bubble.
209/// `on: false` takes the reaction back; the latest one per person, message and
210/// emoji wins.
211#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
212pub struct Reaction {
213    pub emoji: String,
214    pub position: u32,
215    pub on: bool,
216}
217
218/// One part of a message. On the wire each carries its `type`; a FILE part goes
219/// up as a reference (a Drive path or an access code), never its bytes.
220#[derive(Debug, Clone)]
221#[allow(clippy::large_enum_variant)]
222pub enum Part {
223    Text(TextPart),
224    File(File),
225    Invocation(Invocation),
226    Result(Result),
227    Reaction(Reaction),
228}
229
230pub(crate) fn file_ref(file: &crate::drive::File) -> Value {
231    let mut wire = Map::new();
232    wire.insert("type".to_string(), Value::from("FILE"));
233    wire.insert("name".to_string(), Value::from(file.name()));
234    wire.insert(
235        "contentType".to_string(),
236        Value::from(file.content_type.as_str()),
237    );
238    match &file.authorization {
239        DriveAuthorization::AccessCode { access_code, .. } => {
240            wire.insert("accessCode".to_string(), Value::from(access_code.as_str()));
241        }
242        DriveAuthorization::Path { path, group, .. }
243        | DriveAuthorization::Repository { path, group, .. } => {
244            wire.insert("path".to_string(), Value::from(path.as_str()));
245            if let Some(group) = group {
246                wire.insert("group".to_string(), Value::from(group.as_str()));
247            }
248        }
249    }
250    Value::Object(wire)
251}
252
253fn tagged(kind: &str, value: impl Serialize) -> Value {
254    let mut wire = Map::new();
255    wire.insert("type".to_string(), Value::from(kind));
256    if let Ok(Value::Object(fields)) = serde_json::to_value(value) {
257        wire.extend(fields);
258    }
259    Value::Object(wire)
260}
261
262impl Part {
263    /// The part as it goes over the wire, FILE parts as references.
264    pub(crate) fn wire(&self) -> Value {
265        match self {
266            Part::Text(part) => tagged("TEXT", part),
267            Part::File(part) => file_ref(&part.file),
268            Part::Invocation(part) => tagged("INVOCATION", part),
269            Part::Result(part) => tagged("RESULT", part),
270            Part::Reaction(part) => tagged("REACTION", part),
271        }
272    }
273
274    /// Every part but FILE, which needs the caller's authorization to open.
275    pub(crate) fn from_json(json: &Value) -> Option<Part> {
276        match json["type"].as_str()? {
277            "TEXT" => serde_json::from_value(json.clone()).ok().map(Part::Text),
278            "INVOCATION" => serde_json::from_value(json.clone())
279                .ok()
280                .map(Part::Invocation),
281            "RESULT" => serde_json::from_value(json.clone()).ok().map(Part::Result),
282            "REACTION" => serde_json::from_value(json.clone())
283                .ok()
284                .map(Part::Reaction),
285            _ => None,
286        }
287    }
288}
289
290impl Serialize for Part {
291    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
292        self.wire().serialize(serializer)
293    }
294}
295
296/// `'BLOCKING' | 'NON_BLOCKING'` in the TypeScript SDK.
297#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
298#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
299pub enum FunctionBehavior {
300    Blocking,
301    NonBlocking,
302}
303
304#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
305pub struct Function {
306    pub name: String,
307    pub parameters: Schema,
308    #[serde(default, skip_serializing_if = "Option::is_none")]
309    pub description: Option<String>,
310
311    #[serde(default, skip_serializing_if = "Option::is_none")]
312    pub default: Option<Value>,
313    #[serde(default, skip_serializing_if = "Option::is_none")]
314    pub example: Option<Value>,
315
316    #[serde(default, skip_serializing_if = "Option::is_none")]
317    pub behavior: Option<FunctionBehavior>,
318}
319
320/// What a tool runs when the model calls it, given the call's arguments.
321pub type ToolEvaluate =
322    Arc<dyn Fn(Value) -> BoxFuture<'static, crate::Result<String>> + Send + Sync>;
323
324/// The line a tool adds to a prompt, given the call's arguments.
325pub type ToolInstruction = Arc<dyn Fn(&Value) -> String + Send + Sync>;
326
327#[derive(Clone)]
328pub struct Tool {
329    pub function: Function,
330
331    pub evaluate: ToolEvaluate,
332
333    pub instruction: Option<ToolInstruction>,
334}
335
336impl fmt::Debug for Tool {
337    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
338        f.debug_struct("Tool")
339            .field("function", &self.function)
340            .finish_non_exhaustive()
341    }
342}
343
344/// `Tool[] | Tool` in the TypeScript SDK: a single tool forces it, a list lets
345/// the model choose.
346#[derive(Debug, Clone)]
347#[allow(clippy::large_enum_variant)]
348pub enum ToolsOrTool {
349    Tools(Vec<Tool>),
350    Tool(Tool),
351}
352
353#[derive(Debug, Clone)]
354pub struct Content {
355    pub parts: Vec<Part>,
356    pub role: Role,
357    pub created_at: DateTime<Utc>,
358    pub author: Option<Profile>,
359    /// Text model id that produced a MODEL turn (for UI avatar / rehydrate).
360    pub model: Option<String>,
361    /// The name of the API key an agent posted this with, for its author.
362    pub via: Option<String>,
363}
364
365/// `{ promptTokens, completionTokens }` in the TypeScript SDK.
366#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
367#[serde(rename_all = "camelCase")]
368pub struct Usage {
369    #[serde(default)]
370    pub prompt_tokens: u64,
371    #[serde(default)]
372    pub completion_tokens: u64,
373}
374
375#[derive(Debug, Clone)]
376pub struct TextResponse {
377    pub content: Content,
378    pub usage: Usage,
379}
380
381/// `{ promptTokens }` in the TypeScript SDK.
382#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
383#[serde(rename_all = "camelCase")]
384pub struct EmbeddingUsage {
385    #[serde(default)]
386    pub prompt_tokens: u64,
387}
388
389#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
390pub struct EmbeddingResponse {
391    pub embedding: Vec<f64>,
392    pub usage: EmbeddingUsage,
393}
394
395#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
396#[serde(tag = "event", rename_all = "snake_case")]
397pub enum StreamEvent {
398    Text {
399        #[serde(default)]
400        delta: String,
401    },
402    ToolCall {
403        id: String,
404        name: String,
405        #[serde(default)]
406        args: Map<String, Value>,
407        #[serde(default, skip_serializing_if = "Option::is_none")]
408        server: Option<bool>,
409    },
410    Done {
411        #[serde(default)]
412        usage: Usage,
413    },
414    Error {
415        message: String,
416        #[serde(default, skip_serializing_if = "Option::is_none")]
417        code: Option<String>,
418    },
419}
420
421fn pcm() -> String {
422    "audio/pcm".to_string()
423}
424
425fn audio_out<S: Serializer>(delta: &[u8], serializer: S) -> std::result::Result<S::Ok, S::Error> {
426    serializer.serialize_str(&STANDARD.encode(delta))
427}
428
429/// Audio arrives base64 encoded, or as a list of byte values.
430fn audio_in<'de, D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Vec<u8>, D::Error> {
431    Ok(socket::audio_delta(&Value::deserialize(deserializer)?))
432}
433
434#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
435#[serde(tag = "event", rename_all = "snake_case")]
436pub enum VoiceEvent {
437    Audio {
438        #[serde(serialize_with = "audio_out", deserialize_with = "audio_in")]
439        delta: Vec<u8>,
440        #[serde(rename = "contentType", default = "pcm")]
441        content_type: String,
442    },
443    InputTranscript {
444        #[serde(default)]
445        delta: String,
446    },
447    OutputTranscript {
448        #[serde(default)]
449        delta: String,
450    },
451    ToolCall {
452        id: String,
453        name: String,
454        #[serde(default)]
455        args: Map<String, Value>,
456    },
457    SpeechStarted,
458    SpeechStopped,
459    Done {
460        #[serde(default)]
461        usage: Usage,
462    },
463    Error {
464        message: String,
465        #[serde(default, skip_serializing_if = "Option::is_none")]
466        code: Option<String>,
467    },
468}
469
470/// The `options` argument of `generate_text` and `generate_text_sync`. Dropping
471/// the returned stream closes the socket, which stops the reply.
472#[derive(Debug, Clone, Default)]
473pub struct TextOptions {
474    pub content: Option<Vec<Content>>,
475    pub tools: Option<ToolsOrTool>,
476    pub max_tools: Option<u32>,
477    pub reasoning: Option<String>,
478    pub group: Option<Group>,
479}
480
481/// Streaming text generation. A singular Tool forces it; an array lets the model choose.
482pub async fn generate_text(
483    authorization: &CredentialsOrApiKey,
484    model: Text,
485    options: TextOptions,
486) -> crate::Result<BoxStream<'static, StreamEvent>> {
487    socket::stream_text(
488        authorization,
489        "/generative/text",
490        model.as_str(),
491        socket::TextOptions {
492            content: options.content,
493            tools: options.tools,
494            max_tools: options.max_tools,
495            memories: None,
496            reasoning: options.reasoning,
497            group: options.group,
498        },
499    )
500    .await
501}
502
503/// Synchronous wrapper: buffers the stream and returns the full TextResponse.
504pub async fn generate_text_sync(
505    authorization: &CredentialsOrApiKey,
506    model: Text,
507    options: TextOptions,
508) -> crate::Result<TextResponse> {
509    socket::collect_text(generate_text(authorization, model, options).await?).await
510}
511
512/// Embedding (stays HTTP). With `group`, the group pays.
513pub async fn generate_embedding(
514    authorization: &CredentialsOrApiKey,
515    model: Embedding,
516    content: &str,
517    group: Option<&Group>,
518) -> crate::Result<EmbeddingResponse> {
519    let mut request = client()
520        .post(format!("{}/generative/embed", super::get_url()))
521        .header(
522            "Authorization",
523            match authorization {
524                CredentialsOrApiKey::Credentials(credentials) => {
525                    format!("Token {}", credentials.token)
526                }
527                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
528            },
529        );
530    if let Some(group) = group {
531        request = request.header("Group", &group.id);
532    }
533    let response = request
534        .json(&json!({ "model": model, "content": content }))
535        .send()
536        .await?;
537    if !response.status().is_success() {
538        return Err(Error::Message(format!(
539            "Failed to generate embedding: {}",
540            response.status().canonical_reason().unwrap_or_default()
541        )));
542    }
543    Ok(response.json().await?)
544}
545
546/// Decision (stays HTTP). Each question lists its options; every option comes back
547/// with its probability. A question the model declines is left out. With `group`,
548/// the group pays.
549pub async fn generate_decision(
550    authorization: &CredentialsOrApiKey,
551    model: Decision,
552    content: &[Content],
553    questions: &HashMap<String, Vec<String>>,
554    group: Option<&Group>,
555) -> crate::Result<HashMap<String, HashMap<String, f64>>> {
556    let messages = socket::prepare_messages(authorization, content).await?;
557    let mut request = client()
558        .post(format!("{}/generative/decision", super::get_url()))
559        .header(
560            "Authorization",
561            match authorization {
562                CredentialsOrApiKey::Credentials(credentials) => {
563                    format!("Token {}", credentials.token)
564                }
565                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
566            },
567        );
568    if let Some(group) = group {
569        request = request.header("Group", &group.id);
570    }
571    let response = request
572        .json(&json!({ "model": model, "messages": messages, "questions": questions }))
573        .send()
574        .await?;
575    Ok(ok(response).await?.json().await?)
576}
577
578fn media_extra(fields: Vec<(&str, Option<Value>)>) -> Map<String, Value> {
579    fields
580        .into_iter()
581        .filter_map(|(key, value)| value.map(|value| (key.to_string(), value)))
582        .collect()
583}
584
585/// The `options` argument of `generate_image`.
586#[derive(Debug, Clone, Default)]
587pub struct ImageOptions {
588    pub content: Option<Vec<Content>>,
589    pub size: Option<[u32; 2]>,
590    pub group: Option<Group>,
591}
592
593/// Image generation.
594pub async fn generate_image(
595    authorization: &CredentialsOrApiKey,
596    model: Image,
597    options: ImageOptions,
598) -> crate::Result<TextResponse> {
599    socket::generate_media(
600        authorization,
601        "/generative/image",
602        model.as_str(),
603        options.content,
604        options.group,
605        media_extra(vec![("size", options.size.map(|size| json!(size)))]),
606        "image/png",
607    )
608    .await
609}
610
611/// The `options` argument of `generate_video`.
612#[derive(Debug, Clone, Default)]
613pub struct VideoOptions {
614    pub content: Option<Vec<Content>>,
615    pub duration: Option<f64>,
616    pub size: Option<[u32; 2]>,
617    pub group: Option<Group>,
618}
619
620/// Video generation.
621pub async fn generate_video(
622    authorization: &CredentialsOrApiKey,
623    model: Video,
624    options: VideoOptions,
625) -> crate::Result<TextResponse> {
626    socket::generate_media(
627        authorization,
628        "/generative/video",
629        model.as_str(),
630        options.content,
631        options.group,
632        media_extra(vec![
633            ("duration", options.duration.map(Value::from)),
634            ("size", options.size.map(|size| json!(size))),
635        ]),
636        "video/mp4",
637    )
638    .await
639}
640
641/// The `options` argument of `generate_speech`.
642#[derive(Debug, Clone, Default)]
643pub struct SpeechOptions {
644    pub content: Option<Vec<Content>>,
645    pub voice: Option<Demographic>,
646    pub group: Option<Group>,
647}
648
649/// Speech generation.
650pub async fn generate_speech(
651    authorization: &CredentialsOrApiKey,
652    model: Speech,
653    options: SpeechOptions,
654) -> crate::Result<TextResponse> {
655    let voice = options.voice.map(serde_json::to_value).transpose()?;
656    socket::generate_media(
657        authorization,
658        "/generative/speech",
659        model.as_str(),
660        options.content,
661        options.group,
662        media_extra(vec![("voice", voice)]),
663        "audio/mpeg",
664    )
665    .await
666}
667
668/// The `options` argument of `generate_transcription`.
669#[derive(Debug, Clone, Default)]
670pub struct TranscriptionOptions {
671    pub content: Option<Vec<Content>>,
672    pub group: Option<Group>,
673}
674
675/// Transcription generation.
676pub async fn generate_transcription(
677    authorization: &CredentialsOrApiKey,
678    model: Transcription,
679    options: TranscriptionOptions,
680) -> crate::Result<TextResponse> {
681    socket::generate_media(
682        authorization,
683        "/generative/transcription",
684        model.as_str(),
685        options.content,
686        options.group,
687        Map::new(),
688        "application/octet-stream",
689    )
690    .await
691}
692
693/// The `options` argument of `generate_voice` and `generate_voice_sync`. `audio`
694/// is PCM16 at 16 kHz. Dropping the returned stream closes the socket.
695#[derive(Default)]
696pub struct VoiceOptions {
697    pub content: Option<Vec<Content>>,
698    pub audio: Option<BoxStream<'static, Vec<u8>>>,
699    pub tools: Option<ToolsOrTool>,
700    pub max_tools: Option<u32>,
701    pub voice: Option<PartialDemographic>,
702    pub group: Option<Group>,
703}
704
705/// Streaming voice generation.
706pub async fn generate_voice(
707    authorization: &CredentialsOrApiKey,
708    model: Voice,
709    options: VoiceOptions,
710) -> crate::Result<BoxStream<'static, VoiceEvent>> {
711    socket::stream_voice(
712        authorization,
713        "/generative/voice",
714        model.as_str(),
715        socket::VoiceOptions {
716            content: options.content,
717            audio: options.audio,
718            tools: options.tools,
719            max_tools: options.max_tools,
720            voice: options.voice,
721            memories: None,
722            group: options.group,
723        },
724    )
725    .await
726}
727
728pub async fn generate_voice_sync(
729    authorization: &CredentialsOrApiKey,
730    model: Voice,
731    options: VoiceOptions,
732) -> crate::Result<TextResponse> {
733    socket::collect_voice(
734        authorization,
735        generate_voice(authorization, model, options).await?,
736    )
737    .await
738}