Skip to main content

dynamo_renderer/
mistral.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Native Mistral instruct prompt rendering for tekken tokenizers v13 and v15.
5//!
6//! Mistral checkpoints ship no Jinja template; mistral-common builds the prompt
7//! from token ids, inserting structural markers as special tokens and encoding
8//! message text as ordinary BPE. This renderer reproduces mistral-common's
9//! request normalizer and `InstructTokenizerV13`/`V15` encoders as segments:
10//! markers are control segments, and every piece mistral-common encodes in one
11//! call is one ordinary segment, so text such as a literal `[INST]` in user
12//! content never becomes prompt structure.
13//!
14//! An image renders as one `[IMG]` control segment. mistral-common expands it
15//! to the image's full `[IMG]`/`[IMG_BREAK]`/`[IMG_END]` grid, which depends on
16//! the image size; whoever loads the image must do that expansion.
17
18use std::borrow::Cow;
19use std::collections::{HashMap, HashSet};
20use std::fmt;
21
22use anyhow::{Context, Result};
23use serde::de::{MapAccess, Visitor};
24use serde::{Deserialize, Serialize as _};
25use serde_json::value::RawValue;
26use serde_json::{Map, Value};
27
28use crate::python::PyJsonFormatter;
29use crate::{
30    OAIChatLikeRequest, OAIPromptFormatter, PromptRenderError, RenderedPrompt, RenderedSegment,
31};
32
33const BOS: &str = "<s>";
34const EOS: &str = "</s>";
35const INST: &str = "[INST]";
36const INST_END: &str = "[/INST]";
37const AVAILABLE_TOOLS: &str = "[AVAILABLE_TOOLS]";
38const AVAILABLE_TOOLS_END: &str = "[/AVAILABLE_TOOLS]";
39const TOOL_RESULTS: &str = "[TOOL_RESULTS]";
40const TOOL_RESULTS_END: &str = "[/TOOL_RESULTS]";
41const TOOL_CALLS: &str = "[TOOL_CALLS]";
42const ARGS: &str = "[ARGS]";
43const SYSTEM_PROMPT: &str = "[SYSTEM_PROMPT]";
44const SYSTEM_PROMPT_END: &str = "[/SYSTEM_PROMPT]";
45const THINK: &str = "[THINK]";
46const THINK_END: &str = "[/THINK]";
47const MODEL_SETTINGS: &str = "[MODEL_SETTINGS]";
48const MODEL_SETTINGS_END: &str = "[/MODEL_SETTINGS]";
49const IMG: &str = "[IMG]";
50
51/// Separator between text from consecutive same-role messages.
52const MESSAGE_JOIN: &str = "\n\n";
53
54/// Tekken tokenizer versions this renderer reproduces.
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub enum MistralTokenizerVersion {
57    V13,
58    V15,
59}
60
61impl MistralTokenizerVersion {
62    /// Map a tekken `config.version` number (`13` for `v13`) to a version.
63    pub fn from_number(version: u32) -> Option<Self> {
64        match version {
65            13 => Some(Self::V13),
66            15 => Some(Self::V15),
67            _ => None,
68        }
69    }
70
71    /// Separator between text chunks of one message (mistral-common's
72    /// `_chunk_join_str`).
73    fn chunk_join(self) -> &'static str {
74        match self {
75            Self::V13 => MESSAGE_JOIN,
76            Self::V15 => "",
77        }
78    }
79}
80
81/// Allowed values and default of one enum model setting.
82#[derive(Debug, Clone, Deserialize)]
83struct EnumSetting {
84    accepts_none: bool,
85    default: Option<String>,
86    values: Vec<String>,
87}
88
89/// The tekken file's `model_settings_builder`, which decides the
90/// `[MODEL_SETTINGS]` block of v15 prompts.
91#[derive(Debug, Clone, Default, Deserialize)]
92#[serde(deny_unknown_fields)]
93struct ModelSettingsBuilder {
94    #[serde(default)]
95    reasoning_effort: Option<EnumSetting>,
96    /// Present when the model accepts a response JSON schema.
97    #[serde(default)]
98    json_schema: Option<Value>,
99}
100
101#[derive(Debug, Clone)]
102pub struct MistralFormatter {
103    version: MistralTokenizerVersion,
104    settings: Option<ModelSettingsBuilder>,
105}
106
107impl MistralFormatter {
108    /// Build a formatter from a tekken tokenizer's version number and its
109    /// `model_settings_builder` section (required for v15).
110    pub fn new(version: u32, model_settings_builder: Option<&Value>) -> Result<Self> {
111        let version = MistralTokenizerVersion::from_number(version).with_context(|| {
112            format!("Mistral renderer supports tekken v13 and v15, got v{version}")
113        })?;
114        let settings = match (version, model_settings_builder) {
115            (MistralTokenizerVersion::V13, _) => None,
116            (MistralTokenizerVersion::V15, Some(builder)) => Some(
117                ModelSettingsBuilder::deserialize(builder)
118                    .context("Invalid tekken model_settings_builder")?,
119            ),
120            (MistralTokenizerVersion::V15, None) => {
121                anyhow::bail!("tekken v15 tokenizers need a model_settings_builder")
122            }
123        };
124        Ok(Self { version, settings })
125    }
126
127    fn build_segments(&self, req: &dyn OAIChatLikeRequest) -> Result<Vec<RenderedSegment>> {
128        let messages =
129            crate::messages_to_json(req).context("Failed to convert Mistral messages")?;
130        crate::reject_unsupported_partial_assistant(&messages)?;
131        crate::reject_unsupported_message_tools(&messages, &[])?;
132        let Value::Array(messages) = messages else {
133            anyhow::bail!("Mistral messages must be an array");
134        };
135        let messages = messages
136            .iter()
137            .map(Message::from_openai)
138            .collect::<Result<Vec<_>>>()?;
139        validate_message_order(&messages)?;
140        validate_tool_pairs(&messages)?;
141        if req.should_add_generation_prompt()
142            && messages.len() > 1
143            && messages.last().is_some_and(|m| m.role == Role::Assistant)
144        {
145            return Err(invalid(
146                "the last message is from the assistant; use continue_final_message to continue it",
147            ));
148        }
149
150        // Prefer the client's tools: the Jinja backfill would add
151        // `type`/`properties` that mistral-common does not.
152        let tools = req
153            .raw_tools()
154            .or_else(|| req.tools())
155            .map(|tools| serde_json::to_value(&tools))
156            .transpose()
157            .context("Failed to convert Mistral tools")?;
158        let tools_json = render_tools(tools.as_ref())?;
159        let settings_json = self.render_settings(req)?;
160        let messages = aggregate_messages(messages, self.version);
161        // Without a generation prompt, a final assistant turn is continued: it
162        // renders as mistral-common's `prefix` message, open and without `</s>`.
163        let continued = (!req.should_add_generation_prompt()
164            && messages.last().is_some_and(|m| m.role == Role::Assistant))
165        .then(|| messages.len() - 1);
166
167        let mut out = Segments::default();
168        out.control(BOS);
169        let first_user = messages.iter().position(|m| m.role == Role::User);
170        for (index, message) in messages.iter().enumerate() {
171            match message.role {
172                Role::User => {
173                    if Some(index) == first_user {
174                        if let Some(tools_json) = &tools_json {
175                            out.control(AVAILABLE_TOOLS);
176                            out.text(tools_json);
177                            out.control(AVAILABLE_TOOLS_END);
178                        }
179                        if let Some(settings_json) = &settings_json {
180                            out.control(MODEL_SETTINGS);
181                            out.text(settings_json);
182                            out.control(MODEL_SETTINGS_END);
183                        }
184                    }
185                    out.control(INST);
186                    out.content(&image_first(&message.content));
187                    out.control(INST_END);
188                }
189                Role::System => {
190                    if self.version == MistralTokenizerVersion::V15 && message.content.has_think() {
191                        return Err(invalid(
192                            "thinking content is not supported in system messages",
193                        ));
194                    }
195                    out.control(SYSTEM_PROMPT);
196                    out.content(&message.content);
197                    out.control(SYSTEM_PROMPT_END);
198                }
199                Role::Assistant => {
200                    if message.content.is_empty() && message.tool_calls.is_empty() {
201                        return Err(invalid(
202                            "assistant messages need content, reasoning or tool calls",
203                        ));
204                    }
205                    match &message.content {
206                        // mistral-common strips trailing spaces from plain string replies.
207                        AggregatedContent::Text(text) => out.text(text.trim_end_matches(' ')),
208                        chunks => out.content(chunks),
209                    }
210                    for call in &message.tool_calls {
211                        out.control(TOOL_CALLS);
212                        out.text(&call.name);
213                        out.control(ARGS);
214                        out.text(&encoded_arguments(&call.arguments));
215                    }
216                    if continued != Some(index) {
217                        out.control(EOS);
218                    }
219                }
220                Role::Tool => {
221                    out.control(TOOL_RESULTS);
222                    out.content(&message.content);
223                    out.control(TOOL_RESULTS_END);
224                }
225            }
226        }
227        Ok(out.0)
228    }
229
230    /// Render the `[MODEL_SETTINGS]` JSON, or `None` when no setting applies.
231    fn render_settings(&self, req: &dyn OAIChatLikeRequest) -> Result<Option<String>> {
232        let Some(builder) = &self.settings else {
233            // v13 prompts carry no settings; upstream vLLM ignores both fields.
234            return Ok(None);
235        };
236
237        // Keys are emitted in sorted order, as mistral-common does.
238        let mut settings = Map::new();
239        let response_format = req
240            .response_format()
241            .map(|format| serde_json::to_value(&format))
242            .transpose()
243            .context("Failed to convert response_format")?;
244        // Like mistral-common's `build_settings`, a field the tokenizer has no
245        // builder for is dropped rather than rejected.
246        if builder.json_schema.is_some()
247            && let Some(schema) = response_schema(response_format.as_ref())
248        {
249            settings.insert("json_schema".to_string(), schema);
250        }
251
252        let effort = requested_reasoning_effort(req)?;
253        match (&builder.reasoning_effort, effort) {
254            (None, _) => {}
255            (Some(setting), None) => {
256                if !setting.accepts_none {
257                    return Err(invalid("reasoning_effort must be set for this model"));
258                }
259                if let Some(default) = &setting.default {
260                    settings.insert("reasoning_effort".to_string(), default.clone().into());
261                }
262            }
263            (Some(setting), Some(effort)) => {
264                if !setting.values.contains(&effort) {
265                    return Err(invalid(format!(
266                        "reasoning_effort must be one of {:?}, got {effort:?}",
267                        setting.values
268                    )));
269                }
270                settings.insert("reasoning_effort".to_string(), effort.into());
271            }
272        }
273
274        Ok((!settings.is_empty()).then(|| python_json(&Value::Object(settings))))
275    }
276}
277
278impl OAIPromptFormatter for MistralFormatter {
279    fn supports_add_generation_prompt(&self) -> bool {
280        true
281    }
282
283    fn renders_continuation_natively(&self) -> bool {
284        true
285    }
286
287    fn render(&self, req: &dyn OAIChatLikeRequest) -> Result<String> {
288        Ok(self.render_prompt(req)?.into_text())
289    }
290
291    fn render_prompt(&self, req: &dyn OAIChatLikeRequest) -> Result<RenderedPrompt> {
292        Ok(RenderedPrompt::segmented(self.build_segments(req)?))
293    }
294
295    /// Tool results are reordered by call order, and their images with them.
296    fn media_message_order(&self, req: &dyn OAIChatLikeRequest) -> Option<Vec<usize>> {
297        let Value::Array(messages) = crate::messages_to_json(req).ok()? else {
298            return None;
299        };
300        let tool_has_image = messages.iter().any(|message| {
301            message.get("role").and_then(Value::as_str) == Some("tool")
302                && message
303                    .get("content")
304                    .and_then(Value::as_array)
305                    .is_some_and(|parts| parts.iter().any(is_image_part))
306        });
307        if !tool_has_image {
308            return None;
309        }
310        let messages = messages
311            .iter()
312            .map(Message::from_openai)
313            .collect::<Result<Vec<_>>>()
314            .ok()?;
315        let order = rendered_message_order(&messages);
316        order
317            .iter()
318            .enumerate()
319            .any(|(index, &source)| index != source)
320            .then_some(order)
321    }
322}
323
324fn is_image_part(part: &Value) -> bool {
325    part.get("type").and_then(Value::as_str) == Some("image_url")
326}
327
328/// mistral-common's `_maybe_put_image_first` for user turns: an image that
329/// follows only text moves to the front.
330fn image_first(content: &AggregatedContent) -> Cow<'_, AggregatedContent> {
331    match content {
332        AggregatedContent::Chunks(chunks)
333            if chunks.len() >= 2
334                && matches!(chunks.last(), Some(Chunk::Image))
335                && chunks[..chunks.len() - 1]
336                    .iter()
337                    .all(|chunk| matches!(chunk, Chunk::Text(_))) =>
338        {
339            let mut reordered = Vec::with_capacity(chunks.len());
340            reordered.push(Chunk::Image);
341            reordered.extend_from_slice(&chunks[..chunks.len() - 1]);
342            Cow::Owned(AggregatedContent::Chunks(reordered))
343        }
344        _ => Cow::Borrowed(content),
345    }
346}
347
348fn invalid(message: impl Into<String>) -> anyhow::Error {
349    PromptRenderError::invalid_request(message).into()
350}
351
352/// `json.dumps(value, ensure_ascii=False)`.
353fn python_json(value: &Value) -> String {
354    let mut buf = Vec::new();
355    let mut serializer = serde_json::Serializer::with_formatter(&mut buf, PyJsonFormatter);
356    value
357        .serialize(&mut serializer)
358        .expect("serializing a JSON value into a Vec cannot fail");
359    String::from_utf8(buf).expect("serde_json writes UTF-8")
360}
361
362#[derive(Default)]
363struct Segments(Vec<RenderedSegment>);
364
365impl Segments {
366    fn control(&mut self, token: &str) {
367        self.0.push(RenderedSegment::new(token, true));
368    }
369
370    /// One ordinary-text encode call; empty text encodes to nothing.
371    fn text(&mut self, text: &str) {
372        if !text.is_empty() {
373            self.0.push(RenderedSegment::new(text, false));
374        }
375    }
376
377    fn content(&mut self, content: &AggregatedContent) {
378        match content {
379            AggregatedContent::Text(text) => self.text(text),
380            AggregatedContent::Chunks(chunks) => {
381                for chunk in chunks {
382                    match chunk {
383                        Chunk::Text(text) => self.text(text),
384                        Chunk::Think { text, closed } => {
385                            self.control(THINK);
386                            self.text(text);
387                            if *closed {
388                                self.control(THINK_END);
389                            }
390                        }
391                        Chunk::Image => self.control(IMG),
392                    }
393                }
394            }
395        }
396    }
397}
398
399#[derive(Debug, Clone, Copy, PartialEq, Eq)]
400enum Role {
401    System,
402    User,
403    Assistant,
404    Tool,
405}
406
407#[derive(Debug, Clone, PartialEq)]
408enum Chunk {
409    Text(String),
410    Think { text: String, closed: bool },
411    Image,
412}
413
414#[derive(Debug, Clone, PartialEq)]
415enum Content {
416    Text(String),
417    Chunks(Vec<Chunk>),
418}
419
420impl Content {
421    /// Python truthiness: `None`, `""` and `[]` are all empty.
422    fn is_empty(&self) -> bool {
423        match self {
424            Content::Text(text) => text.is_empty(),
425            Content::Chunks(chunks) => chunks.is_empty(),
426        }
427    }
428}
429
430#[derive(Debug, Clone)]
431struct ToolCall {
432    id: Option<String>,
433    name: String,
434    arguments: String,
435}
436
437#[derive(Debug, Clone)]
438struct Message {
439    role: Role,
440    content: Option<Content>,
441    tool_calls: Vec<ToolCall>,
442    tool_call_id: Option<String>,
443}
444
445impl Message {
446    /// Convert one OpenAI message the way mistral-common's `from_openai` does.
447    fn from_openai(message: &Value) -> Result<Self> {
448        let role = match message.get("role").and_then(Value::as_str) {
449            // OpenAI's `developer` role is treated as system; mistral-common
450            // itself rejects the role.
451            Some("system" | "developer") => Role::System,
452            Some("user") => Role::User,
453            Some("assistant") => Role::Assistant,
454            Some("tool") => Role::Tool,
455            other => return Err(invalid(format!("unsupported message role {other:?}"))),
456        };
457        let mut content = content_from_openai(message.get("content"), role)?;
458        let mut tool_calls = Vec::new();
459
460        if role == Role::Assistant {
461            if let Some(calls) = message.get("tool_calls").filter(|calls| !calls.is_null()) {
462                let calls = calls
463                    .as_array()
464                    .ok_or_else(|| invalid("assistant tool_calls must be a list"))?;
465                for call in calls {
466                    tool_calls.push(tool_call_from_openai(call)?);
467                }
468            }
469            if let Some(reasoning) = reasoning_from_openai(message)? {
470                if matches!(&content, Some(Content::Chunks(chunks))
471                    if chunks.iter().any(|c| matches!(c, Chunk::Think { .. })))
472                {
473                    return Err(invalid(
474                        "assistant messages cannot carry both thinking chunks and reasoning",
475                    ));
476                }
477                let think = Chunk::Think {
478                    text: reasoning,
479                    closed: true,
480                };
481                content = Some(Content::Chunks(match content {
482                    None => vec![think],
483                    Some(Content::Text(text)) => vec![think, Chunk::Text(text)],
484                    Some(Content::Chunks(mut chunks)) => {
485                        chunks.insert(0, think);
486                        chunks
487                    }
488                }));
489            }
490        }
491        if role == Role::System && content.is_none() {
492            return Err(invalid("system messages need content"));
493        }
494
495        let tool_call_id = message
496            .get("tool_call_id")
497            .and_then(Value::as_str)
498            .map(str::to_string);
499        Ok(Self {
500            role,
501            content,
502            tool_calls,
503            tool_call_id,
504        })
505    }
506}
507
508fn content_from_openai(content: Option<&Value>, role: Role) -> Result<Option<Content>> {
509    match content {
510        None | Some(Value::Null) => Ok(None),
511        Some(Value::String(text)) => Ok(Some(Content::Text(text.clone()))),
512        Some(Value::Array(parts)) => {
513            let mut chunks = Vec::with_capacity(parts.len());
514            for part in parts {
515                match part.get("type").and_then(Value::as_str) {
516                    Some("text") => {
517                        let text = part.get("text").and_then(Value::as_str).unwrap_or_default();
518                        chunks.push(Chunk::Text(text.to_string()));
519                    }
520                    Some("thinking") if matches!(role, Role::Assistant | Role::System) => {
521                        let text = part
522                            .get("thinking")
523                            .and_then(Value::as_str)
524                            .unwrap_or_default();
525                        let closed = part.get("closed").and_then(Value::as_bool).unwrap_or(true);
526                        chunks.push(Chunk::Think {
527                            text: text.to_string(),
528                            closed,
529                        });
530                    }
531                    // mistral-common rejects images in system and assistant messages.
532                    Some("image_url") if matches!(role, Role::User | Role::Tool) => {
533                        let url = match part.get("image_url") {
534                            Some(Value::String(url)) => Some(url.as_str()),
535                            Some(image_url) => image_url.get("url").and_then(Value::as_str),
536                            None => None,
537                        };
538                        if url.is_none_or(str::is_empty) {
539                            return Err(invalid("image_url parts need a url"));
540                        }
541                        chunks.push(Chunk::Image);
542                    }
543                    other => {
544                        return Err(invalid(format!(
545                            "content part type {other:?} is not supported by the Mistral renderer"
546                        )));
547                    }
548                }
549            }
550            Ok(Some(Content::Chunks(chunks)))
551        }
552        Some(other) => Err(invalid(format!(
553            "message content must be a string or a list of parts, got {other}"
554        ))),
555    }
556}
557
558fn reasoning_from_openai(message: &Value) -> Result<Option<String>> {
559    // Segmented reasoning flattens as the Jinja path does: non-empty segments
560    // joined with newlines (`ReasoningContent::to_flat_string`).
561    let field = |key: &str| match message.get(key)? {
562        Value::String(text) => Some(text.clone()),
563        Value::Array(segments) => Some(
564            segments
565                .iter()
566                .filter_map(Value::as_str)
567                .filter(|segment| !segment.is_empty())
568                .collect::<Vec<_>>()
569                .join("\n"),
570        ),
571        _ => None,
572    };
573    match (field("reasoning_content"), field("reasoning")) {
574        (Some(a), Some(b)) if a != b => Err(invalid(
575            "assistant `reasoning_content` and `reasoning` must be equal when both are set",
576        )),
577        (Some(text), _) | (None, Some(text)) => Ok(Some(text)),
578        (None, None) => Ok(None),
579    }
580}
581
582fn tool_call_from_openai(call: &Value) -> Result<ToolCall> {
583    let function = call
584        .get("function")
585        .ok_or_else(|| invalid("assistant tool calls need a function"))?;
586    let name = function
587        .get("name")
588        .and_then(Value::as_str)
589        .ok_or_else(|| invalid("assistant tool calls need a function name"))?;
590    let arguments = match function.get("arguments") {
591        None | Some(Value::Null) => String::new(),
592        Some(Value::String(arguments)) => arguments.clone(),
593        Some(other) => python_json(other),
594    };
595    Ok(ToolCall {
596        id: call.get("id").and_then(Value::as_str).map(str::to_string),
597        name: name.to_string(),
598        arguments,
599    })
600}
601
602/// mistral-common's message-order rule (`MistralRequestValidator`).
603fn validate_message_order(messages: &[Message]) -> Result<()> {
604    match messages {
605        [] => return Err(invalid("the conversation needs at least one message")),
606        [only] if !matches!(only.role, Role::User | Role::System) => {
607            return Err(invalid(
608                "the conversation must start with a user or system message",
609            ));
610        }
611        _ => {}
612    }
613    for pair in messages.windows(2) {
614        let allowed = match pair[0].role {
615            Role::System => matches!(pair[1].role, Role::User | Role::Assistant | Role::System),
616            Role::User => matches!(pair[1].role, Role::Assistant | Role::System | Role::User),
617            Role::Assistant => matches!(pair[1].role, Role::Assistant | Role::User | Role::Tool),
618            Role::Tool => matches!(pair[1].role, Role::Assistant | Role::Tool | Role::User),
619        };
620        if !allowed {
621            return Err(invalid(format!(
622                "unexpected {:?} message after a {:?} message",
623                pair[1].role, pair[0].role
624            )));
625        }
626    }
627    Ok(())
628}
629
630/// V11 pairing validation in mistral-common's `test` mode: a later assistant
631/// requires all prior results, but an unfinished final turn may still be continued.
632fn validate_tool_pairs(messages: &[Message]) -> Result<()> {
633    let mut expected = HashSet::new();
634    let mut observed = HashSet::new();
635    for message in messages.iter().skip(1) {
636        match message.role {
637            Role::Tool => {
638                let id = message.tool_call_id.as_deref();
639                if observed.contains(&id) {
640                    return Err(invalid(format!(
641                        "duplicate tool call id {id:?} in tool results"
642                    )));
643                }
644                if !expected.contains(&id) {
645                    return Err(invalid(format!(
646                        "unexpected tool call id {id:?} in tool results"
647                    )));
648                }
649                observed.insert(id);
650            }
651            Role::Assistant => {
652                if expected.len() != observed.len() {
653                    return Err(invalid(
654                        "not the same number of function calls and responses",
655                    ));
656                }
657                expected.clear();
658                observed.clear();
659                for call in &message.tool_calls {
660                    let id = call.id.as_deref();
661                    if !expected.insert(id) {
662                        return Err(invalid(format!(
663                            "duplicate tool call id {id:?} in assistant message"
664                        )));
665                    }
666                }
667            }
668            Role::System | Role::User => {}
669        }
670    }
671    Ok(())
672}
673
674#[derive(Debug, Clone, PartialEq)]
675enum AggregatedContent {
676    Text(String),
677    Chunks(Vec<Chunk>),
678}
679
680impl AggregatedContent {
681    fn is_empty(&self) -> bool {
682        match self {
683            AggregatedContent::Text(text) => text.is_empty(),
684            AggregatedContent::Chunks(chunks) => chunks.is_empty(),
685        }
686    }
687
688    fn has_think(&self) -> bool {
689        matches!(self, AggregatedContent::Chunks(chunks)
690            if chunks.iter().any(|c| matches!(c, Chunk::Think { .. })))
691    }
692}
693
694struct AggregatedMessage {
695    role: Role,
696    content: AggregatedContent,
697    tool_calls: Vec<ToolCall>,
698    tool_call_id: Option<String>,
699}
700
701/// mistral-common's `_aggregate_content_chunks_impl`: coalesce text across
702/// messages (joined with `MESSAGE_JOIN`) and within one message (joined with
703/// the version's chunk separator); thinking and image chunks stay separate.
704fn aggregate_content<'a>(
705    contents: impl IntoIterator<Item = Option<&'a Content>>,
706    chunk_join: &str,
707) -> AggregatedContent {
708    let mut chunks = Vec::new();
709    let mut text = String::new();
710    let mut has_text = false;
711
712    for content in contents {
713        let needs_message_join = has_text;
714        let Some(content) = content.filter(|content| !content.is_empty()) else {
715            continue;
716        };
717        match content {
718            Content::Text(part) => {
719                if needs_message_join {
720                    text.push_str(MESSAGE_JOIN);
721                }
722                text.push_str(part);
723                has_text = true;
724            }
725            Content::Chunks(parts) => {
726                let mut needs_message_join = needs_message_join;
727                for part in parts {
728                    match part {
729                        Chunk::Text(part) if part.is_empty() => {}
730                        Chunk::Text(part) => {
731                            if has_text {
732                                text.push_str(if needs_message_join {
733                                    MESSAGE_JOIN
734                                } else {
735                                    chunk_join
736                                });
737                            }
738                            text.push_str(part);
739                            has_text = true;
740                            needs_message_join = false;
741                        }
742                        other => {
743                            if has_text {
744                                chunks.push(Chunk::Text(std::mem::take(&mut text)));
745                                has_text = false;
746                            }
747                            chunks.push(other.clone());
748                        }
749                    }
750                }
751            }
752        }
753    }
754
755    if chunks.is_empty() {
756        return AggregatedContent::Text(text);
757    }
758    if has_text {
759        chunks.push(Chunk::Text(text));
760    }
761    AggregatedContent::Chunks(chunks)
762}
763
764/// mistral-common's `InstructRequestNormalizerV13/V15._aggregate_messages`.
765fn aggregate_messages(
766    messages: Vec<Message>,
767    version: MistralTokenizerVersion,
768) -> Vec<AggregatedMessage> {
769    let chunk_join = version.chunk_join();
770    let mut out: Vec<AggregatedMessage> = Vec::new();
771    let mut latest_call_ids: Vec<String> = Vec::new();
772
773    let mut groups: Vec<Vec<Message>> = Vec::new();
774    for message in messages {
775        match groups.last_mut() {
776            Some(group) if group[0].role == message.role => group.push(message),
777            _ => groups.push(vec![message]),
778        }
779    }
780
781    for group in groups {
782        let role = group[0].role;
783        match role {
784            Role::User => out.push(AggregatedMessage {
785                role,
786                content: aggregate_content(group.iter().map(|m| m.content.as_ref()), chunk_join),
787                tool_calls: Vec::new(),
788                tool_call_id: None,
789            }),
790            Role::Assistant => {
791                let content =
792                    aggregate_content(group.iter().map(|m| m.content.as_ref()), chunk_join);
793                let tool_calls: Vec<ToolCall> = group
794                    .into_iter()
795                    .flat_map(|m| m.tool_calls)
796                    .map(|call| ToolCall {
797                        arguments: normalize_arguments(&call.arguments),
798                        ..call
799                    })
800                    .collect();
801                latest_call_ids.extend(
802                    tool_calls
803                        .iter()
804                        .map(|call| call.id.clone().unwrap_or_else(|| "null".to_string())),
805                );
806                out.push(AggregatedMessage {
807                    role,
808                    content,
809                    tool_calls,
810                    tool_call_id: None,
811                });
812            }
813            Role::System => {
814                for message in group {
815                    out.push(AggregatedMessage {
816                        role,
817                        content: aggregate_content([message.content.as_ref()], chunk_join),
818                        tool_calls: Vec::new(),
819                        tool_call_id: None,
820                    });
821                }
822            }
823            Role::Tool => {
824                let mut tool_messages: Vec<AggregatedMessage> = group
825                    .into_iter()
826                    .map(|message| AggregatedMessage {
827                        role,
828                        content: aggregate_content([message.content.as_ref()], chunk_join),
829                        tool_calls: Vec::new(),
830                        tool_call_id: message.tool_call_id,
831                    })
832                    .collect();
833                sort_tool_messages(&mut tool_messages, &latest_call_ids);
834                out.extend(tool_messages);
835                // Reordering only depends on the latest assistant tool calls.
836                latest_call_ids.clear();
837            }
838        }
839    }
840
841    if out.is_empty() {
842        out.push(AggregatedMessage {
843            role: Role::User,
844            content: AggregatedContent::Text(String::new()),
845            tool_calls: Vec::new(),
846            tool_call_id: None,
847        });
848    }
849    out
850}
851
852/// Order tool results by the latest assistant call order, then by arrival
853/// (mistral-common's `_inplace_sort_tool_messages`; later duplicates win).
854fn sort_tool_messages(messages: &mut Vec<AggregatedMessage>, latest_call_ids: &[String]) {
855    let keys = {
856        let ids: Vec<Option<&str>> = messages
857            .iter()
858            .map(|message| message.tool_call_id.as_deref())
859            .collect();
860        tool_sort_keys(&ids, latest_call_ids)
861    };
862    let mut keyed: Vec<_> = keys.into_iter().zip(std::mem::take(messages)).collect();
863    keyed.sort_by_key(|(key, _)| *key);
864    messages.extend(keyed.into_iter().map(|(_, message)| message));
865}
866
867/// Sort keys of one run of tool results: the call's position among the
868/// latest assistant tool calls, then the last arrival of its call id.
869fn tool_sort_keys(ids: &[Option<&str>], latest_call_ids: &[String]) -> Vec<(usize, usize)> {
870    let call_index: HashMap<&str, usize> = latest_call_ids
871        .iter()
872        .enumerate()
873        .map(|(index, id)| (id.as_str(), index))
874        .collect();
875    let result_index: HashMap<Option<&str>, usize> = ids
876        .iter()
877        .enumerate()
878        .map(|(index, id)| (*id, index))
879        .collect();
880    ids.iter()
881        .map(|id| {
882            (
883                call_index
884                    .get(id.unwrap_or("null"))
885                    .copied()
886                    .unwrap_or(usize::MAX),
887                result_index[id],
888            )
889        })
890        .collect()
891}
892
893/// Source message indices in rendered order, mirroring `aggregate_messages`:
894/// only tool results move.
895fn rendered_message_order(messages: &[Message]) -> Vec<usize> {
896    let mut order = Vec::with_capacity(messages.len());
897    let mut latest_call_ids: Vec<String> = Vec::new();
898    let mut start = 0;
899    while start < messages.len() {
900        let role = messages[start].role;
901        let end = messages[start..]
902            .iter()
903            .position(|message| message.role != role)
904            .map_or(messages.len(), |len| start + len);
905        let run = &messages[start..end];
906        match role {
907            Role::Assistant => {
908                latest_call_ids.extend(
909                    run.iter()
910                        .flat_map(|message| &message.tool_calls)
911                        .map(|call| call.id.clone().unwrap_or_else(|| "null".to_string())),
912                );
913                order.extend(start..end);
914            }
915            Role::Tool => {
916                let ids: Vec<Option<&str>> = run
917                    .iter()
918                    .map(|message| message.tool_call_id.as_deref())
919                    .collect();
920                let mut keyed: Vec<_> = tool_sort_keys(&ids, &latest_call_ids)
921                    .into_iter()
922                    .zip(start..end)
923                    .collect();
924                keyed.sort_by_key(|(key, _)| *key);
925                order.extend(keyed.into_iter().map(|(_, index)| index));
926                latest_call_ids.clear();
927            }
928            Role::User | Role::System => order.extend(start..end),
929        }
930        start = end;
931    }
932    order
933}
934
935/// mistral-common's `_normalize_json_content` for tool-call arguments.
936fn normalize_arguments(arguments: &str) -> String {
937    if arguments.is_empty() {
938        return "{}".to_string();
939    }
940    match normalized_argument_json(arguments) {
941        Ok(value) => value,
942        Err(_) => arguments.to_string(),
943    }
944}
945
946/// The argument text the V13 encoder emits: parsed JSON re-dumped, or an
947/// unparseable string dumped as a JSON string.
948fn encoded_arguments(arguments: &str) -> String {
949    match normalized_argument_json(arguments) {
950        Ok(value) => value,
951        Err(_) => python_json(&Value::String(arguments.to_string())),
952    }
953}
954
955/// Borrow JSON values before numeric conversion: Python preserves unbounded
956/// integers, while decimal/exponent forms still use its ordinary float formatting.
957fn normalized_argument_json(arguments: &str) -> serde_json::Result<String> {
958    let value: &RawValue = serde_json::from_str(arguments)?;
959    let mut out = String::with_capacity(arguments.len());
960    write_argument_json(value, &mut out, 128)?;
961    Ok(out)
962}
963
964fn write_argument_json(
965    value: &RawValue,
966    out: &mut String,
967    remaining_depth: usize,
968) -> serde_json::Result<()> {
969    let raw = value.get();
970    // RawValue can borrow arbitrarily nested input; retain serde_json::Value's
971    // default depth bound before recursively formatting it.
972    if remaining_depth <= 1 && raw.starts_with(['{', '[']) {
973        return Err(<serde_json::Error as serde::de::Error>::custom(
974            "recursion limit exceeded",
975        ));
976    }
977    match raw.as_bytes()[0] {
978        b'{' => {
979            let object: ArgumentObject<'_> = serde_json::from_str(raw)?;
980            out.push('{');
981            for (index, (key, value)) in object.0.into_iter().enumerate() {
982                if index > 0 {
983                    out.push_str(", ");
984                }
985                out.push_str(&python_json(&Value::String(key)));
986                out.push_str(": ");
987                write_argument_json(value, out, remaining_depth - 1)?;
988            }
989            out.push('}');
990        }
991        b'[' => {
992            let values: Vec<&RawValue> = serde_json::from_str(raw)?;
993            out.push('[');
994            for (index, value) in values.into_iter().enumerate() {
995                if index > 0 {
996                    out.push_str(", ");
997                }
998                write_argument_json(value, out, remaining_depth - 1)?;
999            }
1000            out.push(']');
1001        }
1002        b'-' | b'0'..=b'9' if !raw.contains(['.', 'e', 'E']) => {
1003            out.push_str(if raw == "-0" { "0" } else { raw });
1004        }
1005        b'-' | b'0'..=b'9' => {
1006            let number: f64 = serde_json::from_str(raw)?;
1007            out.push_str(&python_json(&Value::from(number)));
1008        }
1009        _ => out.push_str(&python_json(&serde_json::from_str(raw)?)),
1010    }
1011    Ok(())
1012}
1013
1014/// A Python dict keeps a duplicate key's first position and last value.
1015struct ArgumentObject<'a>(Vec<(String, &'a RawValue)>);
1016
1017impl<'de> Deserialize<'de> for ArgumentObject<'de> {
1018    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
1019    where
1020        D: serde::Deserializer<'de>,
1021    {
1022        struct ObjectVisitor;
1023
1024        impl<'de> Visitor<'de> for ObjectVisitor {
1025            type Value = ArgumentObject<'de>;
1026
1027            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1028                formatter.write_str("a JSON object")
1029            }
1030
1031            fn visit_map<M>(self, mut map: M) -> std::result::Result<Self::Value, M::Error>
1032            where
1033                M: MapAccess<'de>,
1034            {
1035                let mut fields: Vec<(String, &'de RawValue)> = Vec::new();
1036                let mut positions: HashMap<String, usize> = HashMap::new();
1037                while let Some((key, value)) = map.next_entry::<String, &'de RawValue>()? {
1038                    if let Some(&index) = positions.get(&key) {
1039                        fields[index].1 = value;
1040                    } else {
1041                        positions.insert(key.clone(), fields.len());
1042                        fields.push((key, value));
1043                    }
1044                }
1045                Ok(ArgumentObject(fields))
1046            }
1047        }
1048
1049        deserializer.deserialize_map(ObjectVisitor)
1050    }
1051}
1052
1053/// `json.dumps` of the tools as mistral-common's `Tool.model_dump` (without
1054/// `strict`), or `None` when there are no tools.
1055fn render_tools(tools: Option<&Value>) -> Result<Option<String>> {
1056    let Some(tools) = tools
1057        .and_then(Value::as_array)
1058        .filter(|tools| !tools.is_empty())
1059    else {
1060        return Ok(None);
1061    };
1062    let mut rendered = Vec::with_capacity(tools.len());
1063    for tool in tools {
1064        let function = tool
1065            .get("function")
1066            .ok_or_else(|| invalid("tools must be function tools"))?;
1067        let name = function
1068            .get("name")
1069            .and_then(Value::as_str)
1070            .ok_or_else(|| invalid("tool functions need a name"))?;
1071        let description = function
1072            .get("description")
1073            .and_then(Value::as_str)
1074            .unwrap_or_default();
1075        let parameters = function
1076            .get("parameters")
1077            .filter(|parameters| !parameters.is_null())
1078            .cloned()
1079            .unwrap_or_else(|| Value::Object(Map::new()));
1080        let mut function = Map::new();
1081        function.insert("name".to_string(), name.into());
1082        function.insert("description".to_string(), description.into());
1083        function.insert("parameters".to_string(), parameters);
1084        let mut tool = Map::new();
1085        tool.insert("type".to_string(), "function".into());
1086        tool.insert("function".to_string(), Value::Object(function));
1087        rendered.push(Value::Object(tool));
1088    }
1089    Ok(Some(python_json(&Value::Array(rendered))))
1090}
1091
1092/// The JSON schema a `response_format` asks for, following upstream vLLM's
1093/// `to_mistral_response_format`: `json_object` allows any object or array,
1094/// `json_schema` uses its schema, everything else adds nothing.
1095fn response_schema(response_format: Option<&Value>) -> Option<Value> {
1096    let response_format = response_format?;
1097    match response_format.get("type").and_then(Value::as_str)? {
1098        "json_object" => Some(serde_json::json!({
1099            "anyOf": [{"type": "object"}, {"type": "array"}]
1100        })),
1101        "json_schema" => response_format
1102            .get("json_schema")
1103            .and_then(|schema| schema.get("schema"))
1104            .filter(|schema| !schema.is_null())
1105            .cloned(),
1106        _ => None,
1107    }
1108}
1109
1110/// `reasoning_effort` from `chat_template_args` (where Dynamo normalizes the
1111/// top-level field) or from the request's own top-level field.
1112fn requested_reasoning_effort(req: &dyn OAIChatLikeRequest) -> Result<Option<String>> {
1113    let value = match req
1114        .chat_template_args()
1115        .and_then(|args| args.get("reasoning_effort"))
1116    {
1117        Some(value) => Some(value.clone()),
1118        None => req
1119            .reasoning_effort()
1120            .map(|value| serde_json::to_value(&value))
1121            .transpose()
1122            .context("Failed to convert reasoning_effort")?,
1123    };
1124    match value {
1125        None | Some(Value::Null) => Ok(None),
1126        Some(Value::String(effort)) => Ok(Some(effort)),
1127        Some(other) => Err(invalid(format!(
1128            "reasoning_effort must be a string, got {other}"
1129        ))),
1130    }
1131}
1132
1133#[cfg(test)]
1134mod tests {
1135    use super::*;
1136    use minijinja::value::Value as MiniValue;
1137    use serde_json::json;
1138
1139    struct Request {
1140        messages: Value,
1141        tools: Option<Value>,
1142        raw_tools: Option<Value>,
1143        response_format: Option<Value>,
1144        args: HashMap<String, Value>,
1145        add_generation_prompt: bool,
1146    }
1147
1148    impl Request {
1149        fn new(messages: Value) -> Self {
1150            Self {
1151                messages,
1152                tools: None,
1153                raw_tools: None,
1154                response_format: None,
1155                args: HashMap::new(),
1156                add_generation_prompt: true,
1157            }
1158        }
1159    }
1160
1161    impl OAIChatLikeRequest for Request {
1162        fn model(&self) -> String {
1163            "mistral".to_string()
1164        }
1165
1166        fn messages(&self) -> MiniValue {
1167            MiniValue::from_serialize(&self.messages)
1168        }
1169
1170        fn tools(&self) -> Option<MiniValue> {
1171            self.tools.as_ref().map(MiniValue::from_serialize)
1172        }
1173
1174        fn raw_tools(&self) -> Option<MiniValue> {
1175            self.raw_tools.as_ref().map(MiniValue::from_serialize)
1176        }
1177
1178        fn response_format(&self) -> Option<MiniValue> {
1179            self.response_format.as_ref().map(MiniValue::from_serialize)
1180        }
1181
1182        fn should_add_generation_prompt(&self) -> bool {
1183            self.add_generation_prompt
1184        }
1185
1186        fn chat_template_args(&self) -> Option<&HashMap<String, Value>> {
1187            Some(&self.args)
1188        }
1189    }
1190
1191    fn settings_builder() -> Value {
1192        json!({
1193            "reasoning_effort": {"type": "enum", "accepts_none": true, "default": "none", "values": ["none", "high"]},
1194            "json_schema": {"type": "json_schema", "accepts_none": false, "default": null}
1195        })
1196    }
1197
1198    fn v15() -> MistralFormatter {
1199        MistralFormatter::new(15, Some(&settings_builder())).unwrap()
1200    }
1201
1202    fn math_tool() -> Value {
1203        json!([{
1204            "type": "function",
1205            "function": {
1206                "name": "math_interpreter",
1207                "description": "Get the value of an arithmetic expression.",
1208                "parameters": {"type": "object", "properties": {"expression": {"type": "string", "description": "Math expression."}}}
1209            }
1210        }])
1211    }
1212
1213    /// mistral-common `tests/test_tokenizer_v15.py::EXPECTED_TEXT_V15`.
1214    #[test]
1215    fn matches_mistral_common_v15_golden_conversation() {
1216        let mut request = Request::new(json!([
1217            {"role": "system", "content": "S"},
1218            {"role": "user", "content": "U1"},
1219            {"role": "assistant", "content": "A1", "tool_calls": [
1220                {"id": "123456789", "type": "function", "function": {"name": "F1", "arguments": "{}"}},
1221                {"id": "999999999", "type": "function", "function": {"name": "F2", "arguments": "{}"}}
1222            ]},
1223            {"role": "tool", "tool_call_id": "123456789", "content": "R1"},
1224            {"role": "tool", "tool_call_id": "999999999", "content": "R2"},
1225            {"role": "assistant", "content": "A2"},
1226            {"role": "user", "content": "U2"}
1227        ]));
1228        request.tools = Some(math_tool());
1229        request
1230            .args
1231            .insert("reasoning_effort".to_string(), json!("high"));
1232
1233        let rendered = v15().render(&request).unwrap();
1234        assert_eq!(
1235            rendered,
1236            concat!(
1237                "<s>[SYSTEM_PROMPT]S[/SYSTEM_PROMPT]",
1238                r#"[AVAILABLE_TOOLS][{"type": "function", "function": {"name": "math_interpreter","#,
1239                r#" "description": "Get the value of an arithmetic expression.","#,
1240                r#" "parameters": {"type": "object", "properties": {"expression":"#,
1241                r#" {"type": "string", "description": "Math expression."}}}}}]"#,
1242                r#"[/AVAILABLE_TOOLS][MODEL_SETTINGS]{"reasoning_effort": "high"}[/MODEL_SETTINGS]"#,
1243                "[INST]U1[/INST]A1",
1244                "[TOOL_CALLS]F1[ARGS]{}[TOOL_CALLS]F2[ARGS]{}</s>",
1245                "[TOOL_RESULTS]R1[/TOOL_RESULTS]",
1246                "[TOOL_RESULTS]R2[/TOOL_RESULTS]A2</s>",
1247                "[INST]U2[/INST]",
1248            )
1249        );
1250    }
1251
1252    #[test]
1253    fn defaults_and_response_format_fill_model_settings() {
1254        let mut request = Request::new(json!([{"role": "user", "content": "hi"}]));
1255        assert_eq!(
1256            v15().render(&request).unwrap(),
1257            r#"<s>[MODEL_SETTINGS]{"reasoning_effort": "none"}[/MODEL_SETTINGS][INST]hi[/INST]"#
1258        );
1259
1260        request.response_format = Some(json!({"type": "json_object"}));
1261        request
1262            .args
1263            .insert("reasoning_effort".to_string(), json!("high"));
1264        assert_eq!(
1265            v15().render(&request).unwrap(),
1266            concat!(
1267                r#"<s>[MODEL_SETTINGS]{"json_schema": {"anyOf": [{"type": "object"}, {"type": "array"}]}, "#,
1268                r#""reasoning_effort": "high"}[/MODEL_SETTINGS][INST]hi[/INST]"#
1269            )
1270        );
1271
1272        request
1273            .args
1274            .insert("reasoning_effort".to_string(), json!("low"));
1275        let error = v15().render(&request).unwrap_err();
1276        assert!(
1277            error.downcast_ref::<PromptRenderError>().is_some(),
1278            "{error}"
1279        );
1280    }
1281
1282    #[test]
1283    fn user_text_that_looks_like_markers_stays_ordinary() {
1284        let request = Request::new(json!([{"role": "user", "content": "say [INST] and </s>"}]));
1285        let prompt = v15().render_prompt(&request).unwrap();
1286        let segments = prompt.segments().unwrap();
1287        let user = segments
1288            .iter()
1289            .find(|segment| segment.text == "say [INST] and </s>")
1290            .unwrap();
1291        assert!(!user.allow_special);
1292        assert!(
1293            segments
1294                .iter()
1295                .filter(|segment| segment.allow_special)
1296                .all(|segment| segment.text.starts_with(['[', '<']))
1297        );
1298    }
1299
1300    #[test]
1301    fn reasoning_history_and_merged_turns() {
1302        let request = Request::new(json!([
1303            {"role": "user", "content": "a"},
1304            {"role": "user", "content": [{"type": "text", "text": "b"}, {"type": "text", "text": "c"}]},
1305            {"role": "assistant", "reasoning_content": "think", "content": "answer  "},
1306            {"role": "user", "content": "next"}
1307        ]));
1308        assert_eq!(
1309            v15().render(&request).unwrap(),
1310            concat!(
1311                r#"<s>[MODEL_SETTINGS]{"reasoning_effort": "none"}[/MODEL_SETTINGS]"#,
1312                "[INST]a\n\nbc[/INST][THINK]think[/THINK]answer  </s>[INST]next[/INST]"
1313            )
1314        );
1315    }
1316
1317    #[test]
1318    fn segmented_reasoning_drops_empty_segments() {
1319        // Anthropic and Responses conversions emit one segment per tool call,
1320        // empty where no reasoning preceded that call.
1321        let request = Request::new(json!([
1322            {"role": "user", "content": "go"},
1323            {"role": "assistant", "reasoning_content": ["plan", "", ""], "tool_calls": [
1324                {"id": "aaaaaaaaa", "type": "function", "function": {"name": "f", "arguments": "{}"}},
1325                {"id": "bbbbbbbbb", "type": "function", "function": {"name": "g", "arguments": "{}"}}
1326            ]},
1327            {"role": "tool", "tool_call_id": "aaaaaaaaa", "content": "A"},
1328            {"role": "tool", "tool_call_id": "bbbbbbbbb", "content": "B"}
1329        ]));
1330        let rendered = v15().render(&request).unwrap();
1331        assert!(
1332            rendered.contains("[INST]go[/INST][THINK]plan[/THINK][TOOL_CALLS]f"),
1333            "{rendered}"
1334        );
1335    }
1336
1337    #[test]
1338    fn tool_results_follow_call_order_and_arguments_normalize() {
1339        let request = Request::new(json!([
1340            {"role": "user", "content": "go"},
1341            {"role": "assistant", "tool_calls": [
1342                {"id": "aaaaaaaaa", "type": "function", "function": {"name": "f", "arguments": "{\"x\":1,  \"y\":[2]}"}},
1343                {"id": "bbbbbbbbb", "type": "function", "function": {"name": "g", "arguments": ""}},
1344                {"id": "ccccccccc", "type": "function", "function": {"name": "h", "arguments": "not json"}}
1345            ]},
1346            {"role": "tool", "tool_call_id": "bbbbbbbbb", "content": "B"},
1347            {"role": "tool", "tool_call_id": "aaaaaaaaa", "content": "A"}
1348        ]));
1349        assert_eq!(
1350            v15().render(&request).unwrap(),
1351            concat!(
1352                r#"<s>[MODEL_SETTINGS]{"reasoning_effort": "none"}[/MODEL_SETTINGS][INST]go[/INST]"#,
1353                r#"[TOOL_CALLS]f[ARGS]{"x": 1, "y": [2]}[TOOL_CALLS]g[ARGS]{}"#,
1354                r#"[TOOL_CALLS]h[ARGS]"not json"</s>"#,
1355                "[TOOL_RESULTS]A[/TOOL_RESULTS][TOOL_RESULTS]B[/TOOL_RESULTS]",
1356            )
1357        );
1358    }
1359
1360    #[test]
1361    fn tool_history_keeps_large_integers_and_python_float_normalization() {
1362        let arguments = concat!(
1363            r#"{"n":18446744073709551617,"nested":[-9223372036854775809,"#,
1364            r#"0.1000000000000000055511151231257827,-0,-0.0,1E2],"#,
1365            r#""duplicate":1,"last":"é","duplicate":18446744073709551618}"#,
1366        );
1367        let expected = concat!(
1368            r#"{"n": 18446744073709551617, "nested": [-9223372036854775809, "#,
1369            r#"0.1, 0, -0.0, 100.0], "duplicate": 18446744073709551618, "last": "é"}"#,
1370        );
1371        assert_eq!(normalize_arguments(arguments), expected);
1372        assert_eq!(encoded_arguments(&normalize_arguments(arguments)), expected);
1373        let request = Request::new(json!([
1374            {"role": "user", "content": "go"},
1375            {"role": "assistant", "tool_calls": [
1376                {"id": "aaaaaaaaa", "type": "function", "function": {"name": "f", "arguments": arguments}}
1377            ]},
1378            {"role": "tool", "tool_call_id": "aaaaaaaaa", "content": "done"}
1379        ]));
1380        assert!(v15().render(&request).unwrap().ends_with(&format!(
1381            "[TOOL_CALLS]f[ARGS]{expected}</s>[TOOL_RESULTS]done[/TOOL_RESULTS]"
1382        )));
1383    }
1384
1385    #[test]
1386    fn argument_normalization_retains_the_depth_bound_and_invalid_fallback() {
1387        for depth in [127, 128] {
1388            let nested = format!("{}0{}", "[".repeat(depth), "]".repeat(depth));
1389            assert_eq!(
1390                normalized_argument_json(&nested).is_ok(),
1391                serde_json::from_str::<Value>(&nested).is_ok()
1392            );
1393        }
1394        assert_eq!(encoded_arguments("not json"), r#""not json""#);
1395    }
1396
1397    fn assistant_calls(ids: &[&str]) -> Value {
1398        json!({"role": "assistant", "tool_calls": ids.iter().map(|id| json!({
1399            "id": id, "type": "function", "function": {"name": "f", "arguments": "{}"}
1400        })).collect::<Vec<_>>()})
1401    }
1402
1403    fn tool_result(id: &str) -> Value {
1404        json!({"role": "tool", "tool_call_id": id, "content": "result"})
1405    }
1406
1407    #[test]
1408    fn rejects_mismatched_duplicate_and_unanswered_tool_histories() {
1409        let user = json!({"role": "user", "content": "go"});
1410        let answer = json!({"role": "assistant", "content": "answer"});
1411        let a = "aaaaaaaaa";
1412        let b = "bbbbbbbbb";
1413        let cases = [
1414            json!([user, assistant_calls(&[a]), tool_result(b)]),
1415            json!([user, assistant_calls(&[a]), tool_result(a), tool_result(a)]),
1416            json!([user, assistant_calls(&[a, a]), tool_result(a)]),
1417            json!([user, assistant_calls(&[a]), answer, user]),
1418            json!([user, assistant_calls(&[a]), user, answer, user]),
1419            json!([
1420                user,
1421                assistant_calls(&[a]),
1422                tool_result(a),
1423                assistant_calls(&[b]),
1424                tool_result(a)
1425            ]),
1426        ];
1427        for messages in cases {
1428            let error = v15().render(&Request::new(messages.clone())).unwrap_err();
1429            assert!(
1430                error.downcast_ref::<PromptRenderError>().is_some(),
1431                "{messages}: {error}"
1432            );
1433        }
1434    }
1435
1436    #[test]
1437    fn trailing_tool_calls_can_be_unanswered_and_completed_ids_can_be_reused() {
1438        let user = json!({"role": "user", "content": "go"});
1439        let a = "aaaaaaaaa";
1440        let b = "bbbbbbbbb";
1441        // The reference's test mode permits an incomplete final tool turn.
1442        for messages in [
1443            json!([user, assistant_calls(&[a]), user]),
1444            json!([user, assistant_calls(&[a, b]), tool_result(a)]),
1445            json!([
1446                user,
1447                assistant_calls(&[a]),
1448                tool_result(a),
1449                assistant_calls(&[a]),
1450                tool_result(a)
1451            ]),
1452        ] {
1453            v15().render(&Request::new(messages)).unwrap();
1454        }
1455        let mut continuation = Request::new(json!([user, assistant_calls(&[a])]));
1456        continuation.add_generation_prompt = false;
1457        assert!(
1458            v15()
1459                .render(&continuation)
1460                .unwrap()
1461                .ends_with("[TOOL_CALLS]f[ARGS]{}")
1462        );
1463    }
1464
1465    #[test]
1466    fn v13_has_no_settings_and_joins_chunks_with_blank_lines() {
1467        let formatter = MistralFormatter::new(13, None).unwrap();
1468        let mut request = Request::new(json!([
1469            {"role": "user", "content": [{"type": "text", "text": "b"}, {"type": "text", "text": "c"}]}
1470        ]));
1471        request
1472            .args
1473            .insert("reasoning_effort".to_string(), json!("high"));
1474        assert_eq!(
1475            formatter.render(&request).unwrap(),
1476            "<s>[INST]b\n\nc[/INST]"
1477        );
1478    }
1479
1480    #[test]
1481    fn rejects_invalid_conversations() {
1482        let cases = [
1483            json!([]),
1484            json!([{"role": "assistant", "content": "hi"}]),
1485            json!([{"role": "user", "content": "hi"}, {"role": "tool", "tool_call_id": "x", "content": "r"}]),
1486            json!([{"role": "user", "content": "hi"}, {"role": "assistant", "content": "yo"}]),
1487            json!([{"role": "system", "content": [{"type": "image_url", "image_url": {"url": "x"}}]},
1488                {"role": "user", "content": "hi"}]),
1489            json!([{"role": "user", "content": "hi"},
1490                {"role": "assistant", "content": [{"type": "image_url", "image_url": {"url": "x"}}]},
1491                {"role": "user", "content": "hi"}]),
1492            json!([{"role": "user", "content": [{"type": "image_url", "image_url": {}}]}]),
1493        ];
1494        for messages in cases {
1495            let error = v15().render(&Request::new(messages.clone())).unwrap_err();
1496            assert!(
1497                error.downcast_ref::<PromptRenderError>().is_some(),
1498                "{messages}: {error}"
1499            );
1500        }
1501    }
1502
1503    fn image(url: &str) -> Value {
1504        json!({"type": "image_url", "image_url": {"url": url}})
1505    }
1506
1507    fn text(text: &str) -> Value {
1508        json!({"type": "text", "text": text})
1509    }
1510
1511    /// Placement follows mistral-common's normalizer and `_maybe_put_image_first`.
1512    #[test]
1513    fn images_render_as_control_placeholders() {
1514        let user = |content: Value| {
1515            let rendered = v15()
1516                .render(&Request::new(json!([{"role": "user", "content": content}])))
1517                .unwrap();
1518            rendered
1519                .strip_prefix(r#"<s>[MODEL_SETTINGS]{"reasoning_effort": "none"}[/MODEL_SETTINGS]"#)
1520                .unwrap()
1521                .to_string()
1522        };
1523        // An image after only text moves first.
1524        assert_eq!(
1525            user(json!([text("What is "), text("this?"), image("a")])),
1526            "[INST][IMG]What is this?[/INST]"
1527        );
1528        assert_eq!(
1529            user(json!([image("a"), text("What is this?")])),
1530            "[INST][IMG]What is this?[/INST]"
1531        );
1532        // Otherwise images stay in place and split the text.
1533        assert_eq!(
1534            user(json!([text("x"), image("a"), image("b")])),
1535            "[INST]x[IMG][IMG][/INST]"
1536        );
1537        assert_eq!(
1538            user(json!([text("x"), image("a"), text("y")])),
1539            "[INST]x[IMG]y[/INST]"
1540        );
1541        assert_eq!(
1542            user(json!([{"type": "image_url", "image_url": "data:image/png;base64,AA"}])),
1543            "[INST][IMG][/INST]"
1544        );
1545
1546        let request =
1547            Request::new(json!([{"role": "user", "content": [text("[IMG]"), image("a")]}]));
1548        let prompt = v15().render_prompt(&request).unwrap();
1549        let segments = prompt.segments().unwrap();
1550        let placeholders: Vec<_> = segments
1551            .iter()
1552            .filter(|segment| segment.text == IMG)
1553            .map(|segment| segment.allow_special)
1554            .collect();
1555        // The literal user text stays ordinary; only the image is a control token.
1556        assert_eq!(placeholders, [true, false]);
1557    }
1558
1559    #[test]
1560    fn merged_user_turns_put_a_trailing_image_first() {
1561        let request = Request::new(json!([
1562            {"role": "user", "content": "a"},
1563            {"role": "user", "content": [image("x")]}
1564        ]));
1565        assert!(
1566            v15()
1567                .render(&request)
1568                .unwrap()
1569                .ends_with("[INST][IMG]a[/INST]"),
1570            "{}",
1571            v15().render(&request).unwrap()
1572        );
1573        assert_eq!(v15().media_message_order(&request), None);
1574    }
1575
1576    #[test]
1577    fn tool_result_images_follow_the_reordered_results() {
1578        let request = Request::new(json!([
1579            {"role": "user", "content": "go"},
1580            {"role": "assistant", "tool_calls": [
1581                {"id": "aaaaaaaaa", "type": "function", "function": {"name": "f", "arguments": "{}"}},
1582                {"id": "bbbbbbbbb", "type": "function", "function": {"name": "g", "arguments": "{}"}}
1583            ]},
1584            {"role": "tool", "tool_call_id": "bbbbbbbbb", "content": [text("B"), image("b")]},
1585            {"role": "tool", "tool_call_id": "aaaaaaaaa", "content": [image("a"), text("A")]}
1586        ]));
1587        assert!(
1588            v15().render(&request).unwrap().ends_with(concat!(
1589                "[TOOL_RESULTS][IMG]A[/TOOL_RESULTS]",
1590                "[TOOL_RESULTS]B[IMG][/TOOL_RESULTS]"
1591            )),
1592            "{}",
1593            v15().render(&request).unwrap()
1594        );
1595        assert_eq!(v15().media_message_order(&request), Some(vec![0, 1, 3, 2]));
1596
1597        // Results already in call order keep arrival order.
1598        let in_order = Request::new(json!([
1599            {"role": "user", "content": "go"},
1600            {"role": "assistant", "tool_calls": [
1601                {"id": "aaaaaaaaa", "type": "function", "function": {"name": "f", "arguments": "{}"}}
1602            ]},
1603            {"role": "tool", "tool_call_id": "aaaaaaaaa", "content": [image("a")]}
1604        ]));
1605        assert_eq!(v15().media_message_order(&in_order), None);
1606    }
1607
1608    #[test]
1609    fn continued_final_assistant_turn_is_an_open_prefix() {
1610        let mut request = Request::new(json!([
1611            {"role": "user", "content": "Give JSON"},
1612            {"role": "assistant", "content": "```json\n  "}
1613        ]));
1614        request.add_generation_prompt = false;
1615        // mistral-common `prefix=True`: trailing spaces stripped, newline kept, no `</s>`.
1616        let rendered = v15().render(&request).unwrap();
1617        assert!(
1618            rendered.ends_with("[INST]Give JSON[/INST]```json\n"),
1619            "{rendered}"
1620        );
1621    }
1622
1623    #[test]
1624    fn client_tools_win_over_the_jinja_backfill() {
1625        let mut request = Request::new(json!([{"role": "user", "content": "now?"}]));
1626        request.raw_tools =
1627            Some(json!([{"type": "function", "function": {"name": "now", "parameters": {}}}]));
1628        request.tools = Some(json!([{"type": "function", "function": {
1629            "name": "now", "description": "", "parameters": {"type": "object", "properties": {}}
1630        }}]));
1631        let rendered = v15().render(&request).unwrap();
1632        assert!(
1633            rendered.contains(r#"{"name": "now", "description": "", "parameters": {}}"#),
1634            "{rendered}"
1635        );
1636    }
1637
1638    #[test]
1639    fn rejects_unsupported_versions_and_missing_v15_builder() {
1640        assert!(MistralFormatter::new(11, None).is_err());
1641        assert!(MistralFormatter::new(15, None).is_err());
1642        assert!(MistralFormatter::new(15, Some(&json!({"unknown": {}}))).is_err());
1643    }
1644}