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