Skip to main content

ai/
types.rs

1//! The message, content, usage, stop-reason, tool, model and stream-event model of `packages/ai/src/types.ts`.
2//! Serde shapes equal the TypeScript JSON: camelCase fields, optional fields omitted when absent, `type`/`role` tags.
3
4use indexmap::IndexMap;
5use serde::{Deserialize, Serialize};
6use serde_json::{Map, Value};
7
8#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
9#[serde(rename_all = "camelCase")]
10pub struct TextContent {
11    pub text: String,
12    #[serde(default, skip_serializing_if = "Option::is_none")]
13    pub text_signature: Option<String>,
14}
15
16#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
17#[serde(rename_all = "camelCase")]
18pub struct ThinkingContent {
19    pub thinking: String,
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub thinking_signature: Option<String>,
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub redacted: Option<bool>,
24}
25
26#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
27#[serde(rename_all = "camelCase")]
28pub struct ImageContent {
29    pub data: String,
30    pub mime_type: String,
31}
32
33/// `arguments` is a JSON object by contract, but streamed arguments can parse to any JSON value, as upstream.
34#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
35#[serde(rename_all = "camelCase")]
36pub struct ToolCall {
37    pub id: String,
38    pub name: String,
39    pub arguments: Value,
40    #[serde(default, skip_serializing_if = "Option::is_none")]
41    pub thought_signature: Option<String>,
42    #[serde(default, skip_serializing_if = "Option::is_none")]
43    pub namespace: Option<String>,
44}
45
46/// Text or image: user and tool-result content.
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
48#[serde(tag = "type", rename_all = "camelCase")]
49pub enum UserContent {
50    Text(TextContent),
51    Image(ImageContent),
52}
53
54/// Text, thinking or a tool call: assistant content.
55#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
56#[serde(tag = "type", rename_all = "camelCase")]
57pub enum AssistantContent {
58    Text(TextContent),
59    Thinking(ThinkingContent),
60    ToolCall(ToolCall),
61}
62
63#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
64#[serde(rename_all = "camelCase")]
65pub struct Cost {
66    pub input: f64,
67    pub output: f64,
68    pub cache_read: f64,
69    pub cache_write: f64,
70    pub total: f64,
71}
72
73#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
74#[serde(rename_all = "camelCase")]
75pub struct Usage {
76    pub input: u64,
77    pub output: u64,
78    pub cache_read: u64,
79    pub cache_write: u64,
80    /// Subset of `cache_write` written with 1h retention (Anthropic only).
81    #[serde(rename = "cacheWrite1h", default, skip_serializing_if = "Option::is_none")]
82    pub cache_write_1h: Option<u64>,
83    /// Reasoning tokens, a subset of `output`, when the provider reports them.
84    #[serde(default, skip_serializing_if = "Option::is_none")]
85    pub reasoning: Option<u64>,
86    pub total_tokens: u64,
87    pub cost: Cost,
88}
89
90#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
91#[serde(rename_all = "camelCase")]
92pub enum StopReason {
93    Pending,
94    Stop,
95    Length,
96    ToolUse,
97    Error,
98    Aborted,
99    Deferred,
100}
101
102#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
103#[serde(rename_all = "camelCase")]
104pub struct DiagnosticErrorInfo {
105    #[serde(default, skip_serializing_if = "Option::is_none")]
106    pub name: Option<String>,
107    pub message: String,
108    #[serde(default, skip_serializing_if = "Option::is_none")]
109    pub stack: Option<String>,
110    #[serde(default, skip_serializing_if = "Option::is_none")]
111    pub code: Option<Value>,
112}
113
114#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
115pub struct AssistantMessageDiagnostic {
116    #[serde(rename = "type")]
117    pub kind: String,
118    pub timestamp: i64,
119    #[serde(default, skip_serializing_if = "Option::is_none")]
120    pub error: Option<DiagnosticErrorInfo>,
121    #[serde(default, skip_serializing_if = "Option::is_none")]
122    pub details: Option<Map<String, Value>>,
123}
124
125#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
126#[serde(rename_all = "camelCase")]
127pub struct DeferredHandle {
128    pub provider: String,
129    pub model_id: String,
130    pub api: String,
131    pub id: String,
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub expires_at: Option<i64>,
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub poll_after_ms: Option<i64>,
136    #[serde(default, skip_serializing_if = "Option::is_none")]
137    pub data: Option<Value>,
138}
139
140#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
141#[serde(tag = "type", rename_all = "camelCase")]
142pub enum ConstrainedSamplingConfig {
143    #[serde(rename = "json_schema")]
144    JsonSchema {
145        strict: StrictMode,
146    },
147    Grammar {
148        variants: GrammarVariants,
149    },
150}
151
152#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
153#[serde(rename_all = "camelCase")]
154pub enum StrictMode {
155    Prefer,
156    Require,
157}
158
159#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
160pub struct GrammarVariants {
161    #[serde(default, skip_serializing_if = "Option::is_none")]
162    pub openai_lark: Option<String>,
163    #[serde(default, skip_serializing_if = "Option::is_none")]
164    pub openai_regex: Option<String>,
165}
166
167/// `constrainedSampling`: `false` or a config.
168#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
169#[serde(untagged)]
170pub enum ConstrainedSampling {
171    Disabled(bool),
172    Config(ConstrainedSamplingConfig),
173}
174
175#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
176#[serde(rename_all = "camelCase")]
177pub struct Tool {
178    pub name: String,
179    pub description: String,
180    pub parameters: Value,
181    #[serde(default, skip_serializing_if = "Option::is_none")]
182    pub constrained_sampling: Option<ConstrainedSampling>,
183}
184
185impl Tool {
186    pub(crate) fn sampling_config(&self) -> Option<&ConstrainedSamplingConfig> {
187        match &self.constrained_sampling {
188            Some(ConstrainedSampling::Config(config)) => Some(config),
189            _ => None,
190        }
191    }
192}
193
194#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
195pub struct ToolReference {
196    pub name: String,
197}
198
199/// `string | TextContent[]`.
200#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
201#[serde(untagged)]
202pub enum SystemContent {
203    Text(String),
204    Blocks(Vec<TypedText>),
205}
206
207/// A `{type: "text", ...}` block where only text is allowed.
208#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
209#[serde(tag = "type", rename_all = "camelCase")]
210pub enum TypedText {
211    Text(TextContent),
212}
213
214/// `string | (TextContent | ImageContent)[]`.
215#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
216#[serde(untagged)]
217pub enum UserMessageContent {
218    Text(String),
219    Blocks(Vec<UserContent>),
220}
221
222#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
223#[serde(tag = "role", rename = "system", rename_all = "camelCase")]
224pub struct SystemMessage {
225    pub content: SystemContent,
226    #[serde(default, skip_serializing_if = "Option::is_none")]
227    pub sections: Option<IndexMap<String, Option<String>>>,
228    #[serde(default, skip_serializing_if = "Option::is_none")]
229    pub tools_added: Option<Vec<Tool>>,
230    #[serde(default, skip_serializing_if = "Option::is_none")]
231    pub tools_removed: Option<Vec<ToolReference>>,
232    pub timestamp: i64,
233}
234
235#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
236#[serde(tag = "role", rename = "user")]
237pub struct UserMessage {
238    pub content: UserMessageContent,
239    pub timestamp: i64,
240}
241
242#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
243#[serde(tag = "role", rename = "assistant", rename_all = "camelCase")]
244pub struct AssistantMessage {
245    pub content: Vec<AssistantContent>,
246    pub api: String,
247    pub provider: String,
248    pub model: String,
249    #[serde(default, skip_serializing_if = "Option::is_none")]
250    pub response_model: Option<String>,
251    #[serde(default, skip_serializing_if = "Option::is_none")]
252    pub response_id: Option<String>,
253    #[serde(default, skip_serializing_if = "Option::is_none")]
254    pub provider_thinking_level: Option<String>,
255    #[serde(default, skip_serializing_if = "Option::is_none")]
256    pub diagnostics: Option<Vec<AssistantMessageDiagnostic>>,
257    pub usage: Usage,
258    pub stop_reason: StopReason,
259    #[serde(default, skip_serializing_if = "Option::is_none")]
260    pub deferred: Option<DeferredHandle>,
261    #[serde(default, skip_serializing_if = "Option::is_none")]
262    pub error_message: Option<String>,
263    #[serde(default, skip_serializing_if = "Option::is_none")]
264    pub raw_stop_reason: Option<String>,
265    #[serde(default, skip_serializing_if = "Option::is_none")]
266    pub end_turn: Option<bool>,
267    /// Provider-owned replay state keyed by provider (an Ultron extension; absent in TypeScript messages). The
268    /// `claude-subscription` provider keeps its versioned native-assistant carrier here.
269    #[serde(default, skip_serializing_if = "Option::is_none")]
270    pub provider_metadata: Option<Map<String, Value>>,
271    pub timestamp: i64,
272}
273
274impl AssistantMessage {
275    /// The empty in-progress message every provider starts from.
276    pub(crate) fn pending(model: &Model, timestamp: i64) -> Self {
277        AssistantMessage {
278            content: Vec::new(),
279            api: model.api.clone(),
280            provider: model.provider.clone(),
281            model: model.id.clone(),
282            response_model: None,
283            response_id: None,
284            provider_thinking_level: None,
285            diagnostics: None,
286            usage: Usage::default(),
287            stop_reason: StopReason::Pending,
288            deferred: None,
289            error_message: None,
290            raw_stop_reason: None,
291            end_turn: None,
292            provider_metadata: None,
293            timestamp,
294        }
295    }
296}
297
298#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
299#[serde(tag = "role", rename = "toolResult", rename_all = "camelCase")]
300pub struct ToolResultMessage {
301    pub tool_call_id: String,
302    pub tool_name: String,
303    pub content: Vec<UserContent>,
304    #[serde(default, skip_serializing_if = "Option::is_none")]
305    pub details: Option<Value>,
306    #[serde(default, skip_serializing_if = "Option::is_none")]
307    pub usage: Option<Usage>,
308    pub is_error: bool,
309    pub timestamp: i64,
310}
311
312/// A transcript message; each variant's struct carries its own `role` tag.
313#[derive(Clone, Debug, PartialEq, Serialize)]
314#[serde(untagged)]
315#[allow(clippy::large_enum_variant)] // transcripts are mostly assistant messages; boxing them would cost more than it saves
316pub enum Message {
317    System(SystemMessage),
318    User(UserMessage),
319    Assistant(AssistantMessage),
320    ToolResult(ToolResultMessage),
321}
322
323impl<'de> Deserialize<'de> for Message {
324    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
325        use serde::de::Error;
326        let value = Value::deserialize(deserializer)?;
327        let parsed = match value.get("role").and_then(Value::as_str) {
328            Some("system") => serde_json::from_value(value).map(Message::System),
329            Some("user") => serde_json::from_value(value).map(Message::User),
330            Some("assistant") => serde_json::from_value(value).map(Message::Assistant),
331            Some("toolResult") => serde_json::from_value(value).map(Message::ToolResult),
332            other => return Err(D::Error::custom(format!("unknown message role {other:?}"))),
333        };
334        parsed.map_err(D::Error::custom)
335    }
336}
337
338impl Message {
339    pub fn timestamp(&self) -> i64 {
340        match self {
341            Message::System(m) => m.timestamp,
342            Message::User(m) => m.timestamp,
343            Message::Assistant(m) => m.timestamp,
344            Message::ToolResult(m) => m.timestamp,
345        }
346    }
347}
348
349/// Request input with the `systemPrompt`/`tools` shorthand; [`crate::transcript::normalize_context`] folds them into
350/// a leading system message.
351#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
352#[serde(rename_all = "camelCase")]
353pub struct Context {
354    #[serde(default, skip_serializing_if = "Option::is_none")]
355    pub system_prompt: Option<String>,
356    pub messages: Vec<Message>,
357    #[serde(default, skip_serializing_if = "Option::is_none")]
358    pub tools: Option<Vec<Tool>>,
359}
360
361/// Normalized provider input: the prompt and tools live in the transcript's system messages.
362#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
363pub struct TranscriptContext {
364    pub messages: Vec<Message>,
365}
366
367/// One stream event. `partial` is a snapshot of the response so far at the time of the event.
368#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
369#[serde(tag = "type", rename_all = "snake_case")]
370pub enum AssistantMessageEvent {
371    Start {
372        partial: AssistantMessage,
373    },
374    TextStart {
375        #[serde(rename = "contentIndex")]
376        content_index: usize,
377        partial: AssistantMessage,
378    },
379    TextDelta {
380        #[serde(rename = "contentIndex")]
381        content_index: usize,
382        delta: String,
383        partial: AssistantMessage,
384    },
385    TextEnd {
386        #[serde(rename = "contentIndex")]
387        content_index: usize,
388        content: String,
389        partial: AssistantMessage,
390    },
391    ThinkingStart {
392        #[serde(rename = "contentIndex")]
393        content_index: usize,
394        partial: AssistantMessage,
395    },
396    ThinkingDelta {
397        #[serde(rename = "contentIndex")]
398        content_index: usize,
399        delta: String,
400        partial: AssistantMessage,
401    },
402    ThinkingEnd {
403        #[serde(rename = "contentIndex")]
404        content_index: usize,
405        content: String,
406        partial: AssistantMessage,
407    },
408    #[serde(rename = "toolcall_start")]
409    ToolCallStart {
410        #[serde(rename = "contentIndex")]
411        content_index: usize,
412        partial: AssistantMessage,
413    },
414    #[serde(rename = "toolcall_delta")]
415    ToolCallDelta {
416        #[serde(rename = "contentIndex")]
417        content_index: usize,
418        delta: String,
419        partial: AssistantMessage,
420    },
421    #[serde(rename = "toolcall_end")]
422    ToolCallEnd {
423        #[serde(rename = "contentIndex")]
424        content_index: usize,
425        #[serde(rename = "toolCall", with = "tagged_tool_call")]
426        tool_call: ToolCall,
427        partial: AssistantMessage,
428    },
429    Done {
430        reason: StopReason,
431        message: AssistantMessage,
432    },
433    Error {
434        reason: StopReason,
435        error: AssistantMessage,
436    },
437}
438
439/// A standalone tool call serialized with its `type: "toolCall"` tag, as in `toolcall_end`.
440mod tagged_tool_call {
441    use super::{AssistantContent, ToolCall};
442    use serde::{Deserialize, Deserializer, Serialize, Serializer};
443
444    pub fn serialize<S: Serializer>(call: &ToolCall, serializer: S) -> Result<S::Ok, S::Error> {
445        AssistantContent::ToolCall(call.clone()).serialize(serializer)
446    }
447
448    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<ToolCall, D::Error> {
449        match AssistantContent::deserialize(deserializer)? {
450            AssistantContent::ToolCall(call) => Ok(call),
451            _ => Err(serde::de::Error::custom("expected a toolCall block")),
452        }
453    }
454}
455
456/// Receives each stream event as it happens.
457pub type EventSink<'a> = dyn FnMut(&AssistantMessageEvent) + Send + 'a;
458
459#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
460#[serde(rename_all = "camelCase")]
461pub enum CacheRetention {
462    None,
463    Short,
464    Long,
465}
466
467#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
468#[serde(rename_all = "camelCase")]
469pub struct ModelCostTier {
470    pub input_tokens_above: f64,
471    pub input: f64,
472    pub output: f64,
473    pub cache_read: f64,
474    pub cache_write: f64,
475}
476
477#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
478#[serde(rename_all = "camelCase")]
479pub struct ModelCost {
480    pub input: f64,
481    pub output: f64,
482    pub cache_read: f64,
483    pub cache_write: f64,
484    #[serde(default, skip_serializing_if = "Option::is_none")]
485    pub tiers: Option<Vec<ModelCostTier>>,
486}
487
488/// A model. `compat` stays a JSON object: each API reads its own keys with upstream's defaults.
489#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
490#[serde(rename_all = "camelCase")]
491pub struct Model {
492    pub id: String,
493    pub name: String,
494    pub api: String,
495    pub provider: String,
496    pub base_url: String,
497    pub reasoning: bool,
498    #[serde(default, skip_serializing_if = "Option::is_none")]
499    pub thinking_level_map: Option<IndexMap<String, Option<String>>>,
500    pub input: Vec<String>,
501    #[serde(default, skip_serializing_if = "Option::is_none")]
502    pub input_limits: Option<Value>,
503    pub cost: ModelCost,
504    #[serde(default, skip_serializing_if = "Option::is_none")]
505    pub prompt_cache: Option<IndexMap<String, f64>>,
506    pub context_window: u64,
507    pub max_tokens: u64,
508    #[serde(default, skip_serializing_if = "Option::is_none")]
509    pub sampling_params: Option<Map<String, Value>>,
510    #[serde(default, skip_serializing_if = "Option::is_none")]
511    pub headers: Option<IndexMap<String, String>>,
512    #[serde(default, skip_serializing_if = "Option::is_none")]
513    pub compat: Option<Map<String, Value>>,
514    /// What `models.json` adds to this model's requests (its provider and model `headers`, resolved, and
515    /// `authHeader`), attached when the model is resolved for use. Never serialized: header values may be secrets.
516    #[serde(skip)]
517    pub request: Option<crate::model_registry::RequestConfig>,
518    /// Catalog fields the provider layer does not read (radius models carry `lab`, `enabled`, `providers`); kept so
519    /// a model round-trips unchanged.
520    #[serde(flatten)]
521    pub extra: Map<String, Value>,
522}
523
524/// The value of `thinkingLevelMap[level]`: absent, `null` (unsupported), or a provider value.
525#[derive(Clone, Copy, Debug, PartialEq, Eq)]
526pub enum Mapped<'a> {
527    Missing,
528    Unsupported,
529    Value(&'a str),
530}
531
532impl Model {
533    pub(crate) fn compat_value(&self, key: &str) -> Option<&Value> {
534        self.compat.as_ref()?.get(key).filter(|v| !v.is_null())
535    }
536
537    pub(crate) fn compat_bool(&self, key: &str) -> Option<bool> {
538        self.compat_value(key)?.as_bool()
539    }
540
541    pub(crate) fn compat_str(&self, key: &str) -> Option<&str> {
542        self.compat_value(key)?.as_str()
543    }
544
545    pub(crate) fn supports_images(&self) -> bool {
546        self.input.iter().any(|i| i == "image")
547    }
548
549    pub fn thinking_level(&self, level: &str) -> Mapped<'_> {
550        match self.thinking_level_map.as_ref().and_then(|map| map.get(level)) {
551            None => Mapped::Missing,
552            Some(None) => Mapped::Unsupported,
553            Some(Some(value)) => Mapped::Value(value),
554        }
555    }
556
557    /// `thinkingLevelMap?.[level] ?? level`.
558    pub(crate) fn mapped_or<'a>(&'a self, level: &'a str) -> &'a str {
559        match self.thinking_level(level) {
560            Mapped::Value(value) => value,
561            _ => level,
562        }
563    }
564}