Skip to main content

otter_ai/
types.rs

1use serde::{Deserialize, Serialize};
2use std::collections::HashMap;
3use uuid::Uuid;
4
5pub type Api = String;
6pub type ProviderId = String;
7pub type ProviderHeaders = HashMap<String, String>;
8pub type ProviderEnv = HashMap<String, String>;
9
10#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
11pub enum KnownApi {
12    OpenaiCompletions,
13    MistralConversations,
14    OpenaiResponses,
15    AzureOpenaiResponses,
16    OpenaiCodexResponses,
17    AnthropicMessages,
18    BedrockConverseStream,
19    GoogleGenerativeAi,
20    GoogleVertex,
21    PiMessages,
22}
23
24// ---- Cost tier (TS: model.cost.tiers) ----
25#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
26pub struct CostTier {
27    pub input_tokens_above: u64,
28    pub input_per_million: f64,
29    pub output_per_million: f64,
30    pub cache_read_per_million: f64,
31    pub cache_write_per_million: f64,
32}
33
34#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
35pub struct ModelCostRates {
36    pub input_per_million: Option<f64>,
37    pub output_per_million: Option<f64>,
38    pub input_cache_read_per_million: Option<f64>,
39    pub input_cache_write_per_million: Option<f64>,
40    #[serde(default, skip_serializing_if = "Vec::is_empty")]
41    pub tiers: Vec<CostTier>,
42}
43
44#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
45pub struct UsageCost {
46    pub input: f64,
47    pub output: f64,
48    pub cache_read: f64,
49    pub cache_write: f64,
50    pub total: f64,
51}
52
53#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
54pub struct Usage {
55    pub input: u64,
56    pub output: u64,
57    pub cache_read: u64,
58    pub cache_write: u64,
59    /// Reasoning tokens reported via `output_tokens_details.reasoning_tokens`.
60    #[serde(default)]
61    pub reasoning: u64,
62    pub total_tokens: u64,
63    pub cost: UsageCost,
64}
65
66#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
67pub enum ModelThinkingLevel {
68    #[default]
69    None,
70    Low,
71    Medium,
72    High,
73}
74
75#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
76pub struct Model {
77    pub id: String,
78    pub provider_id: ProviderId,
79    pub name: String,
80    pub api: Api,
81    pub max_input_tokens: Option<u64>,
82    pub max_output_tokens: Option<u64>,
83    pub supports_images: bool,
84    pub supports_audio: bool,
85    pub supports_video: bool,
86    pub supports_pdf: bool,
87    pub supports_tool_calling: bool,
88    pub supports_structured_output: bool,
89    pub supports_system_prompt: bool,
90    pub thinking: ModelThinkingLevel,
91    pub reasoning: bool,
92    pub cost_rates: ModelCostRates,
93    pub context_window: Option<u64>,
94    pub default_temperature: Option<f32>,
95    /// Provider-specific thinking-level remapping (TS: `thinkingLevelMap`),
96    /// e.g. `{ "minimal": "low", "xhigh": "xhigh" }` for Codex models.
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub thinking_level_map: Option<std::collections::HashMap<String, String>>,
99}
100
101#[derive(Debug, Clone, Serialize, Deserialize)]
102pub struct Tool {
103    pub name: String,
104    #[serde(default, skip_serializing_if = "Option::is_none")]
105    pub description: Option<String>,
106    pub parameters: serde_json::Value,
107    /// TS: `constrainedSampling` — grammar constrained sampling config used
108    /// by Codex models; grammar tools stream as `custom_tool_call` items.
109    #[serde(default, skip_serializing_if = "Option::is_none")]
110    pub constrained_sampling: Option<ToolConstrainedSampling>,
111}
112
113/// TS: `ToolConstrainedSampling` (only `type: "grammar"` is honoured).
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
115pub struct ToolConstrainedSampling {
116    #[serde(rename = "type")]
117    pub sampling_type: String,
118    #[serde(default, skip_serializing_if = "Option::is_none")]
119    pub variants: Option<ToolGrammarVariants>,
120}
121
122#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
123pub struct ToolGrammarVariants {
124    #[serde(default, skip_serializing_if = "Option::is_none")]
125    pub openai_lark: Option<String>,
126    #[serde(default, skip_serializing_if = "Option::is_none")]
127    pub openai_regex: Option<String>,
128}
129
130#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
131pub struct ImageContent {
132    #[serde(rename = "type")]
133    pub content_type: String,
134    pub data: String,
135    #[serde(default, skip_serializing_if = "Option::is_none")]
136    pub mime_type: Option<String>,
137}
138
139#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
140#[serde(tag = "type", rename_all = "camelCase")]
141pub enum ContentBlock {
142    Text {
143        text: String,
144        /// Encoded message identity for OpenAI Responses replay
145        /// (TS: `textSignature`, `{"v":1,"id":"msg_…"}` shape). Lets the
146        /// assistant message round-trip with its server-assigned item id so
147        /// multi-turn prompt-cache affinity and websocket delta
148        /// continuations keep matching prefixes.
149        #[serde(default, skip_serializing_if = "Option::is_none")]
150        text_signature: Option<String>,
151    },
152    Thinking {
153        thinking: String,
154        #[serde(default, skip_serializing_if = "Option::is_none")]
155        signature: Option<String>,
156    },
157    ToolCall {
158        id: String,
159        name: String,
160        #[serde(default)]
161        arguments: serde_json::Value,
162    },
163    ToolResult {
164        tool_call_id: String,
165        tool_name: String,
166        content: Vec<ContentBlock>,
167        #[serde(default)]
168        is_error: bool,
169    },
170    Image(ImageContent),
171}
172
173fn default_timestamp() -> i64 {
174    chrono::Utc::now().timestamp_millis()
175}
176
177#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
178#[serde(tag = "role", rename_all = "camelCase")]
179pub enum Message {
180    #[serde(rename = "user")]
181    User {
182        content: Vec<ContentBlock>,
183        #[serde(default = "default_timestamp")]
184        timestamp: i64,
185    },
186    #[serde(rename = "assistant")]
187    Assistant {
188        content: Vec<ContentBlock>,
189        api: Api,
190        provider: ProviderId,
191        model: Option<String>,
192        #[serde(default)]
193        usage: Usage,
194        #[serde(default, skip_serializing_if = "Option::is_none")]
195        stop_reason: Option<String>,
196        #[serde(default, skip_serializing_if = "Option::is_none")]
197        error_message: Option<String>,
198        #[serde(default, skip_serializing_if = "Option::is_none")]
199        response_id: Option<String>,
200        /// Codex `response.end_turn` flag (TS: `endTurn`).
201        #[serde(default, skip_serializing_if = "Option::is_none")]
202        end_turn: Option<bool>,
203        #[serde(default = "default_timestamp")]
204        timestamp: i64,
205    },
206    #[serde(rename = "toolResult")]
207    ToolResult {
208        tool_call_id: String,
209        tool_name: String,
210        content: Vec<ContentBlock>,
211        #[serde(default)]
212        is_error: bool,
213        #[serde(default = "default_timestamp")]
214        timestamp: i64,
215    },
216    #[serde(rename = "system")]
217    System {
218        content: Vec<ContentBlock>,
219        #[serde(default = "default_timestamp")]
220        timestamp: i64,
221    },
222}
223
224// Allow constructing a Message from a simple string (TS: user content can be string)
225impl Message {
226    pub fn user_from_string<S: Into<String>>(text: S) -> Self {
227        Message::User {
228            content: vec![ContentBlock::Text {
229                text: text.into(),
230                text_signature: None,
231            }],
232            timestamp: default_timestamp(),
233        }
234    }
235
236    pub fn assistant_default(api: Api, provider: ProviderId) -> Self {
237        Message::Assistant {
238            content: vec![],
239            api,
240            provider,
241            model: None,
242            usage: Usage::default(),
243            stop_reason: None,
244            error_message: None,
245            response_id: None,
246            end_turn: None,
247            timestamp: default_timestamp(),
248        }
249    }
250
251    pub fn with_content(mut self, content: Vec<ContentBlock>) -> Self {
252        if let Message::Assistant {
253            content: ref mut c, ..
254        } = self
255        {
256            *c = content;
257        }
258        self
259    }
260
261    pub fn with_model(mut self, model: Option<String>) -> Self {
262        if let Message::Assistant {
263            model: ref mut m, ..
264        } = self
265        {
266            *m = model;
267        }
268        self
269    }
270
271    pub fn with_usage(mut self, usage: Usage) -> Self {
272        if let Message::Assistant {
273            usage: ref mut u, ..
274        } = self
275        {
276            *u = usage;
277        }
278        self
279    }
280
281    pub fn with_stop_reason(mut self, reason: Option<String>) -> Self {
282        if let Message::Assistant {
283            stop_reason: ref mut sr,
284            ..
285        } = self
286        {
287            *sr = reason;
288        }
289        self
290    }
291
292    pub fn with_error_message<S: Into<String>>(mut self, msg: S) -> Self {
293        if let Message::Assistant {
294            ref mut error_message,
295            ..
296        } = self
297        {
298            *error_message = Some(msg.into());
299        }
300        self
301    }
302
303    pub fn stop_reason(&self) -> Option<&str> {
304        match self {
305            Message::Assistant { stop_reason, .. } => stop_reason.as_deref(),
306            _ => None,
307        }
308    }
309}
310
311#[derive(Debug, Clone, Serialize, Deserialize, Default)]
312pub struct Context {
313    #[serde(default, skip_serializing_if = "Option::is_none")]
314    pub system_prompt: Option<String>,
315    #[serde(default)]
316    pub messages: Vec<Message>,
317    #[serde(default)]
318    pub tools: Vec<Tool>,
319    #[serde(default, skip_serializing_if = "Option::is_none")]
320    pub tool_choice: Option<ToolChoice>,
321    #[serde(default, skip_serializing_if = "Option::is_none")]
322    pub temperature: Option<f32>,
323    #[serde(default, skip_serializing_if = "Option::is_none")]
324    pub max_tokens: Option<u64>,
325    #[serde(default, skip_serializing_if = "Option::is_none")]
326    pub response_format: Option<ResponseFormat>,
327}
328
329#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
330#[serde(tag = "type", rename_all = "camelCase")]
331pub enum ToolChoice {
332    Auto,
333    None,
334    Required,
335    Tool { name: String },
336}
337
338#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
339pub struct JsonSchemaFormat {
340    pub name: String,
341    #[serde(default, skip_serializing_if = "Option::is_none")]
342    pub schema: Option<serde_json::Value>,
343    #[serde(default)]
344    pub strict: bool,
345}
346
347#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
348#[serde(tag = "type", rename_all = "lowercase")]
349pub enum ResponseFormat {
350    Text,
351    JsonObject,
352    JsonSchema(JsonSchemaFormat),
353}
354
355#[derive(Debug, Clone, Default)]
356pub struct ProviderRequestOptions {
357    pub headers: ProviderHeaders,
358    pub extra_body: Option<serde_json::Value>,
359    pub query_params: HashMap<String, String>,
360    /// Per-request base URL override (TS: provider config / stream options
361    /// `baseUrl`). When `None`, the provider's configured base URL is used.
362    pub base_url: Option<String>,
363}
364
365#[derive(Debug, Clone, Default)]
366pub struct ApiStreamOptions {
367    pub signal: Option<CancellationToken>,
368    pub request_options: ProviderRequestOptions,
369    /// Maximum number of retries after rate limits / transient errors
370    /// (TS: `maxRetries`; Codex default 0).
371    pub max_retries: Option<u32>,
372    /// Upper bound for server-requested retry delays (TS: `maxRetryDelayMs`;
373    /// Codex default 60 000 ms; `Some(0)` disables the cap).
374    pub max_retry_delay_ms: Option<u64>,
375    /// HTTP response-header timeout (TS: `timeoutMs`).
376    pub timeout_ms: Option<u64>,
377}
378
379#[derive(Debug, Clone, Default)]
380pub struct SimpleStreamOptions {
381    pub signal: Option<CancellationToken>,
382    pub temperature: Option<f32>,
383    pub max_tokens: Option<u64>,
384    pub response_format: Option<ResponseFormat>,
385    pub tool_choice: Option<ToolChoice>,
386    pub thinking: Option<ModelThinkingLevel>,
387    /// Raw reasoning effort override (TS: `reasoning`), e.g. `"minimal"`,
388    /// `"xhigh"`, `"max"` or `"off"`.
389    pub reasoning: Option<String>,
390    pub provider_extra: Option<serde_json::Value>,
391    pub session_id: Option<String>,
392    pub cache_retention: Option<CacheRetention>,
393    /// Per-request base URL override routed through to the provider adapter.
394    pub base_url: Option<String>,
395}
396
397#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
398#[serde(rename_all = "camelCase")]
399pub enum CacheRetention {
400    #[default]
401    None,
402    Short,
403    Long,
404}
405
406pub type AssistantMessage = Message;
407
408#[derive(Debug, Clone, Serialize, Deserialize)]
409#[serde(tag = "type", rename_all = "camelCase")]
410pub enum AssistantMessageEvent {
411    Start {
412        partial: AssistantMessage,
413    },
414    TextStart,
415    TextDelta {
416        delta: String,
417    },
418    TextEnd,
419    ThinkingStart,
420    ThinkingDelta {
421        delta: String,
422    },
423    ThinkingEnd {
424        signature: Option<String>,
425    },
426    ToolcallStart {
427        content_index: usize,
428        id: Option<String>,
429        name: Option<String>,
430    },
431    ToolcallDelta {
432        content_index: usize,
433        delta: String,
434    },
435    ToolcallEnd {
436        content_index: usize,
437        tool_call: ContentBlock,
438    },
439    Usage {
440        usage: Usage,
441    },
442    Done {
443        reason: String,
444        message: AssistantMessage,
445    },
446    Error {
447        reason: String,
448        error: String,
449    },
450}
451
452pub fn content_text(content: &[ContentBlock]) -> String {
453    content
454        .iter()
455        .filter_map(|block| match block {
456            ContentBlock::Text { text, .. } => Some(text.clone()),
457            _ => None,
458        })
459        .collect::<Vec<_>>()
460        .join("\n")
461}
462
463pub fn uuidv7() -> String {
464    Uuid::now_v7().to_string()
465}
466
467// Custom CancellationToken replacement (simplified) — replaces tokio::sync::CancellationToken
468// which has feature-gating inconsistencies across tokio versions.
469#[derive(Debug, Default, Clone)]
470pub struct CancellationToken {
471    inner: std::sync::Arc<std::sync::atomic::AtomicBool>,
472}
473
474impl CancellationToken {
475    pub fn new() -> Self {
476        Self {
477            inner: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
478        }
479    }
480
481    pub fn cancel(&self) {
482        self.inner.store(true, std::sync::atomic::Ordering::SeqCst);
483    }
484
485    pub fn is_cancelled(&self) -> bool {
486        self.inner.load(std::sync::atomic::Ordering::SeqCst)
487    }
488
489    pub fn child_token(&self) -> Self {
490        Self {
491            inner: self.inner.clone(),
492        }
493    }
494
495    /// Future that resolves once the token is cancelled (for `select!`).
496    pub async fn cancelled_fut(&self) {
497        while !self.is_cancelled() {
498            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
499        }
500    }
501}