[Rust Frontend] Split argument grammars into schema resolution and per-model rendering (#59395)

Signed-off-by: Bugen Zhao <i@bugenzhao.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Bugen Zhao
2026-10-01 05:43:18 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent ac9126e58a
commit b2d3a3b9ad
5 changed files with 1050 additions and 427 deletions
+125 -140
View File
@@ -56,21 +56,18 @@
"type": "or",
"elements": [
{
"type": "plus",
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
}
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
@@ -119,60 +116,57 @@
"type": "or",
"elements": [
{
"type": "plus",
"content": {
"type": "or",
"elements": [
{
"type": "tag",
"begin": "<|open|>argument key=\"y\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"type": "sequence",
"elements": [
{
"type": "tag",
"begin": "<|open|>argument key=\"y\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"end": "<|close|>argument<|sep|>"
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
{
"type": "tag",
"begin": "<|open|>argument key=\"x\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
"begin": "<|open|>argument key=\"x\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"end": "<|close|>argument<|sep|>"
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
{
"type": "tag",
"begin": "<|open|>argument key=\"items\" type=\"array\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
"begin": "<|open|>argument key=\"items\" type=\"array\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "array",
"items": {
"type": "string"
}
},
"end": "<|close|>argument<|sep|>"
}
]
}
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
"end": "<|close|>argument<|sep|>"
}
]
},
{
"type": "tag",
@@ -287,21 +281,18 @@
"type": "or",
"elements": [
{
"type": "plus",
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
}
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
@@ -350,60 +341,57 @@
"type": "or",
"elements": [
{
"type": "plus",
"content": {
"type": "or",
"elements": [
{
"type": "tag",
"begin": "<|open|>argument key=\"y\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"type": "sequence",
"elements": [
{
"type": "tag",
"begin": "<|open|>argument key=\"y\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"end": "<|close|>argument<|sep|>"
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
{
"type": "tag",
"begin": "<|open|>argument key=\"x\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
"begin": "<|open|>argument key=\"x\" type=\"number\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "number"
},
"end": "<|close|>argument<|sep|>"
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
{
"type": "tag",
"begin": "<|open|>argument key=\"items\" type=\"array\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
"begin": "<|open|>argument key=\"items\" type=\"array\"<|sep|>",
"content": {
"type": "json_schema",
"json_schema": {
"type": "array",
"items": {
"type": "string"
}
},
"end": "<|close|>argument<|sep|>"
}
]
}
"style": "json",
"any_order": false,
"max_whitespace_cnt": null,
"excludes": []
},
"end": "<|close|>argument<|sep|>"
}
]
},
{
"type": "tag",
@@ -517,21 +505,18 @@
"type": "or",
"elements": [
{
"type": "plus",
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "tag",
"begin": "<|open|>argument key=\"location\" type=\"string\"<|sep|>",
"content": {
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
}
"type": "any_text",
"excludes": [
"<|close|>argument<|sep|>",
"<|close|>call<|sep|>"
],
"max_tokens": null,
"max_chars": null
},
"end": "<|close|>argument<|sep|>"
},
{
"type": "tag",
+11 -13
View File
@@ -10,18 +10,17 @@ sequence
/[1-9][0-9]*/
`"<|sep|>`
or
plus tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ location: string }) `<|close|>json<|sep|>`
tag `<|open|>call tool="add" index="` .. `<|close|>call<|sep|>`
sequence
/[1-9][0-9]*/
`"<|sep|>`
or
plus
or
tag `<|open|>argument key="y" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="x" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="items" type="array"<|sep|>` json(string[]) `<|close|>argument<|sep|>`
sequence
tag `<|open|>argument key="y" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="x" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="items" type="array"<|sep|>` json(string[]) `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ y: number, x: number, items: string[] }) `<|close|>json<|sep|>`
optional `<|close|>message<|sep|>`
@@ -36,18 +35,17 @@ sequence
/[1-9][0-9]*/
`"<|sep|>`
or
plus tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ location: string }) `<|close|>json<|sep|>`
tag `<|open|>call tool="add" index="` .. `<|close|>call<|sep|>`
sequence
/[1-9][0-9]*/
`"<|sep|>`
or
plus
or
tag `<|open|>argument key="y" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="x" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="items" type="array"<|sep|>` json(string[]) `<|close|>argument<|sep|>`
sequence
tag `<|open|>argument key="y" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="x" type="number"<|sep|>` json(number) `<|close|>argument<|sep|>`
tag `<|open|>argument key="items" type="array"<|sep|>` json(string[]) `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ y: number, x: number, items: string[] }) `<|close|>json<|sep|>`
optional `<|close|>message<|sep|>`
@@ -62,6 +60,6 @@ sequence
/[1-9][0-9]*/
`"<|sep|>`
or
plus tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>argument key="location" type="string"<|sep|>` text excluding [`<|close|>argument<|sep|>`, `<|close|>call<|sep|>`] `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ location: string }) `<|close|>json<|sep|>`
optional `<|close|>message<|sep|>`
+1
View File
@@ -17,6 +17,7 @@ use xgrammar_structural_tag::{
use crate::tool::Tool;
pub mod arguments;
#[cfg(any(test, feature = "test-util"))]
pub mod test_utils;
@@ -0,0 +1,845 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright contributors to the vLLM project
//! Tool-call argument grammars for keyed-parameter protocols.
//!
//! Many tool-call protocols render the root arguments object as a sequence of
//! keyed parameters. [`arguments`] owns what follows from the JSON schema
//! alone: which parameters exist, their order and presence, and every option
//! a parameter value can take, with `$ref`s resolved and unions, type arrays,
//! and enums split per option. An [`ArgumentSyntax`], implemented next to each
//! parser, decides how one parameter and its value options are rendered.
//! Values nested below a parameter stay with XGrammar's JSON schema converter
//! through [`ValueOption::json`].
//!
//! This is for protocols whose argument rendering XGrammar's per-model schema
//! styles do not cover, or cover without matching the parser. Parameter lists
//! follow those styles' fixed-order property semantics, with these deliberate
//! differences:
//!
//! - Unions, type arrays, and mixed enums split into one option per
//! alternative, so a syntax can keep a value's type label consistent with
//! the value.
//! - Additional-property keys are not required to differ from declared keys.
//! - String `format` and length constraints are not enforced. `pattern` is.
//! - `minProperties` and `maxProperties` are not enforced.
//! - `allOf` with more than one schema accepts any value.
use std::collections::HashSet;
use serde_json::{Map, Value, json};
use xgrammar_structural_tag::format::{Format, JsonSchemaFormat};
/// Bound on `$ref` and combinator nesting within one value, which keeps a long
/// chain of references from overflowing the stack.
const MAX_SCHEMA_DEPTH: usize = 32;
/// The schema accepting any value.
static ANY_SCHEMA: Value = Value::Bool(true);
/// How one protocol renders the parameters of a call.
pub trait ArgumentSyntax {
/// Text around and between parameters, or `None` when parameters are
/// adjacent.
fn separator(&self) -> Option<Format>;
/// The grammar of one parameter whose value takes one of `options`, or
/// `None` when none of them can be rendered.
fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option<Format>;
}
/// The key of one parameter.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParameterKey<'a> {
/// A property declared by the schema.
Declared(&'a str),
/// Any key allowed by `additionalProperties` or an unconstrained schema.
Free,
}
impl ParameterKey<'_> {
/// Pattern of free keys, as in XGrammar's XML styles.
pub const FREE_PATTERN: &'static str = "[a-zA-Z_][a-zA-Z0-9_]*";
/// `prefix KEY suffix content end`: a tag for a declared key, or a
/// sequence matching [`Self::FREE_PATTERN`] for a free key.
pub fn tag(&self, prefix: &str, suffix: &str, content: Format, end: &str) -> Format {
match self {
Self::Declared(key) => Format::tag(format!("{prefix}{key}{suffix}"), content, end),
Self::Free => Format::sequence(vec![
Format::const_string(prefix),
Format::regex(Self::FREE_PATTERN),
Format::const_string(suffix),
content,
Format::const_string(end),
]),
}
}
}
/// JSON type of a value option.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum JsonType {
String,
Number,
Boolean,
Null,
Object,
Array,
}
impl JsonType {
const ALL: [Self; 6] = [
Self::String,
Self::Number,
Self::Boolean,
Self::Null,
Self::Object,
Self::Array,
];
/// The type's JSON name. Integers are numbers.
pub fn name(self) -> &'static str {
match self {
Self::String => "string",
Self::Number => "number",
Self::Boolean => "boolean",
Self::Null => "null",
Self::Object => "object",
Self::Array => "array",
}
}
fn of_schema_type(name: &str) -> Option<Self> {
Some(match name {
"string" => Self::String,
"integer" | "number" => Self::Number,
"boolean" => Self::Boolean,
"null" => Self::Null,
"object" => Self::Object,
"array" => Self::Array,
_ => return None,
})
}
fn of_value(value: &Value) -> Self {
match value {
Value::String(_) => Self::String,
Value::Number(_) => Self::Number,
Value::Bool(_) => Self::Boolean,
Value::Null => Self::Null,
Value::Object(_) => Self::Object,
Value::Array(_) => Self::Array,
}
}
/// Schema accepting every JSON value of this type.
fn any_schema(self) -> Value {
match self {
Self::Object => json!({ "type": "object", "additionalProperties": true }),
Self::Array => json!({ "type": "array", "items": true }),
_ => json!({ "type": self.name() }),
}
}
}
/// One option of a parameter value: a single JSON type under a narrowed
/// schema, a constant, or any value of the type.
pub struct ValueOption<'a> {
/// The option's JSON type.
pub ty: JsonType,
source: OptionSource,
cx: &'a ArgumentContext<'a>,
}
enum OptionSource {
/// A schema narrowed to [`ValueOption::ty`].
Schema(Map<String, Value>),
/// A `const` or `enum` value.
Literal(Value),
/// Any value of [`ValueOption::ty`].
Any,
}
impl ValueOption<'_> {
/// The option as JSON text.
pub fn json(&self) -> Format {
match &self.source {
OptionSource::Schema(schema) => self.cx.json(Value::Object(schema.clone())),
OptionSource::Literal(value) => self.cx.json(json!({ "const": value })),
OptionSource::Any => self.cx.json(self.ty.any_schema()),
}
}
/// The option as raw text that ends before any of `terminators`, or `None`
/// for a non-string option or a constant containing a terminator or an
/// excluded substring.
pub fn raw_string(&self, terminators: &[&str]) -> Option<Format> {
if self.ty != JsonType::String {
return None;
}
let excludes = self
.cx
.options
.excludes
.iter()
.map(String::as_str)
.chain(terminators.iter().copied())
.collect::<Vec<_>>();
let text = || Format::any_text_excluding(&excludes);
Some(match &self.source {
OptionSource::Literal(Value::String(value)) => {
if excludes.iter().any(|exclude| value.contains(exclude)) {
return None;
}
Format::const_string(value)
}
OptionSource::Literal(_) => unreachable!("literal options are typed by their value"),
OptionSource::Schema(schema) => match schema.get("pattern").and_then(Value::as_str) {
Some(pattern) => Format::regex(pattern),
None => text(),
},
OptionSource::Any => text(),
})
}
}
/// Request options that also apply to nested JSON schema regions.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ArgumentOptions {
/// Whether object properties may appear in any order, at the parameter
/// level and in nested objects.
pub any_order: bool,
/// Maximum consecutive whitespace characters, or no limit when unset.
pub max_whitespace_cnt: Option<i32>,
/// Substrings forbidden in string values, nested JSON strings included.
pub excludes: Vec<String>,
}
/// Reference targets expanded while collecting one value's options.
#[derive(Default)]
struct Expansion {
expanded: HashSet<*const Value>,
/// Whether a reference was skipped because its target already expanded.
skipped: bool,
}
/// Request state shared by the value options of one call.
struct ArgumentContext<'a> {
options: &'a ArgumentOptions,
/// The parameters schema, which local `$ref`s resolve against.
root: &'a Value,
}
impl ArgumentContext<'_> {
/// A JSON value under `schema`, which keeps the root's definitions so its
/// local `$ref`s still resolve.
fn json(&self, mut schema: Value) -> Format {
if let (Some(schema), Some(root)) = (schema.as_object_mut(), self.root.as_object()) {
for key in ["$defs", "definitions"] {
if let Some(definitions) = root.get(key) {
schema.entry(key).or_insert_with(|| definitions.clone());
}
}
}
Format::JsonSchema(JsonSchemaFormat {
excludes: self.options.excludes.clone(),
..JsonSchemaFormat::new(schema)
.with_any_order(self.options.any_order)
.with_max_whitespace_cnt(self.options.max_whitespace_cnt)
})
}
fn resolve_ref(&self, reference: &str) -> Option<&Value> {
self.root.pointer(reference.strip_prefix('#')?)
}
/// Follow `$ref`s and single-schema `allOf`s at the root.
fn resolve<'s>(&'s self, schema: &'s Value, depth: usize) -> &'s Value {
if depth > MAX_SCHEMA_DEPTH {
return &ANY_SCHEMA;
}
if let Some(reference) = schema.get("$ref").and_then(Value::as_str) {
return match self.resolve_ref(reference) {
Some(target) => self.resolve(target, depth + 1),
None => &ANY_SCHEMA,
};
}
match schema.get("allOf").and_then(Value::as_array).map(Vec::as_slice) {
Some([schema]) => self.resolve(schema, depth + 1),
_ => schema,
}
}
/// Every option of a value under `schema`.
///
/// Each reference target expands at most once. A union gains no values
/// from a repeated alternative, and a definition shared by several
/// alternatives would otherwise expand once per path to it, exponentially
/// in the nesting. A schema whose references only lead back into it
/// accepts any value.
fn value_options(&self, schema: &Value) -> Vec<ValueOption<'_>> {
let mut expansion = Expansion::default();
let options = self.value_options_at(schema, 0, &mut expansion);
if options.is_empty() && expansion.skipped {
return self.any_value();
}
options
}
fn value_options_at(
&self,
schema: &Value,
depth: usize,
expansion: &mut Expansion,
) -> Vec<ValueOption<'_>> {
let schema = match schema {
_ if depth > MAX_SCHEMA_DEPTH => return self.any_value(),
Value::Bool(false) => return vec![],
Value::Object(schema) => schema,
_ => return self.any_value(),
};
if let Some(reference) = schema.get("$ref").and_then(Value::as_str) {
let Some(target) = self.resolve_ref(reference) else {
return self.any_value();
};
if !expansion.expanded.insert(std::ptr::from_ref(target)) {
expansion.skipped = true;
return vec![];
}
return self.value_options_at(target, depth + 1, expansion);
}
if let Some(value) = schema.get("const") {
return vec![self.literal(value)];
}
if let Some(values) = schema.get("enum").and_then(Value::as_array) {
return values.iter().map(|value| self.literal(value)).collect();
}
if let Some(options) =
schema.get("anyOf").or_else(|| schema.get("oneOf")).and_then(Value::as_array)
{
return options
.iter()
.flat_map(|option| self.value_options_at(option, depth + 1, expansion))
.collect();
}
if let Some(schemas) = schema.get("allOf").and_then(Value::as_array) {
return match schemas.as_slice() {
[schema] => self.value_options_at(schema, depth + 1, expansion),
_ => self.any_value(),
};
}
match schema.get("type") {
Some(Value::String(name)) => self.typed(schema.clone(), name).into_iter().collect(),
Some(Value::Array(names)) => names
.iter()
.filter_map(Value::as_str)
.filter_map(|name| {
let mut schema = schema.clone();
schema.insert("type".to_string(), Value::String(name.to_string()));
self.typed(schema, name)
})
.collect(),
_ => self.any_value(),
}
}
fn typed(&self, schema: Map<String, Value>, type_name: &str) -> Option<ValueOption<'_>> {
Some(ValueOption {
ty: JsonType::of_schema_type(type_name)?,
source: OptionSource::Schema(schema),
cx: self,
})
}
fn literal(&self, value: &Value) -> ValueOption<'_> {
ValueOption {
ty: JsonType::of_value(value),
source: OptionSource::Literal(value.clone()),
cx: self,
}
}
fn any_value(&self) -> Vec<ValueOption<'_>> {
JsonType::ALL
.into_iter()
.map(|ty| ValueOption {
ty,
source: OptionSource::Any,
cx: self,
})
.collect()
}
}
/// Build the grammar of one call's arguments under `schema`, the tool's
/// parameters schema, rendering each parameter with `syntax`.
pub fn arguments(schema: &Value, syntax: &dyn ArgumentSyntax, options: &ArgumentOptions) -> Format {
let cx = ArgumentContext {
options,
root: schema,
};
let parameter =
|key: ParameterKey<'_>, schema: &Value| syntax.parameter(key, &cx.value_options(schema));
let schema = cx.resolve(schema, 0);
let (properties, additional) = match schema {
Value::Object(schema) => {
let additional = match schema.get("additionalProperties") {
Some(Value::Bool(false)) => None,
Some(additional) => parameter(ParameterKey::Free, additional),
// Strict schemas allow no undeclared properties, and a schema
// without declared properties allows any.
None if schema.contains_key("properties") => None,
None => parameter(ParameterKey::Free, &ANY_SCHEMA),
};
let required = schema
.get("required")
.and_then(Value::as_array)
.map(|required| required.iter().filter_map(Value::as_str).collect::<Vec<_>>())
.unwrap_or_default();
let properties = schema
.get("properties")
.and_then(Value::as_object)
.into_iter()
.flatten()
.filter_map(|(key, schema)| {
let parameter = parameter(ParameterKey::Declared(key), schema)?;
Some((parameter, required.contains(&key.as_str())))
})
.collect();
(properties, additional)
}
Value::Bool(false) => (vec![], None),
_ => (vec![], parameter(ParameterKey::Free, &ANY_SCHEMA)),
};
parameter_list(options, syntax.separator(), properties, additional)
}
/// Parameters in declared order, required ones mandatory, followed by any
/// number of additional parameters; or, under `any_order`, any sequence of
/// them with at least one when some are required.
fn parameter_list(
options: &ArgumentOptions,
separator: Option<Format>,
properties: Vec<(Format, bool)>,
additional: Option<Format>,
) -> Format {
let separated = |parameter: Format| match &separator {
Some(separator) => Format::sequence(vec![parameter, separator.clone()]),
None => parameter,
};
let mut elements = Vec::from_iter(separator.clone());
if options.any_order {
let any_required = properties.iter().any(|(_, required)| *required);
let parameters = properties
.into_iter()
.map(|(parameter, _)| parameter)
.chain(additional)
.collect::<Vec<_>>();
if !parameters.is_empty() {
let parameter = separated(one_of(parameters));
elements.push(if any_required {
Format::plus(parameter)
} else {
Format::star(parameter)
});
}
} else {
for (parameter, required) in properties {
let parameter = separated(parameter);
elements.push(if required {
parameter
} else {
Format::optional(parameter)
});
}
if let Some(additional) = additional {
elements.push(Format::star(separated(additional)));
}
}
match elements.len() {
0 => Format::const_string(""),
1 => elements.pop().expect("one element"),
_ => Format::sequence(elements),
}
}
/// One of `formats`, without an `or` around a single format.
pub fn one_of(mut formats: Vec<Format>) -> Format {
if formats.len() == 1 {
formats.pop().expect("one format")
} else {
Format::or(formats)
}
}
/// `options` grouped by `key`, in order of first appearance.
pub fn group_by<'o, 'a, K: PartialEq>(
options: &'o [ValueOption<'a>],
key: impl Fn(&ValueOption<'a>) -> K,
) -> Vec<(K, Vec<&'o ValueOption<'a>>)> {
let mut groups: Vec<(K, Vec<&ValueOption<'a>>)> = Vec::new();
for option in options {
let key = key(option);
match groups.iter_mut().find(|(existing, _)| *existing == key) {
Some((_, group)) => group.push(option),
None => groups.push((key, vec![option])),
}
}
groups
}
#[cfg(test)]
mod tests {
use super::*;
use crate::output_grammar::test_utils::outline;
use expect_test::{Expect, expect};
use serde_json::json;
/// Qwen-like: `<parameter=KEY>VALUE</parameter>` on separate lines, with
/// raw strings.
struct Untyped;
impl ArgumentSyntax for Untyped {
fn separator(&self) -> Option<Format> {
Some(Format::const_string("\n"))
}
fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option<Format> {
let values = options
.iter()
.filter_map(|option| match option.ty {
JsonType::String => option.raw_string(&["</parameter>"]),
_ => Some(option.json()),
})
.collect::<Vec<_>>();
(!values.is_empty())
.then(|| key.tag("<parameter=", ">", one_of(values), "</parameter>"))
}
}
/// K3-like: `<arg key="KEY" type="TYPE">VALUE</arg>` with adjacent
/// parameters and one header per JSON type.
struct Typed;
impl ArgumentSyntax for Typed {
fn separator(&self) -> Option<Format> {
None
}
fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option<Format> {
let tags = group_by(options, |option| option.ty)
.into_iter()
.filter_map(|(ty, options)| {
let values = options
.into_iter()
.filter_map(|option| match ty {
JsonType::String => option.raw_string(&["</arg>"]),
_ => Some(option.json()),
})
.collect::<Vec<_>>();
(!values.is_empty()).then(|| {
let suffix = format!("\" type=\"{}\">", ty.name());
key.tag("<arg key=\"", &suffix, one_of(values), "</arg>")
})
})
.collect::<Vec<_>>();
(!tags.is_empty()).then(|| one_of(tags))
}
}
fn check(schema: Value, syntax: &dyn ArgumentSyntax, expected: Expect) {
check_with(schema, syntax, &ArgumentOptions::default(), expected);
}
fn check_with(
schema: Value,
syntax: &dyn ArgumentSyntax,
options: &ArgumentOptions,
expected: Expect,
) {
expected.assert_eq(&outline(&arguments(&schema, syntax, options)));
}
fn weather_schema() -> Value {
json!({
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "enum": ["celsius", "fahrenheit"] },
"days": { "type": "integer", "minimum": 1 }
},
"required": ["location"]
})
}
#[test]
fn parameters_follow_declared_order() {
check(
weather_schema(),
&Untyped,
expect![[r#"
sequence
`\n`
sequence
tag `<parameter=location>` text excluding [`</parameter>`] `</parameter>`
`\n`
optional
sequence
tag `<parameter=unit>` .. `</parameter>`
or
`celsius`
`fahrenheit`
`\n`
optional
sequence
tag `<parameter=days>` json(integer(minimum=1)) `</parameter>`
`\n`
"#]],
);
}
#[test]
fn any_order_repeats_any_declared_parameter() {
check_with(
weather_schema(),
&Typed,
&ArgumentOptions {
any_order: true,
..Default::default()
},
expect![[r#"
plus
or
tag `<arg key="location" type="string">` text excluding [`</arg>`] `</arg>`
tag `<arg key="unit" type="string">` .. `</arg>`
or
`celsius`
`fahrenheit`
tag `<arg key="days" type="number">` json(integer(minimum=1)) any_order `</arg>`
"#]],
);
}
#[test]
fn unions_and_mixed_enums_split_per_option() {
check(
json!({
"type": "object",
"properties": {
"id": { "type": ["integer", "string", "null"] },
"mode": { "enum": ["fast", 1] },
"q": { "anyOf": [{ "type": "string", "pattern": "[a-z]+" }, { "type": "array", "items": { "type": "string" } }] }
},
"required": ["q"]
}),
&Typed,
expect![[r#"
sequence
optional
or
tag `<arg key="id" type="number">` json(integer) `</arg>`
tag `<arg key="id" type="string">` text excluding [`</arg>`] `</arg>`
tag `<arg key="id" type="null">` json(null) `</arg>`
optional
or
tag `<arg key="mode" type="string">` `fast` `</arg>`
tag `<arg key="mode" type="number">` json(1) `</arg>`
or
tag `<arg key="q" type="string">` /[a-z]+/ `</arg>`
tag `<arg key="q" type="array">` json(string[]) `</arg>`
"#]],
);
}
#[test]
fn references_resolve_against_the_root_definitions() {
let schema = json!({
"$defs": {
"place": { "type": "object", "properties": { "city": { "type": "string" } } },
"name": { "type": "string" }
},
"type": "object",
"properties": {
"place": { "$ref": "#/$defs/place" },
"name": { "$ref": "#/$defs/name" }
},
"required": ["place", "name"]
});
let arguments = arguments(&schema, &Typed, &ArgumentOptions::default());
expect![[r#"
sequence
tag `<arg key="place" type="object">` json({ city?: string } where place = { city?: string }, name = string) `</arg>`
tag `<arg key="name" type="string">` text excluding [`</arg>`] `</arg>`
"#]].assert_eq(&outline(&arguments));
// Nested JSON regions keep the definitions for their own references.
let serialized = serde_json::to_value(&arguments).unwrap();
assert_eq!(
serialized["elements"][0]["content"]["json_schema"]["$defs"],
schema["$defs"]
);
}
#[test]
fn shared_definitions_expand_once() {
// Each level unions four references to the next, so expanding every
// path would yield 4^12 options.
let mut definitions = Map::new();
for level in 0..12 {
let next = json!({ "$ref": format!("#/$defs/level{}", level + 1) });
definitions.insert(format!("level{level}"), json!({ "anyOf": vec![next; 4] }));
}
definitions.insert("level12".to_string(), json!({ "type": "string" }));
check(
json!({
"$defs": definitions,
"type": "object",
"properties": { "p": { "$ref": "#/$defs/level0" } },
"required": ["p"]
}),
&Untyped,
expect![[r#"
sequence
`\n`
sequence
tag `<parameter=p>` text excluding [`</parameter>`] `</parameter>`
`\n`
"#]],
);
}
#[test]
fn references_that_only_cycle_accept_any_value() {
check(
json!({
"$defs": {
"a": { "anyOf": [{ "$ref": "#/$defs/b" }] },
"b": { "$ref": "#/$defs/a" }
},
"type": "object",
"properties": { "p": { "$ref": "#/$defs/a" } },
"required": ["p"]
}),
&Untyped,
expect![[r#"
sequence
`\n`
sequence
tag `<parameter=p>` .. `</parameter>`
or
text excluding [`</parameter>`]
json(number where a = b, b = a)
json(boolean where a = b, b = a)
json(null where a = b, b = a)
json({ ... } where a = b, b = a)
json(any[] where a = b, b = a)
`\n`
"#]],
);
}
#[test]
fn unconstrained_arguments_accept_any_parameter() {
check(
json!(true),
&Typed,
expect![[r#"
star
or
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="string">`
text excluding [`</arg>`]
`</arg>`
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="number">`
json(number)
`</arg>`
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="boolean">`
json(boolean)
`</arg>`
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="null">`
json(null)
`</arg>`
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="object">`
json({ ... })
`</arg>`
sequence
`<arg key="`
/[a-zA-Z_][a-zA-Z0-9_]*/
`" type="array">`
json(any[])
`</arg>`
"#]],
);
check(
json!(false),
&Untyped,
expect![[r#"
`\n`
"#]],
);
}
#[test]
fn additional_properties_follow_declared_ones() {
check(
json!({
"type": "object",
"properties": { "path": { "type": "string" } },
"required": ["path"],
"additionalProperties": { "type": "boolean" }
}),
&Untyped,
expect![[r#"
sequence
`\n`
sequence
tag `<parameter=path>` text excluding [`</parameter>`] `</parameter>`
`\n`
star
sequence
sequence
`<parameter=`
/[a-zA-Z_][a-zA-Z0-9_]*/
`>`
json(boolean)
`</parameter>`
`\n`
"#]],
);
}
#[test]
fn raw_literals_exclude_terminators_and_request_exclusions() {
check_with(
json!({
"type": "object",
"properties": { "tag": { "enum": ["ok", "a</call>b", "c</arg>d"] } },
"required": ["tag"]
}),
&Typed,
&ArgumentOptions {
excludes: vec!["</call>".to_string()],
..Default::default()
},
expect![[r#"
tag `<arg key="tag" type="string">` `ok` `</arg>`
"#]],
);
}
}
@@ -3,7 +3,7 @@
//! Structural-tag grammar for Kimi K3 XTML tool calls.
use serde_json::{Map, Value};
use serde_json::Value;
use xgrammar_structural_tag::Result;
use xgrammar_structural_tag::builders::{
ReasoningMode, StructuralTagBuilder, StructuralTagContext, StructuralTagOptions,
@@ -11,15 +11,67 @@ use xgrammar_structural_tag::builders::{
use xgrammar_structural_tag::format::{Format, JsonSchemaFormat, StructuralTag, TagFormat};
use xgrammar_structural_tag::tool::{BuilderToolChoice, FunctionToolParam, function_parameters};
use crate::output_grammar::arguments::{
self, ArgumentOptions, ArgumentSyntax, JsonType, ParameterKey, ValueOption, group_by, one_of,
};
use super::{
ARG_CLOSE, CALL_CLOSE, CLOSE, END_OF_MSG, JSON_CLOSE, JSON_OPEN, MESSAGE_CLOSE, OPEN,
ARG_CLOSE, ARG_OPEN, CALL_CLOSE, CLOSE, END_OF_MSG, JSON_CLOSE, JSON_OPEN, MESSAGE_CLOSE, OPEN,
RESPONSE_CLOSE, RESPONSE_OPEN, SEP, THINK_CLOSE, THINK_OPEN, TOOLS_CLOSE, TOOLS_OPEN,
};
pub(super) static KIMI_K3_STRUCTURAL_TAG_BUILDER: KimiK3StructuralTagBuilder =
KimiK3StructuralTagBuilder;
const XTML_TYPES: &[&str] = &["string", "number", "boolean", "null", "object", "array"];
/// XTML arguments:
/// `<|open|>argument key="KEY" type="TYPE"<|sep|>VALUE<|close|>argument<|sep|>`,
/// adjacent to each other.
///
/// The parser decodes each value by its `type` attribute, so every value option
/// sits under the attribute of its own JSON type. String values are raw text
/// and every other value is JSON.
struct XtmlArguments;
impl ArgumentSyntax for XtmlArguments {
fn separator(&self) -> Option<Format> {
None
}
fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option<Format> {
let escaped;
let key = match key {
ParameterKey::Declared(key) => {
escaped = escape_attr_value(key);
ParameterKey::Declared(&escaped)
}
ParameterKey::Free => ParameterKey::Free,
};
let arguments = group_by(options, |option| option.ty)
.into_iter()
.filter_map(|(ty, options)| {
let values = options
.into_iter()
.filter_map(|option| match ty {
// The parser ends the call at its close marker, so a
// string value may contain neither close marker.
JsonType::String => option.raw_string(&[ARG_CLOSE, CALL_CLOSE]),
_ => Some(option.json()),
})
.collect::<Vec<_>>();
(!values.is_empty()).then(|| {
let suffix = format!("\" type=\"{}\"{SEP}", ty.name());
key.tag(
&format!("{ARG_OPEN} key=\""),
&suffix,
one_of(values),
ARG_CLOSE,
)
})
})
.collect::<Vec<_>>();
(!arguments.is_empty()).then(|| one_of(arguments))
}
}
/// Kimi K3 XTML structural-tag builder.
#[derive(Debug, Clone, Copy, Default)]
@@ -92,8 +144,17 @@ fn tools_channel(tools: &[FunctionToolParam], options: StructuralTagOptions) ->
fn call_tag(tool: &FunctionToolParam, options: StructuralTagOptions) -> TagFormat {
let parameters = function_parameters(&tool.function);
let typed_arguments = arguments::arguments(
&parameters,
&XtmlArguments,
&ArgumentOptions {
any_order: options.any_order,
max_whitespace_cnt: options.max_whitespace_cnt,
excludes: vec![],
},
);
let call_body = Format::or(vec![
typed_arguments(&parameters, options),
typed_arguments,
raw_json_arguments(&parameters, options),
]);
@@ -111,189 +172,6 @@ fn call_tag(tool: &FunctionToolParam, options: StructuralTagOptions) -> TagForma
)
}
fn typed_arguments(parameters: &Value, options: StructuralTagOptions) -> Format {
let Some(schema) = parameters.as_object() else {
return if parameters == &Value::Bool(false) {
Format::const_string("")
} else {
Format::star(permissive_argument())
};
};
let Some(properties) = schema.get("properties").and_then(Value::as_object) else {
return Format::star(permissive_argument());
};
if properties.is_empty() {
return Format::star(permissive_argument());
}
let root_defs = root_definitions(schema);
let arguments = properties
.iter()
.flat_map(|(key, schema)| argument_tags(key, schema, &root_defs, options))
.map(Format::Tag)
.collect::<Vec<_>>();
let arguments = match arguments.as_slice() {
[argument] => argument.clone(),
_ => Format::or(arguments),
};
// Keep typed arguments order-agnostic and non-unique, but do not allow an
// empty call when the root schema declares required properties.
if schema
.get("required")
.and_then(Value::as_array)
.is_some_and(|required| !required.is_empty())
{
Format::plus(arguments)
} else {
Format::star(arguments)
}
}
fn argument_tags(
key: &str,
schema: &Value,
root_defs: &Map<String, Value>,
options: StructuralTagOptions,
) -> Vec<TagFormat> {
let types = schema_types(schema);
types
.into_iter()
.map(|xtml_type| {
let content = if xtml_type == "string" {
string_argument_content(schema)
} else {
json_schema(
attach_root_definitions(&narrow_schema_type(schema, xtml_type), root_defs),
options,
)
};
TagFormat::new(
format!(
"{OPEN}argument key=\"{}\" type=\"{xtml_type}\"{SEP}",
escape_attr_value(key)
),
content,
ARG_CLOSE,
)
})
.collect()
}
fn schema_types(schema: &Value) -> Vec<&'static str> {
let Some(schema) = schema.as_object() else {
return XTML_TYPES.to_vec();
};
let mut types = Vec::new();
match schema.get("type") {
Some(Value::String(value)) => push_schema_type(&mut types, value),
Some(Value::Array(values)) => {
for value in values.iter().filter_map(Value::as_str) {
push_schema_type(&mut types, value);
}
}
_ => {}
}
if types.is_empty()
&& let Some(value) = schema.get("const")
{
push_value_type(&mut types, value);
}
if types.is_empty()
&& let Some(values) = schema.get("enum").and_then(Value::as_array)
{
for value in values {
push_value_type(&mut types, value);
}
}
if types.is_empty() {
XTML_TYPES.to_vec()
} else {
types
}
}
fn push_value_type(types: &mut Vec<&'static str>, value: &Value) {
let xtml_type = match value {
Value::String(_) => "string",
Value::Number(_) => "number",
Value::Bool(_) => "boolean",
Value::Null => "null",
Value::Object(_) => "object",
Value::Array(_) => "array",
};
if !types.contains(&xtml_type) {
types.push(xtml_type);
}
}
fn narrow_schema_type(schema: &Value, xtml_type: &str) -> Value {
let Some(mut schema) = schema.as_object().cloned() else {
return schema.clone();
};
let json_type = if xtml_type == "number" && explicitly_integer_only(&schema) {
"integer"
} else {
xtml_type
};
schema.insert("type".to_string(), Value::String(json_type.to_string()));
Value::Object(schema)
}
fn explicitly_integer_only(schema: &Map<String, Value>) -> bool {
match schema.get("type") {
Some(Value::String(value)) => value == "integer",
Some(Value::Array(values)) => {
let values = values.iter().filter_map(Value::as_str).collect::<Vec<_>>();
values.contains(&"integer") && !values.contains(&"number")
}
_ => false,
}
}
fn push_schema_type(types: &mut Vec<&'static str>, json_type: &str) {
let xtml_type = match json_type {
"string" => Some("string"),
"integer" | "number" => Some("number"),
"boolean" => Some("boolean"),
"null" => Some("null"),
"object" => Some("object"),
"array" => Some("array"),
_ => None,
};
if let Some(xtml_type) = xtml_type
&& !types.contains(&xtml_type)
{
types.push(xtml_type);
}
}
fn string_argument_content(schema: &Value) -> Format {
let Some(schema) = schema.as_object() else {
return Format::any_text_excluding(&[ARG_CLOSE, CALL_CLOSE]);
};
let values = schema
.get("enum")
.and_then(Value::as_array)
.cloned()
.or_else(|| schema.get("const").cloned().map(|value| vec![value]));
let Some(values) = values else {
return Format::any_text_excluding(&[ARG_CLOSE, CALL_CLOSE]);
};
if values.is_empty()
|| values.len() > 256
|| values
.iter()
.any(|value| value.as_str().is_none_or(|value| value.contains("<|")))
{
return Format::any_text_excluding(&[ARG_CLOSE, CALL_CLOSE]);
}
let values = values.iter().filter_map(Value::as_str).collect::<Vec<_>>();
match values.as_slice() {
[value] => Format::const_string(*value),
_ => Format::or(values.into_iter().map(Format::const_string).collect()),
}
}
fn raw_json_arguments(parameters: &Value, options: StructuralTagOptions) -> Format {
Format::tag(
format!("{JSON_OPEN} type=\"object\"{SEP}"),
@@ -302,29 +180,6 @@ fn raw_json_arguments(parameters: &Value, options: StructuralTagOptions) -> Form
)
}
fn permissive_argument() -> Format {
let key = Format::regex(r#"(?:[^<\"&]|&(?:amp|quot);|<[^|])*"#);
let alternatives = XTML_TYPES
.iter()
.map(|xtml_type| {
Format::sequence(vec![
key.clone(),
Format::const_string(format!("\" type=\"{xtml_type}\"{SEP}")),
if *xtml_type == "string" {
Format::any_text_excluding(&[ARG_CLOSE, CALL_CLOSE])
} else {
Format::json_schema(Value::Bool(true))
},
])
})
.collect();
Format::tag(
format!("{OPEN}argument key=\""),
Format::or(alternatives),
ARG_CLOSE,
)
}
fn json_schema(schema: Value, options: StructuralTagOptions) -> Format {
Format::JsonSchema(
JsonSchemaFormat::new(schema)
@@ -333,23 +188,6 @@ fn json_schema(schema: Value, options: StructuralTagOptions) -> Format {
)
}
fn root_definitions(schema: &Map<String, Value>) -> Map<String, Value> {
["$defs", "definitions"]
.into_iter()
.filter_map(|key| schema.get(key).map(|value| (key.to_string(), value.clone())))
.collect()
}
fn attach_root_definitions(schema: &Value, root_defs: &Map<String, Value>) -> Value {
let Some(mut schema) = schema.as_object().cloned() else {
return schema.clone();
};
for (key, value) in root_defs {
schema.entry(key.clone()).or_insert_with(|| value.clone());
}
Value::Object(schema)
}
fn escape_attr_value(value: &str) -> String {
value.replace('&', "&amp;").replace('"', "&quot;")
}
@@ -407,52 +245,18 @@ mod tests {
/[1-9][0-9]*/
`"<|sep|>`
or
plus
or
sequence
optional
tag `<|open|>argument key="unit" type="string"<|sep|>` .. `<|close|>argument<|sep|>`
or
`celsius`
`fahrenheit`
tag `<|open|>argument key="place" type="object"<|sep|>` json(place & object where place = { city?: string }) `<|close|>argument<|sep|>`
tag `<|open|>argument key="place" type="object"<|sep|>` json({ city?: string } where place = { city?: string }) `<|close|>argument<|sep|>`
tag `<|open|>json type="object"<|sep|>` json({ unit?: "celsius" | "fahrenheit", place: place & object } where place = { city?: string }) `<|close|>json<|sep|>`
optional `<|close|>message<|sep|>`
"#]].assert_eq(&outline(&tag.format));
}
#[test]
fn typed_arguments_require_one_tag_only_for_nonempty_required() {
let required = super::typed_arguments(
&json!({
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"]
}),
StructuralTagOptions::default(),
);
let optional = super::typed_arguments(
&json!({
"type": "object",
"properties": { "query": { "type": "string" } }
}),
StructuralTagOptions::default(),
);
let empty_required = super::typed_arguments(
&json!({
"type": "object",
"properties": { "query": { "type": "string" } },
"required": []
}),
StructuralTagOptions::default(),
);
assert_eq!(serde_json::to_value(required).unwrap()["type"], "plus");
assert_eq!(serde_json::to_value(optional).unwrap()["type"], "star");
assert_eq!(
serde_json::to_value(empty_required).unwrap()["type"],
"star"
);
}
#[test]
fn reasoning_grammar_starts_inside_prefilled_think_channel() {
let tools = vec![tool("ping", json!({ "type": "object", "properties": {} }))];
@@ -522,14 +326,4 @@ mod tests {
assert!(tag.contains(r#"type=\"null\""#));
assert!(tag.contains(r#""json_schema":{"type":"null"}"#), "{tag}");
}
#[test]
fn unsafe_string_enum_falls_back_as_a_whole() {
let format = super::string_argument_content(&json!({
"type": "string",
"enum": ["safe", "<|unsafe"]
}));
assert_eq!(serde_json::to_value(format).unwrap()["type"], "any_text");
}
}