1use serde::{Deserialize, Serialize};
18
19pub const OBJECT_CHAT_COMPLETION: &str = "chat.completion";
21
22pub const COMPLETION_ID_PREFIX: &str = "chatcmpl-";
28
29pub const OBJECT_CHAT_COMPLETION_CHUNK: &str = "chat.completion.chunk";
31
32pub const OBJECT_LIST: &str = "list";
34
35pub const OBJECT_MODEL: &str = "model";
37
38#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
40#[serde(rename_all = "snake_case")]
41pub enum FinishReason {
42 Stop,
44 Length,
46 ToolCalls,
48 ContentFilter,
51}
52
53#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
55pub struct Usage {
56 pub prompt_tokens: u32,
58 pub completion_tokens: u32,
60 pub total_tokens: u32,
62}
63
64impl Usage {
65 pub fn new(prompt_tokens: u32, completion_tokens: u32) -> Self {
70 Usage {
71 prompt_tokens,
72 completion_tokens,
73 total_tokens: prompt_tokens.saturating_add(completion_tokens),
74 }
75 }
76}
77
78#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
80pub struct ResponseMessage {
81 pub role: String,
83 pub content: Option<String>,
85 #[serde(default, skip_serializing_if = "Option::is_none")]
87 pub tool_calls: Option<Vec<crate::request::ToolCall>>,
88}
89
90impl ResponseMessage {
91 pub fn assistant(content: impl Into<String>) -> Self {
93 ResponseMessage::calling(content, Vec::new())
94 }
95
96 pub fn calling(content: impl Into<String>, tool_calls: Vec<crate::request::ToolCall>) -> Self {
108 ResponseMessage {
109 role: crate::request::MessageRole::Assistant.as_str().to_owned(),
110 content: Some(content.into()),
111 tool_calls: (!tool_calls.is_empty()).then_some(tool_calls),
112 }
113 }
114}
115
116#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
118pub struct Choice {
119 pub index: u32,
121 pub message: ResponseMessage,
123 pub finish_reason: Option<FinishReason>,
125}
126
127#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
129pub struct ChatCompletion {
130 pub id: String,
132 pub object: String,
134 pub created: u64,
136 pub model: String,
138 pub choices: Vec<Choice>,
140 pub usage: Usage,
142}
143
144impl ChatCompletion {
145 pub fn single(
147 id: impl Into<String>,
148 created: u64,
149 model: impl Into<String>,
150 content: impl Into<String>,
151 finish_reason: FinishReason,
152 usage: Usage,
153 ) -> Self {
154 ChatCompletion::from_message(
155 id,
156 created,
157 model,
158 ResponseMessage::assistant(content),
159 finish_reason,
160 usage,
161 )
162 }
163
164 pub fn from_message(
167 id: impl Into<String>,
168 created: u64,
169 model: impl Into<String>,
170 message: ResponseMessage,
171 finish_reason: FinishReason,
172 usage: Usage,
173 ) -> Self {
174 ChatCompletion {
175 id: id.into(),
176 object: OBJECT_CHAT_COMPLETION.to_owned(),
177 created,
178 model: model.into(),
179 choices: vec![Choice {
180 index: 0,
181 message,
182 finish_reason: Some(finish_reason),
183 }],
184 usage,
185 }
186 }
187}
188
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
203pub struct ToolCallDelta {
204 pub index: u32,
206 pub id: String,
210 #[serde(rename = "type")]
212 pub kind: String,
213 pub function: crate::request::FunctionCall,
215}
216
217#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
223pub struct Delta {
224 #[serde(default, skip_serializing_if = "Option::is_none")]
226 pub role: Option<String>,
227 #[serde(default, skip_serializing_if = "Option::is_none")]
229 pub content: Option<String>,
230 #[serde(default, skip_serializing_if = "Option::is_none")]
233 pub tool_calls: Option<Vec<ToolCallDelta>>,
234}
235
236#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
238pub struct ChunkChoice {
239 pub index: u32,
241 pub delta: Delta,
243 pub finish_reason: Option<FinishReason>,
246}
247
248#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
250pub struct ChatCompletionChunk {
251 pub id: String,
253 pub object: String,
255 pub created: u64,
257 pub model: String,
259 pub choices: Vec<ChunkChoice>,
261 #[serde(default, skip_serializing_if = "Option::is_none")]
263 pub usage: Option<Usage>,
264}
265
266#[derive(Debug, Clone)]
284pub struct ChunkBuilder {
285 id: String,
286 created: u64,
287 model: String,
288}
289
290impl ChunkBuilder {
291 pub fn new(id: impl Into<String>, created: u64, model: impl Into<String>) -> Self {
293 ChunkBuilder {
294 id: id.into(),
295 created,
296 model: model.into(),
297 }
298 }
299
300 pub fn id(&self) -> &str {
302 &self.id
303 }
304
305 fn chunk(&self, choices: Vec<ChunkChoice>, usage: Option<Usage>) -> ChatCompletionChunk {
306 ChatCompletionChunk {
307 id: self.id.clone(),
308 object: OBJECT_CHAT_COMPLETION_CHUNK.to_owned(),
309 created: self.created,
310 model: self.model.clone(),
311 choices,
312 usage,
313 }
314 }
315
316 pub fn role(&self) -> ChatCompletionChunk {
322 self.chunk(
323 vec![ChunkChoice {
324 index: 0,
325 delta: Delta {
326 role: Some(crate::request::MessageRole::Assistant.as_str().to_owned()),
327 content: Some(String::new()),
328 tool_calls: None,
329 },
330 finish_reason: None,
331 }],
332 None,
333 )
334 }
335
336 pub fn content(&self, text: impl Into<String>) -> ChatCompletionChunk {
338 self.chunk(
339 vec![ChunkChoice {
340 index: 0,
341 delta: Delta {
342 role: None,
343 content: Some(text.into()),
344 tool_calls: None,
345 },
346 finish_reason: None,
347 }],
348 None,
349 )
350 }
351
352 pub fn tool_call(&self, index: usize, call: crate::request::ToolCall) -> ChatCompletionChunk {
364 self.chunk(
365 vec![ChunkChoice {
366 index: 0,
367 delta: Delta {
368 role: None,
369 content: None,
370 tool_calls: Some(vec![ToolCallDelta {
371 index: u32::try_from(index).unwrap_or(u32::MAX),
372 id: call.id,
373 kind: call.kind,
374 function: call.function,
375 }]),
376 },
377 finish_reason: None,
378 }],
379 None,
380 )
381 }
382
383 pub fn finish(&self, reason: FinishReason) -> ChatCompletionChunk {
385 self.chunk(
386 vec![ChunkChoice {
387 index: 0,
388 delta: Delta::default(),
389 finish_reason: Some(reason),
390 }],
391 None,
392 )
393 }
394
395 pub fn usage(&self, usage: Usage) -> ChatCompletionChunk {
397 self.chunk(Vec::new(), Some(usage))
398 }
399}
400
401#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
403pub struct ModelCard {
404 pub id: String,
406 pub object: String,
408 pub created: u64,
410 pub owned_by: String,
412}
413
414#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
419pub struct ModelList {
420 pub object: String,
422 pub data: Vec<ModelCard>,
424}
425
426impl ModelList {
427 pub fn single(id: impl Into<String>, created: u64) -> Self {
429 ModelList {
430 object: OBJECT_LIST.to_owned(),
431 data: vec![ModelCard {
432 id: id.into(),
433 object: OBJECT_MODEL.to_owned(),
434 created,
435 owned_by: "ramvamp".to_owned(),
436 }],
437 }
438 }
439}
440
441#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
448pub struct Health {
449 pub status: String,
451}
452
453impl Health {
454 pub fn ok() -> Self {
456 Health {
457 status: "ok".to_owned(),
458 }
459 }
460}
461
462#[cfg(test)]
463mod tests {
464 use super::*;
465 use crate::error::ServerError;
466
467 fn json(value: &impl Serialize) -> serde_json::Value {
468 serde_json::to_value(value).expect("response types always serialize")
469 }
470
471 #[test]
472 fn completion_object_is_the_literal_discriminant() {
473 let completion = ChatCompletion::single(
474 "chatcmpl-1",
475 1_700_000_000,
476 "qwen3-30b-a3b",
477 "hi",
478 FinishReason::Stop,
479 Usage::new(10, 2),
480 );
481 let value = json(&completion);
482 assert_eq!(value["object"], OBJECT_CHAT_COMPLETION);
483 assert_eq!(value["object"], "chat.completion");
484 assert_eq!(value["id"], "chatcmpl-1");
485 assert_eq!(value["created"], 1_700_000_000u64);
486 assert_eq!(value["model"], "qwen3-30b-a3b");
487 assert_eq!(value["choices"][0]["index"], 0);
488 assert_eq!(value["choices"][0]["message"]["role"], "assistant");
489 assert_eq!(value["choices"][0]["message"]["content"], "hi");
490 assert_eq!(value["choices"][0]["finish_reason"], "stop");
491 assert_eq!(value["usage"]["prompt_tokens"], 10);
492 assert_eq!(value["usage"]["completion_tokens"], 2);
493 assert_eq!(value["usage"]["total_tokens"], 12);
494 }
495
496 #[test]
497 fn usage_total_is_derived_and_saturates() {
498 assert_eq!(Usage::new(3, 4).total_tokens, 7);
499 assert_eq!(Usage::new(u32::MAX, 1).total_tokens, u32::MAX);
500 }
501
502 #[test]
503 fn finish_reasons_use_openai_spellings() {
504 for (reason, wire) in [
505 (FinishReason::Stop, "stop"),
506 (FinishReason::Length, "length"),
507 (FinishReason::ToolCalls, "tool_calls"),
508 (FinishReason::ContentFilter, "content_filter"),
509 ] {
510 assert_eq!(json(&reason), wire);
511 }
512 }
513
514 #[test]
517 fn streaming_chunk_sequence_is_exact() {
518 let builder = ChunkBuilder::new("chatcmpl-x", 42, "m");
519
520 let role = json(&builder.role());
521 assert_eq!(role["object"], "chat.completion.chunk");
522 assert_eq!(role["id"], "chatcmpl-x");
523 assert_eq!(role["created"], 42);
524 assert_eq!(role["model"], "m");
525 assert_eq!(role["choices"][0]["delta"]["role"], "assistant");
526 assert_eq!(role["choices"][0]["delta"]["content"], "");
527 assert!(role["choices"][0]["finish_reason"].is_null());
528 assert!(
529 role.get("usage").is_none(),
530 "no usage outside the usage chunk"
531 );
532
533 let content = json(&builder.content("hel"));
534 assert_eq!(content["choices"][0]["delta"]["content"], "hel");
535 assert!(
536 content["choices"][0]["delta"].get("role").is_none(),
537 "role is sent once, on the first chunk only"
538 );
539 assert!(content["choices"][0]["finish_reason"].is_null());
540
541 let finish = json(&builder.finish(FinishReason::Stop));
542 assert_eq!(
543 finish["choices"][0]["delta"],
544 serde_json::json!({}),
545 "the final delta is empty"
546 );
547 assert_eq!(finish["choices"][0]["finish_reason"], "stop");
548
549 let usage = json(&builder.usage(Usage::new(7, 3)));
550 assert_eq!(
551 usage["choices"],
552 serde_json::json!([]),
553 "the usage chunk carries no choices"
554 );
555 assert_eq!(usage["usage"]["prompt_tokens"], 7);
556 assert_eq!(usage["usage"]["completion_tokens"], 3);
557 assert_eq!(usage["usage"]["total_tokens"], 10);
558
559 for chunk in [role, content, finish, usage] {
561 assert_eq!(chunk["id"], "chatcmpl-x");
562 assert_eq!(chunk["object"], "chat.completion.chunk");
563 assert_eq!(chunk["created"], 42);
564 assert_eq!(chunk["model"], "m");
565 }
566 }
567
568 #[test]
571 fn a_tool_call_delta_carries_one_complete_call_with_its_index() {
572 let builder = ChunkBuilder::new("chatcmpl-x", 42, "m");
573 let call = crate::request::ToolCall {
574 id: "call_x_0".to_owned(),
575 kind: "function".to_owned(),
576 function: crate::request::FunctionCall {
577 name: "glob".to_owned(),
578 arguments: r#"{"pattern": "*/.rs"}"#.to_owned(),
579 },
580 };
581 let value = json(&builder.tool_call(0, call.clone()));
582
583 assert_eq!(value["object"], "chat.completion.chunk");
584 let delta = &value["choices"][0]["delta"];
585 assert_eq!(delta["tool_calls"][0]["index"], 0);
586 assert_eq!(delta["tool_calls"][0]["id"], "call_x_0");
587 assert_eq!(delta["tool_calls"][0]["type"], "function");
588 assert_eq!(delta["tool_calls"][0]["function"]["name"], "glob");
589 assert_eq!(
591 delta["tool_calls"][0]["function"]["arguments"],
592 r#"{"pattern": "*/.rs"}"#
593 );
594 assert!(
595 delta.get("content").is_none(),
596 "a call delta carries no content key: {delta}"
597 );
598 assert!(delta.get("role").is_none(), "{delta}");
599 assert!(value["choices"][0]["finish_reason"].is_null());
600
601 let second = json(&builder.tool_call(1, call));
604 assert_eq!(second["choices"][0]["delta"]["tool_calls"][0]["index"], 1);
605 }
606
607 #[test]
609 fn non_final_chunks_serialize_a_null_finish_reason() {
610 let builder = ChunkBuilder::new("id", 0, "m");
611 for chunk in [builder.role(), builder.content("x")] {
612 let text = serde_json::to_string(&chunk).expect("serializes");
613 assert!(text.contains(r#""finish_reason":null"#), "{text}");
614 }
615 }
616
617 #[test]
618 fn chunks_round_trip_through_json() -> Result<(), ServerError> {
619 let builder = ChunkBuilder::new("id", 1, "m");
620 for chunk in [
621 builder.role(),
622 builder.content("text"),
623 builder.tool_call(
624 0,
625 crate::request::ToolCall {
626 id: "call_id_0".to_owned(),
627 kind: "function".to_owned(),
628 function: crate::request::FunctionCall {
629 name: "read".to_owned(),
630 arguments: "{}".to_owned(),
631 },
632 },
633 ),
634 builder.finish(FinishReason::Length),
635 builder.usage(Usage::new(1, 2)),
636 ] {
637 let text = serde_json::to_string(&chunk)?;
638 let back: ChatCompletionChunk = serde_json::from_str(&text)?;
639 assert_eq!(back, chunk);
640 }
641 Ok(())
642 }
643
644 #[test]
645 fn models_listing_is_a_list_of_one() {
646 let value = json(&ModelList::single("qwen3-30b-a3b", 1_700_000_000));
647 assert_eq!(value["object"], "list");
648 assert_eq!(value["data"][0]["id"], "qwen3-30b-a3b");
649 assert_eq!(value["data"][0]["object"], "model");
650 assert_eq!(value["data"][0]["created"], 1_700_000_000u64);
651 assert_eq!(value["data"][0]["owned_by"], "ramvamp");
652 assert_eq!(
653 value["data"].as_array().map(Vec::len),
654 Some(1),
655 "one process serves one install"
656 );
657 }
658
659 #[test]
660 fn health_ok_matches_the_llama_cpp_contract() {
661 assert_eq!(json(&Health::ok()), serde_json::json!({"status": "ok"}));
662 assert_eq!(ServerError::ModelLoading.status(), 503);
664 }
665}