use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value;
fn de_string_or_empty<'de, D>(deserializer: D) -> std::result::Result<String, D::Error>
where
D: Deserializer<'de>,
{
Ok(Option::<String>::deserialize(deserializer)?.unwrap_or_default())
}
fn de_arguments_as_string<'de, D>(deserializer: D) -> std::result::Result<String, D::Error>
where
D: Deserializer<'de>,
{
Ok(match Value::deserialize(deserializer)? {
Value::Null => String::new(),
Value::String(s) => s,
other => other.to_string(),
})
}
fn de_usage_or_default<'de, D>(deserializer: D) -> std::result::Result<OpenAIUsage, D::Error>
where
D: Deserializer<'de>,
{
Ok(Option::<OpenAIUsage>::deserialize(deserializer)?.unwrap_or_default())
}
fn de_choices_or_empty<'de, D>(
deserializer: D,
) -> std::result::Result<Vec<OpenAIChatChoice>, D::Error>
where
D: Deserializer<'de>,
{
Ok(Option::<Vec<OpenAIChatChoice>>::deserialize(deserializer)?.unwrap_or_default())
}
fn de_choices_lenient<'de, D>(
deserializer: D,
) -> std::result::Result<Vec<OpenAIStreamChoice>, D::Error>
where
D: Deserializer<'de>,
{
match Value::deserialize(deserializer)? {
value @ Value::Array(_) => serde_json::from_value(value).map_err(serde::de::Error::custom),
_ => Ok(Vec::new()),
}
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIChatResponse {
pub id: String,
pub object: String,
pub model: String,
#[serde(default, deserialize_with = "de_choices_or_empty")]
pub choices: Vec<OpenAIChatChoice>,
#[serde(default, deserialize_with = "de_usage_or_default")]
pub usage: OpenAIUsage,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIChatChoice {
pub index: i64,
pub message: OpenAIChatMessage,
#[serde(default, deserialize_with = "de_string_or_empty")]
pub finish_reason: String,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIChatMessage {
pub role: String,
#[serde(default, deserialize_with = "de_string_or_empty")]
pub content: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_calls: Option<Vec<OpenAIToolCall>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reasoning_content: Option<String>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIToolCall {
pub id: String,
pub r#type: String,
pub function: OpenAIFunctionCall,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIFunctionCall {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
#[serde(default, deserialize_with = "de_arguments_as_string")]
pub arguments: String,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIUsage {
pub prompt_tokens: i64,
pub completion_tokens: i64,
pub total_tokens: i64,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamUsage {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub prompt_tokens: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub completion_tokens: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub total_tokens: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub prompt_tokens_details: Option<OpenAIStreamUsagePromptDetails>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub completion_tokens_details: Option<OpenAIStreamUsageCompletionDetails>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamUsagePromptDetails {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cached_tokens: Option<i64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamUsageCompletionDetails {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reasoning_tokens: Option<i64>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamChunk {
#[serde(default)]
pub id: String,
#[serde(default)]
pub object: String,
#[serde(default, deserialize_with = "de_choices_lenient")]
pub choices: Vec<OpenAIStreamChoice>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub usage: Option<OpenAIStreamUsage>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamChoice {
#[serde(default)]
pub index: i64,
#[serde(default)]
pub delta: OpenAIStreamDelta,
#[serde(default)]
pub finish_reason: Option<String>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamDelta {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub role: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reasoning_content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_calls: Option<Vec<OpenAIStreamToolCall>>,
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct OpenAIStreamToolCall {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub index: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub r#type: Option<String>,
#[serde(default)]
pub function: OpenAIFunctionCall,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn serialized_shape_is_pinned() {
let message = OpenAIChatMessage {
role: "assistant".to_string(),
content: String::new(),
tool_calls: None,
reasoning_content: None,
};
assert_eq!(
serde_json::to_string(&message).unwrap_or_default(),
r#"{"role":"assistant","content":""}"#
);
let function = OpenAIFunctionCall::default();
assert_eq!(
serde_json::to_string(&function).unwrap_or_default(),
r#"{"arguments":""}"#
);
assert_eq!(
serde_json::to_string(&OpenAIFunctionCall {
name: Some("get_weather".to_string()),
arguments: "{}".to_string(),
})
.unwrap_or_default(),
r#"{"name":"get_weather","arguments":"{}"}"#
);
let choice = OpenAIChatChoice::default();
assert_eq!(
serde_json::to_string(&choice).unwrap_or_default(),
r#"{"index":0,"message":{"role":"","content":""},"finish_reason":""}"#
);
let chunk = OpenAIStreamChunk::default();
assert_eq!(
serde_json::to_string(&chunk).unwrap_or_default(),
r#"{"id":"","object":"","choices":[]}"#
);
let tool_call = OpenAIStreamToolCall::default();
assert_eq!(
serde_json::to_string(&tool_call).unwrap_or_default(),
r#"{"function":{"arguments":""}}"#
);
assert_eq!(
serde_json::to_string(&OpenAIStreamToolCall {
index: Some(0),
..Default::default()
})
.unwrap_or_default(),
r#"{"index":0,"function":{"arguments":""}}"#
);
assert_eq!(
serde_json::to_string(&OpenAIStreamUsage::default()).unwrap_or_default(),
"{}"
);
}
#[test]
fn stream_usage_type_accepts_partial_counts() {
let partial = r#"{"choices":[],"usage":{"prompt_tokens":1,"completion_tokens":2}}"#;
let chunk: OpenAIStreamChunk =
serde_json::from_str(partial).expect("partial usage counts must decode");
let usage = serde_json::to_value(&chunk.usage).unwrap_or(Value::Null);
assert_eq!(
usage,
serde_json::json!({ "prompt_tokens": 1, "completion_tokens": 2 })
);
}
#[test]
fn stream_usage_type_still_reads_full_counts_and_details() {
let full = r#"{"prompt_tokens":13171,"completion_tokens":16,"total_tokens":13187,"completion_tokens_details":{"reasoning_tokens":14},"prompt_tokens_details":{"cached_tokens":13056}}"#;
let usage: OpenAIStreamUsage = serde_json::from_str(full).expect("full usage must decode");
assert_eq!(usage.prompt_tokens, Some(13171));
assert_eq!(usage.completion_tokens, Some(16));
assert_eq!(usage.total_tokens, Some(13187));
assert_eq!(
usage.prompt_tokens_details.and_then(|d| d.cached_tokens),
Some(13056)
);
assert_eq!(
usage
.completion_tokens_details
.and_then(|d| d.reasoning_tokens),
Some(14)
);
}
#[test]
fn non_stream_response_without_choices_decodes_as_empty() {
let no_choices = r#"{"id":"c1","object":"chat.completion","model":"m","usage":{"prompt_tokens":3,"completion_tokens":5,"total_tokens":8}}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(no_choices).expect("missing choices must decode");
assert!(resp.choices.is_empty());
assert_eq!(resp.id, "c1");
assert_eq!(resp.model, "m");
assert_eq!(resp.usage.prompt_tokens, 3);
assert_eq!(resp.usage.total_tokens, 8);
}
#[test]
fn non_stream_response_with_null_choices_decodes_as_empty() {
let null_choices = r#"{"id":"c1","object":"chat.completion","model":"m","choices":null,"usage":{"prompt_tokens":3,"completion_tokens":5,"total_tokens":8}}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(null_choices).expect("null choices must decode");
assert!(resp.choices.is_empty());
assert_eq!(resp.id, "c1");
assert_eq!(resp.usage.prompt_tokens, 3);
}
#[test]
fn non_stream_response_with_object_choices_is_still_an_error() {
let object_choices =
r#"{"id":"c1","object":"chat.completion","model":"m","choices":{"0":{}}}"#;
let err = serde_json::from_str::<OpenAIChatResponse>(object_choices)
.expect_err("object choices must stay an error");
assert!(err.to_string().contains("expected a sequence"), "{err}");
}
#[test]
fn non_stream_response_with_choices_still_reads_them() {
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}}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(with_choices).expect("choices present must decode");
assert_eq!(resp.choices.len(), 1);
assert_eq!(resp.choices[0].message.content, "hi");
assert_eq!(resp.choices[0].finish_reason, "stop");
}
#[test]
fn non_stream_response_without_usage_decodes_with_zero_counts() {
let no_usage = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}]}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(no_usage).expect("missing usage must decode");
assert_eq!(resp.usage.prompt_tokens, 0);
assert_eq!(resp.usage.completion_tokens, 0);
assert_eq!(resp.usage.total_tokens, 0);
assert_eq!(resp.choices.len(), 1);
assert_eq!(resp.choices[0].message.content, "hi");
}
#[test]
fn non_stream_response_with_null_usage_decodes_with_zero_counts() {
let null_usage = r#"{"id":"c1","object":"chat.completion","model":"m","choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],"usage":null}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(null_usage).expect("null usage must decode");
assert_eq!(resp.usage.prompt_tokens, 0);
assert_eq!(resp.usage.completion_tokens, 0);
assert_eq!(resp.usage.total_tokens, 0);
assert_eq!(resp.choices.len(), 1);
assert_eq!(resp.choices[0].message.content, "hi");
}
#[test]
fn non_stream_response_with_usage_reads_the_counts() {
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}}"#;
let resp: OpenAIChatResponse =
serde_json::from_str(with_usage).expect("usage present must decode");
assert_eq!(resp.usage.prompt_tokens, 7);
assert_eq!(resp.usage.completion_tokens, 9);
assert_eq!(resp.usage.total_tokens, 16);
}
#[test]
fn stream_choices_accepts_every_non_array_shape() {
for body in [
r#"{"id":"c1","choices":null}"#,
r#"{"id":"c1"}"#,
r#"{"id":"c1","choices":{"0":{}}}"#,
r#"{"id":"c1","choices":123}"#,
] {
let chunk: OpenAIStreamChunk =
serde_json::from_str(body).unwrap_or_else(|e| panic!("{body} must decode: {e}"));
assert!(chunk.choices.is_empty(), "{body}");
assert_eq!(chunk.id, "c1", "{body}");
}
}
#[test]
fn stream_choices_still_decodes_a_real_array() {
let real = r#"{"id":"c1","choices":[{"index":0,"delta":{"content":"hi"}}]}"#;
let chunk: OpenAIStreamChunk = serde_json::from_str(real).expect("real array must decode");
assert_eq!(chunk.choices.len(), 1);
assert_eq!(chunk.choices[0].delta.content.as_deref(), Some("hi"));
}
#[test]
fn stream_choice_without_delta_decodes_to_an_empty_delta() {
let no_delta = r#"{"id":"c1","choices":[{"index":0,"finish_reason":"stop"}]}"#;
let chunk: OpenAIStreamChunk =
serde_json::from_str(no_delta).expect("missing delta must decode");
let choice = chunk.choices.first().expect("choice present");
assert!(choice.delta.role.is_none());
assert!(choice.delta.content.is_none());
assert!(choice.delta.reasoning_content.is_none());
assert!(choice.delta.tool_calls.is_none());
assert_eq!(choice.finish_reason.as_deref(), Some("stop"));
}
#[test]
fn stream_choice_with_delta_still_reads_its_content() {
let with_delta = r#"{"id":"c1","choices":[{"index":0,"delta":{"content":"hi"}}]}"#;
let chunk: OpenAIStreamChunk =
serde_json::from_str(with_delta).expect("delta present must decode");
let choice = chunk.choices.first().expect("choice present");
assert_eq!(choice.delta.content.as_deref(), Some("hi"));
}
#[test]
fn stream_tool_call_index_absent_is_not_zero() {
let absent: OpenAIStreamToolCall =
serde_json::from_str(r#"{"id":"call_1","function":{"arguments":"{}"}}"#)
.expect("absent index must decode");
assert_eq!(absent.index, None);
assert_eq!(absent.function.name, None);
let zero: OpenAIStreamToolCall =
serde_json::from_str(r#"{"index":0,"function":{"name":"f","arguments":"{}"}}"#)
.expect("explicit index must decode");
assert_eq!(zero.index, Some(0));
assert_eq!(zero.function.name.as_deref(), Some("f"));
}
}