From b2d3a3b9ad7c58e96a825a33112c571610219460 Mon Sep 17 00:00:00 2001 From: Bugen Zhao Date: Thu, 1 Oct 2026 13:43:18 +0800 Subject: [PATCH] [Rust Frontend] Split argument grammars into schema resolution and per-model rendering (#59395) Signed-off-by: Bugen Zhao Co-authored-by: Claude Opus 5.5 --- .../chat/tests/grammar_replay/Kimi-K3.json | 265 +++--- .../src/chat/tests/grammar_replay/Kimi-K3.txt | 24 +- rust/src/parser/src/output_grammar.rs | 1 + .../parser/src/output_grammar/arguments.rs | 845 ++++++++++++++++++ .../src/unified/kimi_k3/structural_tag.rs | 342 ++----- 5 files changed, 1050 insertions(+), 427 deletions(-) create mode 100644 rust/src/parser/src/output_grammar/arguments.rs diff --git a/rust/src/chat/tests/grammar_replay/Kimi-K3.json b/rust/src/chat/tests/grammar_replay/Kimi-K3.json index ffe5061192..7fe53b0ab2 100644 --- a/rust/src/chat/tests/grammar_replay/Kimi-K3.json +++ b/rust/src/chat/tests/grammar_replay/Kimi-K3.json @@ -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", diff --git a/rust/src/chat/tests/grammar_replay/Kimi-K3.txt b/rust/src/chat/tests/grammar_replay/Kimi-K3.txt index 9b2eca8b2a..3aeb612642 100644 --- a/rust/src/chat/tests/grammar_replay/Kimi-K3.txt +++ b/rust/src/chat/tests/grammar_replay/Kimi-K3.txt @@ -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|>` diff --git a/rust/src/parser/src/output_grammar.rs b/rust/src/parser/src/output_grammar.rs index 29f91a4c25..9058b4a58b 100644 --- a/rust/src/parser/src/output_grammar.rs +++ b/rust/src/parser/src/output_grammar.rs @@ -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; diff --git a/rust/src/parser/src/output_grammar/arguments.rs b/rust/src/parser/src/output_grammar/arguments.rs new file mode 100644 index 0000000000..a7d9fb3078 --- /dev/null +++ b/rust/src/parser/src/output_grammar/arguments.rs @@ -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; + + /// 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; +} + +/// 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 { + 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), + /// 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 { + if self.ty != JsonType::String { + return None; + } + let excludes = self + .cx + .options + .excludes + .iter() + .map(String::as_str) + .chain(terminators.iter().copied()) + .collect::>(); + 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, + /// Substrings forbidden in string values, nested JSON strings included. + pub excludes: Vec, +} + +/// 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> { + 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> { + 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, type_name: &str) -> Option> { + 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> { + 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::>()) + .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, + properties: Vec<(Format, bool)>, + additional: Option, +) -> 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::>(); + 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 { + 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: `VALUE` on separate lines, with + /// raw strings. + struct Untyped; + + impl ArgumentSyntax for Untyped { + fn separator(&self) -> Option { + Some(Format::const_string("\n")) + } + + fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option { + let values = options + .iter() + .filter_map(|option| match option.ty { + JsonType::String => option.raw_string(&[""]), + _ => Some(option.json()), + }) + .collect::>(); + (!values.is_empty()) + .then(|| key.tag("", one_of(values), "")) + } + } + + /// K3-like: `VALUE` with adjacent + /// parameters and one header per JSON type. + struct Typed; + + impl ArgumentSyntax for Typed { + fn separator(&self) -> Option { + None + } + + fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option { + 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(&[""]), + _ => Some(option.json()), + }) + .collect::>(); + (!values.is_empty()).then(|| { + let suffix = format!("\" type=\"{}\">", ty.name()); + key.tag("") + }) + }) + .collect::>(); + (!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 `` text excluding [``] `` + `\n` + optional + sequence + tag `` .. `` + or + `celsius` + `fahrenheit` + `\n` + optional + sequence + tag `` json(integer(minimum=1)) `` + `\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 `` text excluding [``] `` + tag `` .. `` + or + `celsius` + `fahrenheit` + tag `` json(integer(minimum=1)) any_order `` + "#]], + ); + } + + #[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 `` json(integer) `` + tag `` text excluding [``] `` + tag `` json(null) `` + optional + or + tag `` `fast` `` + tag `` json(1) `` + or + tag `` /[a-z]+/ `` + tag `` json(string[]) `` + "#]], + ); + } + + #[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 `` json({ city?: string } where place = { city?: string }, name = string) `` + tag `` text excluding [``] `` + "#]].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 `` text excluding [``] `` + `\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 `` .. `` + or + text excluding [``] + 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 + `` + text excluding [``] + `` + sequence + `` + json(number) + `` + sequence + `` + json(boolean) + `` + sequence + `` + json(null) + `` + sequence + `` + json({ ... }) + `` + sequence + `` + json(any[]) + `` + "#]], + ); + 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 `` text excluding [``] `` + `\n` + star + sequence + sequence + `` + json(boolean) + `` + `\n` + "#]], + ); + } + + #[test] + fn raw_literals_exclude_terminators_and_request_exclusions() { + check_with( + json!({ + "type": "object", + "properties": { "tag": { "enum": ["ok", "ab", "cd"] } }, + "required": ["tag"] + }), + &Typed, + &ArgumentOptions { + excludes: vec!["".to_string()], + ..Default::default() + }, + expect![[r#" + tag `` `ok` `` + "#]], + ); + } +} diff --git a/rust/src/parser/src/unified/kimi_k3/structural_tag.rs b/rust/src/parser/src/unified/kimi_k3/structural_tag.rs index a80be7bb1e..8f0f098f06 100644 --- a/rust/src/parser/src/unified/kimi_k3/structural_tag.rs +++ b/rust/src/parser/src/unified/kimi_k3/structural_tag.rs @@ -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 { + None + } + + fn parameter(&self, key: ParameterKey<'_>, options: &[ValueOption<'_>]) -> Option { + 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::>(); + (!values.is_empty()).then(|| { + let suffix = format!("\" type=\"{}\"{SEP}", ty.name()); + key.tag( + &format!("{ARG_OPEN} key=\""), + &suffix, + one_of(values), + ARG_CLOSE, + ) + }) + }) + .collect::>(); + (!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( + ¶meters, + &XtmlArguments, + &ArgumentOptions { + any_order: options.any_order, + max_whitespace_cnt: options.max_whitespace_cnt, + excludes: vec![], + }, + ); let call_body = Format::or(vec![ - typed_arguments(¶meters, options), + typed_arguments, raw_json_arguments(¶meters, 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::>(); - 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, - options: StructuralTagOptions, -) -> Vec { - 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) -> 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::>(); - 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::>(); - 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) -> Map { - ["$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) -> 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('&', "&").replace('"', """) } @@ -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"); - } }