Builtin Structural Tag¶

This page contains the API reference for the structural tag template function. For its usage, see Tool Calling and Reasoning.

Global Functions¶

The main public entry points are:

`get_model_structural_tag`(model[, tools, ...])	Get a structural tag for a model's reasoning and tool-call output format.
`normalize_tool_choice`([tools, tool_choice])	Normalize tools and tool choice for structural tag builders.
`register_model_structural_tag`(name)	Register a model-specific structural tag function under name.

xgrammar.builtin_structural_tag.get_builtin_structural_tag: Deprecated alias for get_model_structural_tag().

All APIs¶

The remaining model-specific structural tag builders are generated from xgrammar.builtin_structural_tag automatically.

Functions:

`get_model_structural_tag`(model[, tools, ...])	Get a structural tag for a model's reasoning and tool-call output format.
`normalize_tool_choice`([tools, tool_choice])	Normalize tools and tool choice for structural tag builders.
`register_model_structural_tag`(name)	Register a model-specific structural tag function under name.
`get_llama_structural_tag`([tools, ...])	Get Llama style structural tag format.
`get_kimi_structural_tag`([tools, ...])	Get Kimi-K2 style structural tag format.
`get_deepseek_r1_structural_tag`([tools, ...])	Get DeepSeek-R1 style structural tag format.
`get_deepseek_v3_1_structural_tag`([tools, ...])	Get DeepSeek-V3.1 style structural tag format.
`get_qwen_3_5_structural_tag`([tools, ...])	Get Qwen XML tool-call structural tag format.
`get_qwen_3_coder_structural_tag`([tools, ...])	Deprecated alias for `get_qwen_3_5_structural_tag()`.
`get_qwen_3_structural_tag`([tools, ...])	Get Qwen3 style structural tag format.
`get_harmony_structural_tag`([tools, ...])	Get harmony(gpt-oss) style structural tag format.
`get_deepseek_v3_2_structural_tag`([tools, ...])	Get DeepSeek-V3.2 style structural tag format.
`get_minimax_structural_tag`([tools, ...])	Get MiniMax-M2.5 style structural tag format.
`get_glm_4_7_structural_tag`([tools, ...])	Get GLM-4.7/GLM-5 style structural tag format.
`get_deepseek_v4_structural_tag`([tools, ...])	Get DeepSeek-V4 style structural tag format.
`get_builtin_structural_tag`(model[, tools, ...])	Alias for `get_model_structural_tag()`.

xgrammar.builtin_structural_tag.get_model_structural_tag(model: str, tools: Optional[List[Union[FunctionToolParam, BuiltinToolParam, dict]]] = None, tool_choice: Optional[Union[Literal['none', 'auto', 'required'], NamedToolChoiceParam, AllowedToolChoiceParam, BuiltinToolChoiceParam, dict]] = 'auto', reasoning: bool = True, force_reasoning: bool = False) → StructuralTag[source]¶

Get a structural tag for a model’s reasoning and tool-call output format.

Use this function when a serving engine needs a structural tag that matches a model’s tool-call syntax. Pass the model format, the available tools, and the desired tool choice policy.

This API is designed to resemble OpenAI Chat Completions API.

Function tools use the OpenAI Chat Completions shape: {"type": "function", "function": {...}}.

Builtin tools use a compact shape:

type is the provider-level builtin tool type, such as "web_search_preview".
name is the exact tool name that may appear in model output. If it is omitted, type is used as the output name.
parameters is the JSON schema used to constrain the arguments emitted by the model.

Examples

Ordinary function tool:

structural_tag = get_model_structural_tag(
    "llama",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "parameters": {
                    "type": "object",
                    "properties": {"location": {"type": "string"}},
                },
            },
        }
    ],
)

Harmony with a builtin web search tool:

structural_tag = get_model_structural_tag(
    "harmony",
    tools=[
        {
            "type": "web_search_preview",
            "name": "browser.search",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        }
    ],
)

Force an ordinary function tool:

structural_tag = get_model_structural_tag(
    "llama",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "parameters": {
                    "type": "object",
                    "properties": {"location": {"type": "string"}},
                },
            },
        }
    ],
    tool_choice={
        "type": "function",
        "function": {"name": "get_weather"},
    },
)

Force a builtin tool by type and output name:

structural_tag = get_model_structural_tag(
    "harmony",
    tools=[...],
    tool_choice={"type": "web_search_preview"},
)

Allow only a subset of tools:

structural_tag = get_model_structural_tag(
    "harmony",
    tools=[...],
    tool_choice={
        "type": "allowed_tools",
        "allowed_tools": {
            "mode": "auto",
            "tools": [
                {"type": "function", "function": {"name": "get_weather"}},
                {"type": "web_search_preview"},
            ],
        },
    },
)

Parameters:

model (str) – The model type of the structural tag template. It should be one of the registered values.
tools (Optional[List[Union[ToolParam, dict]]]) – Function and builtin tools available to the model. Function tools use the Chat Completions shape. Builtin tools use type plus optional name and parameters fields. Defaults to None, which is treated as an empty list.
tool_choice (Union[ToolChoiceOptionParam, dict, None]) –
Controls whether the model may or must call tools. Defaults to "auto".
- "auto" lets the model choose between text output and tool calls.
- None is treated the same as "auto".
- "none" disables all tools.
- "required" requires at least one available tool.
- {"type": "function", "function": {"name": ...}} forces one function tool.
- {"type": <builtin_type>} forces one builtin tool. Builtin tool choices are matched by type.
- {"type": "allowed_tools", "allowed_tools": ...} limits the available tools before applying its mode. Its tools list may contain both function refs and builtin refs. Builtin refs are matched by type.
reasoning (bool) – Whether to enable the reasoning part. Some models, such as Qwen 3.6 and DeepSeek V4, support both reasoning and non-reasoning modes. If False, use the non-reasoning mode. For models that do not support reasoning, this has no effect. For models that only support reasoning, False means reasoning with empty content.
force_reasoning (bool) – Deprecated. Control whether to keep the reasoning part but leave its content empty. Now we will embed the model’s specific behavior into the structural tag function, so only controlling reasoning is enough.

Notes

If a tool’s parameters field is omitted or None, its generated arguments are unconstrained JSON. If a function tool has strict=False, its parameters schema is also treated as unconstrained.

Returns:: A structural tag for function calling format.
Return type:: StructuralTag
Raises:: ValueError – If tool lists, tool choices, or required tool availability are invalid.

xgrammar.builtin_structural_tag.normalize_tool_choice(tools: Optional[List[Union[FunctionToolParam, BuiltinToolParam, dict]]] = None, tool_choice: Optional[Union[Literal['none', 'auto', 'required'], NamedToolChoiceParam, AllowedToolChoiceParam, BuiltinToolChoiceParam, dict]] = 'auto') → Tuple[List[FunctionToolParam], List[BuiltinToolParam], Literal['auto', 'required', 'forced']][source]¶

Normalize tools and tool choice for structural tag builders.

This helper exposes the model-independent part of get_model_structural_tag(). It is intended for serving engines that want to own their model-specific structural tag templates while reusing OpenAI-style tool and tool-choice handling.

The return value is not a new public tool-calling protocol. It is a compact prepared form for structural tag builder functions:

ordinary function tools are returned as FunctionToolParam objects;
builtin/server tools are returned as BuiltinToolParam objects;
public tool-choice values are simplified to "auto", "required", or "forced".

Parameters:

tools (Optional[List[Union[ToolParam, dict]]]) – Function and builtin tools available to the model. Function tools use the OpenAI Chat Completions shape, {"type": "function", "function": {...}}. Builtin tools use type plus optional name and parameters fields. None is treated as an empty list.
tool_choice (Union[ToolChoiceOptionParam, dict, None]) –
Controls whether the model may or must call tools. This accepts the same values as get_model_structural_tag():
- "auto" keeps all available tools and lets the builder allow text or tool calls.
- None is treated as "auto".
- "none" clears all tools and returns simplified choice "auto". Builders already interpret auto with no tools as text-only.
- "required" keeps all available tools and requires at least one function or builtin tool to remain available.
- {"type": "function", "function": {"name": ...}} filters to the named function tool and returns simplified choice "forced".
- {"type": <builtin_type>} filters to exactly one builtin tool whose type matches and returns simplified choice "forced".
- {"type": "allowed_tools", "allowed_tools": ...} filters to the referenced tools and returns the nested allowed-tools mode as the simplified choice.

Returns:

A tuple of (function_tools, builtin_tools, simplified_tool_choice) ready to pass to a model-specific structural tag builder.

Return type:

Tuple[List[FunctionToolParam], List[BuiltinToolParam], SimplifiedToolChoice]

Raises:

ValueError – If tools is not a list, a referenced tool is missing, a builtin tool choice does not match exactly one builtin tool, required leaves no available tools, or forced does not resolve to exactly one tool.

Examples

Build tool-choice handling with an external model-specific builder:

function_tools, builtin_tools, tool_choice = normalize_tool_choice(
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "parameters": {
                    "type": "object",
                    "properties": {"location": {"type": "string"}},
                },
            },
        }
    ],
    tool_choice={
        "type": "function",
        "function": {"name": "get_weather"},
    },
)

structural_tag = build_my_model_structural_tag(
    function_tools,
    builtin_tools,
    tool_choice,
    reasoning=True,
)

xgrammar.builtin_structural_tag.register_model_structural_tag(name: str)[source]¶

Register a model-specific structural tag function under name.

The decorated function is stored in the internal registry so that get_model_structural_tag() can look it up by the model argument. Use this to add support for a new model format.

Parameters:: name (str) – The model format key, e.g. "llama", "harmony".

Examples

@register_model_structural_tag("my_model")
def get_my_model_structural_tag(
    tools=None, builtin_tools=None, tool_choice="auto",
    reasoning=True, **kwargs,
):
    ...

xgrammar.builtin_structural_tag.get_llama_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get Llama style structural tag format.

Corresponding model key: "llama".

Reference: https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
reasoning: ignored because this format has no reasoning part.

Supported models:

Meta-Llama-3
Llama-3.1
Llama-3.2

Returns:: A structural tag for function calling format. This format is used by Llama 3 and other models that follow the same style.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_kimi_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get Kimi-K2 style structural tag format.

Corresponding model key: "kimi".

Reference: https://huggingface.co/moonshotai/Kimi-K2-Instruct/blob/main/docs/tool_call_guidance.md

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
reasoning: whether to enable reasoning mode. If False, remove the reasoning part and constrain only the following part.

Supported models:

Kimi-K2
Kimi-K2.5

Returns:: A structural tag template. This format is used by Kimi-K2 and other models that follow the same style.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_deepseek_r1_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get DeepSeek-R1 style structural tag format.

Corresponding model key: "deepseek_r1".

Reference: https://huggingface.co/deepseek-ai/DeepSeek-R1/blob/main/tokenizer_config.json

Supported models:

DeepSeek-R1
DeepSeek-R1-0528

xgrammar.builtin_structural_tag.get_deepseek_v3_1_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get DeepSeek-V3.1 style structural tag format.

Corresponding model key: "deepseek_v3_1".

Reference: https://huggingface.co/deepseek-ai/DeepSeek-V3.1/blob/main/tokenizer_config.json

Supported models:

DeepSeek-V3.1
DeepSeek-V3.2-Exp

xgrammar.builtin_structural_tag.get_qwen_3_5_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get Qwen XML tool-call structural tag format.

Corresponding model keys: "qwen_3_5" and "qwen_3_coder".

Reference: https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8/blob/main/chat_template.jinja

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
reasoning: whether to add the </think> reasoning prefix before the tool/text suffix.

Supported models:

Qwen3.5
Qwen3.6
Qwen3-Coder
Qwen3-Coder-Next

Returns:: A structural tag for Qwen XML function calling format.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_qwen_3_coder_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag¶: Deprecated alias for get_qwen_3_5_structural_tag().

xgrammar.builtin_structural_tag.get_qwen_3_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get Qwen3 style structural tag format.

Corresponding model key: "qwen_3".

Reference: https://qwen.readthedocs.io/en/latest/framework/function_call.html

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
reasoning: whether to enable reasoning mode. If False, remove the reasoning part.

Supported models:

Qwen3
Qwen3-Next

Returns:: A structural tag template. This format is used by Qwen3 and other models that follow the same style.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_harmony_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get harmony(gpt-oss) style structural tag format.

Corresponding model key: "harmony".

Reference: https://developers.openai.com/cookbook/articles/openai-harmony Reference: https://huggingface.co/openai/gpt-oss-120b/blob/main/chat_template.jinja

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
builtin_tools: a list of builtin tools. Each builtin tool should provide type, optional name, and parameters fields.
reasoning: whether to enable the analysis channel.

Supported models:

gpt-oss

Returns:: A structural tag template. This format is in OpenAI Harmony Response Format, which is used by GPT-oss and other models that follow the same style.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_deepseek_v3_2_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get DeepSeek-V3.2 style structural tag format.

Corresponding model key: "deepseek_v3_2".

Supported models:

DeepSeek-V3.2

xgrammar.builtin_structural_tag.get_minimax_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get MiniMax-M2.5 style structural tag format.

Corresponding model key: "minimax".

Supported models:

MiniMax-M2.5
MiniMax-M2.7

Returns:: A structural tag for MiniMax function calling format.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_glm_4_7_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get GLM-4.7/GLM-5 style structural tag format.

The GLM tool calling format uses XML-like tags: <tool_call>function_name <arg_key>key</arg_key><arg_value>value</arg_value> </tool_call>

Corresponding model key: "glm_4_7".

Parameters are normalized by get_model_structural_tag() before this function is called:

tools: a list of function tools. Each tool should have a function object containing name and parameters fields.
reasoning: whether to enable reasoning mode. If False, use the non-reasoning mode.

Supported models:

GLM-5
GLM-4.7

Returns:: A structural tag for GLM function calling format.
Return type:: StructuralTag

xgrammar.builtin_structural_tag.get_deepseek_v4_structural_tag(tools: Optional[List[FunctionToolParam]] = None, builtin_tools: Optional[List[BuiltinToolParam]] = None, tool_choice: Literal['auto', 'required', 'forced'] = 'auto', reasoning: bool = True, **kwargs: Any) → StructuralTag[source]¶

Get DeepSeek-V4 style structural tag format.

Corresponding model key: "deepseek_v4".

Supported models:

DeepSeek-V4

xgrammar.builtin_structural_tag.get_builtin_structural_tag(model: str, tools: Optional[List[Union[FunctionToolParam, BuiltinToolParam, dict]]] = None, tool_choice: Optional[Union[Literal['none', 'auto', 'required'], NamedToolChoiceParam, AllowedToolChoiceParam, BuiltinToolChoiceParam, dict]] = 'auto', reasoning: bool = True, force_reasoning: bool = False) → StructuralTag¶: Alias for get_model_structural_tag(). Deprecated.