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