ramvamp-server 0.1.1

OpenAI-compatible HTTP server for the ramvamp runtime: request/response shapes, SSE streaming, prompt assembly, prefix-cached generation, and error mapping
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
//! `/v1/chat/completions` response shapes, streaming and not, plus the
//! `/v1/models` and `/health` bodies.
//!
//! The shapes are OpenAI's to the byte, including the parts that look
//! redundant. `object` is a literal discriminant some clients switch on;
//! `finish_reason` is serialized as `null` on non-final chunks rather than
//! omitted, because a client that reads `choices[0].finish_reason` positionally
//! sees a missing key as a malformed chunk. Where a field is genuinely optional
//! (`usage` on a chunk, `tool_calls` on a delta) it is omitted, which is what
//! OpenAI's own stream does for at least one of them and no client objects to.
//!
//! Nothing here reads a clock or a random source: `id` and `created` are
//! parameters. That keeps the crate free of I/O and every assertion below
//! deterministic — a test can pin the exact bytes of a chunk, which is the only
//! way to pin a streaming contract.

use serde::{Deserialize, Serialize};

/// The `object` discriminant of a non-streaming completion.
pub const OBJECT_CHAT_COMPLETION: &str = "chat.completion";

/// The prefix every completion id carries.
///
/// Lives here rather than at the mint site because it is also *read*: a call
/// id is derived from the completion id with this stripped off (see
/// [`crate::toolcall::call_id`]), and the two must not drift apart.
pub const COMPLETION_ID_PREFIX: &str = "chatcmpl-";

/// The `object` discriminant of a streaming chunk.
pub const OBJECT_CHAT_COMPLETION_CHUNK: &str = "chat.completion.chunk";

/// The `object` discriminant of a list body.
pub const OBJECT_LIST: &str = "list";

/// The `object` discriminant of a model card.
pub const OBJECT_MODEL: &str = "model";

/// Why generation stopped, in OpenAI's vocabulary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FinishReason {
    /// A stop token or stop sequence ended the reply.
    Stop,
    /// The token budget ran out.
    Length,
    /// The model asked to call a tool.
    ToolCalls,
    /// Output was withheld. Never produced by this build; present because the
    /// value round-trips through client-side transcripts.
    ContentFilter,
}

/// Token accounting for one request.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Usage {
    /// Tokens prefilled, including the ChatML markers this server adds.
    pub prompt_tokens: u32,
    /// Tokens generated, stop token excluded.
    pub completion_tokens: u32,
    /// Their sum.
    pub total_tokens: u32,
}

impl Usage {
    /// Usage with the total derived, so the three numbers cannot disagree.
    ///
    /// Saturating rather than wrapping: an implausible count should report an
    /// implausible total, never a small one.
    pub fn new(prompt_tokens: u32, completion_tokens: u32) -> Self {
        Usage {
            prompt_tokens,
            completion_tokens,
            total_tokens: prompt_tokens.saturating_add(completion_tokens),
        }
    }
}

/// The assistant message of a non-streaming completion.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResponseMessage {
    /// Always `assistant`.
    pub role: String,
    /// The reply text.
    pub content: Option<String>,
    /// Calls the model requested. Omitted when there are none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<crate::request::ToolCall>>,
}

impl ResponseMessage {
    /// An assistant message carrying `content`.
    pub fn assistant(content: impl Into<String>) -> Self {
        ResponseMessage::calling(content, Vec::new())
    }

    /// An assistant message carrying `content` and the calls it asked for.
    ///
    /// No calls means the key is omitted rather than serialized as `[]`:
    /// clients branch on the field being *present*, and an empty array reads
    /// to some of them as "this turn wants tools" — which then waits forever
    /// for a `tool` message that is never coming.
    ///
    /// `content` stays a `Some`, empty string included, rather than becoming
    /// `null` on a pure tool-call turn. Both are legal and clients accept
    /// either; the empty string is the one that cannot be rendered as the
    /// literal text `None` by a client that formats it naively.
    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),
        }
    }
}

/// One choice of a non-streaming completion.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Choice {
    /// Position in `choices`. Always 0 here: `n > 1` is refused.
    pub index: u32,
    /// The reply.
    pub message: ResponseMessage,
    /// Why it ended.
    pub finish_reason: Option<FinishReason>,
}

/// A non-streaming `chat.completion`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChatCompletion {
    /// Completion id, conventionally `chatcmpl-...`.
    pub id: String,
    /// Always [`OBJECT_CHAT_COMPLETION`].
    pub object: String,
    /// Unix seconds.
    pub created: u64,
    /// The model name the client asked for, echoed back.
    pub model: String,
    /// Exactly one choice.
    pub choices: Vec<Choice>,
    /// Token accounting.
    pub usage: Usage,
}

impl ChatCompletion {
    /// The single-choice completion this server always returns.
    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,
        )
    }

    /// The same, around a message that was assembled elsewhere — a reply that
    /// carries tool calls, whose content and calls come out of one parse.
    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,
        }
    }
}

/// One entry of a streaming `tool_calls` delta.
///
/// OpenAI fragments this shape across many deltas — it streams `arguments` as
/// the model generates them, so a client is handed a name, then argument text
/// in pieces, and reassembles them by `index`. This server has the whole block
/// buffered before it recognises it as a call at all (see
/// [`crate::toolcall::CallStream`]), so every field is filled on the one delta
/// the call produces. A client that assembles fragments handles a complete
/// entry as the trivial case of the same rule.
///
/// `index` is therefore the one field that is not decoration: it is how a
/// client knows which call an entry belongs to, and two calls in one turn are
/// indistinguishable without it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolCallDelta {
    /// Position in this response's `tool_calls`.
    pub index: u32,
    /// The call id, matched by the `tool` message's `tool_call_id`. Minted by
    /// [`crate::toolcall::wire_call`], the same function the buffered path
    /// uses, so both paths name the same call identically.
    pub id: String,
    /// Always `function`.
    #[serde(rename = "type")]
    pub kind: String,
    /// Name and arguments, complete.
    pub function: crate::request::FunctionCall,
}

/// The incremental half of a streaming choice.
///
/// Every field is optional and every absent field is omitted, which is what
/// makes the four chunk shapes distinguishable on the wire: `{"role":...,
/// "content":""}`, `{"content":"..."}`, `{"tool_calls":[...]}`, and `{}`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Delta {
    /// Sent once, on the first chunk.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
    /// A slice of the reply.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
    /// Calls the model asked for, one entry per call. Omitted rather than
    /// empty: a client branches on the key being present.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<ToolCallDelta>>,
}

/// One choice of a streaming chunk.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChunkChoice {
    /// Always 0.
    pub index: u32,
    /// What changed.
    pub delta: Delta,
    /// `null` until the final chunk. Serialized even when null: a client
    /// reading the key positionally treats an absent one as a broken chunk.
    pub finish_reason: Option<FinishReason>,
}

/// A streaming `chat.completion.chunk`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChatCompletionChunk {
    /// Same id for every chunk of one response.
    pub id: String,
    /// Always [`OBJECT_CHAT_COMPLETION_CHUNK`].
    pub object: String,
    /// Unix seconds, same for every chunk of one response.
    pub created: u64,
    /// The model name the client asked for.
    pub model: String,
    /// One choice, or none at all on the usage chunk.
    pub choices: Vec<ChunkChoice>,
    /// Present only on the usage chunk.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub usage: Option<Usage>,
}

/// Builds the chunks of one streaming response.
///
/// Holds the fields that must be identical across every chunk (`id`,
/// `created`, `model`) so they cannot drift, and names the four chunk shapes
/// so the emission order is readable at the call site:
///
/// 1. [`role`](Self::role) — `delta: {"role":"assistant","content":""}`
/// 2. [`content`](Self::content) — `delta: {"content":"..."}`, repeated
/// 3. [`tool_call`](Self::tool_call) — `delta: {"tool_calls":[...]}`, once per
///    call the model asked for, interleaved with the content
/// 4. [`usage`](Self::usage) — `choices: []` plus `usage`, only when
///    `stream_options.include_usage` was set, and immediately *before* the
///    sentinel rather than after: a client stops reading at `[DONE]`, so usage
///    emitted after it is usage nobody receives
/// 5. [`finish`](Self::finish) — `delta: {}` plus `finish_reason`
///
/// The order on the wire is 1, (2|3)*, 5, 4?, then `data: [DONE]`.
#[derive(Debug, Clone)]
pub struct ChunkBuilder {
    id: String,
    created: u64,
    model: String,
}

impl ChunkBuilder {
    /// A builder for the response identified by `id`.
    pub fn new(id: impl Into<String>, created: u64, model: impl Into<String>) -> Self {
        ChunkBuilder {
            id: id.into(),
            created,
            model: model.into(),
        }
    }

    /// The completion id every chunk carries.
    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,
        }
    }

    /// The opening chunk: role plus empty content.
    ///
    /// `content` is `""` and not omitted because clients that concatenate
    /// `delta.content` unconditionally would otherwise see their first read
    /// fail on a missing key.
    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,
        )
    }

    /// A content chunk.
    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,
        )
    }

    /// One call, complete, in a single delta.
    ///
    /// `content` is absent rather than `""`: a client concatenating
    /// `delta.content` would otherwise append an empty string for a chunk that
    /// carries no text at all, and a client switching on which key is present
    /// would see two answers to that question in one delta.
    ///
    /// `index` saturates rather than wrapping. A turn with four billion calls
    /// in it is not a case worth modelling, and reporting call `u32::MAX` twice
    /// is a visible fault where wrapping to `0` would silently overwrite the
    /// first call in the client's table.
    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,
        )
    }

    /// The closing chunk: empty delta plus the reason.
    pub fn finish(&self, reason: FinishReason) -> ChatCompletionChunk {
        self.chunk(
            vec![ChunkChoice {
                index: 0,
                delta: Delta::default(),
                finish_reason: Some(reason),
            }],
            None,
        )
    }

    /// The usage-only chunk: no choices, one usage object.
    pub fn usage(&self, usage: Usage) -> ChatCompletionChunk {
        self.chunk(Vec::new(), Some(usage))
    }
}

/// One entry of `GET /v1/models`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ModelCard {
    /// The model name, as it must be sent back in `model`.
    pub id: String,
    /// Always [`OBJECT_MODEL`].
    pub object: String,
    /// Unix seconds; the install time is the honest value.
    pub created: u64,
    /// Owner. `ramvamp` for a local install — there is no account behind it.
    pub owned_by: String,
}

/// The `GET /v1/models` body.
///
/// A list of one: this process serves the install it was started with, and a
/// client's model picker should show exactly that.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ModelList {
    /// Always [`OBJECT_LIST`].
    pub object: String,
    /// The models.
    pub data: Vec<ModelCard>,
}

impl ModelList {
    /// The one-model listing.
    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(),
            }],
        }
    }
}

/// The `GET /health` body when the model is up.
///
/// Mirrors llama.cpp's contract — `{"status":"ok"}` on 200, an error body on
/// 503 while loading — because local tooling already probes that endpoint and
/// expects that pair. See [`crate::error::ServerError::ModelLoading`] for the
/// other half.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Health {
    /// `ok`.
    pub status: String,
}

impl Health {
    /// The ready body.
    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);
        }
    }

    /// The whole streaming contract in one place: shape, order, and the exact
    /// keys present in each delta.
    #[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);

        // Every chunk of one response shares id, object, created and model.
        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");
        }
    }

    /// The tool-call delta, pinned field by field. This is the shape an agent
    /// client switches on, and `index` is the field it cannot do without.
    #[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");
        // `arguments` is a JSON *string*, byte for byte what the model wrote.
        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());

        // A second call in the same turn is index 1, which is the only thing
        // telling a client the two apart.
        let second = json(&builder.tool_call(1, call));
        assert_eq!(second["choices"][0]["delta"]["tool_calls"][0]["index"], 1);
    }

    /// `finish_reason` must be an explicit `null`, not an absent key.
    #[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"}));
        // The loading half is an error body, not a `status` field.
        assert_eq!(ServerError::ModelLoading.status(), 503);
    }
}