Skip to content

# `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_audio` `property`

Whether system messages can contain audio. V15+ with audio support.

### `system_supports_thinking` `property`

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

### `tool_supports_multimodal` `property`

Whether tool messages can contain non-text content chunks. V15+.

### `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`

    1842
    1843
    1844
    1845
    1846
    1847
    1848
    1849
    1850
    1851
    1852
    1853
    1854
    1855
    1856
    1857
    1858
    1859
    1860
    1861
    1862
    1863
    1864
    1865
    1866
    1867
    1868
    1869
    1870
    1871
    1872
    1873
    1874
    1875

    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)