use serde::{Deserialize, Serialize};
pub const OBJECT_CHAT_COMPLETION: &str = "chat.completion";
pub const COMPLETION_ID_PREFIX: &str = "chatcmpl-";
pub const OBJECT_CHAT_COMPLETION_CHUNK: &str = "chat.completion.chunk";
pub const OBJECT_LIST: &str = "list";
pub const OBJECT_MODEL: &str = "model";
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FinishReason {
Stop,
Length,
ToolCalls,
ContentFilter,
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Usage {
pub prompt_tokens: u32,
pub completion_tokens: u32,
pub total_tokens: u32,
}
impl Usage {
pub fn new(prompt_tokens: u32, completion_tokens: u32) -> Self {
Usage {
prompt_tokens,
completion_tokens,
total_tokens: prompt_tokens.saturating_add(completion_tokens),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResponseMessage {
pub role: String,
pub content: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_calls: Option<Vec<crate::request::ToolCall>>,
}
impl ResponseMessage {
pub fn assistant(content: impl Into<String>) -> Self {
ResponseMessage::calling(content, Vec::new())
}
pub fn calling(content: impl Into<String>, tool_calls: Vec<crate::request::ToolCall>) -> Self {
ResponseMessage {
role: crate::request::MessageRole::Assistant.as_str().to_owned(),
content: Some(content.into()),
tool_calls: (!tool_calls.is_empty()).then_some(tool_calls),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Choice {
pub index: u32,
pub message: ResponseMessage,
pub finish_reason: Option<FinishReason>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChatCompletion {
pub id: String,
pub object: String,
pub created: u64,
pub model: String,
pub choices: Vec<Choice>,
pub usage: Usage,
}
impl ChatCompletion {
pub fn single(
id: impl Into<String>,
created: u64,
model: impl Into<String>,
content: impl Into<String>,
finish_reason: FinishReason,
usage: Usage,
) -> Self {
ChatCompletion::from_message(
id,
created,
model,
ResponseMessage::assistant(content),
finish_reason,
usage,
)
}
pub fn from_message(
id: impl Into<String>,
created: u64,
model: impl Into<String>,
message: ResponseMessage,
finish_reason: FinishReason,
usage: Usage,
) -> Self {
ChatCompletion {
id: id.into(),
object: OBJECT_CHAT_COMPLETION.to_owned(),
created,
model: model.into(),
choices: vec![Choice {
index: 0,
message,
finish_reason: Some(finish_reason),
}],
usage,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolCallDelta {
pub index: u32,
pub id: String,
#[serde(rename = "type")]
pub kind: String,
pub function: crate::request::FunctionCall,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Delta {
#[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 tool_calls: Option<Vec<ToolCallDelta>>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChunkChoice {
pub index: u32,
pub delta: Delta,
pub finish_reason: Option<FinishReason>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChatCompletionChunk {
pub id: String,
pub object: String,
pub created: u64,
pub model: String,
pub choices: Vec<ChunkChoice>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub usage: Option<Usage>,
}
#[derive(Debug, Clone)]
pub struct ChunkBuilder {
id: String,
created: u64,
model: String,
}
impl ChunkBuilder {
pub fn new(id: impl Into<String>, created: u64, model: impl Into<String>) -> Self {
ChunkBuilder {
id: id.into(),
created,
model: model.into(),
}
}
pub fn id(&self) -> &str {
&self.id
}
fn chunk(&self, choices: Vec<ChunkChoice>, usage: Option<Usage>) -> ChatCompletionChunk {
ChatCompletionChunk {
id: self.id.clone(),
object: OBJECT_CHAT_COMPLETION_CHUNK.to_owned(),
created: self.created,
model: self.model.clone(),
choices,
usage,
}
}
pub fn role(&self) -> ChatCompletionChunk {
self.chunk(
vec![ChunkChoice {
index: 0,
delta: Delta {
role: Some(crate::request::MessageRole::Assistant.as_str().to_owned()),
content: Some(String::new()),
tool_calls: None,
},
finish_reason: None,
}],
None,
)
}
pub fn content(&self, text: impl Into<String>) -> ChatCompletionChunk {
self.chunk(
vec![ChunkChoice {
index: 0,
delta: Delta {
role: None,
content: Some(text.into()),
tool_calls: None,
},
finish_reason: None,
}],
None,
)
}
pub fn tool_call(&self, index: usize, call: crate::request::ToolCall) -> ChatCompletionChunk {
self.chunk(
vec![ChunkChoice {
index: 0,
delta: Delta {
role: None,
content: None,
tool_calls: Some(vec![ToolCallDelta {
index: u32::try_from(index).unwrap_or(u32::MAX),
id: call.id,
kind: call.kind,
function: call.function,
}]),
},
finish_reason: None,
}],
None,
)
}
pub fn finish(&self, reason: FinishReason) -> ChatCompletionChunk {
self.chunk(
vec![ChunkChoice {
index: 0,
delta: Delta::default(),
finish_reason: Some(reason),
}],
None,
)
}
pub fn usage(&self, usage: Usage) -> ChatCompletionChunk {
self.chunk(Vec::new(), Some(usage))
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ModelCard {
pub id: String,
pub object: String,
pub created: u64,
pub owned_by: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ModelList {
pub object: String,
pub data: Vec<ModelCard>,
}
impl ModelList {
pub fn single(id: impl Into<String>, created: u64) -> Self {
ModelList {
object: OBJECT_LIST.to_owned(),
data: vec![ModelCard {
id: id.into(),
object: OBJECT_MODEL.to_owned(),
created,
owned_by: "ramvamp".to_owned(),
}],
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Health {
pub status: String,
}
impl Health {
pub fn ok() -> Self {
Health {
status: "ok".to_owned(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::error::ServerError;
fn json(value: &impl Serialize) -> serde_json::Value {
serde_json::to_value(value).expect("response types always serialize")
}
#[test]
fn completion_object_is_the_literal_discriminant() {
let completion = ChatCompletion::single(
"chatcmpl-1",
1_700_000_000,
"qwen3-30b-a3b",
"hi",
FinishReason::Stop,
Usage::new(10, 2),
);
let value = json(&completion);
assert_eq!(value["object"], OBJECT_CHAT_COMPLETION);
assert_eq!(value["object"], "chat.completion");
assert_eq!(value["id"], "chatcmpl-1");
assert_eq!(value["created"], 1_700_000_000u64);
assert_eq!(value["model"], "qwen3-30b-a3b");
assert_eq!(value["choices"][0]["index"], 0);
assert_eq!(value["choices"][0]["message"]["role"], "assistant");
assert_eq!(value["choices"][0]["message"]["content"], "hi");
assert_eq!(value["choices"][0]["finish_reason"], "stop");
assert_eq!(value["usage"]["prompt_tokens"], 10);
assert_eq!(value["usage"]["completion_tokens"], 2);
assert_eq!(value["usage"]["total_tokens"], 12);
}
#[test]
fn usage_total_is_derived_and_saturates() {
assert_eq!(Usage::new(3, 4).total_tokens, 7);
assert_eq!(Usage::new(u32::MAX, 1).total_tokens, u32::MAX);
}
#[test]
fn finish_reasons_use_openai_spellings() {
for (reason, wire) in [
(FinishReason::Stop, "stop"),
(FinishReason::Length, "length"),
(FinishReason::ToolCalls, "tool_calls"),
(FinishReason::ContentFilter, "content_filter"),
] {
assert_eq!(json(&reason), wire);
}
}
#[test]
fn streaming_chunk_sequence_is_exact() {
let builder = ChunkBuilder::new("chatcmpl-x", 42, "m");
let role = json(&builder.role());
assert_eq!(role["object"], "chat.completion.chunk");
assert_eq!(role["id"], "chatcmpl-x");
assert_eq!(role["created"], 42);
assert_eq!(role["model"], "m");
assert_eq!(role["choices"][0]["delta"]["role"], "assistant");
assert_eq!(role["choices"][0]["delta"]["content"], "");
assert!(role["choices"][0]["finish_reason"].is_null());
assert!(
role.get("usage").is_none(),
"no usage outside the usage chunk"
);
let content = json(&builder.content("hel"));
assert_eq!(content["choices"][0]["delta"]["content"], "hel");
assert!(
content["choices"][0]["delta"].get("role").is_none(),
"role is sent once, on the first chunk only"
);
assert!(content["choices"][0]["finish_reason"].is_null());
let finish = json(&builder.finish(FinishReason::Stop));
assert_eq!(
finish["choices"][0]["delta"],
serde_json::json!({}),
"the final delta is empty"
);
assert_eq!(finish["choices"][0]["finish_reason"], "stop");
let usage = json(&builder.usage(Usage::new(7, 3)));
assert_eq!(
usage["choices"],
serde_json::json!([]),
"the usage chunk carries no choices"
);
assert_eq!(usage["usage"]["prompt_tokens"], 7);
assert_eq!(usage["usage"]["completion_tokens"], 3);
assert_eq!(usage["usage"]["total_tokens"], 10);
for chunk in [role, content, finish, usage] {
assert_eq!(chunk["id"], "chatcmpl-x");
assert_eq!(chunk["object"], "chat.completion.chunk");
assert_eq!(chunk["created"], 42);
assert_eq!(chunk["model"], "m");
}
}
#[test]
fn a_tool_call_delta_carries_one_complete_call_with_its_index() {
let builder = ChunkBuilder::new("chatcmpl-x", 42, "m");
let call = crate::request::ToolCall {
id: "call_x_0".to_owned(),
kind: "function".to_owned(),
function: crate::request::FunctionCall {
name: "glob".to_owned(),
arguments: r#"{"pattern": "*/.rs"}"#.to_owned(),
},
};
let value = json(&builder.tool_call(0, call.clone()));
assert_eq!(value["object"], "chat.completion.chunk");
let delta = &value["choices"][0]["delta"];
assert_eq!(delta["tool_calls"][0]["index"], 0);
assert_eq!(delta["tool_calls"][0]["id"], "call_x_0");
assert_eq!(delta["tool_calls"][0]["type"], "function");
assert_eq!(delta["tool_calls"][0]["function"]["name"], "glob");
assert_eq!(
delta["tool_calls"][0]["function"]["arguments"],
r#"{"pattern": "*/.rs"}"#
);
assert!(
delta.get("content").is_none(),
"a call delta carries no content key: {delta}"
);
assert!(delta.get("role").is_none(), "{delta}");
assert!(value["choices"][0]["finish_reason"].is_null());
let second = json(&builder.tool_call(1, call));
assert_eq!(second["choices"][0]["delta"]["tool_calls"][0]["index"], 1);
}
#[test]
fn non_final_chunks_serialize_a_null_finish_reason() {
let builder = ChunkBuilder::new("id", 0, "m");
for chunk in [builder.role(), builder.content("x")] {
let text = serde_json::to_string(&chunk).expect("serializes");
assert!(text.contains(r#""finish_reason":null"#), "{text}");
}
}
#[test]
fn chunks_round_trip_through_json() -> Result<(), ServerError> {
let builder = ChunkBuilder::new("id", 1, "m");
for chunk in [
builder.role(),
builder.content("text"),
builder.tool_call(
0,
crate::request::ToolCall {
id: "call_id_0".to_owned(),
kind: "function".to_owned(),
function: crate::request::FunctionCall {
name: "read".to_owned(),
arguments: "{}".to_owned(),
},
},
),
builder.finish(FinishReason::Length),
builder.usage(Usage::new(1, 2)),
] {
let text = serde_json::to_string(&chunk)?;
let back: ChatCompletionChunk = serde_json::from_str(&text)?;
assert_eq!(back, chunk);
}
Ok(())
}
#[test]
fn models_listing_is_a_list_of_one() {
let value = json(&ModelList::single("qwen3-30b-a3b", 1_700_000_000));
assert_eq!(value["object"], "list");
assert_eq!(value["data"][0]["id"], "qwen3-30b-a3b");
assert_eq!(value["data"][0]["object"], "model");
assert_eq!(value["data"][0]["created"], 1_700_000_000u64);
assert_eq!(value["data"][0]["owned_by"], "ramvamp");
assert_eq!(
value["data"].as_array().map(Vec::len),
Some(1),
"one process serves one install"
);
}
#[test]
fn health_ok_matches_the_llama_cpp_contract() {
assert_eq!(json(&Health::ok()), serde_json::json!({"status": "ok"}));
assert_eq!(ServerError::ModelLoading.status(), 503);
}
}