llm/providers/openai_compatible/
types.rs

1use async_openai::types::chat::{
2    ChatCompletionMessageToolCall, ChatCompletionMessageToolCalls, ChatCompletionStreamOptions, ChatCompletionTools,
3    FunctionCall, Role,
4};
5use serde::{Deserialize, Serialize};
6
7use crate::{ChatMessage, ContentBlock, TokenUsage};
8
9/// Unified custom types for OpenAI-compatible APIs that deviate slightly from the standard.
10/// This handles quirks from providers like `OpenRouter`, Z.ai, and potentially others.
11///
12/// Common deviations handled:
13/// - Missing 'object' field (z.ai)
14/// - Negative token counts (openrouter)
15/// - Additional finish reasons like 'error' (openrouter)
16/// - Optional `system_fingerprint` and usage fields
17
18#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
19#[serde(rename_all = "snake_case")]
20pub enum FinishReason {
21    Stop,
22    Length,
23    ToolCalls,
24    ContentFilter,
25    FunctionCall,
26    Error,
27    NetworkError,
28    ModelContextWindowExceeded,
29}
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
32pub struct ChatCompletionStreamResponse {
33    pub id: String,
34    pub choices: Vec<ChatCompletionStreamChoice>,
35    pub created: u64,
36    pub model: String,
37    #[serde(default)]
38    pub system_fingerprint: Option<String>,
39    #[serde(default = "default_object")]
40    pub object: String,
41    #[serde(default)]
42    pub usage: Option<Usage>,
43}
44
45fn default_object() -> String {
46    "chat.completion.chunk".to_string()
47}
48
49#[derive(Debug, Clone, Serialize)]
50#[serde(untagged)]
51pub enum UserContent {
52    Text(String),
53    Parts(Vec<UserContentPart>),
54}
55
56#[derive(Debug, Clone, Serialize)]
57#[serde(tag = "type", rename_all = "snake_case")]
58pub enum UserContentPart {
59    Text { text: String },
60    ImageUrl { image_url: ImageUrlContent },
61}
62
63#[derive(Debug, Clone, Serialize)]
64pub struct ImageUrlContent {
65    pub url: String,
66}
67
68#[derive(Debug, Clone, Serialize)]
69#[serde(tag = "role", rename_all = "lowercase")]
70pub enum CompatibleChatMessage {
71    System {
72        content: String,
73    },
74    User {
75        content: UserContent,
76    },
77    Assistant {
78        content: String,
79        #[serde(skip_serializing_if = "Option::is_none")]
80        reasoning_content: Option<String>,
81        #[serde(skip_serializing_if = "Option::is_none")]
82        tool_calls: Option<Vec<ChatCompletionMessageToolCalls>>,
83    },
84    Tool {
85        content: String,
86        tool_call_id: String,
87    },
88}
89
90#[derive(Debug, Clone, Serialize)]
91pub struct CompatibleChatRequest {
92    pub model: String,
93    pub messages: Vec<CompatibleChatMessage>,
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub stream: Option<bool>,
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub tools: Option<Vec<ChatCompletionTools>>,
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub stream_options: Option<ChatCompletionStreamOptions>,
100    #[serde(skip_serializing_if = "Option::is_none")]
101    pub reasoning_effort: Option<crate::ReasoningEffort>,
102}
103
104pub fn map_messages(messages: &[ChatMessage]) -> crate::Result<Vec<CompatibleChatMessage>> {
105    let mut result = Vec::new();
106
107    for message in messages {
108        let mapped = match message {
109            ChatMessage::System { content, .. } => Some(CompatibleChatMessage::System { content: content.clone() }),
110            ChatMessage::User { content, .. } => {
111                Some(CompatibleChatMessage::User { content: map_user_content(content)? })
112            }
113            ChatMessage::Assistant { content, reasoning, tool_calls, .. } => {
114                let openai_tool_calls: Vec<_> = tool_calls
115                    .iter()
116                    .map(|call| {
117                        ChatCompletionMessageToolCalls::Function(ChatCompletionMessageToolCall {
118                            id: call.id.clone(),
119                            function: FunctionCall { name: call.name.clone(), arguments: call.arguments.clone() },
120                        })
121                    })
122                    .collect();
123
124                let has_tool_calls = !openai_tool_calls.is_empty();
125                let tool_calls = has_tool_calls.then_some(openai_tool_calls);
126
127                let reasoning_content = if reasoning.summary_text.is_some() {
128                    reasoning.summary_text.clone()
129                } else if has_tool_calls {
130                    Some(".".to_string())
131                } else {
132                    None
133                };
134
135                Some(CompatibleChatMessage::Assistant { content: content.clone(), reasoning_content, tool_calls })
136            }
137            ChatMessage::ToolCallResult(r) => {
138                let (content, tool_call_id) = match r {
139                    Ok(tool_result) => (tool_result.result.clone(), tool_result.id.clone()),
140                    Err(tool_error) => (tool_error.error.clone(), tool_error.id.clone()),
141                };
142
143                Some(CompatibleChatMessage::Tool { content, tool_call_id })
144            }
145            ChatMessage::Summary { content, .. } => Some(CompatibleChatMessage::User {
146                content: UserContent::Text(format!("[Previous conversation handoff]\n\n{content}")),
147            }),
148            ChatMessage::Error { .. } => None,
149        };
150
151        if let Some(msg) = mapped {
152            result.push(msg);
153        }
154    }
155
156    Ok(result)
157}
158
159fn map_user_content(parts: &[ContentBlock]) -> crate::Result<UserContent> {
160    let has_non_text = parts.iter().any(|p| !matches!(p, ContentBlock::Text { .. }));
161
162    if !has_non_text {
163        return Ok(UserContent::Text(ContentBlock::join_text(parts)));
164    }
165
166    let mut items = Vec::with_capacity(parts.len());
167    for p in parts {
168        match p {
169            ContentBlock::Text { text } => items.push(UserContentPart::Text { text: text.clone() }),
170            ContentBlock::Image { .. } => {
171                items.push(UserContentPart::ImageUrl { image_url: ImageUrlContent { url: p.as_data_uri().unwrap() } });
172            }
173            ContentBlock::Audio { .. } => {
174                return Err(crate::LlmError::UnsupportedContent("This provider does not support audio input".into()));
175            }
176        }
177    }
178
179    Ok(UserContent::Parts(items))
180}
181
182#[derive(Debug, Clone, Serialize, Deserialize)]
183pub struct ChatCompletionStreamChoice {
184    pub index: i32,
185    pub delta: ChatCompletionStreamResponseDelta,
186    pub finish_reason: Option<FinishReason>,
187    #[serde(default)]
188    pub logprobs: Option<serde_json::Value>,
189}
190
191#[derive(Debug, Clone, Serialize, Deserialize)]
192pub struct ChatCompletionStreamResponseDelta {
193    pub role: Option<Role>,
194    pub content: Option<String>,
195    #[serde(default)]
196    pub reasoning_content: Option<String>,
197    pub tool_calls: Option<Vec<ToolCallDelta>>,
198}
199
200#[derive(Debug, Clone, Serialize, Deserialize)]
201pub struct ToolCallDelta {
202    pub index: i32,
203    pub id: Option<String>,
204    #[serde(rename = "type")]
205    pub tool_type: Option<String>,
206    pub function: Option<FunctionCallDelta>,
207}
208
209#[derive(Debug, Clone, Serialize, Deserialize)]
210pub struct FunctionCallDelta {
211    pub name: Option<String>,
212    pub arguments: Option<String>,
213}
214
215#[derive(Debug, Clone, Default, Serialize, Deserialize)]
216pub struct PromptTokensDetails {
217    #[serde(default)]
218    pub cached_tokens: Option<u32>,
219    /// `OpenRouter`-specific: tokens written to cache (cache creation).
220    /// Only returned for models with explicit caching and cache write pricing.
221    #[serde(default)]
222    pub cache_write_tokens: Option<u32>,
223    /// `OpenAI` + `OpenRouter`: input audio tokens.
224    #[serde(default)]
225    pub audio_tokens: Option<u32>,
226    /// `OpenRouter`-specific: input video tokens.
227    #[serde(default)]
228    pub video_tokens: Option<u32>,
229}
230
231#[derive(Debug, Clone, Default, Serialize, Deserialize)]
232pub struct CompletionTokensDetails {
233    #[serde(default)]
234    pub reasoning_tokens: Option<u32>,
235    #[serde(default)]
236    pub audio_tokens: Option<u32>,
237    #[serde(default)]
238    pub accepted_prediction_tokens: Option<u32>,
239    #[serde(default)]
240    pub rejected_prediction_tokens: Option<u32>,
241}
242
243#[derive(Debug, Clone, Default, Serialize, Deserialize)]
244pub struct Usage {
245    pub prompt_tokens: i64,
246    pub completion_tokens: i64,
247    pub total_tokens: i64,
248    #[serde(default)]
249    pub prompt_tokens_details: Option<PromptTokensDetails>,
250    #[serde(default)]
251    pub completion_tokens_details: Option<CompletionTokensDetails>,
252}
253
254impl From<Usage> for TokenUsage {
255    fn from(usage: Usage) -> Self {
256        let prompt = usage.prompt_tokens_details.unwrap_or_default();
257        let completion = usage.completion_tokens_details.unwrap_or_default();
258        TokenUsage {
259            input_tokens: u32::try_from(usage.prompt_tokens.max(0)).unwrap_or(0),
260            output_tokens: u32::try_from(usage.completion_tokens.max(0)).unwrap_or(0),
261            cache_read_tokens: prompt.cached_tokens,
262            cache_creation_tokens: prompt.cache_write_tokens,
263            input_audio_tokens: prompt.audio_tokens,
264            input_video_tokens: prompt.video_tokens,
265            reasoning_tokens: completion.reasoning_tokens,
266            output_audio_tokens: completion.audio_tokens,
267            accepted_prediction_tokens: completion.accepted_prediction_tokens,
268            rejected_prediction_tokens: completion.rejected_prediction_tokens,
269        }
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use super::*;
276    use crate::providers::openai_compatible::build_chat_request;
277    use crate::types::IsoString;
278    use crate::{ToolCallRequest, ToolDefinition};
279
280    fn assistant_with_tool_call(reasoning_content: Option<&str>) -> ChatMessage {
281        ChatMessage::Assistant {
282            content: String::new(),
283            reasoning: crate::AssistantReasoning {
284                summary_text: reasoning_content.map(ToString::to_string),
285                encrypted_content: None,
286            },
287            timestamp: IsoString::now(),
288            tool_calls: vec![ToolCallRequest {
289                id: "call_1".to_string(),
290                name: "test__tool".to_string(),
291                arguments: "{\"path\":\"src/main.rs\"}".to_string(),
292            }],
293        }
294    }
295
296    fn context_with_assistant_message(message: ChatMessage) -> crate::Context {
297        crate::Context::new(
298            vec![
299                ChatMessage::User { content: vec![ContentBlock::text("run a tool")], timestamp: IsoString::now() },
300                message,
301            ],
302            vec![ToolDefinition {
303                name: "test__tool".to_string(),
304                description: "test".to_string(),
305                parameters: "{\"type\":\"object\"}".to_string(),
306                server: None,
307            }],
308        )
309    }
310
311    #[test]
312    fn test_build_request_includes_reasoning_content_on_assistant_tool_message() {
313        let context = context_with_assistant_message(assistant_with_tool_call(Some("trace chunk")));
314        let request = build_chat_request("test-model", &context).unwrap();
315
316        let json = serde_json::to_value(&request).unwrap();
317        assert_eq!(json["messages"][1]["role"], "assistant");
318        assert_eq!(json["messages"][1]["reasoning_content"], "trace chunk");
319    }
320
321    #[test]
322    fn test_build_request_includes_stream_options_with_usage() {
323        let context = crate::Context::new(
324            vec![ChatMessage::User { content: vec![ContentBlock::text("hello")], timestamp: IsoString::now() }],
325            vec![],
326        );
327        let request = build_chat_request("test-model", &context).unwrap();
328
329        let json = serde_json::to_value(&request).unwrap();
330        assert_eq!(json["stream_options"]["include_usage"], true);
331    }
332
333    #[test]
334    fn test_build_request_sends_empty_reasoning_content_on_tool_call_when_none() {
335        let context = context_with_assistant_message(assistant_with_tool_call(None));
336        let request = build_chat_request("test-model", &context).unwrap();
337
338        let json = serde_json::to_value(&request).unwrap();
339        assert_eq!(json["messages"][1]["role"], "assistant");
340        assert_eq!(json["messages"][1]["reasoning_content"], ".");
341    }
342
343    #[test]
344    fn test_user_message_text_only_serializes_as_string() {
345        let content = map_user_content(&[ContentBlock::text("Hello")]).unwrap();
346        let json = serde_json::to_value(&content).unwrap();
347        assert_eq!(json, "Hello");
348    }
349
350    #[test]
351    fn test_user_message_with_image_serializes_as_array() {
352        let content = map_user_content(&[
353            ContentBlock::text("Look:"),
354            ContentBlock::Image { data: "aW1n".to_string(), mime_type: "image/png".to_string() },
355        ])
356        .unwrap();
357        let json = serde_json::to_value(&content).unwrap();
358        let parts = json.as_array().expect("Expected array");
359        assert_eq!(parts.len(), 2);
360        assert_eq!(parts[0]["type"], "text");
361        assert_eq!(parts[0]["text"], "Look:");
362        assert_eq!(parts[1]["type"], "image_url");
363        assert!(parts[1]["image_url"]["url"].as_str().unwrap().starts_with("data:image/png;base64,"));
364    }
365
366    #[test]
367    fn test_user_message_audio_only_errors() {
368        let result = map_user_content(&[ContentBlock::Audio {
369            data: "YXVkaW8=".to_string(),
370            mime_type: "audio/wav".to_string(),
371        }]);
372        assert!(matches!(result, Err(crate::LlmError::UnsupportedContent(_))));
373    }
374
375    #[test]
376    fn test_user_message_audio_with_text_errors() {
377        let result = map_user_content(&[
378            ContentBlock::text("Listen:"),
379            ContentBlock::Audio { data: "YXVkaW8=".to_string(), mime_type: "audio/wav".to_string() },
380        ]);
381        assert!(matches!(result, Err(crate::LlmError::UnsupportedContent(_))));
382    }
383}
llm/providers/openai_compatible/types.rs

llm/providers/openai_compatible/
types.rs
