1use serde::{Deserialize, Deserializer, Serialize};
7use serde_json::Value;
8
9fn de_string_or_empty<'de, D>(deserializer: D) -> std::result::Result<String, D::Error>
17where
18 D: Deserializer<'de>,
19{
20 Ok(Option::<String>::deserialize(deserializer)?.unwrap_or_default())
21}
22
23fn de_arguments_as_string<'de, D>(deserializer: D) -> std::result::Result<String, D::Error>
29where
30 D: Deserializer<'de>,
31{
32 Ok(match Value::deserialize(deserializer)? {
33 Value::Null => String::new(),
34 Value::String(s) => s,
35 other => other.to_string(),
36 })
37}
38
39fn de_usage_or_default<'de, D>(deserializer: D) -> std::result::Result<OpenAIUsage, D::Error>
45where
46 D: Deserializer<'de>,
47{
48 Ok(Option::<OpenAIUsage>::deserialize(deserializer)?.unwrap_or_default())
49}
50
51fn de_choices_or_empty<'de, D>(
60 deserializer: D,
61) -> std::result::Result<Vec<OpenAIChatChoice>, D::Error>
62where
63 D: Deserializer<'de>,
64{
65 Ok(Option::<Vec<OpenAIChatChoice>>::deserialize(deserializer)?.unwrap_or_default())
66}
67
68fn de_choices_lenient<'de, D>(
74 deserializer: D,
75) -> std::result::Result<Vec<OpenAIStreamChoice>, D::Error>
76where
77 D: Deserializer<'de>,
78{
79 match Value::deserialize(deserializer)? {
80 value @ Value::Array(_) => serde_json::from_value(value).map_err(serde::de::Error::custom),
81 _ => Ok(Vec::new()),
82 }
83}
84
85#[derive(Debug, Clone, Default, Serialize, Deserialize)]
87pub struct OpenAIChatResponse {
88 pub id: String,
89 pub object: String,
91 pub model: String,
92 #[serde(default, deserialize_with = "de_choices_or_empty")]
107 pub choices: Vec<OpenAIChatChoice>,
108 #[serde(default, deserialize_with = "de_usage_or_default")]
116 pub usage: OpenAIUsage,
117}
118
119#[derive(Debug, Clone, Default, Serialize, Deserialize)]
121pub struct OpenAIChatChoice {
122 pub index: i64,
123 pub message: OpenAIChatMessage,
124 #[serde(default, deserialize_with = "de_string_or_empty")]
130 pub finish_reason: String,
131}
132
133#[derive(Debug, Clone, Default, Serialize, Deserialize)]
135pub struct OpenAIChatMessage {
136 pub role: String,
137 #[serde(default, deserialize_with = "de_string_or_empty")]
144 pub content: String,
145 #[serde(default, skip_serializing_if = "Option::is_none")]
146 pub tool_calls: Option<Vec<OpenAIToolCall>>,
147 #[serde(default, skip_serializing_if = "Option::is_none")]
149 pub reasoning_content: Option<String>,
150}
151
152#[derive(Debug, Clone, Default, Serialize, Deserialize)]
154pub struct OpenAIToolCall {
155 pub id: String,
156 pub r#type: String,
158 pub function: OpenAIFunctionCall,
159}
160
161#[derive(Debug, Clone, Default, Serialize, Deserialize)]
167pub struct OpenAIFunctionCall {
168 #[serde(default, skip_serializing_if = "Option::is_none")]
172 pub name: Option<String>,
173 #[serde(default, deserialize_with = "de_arguments_as_string")]
174 pub arguments: String,
175}
176
177#[derive(Debug, Clone, Default, Serialize, Deserialize)]
179pub struct OpenAIUsage {
180 pub prompt_tokens: i64,
181 pub completion_tokens: i64,
182 pub total_tokens: i64,
183}
184
185#[derive(Debug, Clone, Default, Serialize, Deserialize)]
194pub struct OpenAIStreamUsage {
195 #[serde(default, skip_serializing_if = "Option::is_none")]
196 pub prompt_tokens: Option<i64>,
197 #[serde(default, skip_serializing_if = "Option::is_none")]
198 pub completion_tokens: Option<i64>,
199 #[serde(default, skip_serializing_if = "Option::is_none")]
200 pub total_tokens: Option<i64>,
201 #[serde(default, skip_serializing_if = "Option::is_none")]
203 pub prompt_tokens_details: Option<OpenAIStreamUsagePromptDetails>,
204 #[serde(default, skip_serializing_if = "Option::is_none")]
206 pub completion_tokens_details: Option<OpenAIStreamUsageCompletionDetails>,
207}
208
209#[derive(Debug, Clone, Default, Serialize, Deserialize)]
211pub struct OpenAIStreamUsagePromptDetails {
212 #[serde(default, skip_serializing_if = "Option::is_none")]
213 pub cached_tokens: Option<i64>,
214}
215
216#[derive(Debug, Clone, Default, Serialize, Deserialize)]
218pub struct OpenAIStreamUsageCompletionDetails {
219 #[serde(default, skip_serializing_if = "Option::is_none")]
220 pub reasoning_tokens: Option<i64>,
221}
222
223#[derive(Debug, Clone, Default, Serialize, Deserialize)]
230pub struct OpenAIStreamChunk {
231 #[serde(default)]
232 pub id: String,
233 #[serde(default)]
235 pub object: String,
236 #[serde(default, deserialize_with = "de_choices_lenient")]
239 pub choices: Vec<OpenAIStreamChoice>,
240 #[serde(default, skip_serializing_if = "Option::is_none")]
246 pub usage: Option<OpenAIStreamUsage>,
247}
248
249#[derive(Debug, Clone, Default, Serialize, Deserialize)]
251pub struct OpenAIStreamChoice {
252 #[serde(default)]
255 pub index: i64,
256 #[serde(default)]
262 pub delta: OpenAIStreamDelta,
263 #[serde(default)]
265 pub finish_reason: Option<String>,
266}
267
268#[derive(Debug, Clone, Default, Serialize, Deserialize)]
270pub struct OpenAIStreamDelta {
271 #[serde(default, skip_serializing_if = "Option::is_none")]
272 pub role: Option<String>,
273 #[serde(default, skip_serializing_if = "Option::is_none")]
274 pub content: Option<String>,
275 #[serde(default, skip_serializing_if = "Option::is_none")]
276 pub reasoning_content: Option<String>,
277 #[serde(default, skip_serializing_if = "Option::is_none")]
278 pub tool_calls: Option<Vec<OpenAIStreamToolCall>>,
279}
280
281#[derive(Debug, Clone, Default, Serialize, Deserialize)]
283pub struct OpenAIStreamToolCall {
284 #[serde(default, skip_serializing_if = "Option::is_none")]
291 pub index: Option<i64>,
292 #[serde(default, skip_serializing_if = "Option::is_none")]
293 pub id: Option<String>,
294 #[serde(default, skip_serializing_if = "Option::is_none")]
295 pub r#type: Option<String>,
296 #[serde(default)]
300 pub function: OpenAIFunctionCall,
301}
302
303#[cfg(test)]
304mod tests {
305 use super::*;
306
307 #[test]
314 fn serialized_shape_is_pinned() {
315 let message = OpenAIChatMessage {
316 role: "assistant".to_string(),
317 content: String::new(),
318 tool_calls: None,
319 reasoning_content: None,
320 };
321 assert_eq!(
323 serde_json::to_string(&message).unwrap_or_default(),
324 r#"{"role":"assistant","content":""}"#
325 );
326
327 let function = OpenAIFunctionCall::default();
329 assert_eq!(
330 serde_json::to_string(&function).unwrap_or_default(),
331 r#"{"arguments":""}"#
332 );
333 assert_eq!(
334 serde_json::to_string(&OpenAIFunctionCall {
335 name: Some("get_weather".to_string()),
336 arguments: "{}".to_string(),
337 })
338 .unwrap_or_default(),
339 r#"{"name":"get_weather","arguments":"{}"}"#
340 );
341
342 let choice = OpenAIChatChoice::default();
343 assert_eq!(
344 serde_json::to_string(&choice).unwrap_or_default(),
345 r#"{"index":0,"message":{"role":"","content":""},"finish_reason":""}"#
346 );
347
348 let chunk = OpenAIStreamChunk::default();
349 assert_eq!(
350 serde_json::to_string(&chunk).unwrap_or_default(),
351 r#"{"id":"","object":"","choices":[]}"#
352 );
353
354 let tool_call = OpenAIStreamToolCall::default();
356 assert_eq!(
357 serde_json::to_string(&tool_call).unwrap_or_default(),
358 r#"{"function":{"arguments":""}}"#
359 );
360 assert_eq!(
361 serde_json::to_string(&OpenAIStreamToolCall {
362 index: Some(0),
363 ..Default::default()
364 })
365 .unwrap_or_default(),
366 r#"{"index":0,"function":{"arguments":""}}"#
367 );
368
369 assert_eq!(
371 serde_json::to_string(&OpenAIStreamUsage::default()).unwrap_or_default(),
372 "{}"
373 );
374 }
375
376 #[test]
384 fn stream_usage_type_accepts_partial_counts() {
385 let partial = r#"{"choices":[],"usage":{"prompt_tokens":1,"completion_tokens":2}}"#;
386 let chunk: OpenAIStreamChunk =
387 serde_json::from_str(partial).expect("partial usage counts must decode");
388 let usage = serde_json::to_value(&chunk.usage).unwrap_or(Value::Null);
389 assert_eq!(
390 usage,
391 serde_json::json!({ "prompt_tokens": 1, "completion_tokens": 2 })
392 );
393 }
394
395 #[test]
401 fn stream_usage_type_still_reads_full_counts_and_details() {
402 let full = r#"{"prompt_tokens":13171,"completion_tokens":16,"total_tokens":13187,"completion_tokens_details":{"reasoning_tokens":14},"prompt_tokens_details":{"cached_tokens":13056}}"#;
403 let usage: OpenAIStreamUsage = serde_json::from_str(full).expect("full usage must decode");
404 assert_eq!(usage.prompt_tokens, Some(13171));
405 assert_eq!(usage.completion_tokens, Some(16));
406 assert_eq!(usage.total_tokens, Some(13187));
407 assert_eq!(
408 usage.prompt_tokens_details.and_then(|d| d.cached_tokens),
409 Some(13056)
410 );
411 assert_eq!(
412 usage
413 .completion_tokens_details
414 .and_then(|d| d.reasoning_tokens),
415 Some(14)
416 );
417 }
418
419 #[test]
422 fn non_stream_response_without_choices_decodes_as_empty() {
423 let no_choices = r#"{"id":"c1","object":"chat.completion","model":"m","usage":{"prompt_tokens":3,"completion_tokens":5,"total_tokens":8}}"#;
424 let resp: OpenAIChatResponse =
425 serde_json::from_str(no_choices).expect("missing choices must decode");
426 assert!(resp.choices.is_empty());
427 assert_eq!(resp.id, "c1");
429 assert_eq!(resp.model, "m");
430 assert_eq!(resp.usage.prompt_tokens, 3);
431 assert_eq!(resp.usage.total_tokens, 8);
432 }
433
434 #[test]
439 fn non_stream_response_with_null_choices_decodes_as_empty() {
440 let null_choices = r#"{"id":"c1","object":"chat.completion","model":"m","choices":null,"usage":{"prompt_tokens":3,"completion_tokens":5,"total_tokens":8}}"#;
441 let resp: OpenAIChatResponse =
442 serde_json::from_str(null_choices).expect("null choices must decode");
443 assert!(resp.choices.is_empty());
444 assert_eq!(resp.id, "c1");
445 assert_eq!(resp.usage.prompt_tokens, 3);
446 }
447
448 #[test]
453 fn non_stream_response_with_object_choices_is_still_an_error() {
454 let object_choices =
455 r#"{"id":"c1","object":"chat.completion","model":"m","choices":{"0":{}}}"#;
456 let err = serde_json::from_str::<OpenAIChatResponse>(object_choices)
457 .expect_err("object choices must stay an error");
458 assert!(err.to_string().contains("expected a sequence"), "{err}");
459 }
460
461 #[test]
464 fn non_stream_response_with_choices_still_reads_them() {
465 let with_choices = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":5,"total_tokens":8}}"#;
466 let resp: OpenAIChatResponse =
467 serde_json::from_str(with_choices).expect("choices present must decode");
468 assert_eq!(resp.choices.len(), 1);
469 assert_eq!(resp.choices[0].message.content, "hi");
470 assert_eq!(resp.choices[0].finish_reason, "stop");
471 }
472
473 #[test]
476 fn non_stream_response_without_usage_decodes_with_zero_counts() {
477 let no_usage = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}]}"#;
478 let resp: OpenAIChatResponse =
479 serde_json::from_str(no_usage).expect("missing usage must decode");
480 assert_eq!(resp.usage.prompt_tokens, 0);
481 assert_eq!(resp.usage.completion_tokens, 0);
482 assert_eq!(resp.usage.total_tokens, 0);
483 assert_eq!(resp.choices.len(), 1);
485 assert_eq!(resp.choices[0].message.content, "hi");
486 }
487
488 #[test]
492 fn non_stream_response_with_null_usage_decodes_with_zero_counts() {
493 let null_usage = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],"usage":null}"#;
494 let resp: OpenAIChatResponse =
495 serde_json::from_str(null_usage).expect("null usage must decode");
496 assert_eq!(resp.usage.prompt_tokens, 0);
497 assert_eq!(resp.usage.completion_tokens, 0);
498 assert_eq!(resp.usage.total_tokens, 0);
499 assert_eq!(resp.choices.len(), 1);
501 assert_eq!(resp.choices[0].message.content, "hi");
502 }
503
504 #[test]
507 fn non_stream_response_with_usage_reads_the_counts() {
508 let with_usage = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],"usage":{"prompt_tokens":7,"completion_tokens":9,"total_tokens":16}}"#;
509 let resp: OpenAIChatResponse =
510 serde_json::from_str(with_usage).expect("usage present must decode");
511 assert_eq!(resp.usage.prompt_tokens, 7);
512 assert_eq!(resp.usage.completion_tokens, 9);
513 assert_eq!(resp.usage.total_tokens, 16);
514 }
515
516 #[test]
522 fn stream_choices_accepts_every_non_array_shape() {
523 for body in [
524 r#"{"id":"c1","choices":null}"#,
525 r#"{"id":"c1"}"#,
526 r#"{"id":"c1","choices":{"0":{}}}"#,
527 r#"{"id":"c1","choices":123}"#,
528 ] {
529 let chunk: OpenAIStreamChunk =
530 serde_json::from_str(body).unwrap_or_else(|e| panic!("{body} must decode: {e}"));
531 assert!(chunk.choices.is_empty(), "{body}");
532 assert_eq!(chunk.id, "c1", "{body}");
534 }
535 }
536
537 #[test]
540 fn stream_choices_still_decodes_a_real_array() {
541 let real = r#"{"id":"c1","choices":[{"index":0,"delta":{"content":"hi"}}]}"#;
542 let chunk: OpenAIStreamChunk = serde_json::from_str(real).expect("real array must decode");
543 assert_eq!(chunk.choices.len(), 1);
544 assert_eq!(chunk.choices[0].delta.content.as_deref(), Some("hi"));
545 }
546
547 #[test]
549 fn stream_choice_without_delta_decodes_to_an_empty_delta() {
550 let no_delta = r#"{"id":"c1","choices":[{"index":0,"finish_reason":"stop"}]}"#;
551 let chunk: OpenAIStreamChunk =
552 serde_json::from_str(no_delta).expect("missing delta must decode");
553 let choice = chunk.choices.first().expect("choice present");
554 assert!(choice.delta.role.is_none());
555 assert!(choice.delta.content.is_none());
556 assert!(choice.delta.reasoning_content.is_none());
557 assert!(choice.delta.tool_calls.is_none());
558 assert_eq!(choice.finish_reason.as_deref(), Some("stop"));
559 }
560
561 #[test]
564 fn stream_choice_with_delta_still_reads_its_content() {
565 let with_delta = r#"{"id":"c1","choices":[{"index":0,"delta":{"content":"hi"}}]}"#;
566 let chunk: OpenAIStreamChunk =
567 serde_json::from_str(with_delta).expect("delta present must decode");
568 let choice = chunk.choices.first().expect("choice present");
569 assert_eq!(choice.delta.content.as_deref(), Some("hi"));
570 }
571
572 #[test]
574 fn stream_tool_call_index_absent_is_not_zero() {
575 let absent: OpenAIStreamToolCall =
576 serde_json::from_str(r#"{"id":"call_1","function":{"arguments":"{}"}}"#)
577 .expect("absent index must decode");
578 assert_eq!(absent.index, None);
579 assert_eq!(absent.function.name, None);
580
581 let zero: OpenAIStreamToolCall =
583 serde_json::from_str(r#"{"index":0,"function":{"name":"f","arguments":"{}"}}"#)
584 .expect("explicit index must decode");
585 assert_eq!(zero.index, Some(0));
586 assert_eq!(zero.function.name.as_deref(), Some("f"));
587 }
588}