mistral_common.integrations.chat_templates.template_generator

TemplateConfig(version, spm=False, image_support=False, audio_support=False, thinking_support=False, plain_thinking_support=False, use_special_token_variables=False) dataclass

Configuration for generating a chat template.

This class encapsulates all the configuration options required to generate a Jinja2 chat template that formats conversation messages for Mistral models. The template handles message roles, special tokens, tool calls, and multimodal content.

Attributes:

Name	Type	Description
version	TokenizerVersion	The tokenizer version (e.g., v1, v2, v3, v7, v11, v13, v15). Determines special token formatting, tool call syntax, and available features.
spm	bool	Whether to use SentencePiece tokenizer formatting. When True, adds spaces after special tokens. Not supported for versions v11+ or with audio.
image_support	bool	Whether to enable image chunk processing in user messages. Adds [IMG] token support. Requires version v3+. Mutually exclusive with audio.
audio_support	bool	Whether to enable audio chunk processing in user messages. Adds [AUDIO] token support. Requires version v7+. Mutually exclusive with image.
thinking_support	bool	Whether to enable thinking chunks in system and assistant messages. Adds [THINK]/[/THINK] token support. Requires version v13+.
plain_thinking_support	bool	Whether to enable plain text thinking chunks using <think>/</think> tags instead of special tokens. Only available for v11. Mutually exclusive with thinking_support.
use_special_token_variables	bool	Whether to emit BOS/EOS as Jinja variable references (bos_token/eos_token) or as literal string values ('<s>'/'</s>'). When True, the template expects bos_token and eos_token to be passed as render kwargs.

Raises:

Type	Description
ValueError	If the configuration is invalid (e.g., conflicting options like spm with v11+, image and audio together, or version requirements not met).

Examples:

>>> config = TemplateConfig(version=TokenizerVersion.v3, image_support=True)
>>> config.image_support
True
>>> config.version == TokenizerVersion.v3
True

any_thinking_support property

Whether any form of thinking support is enabled.

bos_expr property

Jinja expression for the BOS token.

eos_expr property

Jinja expression for the EOS token.

forbids_assistant_content_with_tools property

Whether assistant messages cannot have both content and tool calls.

has_tools property

Whether tool definitions are supported.

is_v1 property

Whether this is a v1 template with minimal features.

spm_system_prompt_has_space property

Whether SPM system prompt tokens have trailing space.

supports_model_settings property

Whether model settings (reasoning_effort) are supported. V15+.

system_supports_thinking property

Whether system messages support thinking chunks. Pre-v15 only.

tools_at_beginning property

Whether tools definition is emitted at the beginning.

tracks_has_sp_for_audio property

Whether to track has_sp for audio constraint. V15+ allows audio with system prompts.

tracks_max_idx_user property

Whether to track max user index for tools definition placement.

uses_call_id_in_tool_calls property

Whether to include [CALL_ID] in tool calls.

uses_json_tool_results property

Whether tool results use JSON format with content/call_id.

uses_simple_tool_results property

Whether tool results use simple [TOOL_RESULTS]content format.

uses_spm_prev_img_tracking property

Whether to track prev_img for SPM image formatting.

uses_spm_space_tracking property

Whether to track add_space for SPM formatting.

uses_system_prompt_tokens property

Whether to use [SYSTEM_PROMPT] tokens vs inline system message.

uses_tool_content_format property

Whether tool results use [TOOL_RESULTS]id[TOOL_CONTENT]content format.

uses_v13_tool_format property

Whether to use v13-style tool calls (name[ARGS]arguments).

uses_v2_spm_tool_format property

Whether to use v2_spm tool format (no ID, uses name in results).

uses_v2_tool_format property

Whether to use v2 tool format (no ID, uses name in results, elif branch).

uses_v2_v3spm_tool_branch property

Whether assistant tool calls use the v2/v3-SPM inline elif branch.

validates_assistant_non_empty property

Whether to validate that assistant messages have non-empty content or tool calls.

build_chat_template(config)

Generate a complete chat template based on configuration.

Parameters:

Name	Type	Description	Default
config	TemplateConfig	Template configuration specifying version and features.	required

Returns:

Type	Description
str	The complete Jinja2 template as a string.

Examples:

>>> config = TemplateConfig(version=TokenizerVersion.v3, image_support=True, use_special_token_variables=True)
>>> template = build_chat_template(config)
>>> "bos_token" in template
True

Source code in src/mistral_common/integrations/chat_templates/template_generator.py

def build_chat_template(config: TemplateConfig) -> str:
    r"""Generate a complete chat template based on configuration.

    Args:
        config: Template configuration specifying version and features.

    Returns:
        The complete Jinja2 template as a string.

    Examples:
        >>> config = TemplateConfig(version=TokenizerVersion.v3, image_support=True, use_special_token_variables=True)
        >>> template = build_chat_template(config)
        >>> "bos_token" in template
        True
    """
    if config.is_v1:
        return _generate_v1_template(config)

    parts = []
    parts.append(_generate_header(config))
    parts.append(_generate_system_prompt_handling(config))
    parts.append(_generate_available_tools_definition(config))

    macros = _generate_macros(config)
    if macros:
        parts.append(macros)

    parts.append(_generate_message_aggregation(config))
    parts.append(_generate_alternation_check(config))
    parts.append("")
    parts.append(_generate_message_loop(config))
    parts.append("")

    return "\n".join(parts)