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