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, PartialApiKey, 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        GrokVoiceTranscribe2_0 = "grok-voice-transcribe-2.0",
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/// A body written in HTML, such as an email's. Chat UIs draw it as it is; models read its text.
177#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
178pub struct HtmlPart {
179    #[serde(default)]
180    pub html: String,
181}
182
183#[derive(Debug, Clone)]
184pub struct File {
185    pub file: crate::drive::File,
186}
187
188#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
189#[serde(rename_all = "lowercase")]
190pub enum InvocationStatus {
191    Success,
192    Error,
193}
194
195#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
196pub struct Invocation {
197    #[serde(default, skip_serializing_if = "Option::is_none")]
198    pub id: Option<String>,
199    #[serde(default, skip_serializing_if = "Option::is_none")]
200    pub args: Option<Map<String, Value>>,
201    pub name: String,
202    #[serde(default, skip_serializing_if = "Option::is_none")]
203    pub status: Option<InvocationStatus>,
204    #[serde(default, skip_serializing_if = "Option::is_none")]
205    pub result: Option<String>,
206}
207
208#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
209pub struct Result {
210    pub id: String,
211    pub result: String,
212}
213
214/// A reaction to the message at transcript `position`. It travels as its own
215/// USER message; chat UIs fold it onto that message instead of drawing a bubble.
216/// `on: false` takes the reaction back; the latest one per person, message and
217/// emoji wins.
218#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
219pub struct Reaction {
220    pub emoji: String,
221    pub position: u32,
222    pub on: bool,
223}
224
225/// One part of a message. On the wire each carries its `type`; a FILE part goes
226/// up as a reference (a Drive path or an access code), never its bytes.
227#[derive(Debug, Clone)]
228#[allow(clippy::large_enum_variant)]
229pub enum Part {
230    Text(TextPart),
231    Html(HtmlPart),
232    File(File),
233    Invocation(Invocation),
234    Result(Result),
235    Reaction(Reaction),
236}
237
238pub(crate) fn file_ref(file: &crate::drive::File) -> Value {
239    let mut wire = Map::new();
240    wire.insert("type".to_string(), Value::from("FILE"));
241    wire.insert("name".to_string(), Value::from(file.name()));
242    wire.insert(
243        "contentType".to_string(),
244        Value::from(file.content_type.as_str()),
245    );
246    match &file.authorization {
247        DriveAuthorization::AccessCode { access_code, .. } => {
248            wire.insert("accessCode".to_string(), Value::from(access_code.as_str()));
249        }
250        DriveAuthorization::Path { path, group, .. }
251        | DriveAuthorization::Repository { path, group, .. } => {
252            wire.insert("path".to_string(), Value::from(path.as_str()));
253            if let Some(group) = group {
254                wire.insert("group".to_string(), Value::from(group.as_str()));
255            }
256        }
257    }
258    Value::Object(wire)
259}
260
261fn tagged(kind: &str, value: impl Serialize) -> Value {
262    let mut wire = Map::new();
263    wire.insert("type".to_string(), Value::from(kind));
264    if let Ok(Value::Object(fields)) = serde_json::to_value(value) {
265        wire.extend(fields);
266    }
267    Value::Object(wire)
268}
269
270impl Part {
271    /// The part as it goes over the wire, FILE parts as references.
272    pub(crate) fn wire(&self) -> Value {
273        match self {
274            Part::Text(part) => tagged("TEXT", part),
275            Part::Html(part) => tagged("HTML", part),
276            Part::File(part) => file_ref(&part.file),
277            Part::Invocation(part) => tagged("INVOCATION", part),
278            Part::Result(part) => tagged("RESULT", part),
279            Part::Reaction(part) => tagged("REACTION", part),
280        }
281    }
282
283    /// Every part but FILE, which needs the caller's authorization to open.
284    pub(crate) fn from_json(json: &Value) -> Option<Part> {
285        match json["type"].as_str()? {
286            "TEXT" => serde_json::from_value(json.clone()).ok().map(Part::Text),
287            "HTML" => serde_json::from_value(json.clone()).ok().map(Part::Html),
288            "INVOCATION" => serde_json::from_value(json.clone())
289                .ok()
290                .map(Part::Invocation),
291            "RESULT" => serde_json::from_value(json.clone()).ok().map(Part::Result),
292            "REACTION" => serde_json::from_value(json.clone())
293                .ok()
294                .map(Part::Reaction),
295            _ => None,
296        }
297    }
298}
299
300impl Serialize for Part {
301    fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
302        self.wire().serialize(serializer)
303    }
304}
305
306/// `'BLOCKING' | 'NON_BLOCKING'` in the TypeScript SDK.
307#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
308#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
309pub enum FunctionBehavior {
310    Blocking,
311    NonBlocking,
312}
313
314#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
315pub struct Function {
316    pub name: String,
317    pub parameters: Schema,
318    #[serde(default, skip_serializing_if = "Option::is_none")]
319    pub description: Option<String>,
320
321    #[serde(default, skip_serializing_if = "Option::is_none")]
322    pub default: Option<Value>,
323    #[serde(default, skip_serializing_if = "Option::is_none")]
324    pub example: Option<Value>,
325
326    #[serde(default, skip_serializing_if = "Option::is_none")]
327    pub behavior: Option<FunctionBehavior>,
328}
329
330/// What a tool runs when the model calls it, given the call's arguments.
331pub type ToolEvaluate =
332    Arc<dyn Fn(Value) -> BoxFuture<'static, crate::Result<String>> + Send + Sync>;
333
334/// The line a tool adds to a prompt, given the call's arguments.
335pub type ToolInstruction = Arc<dyn Fn(&Value) -> String + Send + Sync>;
336
337#[derive(Clone)]
338pub struct Tool {
339    pub function: Function,
340
341    pub evaluate: ToolEvaluate,
342
343    pub instruction: Option<ToolInstruction>,
344}
345
346impl fmt::Debug for Tool {
347    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
348        f.debug_struct("Tool")
349            .field("function", &self.function)
350            .finish_non_exhaustive()
351    }
352}
353
354/// `Tool[] | Tool` in the TypeScript SDK: a single tool forces it, a list lets
355/// the model choose.
356#[derive(Debug, Clone)]
357#[allow(clippy::large_enum_variant)]
358pub enum ToolsOrTool {
359    Tools(Vec<Tool>),
360    Tool(Tool),
361}
362
363/// Who wrote a message: a person, an agent posting with an API key (only its `name`, never
364/// its id), an app's own agent (`'MODEL'`, such as an inbox agent), or an outside address
365/// such as a phone number or an email. Parrot's own model replies have none; their `model`
366/// says which model wrote them.
367#[derive(Debug, Clone, PartialEq)]
368pub enum Author {
369    Profile(Profile),
370    ApiKey(PartialApiKey),
371    Model,
372    Address(String),
373}
374
375impl Author {
376    pub fn from_json(json: &Value) -> Option<Author> {
377        match json {
378            Value::String(text) if text == "MODEL" => Some(Author::Model),
379            Value::String(text) if !text.is_empty() => Some(Author::Address(text.clone())),
380            Value::Object(_) => Profile::from_json(json).map(Author::Profile).or_else(|| {
381                json["name"].as_str().map(|name| {
382                    Author::ApiKey(PartialApiKey {
383                        name: Some(name.to_string()),
384                        ..Default::default()
385                    })
386                })
387            }),
388            _ => None,
389        }
390    }
391}
392
393impl Serialize for Author {
394    fn serialize<S: serde::Serializer>(
395        &self,
396        serializer: S,
397    ) -> std::result::Result<S::Ok, S::Error> {
398        match self {
399            Author::Profile(profile) => profile.serialize(serializer),
400            Author::ApiKey(key) => json!({ "name": key.name }).serialize(serializer),
401            Author::Model => serializer.serialize_str("MODEL"),
402            Author::Address(address) => serializer.serialize_str(address),
403        }
404    }
405}
406
407impl<'de> Deserialize<'de> for Author {
408    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
409        let json = Value::deserialize(deserializer)?;
410        Author::from_json(&json).ok_or_else(|| serde::de::Error::custom("not an author"))
411    }
412}
413
414#[derive(Debug, Clone)]
415pub struct Content {
416    pub parts: Vec<Part>,
417    pub role: Role,
418    pub created_at: DateTime<Utc>,
419    pub author: Option<Author>,
420    /// The model that wrote a MODEL turn.
421    pub model: Option<Text>,
422}
423
424impl Content {
425    /// A message off the wire. `file` turns each FILE part into a file; without it FILE
426    /// parts are left out, since a file needs a way to be read.
427    pub fn from_json(json: &Value, file: Option<&dyn Fn(&Value) -> Part>) -> Content {
428        Content {
429            parts: json["parts"]
430                .as_array()
431                .into_iter()
432                .flatten()
433                .filter_map(|part| match (part["type"].as_str(), file) {
434                    (Some("FILE"), Some(file)) => Some(file(part)),
435                    (Some("FILE"), None) => None,
436                    _ => Part::from_json(part),
437                })
438                .collect(),
439            role: serde_json::from_value(json["role"].clone()).unwrap_or(Role::User),
440            created_at: crate::tickets::parse_date(&json["createdAt"]).unwrap_or_default(),
441            author: Author::from_json(&json["author"]),
442            model: serde_json::from_value(json["model"].clone()).ok(),
443        }
444    }
445}
446
447/// `{ promptTokens, completionTokens }` in the TypeScript SDK.
448#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
449#[serde(rename_all = "camelCase")]
450pub struct Usage {
451    #[serde(default)]
452    pub prompt_tokens: u64,
453    #[serde(default)]
454    pub completion_tokens: u64,
455}
456
457#[derive(Debug, Clone)]
458pub struct TextResponse {
459    pub content: Content,
460    pub usage: Usage,
461}
462
463/// `{ promptTokens }` in the TypeScript SDK.
464#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
465#[serde(rename_all = "camelCase")]
466pub struct EmbeddingUsage {
467    #[serde(default)]
468    pub prompt_tokens: u64,
469}
470
471#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
472pub struct EmbeddingResponse {
473    pub embedding: Vec<f64>,
474    pub usage: EmbeddingUsage,
475}
476
477#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
478#[serde(tag = "event", rename_all = "snake_case")]
479pub enum StreamEvent {
480    Text {
481        #[serde(default)]
482        delta: String,
483    },
484    ToolCall {
485        id: String,
486        name: String,
487        #[serde(default)]
488        args: Map<String, Value>,
489        #[serde(default, skip_serializing_if = "Option::is_none")]
490        server: Option<bool>,
491    },
492    Done {
493        #[serde(default)]
494        usage: Usage,
495    },
496    Error {
497        message: String,
498        #[serde(default, skip_serializing_if = "Option::is_none")]
499        code: Option<String>,
500    },
501}
502
503fn pcm() -> String {
504    "audio/pcm".to_string()
505}
506
507fn audio_out<S: Serializer>(delta: &[u8], serializer: S) -> std::result::Result<S::Ok, S::Error> {
508    serializer.serialize_str(&STANDARD.encode(delta))
509}
510
511/// Audio arrives base64 encoded, or as a list of byte values.
512fn audio_in<'de, D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Vec<u8>, D::Error> {
513    Ok(socket::audio_delta(&Value::deserialize(deserializer)?))
514}
515
516#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
517#[serde(tag = "event", rename_all = "snake_case")]
518pub enum VoiceEvent {
519    Audio {
520        #[serde(serialize_with = "audio_out", deserialize_with = "audio_in")]
521        delta: Vec<u8>,
522        #[serde(rename = "contentType", default = "pcm")]
523        content_type: String,
524    },
525    InputTranscript {
526        #[serde(default)]
527        delta: String,
528    },
529    OutputTranscript {
530        #[serde(default)]
531        delta: String,
532    },
533    ToolCall {
534        id: String,
535        name: String,
536        #[serde(default)]
537        args: Map<String, Value>,
538    },
539    SpeechStarted,
540    SpeechStopped,
541    Done {
542        #[serde(default)]
543        usage: Usage,
544    },
545    Error {
546        message: String,
547        #[serde(default, skip_serializing_if = "Option::is_none")]
548        code: Option<String>,
549    },
550}
551
552/// The `options` argument of `generate_text` and `generate_text_sync`. Dropping
553/// the returned stream closes the socket, which stops the reply.
554#[derive(Debug, Clone, Default)]
555pub struct TextOptions {
556    pub content: Option<Vec<Content>>,
557    pub tools: Option<ToolsOrTool>,
558    pub max_tools: Option<u32>,
559    pub reasoning: Option<String>,
560    pub group: Option<Group>,
561}
562
563/// Streaming text generation. A singular Tool forces it; an array lets the model choose.
564pub async fn generate_text(
565    authorization: &CredentialsOrApiKey,
566    model: Text,
567    options: TextOptions,
568) -> crate::Result<BoxStream<'static, StreamEvent>> {
569    socket::stream_text(
570        authorization,
571        "/generative/text",
572        model.as_str(),
573        socket::TextOptions {
574            content: options.content,
575            tools: options.tools,
576            max_tools: options.max_tools,
577            memories: None,
578            reasoning: options.reasoning,
579            group: options.group,
580        },
581    )
582    .await
583}
584
585/// Synchronous wrapper: buffers the stream and returns the full TextResponse.
586pub async fn generate_text_sync(
587    authorization: &CredentialsOrApiKey,
588    model: Text,
589    options: TextOptions,
590) -> crate::Result<TextResponse> {
591    socket::collect_text(generate_text(authorization, model, options).await?).await
592}
593
594/// Embedding (stays HTTP). With `group`, the group pays.
595pub async fn generate_embedding(
596    authorization: &CredentialsOrApiKey,
597    model: Embedding,
598    content: &str,
599    group: Option<&Group>,
600) -> crate::Result<EmbeddingResponse> {
601    let mut request = client()
602        .post(format!("{}/generative/embed", super::get_url()))
603        .header(
604            "Authorization",
605            match authorization {
606                CredentialsOrApiKey::Credentials(credentials) => {
607                    format!("Token {}", credentials.token)
608                }
609                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
610            },
611        );
612    if let Some(group) = group {
613        request = request.header("Group", &group.id);
614    }
615    let response = request
616        .json(&json!({ "model": model, "content": content }))
617        .send()
618        .await?;
619    if !response.status().is_success() {
620        return Err(Error::Message(format!(
621            "Failed to generate embedding: {}",
622            response.status().canonical_reason().unwrap_or_default()
623        )));
624    }
625    Ok(response.json().await?)
626}
627
628/// Decision (stays HTTP). Each question lists its options; every option comes back
629/// with its probability. A question the model declines is left out. With `group`,
630/// the group pays.
631pub async fn generate_decision(
632    authorization: &CredentialsOrApiKey,
633    model: Decision,
634    content: &[Content],
635    questions: &HashMap<String, Vec<String>>,
636    group: Option<&Group>,
637) -> crate::Result<HashMap<String, HashMap<String, f64>>> {
638    let messages = socket::prepare_messages(authorization, content).await?;
639    let mut request = client()
640        .post(format!("{}/generative/decision", super::get_url()))
641        .header(
642            "Authorization",
643            match authorization {
644                CredentialsOrApiKey::Credentials(credentials) => {
645                    format!("Token {}", credentials.token)
646                }
647                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
648            },
649        );
650    if let Some(group) = group {
651        request = request.header("Group", &group.id);
652    }
653    let response = request
654        .json(&json!({ "model": model, "messages": messages, "questions": questions }))
655        .send()
656        .await?;
657    Ok(ok(response).await?.json().await?)
658}
659
660fn media_extra(fields: Vec<(&str, Option<Value>)>) -> Map<String, Value> {
661    fields
662        .into_iter()
663        .filter_map(|(key, value)| value.map(|value| (key.to_string(), value)))
664        .collect()
665}
666
667/// The `options` argument of `generate_image`.
668#[derive(Debug, Clone, Default)]
669pub struct ImageOptions {
670    pub content: Option<Vec<Content>>,
671    pub size: Option<[u32; 2]>,
672    pub group: Option<Group>,
673}
674
675/// Image generation.
676pub async fn generate_image(
677    authorization: &CredentialsOrApiKey,
678    model: Image,
679    options: ImageOptions,
680) -> crate::Result<TextResponse> {
681    socket::generate_media(
682        authorization,
683        "/generative/image",
684        model.as_str(),
685        options.content,
686        options.group,
687        media_extra(vec![("size", options.size.map(|size| json!(size)))]),
688        "image/png",
689    )
690    .await
691}
692
693/// The `options` argument of `generate_video`.
694#[derive(Debug, Clone, Default)]
695pub struct VideoOptions {
696    pub content: Option<Vec<Content>>,
697    pub duration: Option<f64>,
698    pub size: Option<[u32; 2]>,
699    pub group: Option<Group>,
700}
701
702/// Video generation.
703pub async fn generate_video(
704    authorization: &CredentialsOrApiKey,
705    model: Video,
706    options: VideoOptions,
707) -> crate::Result<TextResponse> {
708    socket::generate_media(
709        authorization,
710        "/generative/video",
711        model.as_str(),
712        options.content,
713        options.group,
714        media_extra(vec![
715            ("duration", options.duration.map(Value::from)),
716            ("size", options.size.map(|size| json!(size))),
717        ]),
718        "video/mp4",
719    )
720    .await
721}
722
723/// The `options` argument of `generate_speech`.
724#[derive(Debug, Clone, Default)]
725pub struct SpeechOptions {
726    pub content: Option<Vec<Content>>,
727    pub voice: Option<Demographic>,
728    pub group: Option<Group>,
729}
730
731/// Speech generation.
732pub async fn generate_speech(
733    authorization: &CredentialsOrApiKey,
734    model: Speech,
735    options: SpeechOptions,
736) -> crate::Result<TextResponse> {
737    let voice = options.voice.map(serde_json::to_value).transpose()?;
738    socket::generate_media(
739        authorization,
740        "/generative/speech",
741        model.as_str(),
742        options.content,
743        options.group,
744        media_extra(vec![("voice", voice)]),
745        "audio/mpeg",
746    )
747    .await
748}
749
750/// The `options` argument of `generate_transcription`.
751#[derive(Debug, Clone, Default)]
752pub struct TranscriptionOptions {
753    pub content: Option<Vec<Content>>,
754    pub group: Option<Group>,
755}
756
757/// Transcription generation.
758pub async fn generate_transcription(
759    authorization: &CredentialsOrApiKey,
760    model: Transcription,
761    options: TranscriptionOptions,
762) -> crate::Result<TextResponse> {
763    socket::generate_media(
764        authorization,
765        "/generative/transcription",
766        model.as_str(),
767        options.content,
768        options.group,
769        Map::new(),
770        "application/octet-stream",
771    )
772    .await
773}
774
775/// The `options` argument of `generate_voice` and `generate_voice_sync`. `audio`
776/// is PCM16 at 16 kHz. Dropping the returned stream closes the socket.
777#[derive(Default)]
778pub struct VoiceOptions {
779    pub content: Option<Vec<Content>>,
780    pub audio: Option<BoxStream<'static, Vec<u8>>>,
781    pub notes: Option<BoxStream<'static, String>>,
782    pub tools: Option<ToolsOrTool>,
783    pub max_tools: Option<u32>,
784    pub voice: Option<PartialDemographic>,
785    pub group: Option<Group>,
786}
787
788/// Streaming voice generation. Each of `notes` tells the model something to act on now.
789pub async fn generate_voice(
790    authorization: &CredentialsOrApiKey,
791    model: Voice,
792    options: VoiceOptions,
793) -> crate::Result<BoxStream<'static, VoiceEvent>> {
794    socket::stream_voice(
795        authorization,
796        "/generative/voice",
797        model.as_str(),
798        socket::VoiceOptions {
799            content: options.content,
800            audio: options.audio,
801            notes: options.notes,
802            tools: options.tools,
803            max_tools: options.max_tools,
804            voice: options.voice,
805            memories: None,
806            group: options.group,
807        },
808    )
809    .await
810}
811
812pub async fn generate_voice_sync(
813    authorization: &CredentialsOrApiKey,
814    model: Voice,
815    options: VoiceOptions,
816) -> crate::Result<TextResponse> {
817    socket::collect_voice(
818        authorization,
819        generate_voice(authorization, model, options).await?,
820    )
821    .await
822}