Structural Tag¶

This page contains the API reference for the structural tag. For its usage, see Structural Tag Usage.

Top Level Classes¶

class xgrammar.StructuralTag(*, type: Literal['structural_tag'] = 'structural_tag', format: Union[AnyTextFormat, ConstStringFormat, JSONSchemaFormat, GrammarFormat, RegexFormat, QwenXMLParameterFormat, OrFormat, SequenceFormat, TagFormat, TriggeredTagsFormat, TagsWithSeparatorFormat])[source]¶

Bases: BaseModel

Describes a complete structural tag structure. It corresponds to "response_format": {"type": "structural_tag", "format": {...}} in API.

type: Literal['structural_tag']¶: The type must be “structural_tag”.

format: Union[AnyTextFormat, ConstStringFormat, JSONSchemaFormat, GrammarFormat, RegexFormat, QwenXMLParameterFormat, OrFormat, SequenceFormat, TagFormat, TriggeredTagsFormat, TagsWithSeparatorFormat]¶: The format of the structural tag. Could be any of the structural tag formats.

static from_legacy_structural_tag(tags: List[StructuralTagItem], triggers: List[str]) → StructuralTag[source]¶: Convert a legacy structural tag item to a structural tag.

static from_json(json_str: Union[str, Dict[str, Any]]) → StructuralTag[source]¶: Convert a JSON string to a structural tag.

class xgrammar.structural_tag.StructuralTagItem(*, begin: str, schema: Union[str, Type[BaseModel], Dict[str, Any]], end: str)[source]¶

Bases: BaseModel

Deprecated. Definition of a structural tag item.

See xgrammar.Grammar.from_structural_tag() for more details.

begin: str¶: The begin tag.

schema_: Union[str, Type[BaseModel], Dict[str, Any]]¶: The schema.

end: str¶: The end tag.

Format Union¶

xgrammar.structural_tag.Format(*args, **kwargs)¶

Union of all structural tag formats.

alias of Annotated[Union[AnyTextFormat, ConstStringFormat, JSONSchemaFormat, GrammarFormat, RegexFormat, QwenXMLParameterFormat, OrFormat, SequenceFormat, TagFormat, TriggeredTagsFormat, TagsWithSeparatorFormat]]

Basic Formats¶

class xgrammar.structural_tag.ConstStringFormat(*, type: Literal['const_string'] = 'const_string', value: str)[source]¶

Bases: BaseModel

A format that matches a constant string.

type: Literal['const_string']¶: The type of the format.

value: str¶: The constant string.

class xgrammar.structural_tag.JSONSchemaFormat(*, type: Literal['json_schema'] = 'json_schema', json_schema: Union[bool, Dict[str, Any]])[source]¶

Bases: BaseModel

A format that matches a JSON schema.

type: Literal['json_schema']¶: The type of the format.

json_schema: Union[bool, Dict[str, Any]]¶: The JSON schema.

class xgrammar.structural_tag.AnyTextFormat(*, type: Literal['any_text'] = 'any_text')[source]¶

Bases: BaseModel

A format that matches any text.

type: Literal['any_text']¶: The type of the format.

class xgrammar.structural_tag.GrammarFormat(*, type: Literal['grammar'] = 'grammar', grammar: str)[source]¶

Bases: BaseModel

A format that matches an ebnf grammar.

type: Literal['grammar']¶: The type of the format.

grammar: str¶: The ebnf grammar.

class xgrammar.structural_tag.RegexFormat(*, type: Literal['regex'] = 'regex', pattern: str)[source]¶

Bases: BaseModel

A format that matches a regex pattern.

type: Literal['regex']¶: The type of the format.

pattern: str¶: The regex pattern.

class xgrammar.structural_tag.QwenXMLParameterFormat(*, type: Literal['qwen_xml_parameter'] = 'qwen_xml_parameter', json_schema: Union[bool, Dict[str, Any]])[source]¶

Bases: BaseModel

A format that matches Qwen XML function calls.

Examples

structural_tag = QwenXMLParameterFormat(
    json_schema={
        "type": "qwen_xml_parameter",
        "json_schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }
)

The above structural tag can accept the following outputs:

<parameter=name>Bob</parameter><parameter=age>100</parameter>
<parameter=name>"Bob&lt;"</parameter><parameter=age>100</parameter>

type: Literal['qwen_xml_parameter']¶: The type of the format.

json_schema: Union[bool, Dict[str, Any]]¶: The JSON schema for the parameters of the function calling.

Combinatorial Formats¶

class xgrammar.structural_tag.SequenceFormat(*, type: Literal['sequence'] = 'sequence', elements: List[Union[AnyTextFormat, ConstStringFormat, JSONSchemaFormat, GrammarFormat, RegexFormat, QwenXMLParameterFormat, OrFormat, SequenceFormat, TagFormat, TriggeredTagsFormat, TagsWithSeparatorFormat]])[source]¶

Bases: BaseModel

A format that matches a sequence of formats.

type: Literal['sequence']¶: The type of the format.

elements: List[Format]¶: The elements of the sequence.

class xgrammar.structural_tag.OrFormat(**data: Any)[source]¶

Bases: BaseModel

A format that matches one of the formats.

type: Literal['or']¶: The type of the format.

elements: List[Format]¶: The elements of the or.

class xgrammar.structural_tag.TagFormat(*, type: Literal['tag'] = 'tag', begin: str, content: Union[AnyTextFormat, ConstStringFormat, JSONSchemaFormat, GrammarFormat, RegexFormat, QwenXMLParameterFormat, OrFormat, SequenceFormat, TagFormat, TriggeredTagsFormat, TagsWithSeparatorFormat], end: str)[source]¶

Bases: BaseModel

A format that matches a tag: begin content end.

type: Literal['tag']¶: The type of the format.

begin: str¶: The begin tag.

content: Format¶: The content of the tag. It can be any of the formats.

end: str¶: The end tag.

class xgrammar.structural_tag.TriggeredTagsFormat(*, type: Literal['triggered_tags'] = 'triggered_tags', triggers: List[str], tags: List[TagFormat], at_least_one: bool = False, stop_after_first: bool = False)[source]¶

Bases: BaseModel

A format that matches triggered tags. It can allow any output until a trigger is encountered, then dispatch to the corresponding tag; when the end tag is encountered, the grammar will allow any following output, until the next trigger is encountered.

Each tag should be matched by exactly one trigger. “matching” means the trigger should be a prefix of the begin tag.

Examples

structural_tag = TriggeredTagsFormat(
    triggers=["<function="],
    tags=[
        TagFormat(
            begin="<function=func1>",
            content=JSONSchemaFormat(json_schema=...),
            end="</function>",
        ),
        TagFormat(
            begin="<function=func2>",
            content=JSONSchemaFormat(json_schema=...),
            end="</function>",
        ),
    ],
    at_least_one=False,
    stop_after_first=False,
)

The above structural tag can accept the following outputs:

<function=func1>{"name": "John", "age": 30}</function>
<function=func2>{"name": "Jane", "age": 25}</function>
any_text<function=func1>{"name": "John", "age": 30}</function>any_text1<function=func2>{"name": "Jane", "age": 25}</function>any_text2

type: Literal['triggered_tags']¶: The type of the format.

triggers: List[str]¶: The triggers of the triggered tags.

tags: List[TagFormat]¶: The tags of the triggered tags.

at_least_one: bool¶: Whether at least one of the tags must be generated.

stop_after_first: bool¶: Whether to stop after the first tag is generated.

class xgrammar.structural_tag.TagsWithSeparatorFormat(*, type: Literal['tags_with_separator'] = 'tags_with_separator', tags: List[TagFormat], separator: str, at_least_one: bool = False, stop_after_first: bool = False)[source]¶

Bases: BaseModel

A format that matches a tags with separator. It can match zero, one, or more tags, separated by the separator, with no other text allowed.

Examples

structural_tag = TagsWithSeparatorFormat(
    tags=[
        TagFormat(begin="<function=func1>", content=JSONSchemaFormat(json_schema=...), end="</function>"),
        TagFormat(begin="<function=func2>", content=JSONSchemaFormat(json_schema=...), end="</function>"),
    ],
    separator=",",
    at_least_one=False,
    stop_after_first=False,
)

The above structural tag can accept an empty string, or the following outputs:

<function=func1>{"name": "John", "age": 30}</function>
<function=func1>{"name": "John", "age": 30}</function>,<function=func2>{"name": "Jane", "age": 25}</function>
<function=func1>{"name": "John", "age": 30}</function>,<function=func2>{"name": "Jane", "age": 25}</function>,<function=func1>{"name": "John", "age": 30}</function>

type: Literal['tags_with_separator']¶: The type of the format.

tags: List[TagFormat]¶: The tags of the tags with separator.

separator: str¶: The separator of the tags with separator.

at_least_one: bool¶: Whether at least one of the tags must be matched.

stop_after_first: bool¶: Whether to stop after the first tag is matched.