Skip to content

vllm.tool_parsers.structural_tag_registry

Functions:

_K3_STRING_ATOM = '(?:[^<]|<[^|])' module-attribute

One raw-string character: anything but the ambiguous "<|" marker prefix. Allows '<' inside values (e.g. HTML snippets); a value ending in '<' or containing a literal "<|" is not expressible and falls back to AnyText via the pattern checks below never matching those cases at build time (schemas cannot know values, so the only build-time effect is the length bound).

_dump_tool_choice_for_xgrammar(tool_choice)

Convert tool_choice objects to xgrammar's expected protocol.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _dump_tool_choice_for_xgrammar(
    tool_choice: ToolChoice,
) -> dict[str, Any] | str | None:
    """Convert tool_choice objects to xgrammar's expected protocol."""
    if tool_choice is None:
        return None

    if isinstance(tool_choice, str):
        return tool_choice

    if isinstance(tool_choice, ChatCompletionNamedToolChoiceParam):
        return tool_choice.model_dump(mode="json", exclude_none=True)

    if isinstance(tool_choice, (ToolChoiceFunction, ToolChoiceCustom)):
        return {
            "type": "function",
            "function": {"name": tool_choice.name},
        }

    if isinstance(tool_choice, ToolChoiceAllowed):
        return {
            "type": "allowed_tools",
            "allowed_tools": {
                "mode": tool_choice.mode,
                "tools": [
                    _dump_allowed_tool_ref_for_xgrammar(tool)
                    for tool in tool_choice.tools
                ],
            },
        }

    return tool_choice.model_dump(mode="json", exclude_none=True)

_dump_tool_for_xgrammar(tool)

Convert tool objects to xgrammar's Chat Completions tool protocol.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _dump_tool_for_xgrammar(
    tool: ChatCompletionToolsParam | ResponsesTool,
) -> dict[str, Any]:
    """Convert tool objects to xgrammar's Chat Completions tool protocol."""
    if isinstance(tool, FunctionTool):
        function: dict[str, Any] = {"name": tool.name}
        if tool.description is not None:
            function["description"] = tool.description
        if tool.parameters is not None:
            function["parameters"] = tool.parameters
        if tool.strict is not None:
            function["strict"] = tool.strict
        return {"type": "function", "function": function}
    if isinstance(tool, CustomTool):
        function = {"name": tool.name, "parameters": custom_tool_parameters()}
        if tool.description is not None:
            function["description"] = tool.description
        return {"type": "function", "function": function}
    dumped_tool = tool.model_dump(mode="json", exclude_none=True)
    if isinstance(tool, ChatCompletionToolsParam):
        return dumped_tool
    return dict(dumped_tool)

_glm_4_7_plain_properties(params)

Return properties when the schema is a plain object schema.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _glm_4_7_plain_properties(params: dict[str, Any]) -> dict[str, Any] | None:
    """Return `properties` when the schema is a plain object schema."""
    properties = params.get("properties")
    if (
        not isinstance(properties, dict)
        or not properties
        or params.get("additionalProperties") is True
        or any(
            key in params
            for key in ("$ref", "allOf", "anyOf", "oneOf", "patternProperties")
        )
    ):
        return None
    return properties

_glm_4_7_strict_tool_tag(tool)

Schema-pinned tag matching the xgrammar builtin's strict content.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _glm_4_7_strict_tool_tag(tool: FunctionToolParam) -> TagFormat:
    """Schema-pinned tag matching the xgrammar builtin's strict content."""
    return TagFormat(
        begin=f"<tool_call>{tool.function.name}",
        content=JSONSchemaFormat(
            json_schema=tool.function.parameters
            if tool.function.parameters is not None
            else True,
            style="glm_xml",
            any_order=False,
        ),
        end="</tool_call>",
    )

_glm_4_7_tool_tag(tool)

Shallow tag for a non-strict tool: keys and scalar value types pinned.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _glm_4_7_tool_tag(tool: FunctionToolParam) -> TagFormat:
    """Shallow tag for a non-strict tool: keys and scalar value types pinned."""
    properties = _glm_4_7_plain_properties(tool.function.parameters or {})
    if properties is None:
        return TagFormat(
            begin=f"<tool_call>{tool.function.name}",
            content=JSONSchemaFormat(
                json_schema=True, style="glm_xml", any_order=False
            ),
            end="</tool_call>",
        )
    pairs: list[Any] = [
        SequenceFormat(
            elements=[
                ConstStringFormat(value=f"<arg_key>{key}</arg_key><arg_value>"),
                _glm_4_7_value_format(prop),
                ConstStringFormat(value="</arg_value>"),
            ]
        )
        for key, prop in properties.items()
    ]
    content: Any = (
        StarFormat(content=pairs[0] if len(pairs) == 1 else OrFormat(elements=pairs))
        if pairs
        else ConstStringFormat(value="")
    )
    return TagFormat(
        begin=f"<tool_call>{tool.function.name}",
        content=content,
        end="</tool_call>",
    )

_hy_v4_argument_keys(parameters)

Split a tool's argument keys into (required, optional).

Both lists keep declaration order. Required keys missing from properties are still treated as required.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _hy_v4_argument_keys(parameters: dict[str, Any]) -> tuple[list[str], list[str]]:
    """Split a tool's argument keys into `(required, optional)`.

    Both lists keep declaration order. Required keys missing from
    `properties` are still treated as required.
    """
    properties = parameters.get("properties") or {}
    required = parameters.get("required") or []
    required_set = set(required)
    required_keys = [k for k in properties if k in required_set]
    required_keys += [k for k in required if k not in properties]
    optional_keys = [k for k in properties if k not in required_set]
    return required_keys, optional_keys

_k3_argument_tag(key, schema, root_defs=None)

Build one argument XTML tag for property key.

string values are emitted raw (bounded by the close marker); every other JSON type is emitted as JSON and validated against the property schema. A property whose type is a union / missing is left permissive (any XTML type, raw value) so a valid call is never rejected.

root_defs carries the tool parameters' root-level $defs / definitions: slicing a property out of the parameters document orphans its #/$defs/... references, so those tables must be re-attached to keep the embedded schema self-contained.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_argument_tag(
    key: str,
    schema: dict[str, Any],
    root_defs: dict[str, Any] | None = None,
) -> TagFormat | None:
    """Build one `argument` XTML tag for property `key`.

    `string` values are emitted raw (bounded by the close marker); every other
    JSON type is emitted as JSON and validated against the property schema. A
    property whose type is a union / missing is left permissive (any XTML type,
    raw value) so a valid call is never rejected.

    `root_defs` carries the tool parameters' root-level `$defs` /
    `definitions`: slicing a property out of the parameters document orphans
    its `#/$defs/...` references, so those tables must be re-attached to keep
    the embedded schema self-contained.
    """
    prop = schema if isinstance(schema, dict) else {}
    json_type = prop.get("type")
    xtml_type = (
        _K3_JSON_TO_XTML_TYPE.get(json_type) if isinstance(json_type, str) else None
    )
    if xtml_type is None:
        # Unknown / union type: constrain the key but keep the value permissive.
        return None
    begin = (
        f'{_K3_OPEN}argument key="{_k3_escape_attr(key)}" type="{xtml_type}"{_K3_SEP}'
    )
    if xtml_type == "string":
        # Raw string channel: JSONSchemaFormat can't apply (values are not
        # JSON-quoted), but an enum/const of strings is a finite set that can
        # be enforced exactly with const-string alternation. Enum semantics
        # are exclusive, so this never over-rejects. Fall back to permissive
        # AnyText for open-ended strings or non-representable enums.
        enum_values = prop.get("enum")
        if enum_values is None and isinstance(prop.get("const"), str):
            enum_values = [prop["const"]]
        if (
            isinstance(enum_values, list)
            and enum_values
            and len(enum_values) <= 256
            and all(isinstance(v, str) for v in enum_values)
            and not any("<|" in v for v in enum_values)
        ):
            branches = [ConstStringFormat(value=v) for v in enum_values]
            content: Any = (
                branches[0] if len(branches) == 1 else OrFormat(elements=branches)
            )
        elif (bounded := _k3_bounded_string_regex(prop)) is not None:
            content = RegexFormat(pattern=bounded)
        else:
            content = AnyTextFormat(excludes=[_K3_CLOSE])
    else:
        embedded = prop
        if root_defs:
            embedded = dict(prop)
            for defs_key, defs_value in root_defs.items():
                embedded.setdefault(defs_key, defs_value)
        content = JSONSchemaFormat(json_schema=embedded)
    return TagFormat(begin=begin, content=content, end=_K3_ARG_CLOSE)

_k3_arguments_block(parameters)

Build argument tags for a tool's parameter schema.

Require at least one tag when the root schema declares required properties. Otherwise, keep accepting zero-or-more tags. Arguments remain order-agnostic and non-unique.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_arguments_block(parameters: dict[str, Any] | bool) -> Any:
    """Build `argument` tags for a tool's parameter schema.

    Require at least one tag when the root schema declares required properties.
    Otherwise, keep accepting zero-or-more tags. Arguments remain order-agnostic
    and non-unique.
    """
    if not isinstance(parameters, dict):
        return StarFormat(content=_k3_permissive_argument_tag())
    props = parameters.get("properties")
    if not isinstance(props, dict) or not props:
        # No declared properties: allow any argument blocks (or none).
        return StarFormat(content=_k3_permissive_argument_tag())
    root_defs = {
        defs_key: parameters[defs_key]
        for defs_key in ("$defs", "definitions")
        if isinstance(parameters.get(defs_key), dict)
    }
    tags: list[TagFormat] = []
    for key, prop in props.items():
        tag = _k3_argument_tag(key, prop, root_defs)
        tags.append(tag if tag is not None else _k3_permissive_argument_tag())
    inner = tags[0] if len(tags) == 1 else OrFormat(elements=list(tags))
    required = parameters.get("required")
    if isinstance(required, list) and required:
        return PlusFormat(content=inner)
    return StarFormat(content=inner)

_k3_bounded_string_regex(prop)

Length/pattern constraint for the raw string channel, if expressible.

The XTML string channel emits values raw (not JSON-quoted), so JSONSchemaFormat cannot enforce string constraints there; unconstrained AnyText lets maxLength/pattern violations through (observed on the walle verifier: over-long junk strings pass the grammar and fail validation). xgrammar's regex engine has no lookahead, so the close marker is kept unambiguous by excluding the "<|" prefix from value characters.

Returns a regex for the value, or None to keep permissive AnyText.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_bounded_string_regex(prop: dict[str, Any]) -> str | None:
    """Length/pattern constraint for the raw string channel, if expressible.

    The XTML string channel emits values raw (not JSON-quoted), so
    JSONSchemaFormat cannot enforce string constraints there; unconstrained
    AnyText lets maxLength/pattern violations through (observed on the walle
    verifier: over-long junk strings pass the grammar and fail validation).
    xgrammar's regex engine has no lookahead, so the close marker is kept
    unambiguous by excluding the "<|" prefix from value characters.

    Returns a regex for the value, or None to keep permissive AnyText.
    """
    max_len = prop.get("maxLength")
    min_len = prop.get("minLength", 0)
    if not isinstance(max_len, int) or max_len < 0 or max_len > 4096:
        return None
    if not isinstance(min_len, int) or min_len < 0 or min_len > max_len:
        min_len = 0
    return _K3_STRING_ATOM + f"{{{min_len},{max_len}}}"

_k3_call_tag(tool)

One call tag: <|open|>call tool="N" index="<digits>"<|sep|> args.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_call_tag(tool: FunctionToolParam) -> TagFormat:
    """One `call` tag: `<|open|>call tool="N" index="<digits>"<|sep|> args`."""
    function = tool.function
    parameters = get_function_parameters(function)
    begin = f'{_K3_OPEN}call tool="{_k3_escape_attr(function.name)}" index="'
    return TagFormat(
        begin=begin,
        content=SequenceFormat(
            elements=[
                RegexFormat(pattern=r"[0-9]+"),
                ConstStringFormat(value=f'"{_K3_SEP}'),
                _k3_arguments_block(parameters),
            ]
        ),
        end=_K3_CALL_CLOSE,
    )

_k3_escape_attr(value)

Mirror encoding_k3._escape_attr_value (& then ").

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_escape_attr(value: str) -> str:
    """Mirror `encoding_k3._escape_attr_value` (`&` then `"`)."""
    return str(value).replace("&", "&amp;").replace('"', "&quot;")

_k3_permissive_argument_tag()

A key/type-agnostic argument tag: any attributes, raw value.

Used as a fallback so tools with union/loose schemas still get the XTML skeleton constrained without over-rejecting the value.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_permissive_argument_tag() -> TagFormat:
    """A key/type-agnostic `argument` tag: any attributes, raw value.

    Used as a fallback so tools with union/loose schemas still get the XTML
    skeleton constrained without over-rejecting the value.
    """
    return TagFormat(
        begin=_K3_OPEN + "argument ",
        content=SequenceFormat(
            elements=[
                RegexFormat(pattern=r"[^<]*" + _K3_SEP.replace("|", r"\|")),
                AnyTextFormat(excludes=[_K3_CLOSE]),
            ]
        ),
        end=_K3_ARG_CLOSE,
    )

_k3_response_prefix()

The response channel that always precedes the tools channel.

response is generated in thinking mode (prefix ends at <|open|>think<|sep|>) but is part of the generation prefix in non-thinking mode, so its open marker is optional. Excluding the reserved marker heads commits <|close|> to the response-close branch immediately and prevents a nested channel from starting inside response text.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _k3_response_prefix() -> list[Any]:
    """The response channel that always precedes the tools channel.

    `response` is generated in thinking mode (prefix ends at
    `<|open|>think<|sep|>`) but is part of the generation prefix in
    non-thinking mode, so its open marker is optional. Excluding the reserved
    marker heads commits `<|close|>` to the response-close branch immediately
    and prevents a nested channel from starting inside response text.
    """
    return [
        OptionalFormat(content=ConstStringFormat(value=_K3_RESPONSE_OPEN)),
        TagFormat(
            begin="",
            content=AnyTextFormat(excludes=[_K3_OPEN, _K3_CLOSE, _K3_END_OF_MSG]),
            end=_K3_RESPONSE_CLOSE,
        ),
    ]

_with_tool_strict(tool, strict)

Return a copy of tool with strict set, leaving the request's alone.

Source code in vllm/tool_parsers/structural_tag_registry.py
def _with_tool_strict(
    tool: ChatCompletionToolsParam | ResponsesTool,
    strict: bool,
) -> ChatCompletionToolsParam | ResponsesTool:
    """Return a copy of `tool` with `strict` set, leaving the request's alone."""
    if isinstance(tool, FunctionTool):
        return tool.model_copy(update={"strict": strict})
    if isinstance(tool, ChatCompletionToolsParam):
        return tool.model_copy(
            update={"function": tool.function.model_copy(update={"strict": strict})}
        )
    return tool

get_glm_4_7_structural_tag(function_tools, builtin_tools, tool_choice, reasoning, token_suffix='')

Build the GLM-4.7 structural tag, dispatching per tool on strictness.

Parameters:

  • function_tools

    (list[FunctionToolParam]) –

    Normalized function tools with strict pinned by resolve_tool_strictness.

  • builtin_tools

    (list[BuiltinToolParam]) –

    Unused; GLM-4.7 has no builtin tools.

  • tool_choice

    (Any) –

    Simplified tool choice (auto / required / forced).

  • reasoning

    (bool) –

    Whether the grammar also covers the reasoning phase.

  • token_suffix

    (str, default: '' ) –

    Unused; GLM-4.7 structural tokens are fixed.

Source code in vllm/tool_parsers/structural_tag_registry.py
@register_vllm_structural_tag("glm_4_7")
def get_glm_4_7_structural_tag(
    function_tools: list[FunctionToolParam],
    builtin_tools: list[BuiltinToolParam],
    tool_choice: Any,
    reasoning: bool,
    token_suffix: str = "",
) -> StructuralTag:
    """Build the GLM-4.7 structural tag, dispatching per tool on strictness.

    Args:
        function_tools: Normalized function tools with `strict` pinned by
            `resolve_tool_strictness`.
        builtin_tools: Unused; GLM-4.7 has no builtin tools.
        tool_choice: Simplified tool choice (`auto` / `required` /
            `forced`).
        reasoning: Whether the grammar also covers the reasoning phase.
        token_suffix: Unused; GLM-4.7 structural tokens are fixed.

    """
    del builtin_tools, token_suffix

    if function_tools and all(tool.function.strict for tool in function_tools):
        # Strict-only requests stay byte-identical to the xgrammar builtin.
        dumped_choice: Any = (
            {"type": "function", "function": {"name": function_tools[0].function.name}}
            if tool_choice == "forced"
            else tool_choice
        )
        dumped_tools = []
        for tool in function_tools:
            function: dict[str, Any] = {"name": tool.function.name, "strict": True}
            if tool.function.description is not None:
                function["description"] = tool.function.description
            if tool.function.parameters is not None:
                function["parameters"] = tool.function.parameters
            dumped_tools.append({"type": "function", "function": function})
        return get_xgrammar_model_structural_tag(
            model="glm_4_7",
            tools=dumped_tools,
            tool_choice=dumped_choice,
            reasoning=reasoning,
        )

    tags = [
        _glm_4_7_strict_tool_tag(tool)
        if tool.function.strict
        else _glm_4_7_tool_tag(tool)
        for tool in function_tools
    ]
    if tool_choice == "auto":
        # Keep the trigger itself out of the excludes so tag dispatch works.
        suffix_tag: Any = TriggeredTagsFormat(
            triggers=["<tool_call>"],
            tags=tags,
            excludes=[e for e in _GLM_4_7_VALUE_EXCLUDES if e != "<tool_call>"],
        )
    else:
        suffix_tag = TagsWithSeparatorFormat(
            tags=tags,
            separator="",
            at_least_one=True,
            stop_after_first=tool_choice == "forced",
        )
    if reasoning:
        prefix_tag = TagFormat(
            begin="",
            content=AnyTextFormat(excludes=_GLM_4_7_VALUE_EXCLUDES),
            end="</think>",
        )
        return StructuralTag(format=SequenceFormat(elements=[prefix_tag, suffix_tag]))
    return StructuralTag(format=suffix_tag)

get_hy_v4_structural_tag(tools, builtin_tools, tool_choice, reasoning, token_suffix='')

Build HYV4 /// structural tags.

Parameters:

  • tools

    (list[FunctionToolParam]) –

    Normalized function tools the model may call.

  • builtin_tools

    (list[BuiltinToolParam]) –

    Unused; HYV4 has no builtin tools.

  • tool_choice

    (SimplifiedToolChoice) –

    Simplified tool choice.

  • reasoning

    (bool) –

    Whether the grammar also covers the reasoning phase.

  • token_suffix

    (str, default: '' ) –

    Per-checkpoint structural-token suffix including the leading colon (e.g. ":6124c78e"), or "" when the checkpoint uses unsuffixed tokens. The HYV4 tool parser reads it off the tokenizer vocab and passes it to get_model_structural_tag.

Source code in vllm/tool_parsers/structural_tag_registry.py
@register_vllm_structural_tag("hy_v4")
def get_hy_v4_structural_tag(
    tools: list[FunctionToolParam],
    builtin_tools: list[BuiltinToolParam],
    tool_choice: SimplifiedToolChoice,
    reasoning: bool,
    token_suffix: str = "",
) -> StructuralTag:
    """Build HYV4 <tool_calls>/<tool_call>/<arg_key>/<arg_value> structural tags.

    Args:
        tools: Normalized function tools the model may call.
        builtin_tools: Unused; HYV4 has no builtin tools.
        tool_choice: Simplified tool choice.
        reasoning: Whether the grammar also covers the reasoning phase.
        token_suffix: Per-checkpoint structural-token suffix including the
            leading colon (e.g. `":6124c78e"`), or `""` when the checkpoint
            uses unsuffixed tokens. The HYV4 tool parser reads it off the
            tokenizer vocab and passes it to `get_model_structural_tag`.

    """
    del builtin_tools

    think_end = f"</think{token_suffix}>"
    tool_calls_begin = f"<tool_calls{token_suffix}>"
    tool_calls_end = f"</tool_calls{token_suffix}>"
    tool_call_begin = f"<tool_call{token_suffix}>"
    tool_call_end = f"</tool_call{token_suffix}>"
    arg_key_begin = f"<arg_key{token_suffix}>"
    arg_key_end = f"</arg_key{token_suffix}>"
    arg_value_begin = f"<arg_value{token_suffix}>"
    arg_value_end = f"</arg_value{token_suffix}>"

    def arg_pair(key: str) -> SequenceFormat:
        return SequenceFormat(
            elements=[
                ConstStringFormat(value=arg_key_begin),
                ConstStringFormat(value=key),
                ConstStringFormat(value=arg_key_end),
                ConstStringFormat(value=arg_value_begin),
                AnyTextFormat(),
                ConstStringFormat(value=arg_value_end),
            ]
        )

    def single_tool_call(tool: FunctionToolParam) -> TagFormat:
        function = tool.function
        parameters = (
            function.parameters if isinstance(function.parameters, dict) else {}
        )
        required_keys, optional_keys = _hy_v4_argument_keys(parameters)
        elements: list[Any] = [arg_pair(k) for k in required_keys]
        if optional_keys:
            # Optional keys may appear in any order, or not at all.
            optional_pairs = [arg_pair(k) for k in optional_keys]
            elements.append(
                StarFormat(
                    content=optional_pairs[0]
                    if len(optional_pairs) == 1
                    else OrFormat(elements=optional_pairs)
                )
            )
        content: Any = (
            SequenceFormat(elements=elements) if elements else AnyTextFormat()
        )
        return TagFormat(
            begin=tool_call_begin + function.name,
            content=content,
            end=tool_call_end,
        )

    tags = [single_tool_call(tool) for tool in tools]

    if tool_choice == "auto":
        block = TagFormat(
            begin=tool_calls_begin,
            content=TagsWithSeparatorFormat(
                tags=tags,
                separator="",
                at_least_one=True,
            ),
            end=tool_calls_end,
        )
        suffix_tag: Any = TriggeredTagsFormat(triggers=[tool_calls_begin], tags=[block])
    else:
        # HYV4 places tool_call blocks back-to-back with no separator. "forced"
        # has already been filtered down to the single named tool and must emit
        # exactly one block.
        suffix_tag = SequenceFormat(
            elements=[
                ConstStringFormat(value=tool_calls_begin),
                TagsWithSeparatorFormat(
                    tags=tags,
                    separator="",
                    at_least_one=True,
                    stop_after_first=tool_choice == "forced",
                ),
                ConstStringFormat(value=tool_calls_end),
            ]
        )

    if not reasoning:
        return StructuralTag(format=suffix_tag)

    # The reasoning phase is constrained too, so the tag must explicitly skip
    # the ``<think>...</think:SUF>`` prefix.
    prefix_tag = TagFormat(begin="", content=AnyTextFormat(), end=think_end)
    return StructuralTag(format=SequenceFormat(elements=[prefix_tag, suffix_tag]))

get_model_structural_tag(model, tools, tool_choice, reasoning, token_suffix='', strict_level=ToolStrictLevel.AUTO)

Build a structural tag with xgrammar's builtin model templates.

Source code in vllm/tool_parsers/structural_tag_registry.py
def get_model_structural_tag(
    model: str,
    tools: Sequence[ChatCompletionToolsParam | ResponsesTool] | None,
    tool_choice: ToolChoice,
    reasoning: bool,
    token_suffix: str = "",
    strict_level: ToolStrictLevel = ToolStrictLevel.AUTO,
) -> StructuralTag | None:
    """Build a structural tag with xgrammar's builtin model templates."""
    if not tools or tool_choice == "none":
        return None

    tools = get_structural_tag_tools(model, tools, tool_choice)
    if not tools:
        return None
    tools = resolve_tool_strictness(tools, tool_choice, strict_level)
    if tools is None:
        return None

    dumped_tools = [_dump_tool_for_xgrammar(tool) for tool in tools]
    dumped_tool_choice = _dump_tool_choice_for_xgrammar(tool_choice)

    if model in _VLLM_STRUCTURAL_TAG_REGISTRY:
        function_tools, builtin_tools, simplified_tool_choice = normalize_tool_choice(
            dumped_tools,
            dumped_tool_choice,
        )
        return _VLLM_STRUCTURAL_TAG_REGISTRY[model](
            function_tools,
            builtin_tools,
            simplified_tool_choice,
            reasoning,
            token_suffix,
        )

    if model not in XGRAMMAR_BUILTIN_STRUCTURAL_TAG_MODELS:
        supported = sorted(SUPPORTED_STRUCTURAL_TAG_MODELS)
        raise ValueError(f"Unknown format type: {model}, supported types: {supported}")

    if token_suffix:
        raise ValueError(
            f"Structural tag model {model!r} is an xgrammar builtin with fixed "
            f"tokens and cannot apply token_suffix={token_suffix!r}"
        )

    return get_xgrammar_model_structural_tag(
        model=model,
        tools=dumped_tools,
        tool_choice=dumped_tool_choice,
        reasoning=reasoning,
    )

get_plamo3_structural_tag(tools, builtin_tools, tool_choice, reasoning, token_suffix='')

Build PLaMo3's explicit tool-request structural tag.

Source code in vllm/tool_parsers/structural_tag_registry.py
@register_vllm_structural_tag("plamo3")
def get_plamo3_structural_tag(
    tools: list[FunctionToolParam],
    builtin_tools: list[BuiltinToolParam],
    tool_choice: SimplifiedToolChoice,
    reasoning: bool,
    token_suffix: str = "",
) -> StructuralTag:
    """Build PLaMo3's explicit tool-request structural tag."""
    del builtin_tools, reasoning, token_suffix

    request_tags = [
        TagFormat(
            begin=(
                _PLAMO3_BEGIN_TOOL_REQUEST
                + _PLAMO3_BEGIN_TOOL_NAME
                + tool.function.name
                + _PLAMO3_END_TOOL_NAME
                + _PLAMO3_BEGIN_TOOL_ARGUMENTS
            ),
            content=JSONSchemaFormat(
                json_schema=get_function_parameters(tool.function)
            ),
            end=_PLAMO3_END_TOOL_ARGUMENTS + _PLAMO3_END_TOOL_REQUEST,
        )
        for tool in tools
    ]
    requests_tag = TagFormat(
        begin=_PLAMO3_BEGIN_TOOL_REQUESTS,
        content=TagsWithSeparatorFormat(
            tags=request_tags,
            separator="",
            at_least_one=True,
            stop_after_first=tool_choice == "forced",
        ),
        end=[
            _PLAMO3_END_TOOL_REQUESTS,
            _PLAMO3_END_TOOL_REQUESTS + _PLAMO3_EOT,
        ],
    )

    if tool_choice == "auto":
        return StructuralTag(
            format=TriggeredTagsFormat(
                triggers=[_PLAMO3_BEGIN_TOOL_REQUESTS],
                tags=[requests_tag],
            )
        )
    return StructuralTag(format=requests_tag)

get_structural_tag_tools(model, tools, tool_choice)

Return the tools a structural tag for model lets the model call.

Most models are only shown function tools, so their grammar must cover exactly those: a tool missing from the prompt cannot be called, and one missing from the grammar is shown but blocked.

Raises:

  • VLLMValidationError –

    tool_choice requires a call, but the model has no tool it can call.

Source code in vllm/tool_parsers/structural_tag_registry.py
def get_structural_tag_tools(
    model: str,
    tools: Sequence[ChatCompletionToolsParam | ResponsesTool],
    tool_choice: ToolChoice,
) -> Sequence[ChatCompletionToolsParam | ResponsesTool]:
    """Return the tools a structural tag for `model` lets the model call.

    Most models are only shown function tools, so their grammar must cover
    exactly those: a tool missing from the prompt cannot be called, and one
    missing from the grammar is shown but blocked.

    Raises:
        VLLMValidationError: `tool_choice` requires a call, but the model
            has no tool it can call.

    """
    if model in _BUILTIN_TOOL_STRUCTURAL_TAG_MODELS:
        return tools
    if (
        tool_choice is None
        or tool_choice == "auto"
        or getattr(tool_choice, "mode", None) == "auto"
    ):
        return get_function_tools(tools)
    return require_function_tools(tools)

limit_to_single_tool_call(tag)

Stop every tool-call list in tag after its first call, in place.

Enforces parallel_tool_calls=false in the grammar. In every registered tag, _TOOL_CALL_LIST_FORMATS repeat tool calls, never arguments.

Source code in vllm/tool_parsers/structural_tag_registry.py
def limit_to_single_tool_call(tag: StructuralTag) -> StructuralTag:
    """Stop every tool-call list in `tag` after its first call, in place.

    Enforces `parallel_tool_calls=false` in the grammar. In every registered
    tag, `_TOOL_CALL_LIST_FORMATS` repeat tool calls, never arguments.
    """

    def visit(node: Any) -> None:
        if isinstance(node, BaseModel):
            if isinstance(node, _TOOL_CALL_LIST_FORMATS):
                node.stop_after_first = True
            for name in type(node).model_fields:
                visit(getattr(node, name))
        elif isinstance(node, (list, tuple)):
            for item in node:
                visit(item)

    visit(tag.format)
    return tag

register_vllm_structural_tag(model, *, builtin_tools=False)

Register a vLLM-owned structural tag builder.

Parameters:

  • model

    (str) –

    Structural tag model key.

  • builtin_tools

    (bool, default: False ) –

    Whether the model can call non-function tools, so its builder receives every request tool instead of only the function tools from get_function_tools.

Source code in vllm/tool_parsers/structural_tag_registry.py
def register_vllm_structural_tag(
    model: str,
    *,
    builtin_tools: bool = False,
) -> Callable[[StructuralTagBuilder], StructuralTagBuilder]:
    """Register a vLLM-owned structural tag builder.

    Args:
        model: Structural tag model key.
        builtin_tools: Whether the model can call non-function tools, so its
            builder receives every request tool instead of only the function
            tools from `get_function_tools`.

    """

    def decorator(func: StructuralTagBuilder) -> StructuralTagBuilder:
        _VLLM_STRUCTURAL_TAG_REGISTRY[model] = func
        if builtin_tools:
            _BUILTIN_TOOL_STRUCTURAL_TAG_MODELS.add(model)
        return func

    return decorator

resolve_tool_strictness(tools, tool_choice, strict_level)

Decide whether a structural tag applies and pin each tool's strict.

A tool without an explicit strict is treated as non-strict: its call envelope is still constrained, but its arguments stay free unless the server level is PARAMETER. None means no structural tag.

Source code in vllm/tool_parsers/structural_tag_registry.py
def resolve_tool_strictness(
    tools: Sequence[ChatCompletionToolsParam | ResponsesTool],
    tool_choice: ToolChoice,
    strict_level: ToolStrictLevel,
) -> Sequence[ChatCompletionToolsParam | ResponsesTool] | None:
    """Decide whether a structural tag applies and pin each tool's `strict`.

    A tool without an explicit `strict` is treated as non-strict: its call
    envelope is still constrained, but its arguments stay free unless the
    server level is PARAMETER. `None` means no structural tag.
    """
    if (
        tool_choice == "auto"
        and strict_level == ToolStrictLevel.AUTO
        and not _any_tool_strict(tools)
    ):
        return None
    return [
        _with_tool_strict(
            tool, strict_level >= ToolStrictLevel.PARAMETER or _tool_is_strict(tool)
        )
        for tool in tools
    ]