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    #[serde(skip_serializing_if = "Option::is_none")]
103    pub temperature: Option<f32>,
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub top_p: Option<f32>,
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub max_tokens: Option<u32>,
108}
109
110pub fn map_messages(messages: &[ChatMessage]) -> crate::Result<Vec<CompatibleChatMessage>> {
111    let mut result = Vec::new();
112
113    for message in messages {
114        let mapped = match message {
115            ChatMessage::System { content, .. } => Some(CompatibleChatMessage::System { content: content.clone() }),
116            ChatMessage::User { content, .. } => {
117                Some(CompatibleChatMessage::User { content: map_user_content(content)? })
118            }
119            ChatMessage::Assistant { content, reasoning, tool_calls, .. } => {
120                let openai_tool_calls: Vec<_> = tool_calls
121                    .iter()
122                    .map(|call| {
123                        ChatCompletionMessageToolCalls::Function(ChatCompletionMessageToolCall {
124                            id: call.id.clone(),
125                            function: FunctionCall { name: call.name.clone(), arguments: call.arguments.clone() },
126                        })
127                    })
128                    .collect();
129
130                let has_tool_calls = !openai_tool_calls.is_empty();
131                let tool_calls = has_tool_calls.then_some(openai_tool_calls);
132
133                let reasoning_content = if reasoning.summary_text.is_some() {
134                    reasoning.summary_text.clone()
135                } else if has_tool_calls {
136                    Some(".".to_string())
137                } else {
138                    None
139                };
140
141                Some(CompatibleChatMessage::Assistant { content: content.clone(), reasoning_content, tool_calls })
142            }
143            ChatMessage::ToolCallResult(r) => {
144                let (content, tool_call_id) = match r {
145                    Ok(tool_result) => (tool_result.result.clone(), tool_result.id.clone()),
146                    Err(tool_error) => (tool_error.error.clone(), tool_error.id.clone()),
147                };
148
149                Some(CompatibleChatMessage::Tool { content, tool_call_id })
150            }
151            ChatMessage::Summary { content, .. } => Some(CompatibleChatMessage::User {
152                content: UserContent::Text(format!("[Previous conversation handoff]\n\n{content}")),
153            }),
154            ChatMessage::Error { .. } => None,
155        };
156
157        if let Some(msg) = mapped {
158            result.push(msg);
159        }
160    }
161
162    Ok(result)
163}
164
165fn map_user_content(parts: &[ContentBlock]) -> crate::Result<UserContent> {
166    let has_non_text = parts.iter().any(|p| !matches!(p, ContentBlock::Text { .. }));
167
168    if !has_non_text {
169        return Ok(UserContent::Text(ContentBlock::join_text(parts)));
170    }
171
172    let mut items = Vec::with_capacity(parts.len());
173    for p in parts {
174        match p {
175            ContentBlock::Text { text } => items.push(UserContentPart::Text { text: text.clone() }),
176            ContentBlock::Image { .. } => {
177                items.push(UserContentPart::ImageUrl { image_url: ImageUrlContent { url: p.as_data_uri().unwrap() } });
178            }
179            ContentBlock::Audio { .. } => {
180                return Err(crate::LlmError::UnsupportedContent("This provider does not support audio input".into()));
181            }
182        }
183    }
184
185    Ok(UserContent::Parts(items))
186}
187
188#[derive(Debug, Clone, Serialize, Deserialize)]
189pub struct ChatCompletionStreamChoice {
190    pub index: i32,
191    pub delta: ChatCompletionStreamResponseDelta,
192    pub finish_reason: Option<FinishReason>,
193    #[serde(default)]
194    pub logprobs: Option<serde_json::Value>,
195}
196
197#[derive(Debug, Clone, Default, Serialize, Deserialize)]
198pub struct ChatCompletionStreamResponseDelta {
199    pub role: Option<Role>,
200    pub content: Option<String>,
201    #[serde(default)]
202    pub reasoning_content: Option<String>,
203    pub tool_calls: Option<Vec<ToolCallDelta>>,
204}
205
206#[derive(Debug, Clone, Serialize, Deserialize)]
207pub struct ToolCallDelta {
208    pub index: i32,
209    pub id: Option<String>,
210    #[serde(rename = "type")]
211    pub tool_type: Option<String>,
212    pub function: Option<FunctionCallDelta>,
213}
214
215#[derive(Debug, Clone, Serialize, Deserialize)]
216pub struct FunctionCallDelta {
217    pub name: Option<String>,
218    pub arguments: Option<String>,
219}
220
221#[derive(Debug, Clone, Default, Serialize, Deserialize)]
222pub struct PromptTokensDetails {
223    #[serde(default)]
224    pub cached_tokens: Option<u32>,
225    /// `OpenRouter`-specific: tokens written to cache (cache creation).
226    /// Only returned for models with explicit caching and cache write pricing.
227    #[serde(default)]
228    pub cache_write_tokens: Option<u32>,
229    /// `OpenAI` + `OpenRouter`: input audio tokens.
230    #[serde(default)]
231    pub audio_tokens: Option<u32>,
232    /// `OpenRouter`-specific: input video tokens.
233    #[serde(default)]
234    pub video_tokens: Option<u32>,
235}
236
237#[derive(Debug, Clone, Default, Serialize, Deserialize)]
238pub struct CompletionTokensDetails {
239    #[serde(default)]
240    pub reasoning_tokens: Option<u32>,
241    #[serde(default)]
242    pub audio_tokens: Option<u32>,
243    #[serde(default)]
244    pub accepted_prediction_tokens: Option<u32>,
245    #[serde(default)]
246    pub rejected_prediction_tokens: Option<u32>,
247}
248
249#[derive(Debug, Clone, Default, Serialize, Deserialize)]
250pub struct Usage {
251    pub prompt_tokens: i64,
252    pub completion_tokens: i64,
253    pub total_tokens: i64,
254    #[serde(default)]
255    pub prompt_tokens_details: Option<PromptTokensDetails>,
256    #[serde(default)]
257    pub completion_tokens_details: Option<CompletionTokensDetails>,
258}
259
260impl From<Usage> for TokenUsage {
261    fn from(usage: Usage) -> Self {
262        let prompt = usage.prompt_tokens_details.unwrap_or_default();
263        let completion = usage.completion_tokens_details.unwrap_or_default();
264        TokenUsage {
265            input_tokens: u32::try_from(usage.prompt_tokens.max(0)).unwrap_or(0),
266            output_tokens: u32::try_from(usage.completion_tokens.max(0)).unwrap_or(0),
267            cache_read_tokens: prompt.cached_tokens,
268            cache_creation_tokens: prompt.cache_write_tokens,
269            cache_reporting_exclusive: Some(false),
270            input_audio_tokens: prompt.audio_tokens,
271            input_video_tokens: prompt.video_tokens,
272            reasoning_tokens: completion.reasoning_tokens,
273            output_audio_tokens: completion.audio_tokens,
274            accepted_prediction_tokens: completion.accepted_prediction_tokens,
275            rejected_prediction_tokens: completion.rejected_prediction_tokens,
276        }
277    }
278}
279
280#[cfg(test)]
281mod tests {
282    use super::*;
283    use crate::providers::openai_compatible::build_chat_request;
284    use crate::types::IsoString;
285    use crate::{Context, ModelSettings, ToolCallRequest, ToolDefinition};
286
287    fn assistant_with_tool_call(reasoning_content: Option<&str>) -> ChatMessage {
288        ChatMessage::Assistant {
289            content: String::new(),
290            reasoning: crate::AssistantReasoning {
291                summary_text: reasoning_content.map(ToString::to_string),
292                encrypted_content: None,
293            },
294            timestamp: IsoString::now(),
295            tool_calls: vec![ToolCallRequest {
296                id: "call_1".to_string(),
297                name: "test__tool".to_string(),
298                arguments: "{\"path\":\"src/main.rs\"}".to_string(),
299            }],
300        }
301    }
302
303    fn context_with_assistant_message(message: ChatMessage) -> crate::Context {
304        crate::Context::new(
305            vec![ChatMessage::user("run a tool"), message],
306            vec![ToolDefinition::new("test__tool", "test", serde_json::json!({ "type": "object" }))],
307        )
308    }
309
310    #[test]
311    fn test_build_request_includes_reasoning_content_on_assistant_tool_message() {
312        let context = context_with_assistant_message(assistant_with_tool_call(Some("trace chunk")));
313        let request = build_chat_request("test-model", &context, None).unwrap();
314
315        let json = serde_json::to_value(&request).unwrap();
316        assert_eq!(json["messages"][1]["role"], "assistant");
317        assert_eq!(json["messages"][1]["reasoning_content"], "trace chunk");
318    }
319
320    #[test]
321    fn test_build_request_maps_model_settings_and_omits_when_unset() {
322        let user = || ChatMessage::user("hello");
323
324        let mut context = Context::new(vec![user()], vec![]);
325        context.set_model_settings(ModelSettings { temperature: Some(0.0), top_p: Some(0.5), max_tokens: Some(64) });
326        let json = serde_json::to_value(build_chat_request("test-model", &context, None).unwrap()).unwrap();
327        assert_eq!(json["temperature"], 0.0);
328        assert_eq!(json["top_p"], 0.5);
329        assert_eq!(json["max_tokens"], 64);
330
331        let unset = Context::new(vec![user()], vec![]);
332        let json = serde_json::to_value(build_chat_request("test-model", &unset, None).unwrap()).unwrap();
333        assert!(json.get("temperature").is_none());
334        assert!(json.get("top_p").is_none());
335        assert!(json.get("max_tokens").is_none());
336    }
337
338    #[test]
339    fn test_build_request_includes_stream_options_with_usage() {
340        let context = crate::Context::new(vec![ChatMessage::user("hello")], vec![]);
341        let request = build_chat_request("test-model", &context, None).unwrap();
342
343        let json = serde_json::to_value(&request).unwrap();
344        assert_eq!(json["stream_options"]["include_usage"], true);
345    }
346
347    #[test]
348    fn test_build_request_sends_empty_reasoning_content_on_tool_call_when_none() {
349        let context = context_with_assistant_message(assistant_with_tool_call(None));
350        let request = build_chat_request("test-model", &context, None).unwrap();
351
352        let json = serde_json::to_value(&request).unwrap();
353        assert_eq!(json["messages"][1]["role"], "assistant");
354        assert_eq!(json["messages"][1]["reasoning_content"], ".");
355    }
356
357    #[test]
358    fn test_user_message_text_only_serializes_as_string() {
359        let content = map_user_content(&[ContentBlock::text("Hello")]).unwrap();
360        let json = serde_json::to_value(&content).unwrap();
361        assert_eq!(json, "Hello");
362    }
363
364    #[test]
365    fn test_user_message_with_image_serializes_as_array() {
366        let content = map_user_content(&[
367            ContentBlock::text("Look:"),
368            ContentBlock::Image { data: "aW1n".to_string(), mime_type: "image/png".to_string() },
369        ])
370        .unwrap();
371        let json = serde_json::to_value(&content).unwrap();
372        let parts = json.as_array().expect("Expected array");
373        assert_eq!(parts.len(), 2);
374        assert_eq!(parts[0]["type"], "text");
375        assert_eq!(parts[0]["text"], "Look:");
376        assert_eq!(parts[1]["type"], "image_url");
377        assert!(parts[1]["image_url"]["url"].as_str().unwrap().starts_with("data:image/png;base64,"));
378    }
379
380    #[test]
381    fn test_user_message_audio_only_errors() {
382        let result = map_user_content(&[ContentBlock::Audio {
383            data: "YXVkaW8=".to_string(),
384            mime_type: "audio/wav".to_string(),
385        }]);
386        assert!(matches!(result, Err(crate::LlmError::UnsupportedContent(_))));
387    }
388
389    #[test]
390    fn test_user_message_audio_with_text_errors() {
391        let result = map_user_content(&[
392            ContentBlock::text("Listen:"),
393            ContentBlock::Audio { data: "YXVkaW8=".to_string(), mime_type: "audio/wav".to_string() },
394        ]);
395        assert!(matches!(result, Err(crate::LlmError::UnsupportedContent(_))));
396    }
397}
llm/providers/openai_compatible/types.rs

llm/providers/openai_compatible/
types.rs
