Skip to main content

dynamo_renderer/template/
oai.rs

1// SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4use super::*;
5
6use crate::{OAIChatLikeRequest, TextInput};
7use minijinja::{context, value::Value};
8use serde_json::json;
9use std::result::Result::Ok;
10
11/// Fix a tool schema that is missing `type`/`properties`. `pub` so consumers
12/// can normalize their own `tools` value when implementing
13/// [`crate::OAIChatLikeRequest::tools`].
14pub fn may_be_fix_tool_schema(tools: serde_json::Value) -> Option<Value> {
15    // No need to validate or enforce other schema checks as the basic Named function schema is already validated while creating the request.
16    // Empty parameters is allowed by OpenAI at request level. Need to enforce it at template level.
17    // Whenever parameters is empty, insert "type": "object" and "properties": {}
18    let mut updated_tools = Vec::new();
19    if let Some(arr) = tools.as_array() {
20        for tool in arr {
21            let mut tool = tool.clone();
22            if let Some(function) = tool.get_mut("function") {
23                // Backfill a missing/null `description`. It's optional in the
24                // OpenAI tool schema, but some chat templates (e.g. gpt-oss
25                // harmony) concatenate it unconditionally and fail on an
26                // `undefined`/null value.
27                if let Some(obj) = function.as_object_mut()
28                    && !matches!(obj.get("description"), Some(serde_json::Value::String(_)))
29                {
30                    obj.insert(
31                        "description".to_string(),
32                        serde_json::Value::String(String::new()),
33                    );
34                }
35            }
36            if let Some(function) = tool.get_mut("function")
37                && let Some(parameters) = function.get_mut("parameters")
38            {
39                // Only operate if parameters is an object
40                if parameters.is_object() {
41                    let mut needs_type = false;
42                    let mut needs_properties = false;
43                    let is_empty = parameters
44                        .as_object()
45                        .map(|o| o.is_empty())
46                        .unwrap_or(false);
47
48                    // If empty, we need to insert both
49                    if is_empty {
50                        needs_type = true;
51                        needs_properties = true;
52                    } else {
53                        // If not empty, check if type/properties are missing
54                        if let Some(obj) = parameters.as_object() {
55                            if !obj.contains_key("type") {
56                                needs_type = true;
57                            }
58                            if !obj.contains_key("properties") {
59                                needs_properties = true;
60                            }
61                        }
62                    }
63
64                    if (needs_type || needs_properties)
65                        && let Some(obj) = parameters.as_object_mut()
66                    {
67                        if needs_type {
68                            obj.insert(
69                                "type".to_string(),
70                                serde_json::Value::String("object".to_string()),
71                            );
72                        }
73                        if needs_properties {
74                            obj.insert(
75                                "properties".to_string(),
76                                serde_json::Value::Object(Default::default()),
77                            );
78                        }
79                    }
80                }
81            }
82            updated_tools.push(tool);
83        }
84    }
85    Some(Value::from_serialize(&updated_tools))
86}
87
88/// Default media type conversions for multimodal content.
89/// Maps source types (e.g., "image_url") to target placeholder types (e.g., "image").
90const DEFAULT_MEDIA_TYPE_CONVERSIONS: &[(&str, &str)] = &[
91    ("image_url", "image"),
92    ("video_url", "video"),
93    ("audio_url", "audio"),
94];
95
96/// Convert media URL content parts to empty placeholder types.
97fn convert_media_url_to_placeholder(
98    content_array: &mut [serde_json::Value],
99    conversions: &[(&str, &str)],
100) {
101    for part in content_array {
102        let part_type = part.get("type").and_then(|t| t.as_str()).unwrap_or("");
103        if let Some((_, target_type)) = conversions.iter().find(|(src, _)| *src == part_type) {
104            *part = serde_json::json!({"type": target_type});
105        }
106    }
107}
108
109fn may_be_fix_msg_content(
110    mut messages: serde_json::Value,
111    preserve_arrays: bool,
112    image_placeholder_template: Option<&str>,
113) -> serde_json::Value {
114    let Some(arr) = messages.as_array_mut() else {
115        return messages;
116    };
117    for msg in arr {
118        let Some(content) = msg.get_mut("content") else {
119            continue;
120        };
121        match content {
122            serde_json::Value::String(_) if preserve_arrays => {
123                let text = content.take();
124                *content = serde_json::Value::Array(vec![serde_json::Value::Object(
125                    serde_json::Map::from_iter([
126                        ("type".into(), serde_json::Value::String("text".into())),
127                        ("text".into(), text),
128                    ]),
129                )]);
130            }
131            serde_json::Value::Array(parts) => {
132                convert_media_url_to_placeholder(parts, DEFAULT_MEDIA_TYPE_CONVERSIONS);
133                // An empty array must remain an array. Templates distinguish it
134                // from an empty string, including when the placeholder is "".
135                let text_only = !parts.is_empty()
136                    && parts
137                        .iter()
138                        .all(|part| part.get("type").and_then(|v| v.as_str()) == Some("text"));
139                if text_only && !preserve_arrays {
140                    let text = parts
141                        .iter()
142                        .filter_map(|part| part.get("text")?.as_str())
143                        .collect::<Vec<_>>()
144                        .join("\n");
145                    *content = serde_json::Value::String(text);
146                } else if !preserve_arrays
147                    && !parts.is_empty()
148                    && let Some(template) = image_placeholder_template
149                {
150                    *content = serde_json::Value::String(flatten_mixed_content(parts, template));
151                }
152            }
153            _ => {}
154        }
155    }
156    messages
157}
158
159/// Concatenate a mixed-content array (text parts + image placeholders) into a
160/// single string. Text parts contribute their `text` field as-is; non-text
161/// parts (image, video, audio after the URL→placeholder conversion in
162/// `convert_media_url_to_placeholder`) emit the per-family placeholder with
163/// `{n}` substituted by the 1-based index of the image in the message.
164///
165/// Used in `may_be_fix_msg_content` when `preserve_arrays=false` and the
166/// template knows a placeholder convention — currently Phi-3-vision
167/// (`<|image_{n}|>`), LLaVA-1.5 (`<image>`), and pure pass-through /
168/// encoder-decoder templates (`""`, image emits nothing — Nemotron-Parse).
169/// With an empty `placeholder_tpl` the non-text parts contribute no characters,
170/// so the result is the concatenated text parts only.
171///
172/// **Caveat — non-text index slot:** `img_idx` increments for every non-text
173/// part, not just images. The current supported families (Phi-3, LLaVA-1.5)
174/// are image-only so there's no collision today, but a future image+video
175/// family would silently consume an image-index slot for each video/audio
176/// part and emit the image placeholder there. When adding a family that
177/// mixes modalities in one message, either:
178///   1. expand this function with per-modality placeholder strings, or
179///   2. assert in `convert_media_url_to_placeholder` that only "image"
180///      placeholders reach this path.
181fn flatten_mixed_content(parts: &[serde_json::Value], placeholder_tpl: &str) -> String {
182    let mut out = String::new();
183    let mut img_idx: u32 = 1;
184    for part in parts {
185        let type_str = part.get("type").and_then(|t| t.as_str()).unwrap_or("");
186        if type_str == "text" {
187            if let Some(text) = part.get("text").and_then(|t| t.as_str()) {
188                out.push_str(text);
189            }
190        } else if !type_str.is_empty() {
191            let placeholder = placeholder_tpl.replace("{n}", &img_idx.to_string());
192            out.push_str(&placeholder);
193            img_idx += 1;
194        }
195    }
196    out
197}
198
199fn normalize_tool_calls_arguments_in_messages(messages: &mut serde_json::Value) {
200    // Deserialize `tool_calls[].function.arguments` from JSON strings to
201    // objects/arrays before template rendering — avoids double encoding
202    // and enables iteration. Skipped for templates whose own `is string`
203    // branch wants the raw string verbatim (see render()).
204    let Some(msgs) = messages.as_array_mut() else {
205        return;
206    };
207
208    for msg in msgs.iter_mut() {
209        if let Some(tool_calls) = msg.get_mut("tool_calls").and_then(|v| v.as_array_mut()) {
210            for tc in tool_calls {
211                if let Some(function) = tc.get_mut("function").and_then(|v| v.as_object_mut())
212                    && let Some(args) = function.get_mut("arguments")
213                    && let Some(s) = args.as_str()
214                    && let Ok(parsed) = serde_json::from_str(s)
215                {
216                    *args = parsed;
217                }
218            }
219        }
220    }
221}
222
223fn normalize_function_call_arguments_in_messages(messages: &mut serde_json::Value) {
224    // Legacy (deprecated) OpenAI `function_call.arguments` path. Kept separate
225    // from `tool_calls` normalization so the per-template `arguments is string`
226    // opt-out — which only refers to `tool_call.arguments` inside the
227    // tool_calls loop — does not accidentally suppress this path.
228    let Some(msgs) = messages.as_array_mut() else {
229        return;
230    };
231
232    for msg in msgs.iter_mut() {
233        if let Some(function_call) = msg.get_mut("function_call").and_then(|v| v.as_object_mut())
234            && let Some(args) = function_call.get_mut("arguments")
235            && let Some(s) = args.as_str()
236            && let Ok(parsed) = serde_json::from_str(s)
237        {
238            *args = parsed;
239        }
240    }
241}
242
243/// Inject `reasoning_content` back into the `content` field as `<think>` blocks.
244///
245/// Chat templates only reference `{{ message.content }}` — they don't know about
246/// `reasoning_content`. Without this injection, the model's prior chain-of-thought
247/// is silently dropped across turns.
248///
249/// Uses `<think>`/`</think>` delimiters — the same tags that reasoning models emit
250/// and that the reasoning parser strips on output. Reasoning is prepended to content
251/// to match the original generation order (`<think>...</think> response`).
252///
253/// Segments are concatenated rather than interleaved with tool_calls because Jinja
254/// templates render `tool_calls` separately from `content`. The model still sees
255/// all reasoning text before the template-rendered tool call block.
256fn inject_reasoning_content_into_messages(messages: &mut serde_json::Value) {
257    let Some(msgs) = messages.as_array_mut() else {
258        return;
259    };
260
261    for msg in msgs.iter_mut() {
262        if msg.get("role").and_then(|r| r.as_str()) != Some("assistant") {
263            continue;
264        }
265
266        let reasoning = match msg.get("reasoning_content") {
267            Some(serde_json::Value::String(s)) if !s.is_empty() => {
268                format!("<think>{}</think>", s)
269            }
270            Some(serde_json::Value::Array(segments)) => {
271                let mut result = String::new();
272                for seg in segments {
273                    if let Some(s) = seg.as_str()
274                        && !s.is_empty()
275                    {
276                        result.push_str("<think>");
277                        result.push_str(s);
278                        result.push_str("</think>");
279                    }
280                }
281                if result.is_empty() {
282                    continue;
283                }
284                result
285            }
286            _ => continue,
287        };
288
289        match msg.get("content") {
290            // Content is a string or null — prepend reasoning as text
291            Some(serde_json::Value::String(s)) if !s.is_empty() => {
292                msg["content"] = serde_json::Value::String(format!("{}{}", reasoning, s));
293            }
294            None | Some(serde_json::Value::Null) | Some(serde_json::Value::String(_)) => {
295                msg["content"] = serde_json::Value::String(reasoning);
296            }
297            // Content is an array (multimodal) — prepend as a text part
298            Some(serde_json::Value::Array(_)) => {
299                let think_part = serde_json::json!({
300                    "type": "text",
301                    "text": reasoning
302                });
303                if let Some(arr) = msg.get_mut("content").and_then(|v| v.as_array_mut()) {
304                    arr.insert(0, think_part);
305                }
306            }
307            // Other types (number, bool, object) — skip, don't corrupt
308            _ => continue,
309        }
310
311        // Remove so the template doesn't see both the injected <think> in content
312        // and the original reasoning_content field.
313        if let Some(obj) = msg.as_object_mut() {
314            obj.remove("reasoning_content");
315        }
316    }
317}
318
319/// Join `reasoning_content` segments into the flat string a template that only
320/// renders it when it `is string` expects; given the array, such templates
321/// silently drop the prior turn's reasoning. The flat form matches
322/// `ReasoningContent::to_flat_string` (non-empty segments joined by `\n`) and how
323/// SGLang merges consecutive reasoning items.
324fn join_reasoning_content_segments_in_messages(messages: &mut serde_json::Value) {
325    let Some(msgs) = messages.as_array_mut() else {
326        return;
327    };
328
329    for msg in msgs.iter_mut() {
330        if msg.get("role").and_then(|r| r.as_str()) != Some("assistant") {
331            continue;
332        }
333        if let Some(reasoning) = msg.get_mut("reasoning_content")
334            && let Some(segments) = reasoning.as_array()
335        {
336            let joined = segments
337                .iter()
338                .filter_map(|s| s.as_str())
339                .filter(|s| !s.is_empty())
340                .collect::<Vec<_>>()
341                .join("\n");
342            *reasoning = joined.into();
343        }
344    }
345}
346
347/// Default [`OAIChatLikeRequest`] impl for the bare `dynamo-protocols` chat
348/// request. Lets any consumer (e.g. a standalone OpenAI frontend over an
349/// engine) render HF chat templates directly from the wire type, without
350/// defining their own wrapper. Consumers with extra fields (Dynamo's
351/// `NvCreateChatCompletionRequest`) provide their own impl.
352impl OAIChatLikeRequest for dynamo_protocols::types::CreateChatCompletionRequest {
353    fn model(&self) -> String {
354        self.model.clone()
355    }
356
357    fn messages(&self) -> Value {
358        let messages_json = self.function_template_messages();
359        Value::from_serialize(&messages_json)
360    }
361
362    fn typed_messages(&self) -> Option<&[dynamo_protocols::types::ChatCompletionRequestMessage]> {
363        Some(self.messages.as_slice())
364    }
365
366    fn tools(&self) -> Option<Value> {
367        let tools = self.tools.as_ref()?;
368        may_be_fix_tool_schema(
369            serde_json::to_value(
370                tools
371                    .iter()
372                    .map(|tool| tool.function_template_tool())
373                    .collect::<Vec<_>>(),
374            )
375            .unwrap(),
376        )
377    }
378
379    fn tool_choice(&self) -> Option<Value> {
380        self.tool_choice
381            .as_ref()
382            .map(|choice| Value::from_serialize(choice.function_template_choice()))
383    }
384
385    fn response_format(&self) -> Option<Value> {
386        self.response_format.as_ref().map(Value::from_serialize)
387    }
388
389    fn reasoning_effort(&self) -> Option<Value> {
390        self.reasoning_effort.as_ref().map(Value::from_serialize)
391    }
392
393    fn should_add_generation_prompt(&self) -> bool {
394        // Using vLLM default behavior
395        true
396    }
397
398    fn extract_text(&self) -> Option<TextInput> {
399        Some(TextInput::Single(String::new()))
400    }
401
402    fn mm_processor_kwargs(&self) -> Option<&serde_json::Value> {
403        self.mm_processor_kwargs.as_ref()
404    }
405}
406
407/// Joins two message contents without flattening to text: a part array is
408/// spliced part for part, so image parts survive a merge. A string target is
409/// promoted to an array when the source carries parts.
410fn merge_message_content(
411    target: serde_json::Value,
412    source: serde_json::Value,
413) -> serde_json::Value {
414    use serde_json::Value;
415    let text_part = |text: String| json!({"type": "text", "text": text});
416    match (target, source) {
417        (Value::String(mut target), Value::String(source)) => {
418            if !target.is_empty() && !source.is_empty() {
419                target.push_str("\n\n");
420            }
421            target.push_str(&source);
422            Value::String(target)
423        }
424        (Value::Array(mut target), Value::Array(source)) => {
425            target.extend(source);
426            Value::Array(target)
427        }
428        (Value::Array(mut target), Value::String(source)) => {
429            if !source.is_empty() {
430                target.push(text_part(source));
431            }
432            Value::Array(target)
433        }
434        (Value::String(target), Value::Array(source)) => {
435            let mut parts = Vec::with_capacity(source.len() + 1);
436            if !target.is_empty() {
437                parts.push(text_part(target));
438            }
439            parts.extend(source);
440            Value::Array(parts)
441        }
442        (Value::Null, source) => source,
443        // Content is a string or a part array in every shape the schema allows.
444        (target, _) => target,
445    }
446}
447
448/// Merges `source` into `target`, leaving every other field on `target` intact.
449fn append_message_content(target: &mut serde_json::Value, source: serde_json::Value) {
450    let Some(target) = target.as_object_mut() else {
451        return;
452    };
453    let merged = merge_message_content(
454        target.remove("content").unwrap_or(serde_json::Value::Null),
455        source,
456    );
457    target.insert("content".to_string(), merged);
458}
459
460fn take_message_content(message: &mut serde_json::Value) -> serde_json::Value {
461    message
462        .get_mut("content")
463        .map(serde_json::Value::take)
464        .unwrap_or(serde_json::Value::Null)
465}
466
467/// Rewrites an agent-client message stream into a shape strict chat templates
468/// accept. Each rewrite is gated on the restriction the load-time probe actually
469/// found, so a template is never reshaped for a rule it does not enforce.
470fn normalize_system_messages(messages: &mut serde_json::Value, rules: SystemNormalization) {
471    let serde_json::Value::Array(list) = messages else {
472        return;
473    };
474    let role_is =
475        |m: &serde_json::Value, r: &str| m.get("role").and_then(|v| v.as_str()) == Some(r);
476
477    if rules.demote_nonleading_system {
478        // A template that rejects a system turn away from index 0 rejects a
479        // leading run of them too, so the run collapses into the first.
480        let leading = list.iter().take_while(|m| role_is(m, "system")).count();
481        if leading > 1 {
482            for mut trailing in list.drain(1..leading).collect::<Vec<_>>() {
483                let content = take_message_content(&mut trailing);
484                append_message_content(&mut list[0], content);
485            }
486        }
487
488        // Demoted in place, not folded to the front: a mid-conversation reminder
489        // that toggles would otherwise invalidate the whole KV prefix each turn.
490        let leading = list.iter().take_while(|m| role_is(m, "system")).count();
491        for m in list.iter_mut().skip(leading) {
492            if role_is(m, "system")
493                && let Some(m) = m.as_object_mut()
494            {
495                m.insert("role".to_string(), json!("user"));
496            }
497        }
498    }
499
500    if rules.coalesce_consecutive_users {
501        let mut coalesced: Vec<serde_json::Value> = Vec::with_capacity(list.len());
502        for mut m in list.drain(..) {
503            if role_is(&m, "user") && coalesced.last().is_some_and(|p| role_is(p, "user")) {
504                let content = take_message_content(&mut m);
505                append_message_content(coalesced.last_mut().unwrap(), content);
506            } else {
507                coalesced.push(m);
508            }
509        }
510        *list = coalesced;
511    }
512}
513
514impl HfTokenizerConfigJsonFormatter {
515    fn template_handles_native_tools(&self, has_tools: bool) -> bool {
516        if has_tools {
517            self.tool_use_template_handles_native_tools
518        } else {
519            self.default_template_handles_native_tools
520        }
521    }
522
523    fn render_with_token_policy(
524        &self,
525        req: &dyn OAIChatLikeRequest,
526        protect_literals: bool,
527    ) -> Result<crate::RenderedPrompt> {
528        let mixins = Value::from_dyn_object(self.mixins.clone());
529
530        let exclude = self.exclude_tools_when_tool_choice_none
531            && req.tool_choice().as_ref().and_then(Value::as_str) == Some("none");
532        let flat_tools = if exclude { None } else { req.tools() };
533        // Base variant selection on flat tools so changing representations cannot change it.
534        let has_tools = flat_tools
535            .as_ref()
536            .and_then(|tools| tools.len())
537            .is_some_and(|len| len > 0);
538        // Gate the native Responses view on template support. Flat Chat tools
539        // already preserve their explicit defer flags, as vLLM and SGLang do.
540        // Reuse the catalog already converted above when selecting capabilities.
541        let tools = if !exclude && self.template_handles_native_tools(has_tools) {
542            req.template_tools().or(flat_tools)
543        } else {
544            flat_tools
545        };
546        let add_generation_prompt = req.should_add_generation_prompt();
547
548        tracing::trace!(
549            "Rendering prompt with tools: {:?}, add_generation_prompt: {}",
550            has_tools,
551            add_generation_prompt
552        );
553
554        // Pick the concrete template before applying any template-specific
555        // message rewrites or field normalization.
556        let (
557            template_name,
558            template_handles_tool_calls_args_string,
559            template_handles_reasoning,
560            template_requires_reasoning_string,
561            system_normalization,
562        ) = if has_tools {
563            (
564                "tool_use",
565                self.tool_use_template_handles_tool_calls_arguments_string,
566                self.tool_use_template_handles_reasoning,
567                self.tool_use_template_requires_reasoning_string,
568                self.tool_use_system_normalization,
569            )
570        } else {
571            (
572                "default",
573                self.default_template_handles_tool_calls_arguments_string,
574                self.default_template_handles_reasoning,
575                self.default_template_requires_reasoning_string,
576                self.default_system_normalization,
577            )
578        };
579
580        let mut messages_for_template = crate::messages_to_json(req)?;
581
582        crate::reject_unsupported_partial_assistant(&messages_for_template)?;
583        crate::reject_unsupported_message_tools(&messages_for_template, &[])?;
584
585        if system_normalization.is_required() {
586            normalize_system_messages(&mut messages_for_template, system_normalization);
587        }
588
589        messages_for_template = may_be_fix_msg_content(
590            messages_for_template,
591            self.requires_content_arrays,
592            self.image_placeholder_template,
593        );
594
595        // Pre-parse JSON-string `arguments` into objects — but only for templates
596        // that unconditionally `| tojson` them. Templates that branch on
597        // `tool_call.arguments is string` (Qwen3, Hermes) want the raw string
598        // verbatim so the rendered bytes match what the model emitted on the
599        // prior turn. Re-serializing through minijinja's compact `tojson` here
600        // breaks append-only prefix matching across multi-step tool use.
601        if !template_handles_tool_calls_args_string {
602            normalize_tool_calls_arguments_in_messages(&mut messages_for_template);
603        }
604        // Legacy `function_call.arguments` is always normalized — the
605        // `arguments is string` opt-out only covers the modern `tool_calls`
606        // branch.
607        normalize_function_call_arguments_in_messages(&mut messages_for_template);
608
609        // Inject reasoning_content as <think> blocks into content — but only if
610        // the template doesn't handle it natively. Templates like Nemotron and
611        // Qwen3 reference reasoning_content directly in their Jinja logic; injecting
612        // would produce duplicate <think> blocks.
613        if !template_handles_reasoning {
614            inject_reasoning_content_into_messages(&mut messages_for_template);
615        } else if template_requires_reasoning_string {
616            join_reasoning_content_segments_in_messages(&mut messages_for_template);
617        }
618
619        let tmpl = self.env.get_template(template_name)?;
620        let mut literals = Vec::new();
621        let mut tools = tools;
622        let mut placeholder = "__DYNAMO_HARMONY_LITERAL_".to_string();
623        if protect_literals
624            && tmpl.source().contains("<|start|>")
625            && tmpl.source().contains("<|message|>")
626        {
627            // Only template-owned markers are controls. Markers in message/tool
628            // data must survive Jinja unchanged and encode as ordinary text.
629            let mut tool_json = tools.as_ref().map(serde_json::to_value).transpose()?;
630            let collision_source = format!(
631                "{messages_for_template}{tool_json:?}{:?}{}",
632                req.chat_template_args(),
633                tmpl.source()
634            );
635            while collision_source.contains(&placeholder) {
636                placeholder.push('_');
637            }
638            shield_harmony_literals(&mut messages_for_template, &placeholder, &mut literals);
639            if let Some(value) = &mut tool_json {
640                shield_harmony_literals(value, &placeholder, &mut literals);
641                tools = Some(Value::from_serialize(value));
642            }
643        }
644
645        let ctx = context! {
646            messages => messages_for_template,
647            tools => tools,
648            bos_token => self.config.bos_tok(),
649            eos_token => self.config.eos_tok(),
650            unk_token => self.config.unk_tok(),
651            add_generation_prompt => add_generation_prompt,
652            ..mixins
653        };
654
655        // Merge any additional args into the context last so they take precedence
656        let ctx = if let Some(args) = req.chat_template_args() {
657            let extra = Value::from_serialize(args);
658            context! { ..ctx, ..extra }
659        } else {
660            ctx
661        };
662
663        let rendered = tmpl.render(&ctx)?;
664        if literals.is_empty() {
665            return Ok(crate::RenderedPrompt::text(rendered));
666        }
667        let mut segments = Vec::new();
668        let mut remaining = rendered.as_str();
669        while let Some(start) = remaining.find(&placeholder) {
670            segments.push(crate::RenderedSegment::new(&remaining[..start], true));
671            let after = &remaining[start + placeholder.len()..];
672            let (index, suffix) = after
673                .split_once('_')
674                .ok_or_else(|| anyhow::anyhow!("damaged Harmony literal placeholder"))?;
675            let index: usize = index.parse()?;
676            // TODO: Preserve the template's escaping/filter transformations when
677            // restoring marker-shaped input containing quotes or newlines.
678            segments.push(crate::RenderedSegment::new(
679                literals
680                    .get(index)
681                    .ok_or_else(|| anyhow::anyhow!("unknown Harmony literal placeholder"))?,
682                false,
683            ));
684            remaining = suffix;
685        }
686        segments.push(crate::RenderedSegment::new(remaining, true));
687        Ok(crate::RenderedPrompt::segmented(segments))
688    }
689}
690
691// ASCII placeholders remain unchanged by both direct interpolation and tojson,
692// so JSON quoting/escaping still belongs to the model's original chat template.
693fn shield_harmony_literals(
694    value: &mut serde_json::Value,
695    prefix: &str,
696    literals: &mut Vec<String>,
697) {
698    match value {
699        serde_json::Value::String(text) => {
700            let mut protected = String::new();
701            let mut remaining = text.as_str();
702            while let Some(start) = remaining.find("<|") {
703                let Some(end) = remaining[start + 2..].find("|>") else {
704                    break;
705                };
706                let end = start + 2 + end + 2;
707                protected.push_str(&remaining[..start]);
708                protected.push_str(&format!("{prefix}{}_", literals.len()));
709                literals.push(remaining[start..end].to_string());
710                remaining = &remaining[end..];
711            }
712            if remaining.len() != text.len() {
713                protected.push_str(remaining);
714                *text = protected;
715            }
716        }
717        serde_json::Value::Array(values) => {
718            for value in values {
719                shield_harmony_literals(value, prefix, literals);
720            }
721        }
722        serde_json::Value::Object(values) => {
723            for value in values.values_mut() {
724                shield_harmony_literals(value, prefix, literals);
725            }
726        }
727        _ => {}
728    }
729}
730
731impl OAIPromptFormatter for HfTokenizerConfigJsonFormatter {
732    fn supports_native_tools(&self, request: &dyn OAIChatLikeRequest) -> bool {
733        // Match render's tool exclusion and variant choice before declaring support.
734        let exclude = self.exclude_tools_when_tool_choice_none
735            && request.tool_choice().as_ref().and_then(Value::as_str) == Some("none");
736        let has_tools = !exclude
737            && request
738                .tools()
739                .as_ref()
740                .and_then(|tools| tools.len())
741                .is_some_and(|len| len > 0);
742        self.template_handles_native_tools(has_tools)
743    }
744
745    fn supports_add_generation_prompt(&self) -> bool {
746        self.supports_add_generation_prompt
747    }
748
749    fn render(&self, req: &dyn OAIChatLikeRequest) -> Result<String> {
750        Ok(self
751            .render_with_token_policy(req, false)?
752            .as_str()
753            .to_string())
754    }
755
756    fn render_prompt(&self, req: &dyn OAIChatLikeRequest) -> Result<crate::RenderedPrompt> {
757        self.render_with_token_policy(req, true)
758    }
759}
760
761#[cfg(test)]
762mod tests {
763    use super::*;
764
765    use dynamo_protocols::types::ChatCompletionRequestMessage as Msg;
766    // The crate's renderer tests exercise the bare-protocol request type via the
767    // default `OAIChatLikeRequest` impl above; Dynamo's `Nv*` wrapper lives in lib/llm.
768    use dynamo_protocols::types::CreateChatCompletionRequest as NvCreateChatCompletionRequest;
769    use minijinja::{Environment, context};
770
771    // --- adaptive system-message normalization (#11762) --------------------
772
773    use super::super::tokcfg::ChatTemplate as SysChatTemplate;
774    use super::super::{
775        ContextMixins as SysMixins, HfTokenizerConfigJsonFormatter as SysFormatter,
776    };
777
778    fn formatter_for(template: &str) -> SysFormatter {
779        // Dummy tokens: real templates that append eos/bos won't render without them.
780        let ct: SysChatTemplate = serde_json::from_value(json!({
781            "chat_template": template,
782            "bos_token": "<s>",
783            "eos_token": "</s>",
784            "unk_token": "<unk>",
785        }))
786        .unwrap();
787        SysFormatter::new(ct, SysMixins::new(&[])).unwrap()
788    }
789
790    #[test]
791    fn harmony_literal_markers_keep_text_and_token_trust_boundaries() {
792        let formatter = formatter_for(
793            r#"{% for m in messages %}<|start|>{{ m.role }}<|message|>{{ m.content }}<|end|>{% endfor %}<|start|>assistant"#,
794        );
795        let request: NvCreateChatCompletionRequest = serde_json::from_value(json!({
796            "model":"gpt-oss", "messages":[{"role":"user","content":"literal <|channel|>analysis<|message|>x<|call|> __DYNAMO_HARMONY_LITERAL_0_"}]
797        })).unwrap();
798        let prompt = formatter.render_prompt(&request).unwrap();
799        assert_eq!(prompt.as_str(), formatter.render(&request).unwrap());
800        let ordinary: Vec<_> = prompt
801            .segments()
802            .unwrap()
803            .iter()
804            .filter(|segment| !segment.allow_special)
805            .map(|segment| segment.text.as_str())
806            .collect();
807        assert_eq!(ordinary, ["<|channel|>", "<|message|>", "<|call|>"]);
808        assert!(prompt.segments().unwrap()[0].allow_special);
809        assert!(prompt.segments().unwrap().last().unwrap().allow_special);
810    }
811
812    fn formatter_for_templates(default: &str, tool_use: &str) -> SysFormatter {
813        let ct: SysChatTemplate = serde_json::from_value(json!({
814            "chat_template": [
815                {"default": default},
816                {"tool_use": tool_use},
817            ],
818            "bos_token": "<s>",
819            "eos_token": "</s>",
820            "unk_token": "<unk>",
821        }))
822        .unwrap();
823        SysFormatter::new(ct, SysMixins::new(&[])).unwrap()
824    }
825
826    fn try_formatter_for(template: &str) -> Option<SysFormatter> {
827        let ct: SysChatTemplate = serde_json::from_value(json!({
828            "chat_template": template,
829            "bos_token": "<s>",
830            "eos_token": "</s>",
831            "unk_token": "<unk>",
832        }))
833        .ok()?;
834        SysFormatter::new(ct, SysMixins::new(&[])).ok()
835    }
836
837    fn render_shape(f: &SysFormatter, messages: serde_json::Value) -> Result<String> {
838        let req: NvCreateChatCompletionRequest =
839            serde_json::from_value(json!({ "model": "test", "messages": messages })).unwrap();
840        f.render(&req)
841    }
842
843    fn render_shape_with_tools(f: &SysFormatter, messages: serde_json::Value) -> Result<String> {
844        let req: NvCreateChatCompletionRequest = serde_json::from_value(json!({
845            "model": "test",
846            "messages": messages,
847            "tools": [{
848                "type": "function",
849                "function": {"name": "noop", "parameters": {}}
850            }]
851        }))
852        .unwrap();
853        f.render(&req)
854    }
855
856    struct RawMessagesRequest(Value);
857
858    impl OAIChatLikeRequest for RawMessagesRequest {
859        fn model(&self) -> String {
860            "test".to_string()
861        }
862
863        fn messages(&self) -> Value {
864            self.0.clone()
865        }
866
867        fn should_add_generation_prompt(&self) -> bool {
868            true
869        }
870    }
871
872    fn render_raw_shape(f: &SysFormatter, messages: serde_json::Value) -> Result<String> {
873        f.render(&RawMessagesRequest(Value::from_serialize(&messages)))
874    }
875
876    #[test]
877    fn content_normalization_preserves_unchanged_values() {
878        let messages = json!([
879            {"role": "user", "content": "  中文 <special>\n", "name": "user"},
880            {"role": "assistant", "content": null},
881            {"role": "user", "content": []},
882            {"role": "assistant", "tool_calls": []}
883        ]);
884        assert_eq!(
885            may_be_fix_msg_content(messages.clone(), false, Some("")),
886            messages
887        );
888    }
889
890    const PERMISSIVE_TMPL: &str = concat!(
891        "{%- for m in messages -%}",
892        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
893        "{%- endfor -%}"
894    );
895
896    #[test]
897    fn jinja_templates_reject_message_level_tools() {
898        let f = formatter_for(PERMISSIVE_TMPL);
899        let error = render_shape(
900            &f,
901            json!([
902                {"role": "system", "tools": [{"name": "lookup", "parameters": {"type": "object"}}]},
903                {"role": "user", "content": "hi"}
904            ]),
905        )
906        .unwrap_err();
907        assert!(matches!(
908            error.downcast_ref::<crate::PromptRenderError>(),
909            Some(crate::PromptRenderError::InvalidRequest(message))
910                if message.contains("message-level `tools`")
911        ));
912
913        let error = render_raw_shape(
914            &f,
915            json!([{
916                "role": "user",
917                "content": "hi",
918                "tools": [{"name": "lookup", "parameters": {"type": "object"}}]
919            }]),
920        )
921        .unwrap_err();
922        assert!(matches!(
923            error.downcast_ref::<crate::PromptRenderError>(),
924            Some(crate::PromptRenderError::InvalidRequest(message))
925                if message.contains("message-level `tools`")
926        ));
927
928        let rendered = render_shape(
929            &f,
930            json!([
931                {"role": "system", "content": "You are helpful.", "tools": []},
932                {"role": "user", "content": "hi"}
933            ]),
934        )
935        .unwrap();
936        assert!(rendered.contains("<|im_start|>system\nYou are helpful.<|im_end|>"));
937    }
938
939    #[test]
940    fn jinja_templates_reject_unsupported_partial_assistant() {
941        let f = formatter_for(PERMISSIVE_TMPL);
942        let error = render_shape(
943            &f,
944            json!([
945                {"role": "user", "content": "Continue"},
946                {"role": "assistant", "content": "prefix", "partial": true}
947            ]),
948        )
949        .unwrap_err();
950        assert!(matches!(
951            error.downcast_ref::<crate::PromptRenderError>(),
952            Some(crate::PromptRenderError::InvalidRequest(message))
953                if message.contains("`partial: true` is not supported")
954        ));
955
956        let rendered = render_shape(
957            &f,
958            json!([{"role": "assistant", "content": "ordinary", "partial": false}]),
959        )
960        .unwrap();
961        assert!(rendered.contains("ordinary"));
962    }
963    // Rejects a non-leading system (Qwen3.5 shape); accepts consecutive users.
964    const STRICT_LEADING_TMPL: &str = concat!(
965        "{%- for m in messages -%}",
966        "{%- if m.role == 'system' and not loop.first -%}",
967        "{{ raise_exception('System message must be at the beginning.') }}",
968        "{%- endif -%}",
969        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
970        "{%- endfor -%}"
971    );
972    // Rejects consecutive user turns only; accepts a non-leading system.
973    const ALTERNATION_TMPL: &str = concat!(
974        "{%- set ns = namespace(prev='') -%}",
975        "{%- for m in messages -%}",
976        "{%- if m.role == 'user' and ns.prev == 'user' -%}",
977        "{{ raise_exception('Conversation roles must alternate.') }}",
978        "{%- endif -%}",
979        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
980        "{%- set ns.prev = m.role -%}",
981        "{%- endfor -%}"
982    );
983    // Rejects both restrictions (Gemma-3 / Mistral shape).
984    const STRICT_BOTH_TMPL: &str = concat!(
985        "{%- set ns = namespace(prev='') -%}",
986        "{%- for m in messages -%}",
987        "{%- if m.role == 'system' and not loop.first -%}",
988        "{{ raise_exception('System message must be at the beginning.') }}",
989        "{%- endif -%}",
990        "{%- if m.role == 'user' and ns.prev == 'user' -%}",
991        "{{ raise_exception('Conversation roles must alternate.') }}",
992        "{%- endif -%}",
993        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
994        "{%- set ns.prev = m.role -%}",
995        "{%- endfor -%}"
996    );
997    // Mirrors templates that only enforce role constraints when a particular
998    // tools shape is present.
999    const DEFAULT_NONE_GATED_TMPL: &str = concat!(
1000        "{%- set strict = tools is not none -%}",
1001        "{%- for m in messages -%}",
1002        "{%- if strict and m.role == 'system' and not loop.first -%}",
1003        "{{ raise_exception('System message must be at the beginning.') }}",
1004        "{%- endif -%}",
1005        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
1006        "{%- endfor -%}"
1007    );
1008    const TOOL_NONEMPTY_GATED_TMPL: &str = concat!(
1009        "{%- set strict = tools|length > 0 -%}",
1010        "{%- for m in messages -%}",
1011        "{%- if strict and m.role == 'system' and not loop.first -%}",
1012        "{{ raise_exception('System message must be at the beginning.') }}",
1013        "{%- endif -%}",
1014        "<|im_start|>{{ m.role }}\n{{ m.content }}<|im_end|>\n",
1015        "{%- endfor -%}"
1016    );
1017    // Ignores string content and only renders text parts from content arrays.
1018    const STRICT_ARRAY_TMPL: &str = concat!(
1019        "{%- for m in messages -%}",
1020        "{%- if m.role == 'system' and not loop.first -%}",
1021        "{{ raise_exception('System message must be at the beginning.') }}",
1022        "{%- endif -%}",
1023        "<|im_start|>{{ m.role }}\n",
1024        "{%- if m.content is not string -%}",
1025        "{%- for part in m.content -%}{{ part.text }}{%- endfor -%}",
1026        "{%- endif -%}",
1027        "<|im_end|>\n",
1028        "{%- endfor -%}"
1029    );
1030
1031    // Claude Code first-turn shape: top-level system + a mid-array system.
1032    fn claude_shape() -> serde_json::Value {
1033        json!([
1034            {"role": "system", "content": "You are Claude Code."},
1035            {"role": "user", "content": "hello"},
1036            {"role": "system", "content": "mid-conversation reminder"},
1037        ])
1038    }
1039
1040    fn all_restrictions() -> SystemNormalization {
1041        SystemNormalization {
1042            demote_nonleading_system: true,
1043            coalesce_consecutive_users: true,
1044        }
1045    }
1046
1047    #[test]
1048    fn permissive_template_is_not_flagged_and_renders_untouched() {
1049        let f = formatter_for(PERMISSIVE_TMPL);
1050        assert!(!f.default_system_normalization.is_required());
1051        assert!(!f.tool_use_system_normalization.is_required());
1052        let out = render_shape(&f, claude_shape()).unwrap();
1053        assert!(out.contains("<|im_start|>system\nmid-conversation reminder<|im_end|>"));
1054    }
1055
1056    #[test]
1057    fn strict_leading_template_demotes_mid_system_but_keeps_user_turns_apart() {
1058        let f = formatter_for(STRICT_LEADING_TMPL);
1059        assert!(f.default_system_normalization.demote_nonleading_system);
1060        // The template accepts consecutive users, so demotion must not merge them.
1061        assert!(!f.default_system_normalization.coalesce_consecutive_users);
1062
1063        // This shape returned a 500 before the probe existed.
1064        let out = render_shape(&f, claude_shape()).unwrap();
1065        assert_eq!(out.matches("<|im_start|>system").count(), 1);
1066        assert!(out.contains("<|im_start|>user\nhello<|im_end|>"));
1067        assert!(out.contains("<|im_start|>user\nmid-conversation reminder<|im_end|>"));
1068    }
1069
1070    #[test]
1071    fn alternation_template_coalesces_users_but_keeps_mid_system() {
1072        let f = formatter_for(ALTERNATION_TMPL);
1073        assert!(f.default_system_normalization.coalesce_consecutive_users);
1074        // The template accepts a non-leading system, so it stays a system turn.
1075        assert!(!f.default_system_normalization.demote_nonleading_system);
1076
1077        let out = render_shape(&f, claude_shape()).unwrap();
1078        assert!(out.contains("<|im_start|>system\nmid-conversation reminder<|im_end|>"));
1079
1080        let out = render_shape(
1081            &f,
1082            json!([
1083                {"role": "system", "content": "s"},
1084                {"role": "user", "content": "hello"},
1085                {"role": "user", "content": "again"},
1086            ]),
1087        )
1088        .unwrap();
1089        assert_eq!(out.matches("<|im_start|>user").count(), 1);
1090        assert!(out.contains("<|im_start|>user\nhello\n\nagain<|im_end|>"));
1091    }
1092
1093    #[test]
1094    fn strict_both_template_demotes_then_coalesces() {
1095        let f = formatter_for(STRICT_BOTH_TMPL);
1096        assert!(f.default_system_normalization.demote_nonleading_system);
1097        assert!(f.default_system_normalization.coalesce_consecutive_users);
1098
1099        let out = render_shape(&f, claude_shape()).unwrap();
1100        assert_eq!(out.matches("<|im_start|>system").count(), 1);
1101        assert!(out.contains("<|im_start|>user\nhello\n\nmid-conversation reminder<|im_end|>"));
1102    }
1103
1104    #[test]
1105    fn system_normalization_flag_is_selected_per_template() {
1106        let f = formatter_for_templates(PERMISSIVE_TMPL, STRICT_LEADING_TMPL);
1107        assert!(!f.default_system_normalization.is_required());
1108        assert!(f.tool_use_system_normalization.is_required());
1109
1110        let no_tools = render_shape(&f, claude_shape()).unwrap();
1111        assert!(no_tools.contains("<|im_start|>system\nmid-conversation reminder<|im_end|>"));
1112        let with_tools = render_shape_with_tools(&f, claude_shape()).unwrap();
1113        assert_eq!(with_tools.matches("<|im_start|>system").count(), 1);
1114        assert!(with_tools.contains("<|im_start|>user\nmid-conversation reminder<|im_end|>"));
1115
1116        let f = formatter_for_templates(STRICT_LEADING_TMPL, PERMISSIVE_TMPL);
1117        assert!(f.default_system_normalization.is_required());
1118        assert!(!f.tool_use_system_normalization.is_required());
1119        let with_tools = render_shape_with_tools(&f, claude_shape()).unwrap();
1120        assert!(with_tools.contains("<|im_start|>system\nmid-conversation reminder<|im_end|>"));
1121    }
1122
1123    #[test]
1124    fn system_normalization_probe_uses_runtime_tools_shape() {
1125        let f = formatter_for_templates(DEFAULT_NONE_GATED_TMPL, TOOL_NONEMPTY_GATED_TMPL);
1126        assert!(!f.default_system_normalization.is_required());
1127        assert!(f.tool_use_system_normalization.is_required());
1128
1129        let no_tools = render_shape(&f, claude_shape()).unwrap();
1130        assert!(no_tools.contains("<|im_start|>system\nmid-conversation reminder<|im_end|>"));
1131
1132        let with_tools = render_shape_with_tools(&f, claude_shape()).unwrap();
1133        assert_eq!(with_tools.matches("<|im_start|>system").count(), 1);
1134        assert!(with_tools.contains("<|im_start|>user\nmid-conversation reminder<|im_end|>"));
1135    }
1136
1137    #[test]
1138    fn system_normalization_precedes_required_content_array_conversion() {
1139        let f = formatter_for(STRICT_ARRAY_TMPL);
1140        assert!(f.requires_content_arrays);
1141        assert!(f.default_system_normalization.demote_nonleading_system);
1142
1143        let out = render_shape(
1144            &f,
1145            json!([
1146                {"role": "system", "content": "A"},
1147                {"role": "system", "content": "B"},
1148                {"role": "user", "content": "hello"},
1149            ]),
1150        )
1151        .unwrap();
1152        assert!(out.contains("A\n\nB"));
1153    }
1154
1155    #[test]
1156    fn normalize_preserves_multimodal_user_content_and_fields() {
1157        let mut m = json!([
1158            {
1159                "role": "user",
1160                "name": "kept",
1161                "content": [
1162                    {"type": "text", "text": "look"},
1163                    {"type": "image"},
1164                ],
1165            },
1166            {"role": "system", "content": "remember"},
1167        ]);
1168        normalize_system_messages(&mut m, all_restrictions());
1169        assert_eq!(
1170            m,
1171            json!([{
1172                "role": "user",
1173                "name": "kept",
1174                "content": [
1175                    {"type": "text", "text": "look"},
1176                    {"type": "image"},
1177                    {"type": "text", "text": "remember"},
1178                ],
1179            }])
1180        );
1181    }
1182
1183    /// The mirror of the case above: the parts belong to the turn being merged
1184    /// away, not the one being merged into.
1185    #[test]
1186    fn coalesce_preserves_multimodal_content_of_the_merged_turn() {
1187        let mut m = json!([
1188            {"role": "user", "content": "look"},
1189            {"role": "user", "content": [
1190                {"type": "text", "text": "at this"},
1191                {"type": "image_url", "image_url": {"url": "http://img"}},
1192            ]},
1193        ]);
1194        normalize_system_messages(&mut m, all_restrictions());
1195        assert_eq!(
1196            m,
1197            json!([{
1198                "role": "user",
1199                "content": [
1200                    {"type": "text", "text": "look"},
1201                    {"type": "text", "text": "at this"},
1202                    {"type": "image_url", "image_url": {"url": "http://img"}},
1203                ],
1204            }])
1205        );
1206    }
1207
1208    #[test]
1209    fn normalize_merges_leading_run_and_coalesces() {
1210        let mut m = json!([
1211            {"role": "system", "content": "A"},
1212            {"role": "system", "content": "B"},
1213            {"role": "user", "content": "hi"},
1214            {"role": "system", "content": "reminder"},
1215        ]);
1216        normalize_system_messages(&mut m, all_restrictions());
1217        assert_eq!(
1218            m,
1219            json!([
1220                {"role": "system", "content": "A\n\nB"},
1221                {"role": "user", "content": "hi\n\nreminder"},
1222            ])
1223        );
1224    }
1225
1226    /// Each restriction drives only its own rewrite, so a template is never
1227    /// reshaped for a rule it does not enforce.
1228    #[test]
1229    fn each_restriction_applies_only_its_own_rewrite() {
1230        let shape = json!([
1231            {"role": "system", "content": "A"},
1232            {"role": "system", "content": "B"},
1233            {"role": "user", "content": "hi"},
1234            {"role": "system", "content": "reminder"},
1235        ]);
1236
1237        let mut demote_only = shape.clone();
1238        normalize_system_messages(
1239            &mut demote_only,
1240            SystemNormalization {
1241                demote_nonleading_system: true,
1242                coalesce_consecutive_users: false,
1243            },
1244        );
1245        assert_eq!(
1246            demote_only,
1247            json!([
1248                {"role": "system", "content": "A\n\nB"},
1249                {"role": "user", "content": "hi"},
1250                {"role": "user", "content": "reminder"},
1251            ])
1252        );
1253
1254        let mut coalesce_only = shape.clone();
1255        normalize_system_messages(
1256            &mut coalesce_only,
1257            SystemNormalization {
1258                demote_nonleading_system: false,
1259                coalesce_consecutive_users: true,
1260            },
1261        );
1262        assert_eq!(coalesce_only, shape);
1263    }
1264
1265    #[test]
1266    fn normalize_preserves_array_system_content() {
1267        let mut m = json!([
1268            {"role": "user", "content": "hi"},
1269            {"role": "system", "content": [{"type": "text", "text": "one"},
1270                                           {"type": "text", "text": "two"}]},
1271        ]);
1272        normalize_system_messages(&mut m, all_restrictions());
1273        assert_eq!(
1274            m,
1275            json!([{"role": "user", "content": [
1276                {"type": "text", "text": "hi"},
1277                {"type": "text", "text": "one"},
1278                {"type": "text", "text": "two"},
1279            ]}])
1280        );
1281    }
1282
1283    /// Renders every agent-client shape through every template in a corpus of
1284    /// real models. A failure means the probe missed a strict template, or the
1285    /// normalization it triggered was not enough to satisfy one.
1286    ///
1287    /// TEMPLATE_CORPUS points at a dir of `<name>.jinja` files + `manifest.json`
1288    /// mapping each to `{model}` (see experiments/system-probe):
1289    ///   TEMPLATE_CORPUS=... cargo test -p dynamo-renderer \
1290    ///     adaptive_system_corpus_audit -- --ignored --nocapture
1291    #[test]
1292    #[ignore]
1293    fn adaptive_system_corpus_audit() {
1294        let dir =
1295            std::env::var("TEMPLATE_CORPUS").expect("set TEMPLATE_CORPUS to the templates dir");
1296        let manifest: serde_json::Value =
1297            serde_json::from_str(&std::fs::read_to_string(format!("{dir}/manifest.json")).unwrap())
1298                .unwrap();
1299
1300        // Tool-call shapes are omitted: they need a per-family `tools` payload,
1301        // and the hermetic tests already cover them.
1302        let sys = |c: &str| json!({"role": "system", "content": c});
1303        let usr = |c: &str| json!({"role": "user", "content": c});
1304        let asst = |c: &str| json!({"role": "assistant", "content": c});
1305        let shapes: Vec<(&str, serde_json::Value)> = vec![
1306            ("turn1", json!([sys("s"), usr("u"), sys("mid")])),
1307            (
1308                "multiturn",
1309                json!([sys("s"), usr("u"), sys("mid"), asst("a"), usr("u2")]),
1310            ),
1311            (
1312                "mid_after_asst",
1313                json!([sys("s"), usr("u"), asst("a"), sys("mid"), usr("u2")]),
1314            ),
1315            ("double_leading", json!([sys("s0"), sys("s1"), usr("u")])),
1316            ("consec_user", json!([sys("s"), usr("u0"), usr("u1")])),
1317            (
1318                "tail_reminder",
1319                json!([
1320                    sys("s"),
1321                    usr("u"),
1322                    asst("a"),
1323                    usr("u2"),
1324                    sys("mid"),
1325                    usr("u3")
1326                ]),
1327            ),
1328            ("leading_only_baseline", json!([sys("s"), usr("u")])),
1329        ];
1330
1331        let mut total = 0usize;
1332        let mut flagged = 0usize;
1333        let mut demote_only = 0usize;
1334        let mut coalesce = 0usize;
1335        let mut failures: Vec<String> = Vec::new();
1336        for (file, meta) in manifest.as_object().unwrap() {
1337            let tmpl = std::fs::read_to_string(format!("{dir}/{file}.jinja")).unwrap();
1338            let model = meta["model"].as_str().unwrap_or(file);
1339            // Some real templates use custom tags minijinja can't compile,
1340            // which says nothing about system normalization.
1341            let f = match try_formatter_for(&tmpl) {
1342                Some(f) => f,
1343                None => {
1344                    eprintln!("[skip-compile] {model}");
1345                    continue;
1346                }
1347            };
1348            // Vision templates need image inputs, so they can't render text-only
1349            // here. The probe's baseline guard leaves them unflagged anyway.
1350            if render_shape(&f, json!([sys("s"), usr("u")])).is_err() {
1351                eprintln!("[skip-baseline] {model}");
1352                continue;
1353            }
1354            total += 1;
1355            let rules = f.default_system_normalization;
1356            let flag = rules.is_required();
1357            if flag {
1358                flagged += 1;
1359            }
1360            if rules.demote_nonleading_system {
1361                demote_only += usize::from(!rules.coalesce_consecutive_users);
1362            }
1363            if rules.coalesce_consecutive_users {
1364                coalesce += 1;
1365            }
1366            for (name, shape) in &shapes {
1367                if render_shape(&f, shape.clone()).is_err() {
1368                    failures.push(format!("{model} | shape={name} | flag={flag}"));
1369                }
1370            }
1371            if flag {
1372                eprintln!(
1373                    "[ok] demote={} coalesce={} {model}",
1374                    rules.demote_nonleading_system, rules.coalesce_consecutive_users
1375                );
1376            }
1377        }
1378        eprintln!(
1379            "\naudited {total} templates ({flagged} flagged: {demote_only} demote-only, \
1380             {coalesce} coalescing); {} shape failures",
1381            failures.len()
1382        );
1383        for f in &failures {
1384            eprintln!("  FAIL {f}");
1385        }
1386        assert!(
1387            failures.is_empty(),
1388            "{} template/shape combinations did not render (probe insufficient or normalization insufficient)",
1389            failures.len()
1390        );
1391    }
1392
1393    /// End-to-end guard for the minijinja stack-overflow fix, exercised through
1394    /// Dynamo's real chat-template render path. A template that accumulates
1395    /// messages via `ns.items = ns.items + [m]` and then takes `|length`
1396    /// previously overflowed the native stack for long conversations (~1500+
1397    /// turns on a worker thread), core-dumping the frontend. Runs on a 2 MiB
1398    /// stack — the size of a Dynamo tokio worker thread — so a regression aborts
1399    /// deterministically instead of depending on the platform default.
1400    #[test]
1401    fn test_render_long_conversation_does_not_overflow_stack() {
1402        let handle = std::thread::Builder::new()
1403            .stack_size(2 * 1024 * 1024)
1404            .spawn(|| {
1405                let template_string = concat!(
1406                    "{%- set ns = namespace(items=[]) -%}",
1407                    "{%- for m in messages -%}",
1408                    "{%- set ns.items = ns.items + [m] -%}",
1409                    "{%- endfor -%}",
1410                    "COUNT={{ ns.items | length }}"
1411                );
1412                let chat_template: ChatTemplate =
1413                    serde_json::from_value(serde_json::json!({ "chat_template": template_string }))
1414                        .unwrap();
1415                let formatter =
1416                    HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[]))
1417                        .unwrap();
1418
1419                let n = 3000;
1420                let messages: Vec<serde_json::Value> = (0..n)
1421                    .map(|i| serde_json::json!({"role": "user", "content": format!("turn {i}")}))
1422                    .collect();
1423                let request: NvCreateChatCompletionRequest =
1424                    serde_json::from_value(serde_json::json!({
1425                        "model": "test",
1426                        "messages": messages,
1427                    }))
1428                    .unwrap();
1429
1430                // The crash path: `|length` -> minijinja `Value::len()`.
1431                let rendered = formatter.render(&request).unwrap();
1432                assert_eq!(rendered.trim(), format!("COUNT={n}"));
1433            })
1434            .unwrap();
1435        handle.join().unwrap();
1436    }
1437
1438    /// Dev utility (ignored by default): dump the prompt Dynamo's renderer
1439    /// produces for a tool-calling chat request, so it can be diffed against
1440    /// vLLM's `openai_harmony` rendering — to see whether the gpt-oss Jinja
1441    /// `chat_template` actually emits the harmony "tool calls go to the
1442    /// commentary channel" guidance + `functions` namespace.
1443    ///
1444    /// Point GPTOSS_CHAT_TEMPLATE at the model's tokenizer_config.json (its
1445    /// `chat_template` field is extracted) OR a raw chat_template.jinja file:
1446    ///   GPTOSS_CHAT_TEMPLATE=/path/openai-gpt-oss-120b/tokenizer_config.json \
1447    ///     cargo test -p dynamo-renderer dump_gptoss_tool_prompt -- --ignored --nocapture
1448    #[test]
1449    #[ignore]
1450    fn dump_gptoss_tool_prompt() {
1451        use super::tokcfg::ChatTemplate;
1452        use super::{ContextMixins, HfTokenizerConfigJsonFormatter};
1453
1454        let path = std::env::var("GPTOSS_CHAT_TEMPLATE").expect(
1455            "set GPTOSS_CHAT_TEMPLATE to the tokenizer_config.json, chat_template.jinja, or model dir path",
1456        );
1457        let input_path = std::path::Path::new(&path);
1458        let file_path = if input_path.is_dir() {
1459            // Prefer tokenizer_config.json from model dir if provided
1460            input_path.join("tokenizer_config.json")
1461        } else {
1462            input_path.to_path_buf()
1463        };
1464        let raw = std::fs::read_to_string(&file_path).expect("read chat template file");
1465        // Resolve the actual Jinja template. gpt-oss ships its chat template in a
1466        // separate `chat_template.jinja` file, NOT inside tokenizer_config.json,
1467        // so:
1468        //   * if the file is JSON with a `chat_template` field, use it;
1469        //   * otherwise, if a sibling `chat_template.jinja` exists, read that;
1470        //   * otherwise treat the file itself as the template.
1471        let template_string: String = match serde_json::from_str::<serde_json::Value>(&raw) {
1472            Ok(v) if v.get("chat_template").is_some() => v["chat_template"]
1473                .as_str()
1474                .expect("chat_template field must be a string")
1475                .to_string(),
1476            _ => {
1477                let sibling = std::path::Path::new(&path)
1478                    .parent()
1479                    .map(|d| d.join("chat_template.jinja"));
1480                match sibling {
1481                    Some(p) if p.exists() => {
1482                        eprintln!(
1483                            "[info] {path} had no chat_template field; using {}",
1484                            p.display()
1485                        );
1486                        std::fs::read_to_string(&p).expect("read sibling chat_template.jinja")
1487                    }
1488                    _ => raw,
1489                }
1490            }
1491        };
1492
1493        // Guard against silently echoing a non-template (e.g. a tokenizer_config.json
1494        // with no chat_template and no sibling .jinja).
1495        assert!(
1496            template_string.contains("{%") || template_string.contains("{{"),
1497            "resolved template has no Jinja tags — GPTOSS_CHAT_TEMPLATE ({path}) is probably \
1498             tokenizer_config.json with no chat_template field and no sibling chat_template.jinja. \
1499             Point it at the chat_template.jinja file."
1500        );
1501
1502        let chat_template: ChatTemplate =
1503            serde_json::from_value(serde_json::json!({ "chat_template": template_string }))
1504                .unwrap();
1505
1506        let formatter =
1507            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
1508
1509        // Declare tools — the tool-channel guidance only renders when tools are present.
1510        let request: NvCreateChatCompletionRequest = serde_json::from_str(
1511            r#"{
1512              "model": "openai/gpt-oss-120b",
1513              "messages": [{"role":"user","content":"Search the repo for the string \"countHook\"."}],
1514              "tools": [
1515                {"type":"function","function":{"name":"grep","description":"search files","parameters":{"type":"object","properties":{"pattern":{"type":"string"},"path":{"type":"string"}},"required":["pattern"]}}},
1516                {"type":"function","function":{"name":"read","description":"read a file","parameters":{"type":"object","properties":{"filePath":{"type":"string"}},"required":["filePath"]}}}
1517              ]
1518            }"#,
1519        )
1520        .unwrap();
1521
1522        let rendered = formatter.render(&request).unwrap();
1523        eprintln!("================ RENDERED gpt-oss PROMPT (tools declared) ================");
1524        eprintln!("{rendered}");
1525        eprintln!("================ END RENDERED PROMPT ================");
1526        eprintln!("[diagnostics] does the rendered prompt contain…");
1527        for needle in [
1528            "commentary",
1529            "Calls to these tools",
1530            "functions",
1531            "# Tools",
1532            "<|channel|>",
1533            "constrain",
1534            "analysis",
1535        ] {
1536            eprintln!(
1537                "  {:>22}: {}",
1538                format!("{needle:?}"),
1539                rendered.contains(needle)
1540            );
1541        }
1542    }
1543
1544    /// Tests that media URL content parts are converted to empty placeholders.
1545    #[test]
1546    fn test_convert_media_url_to_placeholder_single_type() {
1547        let mut content_array = vec![
1548            serde_json::json!({"type": "text", "text": "Check this image:"}),
1549            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}),
1550            serde_json::json!({"type": "text", "text": "What do you see?"}),
1551        ];
1552
1553        let conversions = &[("image_url", "image")];
1554        convert_media_url_to_placeholder(&mut content_array, conversions);
1555
1556        assert_eq!(content_array.len(), 3);
1557        // Text parts should be unchanged
1558        assert_eq!(content_array[0]["type"], "text");
1559        assert_eq!(content_array[0]["text"], "Check this image:");
1560        // image_url should be converted to image placeholder
1561        assert_eq!(content_array[1]["type"], "image");
1562        assert!(content_array[1].get("image_url").is_none());
1563        // Text parts should be unchanged
1564        assert_eq!(content_array[2]["type"], "text");
1565        assert_eq!(content_array[2]["text"], "What do you see?");
1566    }
1567
1568    /// Tests that multiple media URL parts of the same type are all converted.
1569    #[test]
1570    fn test_convert_media_url_to_placeholder_multiple_same_type() {
1571        let mut content_array = vec![
1572            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}}),
1573            serde_json::json!({"type": "text", "text": "vs"}),
1574            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}}),
1575        ];
1576
1577        let conversions = &[("image_url", "image")];
1578        convert_media_url_to_placeholder(&mut content_array, conversions);
1579
1580        assert_eq!(content_array.len(), 3);
1581        assert_eq!(content_array[0]["type"], "image");
1582        assert_eq!(content_array[1]["type"], "text");
1583        assert_eq!(content_array[2]["type"], "image");
1584    }
1585
1586    /// Tests that only specified media types are converted, others preserved.
1587    #[test]
1588    fn test_convert_media_url_to_placeholder_selective_conversion() {
1589        let mut content_array = vec![
1590            serde_json::json!({"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}}),
1591            serde_json::json!({"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}),
1592            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}),
1593        ];
1594
1595        // Only convert image_url
1596        let conversions = &[("image_url", "image")];
1597        convert_media_url_to_placeholder(&mut content_array, conversions);
1598
1599        assert_eq!(content_array.len(), 3);
1600        // audio_url and video_url should be preserved as-is
1601        assert_eq!(content_array[0]["type"], "audio_url");
1602        assert!(content_array[0].get("audio_url").is_some());
1603        assert_eq!(content_array[1]["type"], "video_url");
1604        assert!(content_array[1].get("video_url").is_some());
1605        // Only image_url should be converted
1606        assert_eq!(content_array[2]["type"], "image");
1607        assert!(content_array[2].get("image_url").is_none());
1608    }
1609
1610    /// Tests converting multiple different media types at once.
1611    #[test]
1612    fn test_convert_media_url_to_placeholder_multiple_types() {
1613        let mut content_array = vec![
1614            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}),
1615            serde_json::json!({"type": "text", "text": "and listen to"}),
1616            serde_json::json!({"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}}),
1617            serde_json::json!({"type": "text", "text": "and watch"}),
1618            serde_json::json!({"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}),
1619        ];
1620
1621        // Convert all media types
1622        let conversions = &[
1623            ("image_url", "image"),
1624            ("audio_url", "audio"),
1625            ("video_url", "video"),
1626        ];
1627        convert_media_url_to_placeholder(&mut content_array, conversions);
1628
1629        assert_eq!(content_array.len(), 5);
1630        assert_eq!(content_array[0]["type"], "image");
1631        assert!(content_array[0].get("image_url").is_none());
1632        assert_eq!(content_array[1]["type"], "text");
1633        assert_eq!(content_array[2]["type"], "audio");
1634        assert!(content_array[2].get("audio_url").is_none());
1635        assert_eq!(content_array[3]["type"], "text");
1636        assert_eq!(content_array[4]["type"], "video");
1637        assert!(content_array[4].get("video_url").is_none());
1638    }
1639
1640    /// Tests that empty conversions list preserves all content.
1641    #[test]
1642    fn test_convert_media_url_to_placeholder_no_conversions() {
1643        let mut content_array = vec![
1644            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}),
1645            serde_json::json!({"type": "text", "text": "hello"}),
1646        ];
1647
1648        let conversions: &[(&str, &str)] = &[];
1649        convert_media_url_to_placeholder(&mut content_array, conversions);
1650
1651        assert_eq!(content_array.len(), 2);
1652        // Everything should be preserved as-is
1653        assert_eq!(content_array[0]["type"], "image_url");
1654        assert!(content_array[0].get("image_url").is_some());
1655        assert_eq!(content_array[1]["type"], "text");
1656    }
1657
1658    /// Tests that DEFAULT_MEDIA_TYPE_CONVERSIONS only converts image_url,
1659    /// and preserves other media types like video_url and audio_url.
1660    #[test]
1661    fn test_default_media_type_conversions_only_converts_image_url() {
1662        let mut content_array = vec![
1663            serde_json::json!({"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}),
1664            serde_json::json!({"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}),
1665            serde_json::json!({"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}}),
1666            serde_json::json!({"type": "text", "text": "hello"}),
1667        ];
1668
1669        // Use the actual DEFAULT_MEDIA_TYPE_CONVERSIONS
1670        convert_media_url_to_placeholder(&mut content_array, DEFAULT_MEDIA_TYPE_CONVERSIONS);
1671
1672        assert_eq!(content_array.len(), 4);
1673
1674        // image_url SHOULD be converted to image (it's in the default map)
1675        assert_eq!(content_array[0]["type"], "image");
1676        assert!(content_array[0].get("image_url").is_none());
1677
1678        // video_url should NOT be converted (not in the default map)
1679        assert_eq!(content_array[1]["type"], "video");
1680        assert!(content_array[1].get("video_url").is_none());
1681
1682        // audio_url should NOT be converted (not in the default map)
1683        assert_eq!(content_array[2]["type"], "audio");
1684        assert!(content_array[2].get("audio_url").is_none());
1685
1686        // text should be unchanged
1687        assert_eq!(content_array[3]["type"], "text");
1688        assert_eq!(content_array[3]["text"], "hello");
1689    }
1690
1691    #[test]
1692    fn test_may_be_fix_tool_schema_missing_type_and_properties() {
1693        let json_str = r#"{
1694            "model": "gpt-4o",
1695            "messages": [],
1696            "tools": [
1697                {
1698                    "type": "function",
1699                    "function": {
1700                        "name": "get_weather",
1701                        "description": "Get the current weather in a given location",
1702                        "parameters": {},
1703                        "strict": null
1704                    }
1705                }
1706            ]
1707        }"#;
1708
1709        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1710        let tools = serde_json::to_value(request.tools()).unwrap();
1711
1712        assert!(tools[0]["function"]["parameters"]["type"] == "object");
1713        assert!(
1714            tools[0]["function"]["parameters"]["properties"]
1715                == serde_json::Value::Object(Default::default())
1716        );
1717    }
1718
1719    #[test]
1720    fn test_may_be_fix_tool_schema_missing_type() {
1721        let json_str = r#"{
1722            "model": "gpt-4o",
1723            "messages": [],
1724            "tools": [
1725                {
1726                    "type": "function",
1727                    "function": {
1728                        "name": "get_weather",
1729                        "description": "Get the current weather in a given location",
1730                        "parameters": {
1731                            "properties": {
1732                                "location": {
1733                                    "type": "string",
1734                                    "description": "City and state, e.g., 'San Francisco, CA'"
1735                                }
1736                            }
1737                        },
1738                        "strict": null
1739                    }
1740                }
1741            ]
1742        }"#;
1743        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1744
1745        let tools = serde_json::to_value(request.tools()).unwrap();
1746
1747        assert_eq!(tools[0]["function"]["parameters"]["type"], "object");
1748
1749        let mut expected_properties = serde_json::Map::new();
1750        let mut location = serde_json::Map::new();
1751        location.insert(
1752            "type".to_string(),
1753            serde_json::Value::String("string".to_string()),
1754        );
1755        location.insert(
1756            "description".to_string(),
1757            serde_json::Value::String("City and state, e.g., 'San Francisco, CA'".to_string()),
1758        );
1759        expected_properties.insert("location".to_string(), serde_json::Value::Object(location));
1760
1761        assert_eq!(
1762            tools[0]["function"]["parameters"]["properties"],
1763            serde_json::Value::Object(expected_properties)
1764        );
1765    }
1766
1767    #[test]
1768    fn test_may_be_fix_tool_schema_missing_properties() {
1769        let json_str = r#"{
1770            "model": "gpt-4o",
1771            "messages": [],
1772            "tools": [
1773                {
1774                    "type": "function",
1775                    "function": {
1776                        "name": "get_weather",
1777                        "description": "Get the current weather in a given location",
1778                        "parameters": {"type": "object"},
1779                        "strict": null
1780                    }
1781                }
1782            ]
1783        }"#;
1784
1785        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1786        let tools = serde_json::to_value(request.tools()).unwrap();
1787
1788        assert_eq!(
1789            tools[0]["function"]["parameters"]["properties"],
1790            serde_json::Value::Object(Default::default())
1791        );
1792        assert_eq!(tools[0]["function"]["parameters"]["type"], "object");
1793    }
1794
1795    #[test]
1796    fn test_may_be_fix_tool_schema_missing_description() {
1797        // `description` is optional in the OpenAI tool schema, but some chat
1798        // templates (e.g. gpt-oss harmony) concatenate it unconditionally and
1799        // fail on an `undefined`/null value. It must be backfilled to "".
1800        let json_str = r#"{
1801            "model": "gpt-4o",
1802            "messages": [],
1803            "tools": [
1804                {
1805                    "type": "function",
1806                    "function": {
1807                        "name": "noop",
1808                        "parameters": {
1809                            "type": "object",
1810                            "properties": { "x": { "type": "string" } },
1811                            "required": ["x"],
1812                            "additionalProperties": false
1813                        },
1814                        "strict": null
1815                    }
1816                }
1817            ]
1818        }"#;
1819
1820        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1821        let tools = serde_json::to_value(request.tools()).unwrap();
1822
1823        assert_eq!(
1824            tools[0]["function"]["description"],
1825            serde_json::Value::String(String::new())
1826        );
1827    }
1828
1829    #[test]
1830    fn test_may_be_fix_tool_schema_null_description() {
1831        // An explicit null `description` must also be normalized to "".
1832        let json_str = r#"{
1833            "model": "gpt-4o",
1834            "messages": [],
1835            "tools": [
1836                {
1837                    "type": "function",
1838                    "function": {
1839                        "name": "noop",
1840                        "description": null,
1841                        "parameters": {"type": "object", "properties": {}},
1842                        "strict": null
1843                    }
1844                }
1845            ]
1846        }"#;
1847
1848        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1849        let tools = serde_json::to_value(request.tools()).unwrap();
1850
1851        assert_eq!(
1852            tools[0]["function"]["description"],
1853            serde_json::Value::String(String::new())
1854        );
1855    }
1856
1857    #[test]
1858    fn test_may_be_fix_tool_schema_preserves_description() {
1859        // A present `description` must be left untouched.
1860        let json_str = r#"{
1861            "model": "gpt-4o",
1862            "messages": [],
1863            "tools": [
1864                {
1865                    "type": "function",
1866                    "function": {
1867                        "name": "get_weather",
1868                        "description": "Get the current weather in a given location",
1869                        "parameters": {"type": "object", "properties": {}},
1870                        "strict": null
1871                    }
1872                }
1873            ]
1874        }"#;
1875
1876        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1877        let tools = serde_json::to_value(request.tools()).unwrap();
1878
1879        assert_eq!(
1880            tools[0]["function"]["description"],
1881            "Get the current weather in a given location"
1882        );
1883    }
1884
1885    /// Tests that content arrays (containing only text parts) are correctly concatenated.
1886    #[test]
1887    fn test_may_be_fix_msg_content_user_multipart() {
1888        let json_str = r#"{
1889            "model": "gpt-4o",
1890            "messages": [
1891                {
1892                    "role": "user",
1893                    "content": [
1894                        {"type": "text", "text": "part 1"},
1895                        {"type": "text", "text": "part 2"}
1896                    ]
1897                }
1898            ]
1899        }"#;
1900
1901        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1902        let messages_raw = serde_json::to_value(request.messages()).unwrap();
1903
1904        // Test array → string normalization (preserve_arrays=false for standard templates)
1905        let messages =
1906            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
1907
1908        // Verify: text-only array is concatenated into a single string
1909        assert_eq!(
1910            messages[0]["content"],
1911            serde_json::Value::String("part 1\npart 2".to_string())
1912        );
1913    }
1914
1915    /// Tests that the function correctly handles a conversation
1916    /// with multiple roles and mixed message types:
1917    #[test]
1918    fn test_may_be_fix_msg_content_mixed_messages() {
1919        let json_str = r#"{
1920            "model": "gpt-4o",
1921            "messages": [
1922                {
1923                    "role": "system",
1924                    "content": "You are a helpful assistant"
1925                },
1926                {
1927                    "role": "user",
1928                    "content": [
1929                        {"type": "text", "text": "Hello"},
1930                        {"type": "text", "text": "World"}
1931                    ]
1932                },
1933                {
1934                    "role": "assistant",
1935                    "content": "Hi there!"
1936                },
1937                {
1938                    "role": "user",
1939                    "content": [
1940                        {"type": "text", "text": "Another"},
1941                        {"type": "text", "text": "multi-part"},
1942                        {"type": "text", "text": "message"}
1943                    ]
1944                }
1945            ]
1946        }"#;
1947
1948        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1949        let messages_raw = serde_json::to_value(request.messages()).unwrap();
1950
1951        // Test array → string normalization (preserve_arrays=false for standard templates)
1952        let messages =
1953            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
1954
1955        // Verify: System message with string content remains unchanged
1956        assert_eq!(
1957            messages[0]["content"],
1958            serde_json::Value::String("You are a helpful assistant".to_string())
1959        );
1960
1961        // Verify: User message with text-only array is concatenated
1962        assert_eq!(
1963            messages[1]["content"],
1964            serde_json::Value::String("Hello\nWorld".to_string())
1965        );
1966
1967        // Verify: Assistant message with string content remains unchanged
1968        assert_eq!(
1969            messages[2]["content"],
1970            serde_json::Value::String("Hi there!".to_string())
1971        );
1972
1973        // Verify: Second user message with text-only array is concatenated
1974        assert_eq!(
1975            messages[3]["content"],
1976            serde_json::Value::String("Another\nmulti-part\nmessage".to_string())
1977        );
1978    }
1979
1980    /// Tests that empty content arrays remain unchanged.
1981    #[test]
1982    fn test_may_be_fix_msg_content_empty_array() {
1983        let json_str = r#"{
1984            "model": "gpt-4o",
1985            "messages": [
1986                {
1987                    "role": "user",
1988                    "content": []
1989                }
1990            ]
1991        }"#;
1992
1993        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
1994        let messages_raw = serde_json::to_value(request.messages()).unwrap();
1995
1996        // Empty arrays should be preserved regardless of preserve_arrays setting
1997        let messages =
1998            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
1999
2000        // Verify: Empty arrays are preserved as-is
2001        assert!(messages[0]["content"].is_array());
2002        assert_eq!(messages[0]["content"].as_array().unwrap().len(), 0);
2003    }
2004
2005    /// Empty arrays must stay as `[]` even when a flatten-time placeholder
2006    /// template is provided (Phi-3 / LLaVA-1.5 path). Without the
2007    /// `!content_array.is_empty()` guard in `may_be_fix_msg_content`,
2008    /// an empty content array would silently flatten to `""` and the
2009    /// chat template would render an entirely empty message instead of
2010    /// failing or being preserved.
2011    #[test]
2012    fn test_may_be_fix_msg_content_empty_array_with_placeholder_template() {
2013        let json_str = r#"{
2014            "model": "phi-3-vision",
2015            "messages": [
2016                {
2017                    "role": "user",
2018                    "content": []
2019                }
2020            ]
2021        }"#;
2022
2023        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2024        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2025
2026        // preserve_arrays=false + image_placeholder_template=Some(...) is
2027        // the combination that previously flattened `[]` to `""`.
2028        let messages = serde_json::to_value(may_be_fix_msg_content(
2029            messages_raw,
2030            false,
2031            Some("<|image_{n}|>"),
2032        ))
2033        .unwrap();
2034
2035        assert!(
2036            messages[0]["content"].is_array(),
2037            "empty array should be preserved as `[]`, not flattened to `\"\"`"
2038        );
2039        assert_eq!(messages[0]["content"].as_array().unwrap().len(), 0);
2040    }
2041
2042    /// Tests that messages with simple string content remain unchanged.
2043    #[test]
2044    fn test_may_be_fix_msg_content_single_text() {
2045        let json_str = r#"{
2046            "model": "gpt-4o",
2047            "messages": [
2048                {
2049                    "role": "user",
2050                    "content": "Simple text message"
2051                }
2052            ]
2053        }"#;
2054
2055        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2056        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2057
2058        // Test with preserve_arrays=false (standard templates)
2059        let messages =
2060            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2061
2062        // Verify: String content is not modified
2063        assert_eq!(
2064            messages[0]["content"],
2065            serde_json::Value::String("Simple text message".to_string())
2066        );
2067    }
2068
2069    /// Tests that content arrays with mixed types (text + non-text) remain as arrays,
2070    /// and that image_url is converted to image placeholder.
2071    #[test]
2072    fn test_may_be_fix_msg_content_mixed_types() {
2073        let json_str = r#"{
2074            "model": "gpt-4o",
2075            "messages": [
2076                {
2077                    "role": "user",
2078                    "content": [
2079                        {"type": "text", "text": "Check this image:"},
2080                        {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}},
2081                        {"type": "text", "text": "What do you see?"}
2082                    ]
2083                }
2084            ]
2085        }"#;
2086
2087        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2088        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2089
2090        // Mixed content should be preserved regardless of preserve_arrays setting
2091        let messages =
2092            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2093
2094        // Verify: Mixed content types are preserved as array for template handling
2095        // image_url should be converted to image placeholder
2096        assert!(messages[0]["content"].is_array());
2097        let content_array = messages[0]["content"].as_array().unwrap();
2098        assert_eq!(content_array.len(), 3);
2099        assert_eq!(content_array[0]["type"], "text");
2100        assert_eq!(content_array[1]["type"], "image");
2101        assert!(content_array[1].get("image_url").is_none());
2102        assert_eq!(content_array[2]["type"], "text");
2103    }
2104
2105    /// Mixed text+image array with a string-content template and an
2106    /// `<|image_{n}|>`-style placeholder (Phi-3-vision) — content must be
2107    /// flattened to a single string with numbered image markers in place of
2108    /// the image parts. The previous default (leave as array) would crash
2109    /// the Phi-3 template's `'+' message.content` concatenation.
2110    #[test]
2111    fn test_may_be_fix_msg_content_flattens_phi3_style() {
2112        let json_str = r#"{
2113            "model": "phi-3-vision",
2114            "messages": [
2115                {
2116                    "role": "user",
2117                    "content": [
2118                        {"type": "text", "text": "First "},
2119                        {"type": "image_url", "image_url": {"url": "https://example.com/a.jpg"}},
2120                        {"type": "text", "text": " then "},
2121                        {"type": "image_url", "image_url": {"url": "https://example.com/b.jpg"}},
2122                        {"type": "text", "text": "?"}
2123                    ]
2124                }
2125            ]
2126        }"#;
2127        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2128        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2129
2130        let messages = serde_json::to_value(may_be_fix_msg_content(
2131            messages_raw,
2132            false,
2133            Some("<|image_{n}|>"),
2134        ))
2135        .unwrap();
2136
2137        let content = messages[0]["content"].as_str().expect("content flattened");
2138        assert_eq!(content, "First <|image_1|> then <|image_2|>?");
2139    }
2140
2141    /// Same flattening with a static placeholder (LLaVA-1.5 `<image>`).
2142    #[test]
2143    fn test_may_be_fix_msg_content_flattens_llava_style() {
2144        let json_str = r#"{
2145            "model": "llava-1.5-7b-hf",
2146            "messages": [
2147                {
2148                    "role": "user",
2149                    "content": [
2150                        {"type": "text", "text": "Describe: "},
2151                        {"type": "image_url", "image_url": {"url": "https://example.com/x.jpg"}}
2152                    ]
2153                }
2154            ]
2155        }"#;
2156        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2157        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2158
2159        let messages =
2160            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, Some("<image>")))
2161                .unwrap();
2162
2163        let content = messages[0]["content"].as_str().expect("content flattened");
2164        assert_eq!(content, "Describe: <image>");
2165    }
2166
2167    /// Nemotron-Parse pass-through path: a mixed text+image array with an
2168    /// empty placeholder (`""`) flattens to the text parts only — the image
2169    /// contributes nothing because the vision encoder consumes it out-of-band.
2170    /// Without this, `{{ message.content }}` would JSON-serialize the array
2171    /// into the prompt (the gibberish failure mode).
2172    #[test]
2173    fn test_may_be_fix_msg_content_flattens_empty_placeholder() {
2174        let json_str = r#"{
2175            "model": "nvidia/NVIDIA-Nemotron-Parse-v1.2",
2176            "messages": [
2177                {
2178                    "role": "user",
2179                    "content": [
2180                        {"type": "text", "text": "</s><s><predict_bbox><predict_classes><output_markdown><predict_no_text_in_pic>"},
2181                        {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA"}}
2182                    ]
2183                }
2184            ]
2185        }"#;
2186        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2187        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2188
2189        let messages =
2190            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, Some(""))).unwrap();
2191
2192        let content = messages[0]["content"].as_str().expect("content flattened");
2193        assert_eq!(
2194            content,
2195            "</s><s><predict_bbox><predict_classes><output_markdown><predict_no_text_in_pic>"
2196        );
2197    }
2198
2199    /// End-to-end render through the Nemotron-Parse pass-through chat template:
2200    /// a text+image chat request must produce exactly the control-token prompt,
2201    /// with the image dropped from the rendered text. The renderer is agnostic
2202    /// to the control tokens themselves (they are just the text part, passed
2203    /// through verbatim), so both `predict_no_text_in_pic` and
2204    /// `predict_text_in_pic` prompts round-trip identically.
2205    #[test]
2206    fn test_render_nemotron_parse_passthrough() {
2207        use super::super::tokcfg::ChatTemplate;
2208        use super::{ContextMixins, HfTokenizerConfigJsonFormatter};
2209
2210        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
2211            "chat_template": "{% for message in messages %}{{ message['content'] }}{% endfor %}"
2212        }))
2213        .unwrap();
2214        let formatter =
2215            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
2216
2217        for prompt in [
2218            "</s><s><predict_bbox><predict_classes><output_markdown><predict_no_text_in_pic>",
2219            "</s><s><predict_bbox><predict_classes><output_markdown><predict_text_in_pic>",
2220        ] {
2221            let request: NvCreateChatCompletionRequest =
2222                serde_json::from_value(serde_json::json!({
2223                    "model": "nvidia/NVIDIA-Nemotron-Parse-v1.2",
2224                    "messages": [{
2225                        "role": "user",
2226                        "content": [
2227                            {"type": "text", "text": prompt},
2228                            {"type": "image_url", "image_url": {"url": "data:image/png;base64,AAAA"}}
2229                        ]
2230                    }]
2231                }))
2232                .unwrap();
2233
2234            let rendered = formatter.render(&request).unwrap();
2235            assert_eq!(
2236                rendered, prompt,
2237                "rendered prompt must be the control tokens only, with no JSON-serialized image array"
2238            );
2239        }
2240    }
2241
2242    /// Tests that content arrays containing only non-text types remain as arrays,
2243    /// and image_url types are converted to image placeholders.
2244    #[test]
2245    fn test_may_be_fix_msg_content_non_text_only() {
2246        let json_str = r#"{
2247            "model": "gpt-4o",
2248            "messages": [
2249                {
2250                    "role": "user",
2251                    "content": [
2252                        {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
2253                        {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}}
2254                    ]
2255                }
2256            ]
2257        }"#;
2258
2259        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2260        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2261
2262        // Non-text arrays should be preserved regardless of preserve_arrays setting
2263        let messages =
2264            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2265
2266        // Verify: Non-text content arrays are preserved, with image_url converted to image
2267        assert!(messages[0]["content"].is_array());
2268        let content_array = messages[0]["content"].as_array().unwrap();
2269        assert_eq!(content_array.len(), 2);
2270        assert_eq!(content_array[0]["type"], "image");
2271        assert_eq!(content_array[1]["type"], "image");
2272    }
2273
2274    #[test]
2275    fn test_none_tools_safe_for_all_templates() {
2276        use super::tokcfg::ChatTemplate;
2277        use super::{ContextMixins, HfTokenizerConfigJsonFormatter};
2278
2279        // Due to minijinja limitations the expressions in conditional statements may not be short-circuited
2280        // This checks that our custom length filter works to avoid errors in this scenario
2281        // length should return 0 if tools is None and 'if tools is iterable and tools | length > 0' should evaluate to false
2282        let length_template = r#"
2283{%- if tools is iterable and tools | length > 0 %}
2284Tools available: {{ tools | length }}
2285{%- else %}
2286No tools
2287{%- endif %}
2288"#;
2289
2290        // Because we return None for tools when there are no tools this scenario should also be evaluate to false
2291        // This is similar to the default jinja template behavior seen with llama models which check if tools is not none to activate tool mode
2292        let no_tool_template = r#"
2293{%- if tools is not none %}
2294TOOL MODE
2295{%- else %}
2296NORMAL MODE
2297{%- endif %}
2298"#;
2299
2300        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
2301            "chat_template": [
2302                {"safe_length": length_template},
2303                {"no_tool": no_tool_template}
2304            ]
2305        }))
2306        .unwrap();
2307
2308        let formatter =
2309            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
2310
2311        let ctx = context! { tools => Option::<Value>::None };
2312
2313        let result1 = formatter
2314            .env
2315            .get_template("safe_length")
2316            .unwrap()
2317            .render(&ctx);
2318        println!("Safe length template with no tools => None: {:?}", result1);
2319        assert!(
2320            result1.is_ok(),
2321            "Jinja template with and conditional and length filter should handle None: {:?}",
2322            result1
2323        );
2324        assert!(
2325            result1.unwrap().contains("No tools"),
2326            "Should show 'No tools'"
2327        );
2328
2329        let result2 = formatter.env.get_template("no_tool").unwrap().render(&ctx);
2330        println!("Default template with no tools => None: {:?}", result2);
2331        assert!(
2332            result2.is_ok(),
2333            "Jinja template with if tools is not none conditional should handle None: {:?}",
2334            result2
2335        );
2336        assert!(result2.unwrap().contains("NORMAL MODE"));
2337    }
2338
2339    /// Tests mixed content type scenarios.
2340    #[test]
2341    fn test_may_be_fix_msg_content_multiple_content_types() {
2342        // Scenario 1: Multiple different content types (text + image + audio)
2343        let json_str = r#"{
2344            "model": "gpt-4o",
2345            "messages": [
2346                {
2347                    "role": "user",
2348                    "content": [
2349                        {"type": "text", "text": "Listen to this:"},
2350                        {"type": "audio_url", "audio_url": {"url": "https://example.com/audio.mp3"}},
2351                        {"type": "text", "text": "And look at:"},
2352                        {"type": "image_url", "image_url": {"url": "https://example.com/img.jpg"}},
2353                        {"type": "text", "text": "What do you think?"}
2354                    ]
2355                }
2356            ]
2357        }"#;
2358
2359        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2360        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2361        let messages =
2362            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2363
2364        // Mixed types should preserve array structure, with image_url converted to image
2365        assert!(messages[0]["content"].is_array());
2366        let content_array = messages[0]["content"].as_array().unwrap();
2367        assert_eq!(content_array.len(), 5);
2368        assert_eq!(content_array[0]["type"], "text");
2369        assert_eq!(content_array[1]["type"], "audio");
2370        assert_eq!(content_array[2]["type"], "text");
2371        assert_eq!(content_array[3]["type"], "image");
2372        assert_eq!(content_array[4]["type"], "text");
2373
2374        // Scenario 2: Unknown/future content types mixed with text
2375        let json_str = r#"{
2376            "model": "gpt-4o",
2377            "messages": [
2378                {
2379                    "role": "user",
2380                    "content": [
2381                        {"type": "text", "text": "Check this:"},
2382                        {"type": "video_url", "video_url": {"url": "https://example.com/vid.mp4"}},
2383                        {"type": "text", "text": "Interesting?"}
2384                    ]
2385                }
2386            ]
2387        }"#;
2388
2389        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2390        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2391        let messages =
2392            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2393
2394        // Unknown types mixed with text should preserve array
2395        assert!(messages[0]["content"].is_array());
2396        assert_eq!(messages[0]["content"].as_array().unwrap().len(), 3);
2397    }
2398
2399    #[test]
2400    fn test_normalize_tool_arguments_tojson() {
2401        let tmpl = r#"{{ messages[0].tool_calls[0].function.arguments | tojson }}"#;
2402
2403        // Message with tool_calls containing JSON string arguments
2404        let mut messages = serde_json::Value::Array(vec![serde_json::json!({
2405            "role": "assistant",
2406            "tool_calls": [{
2407                "type": "function",
2408                "function": {
2409                    "name": "get_current_weather",
2410                    "arguments": "{\"format\":\"celsius\",\"location\":\"San Francisco, CA\"}"
2411                }
2412            }]
2413        })]);
2414
2415        normalize_tool_calls_arguments_in_messages(&mut messages);
2416
2417        let mut env = Environment::new();
2418        env.add_filter("tojson", super::super::tokcfg::tojson);
2419        env.add_template("t", tmpl).unwrap();
2420        let out = env
2421            .get_template("t")
2422            .unwrap()
2423            .render(context! { messages => messages.as_array().unwrap() })
2424            .unwrap();
2425
2426        // Should produce clean JSON without double-encoding, with Python
2427        // json.dumps separators (what transformers' tojson emits).
2428        assert_eq!(
2429            out,
2430            r#"{"format": "celsius", "location": "San Francisco, CA"}"#
2431        );
2432    }
2433
2434    #[test]
2435    fn test_normalize_tool_arguments_items_loop() {
2436        let tmpl = r#"{% for k, v in messages[0].tool_calls[0].function.arguments|items %}{{k}}={{v}};{% endfor %}"#;
2437
2438        let mut messages = serde_json::Value::Array(vec![serde_json::json!({
2439            "role": "assistant",
2440            "tool_calls": [{
2441                "type": "function",
2442                "function": {
2443                    "name": "f",
2444                    "arguments": "{\"a\":1,\"b\":\"x\"}"
2445                }
2446            }]
2447        })]);
2448
2449        normalize_tool_calls_arguments_in_messages(&mut messages);
2450
2451        let mut env = Environment::new();
2452        env.add_template("t", tmpl).unwrap();
2453        let out = env
2454            .get_template("t")
2455            .unwrap()
2456            .render(context! { messages => messages.as_array().unwrap() })
2457            .unwrap();
2458
2459        assert!(out == "a=1;b=x;" || out == "b=x;a=1;");
2460    }
2461
2462    #[test]
2463    fn test_normalize_tool_arguments_legacy_function_call() {
2464        // Test deprecated function_call format (OpenAI compat)
2465        let mut messages = serde_json::Value::Array(vec![serde_json::json!({
2466            "role": "assistant",
2467            "function_call": {
2468                "name": "get_weather",
2469                "arguments": "{\"location\":\"NYC\"}"
2470            }
2471        })]);
2472
2473        normalize_function_call_arguments_in_messages(&mut messages);
2474
2475        assert_eq!(
2476            messages[0]["function_call"]["arguments"],
2477            serde_json::json!({"location": "NYC"})
2478        );
2479    }
2480
2481    #[test]
2482    fn test_normalize_tool_arguments_malformed_json_passthrough() {
2483        // Malformed JSON should be left as a string
2484        let mut messages = serde_json::Value::Array(vec![serde_json::json!({
2485            "role": "assistant",
2486            "tool_calls": [{
2487                "type": "function",
2488                "function": {
2489                    "name": "f",
2490                    "arguments": "not valid json at all"
2491                }
2492            }]
2493        })]);
2494
2495        normalize_tool_calls_arguments_in_messages(&mut messages);
2496
2497        assert_eq!(
2498            messages[0]["tool_calls"][0]["function"]["arguments"],
2499            serde_json::Value::String("not valid json at all".to_string())
2500        );
2501    }
2502
2503    #[test]
2504    fn test_normalize_tool_arguments_with_multimodal_content() {
2505        let json_str = r#"{
2506            "model": "gpt-4o",
2507            "messages": [
2508                {
2509                    "role": "user",
2510                    "content": [
2511                        {"type": "text", "text": "Check this:"},
2512                        {"type": "video_url", "video_url": {"url": "https://example.com/vid.mp4"}},
2513                        {"type": "text", "text": "Interesting?"}
2514                    ]
2515                },
2516                {
2517                    "role": "assistant",
2518                    "tool_calls": [{
2519                        "id": "call_123",
2520                        "type": "function",
2521                        "function": {
2522                            "name": "analyze_video",
2523                            "arguments": "{\"url\":\"https://example.com/vid.mp4\",\"format\":\"mp4\"}"
2524                        }
2525                    }]
2526                }
2527            ]
2528        }"#;
2529
2530        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2531        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2532
2533        // Apply content normalization with preserve_arrays=false (standard templates)
2534        let mut messages =
2535            serde_json::to_value(may_be_fix_msg_content(messages_raw, false, None)).unwrap();
2536
2537        normalize_tool_calls_arguments_in_messages(&mut messages);
2538
2539        // Multimodal content preserved as array (mixed types not flattened)
2540        assert!(messages[0]["content"].is_array());
2541        assert_eq!(messages[0]["content"].as_array().unwrap().len(), 3);
2542
2543        // Tool arguments deserialized to object
2544        assert!(messages[1]["tool_calls"][0]["function"]["arguments"].is_object());
2545        assert_eq!(
2546            messages[1]["tool_calls"][0]["function"]["arguments"]["url"],
2547            "https://example.com/vid.mp4"
2548        );
2549    }
2550
2551    /// MiniMax-M3's `to_xml` prints history argument floats with `{{ val }}`;
2552    /// HF (vLLM/SGLang `json.loads` the arguments) renders Python `str(float)`.
2553    #[test]
2554    fn test_minimax_m3_history_tool_call_float_arguments_match_hf() {
2555        let template = r#"{%- set ns_token = ']<]minimax[>[' -%}
2556{%- macro to_xml(val, ns) -%}
2557{%- if val is mapping -%}
2558{%- for k, v in val.items() if v is not none -%}
2559{{ ns }}<{{ k }}>{{ to_xml(v, ns) }}{{ ns }}</{{ k }}>
2560{%- endfor -%}
2561{%- elif val is iterable and val is not string -%}
2562{%- for item in val -%}
2563{{ ns }}<item>{{ to_xml(item, ns) }}{{ ns }}</item>
2564{%- endfor -%}
2565{%- elif val is none -%}
2566{%- elif val is boolean -%}
2567{{ val | tojson }}
2568{%- else -%}
2569{{ val }}
2570{%- endif -%}
2571{%- endmacro -%}
2572{%- for message in messages if message.tool_calls -%}
2573{%- for tool_call in message.tool_calls -%}
2574{%- if tool_call.function -%}
2575{%- set tool_call = tool_call.function -%}
2576{%- endif -%}
2577{{- ns_token + '<invoke name="' + tool_call.name + '">' }}
2578{%- set _args = tool_call.arguments -%}
2579{%- for k, v in _args.items() if v is not none %}
2580{{- ns_token + '<' + k + '>' -}}
2581{{- to_xml(v, ns_token) -}}
2582{{- ns_token + '</' + k + '>' }}
2583{%- endfor -%}
2584{{- ns_token + '</invoke>' ~ '\n' }}
2585{%- endfor -%}
2586{%- endfor -%}"#;
2587        let rendered = render_shape(
2588            &formatter_for(template),
2589            json!([
2590                {"role": "user", "content": "u"},
2591                {"role": "assistant", "content": "", "tool_calls": [{
2592                    "id": "c1",
2593                    "type": "function",
2594                    "function": {
2595                        "name": "fit",
2596                        "arguments": r#"{"tolerance": 1e-07, "bounds": [0.00001, 1e16]}"#
2597                    }
2598                }]}
2599            ]),
2600        )
2601        .unwrap();
2602        assert_eq!(
2603            rendered,
2604            "]<]minimax[>[<invoke name=\"fit\">]<]minimax[>[<tolerance>1e-07]<]minimax[>[</tolerance>]<]minimax[>[<bounds>]<]minimax[>[<item>1e-05]<]minimax[>[</item>]<]minimax[>[<item>1e+16]<]minimax[>[</item>]<]minimax[>[</bounds>]<]minimax[>[</invoke>\n"
2605        );
2606    }
2607
2608    /// Qwen3-Coder prints scalar history arguments with `| string`, which HF
2609    /// renders as Python `str(float)`.
2610    #[test]
2611    fn test_qwen3_coder_history_tool_call_float_arguments_match_hf() {
2612        let template = r#"{%- for message in messages if message.tool_calls -%}
2613{%- for tool_call in message.tool_calls %}
2614    {%- if tool_call.function is defined %}
2615        {%- set tool_call = tool_call.function %}
2616    {%- endif %}
2617    {%- for args_name, args_value in tool_call.arguments|items %}
2618        {{- '<parameter=' + args_name + '>\n' }}
2619        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
2620        {{- args_value }}
2621        {{- '\n</parameter>\n' }}
2622    {%- endfor %}
2623{%- endfor %}
2624{%- endfor %}"#;
2625        let rendered = render_shape(
2626            &formatter_for(template),
2627            json!([
2628                {"role": "user", "content": "u"},
2629                {"role": "assistant", "content": "", "tool_calls": [{
2630                    "id": "c1",
2631                    "type": "function",
2632                    "function": {
2633                        "name": "fit",
2634                        "arguments": r#"{"tolerance": 1e-07, "bounds": [0.00001, 1e16]}"#
2635                    }
2636                }]}
2637            ]),
2638        )
2639        .unwrap();
2640        assert_eq!(
2641            rendered,
2642            "<parameter=tolerance>\n1e-07\n</parameter>\n<parameter=bounds>\n[1e-05, 1e+16]\n</parameter>\n"
2643        );
2644    }
2645
2646    /// Tests string → array normalization for multimodal templates
2647    #[test]
2648    fn test_may_be_fix_msg_content_string_to_array() {
2649        let json_str = r#"{
2650            "model": "gpt-4o",
2651            "messages": [
2652                {
2653                    "role": "user",
2654                    "content": "Hello, how are you?"
2655                }
2656            ]
2657        }"#;
2658
2659        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2660        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2661
2662        // Test with preserve_arrays=true (multimodal templates)
2663        let messages =
2664            serde_json::to_value(may_be_fix_msg_content(messages_raw, true, None)).unwrap();
2665
2666        // Verify: String is converted to array format
2667        assert!(messages[0]["content"].is_array());
2668        let content_array = messages[0]["content"].as_array().unwrap();
2669        assert_eq!(content_array.len(), 1);
2670        assert_eq!(content_array[0]["type"], "text");
2671        assert_eq!(content_array[0]["text"], "Hello, how are you?");
2672    }
2673
2674    /// Tests that arrays are preserved when preserve_arrays=true
2675    #[test]
2676    fn test_may_be_fix_msg_content_array_preserved_with_multimodal() {
2677        let json_str = r#"{
2678            "model": "gpt-4o",
2679            "messages": [
2680                {
2681                    "role": "user",
2682                    "content": [
2683                        {"type": "text", "text": "part 1"},
2684                        {"type": "text", "text": "part 2"}
2685                    ]
2686                }
2687            ]
2688        }"#;
2689
2690        let request: NvCreateChatCompletionRequest = serde_json::from_str(json_str).unwrap();
2691        let messages_raw = serde_json::to_value(request.messages()).unwrap();
2692
2693        // Test with preserve_arrays=true (multimodal templates)
2694        let messages =
2695            serde_json::to_value(may_be_fix_msg_content(messages_raw, true, None)).unwrap();
2696
2697        // Verify: Array is preserved as-is
2698        assert!(messages[0]["content"].is_array());
2699        let content_array = messages[0]["content"].as_array().unwrap();
2700        assert_eq!(content_array.len(), 2);
2701        assert_eq!(content_array[0]["text"], "part 1");
2702        assert_eq!(content_array[1]["text"], "part 2");
2703    }
2704
2705    fn user() -> Msg {
2706        Msg::User(Default::default())
2707    }
2708    fn tool() -> Msg {
2709        Msg::Tool(Default::default())
2710    }
2711
2712    fn dummy_state(messages: Vec<Msg>) -> NvCreateChatCompletionRequest {
2713        let json = serde_json::json!({
2714            "model": "test-model",
2715            "messages": messages
2716        });
2717        serde_json::from_value(json).unwrap()
2718    }
2719
2720    #[test]
2721    fn add_after_user() {
2722        let s = dummy_state(vec![user()]);
2723        assert!(s.should_add_generation_prompt());
2724    }
2725
2726    #[test]
2727    fn add_after_tool() {
2728        let s = dummy_state(vec![tool()]);
2729        assert!(s.should_add_generation_prompt());
2730    }
2731
2732    #[test]
2733    fn add_when_empty() {
2734        let s = dummy_state(vec![]);
2735        assert!(s.should_add_generation_prompt());
2736    }
2737
2738    /// Helper to build a formatter with a simple tool-aware template.
2739    fn tool_aware_formatter(
2740        exclude_tools_when_tool_choice_none: bool,
2741    ) -> HfTokenizerConfigJsonFormatter {
2742        let template = r#"
2743{%- if tools is iterable and tools | length > 0 %}
2744TOOL_MODE tools={{ tools | length }}
2745{%- else %}
2746NORMAL_MODE
2747{%- endif %}
2748{{ messages[0].content }}"#;
2749
2750        let chat_template: super::tokcfg::ChatTemplate =
2751            serde_json::from_value(serde_json::json!({ "chat_template": template })).unwrap();
2752
2753        HfTokenizerConfigJsonFormatter::with_options(
2754            chat_template,
2755            ContextMixins::new(&[]),
2756            exclude_tools_when_tool_choice_none,
2757        )
2758        .unwrap()
2759    }
2760
2761    fn gemma4_tool_template_for_tests() -> &'static str {
2762        r#"
2763{{ bos_token }}
2764{%- set loop_messages = messages -%}
2765{%- set ns_turn = namespace(last_user_idx=-1) -%}
2766{%- for i in range(loop_messages | length) -%}
2767    {%- if loop_messages[i]['role'] == 'user' -%}
2768        {%- set ns_turn.last_user_idx = i -%}
2769    {%- endif -%}
2770{%- endfor -%}
2771{%- for message in loop_messages -%}
2772    {%- set role = 'model' if message['role'] == 'assistant' else message['role'] -%}
2773    {{- '<|turn>' + role + '\n' }}
2774
2775    {%- if message.get('reasoning') and loop.index0 > ns_turn.last_user_idx and message.get('tool_calls') -%}
2776        {{- '<|channel>thought\n' + message['reasoning'] + '\n<channel|>'}}
2777    {%- endif -%}
2778
2779            {%- if message['tool_calls'] -%}
2780                {%- for tool_call in message['tool_calls'] -%}
2781                    {%- set function = tool_call['function'] -%}
2782                    {{- '<|tool_call>call:' + function['name'] + '{' -}}
2783                    {%- if function['arguments'] is mapping -%}
2784                        {%- set ns_args = namespace(found_first=false) -%}
2785                        {%- for key, value in function['arguments'] | dictsort -%}
2786                            {%- if ns_args.found_first %},{% endif -%}
2787                            {%- set ns_args.found_first = true -%}
2788                            {{- key -}}:{{- value -}}
2789                        {%- endfor -%}
2790                    {%- elif function['arguments'] is string -%}
2791                        {{- function['arguments'] -}}
2792                    {%- endif -%}
2793                    {{- '}<tool_call|>' -}}
2794                {%- endfor -%}
2795            {%- endif -%}
2796
2797            {%- if message['content'] is string -%}
2798                {{- message['content'] -}}
2799            {%- endif -%}
2800    {{- '<turn|>\n' -}}
2801{%- endfor -%}
2802"#
2803    }
2804
2805    fn make_gemma4_tool_formatter_for_tests() -> HfTokenizerConfigJsonFormatter {
2806        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
2807            "chat_template": gemma4_tool_template_for_tests()
2808        }))
2809        .unwrap();
2810        HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap()
2811    }
2812
2813    /// Helper to build a request with tools and optional tool_choice.
2814    fn request_with_tool_choice(tool_choice: &str) -> NvCreateChatCompletionRequest {
2815        serde_json::from_value(serde_json::json!({
2816            "model": "test",
2817            "messages": [{"role": "user", "content": "hello"}],
2818            "tools": [{
2819                "type": "function",
2820                "function": {
2821                    "name": "get_weather",
2822                    "description": "Get weather",
2823                    "parameters": {"type": "object", "properties": {"location": {"type": "string"}}}
2824                }
2825            }],
2826            "tool_choice": tool_choice
2827        }))
2828        .unwrap()
2829    }
2830
2831    #[test]
2832    fn test_exclude_tools_strips_when_tool_choice_none() {
2833        let formatter = tool_aware_formatter(true);
2834        let request = request_with_tool_choice("none");
2835        let result = formatter.render(&request).unwrap();
2836        assert!(
2837            result.contains("NORMAL_MODE"),
2838            "With exclude_tools=true and tool_choice=none, tools should be stripped. Got: {}",
2839            result
2840        );
2841    }
2842
2843    #[test]
2844    fn test_exclude_tools_keeps_when_tool_choice_auto() {
2845        let formatter = tool_aware_formatter(true);
2846        let request = request_with_tool_choice("auto");
2847        let result = formatter.render(&request).unwrap();
2848        assert!(
2849            result.contains("TOOL_MODE"),
2850            "With tool_choice=auto, tools should be included. Got: {}",
2851            result
2852        );
2853    }
2854
2855    #[test]
2856    fn test_no_exclude_tools_keeps_when_tool_choice_none() {
2857        let formatter = tool_aware_formatter(false);
2858        let request = request_with_tool_choice("none");
2859        let result = formatter.render(&request).unwrap();
2860        assert!(
2861            result.contains("TOOL_MODE"),
2862            "With exclude_tools=false and tool_choice=none, tools should NOT be stripped. Got: {}",
2863            result
2864        );
2865    }
2866
2867    #[test]
2868    fn test_inject_reasoning_content_segments_with_tool_calls() {
2869        // Assistant message with reasoning_content segments and tool_calls
2870        let mut messages = serde_json::json!([
2871            {
2872                "role": "user",
2873                "content": "What is sqrt(144) and sqrt(256)?"
2874            },
2875            {
2876                "role": "assistant",
2877                "content": "Let me calculate those.",
2878                "reasoning_content": ["I need to compute sqrt(144)", "Now sqrt(256)", ""],
2879                "tool_calls": [
2880                    {
2881                        "id": "call_0",
2882                        "type": "function",
2883                        "function": {
2884                            "name": "calculator",
2885                            "arguments": "{\"expr\": \"sqrt(144)\"}"
2886                        }
2887                    },
2888                    {
2889                        "id": "call_1",
2890                        "type": "function",
2891                        "function": {
2892                            "name": "calculator",
2893                            "arguments": "{\"expr\": \"sqrt(256)\"}"
2894                        }
2895                    }
2896                ]
2897            }
2898        ]);
2899
2900        inject_reasoning_content_into_messages(&mut messages);
2901
2902        let assistant = &messages[1];
2903
2904        // reasoning_content should be removed
2905        assert!(
2906            assistant.get("reasoning_content").is_none(),
2907            "reasoning_content should be removed after injection"
2908        );
2909
2910        // content should have <think> blocks prepended (empty segment skipped)
2911        let content = assistant["content"].as_str().unwrap();
2912        assert!(
2913            content.starts_with("<think>I need to compute sqrt(144)</think>"),
2914            "content should start with first reasoning segment, got: {}",
2915            content
2916        );
2917        assert!(
2918            content.contains("<think>Now sqrt(256)</think>"),
2919            "content should contain second reasoning segment"
2920        );
2921        // Empty third segment should NOT produce <think></think>
2922        assert!(
2923            !content.contains("<think></think>"),
2924            "empty segments should be skipped"
2925        );
2926        // Original content should be preserved at the end
2927        assert!(
2928            content.ends_with("Let me calculate those."),
2929            "original content should be at the end, got: {}",
2930            content
2931        );
2932
2933        // tool_calls should be untouched
2934        assert!(assistant.get("tool_calls").is_some());
2935        assert_eq!(assistant["tool_calls"].as_array().unwrap().len(), 2);
2936    }
2937
2938    #[test]
2939    fn test_gemma4_template_renders_reasoning_content_segments_around_tool_calls() {
2940        let formatter = make_gemma4_tool_formatter_for_tests();
2941        assert!(
2942            formatter.tool_use_template_handles_reasoning,
2943            "Gemma4 template adaptation should make reasoning_content native"
2944        );
2945
2946        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
2947            "model": "gemma4-test",
2948            "messages": [
2949                {"role": "user", "content": "inspect two things"},
2950                {
2951                    "role": "assistant",
2952                    "content": null,
2953                    "reasoning_content": [
2954                        "Think before the first call.",
2955                        "Think before the second call.",
2956                        "Think after both calls."
2957                    ],
2958                    "tool_calls": [
2959                        {
2960                            "id": "call_0",
2961                            "type": "function",
2962                            "function": {
2963                                "name": "first_tool",
2964                                "arguments": "{\"path\":\".\"}"
2965                            }
2966                        },
2967                        {
2968                            "id": "call_1",
2969                            "type": "function",
2970                            "function": {
2971                                "name": "second_tool",
2972                                "arguments": "{\"path\":\"/tmp\"}"
2973                            }
2974                        }
2975                    ]
2976                }
2977            ]
2978        }))
2979        .unwrap();
2980
2981        let rendered = formatter.render(&request).unwrap();
2982
2983        let expected = concat!(
2984            "<|channel>thought\nThink before the first call.\n<channel|>",
2985            "<|tool_call>call:first_tool{path:.}<tool_call|>",
2986            "<|channel>thought\nThink before the second call.\n<channel|>",
2987            "<|tool_call>call:second_tool{path:/tmp}<tool_call|>",
2988            "<|channel>thought\nThink after both calls.\n<channel|>"
2989        );
2990        assert!(
2991            rendered.contains(expected),
2992            "Gemma4 reasoning segments should stay adjacent to their tool calls, got: {rendered}"
2993        );
2994        assert!(!rendered.contains("<think>"));
2995        assert!(!rendered.contains("reasoning_content"));
2996    }
2997
2998    #[test]
2999    fn test_gemma4_template_renders_reasoning_content_without_tool_calls() {
3000        let formatter = make_gemma4_tool_formatter_for_tests();
3001        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3002            "model": "gemma4-test",
3003            "messages": [
3004                {"role": "user", "content": "answer directly"},
3005                {
3006                    "role": "assistant",
3007                    "content": "Direct answer.",
3008                    "reasoning_content": "Private thought."
3009                }
3010            ]
3011        }))
3012        .unwrap();
3013
3014        let rendered = formatter.render(&request).unwrap();
3015
3016        assert!(
3017            rendered.contains("<|channel>thought\nPrivate thought.\n<channel|>Direct answer."),
3018            "Gemma4 reasoning_content should render in the thought channel, got: {rendered}"
3019        );
3020        assert!(!rendered.contains("<think>"));
3021        assert!(!rendered.contains("reasoning_content"));
3022    }
3023
3024    /// Regression: when a config ships a separate non-tool `default` template
3025    /// (dict form), adapting only the `tool_use` template to read
3026    /// `reasoning_content` must NOT suppress `<think>` injection on the
3027    /// `default` path. A global `any()` flag would flip true off the adapted
3028    /// `tool_use` template and silently drop reasoning on no-tool renders.
3029    #[test]
3030    fn test_reasoning_flag_is_per_template_not_global() {
3031        // Plain default template: renders content, never mentions reasoning_content
3032        // and lacks the Gemma4 fingerprint, so it is left untouched.
3033        const PLAIN_DEFAULT: &str = "{{ bos_token }}{%- for message in messages -%}\
3034            {{ message['role'] }}: {{ message['content'] }}\n{%- endfor -%}";
3035
3036        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
3037            "chat_template": [
3038                {"default": PLAIN_DEFAULT},
3039                {"tool_use": gemma4_tool_template_for_tests()},
3040            ]
3041        }))
3042        .unwrap();
3043        let formatter =
3044            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
3045
3046        // The adapted Gemma4 tool_use template handles reasoning natively; the
3047        // untouched plain default template does not. The flag must reflect that
3048        // per-template split, not a global OR across both.
3049        assert!(
3050            formatter.tool_use_template_handles_reasoning,
3051            "adapted gemma4 tool_use template should handle reasoning natively"
3052        );
3053        assert!(
3054            !formatter.default_template_handles_reasoning,
3055            "plain default template does not reference reasoning_content"
3056        );
3057
3058        // A no-tools request routes to `default`. Reasoning must still be injected
3059        // as a <think> block — not silently dropped by the tool_use template's flag.
3060        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3061            "model": "gemma4-test",
3062            "messages": [
3063                {"role": "user", "content": "answer directly"},
3064                {
3065                    "role": "assistant",
3066                    "content": "Direct answer.",
3067                    "reasoning_content": "Private thought."
3068                }
3069            ]
3070        }))
3071        .unwrap();
3072
3073        let rendered = formatter.render(&request).unwrap();
3074        assert!(
3075            rendered.contains("<think>Private thought.</think>Direct answer."),
3076            "reasoning must be injected on the no-tool default path, got: {rendered}"
3077        );
3078    }
3079
3080    /// An assistant turn with reasoning and two tool calls, then their results.
3081    fn reasoning_tool_call_turn(reasoning: serde_json::Value) -> serde_json::Value {
3082        let call = |id: &str, expr: &str| {
3083            json!({"id": id, "type": "function",
3084                "function": {"name": "calc", "arguments": json!({"expr": expr}).to_string()}})
3085        };
3086        json!([
3087            {"role": "user", "content": "sqrt(144) + sqrt(256)?"},
3088            {"role": "assistant", "content": null, "reasoning_content": reasoning,
3089                "tool_calls": [call("call_0", "sqrt(144)"), call("call_1", "sqrt(256)")]},
3090            {"role": "tool", "tool_call_id": "call_0", "content": "12"},
3091            {"role": "tool", "tool_call_id": "call_1", "content": "16"}
3092        ])
3093    }
3094
3095    /// MiniMax-M2's assistant branch: `reasoning_content` renders only when it
3096    /// `is string`, so the segment array the Responses and Anthropic converters
3097    /// send with tool calls must reach it joined, not as an array.
3098    #[test]
3099    fn test_string_reasoning_template_joins_reasoning_content_segments() {
3100        const MINIMAX_REASONING_TMPL: &str = r#"{%- for message in messages -%}
3101{%- if message.role == 'assistant' -%}
3102{{- ']~b]ai' ~ '\n' -}}
3103{%- set reasoning_content = '' -%}
3104{%- if message.reasoning_content is string -%}
3105{%- set reasoning_content = message.reasoning_content -%}
3106{%- endif -%}
3107{%- if reasoning_content -%}
3108{{- '<think>' ~ '\n' ~ reasoning_content ~ '\n' ~ '</think>' ~ '\n\n' -}}
3109{%- endif -%}
3110{%- for tool_call in message.tool_calls -%}
3111{{- '<invoke name="' ~ tool_call.function.name ~ '">' -}}
3112{%- endfor -%}
3113{{- '[e~[\n' -}}
3114{%- else -%}
3115{{- ']~b]' ~ message.role ~ '\n' ~ message.content ~ '[e~[\n' -}}
3116{%- endif -%}
3117{%- endfor -%}"#;
3118        let f = formatter_for(MINIMAX_REASONING_TMPL);
3119        // HF transformers render of this template with the equivalent string.
3120        let expected = concat!(
3121            "]~b]user\nsqrt(144) + sqrt(256)?[e~[\n",
3122            "]~b]ai\n<think>\nCheck both.\nThen add.\n</think>\n\n",
3123            "<invoke name=\"calc\"><invoke name=\"calc\">[e~[\n",
3124            "]~b]tool\n12[e~[\n]~b]tool\n16[e~[\n",
3125        );
3126        // `default` (no tools) and `tool_use` are probed separately.
3127        for render in [render_shape, render_shape_with_tools] {
3128            for reasoning in [
3129                json!(["Check both.", "Then add.", ""]),
3130                json!("Check both.\nThen add."),
3131            ] {
3132                assert_eq!(
3133                    render(&f, reasoning_tool_call_turn(reasoning)).unwrap(),
3134                    expected
3135                );
3136            }
3137        }
3138    }
3139
3140    #[test]
3141    fn test_inject_reasoning_content_text_variant() {
3142        let mut messages = serde_json::json!([
3143            {
3144                "role": "assistant",
3145                "content": "The answer is 42.",
3146                "reasoning_content": "Let me think about this carefully."
3147            }
3148        ]);
3149
3150        inject_reasoning_content_into_messages(&mut messages);
3151
3152        let assistant = &messages[0];
3153        assert!(assistant.get("reasoning_content").is_none());
3154        let content = assistant["content"].as_str().unwrap();
3155        assert_eq!(
3156            content,
3157            "<think>Let me think about this carefully.</think>The answer is 42."
3158        );
3159    }
3160
3161    #[test]
3162    fn test_inject_reasoning_content_null_content() {
3163        // reasoning_content present but content is null
3164        let mut messages = serde_json::json!([
3165            {
3166                "role": "assistant",
3167                "content": null,
3168                "reasoning_content": "Thinking...",
3169                "tool_calls": [{"id": "call_0", "type": "function", "function": {"name": "f", "arguments": "{}"}}]
3170            }
3171        ]);
3172
3173        inject_reasoning_content_into_messages(&mut messages);
3174
3175        let content = messages[0]["content"].as_str().unwrap();
3176        assert_eq!(content, "<think>Thinking...</think>");
3177        assert!(messages[0].get("reasoning_content").is_none());
3178    }
3179
3180    #[test]
3181    fn test_inject_reasoning_content_skips_non_assistant() {
3182        let mut messages = serde_json::json!([
3183            {
3184                "role": "user",
3185                "content": "hello",
3186                "reasoning_content": "should not be touched"
3187            }
3188        ]);
3189
3190        inject_reasoning_content_into_messages(&mut messages);
3191
3192        // User message should be untouched
3193        assert!(messages[0].get("reasoning_content").is_some());
3194    }
3195
3196    // Helper: create a formatter with a minimal chat template for render tests
3197    fn make_test_formatter() -> HfTokenizerConfigJsonFormatter {
3198        use super::tokcfg::ChatTemplate;
3199        use super::{ContextMixins, HfTokenizerConfigJsonFormatter};
3200
3201        // Minimal template that renders content verbatim — enough to verify
3202        // that reasoning_content injection works through the full pipeline.
3203        let template = r#"{%- for message in messages %}{{ message.role }}: {{ message.content }}
3204{%- endfor %}
3205{%- if add_generation_prompt %}assistant:{%- endif %}"#;
3206
3207        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
3208            "chat_template": template
3209        }))
3210        .unwrap();
3211
3212        HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap()
3213    }
3214
3215    // Verify reasoning_content (Text variant) from a prior assistant turn
3216    // appears as a <think> block in the rendered prompt.
3217    #[test]
3218    fn test_reasoning_content_text_roundtrip_render() {
3219        use super::OAIPromptFormatter;
3220        let formatter = make_test_formatter();
3221
3222        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3223            "model": "test-model",
3224            "messages": [
3225                {"role": "user", "content": "What is sqrt(144)?"},
3226                {
3227                    "role": "assistant",
3228                    "content": "The answer is 12.",
3229                    "reasoning_content": "I need to compute the square root of 144."
3230                },
3231                {"role": "user", "content": "Are you sure?"}
3232            ]
3233        }))
3234        .unwrap();
3235
3236        let rendered = formatter.render(&request).unwrap();
3237
3238        assert!(
3239            rendered.contains("<think>I need to compute the square root of 144.</think>"),
3240            "reasoning_content must appear as <think> block, got: {}",
3241            rendered
3242        );
3243        assert!(
3244            rendered.contains("The answer is 12."),
3245            "original content must be preserved"
3246        );
3247        assert!(
3248            !rendered.contains("reasoning_content"),
3249            "raw reasoning_content field should not leak into prompt"
3250        );
3251    }
3252
3253    // Verify a full agentic flow: assistant reasons, calls a tool, gets a
3254    // result, then reasons again before answering. Both reasoning turns must
3255    // survive into the rendered prompt.
3256    #[test]
3257    fn test_reasoning_content_agentic_tool_call_roundtrip_render() {
3258        use super::OAIPromptFormatter;
3259        let formatter = make_test_formatter();
3260
3261        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3262            "model": "test-model",
3263            "messages": [
3264                {"role": "user", "content": "What is sqrt(144) + sqrt(256)?"},
3265                {
3266                    "role": "assistant",
3267                    "content": null,
3268                    "reasoning_content": "I need to compute both square roots. Let me start with sqrt(144).",
3269                    "tool_calls": [{
3270                        "id": "call_0",
3271                        "type": "function",
3272                        "function": {
3273                            "name": "calculator",
3274                            "arguments": "{\"expr\": \"sqrt(144)\"}"
3275                        }
3276                    }]
3277                },
3278                {
3279                    "role": "tool",
3280                    "tool_call_id": "call_0",
3281                    "content": "12"
3282                },
3283                {
3284                    "role": "assistant",
3285                    "content": "sqrt(144) = 12 and sqrt(256) = 16, so the answer is 28.",
3286                    "reasoning_content": "Got 12 for sqrt(144). Now sqrt(256) = 16. Sum is 28."
3287                },
3288                {"role": "user", "content": "Thanks!"}
3289            ]
3290        }))
3291        .unwrap();
3292
3293        let rendered = formatter.render(&request).unwrap();
3294
3295        // First assistant turn: reasoning with tool call, null content
3296        assert!(
3297            rendered.contains("<think>I need to compute both square roots"),
3298            "first turn reasoning must be in prompt, got: {}",
3299            rendered
3300        );
3301        // Second assistant turn: reasoning with final answer
3302        assert!(
3303            rendered.contains("<think>Got 12 for sqrt(144)"),
3304            "second turn reasoning must be in prompt"
3305        );
3306        assert!(
3307            rendered.contains("the answer is 28"),
3308            "final answer content must be preserved"
3309        );
3310        // No raw reasoning_content in output
3311        assert!(
3312            !rendered.contains("reasoning_content"),
3313            "raw reasoning_content field should not leak into prompt"
3314        );
3315    }
3316
3317    // Template that does NOT reference reasoning_content — injection should happen.
3318    #[test]
3319    fn test_reasoning_injected_when_template_ignores_it() {
3320        use super::OAIPromptFormatter;
3321        let formatter = make_test_formatter();
3322
3323        // Formatter uses a simple template that doesn't reference reasoning_content
3324        assert!(!formatter.default_template_handles_reasoning);
3325        assert!(!formatter.tool_use_template_handles_reasoning);
3326
3327        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3328            "model": "test-model",
3329            "messages": [
3330                {"role": "user", "content": "Hello"},
3331                {
3332                    "role": "assistant",
3333                    "content": "Hi.",
3334                    "reasoning_content": "The user said hello."
3335                },
3336                {"role": "user", "content": "Bye"}
3337            ]
3338        }))
3339        .unwrap();
3340
3341        let rendered = formatter.render(&request).unwrap();
3342        assert!(
3343            rendered.contains("<think>The user said hello.</think>"),
3344            "injection must happen when template ignores reasoning_content, got: {}",
3345            rendered
3346        );
3347    }
3348
3349    // Template that DOES reference reasoning_content — injection must be skipped.
3350    #[test]
3351    fn test_reasoning_not_injected_when_template_handles_it() {
3352        use super::tokcfg::ChatTemplate;
3353        use super::{ContextMixins, HfTokenizerConfigJsonFormatter, OAIPromptFormatter};
3354
3355        // Template that natively renders reasoning_content (like Nemotron/Qwen3)
3356        let template = r#"{%- for message in messages %}{%- if message.role == "assistant" and message.reasoning_content is defined and message.reasoning_content %}<think>{{ message.reasoning_content }}</think>
3357{%- endif %}{{ message.role }}: {{ message.content }}
3358{%- endfor %}
3359{%- if add_generation_prompt %}assistant:{%- endif %}"#;
3360
3361        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
3362            "chat_template": template
3363        }))
3364        .unwrap();
3365
3366        let formatter =
3367            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
3368
3369        // Verify detection worked
3370        assert!(formatter.default_template_handles_reasoning);
3371        assert!(formatter.tool_use_template_handles_reasoning);
3372
3373        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3374            "model": "test-model",
3375            "messages": [
3376                {"role": "user", "content": "Hello"},
3377                {
3378                    "role": "assistant",
3379                    "content": "Hi.",
3380                    "reasoning_content": "The user said hello."
3381                },
3382                {"role": "user", "content": "Bye"}
3383            ]
3384        }))
3385        .unwrap();
3386
3387        let rendered = formatter.render(&request).unwrap();
3388
3389        // Template renders reasoning natively — no duplicate injection
3390        assert!(
3391            rendered.contains("<think>The user said hello.</think>"),
3392            "template must render reasoning_content natively, got: {}",
3393            rendered
3394        );
3395        // Must NOT have double <think> blocks
3396        let think_count = rendered.matches("<think>").count();
3397        assert_eq!(
3398            think_count, 1,
3399            "must have exactly one <think> block (from template), got {} in: {}",
3400            think_count, rendered
3401        );
3402    }
3403
3404    /// Real Qwen3-4B-Thinking-2507 chat template (verbatim from
3405    /// `Qwen/Qwen3-4B-Thinking-2507/tokenizer_config.json`). Used to
3406    /// regression-test append-only rendering across multi-step tool use.
3407    const QWEN3_THINKING_TEMPLATE: &str = r##"{%- if tools %}
3408    {{- '<|im_start|>system\n' }}
3409    {%- if messages[0].role == 'system' %}
3410        {{- messages[0].content + '\n\n' }}
3411    {%- endif %}
3412    {{- "# Tools\n\nYou may call one or more functions to assist with the user query.\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
3413    {%- for tool in tools %}
3414        {{- "\n" }}
3415        {{- tool | tojson }}
3416    {%- endfor %}
3417    {{- "\n</tools>\n\nFor each function call, return a json object with function name and arguments within <tool_call></tool_call> XML tags:\n<tool_call>\n{\"name\": <function-name>, \"arguments\": <args-json-object>}\n</tool_call><|im_end|>\n" }}
3418{%- else %}
3419    {%- if messages[0].role == 'system' %}
3420        {{- '<|im_start|>system\n' + messages[0].content + '<|im_end|>\n' }}
3421    {%- endif %}
3422{%- endif %}
3423{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
3424{%- for message in messages[::-1] %}
3425    {%- set index = (messages|length - 1) - loop.index0 %}
3426    {%- if ns.multi_step_tool and message.role == "user" and message.content is string and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}
3427        {%- set ns.multi_step_tool = false %}
3428        {%- set ns.last_query_index = index %}
3429    {%- endif %}
3430{%- endfor %}
3431{%- for message in messages %}
3432    {%- if message.content is string %}
3433        {%- set content = message.content %}
3434    {%- else %}
3435        {%- set content = '' %}
3436    {%- endif %}
3437    {%- if (message.role == "user") or (message.role == "system" and not loop.first) %}
3438        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
3439    {%- elif message.role == "assistant" %}
3440        {%- set reasoning_content = '' %}
3441        {%- if message.reasoning_content is string %}
3442            {%- set reasoning_content = message.reasoning_content %}
3443        {%- else %}
3444            {%- if '</think>' in content %}
3445                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
3446                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
3447            {%- endif %}
3448        {%- endif %}
3449        {%- if loop.index0 > ns.last_query_index %}
3450            {%- if loop.last or (not loop.last and reasoning_content) %}
3451                {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content.strip('\n') + '\n</think>\n\n' + content.lstrip('\n') }}
3452            {%- else %}
3453                {{- '<|im_start|>' + message.role + '\n' + content }}
3454            {%- endif %}
3455        {%- else %}
3456            {{- '<|im_start|>' + message.role + '\n' + content }}
3457        {%- endif %}
3458        {%- if message.tool_calls %}
3459            {%- for tool_call in message.tool_calls %}
3460                {%- if (loop.first and content) or (not loop.first) %}
3461                    {{- '\n' }}
3462                {%- endif %}
3463                {%- if tool_call.function %}
3464                    {%- set tool_call = tool_call.function %}
3465                {%- endif %}
3466                {{- '<tool_call>\n{"name": "' }}
3467                {{- tool_call.name }}
3468                {{- '", "arguments": ' }}
3469                {%- if tool_call.arguments is string %}
3470                    {{- tool_call.arguments }}
3471                {%- else %}
3472                    {{- tool_call.arguments | tojson }}
3473                {%- endif %}
3474                {{- '}\n</tool_call>' }}
3475            {%- endfor %}
3476        {%- endif %}
3477        {{- '<|im_end|>\n' }}
3478    {%- elif message.role == "tool" %}
3479        {%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
3480            {{- '<|im_start|>user' }}
3481        {%- endif %}
3482        {{- '\n<tool_response>\n' }}
3483        {{- content }}
3484        {{- '\n</tool_response>' }}
3485        {%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
3486            {{- '<|im_end|>\n' }}
3487        {%- endif %}
3488    {%- endif %}
3489{%- endfor %}
3490{%- if add_generation_prompt %}
3491    {{- '<|im_start|>assistant\n<think>\n' }}
3492{%- endif %}"##;
3493
3494    fn qwen3_thinking_formatter() -> HfTokenizerConfigJsonFormatter {
3495        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
3496            "chat_template": QWEN3_THINKING_TEMPLATE,
3497        }))
3498        .unwrap();
3499        HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap()
3500    }
3501
3502    #[test]
3503    fn test_qwen3_thinking_template_flags_detected() {
3504        let formatter = qwen3_thinking_formatter();
3505        assert!(
3506            formatter.tool_use_template_handles_reasoning,
3507            "template references reasoning_content directly"
3508        );
3509        // The Qwen3-Thinking template is registered as both `default` and
3510        // `tool_use` (single-string HF chat template), so both flags must fire.
3511        assert!(
3512            formatter.default_template_handles_tool_calls_arguments_string,
3513            "default template branches on `arguments is string`"
3514        );
3515        assert!(
3516            formatter.tool_use_template_handles_tool_calls_arguments_string,
3517            "tool_use template branches on `arguments is string`"
3518        );
3519    }
3520
3521    /// Tool-call loop of unsloth's Qwen3.8 template (unsloth/Qwen3.8-27B): it
3522    /// renders mapping arguments as `<parameter=...>` and uses `arguments is
3523    /// string` only to reject strings.
3524    const QWEN38_REJECTS_STRING_ARGS_TEMPLATE: &str = r##"{%- for message in messages %}
3525    {%- if message.role == "assistant" and message.tool_calls %}
3526        {%- for tool_call in message.tool_calls %}
3527            {%- if tool_call.function %}
3528                {%- set tool_call = tool_call.function %}
3529            {%- endif %}
3530            {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
3531            {%- if tool_call.arguments is mapping %}
3532                {%- for args_name, args_value in tool_call.arguments|items %}
3533                    {{- '<parameter=' + args_name + '>\n' + args_value + '\n</parameter>\n' }}
3534                {%- endfor %}
3535            {%- elif tool_call.arguments is string %}
3536                {%- if tool_call.arguments|trim %}
3537                    {{- raise_exception('Tool call arguments were passed as a JSON string.') }}
3538                {%- endif %}
3539            {%- endif %}
3540            {{- '</function>\n</tool_call>' }}
3541        {%- endfor %}
3542    {%- else %}
3543        {{- '<|im_start|>' + message.role + '\n' + message.content + '<|im_end|>\n' }}
3544    {%- endif %}
3545{%- endfor %}"##;
3546
3547    /// A template that mentions `arguments is string` only to reject strings
3548    /// must still get parsed arguments; otherwise every request with a tool call
3549    /// in its history fails.
3550    #[test]
3551    fn test_template_rejecting_string_arguments_gets_objects() {
3552        let chat_template: ChatTemplate = serde_json::from_value(serde_json::json!({
3553            "chat_template": QWEN38_REJECTS_STRING_ARGS_TEMPLATE,
3554        }))
3555        .unwrap();
3556        let formatter =
3557            HfTokenizerConfigJsonFormatter::new(chat_template, ContextMixins::new(&[])).unwrap();
3558        assert!(!formatter.default_template_handles_tool_calls_arguments_string);
3559        assert!(!formatter.tool_use_template_handles_tool_calls_arguments_string);
3560
3561        let request: NvCreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
3562            "model": "qwen3.8",
3563            "messages": [
3564                {"role": "user", "content": "What's the weather in San Francisco?"},
3565                {"role": "assistant", "content": "", "tool_calls": [{
3566                    "id": "call_sf",
3567                    "type": "function",
3568                    "function": {"name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}"}
3569                }]},
3570                {"role": "tool", "tool_call_id": "call_sf", "content": "Foggy"}
3571            ],
3572        }))
3573        .unwrap();
3574        let rendered = formatter.render(&request).unwrap();
3575        assert!(
3576            rendered.contains("<parameter=location>\nSan Francisco\n</parameter>"),
3577            "{rendered}"
3578        );
3579    }
3580
3581    /// Across a multi-step tool-use turn, the rendered prompt for turn N+1
3582    /// must be a strict prefix-extension of [turn-N prompt + bytes the model
3583    /// emitted on turn N]. Otherwise KV-cache prefix matching falls off a
3584    /// cliff every time a tool result comes back.
3585    ///
3586    /// The Qwen3-Thinking template's `is string` branch (template lines 63-67)
3587    /// renders `tool_call.arguments` verbatim from the OpenAI-canonical JSON
3588    /// string. Pre-parsing that string into an object forces the `else` branch
3589    /// and re-emits with minijinja's compact `tojson`, breaking append-only.
3590    #[test]
3591    fn test_qwen3_thinking_append_only_across_tool_use_turn() {
3592        let formatter = qwen3_thinking_formatter();
3593
3594        let tools = serde_json::json!([{
3595            "type": "function",
3596            "function": {
3597                "name": "get_weather",
3598                "description": "Get the current weather for a location",
3599                "parameters": {
3600                    "type": "object",
3601                    "properties": {
3602                        "location": {"type": "string"},
3603                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
3604                    },
3605                    "required": ["location"]
3606                }
3607            }
3608        }]);
3609
3610        // Turn 1: server is asked to produce the first assistant turn.
3611        let turn1_request: NvCreateChatCompletionRequest =
3612            serde_json::from_value(serde_json::json!({
3613                "model": "qwen3-thinking",
3614                "messages": [
3615                    {"role": "system", "content": "You are a helpful assistant."},
3616                    {"role": "user", "content": "What's the weather in San Francisco?"},
3617                ],
3618                "tools": tools,
3619            }))
3620            .unwrap();
3621        let p1 = formatter.render(&turn1_request).unwrap();
3622
3623        // Bytes the model emits next. Spacing matches the Qwen3 training
3624        // distribution (Python jinja2 / json.dumps defaults: `, ` and `: `).
3625        // Empty content + reasoning + a tool call.
3626        let model_emitted = "I'll call get_weather for SF.\n\
3627            </think>\n\n\
3628            <tool_call>\n\
3629            {\"name\": \"get_weather\", \"arguments\": {\"location\": \"San Francisco\", \"unit\": \"celsius\"}}\n\
3630            </tool_call><|im_end|>\n";
3631        let wire_after_t1 = format!("{p1}{model_emitted}");
3632
3633        // Turn 2: client sends the prior assistant turn back in OpenAI canonical
3634        // form (arguments as a JSON STRING with spaces) plus the tool result.
3635        let turn2_request: NvCreateChatCompletionRequest =
3636            serde_json::from_value(serde_json::json!({
3637                "model": "qwen3-thinking",
3638                "messages": [
3639                    {"role": "system", "content": "You are a helpful assistant."},
3640                    {"role": "user", "content": "What's the weather in San Francisco?"},
3641                    {
3642                        "role": "assistant",
3643                        "content": "",
3644                        "reasoning_content": "I'll call get_weather for SF.",
3645                        "tool_calls": [{
3646                            "id": "call_sf",
3647                            "type": "function",
3648                            "function": {
3649                                "name": "get_weather",
3650                                "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
3651                            }
3652                        }]
3653                    },
3654                    {
3655                        "role": "tool",
3656                        "tool_call_id": "call_sf",
3657                        "content": "{\"temp\": 18, \"conditions\": \"Foggy\"}"
3658                    }
3659                ],
3660                "tools": tools,
3661            }))
3662            .unwrap();
3663        let p2 = formatter.render(&turn2_request).unwrap();
3664
3665        if !p2.starts_with(&wire_after_t1) {
3666            // Find first divergence and report it for easy debugging.
3667            let div = wire_after_t1
3668                .as_bytes()
3669                .iter()
3670                .zip(p2.as_bytes())
3671                .position(|(a, b)| a != b)
3672                .unwrap_or_else(|| wire_after_t1.len().min(p2.len()));
3673            let lo = div.saturating_sub(40);
3674            panic!(
3675                "turn-2 prompt is NOT a prefix-extension of [turn-1 + model bytes]\n  \
3676                 diverges at byte {div}\n  \
3677                 wire ends: ...{}|{}\n  \
3678                 t2 has:    ...{}|{}",
3679                String::from_utf8_lossy(&wire_after_t1.as_bytes()[lo..div]),
3680                String::from_utf8_lossy(
3681                    &wire_after_t1.as_bytes()[div..(div + 60).min(wire_after_t1.len())]
3682                ),
3683                String::from_utf8_lossy(&p2.as_bytes()[lo..div]),
3684                String::from_utf8_lossy(&p2.as_bytes()[div..(div + 60).min(p2.len())]),
3685            );
3686        }
3687
3688        // The only new bytes in P2 should be the tool response and the next
3689        // generation prompt — nothing in the prior conversation should change.
3690        let suffix = &p2[wire_after_t1.len()..];
3691        assert!(
3692            suffix.contains("<tool_response>"),
3693            "appended bytes must include the tool response, got: {suffix}"
3694        );
3695        assert!(
3696            suffix.ends_with("<|im_start|>assistant\n<think>\n"),
3697            "appended bytes must end with the next generation prompt, got: {suffix}"
3698        );
3699    }
3700
3701    /// Qwen3 reads `reasoning_content` only when it `is string`, so segments sent
3702    /// with tool calls must render exactly as the equivalent string does (keeping
3703    /// the append-only prefix above), with and without tools.
3704    #[test]
3705    fn test_qwen3_thinking_renders_reasoning_content_segments_as_string() {
3706        let formatter = qwen3_thinking_formatter();
3707        assert!(formatter.default_template_requires_reasoning_string);
3708        assert!(formatter.tool_use_template_requires_reasoning_string);
3709
3710        for render in [render_shape, render_shape_with_tools] {
3711            let segments = json!(["Check both.", "Then add.", ""]);
3712            let rendered = render(&formatter, reasoning_tool_call_turn(segments)).unwrap();
3713            assert!(
3714                rendered.contains(
3715                    "<|im_start|>assistant\n<think>\nCheck both.\nThen add.\n</think>\n\n<tool_call>"
3716                ),
3717                "{rendered}"
3718            );
3719            let string = json!("Check both.\nThen add.");
3720            assert_eq!(
3721                rendered,
3722                render(&formatter, reasoning_tool_call_turn(string)).unwrap()
3723            );
3724        }
3725    }
3726}