Skip to main content

fauna_api/parrot/
routing.rs

1use std::collections::HashMap;
2use std::ops::Deref;
3
4use serde::de::DeserializeOwned;
5use serde::{Deserialize, Deserializer, Serialize};
6use serde_json::Value;
7
8use super::generative::{Decision, Embedding, Image, Speech, Text, Transcription, Video, Voice};
9use crate::authentification::CredentialsOrApiKey;
10use crate::error::Result;
11use crate::http::{client, encode, ok};
12
13/// One provider's settings in a garden.
14#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
15#[serde(rename_all = "camelCase")]
16pub struct ProviderConfig {
17    #[serde(default, skip_serializing_if = "Option::is_none")]
18    pub api_key: Option<String>,
19    #[serde(default, skip_serializing_if = "Option::is_none")]
20    pub system_prompt: Option<String>,
21    #[serde(default, skip_serializing_if = "Option::is_none")]
22    pub temperature: Option<f64>,
23}
24
25#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
26pub struct Garden {
27    #[serde(default)]
28    pub providers: HashMap<String, ProviderConfig>,
29    #[serde(default)]
30    pub memories: u32,
31}
32
33/// `Partial<Garden>` in the TypeScript SDK.
34#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
35pub struct PartialGarden {
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    pub providers: Option<HashMap<String, ProviderConfig>>,
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub memories: Option<u32>,
40}
41
42/// `Partial<Garden> & { provider?, providerConfig? }` in the TypeScript SDK.
43#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
44#[serde(rename_all = "camelCase")]
45pub struct GardenUpdate {
46    #[serde(flatten)]
47    pub garden: PartialGarden,
48    #[serde(default, skip_serializing_if = "Option::is_none")]
49    pub provider: Option<String>,
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub provider_config: Option<ProviderConfig>,
52}
53
54impl Deref for GardenUpdate {
55    type Target = PartialGarden;
56    fn deref(&self) -> &PartialGarden {
57        &self.garden
58    }
59}
60
61/// `Text | Embedding | Image | Video | Speech | Transcription | Voice | Decision`
62/// in the TypeScript SDK: any Parrot model.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
64#[serde(untagged)]
65pub enum TextOrEmbeddingOrImageOrVideoOrSpeechOrTranscriptionOrVoiceOrDecision {
66    Text(Text),
67    Embedding(Embedding),
68    Image(Image),
69    Video(Video),
70    Speech(Speech),
71    Transcription(Transcription),
72    Voice(Voice),
73    Decision(Decision),
74}
75
76impl TextOrEmbeddingOrImageOrVideoOrSpeechOrTranscriptionOrVoiceOrDecision {
77    fn as_str(self) -> &'static str {
78        match self {
79            Self::Text(model) => model.as_str(),
80            Self::Embedding(model) => model.as_str(),
81            Self::Image(model) => model.as_str(),
82            Self::Video(model) => model.as_str(),
83            Self::Speech(model) => model.as_str(),
84            Self::Transcription(model) => model.as_str(),
85            Self::Voice(model) => model.as_str(),
86            Self::Decision(model) => model.as_str(),
87        }
88    }
89}
90
91macro_rules! any_model {
92    ($($variant:ident),*) => {
93        $(
94            impl From<$variant> for TextOrEmbeddingOrImageOrVideoOrSpeechOrTranscriptionOrVoiceOrDecision {
95                fn from(model: $variant) -> Self {
96                    Self::$variant(model)
97                }
98            }
99        )*
100    };
101}
102
103any_model!(
104    Text,
105    Embedding,
106    Image,
107    Video,
108    Speech,
109    Transcription,
110    Voice,
111    Decision
112);
113
114/// `{ inputPer1M?, outputPer1M?, perUnit?, unit? }` in the TypeScript SDK.
115#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
116pub struct Price {
117    #[serde(
118        default,
119        rename = "inputPer1M",
120        skip_serializing_if = "Option::is_none"
121    )]
122    pub input_per_1m: Option<f64>,
123    #[serde(
124        default,
125        rename = "outputPer1M",
126        skip_serializing_if = "Option::is_none"
127    )]
128    pub output_per_1m: Option<f64>,
129    #[serde(default, rename = "perUnit", skip_serializing_if = "Option::is_none")]
130    pub per_unit: Option<f64>,
131    #[serde(default, skip_serializing_if = "Option::is_none")]
132    pub unit: Option<String>,
133}
134
135pub async fn get_price(
136    model: impl Into<TextOrEmbeddingOrImageOrVideoOrSpeechOrTranscriptionOrVoiceOrDecision>,
137) -> Result<Price> {
138    let response = client()
139        .get(format!(
140            "{}/routing/price/{}",
141            super::get_url(),
142            encode(model.into().as_str())
143        ))
144        .send()
145        .await?;
146    Ok(ok(response).await?.json().await?)
147}
148
149pub async fn get_dimensions(model: Embedding) -> Result<u32> {
150    let response = client()
151        .get(format!(
152            "{}/routing/dimensions/{}",
153            super::get_url(),
154            encode(model.as_str())
155        ))
156        .send()
157        .await?;
158    let text = ok(response).await?.text().await?;
159    Ok(text.trim().parse::<f64>().unwrap_or(f64::NAN) as u32)
160}
161
162#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
163#[serde(rename_all = "camelCase")]
164pub struct CatalogModel {
165    pub model: String,
166    pub name: String,
167    pub provider: String,
168    #[serde(rename = "baseURL")]
169    pub base_url: String,
170    pub icon: String,
171    #[serde(
172        default,
173        rename = "inputPer1M",
174        skip_serializing_if = "Option::is_none"
175    )]
176    pub input_per_1m: Option<f64>,
177    #[serde(
178        default,
179        rename = "outputPer1M",
180        skip_serializing_if = "Option::is_none"
181    )]
182    pub output_per_1m: Option<f64>,
183    #[serde(
184        default,
185        rename = "cachedInputPer1M",
186        skip_serializing_if = "Option::is_none"
187    )]
188    pub cached_input_per_1m: Option<f64>,
189    #[serde(default, skip_serializing_if = "Option::is_none")]
190    pub per_unit: Option<f64>,
191    #[serde(default, skip_serializing_if = "Option::is_none")]
192    pub unit: Option<String>,
193    #[serde(default, skip_serializing_if = "Option::is_none")]
194    pub kind: Option<String>,
195    #[serde(default, skip_serializing_if = "Option::is_none")]
196    pub dimensions: Option<u32>,
197    #[serde(default, skip_serializing_if = "Option::is_none")]
198    pub reasoning: Option<Vec<String>>,
199    /// Decision models: image input and the limits the model accepts.
200    #[serde(default, skip_serializing_if = "Option::is_none")]
201    pub images: Option<bool>,
202    #[serde(default, skip_serializing_if = "Option::is_none")]
203    pub max_questions: Option<u32>,
204    #[serde(default, skip_serializing_if = "Option::is_none")]
205    pub max_options: Option<u32>,
206    #[serde(default, skip_serializing_if = "Option::is_none")]
207    pub input_context_window: Option<u64>,
208}
209
210/// Every model Parrot offers, by family.
211#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
212pub struct Catalog {
213    #[serde(default)]
214    pub text: Vec<CatalogModel>,
215    #[serde(default)]
216    pub embedding: Vec<CatalogModel>,
217    #[serde(default)]
218    pub image: Vec<CatalogModel>,
219    #[serde(default)]
220    pub video: Vec<CatalogModel>,
221    #[serde(default)]
222    pub speech: Vec<CatalogModel>,
223    #[serde(default)]
224    pub transcription: Vec<CatalogModel>,
225    #[serde(default)]
226    pub voice: Vec<CatalogModel>,
227    #[serde(default)]
228    pub decision: Vec<CatalogModel>,
229}
230
231pub async fn get_all() -> Result<Catalog> {
232    let response = client()
233        .get(format!("{}/routing/all", super::get_url()))
234        .header("Content-Type", "application/json")
235        .send()
236        .await?;
237    Ok(ok(response).await?.json().await?)
238}
239
240/// A model id this SDK knows; one it doesn't reads as unset.
241fn known<'de, D: Deserializer<'de>, T: DeserializeOwned>(
242    deserializer: D,
243) -> std::result::Result<Option<T>, D::Error> {
244    Ok(serde_json::from_value(Value::deserialize(deserializer)?).ok())
245}
246
247/// `{ model, reasoning? }` in the TypeScript SDK.
248#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
249pub struct LastTextModel {
250    pub model: Text,
251    #[serde(default, skip_serializing_if = "Option::is_none")]
252    pub reasoning: Option<String>,
253}
254
255/// The model the caller starts from in each kind: the one they last picked in a model picker,
256/// else the kind's default. A model this SDK doesn't know reads as `None`. As the argument of
257/// `set_last_used_models`, the kinds to record.
258#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
259pub struct LastUsedModels {
260    #[serde(
261        default,
262        deserialize_with = "known",
263        skip_serializing_if = "Option::is_none"
264    )]
265    pub text: Option<LastTextModel>,
266    #[serde(
267        default,
268        deserialize_with = "known",
269        skip_serializing_if = "Option::is_none"
270    )]
271    pub embedding: Option<Embedding>,
272    #[serde(
273        default,
274        deserialize_with = "known",
275        skip_serializing_if = "Option::is_none"
276    )]
277    pub image: Option<Image>,
278    #[serde(
279        default,
280        deserialize_with = "known",
281        skip_serializing_if = "Option::is_none"
282    )]
283    pub video: Option<Video>,
284    #[serde(
285        default,
286        deserialize_with = "known",
287        skip_serializing_if = "Option::is_none"
288    )]
289    pub speech: Option<Speech>,
290    #[serde(
291        default,
292        deserialize_with = "known",
293        skip_serializing_if = "Option::is_none"
294    )]
295    pub transcription: Option<Transcription>,
296    #[serde(
297        default,
298        deserialize_with = "known",
299        skip_serializing_if = "Option::is_none"
300    )]
301    pub voice: Option<Voice>,
302    #[serde(
303        default,
304        deserialize_with = "known",
305        skip_serializing_if = "Option::is_none"
306    )]
307    pub decision: Option<Decision>,
308}
309
310/// The model you start from in each kind: the one you last picked in a model picker, else the
311/// kind's default (the cheapest Google model, else the cheapest). Generating never changes it;
312/// `set_last_used_models` does.
313pub async fn get_last_used_models(authorization: &CredentialsOrApiKey) -> Result<LastUsedModels> {
314    let response = client()
315        .get(format!("{}/routing/last", super::get_url()))
316        .header(
317            "Authorization",
318            match authorization {
319                CredentialsOrApiKey::Credentials(credentials) => {
320                    format!("Token {}", credentials.token)
321                }
322                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
323            },
324        )
325        .send()
326        .await?;
327    Ok(ok(response).await?.json().await?)
328}
329
330/// Records the models you picked. Each kind given replaces that kind; a text model replaces its
331/// reasoning too, clearing it when none is given. A model outside its kind, or a reasoning the
332/// model doesn't take, is refused.
333pub async fn set_last_used_models(
334    authorization: &CredentialsOrApiKey,
335    models: &LastUsedModels,
336) -> Result<()> {
337    let response = client()
338        .put(format!("{}/routing/last", super::get_url()))
339        .header(
340            "Authorization",
341            match authorization {
342                CredentialsOrApiKey::Credentials(credentials) => {
343                    format!("Token {}", credentials.token)
344                }
345                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
346            },
347        )
348        .json(models)
349        .send()
350        .await?;
351    ok(response).await?;
352    Ok(())
353}
354
355/// `{ input, output }` in the TypeScript SDK: text tokens spent.
356#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
357pub struct TokenCost {
358    #[serde(default)]
359    pub input: f64,
360    #[serde(default)]
361    pub output: f64,
362}
363
364/// `{ cost }` in the TypeScript SDK.
365#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
366pub struct Cost {
367    #[serde(default)]
368    pub cost: f64,
369}
370
371/// The caller's usage by family: `(model, day, spend)` rows.
372#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
373pub struct ModelUsage {
374    #[serde(default)]
375    pub text: Vec<(String, String, TokenCost)>,
376    #[serde(default)]
377    pub embedding: Vec<(String, String, Cost)>,
378    #[serde(default)]
379    pub image: Vec<(String, String, Cost)>,
380    #[serde(default)]
381    pub video: Vec<(String, String, Cost)>,
382    #[serde(default)]
383    pub speech: Vec<(String, String, Cost)>,
384    #[serde(default)]
385    pub transcription: Vec<(String, String, Cost)>,
386    #[serde(default)]
387    pub voice: Vec<(String, String, Cost)>,
388    #[serde(default)]
389    pub decision: Vec<(String, String, Cost)>,
390}
391
392pub async fn get_usage(authorization: &CredentialsOrApiKey) -> Result<ModelUsage> {
393    let response = client()
394        .get(format!("{}/routing/usage", super::get_url()))
395        .header(
396            "Authorization",
397            match authorization {
398                CredentialsOrApiKey::Credentials(credentials) => {
399                    format!("Token {}", credentials.token)
400                }
401                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
402            },
403        )
404        .send()
405        .await?;
406    Ok(ok(response).await?.json().await?)
407}
408
409pub async fn get_garden(authorization: &CredentialsOrApiKey) -> Result<Garden> {
410    let response = client()
411        .get(format!("{}/routing/garden", super::get_url()))
412        .header(
413            "Authorization",
414            match authorization {
415                CredentialsOrApiKey::Credentials(credentials) => {
416                    format!("Token {}", credentials.token)
417                }
418                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
419            },
420        )
421        .send()
422        .await?;
423    Ok(ok(response).await?.json().await?)
424}
425
426pub async fn set_garden(authorization: &CredentialsOrApiKey, update: &GardenUpdate) -> Result<()> {
427    let response = client()
428        .put(format!("{}/routing/garden", super::get_url()))
429        .header(
430            "Authorization",
431            match authorization {
432                CredentialsOrApiKey::Credentials(credentials) => {
433                    format!("Token {}", credentials.token)
434                }
435                CredentialsOrApiKey::ApiKey(key) => format!("ApiKey {}", key.id),
436            },
437        )
438        .json(update)
439        .send()
440        .await?;
441    ok(response).await?;
442    Ok(())
443}