Skip to main content

dynamo_renderer/
kimi_k3.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Native Kimi K3 and K3.1 XTML prompt rendering.
5//!
6//! K3 does not ship a Jinja chat template. Its model-side `encoding_k3.py`
7//! emits a sequence of segments where protocol markers are encoded with
8//! tiktoken special IDs and message/tool data is encoded as ordinary text.
9//! Keeping that distinction is required both for model parity and to prevent a
10//! literal marker in user content from becoming prompt structure.
11
12use std::collections::HashMap;
13
14use anyhow::{Context, Result, bail};
15use serde_json::{Map, Value};
16
17use crate::{
18    OAIChatLikeRequest, OAIPromptFormatter, PromptRenderError, RenderedPrompt, RenderedSegment,
19    thinking_bool_from_args,
20};
21
22const OPEN_TOKEN: &str = "<|open|>";
23const CLOSE_TOKEN: &str = "<|close|>";
24const SEP_TOKEN: &str = "<|sep|>";
25const END_OF_MSG_TOKEN: &str = "<|end_of_msg|>";
26/// The one token this renderer emits per image.
27///
28/// This is the canonical frontend contract: exactly one `<|media_pad|>` per
29/// image, for every engine. It is a registered special token in the K3
30/// tokenizer (`config.json`'s `media_placeholder_token_id`), so it encodes to
31/// a single id and stays one id no matter what surrounds it.
32///
33/// The checkpoint's other spelling, `<|kimi_image_placeholder|>`, is a plain
34/// string that is *not* in the vocabulary — it BPE-shatters into several ids
35/// whose boundaries depend on neighbouring text. Engines that want that form
36/// (vLLM) convert from the pad on the worker side, where a single known id is
37/// a reliable thing to substitute; matching a shattered string is not.
38///
39/// Equivalent to calling the checkpoint's own
40/// `encoding_k3.build_chat_segments(image_prompts=["<|media_pad|>"] * n)` —
41/// `image_prompts` is the model author's hook for exactly this choice, and
42/// `<|kimi_image_placeholder|>` is only its `None` fallback.
43const MEDIA_PAD: &str = "<|media_pad|>";
44const VALID_THINKING_EFFORTS: &[&str] = &["low", "high", "max"];
45
46#[derive(Debug, Clone, Copy)]
47enum KimiVersion {
48    K3,
49    K31,
50}
51
52#[derive(Debug, Clone)]
53pub struct KimiK3Formatter {
54    exclude_tools_when_tool_choice_none: bool,
55    version: KimiVersion,
56}
57
58impl KimiK3Formatter {
59    pub fn new(exclude_tools_when_tool_choice_none: bool) -> Self {
60        Self {
61            exclude_tools_when_tool_choice_none,
62            version: KimiVersion::K3,
63        }
64    }
65
66    /// K3.1 shares the K3 encoding and thinking-effort values.
67    pub fn new_k31(exclude_tools_when_tool_choice_none: bool) -> Self {
68        Self {
69            version: KimiVersion::K31,
70            ..Self::new(exclude_tools_when_tool_choice_none)
71        }
72    }
73
74    /// Render the conversation into segments, also returning how many trailing
75    /// segments form the assistant generation stub (`<|open|>think<|sep|>` or
76    /// `<|open|>response<|sep|>`). Moonshot's K3 API feeds that stub to the
77    /// model but excludes it from reported `usage.prompt_tokens`.
78    fn build_segments(&self, req: &dyn OAIChatLikeRequest) -> Result<ChatSegments> {
79        let messages = crate::messages_to_json(req).context("Failed to convert K3 messages")?;
80        let Value::Array(messages) = messages else {
81            anyhow::bail!("Kimi K3 messages must be an array");
82        };
83        let messages = normalize_tool_result_messages(messages)?;
84
85        let tool_choice = req.tool_choice().map(json_value).transpose()?;
86        let (tool_choice_kind, named_tool) = resolve_tool_choice(tool_choice.as_ref())?;
87        let mut tools = req.tools().map(json_value).transpose()?;
88        // A named tool_choice may target a message-level declaration that
89        // never appears in the top-level list.
90        if let Some(named_tool) = named_tool
91            && !tools
92                .as_ref()
93                .is_some_and(|tools| contains_tool(tools, named_tool))
94            && !messages
95                .iter()
96                .any(|message| message_declares_tool(message, named_tool))
97        {
98            return Err(PromptRenderError::invalid_request(format!(
99                "tool named {named_tool:?} in tool_choice is not present in tools"
100            ))
101            .into());
102        }
103        if self.exclude_tools_when_tool_choice_none && tool_choice_kind == Some("none") {
104            tools = None;
105        }
106        let tools = tools.map(deep_sort);
107
108        let args = req.chat_template_args();
109        // Moonshot's K3 API defines named tool choice as incompatible with
110        // thinking. Make the public function-object form work without requiring
111        // clients to know K3-specific chat-template arguments.
112        let thinking = named_tool.is_none() && thinking_bool_from_args(args).unwrap_or(true);
113        let thinking_effort = resolve_thinking_effort(args);
114        let model_name = match self.version {
115            KimiVersion::K3 => "Kimi K3",
116            KimiVersion::K31 => "Kimi K3.1",
117        };
118        if thinking && !VALID_THINKING_EFFORTS.contains(&thinking_effort.as_str()) {
119            return Err(PromptRenderError::invalid_request(format!(
120                "Unsupported {model_name} thinking_effort={thinking_effort:?}; supported values are {}",
121                VALID_THINKING_EFFORTS.join(", ")
122            ))
123            .into());
124        }
125
126        let response_format = req.response_format().map(json_value).transpose()?;
127        build_chat_segments(
128            &messages,
129            tools.as_ref(),
130            tool_choice_kind,
131            named_tool,
132            response_format.as_ref(),
133            req.should_add_generation_prompt(),
134            thinking,
135            thinking_effort.as_str(),
136        )
137    }
138}
139
140impl OAIPromptFormatter for KimiK3Formatter {
141    fn supports_add_generation_prompt(&self) -> bool {
142        true
143    }
144
145    fn render(&self, req: &dyn OAIChatLikeRequest) -> Result<String> {
146        Ok(self.build_segments(req)?.into_prompt().into_text())
147    }
148
149    fn render_prompt(&self, req: &dyn OAIChatLikeRequest) -> Result<RenderedPrompt> {
150        Ok(self.build_segments(req)?.into_prompt())
151    }
152}
153
154struct ChatSegments {
155    segments: Vec<RenderedSegment>,
156    /// Trailing segments that open the assistant channel for generation.
157    /// Zero when no generation prompt was added or a partial assistant
158    /// message is being continued.
159    pending_segments: usize,
160}
161
162impl ChatSegments {
163    fn into_prompt(self) -> RenderedPrompt {
164        RenderedPrompt::segmented_with_pending(self.segments, self.pending_segments)
165    }
166}
167
168fn json_value(value: minijinja::value::Value) -> Result<Value> {
169    crate::python::template_json(&value).context("Failed to convert template value to JSON")
170}
171
172fn resolve_tool_choice(tool_choice: Option<&Value>) -> Result<(Option<&str>, Option<&str>)> {
173    match tool_choice {
174        Some(Value::String(kind)) => Ok((Some(kind.as_str()), None)),
175        Some(Value::Object(choice)) => {
176            if choice.get("type").and_then(Value::as_str) != Some("function") {
177                return Err(PromptRenderError::invalid_request(
178                    "Kimi K3 named tool_choice must have type=\"function\"",
179                )
180                .into());
181            }
182            // Chat Completions uses function.name. Responses API uses a
183            // top-level name and is normalized to the same internal request in
184            // Dynamo, but accepting both shapes keeps this renderer reusable.
185            let name = choice
186                .get("function")
187                .and_then(Value::as_object)
188                .and_then(|function| function.get("name"))
189                .or_else(|| choice.get("name"))
190                .and_then(Value::as_str)
191                .filter(|name| !name.is_empty())
192                .ok_or_else(|| {
193                    PromptRenderError::invalid_request(
194                        "Kimi K3 named tool_choice requires a non-empty function name",
195                    )
196                })?;
197            Ok((Some("specified"), Some(name)))
198        }
199        Some(Value::Null) | None => Ok((None, None)),
200        Some(other) => Err(anyhow::anyhow!(
201            "Unsupported Kimi K3 tool_choice value: {other}"
202        )),
203    }
204}
205
206fn contains_tool(tools: &Value, name: &str) -> bool {
207    tools.as_array().is_some_and(|tools| {
208        tools.iter().any(|tool| {
209            tool.get("function")
210                .and_then(Value::as_object)
211                .and_then(|function| function.get("name"))
212                .or_else(|| tool.get("name"))
213                .and_then(Value::as_str)
214                == Some(name)
215        })
216    })
217}
218
219/// Longest tool name Moonshot's vendor verifier accepts.
220const MAX_TOOL_NAME_LEN: usize = 256;
221
222/// The dynamic tool declaration carried by a system or developer message.
223///
224/// `Ok(Some(..))` for a non-empty `tools` array; `Ok(None)` when `tools` is
225/// missing, `null`, or an empty array (an empty list declares nothing, so the
226/// message is an ordinary turn); `Err` for any other JSON type.
227fn dynamic_tools_of(message: &Value) -> Result<Option<&Vec<Value>>> {
228    match message.get("tools") {
229        None | Some(Value::Null) => Ok(None),
230        Some(Value::Array(tools)) if tools.is_empty() => Ok(None),
231        Some(Value::Array(tools)) => Ok(Some(tools)),
232        Some(_) => Err(PromptRenderError::invalid_request(
233            "Kimi K3 dynamic tool messages need `tools` to be an array",
234        )
235        .into()),
236    }
237}
238
239/// Accepts both OpenAI-wrapped and bare Kimi tool declarations; rejects mixed
240/// shapes so every entry has one unambiguous name.
241fn dynamic_tool_entry_name(tool: &Value) -> Result<&str> {
242    let object = tool.as_object().ok_or_else(|| {
243        PromptRenderError::invalid_request("Kimi K3 dynamic tool entries must be JSON objects")
244    })?;
245    let name = match (object.get("type"), object.get("function")) {
246        (Some(kind), function) => {
247            if kind.as_str() != Some("function") {
248                return Err(PromptRenderError::invalid_request(format!(
249                    "Kimi K3 dynamic tool entries must have type=\"function\", got {kind}"
250                ))
251                .into());
252            }
253            let function = function.and_then(Value::as_object).ok_or_else(|| {
254                PromptRenderError::invalid_request(
255                    "Kimi K3 dynamic tool entries with type=\"function\" need a `function` object",
256                )
257            })?;
258            function.get("name")
259        }
260        (None, Some(_)) => {
261            return Err(PromptRenderError::invalid_request(
262                "Kimi K3 dynamic tool entries with a `function` object need type=\"function\"",
263            )
264            .into());
265        }
266        (None, None) => object.get("name"),
267    };
268    let name = name.and_then(Value::as_str).ok_or_else(|| {
269        PromptRenderError::invalid_request("Kimi K3 dynamic tool entries need a string `name`")
270    })?;
271    validate_tool_name(name)?;
272    Ok(name)
273}
274
275/// Tool names must match `[A-Za-z_][A-Za-z0-9_-]*` and be at most
276/// [`MAX_TOOL_NAME_LEN`] characters (Moonshot vendor verifier rules).
277fn validate_tool_name(name: &str) -> Result<()> {
278    let mut chars = name.chars();
279    let valid_start = chars
280        .next()
281        .is_some_and(|c| c.is_ascii_alphabetic() || c == '_');
282    let valid_rest = chars.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-');
283    if !valid_start || !valid_rest {
284        return Err(PromptRenderError::invalid_request(format!(
285            "Kimi K3 tool name {name:?} must match [A-Za-z_][A-Za-z0-9_-]*"
286        ))
287        .into());
288    }
289    if name.len() > MAX_TOOL_NAME_LEN {
290        return Err(PromptRenderError::invalid_request(format!(
291            "Kimi K3 tool name is {} characters; the maximum is {MAX_TOOL_NAME_LEN}",
292            name.len()
293        ))
294        .into());
295    }
296    Ok(())
297}
298
299/// Validate top-level and message-level tools as one namespace: entries must
300/// be well-formed and names unique. Raw requests retain the renderer's native
301/// developer-tool support alongside Kimi's system-tool declarations.
302fn validate_tool_declarations(top_level: Option<&Value>, messages: &[Value]) -> Result<()> {
303    let mut seen = std::collections::HashSet::new();
304    // The OpenAI schema does not enforce Kimi's tool-name rules.
305    for tool in top_level.and_then(Value::as_array).into_iter().flatten() {
306        let name = dynamic_tool_entry_name(tool)?;
307        if !seen.insert(name) {
308            return Err(PromptRenderError::invalid_request(format!(
309                "tool {name:?} is declared more than once in `tools`"
310            ))
311            .into());
312        }
313    }
314    for message in messages {
315        let role = message.get("role").and_then(Value::as_str);
316        if !matches!(role, Some("system" | "developer")) {
317            if message.get("tools").is_some_and(|tools| !tools.is_null()) {
318                return Err(PromptRenderError::invalid_request(format!(
319                    "`tools` is only accepted on system or developer messages, not on role {}",
320                    role.unwrap_or("<missing>")
321                ))
322                .into());
323            }
324            continue;
325        }
326        for tool in dynamic_tools_of(message)?.into_iter().flatten() {
327            let name = dynamic_tool_entry_name(tool)?;
328            if !seen.insert(name) {
329                return Err(PromptRenderError::invalid_request(format!(
330                    "tool {name:?} is declared more than once across `tools` and dynamic message tools"
331                ))
332                .into());
333            }
334        }
335    }
336    Ok(())
337}
338
339/// Whether `content` carries text: missing, `null`, `""`, and `[]` all count
340/// as empty, matching Moonshot's "omit `content`" contract for dynamic tools.
341fn content_is_non_empty(content: Option<&Value>) -> bool {
342    match content {
343        None | Some(Value::Null) => false,
344        Some(Value::String(text)) => !text.is_empty(),
345        Some(Value::Array(parts)) => !parts.is_empty(),
346        Some(_) => true,
347    }
348}
349
350fn message_declares_tool(message: &Value, name: &str) -> bool {
351    matches!(
352        message.get("role").and_then(Value::as_str),
353        Some("system" | "developer")
354    ) && message
355        .get("tools")
356        .is_some_and(|tools| contains_tool(tools, name))
357}
358
359fn resolve_thinking_effort(args: Option<&HashMap<String, Value>>) -> String {
360    args.and_then(|args| {
361        args.get("thinking_effort")
362            .or_else(|| args.get("reasoning_effort"))
363            .and_then(Value::as_str)
364    })
365    .unwrap_or("max")
366    .to_string()
367}
368
369fn push_segment(segments: &mut Vec<RenderedSegment>, text: impl Into<String>, allow_special: bool) {
370    let text = text.into();
371    if !text.is_empty() {
372        segments.push(RenderedSegment {
373            text,
374            allow_special,
375        });
376    }
377}
378
379fn control(segments: &mut Vec<RenderedSegment>, text: impl Into<String>) {
380    push_segment(segments, text, true);
381}
382
383fn text(segments: &mut Vec<RenderedSegment>, text: impl Into<String>) {
384    push_segment(segments, text, false);
385}
386
387fn escape_attr_value(value: impl std::fmt::Display) -> String {
388    value
389        .to_string()
390        .replace('&', "&amp;")
391        .replace('"', "&quot;")
392}
393
394fn open_tag(
395    segments: &mut Vec<RenderedSegment>,
396    tag: &str,
397    attrs: impl IntoIterator<Item = (String, String)>,
398) {
399    control(segments, OPEN_TOKEN);
400    text(segments, tag);
401    for (key, value) in attrs {
402        text(segments, format!(" {key}"));
403        text(segments, "=\"");
404        text(segments, escape_attr_value(value));
405        text(segments, "\"");
406    }
407    control(segments, SEP_TOKEN);
408}
409
410fn close_tag(segments: &mut Vec<RenderedSegment>, tag: &str) {
411    control(segments, CLOSE_TOKEN);
412    text(segments, tag);
413    control(segments, SEP_TOKEN);
414}
415
416fn end_of_msg(segments: &mut Vec<RenderedSegment>) {
417    control(segments, END_OF_MSG_TOKEN);
418}
419
420fn internal_system_message(segments: &mut Vec<RenderedSegment>, message_type: &str, body: &str) {
421    open_tag(
422        segments,
423        "message",
424        [
425            ("role".to_string(), "system".to_string()),
426            ("type".to_string(), message_type.to_string()),
427        ],
428    );
429    text(segments, body.trim());
430    close_tag(segments, "message");
431    end_of_msg(segments);
432}
433
434fn deep_sort(value: Value) -> Value {
435    match value {
436        Value::Object(map) => {
437            let mut entries: Vec<_> = map.into_iter().collect();
438            entries.sort_by(|(left, _), (right, _)| left.cmp(right));
439            Value::Object(
440                entries
441                    .into_iter()
442                    .map(|(key, value)| (key, deep_sort(value)))
443                    .collect(),
444            )
445        }
446        Value::Array(items) => Value::Array(items.into_iter().map(deep_sort).collect()),
447        other => other,
448    }
449}
450
451fn compact_json(value: &Value) -> Result<String> {
452    serde_json::to_string(value).context("Failed to serialize K3 JSON")
453}
454
455fn response_schema(response_format: &Value) -> Option<Value> {
456    let json_schema = response_format.get("json_schema")?;
457    if let Some(schema) = json_schema.get("schema") {
458        return Some(schema.clone());
459    }
460    if let Some(schema) = json_schema.get("json_schema") {
461        return Some(schema.clone());
462    }
463    Some(json_schema.clone())
464}
465
466fn value_as_body_text(value: &Value) -> Result<String> {
467    match value {
468        Value::String(value) => Ok(value.clone()),
469        Value::Array(values) if values.iter().all(Value::is_string) => Ok(values
470            .iter()
471            .filter_map(Value::as_str)
472            .filter(|value| !value.is_empty())
473            .collect::<Vec<_>>()
474            .join("\n")),
475        other => compact_json(other),
476    }
477}
478
479fn render_content_segments(
480    segments: &mut Vec<RenderedSegment>,
481    content: Option<&Value>,
482) -> Result<()> {
483    let Some(content) = content else {
484        return Ok(());
485    };
486    match content {
487        Value::Null => {}
488        Value::String(value) => text(segments, value),
489        Value::Array(parts) => {
490            for part in parts {
491                match part.get("type").and_then(Value::as_str) {
492                    Some("image" | "image_url") => control(segments, MEDIA_PAD),
493                    _ => {
494                        if let Some(part_text) = part.get("text") {
495                            text(segments, value_as_body_text(part_text)?);
496                        }
497                    }
498                }
499            }
500        }
501        other => text(segments, value_as_body_text(other)?),
502    }
503    Ok(())
504}
505
506fn render_role_message(
507    segments: &mut Vec<RenderedSegment>,
508    message: &Value,
509    role: &str,
510) -> Result<()> {
511    let mut attrs = vec![("role".to_string(), role.to_string())];
512    if let Some(name) = message
513        .get("name")
514        .and_then(Value::as_str)
515        .filter(|name| !name.is_empty())
516    {
517        attrs.push(("name".to_string(), name.to_string()));
518    }
519    open_tag(segments, "message", attrs);
520    render_content_segments(segments, message.get("content"))?;
521    close_tag(segments, "message");
522    end_of_msg(segments);
523    Ok(())
524}
525
526fn render_tool_declare(
527    segments: &mut Vec<RenderedSegment>,
528    tools: &Value,
529    dynamic: bool,
530) -> Result<()> {
531    let tools = compact_json(tools)?;
532    let body = if dynamic {
533        format!(
534            "## New Tools Available\n\
535             The system dynamically extends the toolset via lazy-loading.\n\
536             You have access to all existing and extended tools.\n\
537             Here are the specs for the extended tools.\n\n\
538             ```json\n{tools}\n```"
539        )
540    } else {
541        format!(
542            "# Tools\n\
543             Here are the available tools, described in JSONSchema.\n\n\
544             ```json\n{tools}\n```"
545        )
546    };
547    open_tag(
548        segments,
549        "message",
550        [
551            ("role".to_string(), "system".to_string()),
552            ("type".to_string(), "tool-declare".to_string()),
553        ],
554    );
555    text(segments, body);
556    close_tag(segments, "message");
557    end_of_msg(segments);
558    Ok(())
559}
560
561fn xtml_type(value: &Value) -> &'static str {
562    match value {
563        Value::Bool(_) => "boolean",
564        Value::Null => "null",
565        Value::Number(_) => "number",
566        Value::String(_) => "string",
567        Value::Object(_) => "object",
568        Value::Array(_) => "array",
569    }
570}
571
572fn xtml_value(value: &Value) -> Result<String> {
573    match value {
574        Value::String(value) => Ok(value.clone()),
575        // Python's `json.dumps(..., ensure_ascii=False)` uses `", "` and
576        // `": "` separators by default. Preserve that byte shape in prompt
577        // history; the compact form is used only for schemas/tool declarations.
578        other => python_default_json(other),
579    }
580}
581
582fn python_default_json(value: &Value) -> Result<String> {
583    let compact = compact_json(value)?;
584    let mut output = String::with_capacity(compact.len());
585    let mut in_string = false;
586    let mut escaped = false;
587    for ch in compact.chars() {
588        output.push(ch);
589        if in_string {
590            if escaped {
591                escaped = false;
592            } else if ch == '\\' {
593                escaped = true;
594            } else if ch == '"' {
595                in_string = false;
596            }
597        } else if ch == '"' {
598            in_string = true;
599        } else if matches!(ch, ',' | ':') {
600            output.push(' ');
601        }
602    }
603    Ok(output)
604}
605
606enum NormalizedArguments {
607    Object(Map<String, Value>),
608    JsonBlock(String),
609}
610
611fn normalize_arguments(arguments: Option<&Value>) -> Result<NormalizedArguments> {
612    let Some(arguments) = arguments else {
613        return Ok(NormalizedArguments::Object(Map::new()));
614    };
615    match arguments {
616        Value::Null => Ok(NormalizedArguments::Object(Map::new())),
617        Value::Object(arguments) => Ok(NormalizedArguments::Object(arguments.clone())),
618        Value::String(arguments) if arguments.trim().is_empty() => {
619            Ok(NormalizedArguments::Object(Map::new()))
620        }
621        Value::String(arguments) => match serde_json::from_str::<Value>(arguments) {
622            Ok(Value::Object(arguments)) => Ok(NormalizedArguments::Object(arguments)),
623            Ok(_) => bail!("Kimi K3 tool call arguments must be a JSON object"),
624            Err(_) => Ok(NormalizedArguments::JsonBlock(arguments.clone())),
625        },
626        _ => bail!("Kimi K3 tool call arguments must be an object or JSON object string"),
627    }
628}
629
630/// Renders an assistant message's think channel.
631///
632/// The think channel is structural in the latest K3 model encoding. Every
633/// historical assistant message carries it in thinking mode, even if its body
634/// is empty. Non-thinking mode drops both the channel and preserved reasoning
635/// content.
636fn render_think_channel(
637    segments: &mut Vec<RenderedSegment>,
638    message: &Value,
639    thinking: bool,
640) -> Result<()> {
641    if !thinking {
642        return Ok(());
643    }
644    // Match encoding_k3.py: `reasoning_content` wins when truthy, otherwise
645    // fall back to the Responses-style `reasoning` alias.
646    let reasoning = message
647        .get("reasoning_content")
648        .filter(|value| match value {
649            Value::Null => false,
650            Value::Bool(value) => *value,
651            Value::Number(value) => value.as_f64().is_some_and(|value| value != 0.0),
652            Value::String(value) => !value.is_empty(),
653            Value::Array(value) => !value.is_empty(),
654            Value::Object(value) => !value.is_empty(),
655        })
656        .or_else(|| message.get("reasoning"))
657        .map(value_as_body_text)
658        .transpose()?;
659
660    open_tag(segments, "think", []);
661    // Match encoding_k3.py: only an empty string means "no reasoning", so
662    // whitespace-only reasoning is still rendered.
663    if let Some(reasoning) = reasoning.filter(|reasoning| !reasoning.is_empty()) {
664        text(segments, reasoning);
665    }
666    close_tag(segments, "think");
667    Ok(())
668}
669
670fn assistant_message_attrs(message: &Value) -> Vec<(String, String)> {
671    let mut attrs = vec![("role".to_string(), "assistant".to_string())];
672    if let Some(name) = message
673        .get("name")
674        .and_then(Value::as_str)
675        .filter(|name| !name.is_empty())
676    {
677        attrs.push(("name".to_string(), name.to_string()));
678    }
679    attrs
680}
681
682fn is_partial(message: &Value) -> bool {
683    message.get("partial").and_then(Value::as_bool) == Some(true)
684}
685
686/// Leaves the assistant response and message open for prefix continuation,
687/// replacing the ordinary generation prompt. In thinking mode, the think
688/// channel is rendered and closed before the response opens.
689fn render_partial_assistant_segments(
690    segments: &mut Vec<RenderedSegment>,
691    message: &Value,
692    thinking: bool,
693) -> Result<()> {
694    if message
695        .get("tool_calls")
696        .is_some_and(|calls| !calls.is_null() && !calls.as_array().is_some_and(Vec::is_empty))
697    {
698        return Err(PromptRenderError::invalid_request(
699            "Kimi K3 partial assistant messages cannot carry tool_calls",
700        )
701        .into());
702    }
703    open_tag(segments, "message", assistant_message_attrs(message));
704    render_think_channel(segments, message, thinking)?;
705    open_tag(segments, "response", []);
706    render_content_segments(segments, message.get("content"))?;
707    Ok(())
708}
709
710fn render_assistant_segments(
711    segments: &mut Vec<RenderedSegment>,
712    message: &Value,
713    thinking: bool,
714) -> Result<()> {
715    render_think_channel(segments, message, thinking)?;
716
717    open_tag(segments, "response", []);
718    render_content_segments(segments, message.get("content"))?;
719    close_tag(segments, "response");
720
721    let Some(tool_calls) = message.get("tool_calls").and_then(Value::as_array) else {
722        return Ok(());
723    };
724    if tool_calls.is_empty() {
725        return Ok(());
726    }
727
728    open_tag(segments, "tools", []);
729    for (position, tool_call) in tool_calls.iter().enumerate() {
730        let function = tool_call.get("function").unwrap_or(tool_call);
731        let name = function
732            .get("name")
733            .and_then(Value::as_str)
734            .context("Kimi K3 tool call is missing function.name")?;
735        open_tag(
736            segments,
737            "call",
738            [
739                ("tool".to_string(), name.to_string()),
740                ("index".to_string(), (position + 1).to_string()),
741            ],
742        );
743
744        match normalize_arguments(function.get("arguments"))? {
745            NormalizedArguments::JsonBlock(raw) => {
746                open_tag(
747                    segments,
748                    "json",
749                    [("type".to_string(), "object".to_string())],
750                );
751                text(segments, raw);
752                close_tag(segments, "json");
753            }
754            NormalizedArguments::Object(arguments) => {
755                for (key, value) in arguments {
756                    open_tag(
757                        segments,
758                        "argument",
759                        [
760                            ("key".to_string(), key),
761                            ("type".to_string(), xtml_type(&value).to_string()),
762                        ],
763                    );
764                    text(segments, xtml_value(&value)?);
765                    close_tag(segments, "argument");
766                }
767            }
768        }
769        close_tag(segments, "call");
770    }
771    close_tag(segments, "tools");
772    Ok(())
773}
774
775fn tool_call_index(tool_calls: Option<&Value>) -> HashMap<String, (usize, Option<String>)> {
776    let mut index = HashMap::new();
777    let Some(tool_calls) = tool_calls.and_then(Value::as_array) else {
778        return index;
779    };
780    for (position, tool_call) in tool_calls.iter().enumerate() {
781        let Some(id) = tool_call.get("id").and_then(Value::as_str) else {
782            continue;
783        };
784        let function = tool_call.get("function").unwrap_or(tool_call);
785        let name = function
786            .get("name")
787            .and_then(Value::as_str)
788            .map(str::to_string);
789        index.entry(id.to_string()).or_insert((position + 1, name));
790    }
791    index
792}
793
794fn normalize_tool_result_messages(messages: Vec<Value>) -> Result<Vec<Value>> {
795    let mut output = Vec::with_capacity(messages.len());
796    let mut current_index = HashMap::new();
797    let mut messages = messages.into_iter().peekable();
798
799    while let Some(message) = messages.peek() {
800        let role = message.get("role").and_then(Value::as_str);
801        if role == Some("assistant") {
802            current_index = tool_call_index(message.get("tool_calls"));
803            output.push(messages.next().expect("peeked message"));
804            continue;
805        }
806        if role != Some("tool") {
807            output.push(messages.next().expect("peeked message"));
808            continue;
809        }
810
811        let mut run: Vec<(Option<usize>, usize, Value, Option<String>)> = Vec::new();
812        let mut unresolved = false;
813        let mut offset = 0;
814        while messages
815            .peek()
816            .is_some_and(|message| message.get("role").and_then(Value::as_str) == Some("tool"))
817        {
818            let tool_message = messages.next().expect("peeked tool message");
819            let call_id = tool_message
820                .get("tool_call_id")
821                .or_else(|| tool_message.get("id"))
822                .and_then(Value::as_str);
823            let matched = call_id.and_then(|id| current_index.get(id));
824            if let Some((tool_position, name)) = matched {
825                run.push((Some(*tool_position), offset, tool_message, name.clone()));
826            } else {
827                unresolved = true;
828                run.push((None, offset, tool_message, None));
829            }
830            offset += 1;
831        }
832
833        if unresolved {
834            output.extend(run.into_iter().map(|(_, _, message, _)| message));
835            continue;
836        }
837        run.sort_by_key(|(tool_position, offset, _, _)| (*tool_position, *offset));
838        for (_, _, mut message, name) in run {
839            if let (Some(name), Some(message)) = (name, message.as_object_mut()) {
840                message.insert("tool".to_string(), Value::String(name.clone()));
841                if message.contains_key("name") {
842                    message.insert("name".to_string(), Value::String(name));
843                }
844            }
845            output.push(message);
846        }
847    }
848    Ok(output)
849}
850
851#[allow(clippy::too_many_arguments)]
852fn build_chat_segments(
853    messages: &[Value],
854    tools: Option<&Value>,
855    tool_choice: Option<&str>,
856    named_tool: Option<&str>,
857    response_format: Option<&Value>,
858    add_generation_prompt: bool,
859    thinking: bool,
860    thinking_effort: &str,
861) -> Result<ChatSegments> {
862    let mut segments = Vec::new();
863    let mut pending_segments = 0usize;
864    let mut previous_tool_calls: Option<&Value> = None;
865    let mut tool_index = 0usize;
866
867    for message in messages {
868        let Some(partial) = message.get("partial").filter(|value| !value.is_null()) else {
869            continue;
870        };
871        if message.get("role").and_then(Value::as_str) != Some("assistant") {
872            return Err(PromptRenderError::invalid_request(
873                "Kimi K3 `partial` is only supported on an assistant message",
874            )
875            .into());
876        }
877        if !partial.is_boolean() {
878            return Err(
879                PromptRenderError::invalid_request("Kimi K3 `partial` must be a boolean").into(),
880            );
881        }
882    }
883
884    // Kimi Partial Mode: only the final message may be partial, and it must be
885    // an assistant turn. Split it off so the history loop renders everything
886    // before it normally and the partial turn takes the generation prompt's
887    // place at the very end (after any internal system messages).
888    let (history, partial_tail) = match messages.split_last() {
889        Some((last, history)) if is_partial(last) => (history, Some(last)),
890        _ => (messages, None),
891    };
892
893    // Validate the complete raw message list, including a split-off Partial
894    // Mode tail. Otherwise `tools` on the final partial assistant message
895    // bypasses the supported-role check below.
896    validate_tool_declarations(tools, messages)?;
897    if history.iter().any(is_partial) {
898        return Err(PromptRenderError::invalid_request(
899            "Kimi K3 `partial` is only supported on the final message",
900        )
901        .into());
902    }
903
904    if let Some(tools) = tools.filter(|tools| !tools.as_array().is_some_and(Vec::is_empty)) {
905        render_tool_declare(&mut segments, tools, false)?;
906    }
907
908    if thinking {
909        internal_system_message(
910            &mut segments,
911            "thinking-effort",
912            &format!(
913                "`thinking_effort` guides on how much to think in your thinking channel \
914                 (not including the response channel), supported values include `low`, \
915                 `medium`, `high`, and `max`.\nNow the system is invoked with \
916                 `thinking_effort={thinking_effort}`."
917            ),
918        );
919    }
920
921    for message in history {
922        let role = message.get("role").and_then(Value::as_str).ok_or_else(|| {
923            PromptRenderError::invalid_request("Kimi K3 messages must contain a string role")
924        })?;
925        // An empty `tools` list is not a dynamic-tool declaration.
926        let dynamic_tools = dynamic_tools_of(message)?;
927        match role {
928            "system" | "developer" if dynamic_tools.is_some() => {
929                let dynamic_tools = dynamic_tools.expect("guarded by the match arm");
930                // Moonshot's contract: a dynamic-tool system message omits
931                // `content` (an empty string counts as omitted; the official
932                // verifier sends `"content": ""`). Rejecting non-empty text
933                // keeps it from being silently lost.
934                if role == "system" && content_is_non_empty(message.get("content")) {
935                    return Err(PromptRenderError::invalid_request(
936                        "Kimi K3 system messages carry either `content` or `tools`, not both",
937                    )
938                    .into());
939                }
940                let dynamic_tools = deep_sort(Value::Array(dynamic_tools.clone()));
941                render_tool_declare(&mut segments, &dynamic_tools, true)?;
942                if role == "developer"
943                    && message
944                        .get("content")
945                        .is_some_and(|content| !content.is_null())
946                {
947                    render_role_message(&mut segments, message, "system")?;
948                }
949            }
950            "system" | "developer"
951                if message
952                    .get("content")
953                    .is_none_or(|content| content.is_null()) =>
954            {
955                return Err(PromptRenderError::invalid_request(format!(
956                    "Kimi K3 {role} messages need `content` or `tools`"
957                ))
958                .into());
959            }
960            "user" | "system" | "developer" => {
961                let rendered_role = if role == "developer" { "system" } else { role };
962                render_role_message(&mut segments, message, rendered_role)?;
963            }
964            "assistant" => {
965                previous_tool_calls = message.get("tool_calls");
966                tool_index = 0;
967                open_tag(&mut segments, "message", assistant_message_attrs(message));
968                render_assistant_segments(&mut segments, message, thinking)?;
969                close_tag(&mut segments, "message");
970                end_of_msg(&mut segments);
971            }
972            "tool" => {
973                tool_index += 1;
974                let fallback_name = previous_tool_calls
975                    .and_then(Value::as_array)
976                    .and_then(|calls| calls.get(tool_index - 1))
977                    .map(|call| call.get("function").unwrap_or(call))
978                    .and_then(|function| function.get("name"))
979                    .and_then(Value::as_str);
980                let tool_name = message
981                    .get("tool")
982                    .or_else(|| message.get("name"))
983                    .and_then(Value::as_str)
984                    .or(fallback_name)
985                    .context(
986                        "Kimi K3 tool messages need a tool/name or a preceding assistant tool call",
987                    )?;
988                open_tag(
989                    &mut segments,
990                    "message",
991                    [
992                        ("role".to_string(), "tool".to_string()),
993                        ("tool".to_string(), tool_name.to_string()),
994                        ("index".to_string(), tool_index.to_string()),
995                    ],
996                );
997                render_content_segments(&mut segments, message.get("content"))?;
998                close_tag(&mut segments, "message");
999                end_of_msg(&mut segments);
1000            }
1001            unsupported => {
1002                return Err(PromptRenderError::invalid_request(format!(
1003                    "Kimi K3 does not support message role {unsupported:?}"
1004                ))
1005                .into());
1006            }
1007        }
1008    }
1009
1010    match tool_choice {
1011        Some("required") => internal_system_message(
1012            &mut segments,
1013            "tool-choice",
1014            "The system is invoked with `tool_choice=required`.\n\
1015             You MUST call tools in the next message.",
1016        ),
1017        Some("none") => internal_system_message(
1018            &mut segments,
1019            "tool-choice",
1020            "The system is invoked with `tool_choice=none`.\n\
1021             You MUST NOT call any tools in the next message.",
1022        ),
1023        Some("specified") => internal_system_message(
1024            &mut segments,
1025            "tool-choice",
1026            &format!(
1027                "The system is invoked with `tool_choice=specified`.\n\
1028                 You MUST call the tool `{}` in the next message.",
1029                named_tool.expect("specified tool_choice has a function name")
1030            ),
1031        ),
1032        _ => {}
1033    }
1034
1035    if let Some(response_format) = response_format {
1036        match response_format.get("type").and_then(Value::as_str) {
1037            Some("json_object") => internal_system_message(
1038                &mut segments,
1039                "response-format",
1040                "The system is invoked with `response_format=json_object`.\n\
1041                 Your response must be raw JSON data without markdown code blocks \
1042                 (```json) or any additional formatting.",
1043            ),
1044            Some("json_schema") => {
1045                let schema = response_schema(response_format)
1046                    .map(deep_sort)
1047                    .unwrap_or(Value::Null);
1048                internal_system_message(
1049                    &mut segments,
1050                    "response-format",
1051                    &format!(
1052                        "The system is invoked with `response_format=json_schema`.\n\
1053                         Your response must be raw JSON data without markdown code blocks \
1054                         (```json) or any additional formatting.\n\
1055                         The JSON data must match the following schema:\n\
1056                         ```json\n{}\n```",
1057                        compact_json(&schema)?
1058                    ),
1059                );
1060            }
1061            _ => {}
1062        }
1063    }
1064
1065    // A partial assistant turn *is* the generation prompt: it is left open so
1066    // the model continues from its prefix, so the generic prompt is skipped
1067    // regardless of `add_generation_prompt`.
1068    if let Some(partial) = partial_tail {
1069        render_partial_assistant_segments(&mut segments, partial, thinking)?;
1070    } else if add_generation_prompt {
1071        open_tag(
1072            &mut segments,
1073            "message",
1074            [("role".to_string(), "assistant".to_string())],
1075        );
1076        // Only the channel-opening tag is the "pending" stub under Moonshot's
1077        // accounting; the assistant message header above still counts as
1078        // prompt. Measure it rather than assuming its segment count.
1079        let before_channel_tag = segments.len();
1080        open_tag(
1081            &mut segments,
1082            if thinking { "think" } else { "response" },
1083            [],
1084        );
1085        pending_segments = segments.len() - before_channel_tag;
1086    }
1087
1088    Ok(ChatSegments {
1089        segments,
1090        pending_segments,
1091    })
1092}
1093
1094#[cfg(test)]
1095mod tests {
1096    use super::*;
1097    use minijinja::value::Value as MiniValue;
1098    use serde_json::json;
1099
1100    struct Request {
1101        messages: Value,
1102        tools: Option<Value>,
1103        tool_choice: Option<Value>,
1104        response_format: Option<Value>,
1105        args: HashMap<String, Value>,
1106        add_generation_prompt: bool,
1107    }
1108
1109    impl Request {
1110        fn new(messages: Value) -> Self {
1111            Self {
1112                messages,
1113                tools: None,
1114                tool_choice: None,
1115                response_format: None,
1116                args: HashMap::new(),
1117                add_generation_prompt: true,
1118            }
1119        }
1120    }
1121
1122    impl OAIChatLikeRequest for Request {
1123        fn model(&self) -> String {
1124            "kimi-k3".to_string()
1125        }
1126
1127        fn messages(&self) -> MiniValue {
1128            MiniValue::from_serialize(&self.messages)
1129        }
1130
1131        fn tools(&self) -> Option<MiniValue> {
1132            self.tools.as_ref().map(MiniValue::from_serialize)
1133        }
1134
1135        fn tool_choice(&self) -> Option<MiniValue> {
1136            self.tool_choice.as_ref().map(MiniValue::from_serialize)
1137        }
1138
1139        fn response_format(&self) -> Option<MiniValue> {
1140            self.response_format.as_ref().map(MiniValue::from_serialize)
1141        }
1142
1143        fn should_add_generation_prompt(&self) -> bool {
1144            self.add_generation_prompt
1145        }
1146
1147        fn chat_template_args(&self) -> Option<&HashMap<String, Value>> {
1148            Some(&self.args)
1149        }
1150    }
1151
1152    /// Default formatter: no worker declaration, so the checkpoint token.
1153    fn fmt() -> KimiK3Formatter {
1154        KimiK3Formatter::new(true)
1155    }
1156
1157    /// One user message carrying a single image part.
1158    fn image_request() -> Request {
1159        let mut request = Request::new(json!([{
1160            "role": "user",
1161            "content": [{"type": "image_url", "image_url": {"url": "http://example.com/a.png"}}]
1162        }]));
1163        request
1164            .args
1165            .insert("thinking".to_string(), Value::Bool(false));
1166        request
1167    }
1168
1169    fn image_segments(formatter: &KimiK3Formatter, request: &Request) -> Vec<RenderedSegment> {
1170        formatter
1171            .render_prompt(request)
1172            .unwrap()
1173            .segments()
1174            .expect("K3 always renders segmented prompts")
1175            .to_vec()
1176    }
1177
1178    #[test]
1179    fn renders_one_media_pad_per_image() {
1180        let segments = image_segments(&fmt(), &image_request());
1181
1182        let matches: Vec<_> = segments
1183            .iter()
1184            .filter(|segment| segment.text == MEDIA_PAD)
1185            .collect();
1186        assert_eq!(matches.len(), 1, "exactly one pad per image");
1187        // The pad MUST stay special: it is a registered token, and only the
1188        // special-aware encode path yields its single id.
1189        assert!(matches[0].allow_special);
1190        // The checkpoint's non-vocabulary spelling must never be emitted --
1191        // the vLLM worker converts from the pad instead.
1192        assert!(
1193            !segments
1194                .iter()
1195                .any(|segment| segment.text.contains("kimi_image_placeholder")),
1196        );
1197    }
1198
1199    #[test]
1200    fn image_token_cardinality_is_one_per_image() {
1201        let mut request = Request::new(json!([{
1202            "role": "user",
1203            "content": [
1204                {"type": "image_url", "image_url": {"url": "http://example.com/a.png"}},
1205                {"type": "text", "text": "and"},
1206                {"type": "image_url", "image_url": {"url": "http://example.com/b.png"}},
1207                {"type": "text", "text": "compare them"}
1208            ]
1209        }]));
1210        request
1211            .args
1212            .insert("thinking".to_string(), Value::Bool(false));
1213
1214        let segments = image_segments(&fmt(), &request);
1215
1216        assert_eq!(
1217            segments
1218                .iter()
1219                .filter(|segment| segment.text == MEDIA_PAD)
1220                .count(),
1221            2
1222        );
1223        // Interleaved prose must stay ordinary text.
1224        for body in ["and", "compare them"] {
1225            assert!(
1226                segments
1227                    .iter()
1228                    .any(|segment| segment.text == body && !segment.allow_special)
1229            );
1230        }
1231    }
1232
1233    #[test]
1234    fn user_text_spelling_the_pad_stays_ordinary() {
1235        let body = "please describe <|media_pad|>";
1236        let mut request = Request::new(json!([{"role": "user", "content": body}]));
1237        request
1238            .args
1239            .insert("thinking".to_string(), Value::Bool(false));
1240
1241        let segments = image_segments(&fmt(), &request);
1242
1243        assert!(
1244            segments
1245                .iter()
1246                .any(|segment| segment.text == body && !segment.allow_special),
1247            "user content must never be promoted into prompt structure"
1248        );
1249    }
1250
1251    #[test]
1252    fn renders_off_mode_like_model_encoding() {
1253        let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1254        request
1255            .args
1256            .insert("thinking".to_string(), Value::Bool(false));
1257        let rendered = fmt().render(&request).unwrap();
1258        assert_eq!(
1259            rendered,
1260            concat!(
1261                "<|open|>message role=\"user\"<|sep|>Hello",
1262                "<|close|>message<|sep|><|end_of_msg|>",
1263                "<|open|>message role=\"assistant\"<|sep|>",
1264                "<|open|>response<|sep|>"
1265            )
1266        );
1267    }
1268
1269    #[test]
1270    fn renders_developer_messages_as_system() {
1271        let mut request = Request::new(json!([
1272            {"role": "developer", "content": "Follow this policy", "name": "policy"},
1273            {"role": "user", "content": "Hello"}
1274        ]));
1275        request
1276            .args
1277            .insert("thinking".to_string(), Value::Bool(false));
1278
1279        let rendered = fmt().render(&request).unwrap();
1280
1281        assert!(
1282            rendered.contains(
1283                "<|open|>message role=\"system\" name=\"policy\"<|sep|>Follow this policy"
1284            )
1285        );
1286        assert!(!rendered.contains("role=\"developer\""));
1287        assert!(
1288            rendered.find("Follow this policy").unwrap() < rendered.find("Hello").unwrap(),
1289            "developer instructions must retain their position"
1290        );
1291    }
1292
1293    #[test]
1294    fn renders_developer_tools_and_content_in_place_with_named_tool_choice() {
1295        let mut request = Request::new(json!([
1296            {"role": "user", "content": "Start"},
1297            {
1298                "role": "developer",
1299                "name": "policy",
1300                "content": "Use the lookup tool",
1301                "tools": [{"type": "function", "function": {"name": "lookup"}}]
1302            },
1303            {"role": "user", "content": "Look this up"}
1304        ]));
1305        request.tool_choice = Some(json!({
1306            "type": "function",
1307            "function": {"name": "lookup"}
1308        }));
1309        let rendered = fmt().render(&request).unwrap();
1310        let developer_turn = concat!(
1311            "<|open|>message role=\"system\" name=\"policy\"<|sep|>Use the lookup tool",
1312            "<|close|>message<|sep|><|end_of_msg|>"
1313        );
1314        let declaration = rendered.find("## New Tools Available").unwrap();
1315        let content = rendered.find(developer_turn).unwrap();
1316        assert!(rendered.find("Start").unwrap() < declaration);
1317        assert!(declaration < content);
1318        assert!(content < rendered.find("Look this up").unwrap());
1319        assert!(rendered.contains("\"name\":\"lookup\""));
1320        assert!(rendered.contains("MUST call the tool `lookup`"));
1321
1322        request.messages[1]
1323            .as_object_mut()
1324            .unwrap()
1325            .remove("content");
1326        assert_eq!(
1327            fmt().render(&request).unwrap(),
1328            rendered.replace(developer_turn, "")
1329        );
1330    }
1331
1332    #[test]
1333    fn rejects_tools_on_unsupported_message_roles() {
1334        let tools = json!([{"type": "function", "function": {"name": "lookup"}}]);
1335        for (role, extra) in [
1336            ("user", json!({"content": "Look this up"})),
1337            ("assistant", json!({"content": "ok"})),
1338        ] {
1339            let mut message = extra;
1340            message["role"] = json!(role);
1341            message["tools"] = tools.clone();
1342            let request = Request::new(json!([message, {"role": "user", "content": "Go"}]));
1343
1344            let error = fmt().render(&request).unwrap_err();
1345            assert_eq!(
1346                invalid_request_message(&error),
1347                format!(
1348                    "`tools` is only accepted on system or developer messages, not on role {role}"
1349                ),
1350                "role={role}"
1351            );
1352        }
1353    }
1354
1355    #[test]
1356    fn rejects_unsupported_message_roles() {
1357        for role in ["function", "unknown"] {
1358            let request = Request::new(json!([{"role": role, "content": "ignored before"}]));
1359
1360            let error = fmt().render(&request).unwrap_err();
1361
1362            assert!(matches!(
1363                error.downcast_ref::<PromptRenderError>(),
1364                Some(PromptRenderError::InvalidRequest(message))
1365                    if message == &format!("Kimi K3 does not support message role {role:?}")
1366            ));
1367        }
1368    }
1369
1370    #[test]
1371    fn rejects_messages_without_a_string_role() {
1372        for messages in [json!([{"content": "missing"}]), json!([{"role": 7}])] {
1373            let request = Request::new(messages);
1374
1375            let error = fmt().render(&request).unwrap_err();
1376
1377            assert!(matches!(
1378                error.downcast_ref::<PromptRenderError>(),
1379                Some(PromptRenderError::InvalidRequest(message))
1380                    if message == "Kimi K3 messages must contain a string role"
1381            ));
1382        }
1383    }
1384
1385    #[test]
1386    fn rejects_unsupported_thinking_effort_as_invalid_request() {
1387        let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1388        request.args.insert(
1389            "thinking_effort".to_string(),
1390            Value::String("medium".to_string()),
1391        );
1392
1393        let error = fmt().render(&request).unwrap_err();
1394        assert!(matches!(
1395            error.downcast_ref::<PromptRenderError>(),
1396            Some(PromptRenderError::InvalidRequest(message))
1397                if message.contains("thinking_effort=\"medium\"")
1398        ));
1399    }
1400
1401    #[test]
1402    fn k31_rejects_medium_effort_like_current_checkpoint() {
1403        let crate::PromptFormatter::OAI(formatter) = crate::template::kimi_k3_formatter_for(
1404            &Some("kimi_k31".to_string()),
1405            "served-name",
1406            true,
1407        )
1408        .unwrap();
1409        // Reference: encoding_k3.py at checkpoint revision d9e99b07.
1410        for key in ["thinking_effort", "reasoning_effort"] {
1411            let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1412            request.args.insert(key.to_string(), json!("medium"));
1413            let error = formatter.render(&request).unwrap_err();
1414            let message = invalid_request_message(&error);
1415            assert!(
1416                message.contains("thinking_effort=\"medium\""),
1417                "{key}: {message}"
1418            );
1419            assert!(
1420                message.contains("supported values are low, high, max"),
1421                "{message}"
1422            );
1423            let prompt_error = formatter.render_prompt(&request).err().unwrap();
1424            assert_eq!(invalid_request_message(&prompt_error), message, "{key}");
1425        }
1426    }
1427
1428    #[test]
1429    fn factory_selects_model_specific_error_name() {
1430        for (model_type, name, model_name) in [
1431            (Some("kimi_k31"), "served-name", "Kimi K3.1"),
1432            (Some("kimi_k31"), "moonshot/kimi-k3", "Kimi K3.1"),
1433            (Some("kimi_k3"), "moonshot/kimi-k3.1", "Kimi K3"),
1434            (None, "moonshot/kimi-k3", "Kimi K3"),
1435            (None, "moonshot/kimi-k3.1", "Kimi K3.1"),
1436            (None, "kimi_k3.1-instruct", "Kimi K3.1"),
1437            (None, "kimik3.1", "Kimi K3.1"),
1438            (None, "kimi-k31", "Kimi K3.1"),
1439            (None, "kimi_k31", "Kimi K3.1"),
1440            (None, "kimik31", "Kimi K3.1"),
1441        ] {
1442            let crate::PromptFormatter::OAI(formatter) =
1443                crate::template::kimi_k3_formatter_for(&model_type.map(str::to_owned), name, true)
1444                    .unwrap();
1445            let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1446            request
1447                .args
1448                .insert("thinking_effort".to_string(), json!("medium"));
1449            let error = formatter.render(&request).unwrap_err();
1450            let message = invalid_request_message(&error);
1451            assert!(
1452                message.starts_with(&format!("Unsupported {model_name} thinking_effort=")),
1453                "model_type={model_type:?}, name={name}"
1454            );
1455        }
1456    }
1457
1458    #[test]
1459    fn k31_preserves_shared_efforts_and_rejects_invalid_values() {
1460        let crate::PromptFormatter::OAI(formatter) = crate::template::kimi_k3_formatter_for(
1461            &Some("kimi_k31".to_string()),
1462            "served-name",
1463            true,
1464        )
1465        .unwrap();
1466        for key in ["thinking_effort", "reasoning_effort"] {
1467            for effort in ["low", "high", "max"] {
1468                let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1469                request.args.insert(key.to_string(), json!(effort));
1470                assert_eq!(
1471                    formatter.render(&request).unwrap(),
1472                    fmt().render(&request).unwrap()
1473                );
1474            }
1475            let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
1476            request.args.insert(key.to_string(), json!("invalid"));
1477            let error = formatter.render(&request).unwrap_err();
1478            let message = invalid_request_message(&error);
1479            assert!(message.contains("Kimi K3.1"), "{message}");
1480            assert!(message.contains("invalid"), "{message}");
1481            assert!(
1482                message.contains("supported values are low, high, max"),
1483                "{message}"
1484            );
1485        }
1486    }
1487
1488    // -- Kimi Partial Mode (prefix continuation) --
1489
1490    #[test]
1491    fn partial_assistant_renders_open_turn_in_place_of_generation_prompt() {
1492        let mut request = Request::new(json!([
1493            {"role": "user", "content": "Greet the customer"},
1494            {"role": "assistant", "content": "Dear customer, hello", "partial": true}
1495        ]));
1496        request
1497            .args
1498            .insert("thinking".to_string(), Value::Bool(false));
1499
1500        let rendered = fmt().render(&request).unwrap();
1501
1502        assert_eq!(
1503            rendered,
1504            concat!(
1505                "<|open|>message role=\"user\"<|sep|>Greet the customer",
1506                "<|close|>message<|sep|><|end_of_msg|>",
1507                "<|open|>message role=\"assistant\"<|sep|>",
1508                "<|open|>response<|sep|>Dear customer, hello"
1509            ),
1510            "the partial turn must stay open: no <|close|>response / <|close|>message / <|end_of_msg|>, \
1511             and no extra generation prompt after it"
1512        );
1513        for tool_calls in [Value::Null, json!([])] {
1514            request.messages[1]["tool_calls"] = tool_calls;
1515            assert_eq!(fmt().render(&request).unwrap(), rendered);
1516        }
1517    }
1518
1519    #[test]
1520    fn partial_assistant_ignores_add_generation_prompt_flag() {
1521        let mut request = Request::new(json!([
1522            {"role": "user", "content": "Go"},
1523            {"role": "assistant", "content": "prefix", "partial": true}
1524        ]));
1525        request
1526            .args
1527            .insert("thinking".to_string(), Value::Bool(false));
1528        request.add_generation_prompt = false;
1529
1530        let rendered = fmt().render(&request).unwrap();
1531
1532        assert!(rendered.ends_with("<|open|>response<|sep|>prefix"));
1533        assert_eq!(rendered.matches("role=\"assistant\"").count(), 1);
1534    }
1535
1536    #[test]
1537    fn partial_assistant_in_thinking_mode_closes_think_then_opens_response() {
1538        let mut request = Request::new(json!([
1539            {"role": "user", "content": "Go"},
1540            {
1541                "role": "assistant",
1542                "reasoning_content": "carried over reasoning",
1543                "content": "prefix",
1544                "partial": true
1545            }
1546        ]));
1547        request
1548            .args
1549            .insert("thinking".to_string(), Value::Bool(true));
1550
1551        let rendered = fmt().render(&request).unwrap();
1552
1553        assert!(rendered.ends_with(concat!(
1554            "<|open|>message role=\"assistant\"<|sep|>",
1555            "<|open|>think<|sep|>carried over reasoning<|close|>think<|sep|>",
1556            "<|open|>response<|sep|>prefix"
1557        )));
1558    }
1559
1560    #[test]
1561    fn partial_assistant_keeps_name_as_part_of_the_prefix() {
1562        let mut request = Request::new(json!([
1563            {"role": "user", "content": "Who are you?"},
1564            {"role": "assistant", "name": "Sherlock", "content": "Elementary", "partial": true}
1565        ]));
1566        request
1567            .args
1568            .insert("thinking".to_string(), Value::Bool(false));
1569
1570        let rendered = fmt().render(&request).unwrap();
1571
1572        assert!(rendered.ends_with(concat!(
1573            "<|open|>message role=\"assistant\" name=\"Sherlock\"<|sep|>",
1574            "<|open|>response<|sep|>Elementary"
1575        )));
1576    }
1577
1578    #[test]
1579    fn partial_assistant_follows_internal_system_messages() {
1580        // tool_choice / response_format hints are injected after history and
1581        // before the generation turn; a partial turn must not be split by them.
1582        let mut request = Request::new(json!([
1583            {"role": "user", "content": "Go"},
1584            {"role": "assistant", "content": "prefix", "partial": true}
1585        ]));
1586        request.tools = Some(json!([{
1587            "type": "function",
1588            "function": {"name": "lookup", "parameters": {"type": "object"}}
1589        }]));
1590        request.tool_choice = Some(json!("none"));
1591        request
1592            .args
1593            .insert("thinking".to_string(), Value::Bool(false));
1594
1595        let rendered = fmt().render(&request).unwrap();
1596
1597        let hint = rendered
1598            .find("tool_choice=none")
1599            .expect("tool-choice hint rendered");
1600        let turn = rendered
1601            .rfind("<|open|>message role=\"assistant\"<|sep|>")
1602            .expect("partial turn rendered");
1603        assert!(
1604            hint < turn,
1605            "internal system messages must precede the open partial turn"
1606        );
1607        assert!(rendered.ends_with("<|open|>response<|sep|>prefix"));
1608    }
1609
1610    #[test]
1611    fn partial_false_is_an_ordinary_assistant_turn() {
1612        let mut request = Request::new(json!([
1613            {"role": "user", "content": "Go"},
1614            {"role": "assistant", "content": "done", "partial": false}
1615        ]));
1616        request
1617            .args
1618            .insert("thinking".to_string(), Value::Bool(false));
1619
1620        let rendered = fmt().render(&request).unwrap();
1621
1622        assert!(rendered.contains(
1623            "<|open|>response<|sep|>done<|close|>response<|sep|><|close|>message<|sep|><|end_of_msg|>"
1624        ));
1625        assert!(
1626            rendered.ends_with("<|open|>message role=\"assistant\"<|sep|><|open|>response<|sep|>")
1627        );
1628    }
1629
1630    #[test]
1631    fn rejects_partial_on_a_non_final_message() {
1632        let request = Request::new(json!([
1633            {"role": "assistant", "content": "early", "partial": true},
1634            {"role": "user", "content": "Go"}
1635        ]));
1636
1637        let error = fmt().render(&request).unwrap_err();
1638
1639        assert!(matches!(
1640            error.downcast_ref::<PromptRenderError>(),
1641            Some(PromptRenderError::InvalidRequest(message))
1642                if message == "Kimi K3 `partial` is only supported on the final message"
1643        ));
1644    }
1645
1646    #[test]
1647    fn rejects_partial_on_a_non_assistant_message() {
1648        let request = Request::new(json!([
1649            {"role": "user", "content": "Go", "partial": false}
1650        ]));
1651        let error = fmt().render(&request).unwrap_err();
1652        assert_eq!(
1653            invalid_request_message(&error),
1654            "Kimi K3 `partial` is only supported on an assistant message"
1655        );
1656    }
1657
1658    #[test]
1659    fn rejects_non_boolean_partial() {
1660        let request = Request::new(json!([
1661            {"role": "assistant", "content": "done", "partial": "true"}
1662        ]));
1663        let error = fmt().render(&request).unwrap_err();
1664        assert_eq!(
1665            invalid_request_message(&error),
1666            "Kimi K3 `partial` must be a boolean"
1667        );
1668    }
1669
1670    #[test]
1671    fn null_partial_is_equivalent_to_absent() {
1672        let mut request = Request::new(json!([
1673            {"role": "user", "content": "Go"}
1674        ]));
1675        let expected = fmt().render(&request).unwrap();
1676        request.messages[0]["partial"] = Value::Null;
1677        assert_eq!(fmt().render(&request).unwrap(), expected);
1678    }
1679
1680    // -- Dynamic tool system messages: content XOR tools --
1681
1682    fn invalid_request_message(error: &anyhow::Error) -> &str {
1683        match error.downcast_ref::<PromptRenderError>() {
1684            Some(PromptRenderError::InvalidRequest(message)) => message,
1685            other => panic!("expected InvalidRequest, got {other:?}"),
1686        }
1687    }
1688
1689    #[test]
1690    fn rejects_system_message_with_both_content_and_tools() {
1691        let request = Request::new(json!([
1692            {
1693                "role": "system",
1694                "content": "You are helpful",
1695                "tools": [{"type": "function", "function": {"name": "lookup"}}]
1696            },
1697            {"role": "user", "content": "Go"}
1698        ]));
1699
1700        let error = fmt().render(&request).unwrap_err();
1701        assert_eq!(
1702            invalid_request_message(&error),
1703            "Kimi K3 system messages carry either `content` or `tools`, not both"
1704        );
1705    }
1706
1707    #[test]
1708    fn rejects_system_message_tools_that_are_not_an_array() {
1709        let request = Request::new(json!([
1710            {"role": "system", "tools": {"name": "lookup"}},
1711            {"role": "user", "content": "Go"}
1712        ]));
1713
1714        let error = fmt().render(&request).unwrap_err();
1715        assert_eq!(
1716            invalid_request_message(&error),
1717            "Kimi K3 dynamic tool messages need `tools` to be an array"
1718        );
1719    }
1720
1721    /// Moonshot's official dynamic-tools verifier sends `"content": ""`
1722    /// alongside `tools` and expects success. Empty content is "omitted".
1723    #[test]
1724    fn accepts_dynamic_tools_with_empty_string_content() {
1725        for empty in [json!(""), json!([]), Value::Null] {
1726            let mut request = Request::new(json!([
1727                {"role": "user", "content": "Start"},
1728                {
1729                    "role": "system",
1730                    "content": empty,
1731                    "tools": [{"type": "function", "function": {"name": "lookup"}}]
1732                },
1733                {"role": "user", "content": "Go"}
1734            ]));
1735            request
1736                .args
1737                .insert("thinking".to_string(), Value::Bool(false));
1738
1739            let rendered = fmt()
1740                .render(&request)
1741                .unwrap_or_else(|e| panic!("content={empty}: {e}"));
1742            assert!(
1743                rendered.contains("## New Tools Available"),
1744                "content={empty}"
1745            );
1746            assert!(
1747                !rendered.contains("<|open|>message role=\"system\"<|sep|><|close|>message"),
1748                "content={empty}: must not emit an empty system turn"
1749            );
1750        }
1751    }
1752
1753    #[test]
1754    fn rejects_malformed_dynamic_tool_entries() {
1755        let long_name = "a".repeat(257);
1756        for (entry, needle) in [
1757            (json!("lookup"), "must be JSON objects"),
1758            (
1759                json!({"parameters": {"type": "object"}}),
1760                "need a string `name`",
1761            ),
1762            (
1763                json!({"type": "web_search", "function": {"name": "lookup"}}),
1764                "type=\"function\"",
1765            ),
1766            (
1767                json!({"function": {"name": "lookup"}}),
1768                "need type=\"function\"",
1769            ),
1770            (
1771                json!({"type": "function", "name": "lookup"}),
1772                "need a `function` object",
1773            ),
1774            (json!({"name": ""}), "must match"),
1775            (json!({"name": "1bad_name"}), "must match"),
1776            (json!({"name": "bad@name"}), "must match"),
1777            (json!({"name": long_name}), "maximum is 256"),
1778        ] {
1779            let request = Request::new(json!([
1780                {"role": "system", "tools": [entry]},
1781                {"role": "user", "content": "Go"}
1782            ]));
1783            let error = fmt().render(&request).unwrap_err();
1784            assert!(
1785                invalid_request_message(&error).contains(needle),
1786                "entry={entry}: {}",
1787                invalid_request_message(&error)
1788            );
1789        }
1790    }
1791
1792    #[test]
1793    fn rejects_duplicate_tool_names_across_declarations() {
1794        let mut request = Request::new(json!([
1795            {"role": "system", "tools": [{"name": "lookup"}]},
1796            {"role": "user", "content": "Go"}
1797        ]));
1798        request.tools = Some(json!([{
1799            "type": "function",
1800            "function": {"name": "lookup", "parameters": {"type": "object"}}
1801        }]));
1802        let error = fmt().render(&request).unwrap_err();
1803        assert!(invalid_request_message(&error).contains("declared more than once"));
1804
1805        request.messages[0]["role"] = json!("developer");
1806        let error = fmt().render(&request).unwrap_err();
1807        assert!(invalid_request_message(&error).contains("declared more than once"));
1808
1809        let mut request = Request::new(json!([{"role": "user", "content": "Go"}]));
1810        request.tools = Some(json!([
1811            {"type": "function", "function": {"name": "lookup"}},
1812            {"type": "function", "function": {"name": "lookup"}}
1813        ]));
1814        let error = fmt().render(&request).unwrap_err();
1815        assert!(invalid_request_message(&error).contains("more than once in `tools`"));
1816
1817        let max_name = "a".repeat(256);
1818        let request = Request::new(json!([
1819            {"role": "system", "tools": [
1820                {"name": "_private-tool_2"},
1821                {"type": "function", "function": {"name": max_name}}
1822            ]},
1823            {"role": "user", "content": "Go"}
1824        ]));
1825        fmt().render(&request).unwrap();
1826
1827        let mut request = Request::new(json!([
1828            {"role": "system", "tools": [{"name": "lookup"}, {"type": "function", "function": {"name": "search"}}]},
1829            {"role": "user", "content": "Go"}
1830        ]));
1831        request.tools = Some(json!([{
1832            "type": "function",
1833            "function": {"name": "add", "parameters": {"type": "object"}}
1834        }]));
1835        fmt().render(&request).unwrap();
1836    }
1837
1838    #[test]
1839    fn empty_tools_list_is_an_ordinary_system_message() {
1840        let mut request = Request::new(json!([
1841            {"role": "system", "content": "You are helpful", "tools": []},
1842            {"role": "user", "content": "Go"}
1843        ]));
1844        request
1845            .args
1846            .insert("thinking".to_string(), Value::Bool(false));
1847
1848        let rendered = fmt().render(&request).unwrap();
1849        assert!(rendered.contains("<|open|>message role=\"system\"<|sep|>You are helpful"));
1850        assert!(!rendered.contains("## New Tools Available"));
1851
1852        let request = Request::new(json!([
1853            {"role": "system", "tools": []},
1854            {"role": "user", "content": "Go"}
1855        ]));
1856        let error = fmt().render(&request).unwrap_err();
1857        assert_eq!(
1858            invalid_request_message(&error),
1859            "Kimi K3 system messages need `content` or `tools`"
1860        );
1861    }
1862
1863    #[test]
1864    fn rejects_system_message_with_neither_content_nor_tools() {
1865        let request = Request::new(json!([
1866            {"role": "system"},
1867            {"role": "user", "content": "Go"}
1868        ]));
1869
1870        let error = fmt().render(&request).unwrap_err();
1871        assert_eq!(
1872            invalid_request_message(&error),
1873            "Kimi K3 system messages need `content` or `tools`"
1874        );
1875    }
1876
1877    // -- Typed request path: JSON -> CreateChatCompletionRequest -> renderer --
1878    //
1879    // The raw-JSON `Request` above bypasses protocol deserialization. These
1880    // tests go through `dynamo_protocols::types::CreateChatCompletionRequest`
1881    // and its default `OAIChatLikeRequest` impl, which is what an HTTP frontend
1882    // actually hands to the formatter.
1883
1884    fn typed(body: Value) -> dynamo_protocols::types::CreateChatCompletionRequest {
1885        serde_json::from_value(body).expect("request deserializes")
1886    }
1887
1888    #[test]
1889    fn typed_request_rejects_invalid_top_level_tool_name() {
1890        let request = typed(json!({
1891            "model": "kimi-k3",
1892            "messages": [{"role": "user", "content": "Look it up"}],
1893            "tools": [{
1894                "type": "function",
1895                "function": {"name": "bad@name", "parameters": {"type": "object"}}
1896            }]
1897        }));
1898
1899        let error = fmt().render(&request).unwrap_err();
1900        assert_eq!(
1901            invalid_request_message(&error),
1902            "Kimi K3 tool name \"bad@name\" must match [A-Za-z_][A-Za-z0-9_-]*"
1903        );
1904    }
1905
1906    #[test]
1907    fn typed_request_renders_dynamic_tools_and_final_partial_end_to_end() {
1908        let request = typed(json!({
1909            "model": "kimi-k3",
1910            "messages": [
1911                {"role": "system", "tools": [{
1912                    "type": "function",
1913                    "function": {"name": "lookup", "parameters": {"type": "object"}}
1914                }]},
1915                {"role": "user", "content": "Look it up"},
1916                {"role": "assistant", "content": "Looking", "partial": true}
1917            ]
1918        }));
1919
1920        let rendered = fmt().render(&request).unwrap();
1921
1922        assert!(rendered.contains("## New Tools Available"));
1923        assert!(rendered.contains("\"lookup\""));
1924        assert!(
1925            rendered.ends_with("<|open|>response<|sep|>Looking"),
1926            "partial turn must stay open, got {rendered:?}"
1927        );
1928    }
1929
1930    #[test]
1931    fn typed_request_preserves_content_and_tools_for_renderer_conflict_check() {
1932        let request = typed(json!({
1933            "model": "kimi-k3",
1934            "messages": [
1935                {
1936                    "role": "system",
1937                    "content": "You are helpful",
1938                    "tools": [{"type": "function", "function": {"name": "lookup"}}]
1939                },
1940                {"role": "user", "content": "Go"}
1941            ]
1942        }));
1943
1944        let system = serde_json::to_value(&request.messages[0]).unwrap();
1945        assert_eq!(system["content"], json!("You are helpful"));
1946        assert_eq!(system["tools"][0]["function"]["name"], json!("lookup"));
1947
1948        let error = fmt().render(&request).unwrap_err();
1949        assert_eq!(
1950            invalid_request_message(&error),
1951            "Kimi K3 system messages carry either `content` or `tools`, not both"
1952        );
1953    }
1954
1955    #[test]
1956    fn rejects_partial_assistant_with_tool_calls() {
1957        let tool_call = json!({
1958            "id": "call_1",
1959            "type": "function",
1960            "function": {"name": "lookup", "arguments": "{}"}
1961        });
1962        for tool_calls in [json!([tool_call.clone()]), tool_call] {
1963            let request = Request::new(json!([
1964                {"role": "user", "content": "Go"},
1965                {
1966                    "role": "assistant",
1967                    "content": "prefix",
1968                    "partial": true,
1969                    "tool_calls": tool_calls
1970                }
1971            ]));
1972            let error = fmt().render(&request).unwrap_err();
1973            assert_eq!(
1974                invalid_request_message(&error),
1975                "Kimi K3 partial assistant messages cannot carry tool_calls",
1976                "tool_calls={tool_calls}"
1977            );
1978        }
1979    }
1980
1981    #[test]
1982    fn rejects_tools_on_final_partial_assistant_raw_path() {
1983        let request = Request::new(json!([
1984            {"role": "user", "content": "Go"},
1985            {
1986                "role": "assistant",
1987                "content": "prefix",
1988                "partial": true,
1989                "tools": [{"type": "function", "function": {"name": "lookup"}}]
1990            }
1991        ]));
1992
1993        let error = fmt().render(&request).unwrap_err();
1994
1995        assert!(matches!(
1996            error.downcast_ref::<PromptRenderError>(),
1997            Some(PromptRenderError::InvalidRequest(message))
1998                if message == "`tools` is only accepted on system or developer messages, not on role assistant"
1999        ));
2000    }
2001
2002    #[test]
2003    fn named_tool_choice_forces_tool_and_disables_thinking() {
2004        let mut request = Request::new(json!([
2005            {"role": "user", "content": "What did you do before?"},
2006            {
2007                "role": "assistant",
2008                "reasoning_content": "historical hidden reasoning",
2009                "content": "I answered the earlier question."
2010            },
2011            {"role": "user", "content": "Calculate"}
2012        ]));
2013        request.tools = Some(json!([{
2014            "type": "function",
2015            "function": {
2016                "name": "add_numbers",
2017                "parameters": {
2018                    "type": "object",
2019                    "properties": {
2020                        "a": {"type": "integer"},
2021                        "b": {"type": "integer"}
2022                    },
2023                    "required": ["a", "b"]
2024                }
2025            }
2026        }]));
2027        request.tool_choice = Some(json!({
2028            "type": "function",
2029            "function": {"name": "add_numbers"}
2030        }));
2031        request
2032            .args
2033            .insert("thinking".to_string(), Value::Bool(true));
2034
2035        let rendered = fmt().render(&request).unwrap();
2036        assert!(rendered.contains("The system is invoked with `tool_choice=specified`."));
2037        assert!(rendered.contains("MUST call the tool `add_numbers`"));
2038        assert!(
2039            rendered.ends_with("<|open|>message role=\"assistant\"<|sep|><|open|>response<|sep|>"),
2040            "named tool choice must use K3's non-thinking generation prefix"
2041        );
2042        assert!(
2043            !rendered.contains("<|open|>think<|sep|>"),
2044            "named tool choice must override thinking=true"
2045        );
2046        assert!(
2047            !rendered.contains("historical hidden reasoning"),
2048            "named tool choice must also suppress preserved thinking history"
2049        );
2050    }
2051
2052    #[test]
2053    fn named_tool_choice_accepts_a_dynamic_system_tool() {
2054        for lookup in [
2055            json!({"type": "function", "function": {"name": "lookup", "parameters": {"type": "object"}}}),
2056            json!({"name": "lookup", "parameters": {"type": "object"}}),
2057        ] {
2058            let mut request = Request::new(json!([
2059                {"role": "user", "content": "Start"},
2060                {"role": "system", "tools": [lookup]},
2061                {"role": "user", "content": "Look this up"}
2062            ]));
2063            request.tool_choice = Some(json!({
2064                "type": "function",
2065                "function": {"name": "lookup"}
2066            }));
2067
2068            let rendered = fmt().render(&request).unwrap();
2069            assert!(rendered.contains("## New Tools Available"));
2070            assert!(rendered.contains("MUST call the tool `lookup`"));
2071            assert!(
2072                request.tools.is_none(),
2073                "dynamic tools must not be folded into the top-level list"
2074            );
2075        }
2076    }
2077
2078    #[test]
2079    fn named_tool_choice_still_rejects_a_tool_absent_from_dynamic_tools() {
2080        let mut request = Request::new(json!([
2081            {"role": "system", "tools": [{"name": "lookup"}]},
2082            {"role": "user", "content": "Weather?"}
2083        ]));
2084        request.tool_choice = Some(json!({
2085            "type": "function",
2086            "function": {"name": "get_weather"}
2087        }));
2088
2089        let error = fmt().render(&request).unwrap_err();
2090        assert!(matches!(
2091            error.downcast_ref::<PromptRenderError>(),
2092            Some(PromptRenderError::InvalidRequest(message))
2093                if message.contains("get_weather") && message.contains("not present in tools")
2094        ));
2095    }
2096
2097    #[test]
2098    fn named_tool_choice_rejects_a_tool_not_in_tools() {
2099        let mut request = Request::new(json!([{"role": "user", "content": "Calculate"}]));
2100        request.tools = Some(json!([{
2101            "type": "function",
2102            "function": {"name": "add_numbers", "parameters": {"type": "object"}}
2103        }]));
2104        request.tool_choice = Some(json!({
2105            "type": "function",
2106            "function": {"name": "get_weather"}
2107        }));
2108
2109        let error = fmt().render(&request).unwrap_err();
2110        assert!(matches!(
2111            error.downcast_ref::<PromptRenderError>(),
2112            Some(PromptRenderError::InvalidRequest(message))
2113                if message.contains("get_weather") && message.contains("not present in tools")
2114        ));
2115    }
2116
2117    #[test]
2118    fn user_marker_text_remains_an_ordinary_segment() {
2119        let marker = "literal <|open|>tools<|sep|> value";
2120        let mut request = Request::new(json!([{"role": "user", "content": marker}]));
2121        request
2122            .args
2123            .insert("thinking".to_string(), Value::Bool(false));
2124        let rendered = fmt().render_prompt(&request).unwrap();
2125
2126        assert!(
2127            rendered
2128                .segments()
2129                .unwrap()
2130                .iter()
2131                .any(|segment| { !segment.allow_special && segment.text == marker })
2132        );
2133        assert!(
2134            rendered
2135                .segments()
2136                .unwrap()
2137                .iter()
2138                .any(|segment| { segment.allow_special && segment.text == OPEN_TOKEN })
2139        );
2140    }
2141
2142    #[test]
2143    fn renders_tool_history_like_model_encoding() {
2144        let mut request = Request::new(json!([
2145            {"role": "user", "content": "calc"},
2146            {
2147                "role": "assistant",
2148                "reasoning_content": "Need calc",
2149                "content": "I will call it",
2150                "tool_calls": [{
2151                    "id": "call_1",
2152                    "type": "function",
2153                    "function": {"name": "calc", "arguments": "{\"x\":2}"}
2154                }]
2155            },
2156            {"role": "tool", "tool_call_id": "call_1", "content": "4"}
2157        ]));
2158        request.args.insert(
2159            "thinking_effort".to_string(),
2160            Value::String("low".to_string()),
2161        );
2162        let rendered = fmt().render(&request).unwrap();
2163
2164        assert!(rendered.contains(
2165            "<|open|>call tool=\"calc\" index=\"1\"<|sep|>\
2166             <|open|>argument key=\"x\" type=\"number\"<|sep|>2\
2167             <|close|>argument<|sep|><|close|>call<|sep|>"
2168        ));
2169        assert!(
2170            rendered.contains("<|open|>message role=\"tool\" tool=\"calc\" index=\"1\"<|sep|>4")
2171        );
2172        assert!(
2173            rendered.ends_with("<|open|>message role=\"assistant\"<|sep|><|open|>think<|sep|>")
2174        );
2175    }
2176
2177    #[test]
2178    fn tool_result_order_preserves_unresolved_runs() {
2179        let assistant = json!({"role": "assistant", "tool_calls": [
2180            {"id": "first", "function": {"name": "one"}},
2181            {"id": "second", "function": {"name": "two"}}
2182        ]});
2183        let second =
2184            json!({"role": "tool", "tool_call_id": "second", "content": "第二", "name": "old"});
2185        let first = json!({"role": "tool", "tool_call_id": "first", "content": "第一"});
2186        let sorted =
2187            normalize_tool_result_messages(vec![assistant.clone(), second.clone(), first]).unwrap();
2188        assert_eq!(sorted[1]["content"], "第一");
2189        assert_eq!(sorted[1]["tool"], "one");
2190        assert_eq!(sorted[2]["content"], "第二");
2191        assert_eq!(sorted[2]["tool"], "two");
2192        assert_eq!(sorted[2]["name"], "two");
2193
2194        let unresolved = vec![
2195            assistant,
2196            second,
2197            json!({"role": "tool", "tool_call_id": "unknown", "content": "keep order"}),
2198        ];
2199        assert_eq!(
2200            normalize_tool_result_messages(unresolved.clone()).unwrap(),
2201            unresolved
2202        );
2203    }
2204
2205    #[test]
2206    fn thinking_history_renders_an_empty_think_channel() {
2207        let request = Request::new(json!([
2208            {"role": "user", "content": "question"},
2209            {"role": "assistant", "content": "answer"},
2210            {"role": "user", "content": "follow-up"}
2211        ]));
2212
2213        let rendered = fmt().render(&request).unwrap();
2214
2215        assert!(rendered.contains(concat!(
2216            "<|open|>message role=\"assistant\"<|sep|>",
2217            "<|open|>think<|sep|><|close|>think<|sep|>",
2218            "<|open|>response<|sep|>answer<|close|>response<|sep|>"
2219        )));
2220    }
2221
2222    #[test]
2223    fn non_thinking_history_omits_preserved_reasoning() {
2224        let mut request = Request::new(json!([
2225            {"role": "user", "content": "question"},
2226            {
2227                "role": "assistant",
2228                "reasoning_content": "hidden reasoning",
2229                "content": "answer"
2230            },
2231            {"role": "user", "content": "follow-up"}
2232        ]));
2233        request
2234            .args
2235            .insert("thinking".to_string(), Value::Bool(false));
2236
2237        let rendered = fmt().render(&request).unwrap();
2238
2239        assert!(!rendered.contains("hidden reasoning"));
2240        assert!(!rendered.contains("<|open|>think<|sep|>"));
2241        assert!(rendered.contains(concat!(
2242            "<|open|>message role=\"assistant\"<|sep|>",
2243            "<|open|>response<|sep|>answer<|close|>response<|sep|>"
2244        )));
2245    }
2246
2247    #[test]
2248    fn tools_are_deep_sorted_before_declaration() {
2249        let mut request = Request::new(json!([{"role": "user", "content": "Weather?"}]));
2250        request
2251            .args
2252            .insert("thinking".to_string(), Value::Bool(false));
2253        request.tools = Some(json!([{
2254            "type": "function",
2255            "function": {
2256                "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
2257                "name": "weather",
2258                "description": "Get weather"
2259            }
2260        }]));
2261        let rendered = fmt().render(&request).unwrap();
2262        assert!(rendered.contains(concat!(
2263            "[{\"function\":{\"description\":\"Get weather\",",
2264            "\"name\":\"weather\",\"parameters\":{\"properties\":",
2265            "{\"city\":{\"type\":\"string\"}},\"type\":\"object\"}},",
2266            "\"type\":\"function\"}]"
2267        )));
2268    }
2269
2270    #[test]
2271    fn assistant_history_matches_python_json_spacing_and_reasoning_fallback() {
2272        let request = Request::new(json!([{
2273            "role": "assistant",
2274            "reasoning_content": "",
2275            "reasoning": "fallback",
2276            "content": null,
2277            "tool_calls": [{
2278                "type": "function",
2279                "function": {
2280                    "name": "run",
2281                    "arguments": {
2282                        "opts": {"a": 1, "b": [true, false]}
2283                    }
2284                }
2285            }]
2286        }]));
2287        let rendered = fmt().render(&request).unwrap();
2288
2289        assert!(rendered.contains("<|open|>think<|sep|>fallback<|close|>think<|sep|>"));
2290        assert!(rendered.contains(concat!(
2291            "<|open|>argument key=\"opts\" type=\"object\"<|sep|>",
2292            "{\"a\": 1, \"b\": [true, false]}",
2293            "<|close|>argument<|sep|>"
2294        )));
2295    }
2296
2297    #[test]
2298    fn assistant_history_keeps_whitespace_only_reasoning() {
2299        let request = Request::new(json!([
2300            {"role": "user", "content": "Hello"},
2301            {"role": "assistant", "reasoning_content": "\n\n", "content": "Hi"},
2302            {"role": "user", "content": "Again"}
2303        ]));
2304        let rendered = fmt().render(&request).unwrap();
2305
2306        assert!(
2307            rendered.contains("<|open|>think<|sep|>\n\n<|close|>think<|sep|>"),
2308            "whitespace-only reasoning must be rendered like encoding_k3.py"
2309        );
2310    }
2311
2312    fn pending_texts(prompt: &RenderedPrompt) -> Vec<String> {
2313        let segments = prompt.segments().unwrap();
2314        segments[segments.len() - prompt.pending_segments()..]
2315            .iter()
2316            .map(|segment| segment.text.clone())
2317            .collect()
2318    }
2319
2320    #[test]
2321    fn non_thinking_generation_stub_is_reported_as_pending_segments() {
2322        let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
2323        request
2324            .args
2325            .insert("thinking".to_string(), Value::Bool(false));
2326        let prompt = fmt().render_prompt(&request).unwrap();
2327        assert_eq!(prompt.pending_segments(), 3);
2328        assert_eq!(pending_texts(&prompt), ["<|open|>", "response", "<|sep|>"]);
2329        // The assistant message header stays part of the prompt proper.
2330        let pending = prompt.pending_encode_segments().unwrap();
2331        assert_eq!(pending.len(), 3);
2332        assert!(pending[0].allow_special, "open marker is a control token");
2333        assert!(!pending[1].allow_special, "channel name is ordinary text");
2334        assert!(pending[2].allow_special, "sep marker is a control token");
2335        assert!(prompt.as_str().ends_with(concat!(
2336            "<|open|>message role=\"assistant\"<|sep|>",
2337            "<|open|>response<|sep|>"
2338        )));
2339    }
2340
2341    #[test]
2342    fn thinking_generation_stub_is_reported_as_pending_segments() {
2343        let request = Request::new(json!([{"role": "user", "content": "Hello"}]));
2344        let prompt = fmt().render_prompt(&request).unwrap();
2345        assert_eq!(prompt.pending_segments(), 3);
2346        assert_eq!(pending_texts(&prompt), ["<|open|>", "think", "<|sep|>"]);
2347    }
2348
2349    #[test]
2350    fn response_format_instructions_are_prompt_not_pending() {
2351        let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
2352        request
2353            .args
2354            .insert("thinking".to_string(), Value::Bool(false));
2355        request.response_format = Some(json!({
2356            "type": "json_schema",
2357            "json_schema": {
2358                "name": "capital_answer",
2359                "schema": {
2360                    "type": "object",
2361                    "properties": {"capital": {"type": "boolean"}},
2362                    "required": ["capital"],
2363                    "additionalProperties": false
2364                }
2365            }
2366        }));
2367        let prompt = fmt().render_prompt(&request).unwrap();
2368        assert_eq!(prompt.pending_segments(), 3);
2369        assert_eq!(pending_texts(&prompt), ["<|open|>", "response", "<|sep|>"]);
2370        let stub_start = prompt.as_str().len() - "<|open|>response<|sep|>".len();
2371        let schema_at = prompt
2372            .as_str()
2373            .find("type=\"response-format\"")
2374            .expect("response_format renders a system message");
2375        assert!(
2376            schema_at < stub_start,
2377            "schema instructions precede the stub"
2378        );
2379    }
2380
2381    #[test]
2382    fn no_generation_prompt_has_no_pending_segments() {
2383        let mut request = Request::new(json!([{"role": "user", "content": "Hello"}]));
2384        request.add_generation_prompt = false;
2385        let prompt = fmt().render_prompt(&request).unwrap();
2386        assert_eq!(prompt.pending_segments(), 0);
2387        assert!(prompt.pending_encode_segments().unwrap().is_empty());
2388        assert!(prompt.as_str().ends_with("<|end_of_msg|>"));
2389    }
2390
2391    #[test]
2392    fn partial_assistant_continuation_has_no_pending_segments() {
2393        let mut request = Request::new(json!([
2394            {"role": "user", "content": "Hello"},
2395            {"role": "assistant", "content": "Hi", "partial": true}
2396        ]));
2397        request
2398            .args
2399            .insert("thinking".to_string(), Value::Bool(false));
2400        let prompt = fmt().render_prompt(&request).unwrap();
2401        assert_eq!(prompt.pending_segments(), 0);
2402    }
2403}