[Rust Frontend] Share SchemaRoot between argument coercion and grammars (#59408)

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-07 08:28:27 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 90f4936d9e
commit bc8dd4ad27
6 changed files with 858 additions and 442 deletions
+1
View File
@@ -5,6 +5,7 @@
pub mod output_grammar;
pub mod reasoning;
pub(crate) mod schema;
pub mod tool;
pub mod unified;
pub(crate) mod utils;
+23 -213
View File
@@ -25,14 +25,11 @@
//! - `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 serde_json::{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;
pub use crate::schema::JsonType;
use crate::schema::{self, OptionSource, SchemaOption, SchemaRoot};
/// The schema accepting any value.
static ANY_SCHEMA: Value = Value::Bool(true);
@@ -77,95 +74,22 @@ impl ParameterKey<'_> {
}
}
/// 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.
/// The option's JSON Schema type.
pub ty: JsonType,
source: OptionSource,
source: OptionSource<'a>,
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::Schema(schema) => {
self.cx.json(Value::Object(schema::narrow(schema, self.ty).into_owned()))
}
OptionSource::Literal(value) => self.cx.json(json!({ "const": value })),
OptionSource::Any => self.cx.json(self.ty.any_schema()),
}
@@ -216,26 +140,18 @@ pub struct ArgumentOptions {
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,
root: SchemaRoot<'a>,
}
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()) {
if let (Some(schema), Some(root)) = (schema.as_object_mut(), self.root.schema().as_object())
{
for key in ["$defs", "definitions"] {
if let Some(definitions) = root.get(key) {
schema.entry(key).or_insert_with(|| definitions.clone());
@@ -250,122 +166,14 @@ impl ArgumentContext<'_> {
})
}
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
fn value_options<'s>(&'s self, schema: &'s Value) -> Vec<ValueOption<'s>> {
let root: SchemaRoot<'s> = self.root;
root.options(schema)
.into_iter()
.map(|ty| ValueOption {
.map(|SchemaOption { ty, source }| ValueOption {
ty,
source: OptionSource::Any,
source,
cx: self,
})
.collect()
@@ -377,12 +185,12 @@ impl ArgumentContext<'_> {
pub fn arguments(schema: &Value, syntax: &dyn ArgumentSyntax, options: &ArgumentOptions) -> Format {
let cx = ArgumentContext {
options,
root: schema,
root: SchemaRoot::new(schema),
};
let parameter =
|key: ParameterKey<'_>, schema: &Value| syntax.parameter(key, &cx.value_options(schema));
let schema = cx.resolve(schema, 0);
let schema = cx.root.resolved();
let (properties, additional) = match schema {
Value::Object(schema) => {
let additional = match schema.get("additionalProperties") {
@@ -492,6 +300,8 @@ pub fn group_by<'o, 'a, K: PartialEq>(
#[cfg(test)]
mod tests {
use serde_json::Map;
use super::*;
use crate::output_grammar::test_utils::outline;
use expect_test::{Expect, expect};
@@ -617,7 +427,7 @@ mod tests {
or
`celsius`
`fahrenheit`
tag `<arg key="days" type="number">` json(integer(minimum=1)) any_order `</arg>`
tag `<arg key="days" type="integer">` json(integer(minimum=1)) any_order `</arg>`
"#]],
);
}
@@ -639,13 +449,13 @@ mod tests {
sequence
optional
or
tag `<arg key="id" type="number">` json(integer) `</arg>`
tag `<arg key="id" type="integer">` 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>`
tag `<arg key="mode" type="integer">` json(1) `</arg>`
or
tag `<arg key="q" type="string">` /[a-z]+/ `</arg>`
tag `<arg key="q" type="array">` json(string[]) `</arg>`
+499
View File
@@ -0,0 +1,499 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright contributors to the vLLM project
//! Views of tool parameter JSON schemas.
//!
//! Tool parsers coerce generated parameter values by their schema, and output
//! grammars constrain the same values by it. Both read a parameter's schema
//! through [`SchemaRoot`], so they agree on which JSON types the value may take.
use std::borrow::Cow;
use std::collections::HashSet;
use serde_json::{Map, Value, json};
/// 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);
/// A tool's parameters schema, which local `$ref`s resolve against.
#[derive(Debug, Clone, Copy)]
pub(crate) struct SchemaRoot<'a> {
schema: &'a Value,
}
/// 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,
}
/// Roots are equal when they are the same schema, which a pointer compare
/// decides without walking it.
impl PartialEq for SchemaRoot<'_> {
fn eq(&self, other: &Self) -> bool {
std::ptr::eq(self.schema, other.schema)
}
}
impl Eq for SchemaRoot<'_> {}
/// One option of a value: a single JSON type under a narrowed schema, a
/// constant, or any value of the type.
#[derive(Debug, Clone)]
pub(crate) struct SchemaOption<'a> {
pub(crate) ty: JsonType,
pub(crate) source: OptionSource<'a>,
}
/// Where a [`SchemaOption`] comes from.
#[derive(Debug, Clone)]
pub(crate) enum OptionSource<'a> {
/// A schema, of which the option takes the values of its type; [`narrow`]
/// sets that type on it.
Schema(&'a Map<String, Value>),
/// A `const` or `enum` value.
Literal(&'a Value),
/// Any value of the option's type.
Any,
}
/// JSON Schema type of a value option.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum JsonType {
String,
Integer,
Number,
Boolean,
Null,
Object,
Array,
}
impl<'a> SchemaRoot<'a> {
pub(crate) fn new(schema: &'a Value) -> Self {
Self { schema }
}
/// The parameters schema itself.
pub(crate) fn schema(&self) -> &'a Value {
self.schema
}
/// The parameters schema after following `$ref`s and single-schema
/// `allOf`s.
pub(crate) fn resolved(&self) -> &'a Value {
self.resolve(self.schema)
}
/// Follow `$ref`s and single-schema `allOf`s. A reference that does not
/// resolve, or a chain deeper than [`MAX_SCHEMA_DEPTH`], accepts any value.
fn resolve(&self, schema: &'a Value) -> &'a Value {
let mut schema = schema;
for _ in 0..=MAX_SCHEMA_DEPTH {
if let Some(reference) = schema.get("$ref").and_then(Value::as_str) {
match self.resolve_ref(reference) {
Some(target) => schema = target,
None => return &ANY_SCHEMA,
}
continue;
}
match schema.get("allOf").and_then(Value::as_array).map(Vec::as_slice) {
Some([inner]) => schema = inner,
_ => return schema,
}
}
&ANY_SCHEMA
}
/// Every option of a value under `schema`.
///
/// `const` and `enum` values become literal options, and `anyOf`, `oneOf`,
/// and type arrays one option per alternative, in schema order. An object
/// or array schema without `type` is typed by its `properties`,
/// `additionalProperties`, or `items`. `"nullable": true`, the OpenAPI
/// spelling of an optional value, adds a `null` option. Type names accept
/// the aliases that real tool schemas use, such as `int` or `dict`.
///
/// 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 that constrains nothing, or whose references
/// only lead back into it, yields [`Self::any`].
pub(crate) fn options(&self, schema: &'a Value) -> Vec<SchemaOption<'a>> {
let mut expansion = Expansion::default();
let mut options = self.options_at(schema, 0, &mut expansion);
if options.is_empty() && expansion.skipped {
options = Self::any();
}
let nullable = schema.get("nullable").and_then(Value::as_bool) == Some(true);
if nullable && !options.iter().any(|option| option.ty == JsonType::Null) {
options.push(SchemaOption {
ty: JsonType::Null,
source: OptionSource::Any,
});
}
options
}
/// One option per JSON value type, each accepting any value of the type.
pub(crate) fn any() -> Vec<SchemaOption<'a>> {
JsonType::VALUE_TYPES
.into_iter()
.map(|ty| SchemaOption {
ty,
source: OptionSource::Any,
})
.collect()
}
fn resolve_ref(&self, reference: &str) -> Option<&'a Value> {
self.schema.pointer(reference.strip_prefix('#')?)
}
fn options_at(
&self,
schema: &'a Value,
depth: usize,
expansion: &mut Expansion,
) -> Vec<SchemaOption<'a>> {
let schema = match schema {
_ if depth > MAX_SCHEMA_DEPTH => return Self::any(),
Value::Bool(false) => return vec![],
Value::Object(schema) => schema,
_ => return Self::any(),
};
if let Some(reference) = schema.get("$ref").and_then(Value::as_str) {
let Some(target) = self.resolve_ref(reference) else {
return Self::any();
};
if !expansion.expanded.insert(std::ptr::from_ref(target)) {
expansion.skipped = true;
return vec![];
}
return self.options_at(target, depth + 1, expansion);
}
if let Some(value) = schema.get("const") {
return vec![SchemaOption::literal(value)];
}
if let Some(values) = schema.get("enum").and_then(Value::as_array) {
return values.iter().map(SchemaOption::literal).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.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.options_at(schema, depth + 1, expansion),
_ => Self::any(),
};
}
match schema.get("type") {
Some(Value::String(name)) => JsonType::parse(name)
.map(|ty| SchemaOption::typed(schema, ty))
.into_iter()
.collect(),
Some(Value::Array(names)) => names
.iter()
.filter_map(Value::as_str)
.filter_map(JsonType::parse)
.map(|ty| SchemaOption::typed(schema, ty))
.collect(),
Some(_) => Self::any(),
None if schema.contains_key("properties")
|| schema.contains_key("additionalProperties") =>
{
vec![SchemaOption::typed(schema, JsonType::Object)]
}
None if schema.contains_key("items") => {
vec![SchemaOption::typed(schema, JsonType::Array)]
}
None => Self::any(),
}
}
}
impl<'a> SchemaOption<'a> {
/// The schema of a [`OptionSource::Schema`] option.
pub(crate) fn schema(&self) -> Option<&'a Map<String, Value>> {
match self.source {
OptionSource::Schema(schema) => Some(schema),
OptionSource::Literal(_) | OptionSource::Any => None,
}
}
/// The option of `schema` that takes its values of type `ty`.
fn typed(schema: &'a Map<String, Value>, ty: JsonType) -> Self {
Self {
ty,
source: OptionSource::Schema(schema),
}
}
fn literal(value: &'a Value) -> Self {
Self {
ty: JsonType::of_value(value),
source: OptionSource::Literal(value),
}
}
}
/// `schema` with its `type` set to the canonical name of `ty`, copied only
/// when that changes it.
pub(crate) fn narrow(schema: &Map<String, Value>, ty: JsonType) -> Cow<'_, Map<String, Value>> {
if schema.get("type").and_then(Value::as_str) == Some(ty.name()) {
Cow::Borrowed(schema)
} else {
let mut schema = schema.clone();
schema.insert("type".to_string(), Value::String(ty.name().to_string()));
Cow::Owned(schema)
}
}
impl JsonType {
/// The types of JSON values, which do not distinguish integers.
const VALUE_TYPES: [Self; 6] = [
Self::String,
Self::Number,
Self::Boolean,
Self::Null,
Self::Object,
Self::Array,
];
/// The JSON Schema type name.
pub fn name(self) -> &'static str {
match self {
Self::String => "string",
Self::Integer => "integer",
Self::Number => "number",
Self::Boolean => "boolean",
Self::Null => "null",
Self::Object => "object",
Self::Array => "array",
}
}
/// Schema accepting every JSON value of this type.
pub(crate) fn any_schema(self) -> Value {
match self {
Self::Object => json!({ "type": "object", "additionalProperties": true }),
Self::Array => json!({ "type": "array", "items": true }),
ty => json!({ "type": ty.name() }),
}
}
/// Parse a schema type name, including aliases used by real tool schemas.
fn parse(name: &str) -> Option<Self> {
let name = name.trim().to_ascii_lowercase();
Some(match name.as_str() {
"string" | "str" | "text" | "varchar" | "char" | "enum" => Self::String,
"integer" | "int" => Self::Integer,
"number" | "float" | "double" => Self::Number,
"boolean" | "bool" | "binary" => Self::Boolean,
"object" | "dict" | "map" => Self::Object,
"array" | "arr" | "list" | "sequence" => Self::Array,
"null" => Self::Null,
_ if name.starts_with("int")
|| name.starts_with("uint")
|| name.starts_with("long")
|| name.starts_with("short")
|| name.starts_with("unsigned") =>
{
Self::Integer
}
_ if name.starts_with("num") || name.starts_with("float") => Self::Number,
_ if name.starts_with("dict") => Self::Object,
_ if name.starts_with("list") => Self::Array,
_ => return None,
})
}
fn of_value(value: &Value) -> Self {
match value {
Value::String(_) => Self::String,
Value::Number(number) if number.is_f64() => Self::Number,
Value::Number(_) => Self::Integer,
Value::Bool(_) => Self::Boolean,
Value::Null => Self::Null,
Value::Object(_) => Self::Object,
Value::Array(_) => Self::Array,
}
}
}
#[cfg(test)]
mod tests {
use expect_test::{Expect, expect};
use serde_json::json;
use super::*;
/// A Pydantic v2 `model_json_schema()` for a nested model, an enum, and an
/// optional nested model.
fn pydantic_schema() -> Value {
json!({
"$defs": {
"Place": {
"properties": { "city": { "title": "City", "type": "string" } },
"required": ["city"],
"title": "Place",
"type": "object"
},
"Unit": { "enum": ["celsius", "fahrenheit"], "title": "Unit", "type": "string" }
},
"properties": {
"place": { "$ref": "#/$defs/Place" },
"unit": { "$ref": "#/$defs/Unit", "default": "celsius" },
"backup": { "anyOf": [{ "$ref": "#/$defs/Place" }, { "type": "null" }], "default": null }
},
"required": ["place"],
"title": "Args",
"type": "object"
})
}
fn check_options(root: &Value, schema: &Value, expected: Expect) {
let options = SchemaRoot::new(root)
.options(schema)
.into_iter()
.map(|option| match option.source {
OptionSource::Schema(schema) => format!(
"{} {}",
option.ty.name(),
Value::Object(narrow(schema, option.ty).into_owned())
),
OptionSource::Literal(value) => format!("{} = {value}", option.ty.name()),
OptionSource::Any => format!("{} any", option.ty.name()),
})
.collect::<Vec<_>>();
expected.assert_debug_eq(&options);
}
#[test]
fn references_resolve_to_their_definitions() {
let root = pydantic_schema();
let properties = &root["properties"];
check_options(
&root,
&properties["place"],
expect![[r#"
[
"object {\"properties\":{\"city\":{\"title\":\"City\",\"type\":\"string\"}},\"required\":[\"city\"],\"title\":\"Place\",\"type\":\"object\"}",
]
"#]],
);
check_options(
&root,
&properties["unit"],
expect![[r#"
[
"string = \"celsius\"",
"string = \"fahrenheit\"",
]
"#]],
);
check_options(
&root,
&properties["backup"],
expect![[r#"
[
"object {\"properties\":{\"city\":{\"title\":\"City\",\"type\":\"string\"}},\"required\":[\"city\"],\"title\":\"Place\",\"type\":\"object\"}",
"null {\"type\":\"null\"}",
]
"#]],
);
}
#[test]
fn unresolvable_and_cyclic_references_accept_any_value() {
let root = json!({
"$defs": { "a": { "$ref": "#/$defs/b" }, "b": { "$ref": "#/$defs/a" } },
"properties": {
"missing": { "$ref": "#/$defs/missing" },
"cycle": { "$ref": "#/$defs/a" },
"remote": { "$ref": "https://example.com/schema.json" }
}
});
let schema_root = SchemaRoot::new(&root);
for key in ["missing", "cycle", "remote"] {
assert_eq!(
schema_root.resolve(&root["properties"][key]),
&ANY_SCHEMA,
"{key}"
);
assert!(
schema_root
.options(&root["properties"][key])
.iter()
.all(|option| matches!(option.source, OptionSource::Any)),
"{key}"
);
}
}
#[test]
fn options_normalize_common_schema_spellings() {
let root = json!({});
check_options(
&root,
&json!({ "type": ["int", "null"], "minimum": 0 }),
expect![[r#"
[
"integer {\"type\":\"integer\",\"minimum\":0}",
"null {\"type\":\"null\",\"minimum\":0}",
]
"#]],
);
check_options(
&root,
&json!({ "type": "string", "nullable": true }),
expect![[r#"
[
"string {\"type\":\"string\",\"nullable\":true}",
"null any",
]
"#]],
);
check_options(
&root,
&json!({ "enum": ["a", 1, 1.5, null] }),
expect![[r#"
[
"string = \"a\"",
"integer = 1",
"number = 1.5",
"null = null",
]
"#]],
);
check_options(
&root,
&json!({ "allOf": [{ "type": "boolean" }] }),
expect![[r#"
[
"boolean {\"type\":\"boolean\"}",
]
"#]],
);
check_options(
&root,
&json!({ "items": { "type": "string" } }),
expect![[r#"
[
"array {\"items\":{\"type\":\"string\"},\"type\":\"array\"}",
]
"#]],
);
}
}
+283 -224
View File
@@ -5,6 +5,7 @@ use std::collections::BTreeMap;
use serde_json::{Map, Number, Value};
use crate::schema::{JsonType, OptionSource, SchemaRoot};
use crate::tool::Tool;
/// Normalized parameter schemas for all tools in one request.
@@ -21,7 +22,9 @@ pub(crate) struct ToolSchemas {
/// downstream tool call execution.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub(super) struct ToolSchema {
params: BTreeMap<String, JsonParamType>,
/// The tool's parameters schema, read one level at a time as values are
/// converted, so recursive schemas cost only as deep as the value.
parameters: Value,
}
/// Parameter input for schema-aware conversion.
@@ -47,22 +50,38 @@ pub(crate) struct ParamElement {
pub value: ParamInput,
}
/// Normalized JSON parameter type used for raw string coercion.
/// One level of a parameter's normalized type, used for raw string coercion.
///
/// Object and array types normalize their children only when a structured
/// value reaches them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) enum JsonParamType {
enum JsonParamType<'a> {
String,
Integer,
Number,
Boolean,
Object {
properties: BTreeMap<String, JsonParamType>,
additional_properties: Option<Box<JsonParamType>>,
},
Array {
items: Option<Box<JsonParamType>>,
},
Object(ObjectType<'a>),
Array(ArrayType<'a>),
Null,
OneOf(Vec<JsonParamType>),
/// A non-string `const` or `enum` value: text spelling it as JSON decodes
/// to it.
Literal(&'a Value),
OneOf(Vec<JsonParamType<'a>>),
}
/// An object type whose field types are normalized on access.
#[derive(Debug, Clone, PartialEq, Eq)]
struct ObjectType<'a> {
root: SchemaRoot<'a>,
properties: Option<&'a Map<String, Value>>,
additional_properties: Option<&'a Value>,
}
/// An array type whose item type is normalized on access.
#[derive(Debug, Clone, PartialEq, Eq)]
struct ArrayType<'a> {
root: SchemaRoot<'a>,
items: Option<&'a Value>,
}
impl ToolSchemas {
@@ -70,7 +89,12 @@ impl ToolSchemas {
pub(crate) fn from_tools(tools: &[Tool]) -> Self {
let tools = tools
.iter()
.map(|tool| (tool.name.clone(), ToolSchema::from_schema(&tool.parameters)))
.map(|tool| {
(
tool.name.clone(),
ToolSchema::from_schema(tool.parameters.clone()),
)
})
.collect();
Self { tools }
@@ -117,25 +141,14 @@ impl ToolSchema {
/// parameters to be treated as strings.
const fn empty() -> &'static Self {
static EMPTY: ToolSchema = ToolSchema {
params: BTreeMap::new(),
parameters: Value::Null,
};
&EMPTY
}
/// Normalize an OpenAI-style tool parameters JSON schema.
fn from_schema(parameters: &Value) -> Self {
let Some(properties) = parameters.get("properties").and_then(Value::as_object) else {
return Self::default();
};
let params = properties
.iter()
.filter_map(|(name, schema)| {
JsonParamType::from_schema(schema).map(|param_type| (name.clone(), param_type))
})
.collect();
Self { params }
/// Keep an OpenAI-style tool parameters JSON schema.
fn from_schema(parameters: Value) -> Self {
Self { parameters }
}
/// Convert one parameter value using its normalized schema type.
@@ -144,169 +157,86 @@ impl ToolSchema {
/// the value fails to convert, this falls back to returning the raw
/// string as a JSON string value, or object-like JSON for structured input.
fn convert(&self, name: &str, input: ParamInput) -> Value {
convert_with_optional_schema(self.params.get(name), &input)
let root = SchemaRoot::new(&self.parameters);
let param_type = root
.resolved()
.get("properties")
.and_then(|properties| properties.get(name))
.and_then(|schema| JsonParamType::from_schema(&root, schema));
convert_with_optional_schema(param_type.as_ref(), &input)
}
}
impl JsonParamType {
/// Normalize one parameter property schema.
///
/// `"nullable": true` (the OpenAPI spelling of an optional parameter) adds
/// `null` to the accepted types.
fn from_schema(schema: &Value) -> Option<Self> {
let param_type = Self::from_schema_ignoring_nullable(schema)?;
let nullable = schema.get("nullable").and_then(Value::as_bool) == Some(true);
Some(match param_type {
_ if !nullable || param_type.accepts_null() => param_type,
Self::OneOf(mut types) => {
types.push(Self::Null);
Self::OneOf(types)
}
param_type => Self::OneOf(vec![param_type, Self::Null]),
})
}
/// Return whether `null` is one of the accepted types.
fn accepts_null(&self) -> bool {
match self {
Self::Null => true,
Self::OneOf(types) => types.iter().any(Self::accepts_null),
_ => false,
impl<'a> JsonParamType<'a> {
/// Normalize one parameter or nested value schema, or `None` when it does
/// not constrain the value's type.
fn from_schema(root: &SchemaRoot<'a>, schema: &'a Value) -> Option<Self> {
let options = root.options(schema);
if options.iter().all(|option| matches!(option.source, OptionSource::Any)) {
return None;
}
}
/// Normalize one parameter property schema, without `nullable`.
fn from_schema_ignoring_nullable(schema: &Value) -> Option<Self> {
let schema = schema.as_object()?;
if let Some(type_value) = schema.get("type") {
return Self::from_type_value(type_value, schema);
}
if let Some(composite) = schema.get("anyOf").or_else(|| schema.get("oneOf")) {
let param_type = composite
.as_array()
.map(|schemas| schemas.iter().filter_map(Self::from_schema).collect::<Vec<_>>())
.filter(|types| !types.is_empty())
.map(Self::one_of)
.unwrap_or_else(|| Self::object_from_schema(Some(schema)));
return Some(param_type);
}
// Typically, these types are already handled by checking the "type" field, but
// we can also infer them from their characteristic fields if "type" is missing.
if let Some(values) = schema.get("enum").and_then(Value::as_array) {
// Enum values are treated as strings, except that a `null` member
// makes the parameter nullable (mirrors Python's enum type
// inference), so a literal "null" coerces to JSON null.
if values.iter().any(Value::is_null) {
return Some(Self::one_of(vec![Self::String, Self::Null]));
}
return Some(Self::String);
}
if schema.contains_key("items") {
return Some(Self::array_from_schema(Some(schema)));
}
if schema.contains_key("properties") || schema.contains_key("additionalProperties") {
return Some(Self::object_from_schema(Some(schema)));
}
None
}
/// Normalize a JSON schema `type` value.
fn from_type_value(type_value: &Value, schema: &Map<String, Value>) -> Option<Self> {
match type_value {
Value::String(kind) => Self::from_type_name(kind, Some(schema)),
Value::Array(kinds) => {
let types = kinds
.iter()
.filter_map(Value::as_str)
.filter_map(|kind| Self::from_type_name(kind, Some(schema)))
.collect::<Vec<_>>();
if types.is_empty() {
None
} else {
Some(Self::one_of(types))
}
}
_ => None,
}
}
/// Normalize one JSON schema type name.
fn from_type_name(kind: &str, schema: Option<&Map<String, Value>>) -> Option<Self> {
let kind = kind.trim().to_ascii_lowercase();
match kind.as_str() {
"string" | "str" | "text" | "varchar" | "char" | "enum" => Some(Self::String),
"integer" | "int" => Some(Self::Integer),
"number" | "float" | "double" => Some(Self::Number),
"boolean" | "bool" | "binary" => Some(Self::Boolean),
"object" | "dict" | "map" => Some(Self::object_from_schema(schema)),
"array" | "arr" | "list" | "sequence" => Some(Self::array_from_schema(schema)),
"null" => Some(Self::Null),
_ if kind.starts_with("int")
|| kind.starts_with("uint")
|| kind.starts_with("long")
|| kind.starts_with("short")
|| kind.starts_with("unsigned") =>
let mut types = Vec::new();
for option in &options {
// String literals stay with the string type, which keeps text
// verbatim instead of unquoting text that spells one as JSON.
if let OptionSource::Literal(value) = option.source
&& !value.is_string()
&& !types.contains(&Self::Literal(value))
{
Some(Self::Integer)
types.push(Self::Literal(value));
}
_ if kind.starts_with("num") || kind.starts_with("float") => Some(Self::Number),
_ if kind.starts_with("dict") => Some(Self::object_from_schema(schema)),
_ if kind.starts_with("list") => Some(Self::array_from_schema(schema)),
_ => None,
let schema = option.schema();
let param_type = match option.ty {
JsonType::String => Self::String,
JsonType::Integer => Self::Integer,
JsonType::Number => Self::Number,
JsonType::Boolean => Self::Boolean,
JsonType::Null => Self::Null,
JsonType::Object => Self::Object(ObjectType {
root: *root,
properties: schema
.and_then(|schema| schema.get("properties"))
.and_then(Value::as_object),
additional_properties: schema
.and_then(|schema| schema.get("additionalProperties"))
.filter(|schema| schema.is_object()),
}),
JsonType::Array => Self::Array(ArrayType {
root: *root,
items: schema.and_then(|schema| schema.get("items")),
}),
};
if !types.contains(&param_type) {
types.push(param_type);
}
}
// Text spelling a literal decodes to it before any type, a string in
// particular, accepts the same text.
types.sort_by_key(|param_type| !matches!(param_type, Self::Literal(_)));
match types.len() {
0 => None,
1 => types.pop(),
_ => Some(Self::OneOf(types)),
}
}
}
/// Normalize object schema fields.
fn object_from_schema(schema: Option<&Map<String, Value>>) -> Self {
let properties = schema
.and_then(|schema| schema.get("properties"))
.and_then(Value::as_object)
.map(|properties| {
properties
.iter()
.filter_map(|(name, schema)| {
Self::from_schema(schema).map(|param_type| (name.clone(), param_type))
})
.collect()
})
.unwrap_or_default();
let additional_properties =
schema.and_then(|schema| schema.get("additionalProperties")).and_then(|schema| {
if schema.is_object() {
Self::from_schema(schema).map(Box::new)
} else {
None
}
});
Self::Object {
properties,
additional_properties,
}
impl<'a> ObjectType<'a> {
/// The type of the field named `name`, from its declared schema or the
/// additional properties' schema.
fn field(&self, name: &str) -> Option<JsonParamType<'a>> {
let schema = self
.properties
.and_then(|properties| properties.get(name))
.or(self.additional_properties)?;
JsonParamType::from_schema(&self.root, schema)
}
}
/// Normalize array schema fields.
fn array_from_schema(schema: Option<&Map<String, Value>>) -> Self {
let items = schema
.and_then(|schema| schema.get("items"))
.and_then(Self::from_schema)
.map(Box::new);
Self::Array { items }
}
/// Collapse a candidate type list into one normalized type.
fn one_of(mut types: Vec<Self>) -> Self {
if types.len() == 1 {
types.remove(0)
} else {
Self::OneOf(types)
}
impl<'a> ArrayType<'a> {
/// The type of the array's items.
fn items(&self) -> Option<JsonParamType<'a>> {
JsonParamType::from_schema(&self.root, self.items?)
}
}
@@ -318,7 +248,10 @@ fn is_null_literal(value: &str) -> bool {
}
/// Convert one parameter input to a normalized JSON value.
fn convert_with_optional_schema(param_type: Option<&JsonParamType>, input: &ParamInput) -> Value {
fn convert_with_optional_schema(
param_type: Option<&JsonParamType<'_>>,
input: &ParamInput,
) -> Value {
// Coerce the literal text `null` to JSON null, except for `string`-typed
// params, where it must stay the string "null": a model emitting the literal
// text "null" for a string field means the string, not a missing value.
@@ -341,13 +274,13 @@ fn convert_with_optional_schema(param_type: Option<&JsonParamType>, input: &Para
ParamInput::Text(value) => Value::String(value.clone()),
ParamInput::Elements(elements) => {
// Convert structured input to object without a schema.
Value::Object(convert_elements_to_object(elements, &BTreeMap::new(), None))
Value::Object(convert_elements_to_object(elements, None))
}
}
}
/// Convert one parameter input to a normalized JSON type.
fn try_convert_value(param_type: &JsonParamType, input: &ParamInput) -> Option<Value> {
fn try_convert_value(param_type: &JsonParamType<'_>, input: &ParamInput) -> Option<Value> {
match input {
ParamInput::Text(value) => try_convert_text_value(param_type, value),
ParamInput::Elements(elements) => try_convert_elements_value(param_type, elements),
@@ -358,18 +291,21 @@ fn try_convert_value(param_type: &JsonParamType, input: &ParamInput) -> Option<V
///
/// Only `string` keeps the value verbatim; the other types ignore surrounding
/// whitespace.
fn try_convert_text_value(param_type: &JsonParamType, value: &str) -> Option<Value> {
fn try_convert_text_value(param_type: &JsonParamType<'_>, value: &str) -> Option<Value> {
match param_type {
JsonParamType::String => Some(Value::String(value.to_string())),
JsonParamType::Integer => convert_integer_text(value),
JsonParamType::Number => convert_number_text(value),
JsonParamType::Boolean => try_convert_boolean(value),
JsonParamType::Object { .. } if value.trim().is_empty() => Some(Value::Object(Map::new())),
JsonParamType::Array { .. } if value.trim().is_empty() => Some(Value::Array(Vec::new())),
JsonParamType::Object(_) if value.trim().is_empty() => Some(Value::Object(Map::new())),
JsonParamType::Array(_) if value.trim().is_empty() => Some(Value::Array(Vec::new())),
// For composite types with string input, interpret the string as JSON of that type.
JsonParamType::Object { .. } => serde_json::from_str(value).ok().filter(Value::is_object),
JsonParamType::Array { .. } => serde_json::from_str(value).ok().filter(Value::is_array),
JsonParamType::Object(_) => serde_json::from_str(value).ok().filter(Value::is_object),
JsonParamType::Array(_) => serde_json::from_str(value).ok().filter(Value::is_array),
JsonParamType::Null => is_null_literal(value).then_some(Value::Null),
JsonParamType::Literal(literal) => serde_json::from_str::<Value>(value.trim())
.ok()
.filter(|value| value == *literal),
JsonParamType::OneOf(types) => {
types.iter().find_map(|param_type| try_convert_text_value(param_type, value))
}
@@ -378,25 +314,24 @@ fn try_convert_text_value(param_type: &JsonParamType, value: &str) -> Option<Val
/// Convert one structured parameter input to a normalized JSON type.
fn try_convert_elements_value(
param_type: &JsonParamType,
param_type: &JsonParamType<'_>,
elements: &[ParamElement],
) -> Option<Value> {
match param_type {
JsonParamType::Object {
properties,
additional_properties,
} => Some(Value::Object(convert_elements_to_object(
JsonParamType::Object(object) => Some(Value::Object(convert_elements_to_object(
elements,
properties,
additional_properties.as_deref(),
Some(object),
))),
JsonParamType::Array { items } => Some(Value::Array(
// Collect all child elements into an array, regardless of their names.
elements
.iter()
.map(|element| convert_with_optional_schema(items.as_deref(), &element.value))
.collect(),
)),
JsonParamType::Array(array) => {
let items = array.items();
Some(Value::Array(
// Collect all child elements into an array, regardless of their names.
elements
.iter()
.map(|element| convert_with_optional_schema(items.as_ref(), &element.value))
.collect(),
))
}
JsonParamType::OneOf(types) => types
.iter()
.find_map(|param_type| try_convert_elements_value(param_type, elements)),
@@ -406,20 +341,20 @@ fn try_convert_elements_value(
| JsonParamType::Integer
| JsonParamType::Number
| JsonParamType::Boolean
| JsonParamType::Null => None,
| JsonParamType::Null
| JsonParamType::Literal(_) => None,
}
}
/// Convert structured elements to an object, using field schemas when present.
fn convert_elements_to_object(
elements: &[ParamElement],
properties: &BTreeMap<String, JsonParamType>,
additional_properties: Option<&JsonParamType>,
object_type: Option<&ObjectType<'_>>,
) -> Map<String, Value> {
let mut object = Map::with_capacity(elements.len());
for element in elements {
let param_type = properties.get(&element.name).or(additional_properties);
let value = convert_with_optional_schema(param_type, &element.value);
let param_type = object_type.and_then(|object_type| object_type.field(&element.name));
let value = convert_with_optional_schema(param_type.as_ref(), &element.value);
insert_object_value(&mut object, element.name.clone(), value);
}
object
@@ -508,7 +443,7 @@ mod tests {
#[test]
fn invalid_schema_converts_everything_as_string() {
let params = ToolSchema::from_schema(&json!({ "type": "object" }));
let params = ToolSchema::from_schema(json!({ "type": "object" }));
assert_eq!(params.convert("count", text("42")), json!("42"));
assert_eq!(params.convert("count", text("null")), json!(null));
@@ -516,7 +451,7 @@ mod tests {
#[test]
fn skips_unknown_property_schema_and_unknown_type() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"unknown_schema": true,
@@ -532,7 +467,7 @@ mod tests {
#[test]
fn converts_supported_types() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"text": { "type": "string" },
@@ -571,7 +506,7 @@ mod tests {
#[test]
fn number_conversion_preserves_json_number_spelling_with_legacy_fallback() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"value": { "type": "number" }
@@ -618,7 +553,7 @@ mod tests {
#[test]
fn non_string_values_ignore_surrounding_whitespace() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"text": { "type": "string" },
@@ -641,7 +576,7 @@ mod tests {
#[test]
fn numbers_accept_digit_separators() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"count": { "type": "integer" },
@@ -658,7 +593,7 @@ mod tests {
#[test]
fn nullable_schemas_accept_null() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"text": { "type": "string", "nullable": true },
@@ -675,7 +610,7 @@ mod tests {
#[test]
fn composite_values_must_decode_to_their_type() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"payload": { "type": "object" },
@@ -695,7 +630,7 @@ mod tests {
#[test]
fn converts_upstream_aliases() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"s": { "type": "varchar" },
@@ -717,13 +652,13 @@ mod tests {
#[test]
fn preserves_union_type_order() {
let integer_first = ToolSchema::from_schema(&json!({
let integer_first = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"value": { "type": ["integer", "string"] }
}
}));
let string_first = ToolSchema::from_schema(&json!({
let string_first = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"value": { "type": ["string", "integer"] }
@@ -736,7 +671,7 @@ mod tests {
#[test]
fn converts_composite_schemas() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"choice": {
@@ -745,7 +680,7 @@ mod tests {
{ "type": "string" }
]
},
"fallback_object": {
"unknown_alternatives": {
"oneOf": [
{ "type": "mystery" }
]
@@ -754,15 +689,139 @@ mod tests {
}));
assert_eq!(params.convert("choice", text("42")), json!(42));
// Alternatives of unknown types leave the value unconstrained, like an
// unknown `type`.
assert_eq!(
params.convert("fallback_object", text(r#"{"x":1}"#)),
json!({ "x": 1 })
params.convert("unknown_alternatives", text(r#"{"x":1}"#)),
json!(r#"{"x":1}"#)
);
}
#[test]
fn resolves_references_in_pydantic_schemas() {
let params = ToolSchema::from_schema(json!({
"$defs": {
"Place": {
"properties": { "city": { "type": "string" }, "days": { "type": "integer" } },
"type": "object"
},
"Count": { "type": "integer" }
},
"type": "object",
"properties": {
"place": { "$ref": "#/$defs/Place" },
"backup": { "anyOf": [{ "$ref": "#/$defs/Place" }, { "type": "null" }] },
"count": { "$ref": "#/$defs/Count" }
}
}));
assert_eq!(
params.convert("place", text(r#"{"city": "Paris", "days": 3}"#)),
json!({ "city": "Paris", "days": 3 })
);
assert_eq!(
params.convert("backup", text(r#"{"city": "Paris"}"#)),
json!({ "city": "Paris" })
);
assert_eq!(params.convert("backup", text("null")), Value::Null);
assert_eq!(params.convert("count", text("3")), json!(3));
}
#[test]
fn recursive_references_convert_without_unbounded_expansion() {
let params = ToolSchema::from_schema(json!({
"$defs": {
"Node": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"children": { "type": "array", "items": { "$ref": "#/$defs/Node" } }
}
}
},
"type": "object",
"properties": { "tree": { "$ref": "#/$defs/Node" } }
}));
assert_eq!(
params.convert(
"tree",
text(r#"{"id": 1, "children": [{"id": 2, "children": []}]}"#)
),
json!({ "id": 1, "children": [{ "id": 2, "children": [] }] })
);
}
#[test]
fn branching_recursive_references_convert_structured_values_by_level() {
// Two recursive children per node expand to 2^depth types if the schema
// is walked ahead of the value.
let params = ToolSchema::from_schema(json!({
"$defs": {
"Tree": {
"type": "object",
"properties": {
"value": { "type": "integer" },
"left": { "$ref": "#/$defs/Tree" },
"right": { "$ref": "#/$defs/Tree" }
}
}
},
"type": "object",
"properties": { "tree": { "$ref": "#/$defs/Tree" } }
}));
let leaf = |value: &str| ParamInput::Elements(vec![elem("value", text(value))]);
let tree = ParamInput::Elements(vec![
elem("value", text("1")),
elem(
"left",
ParamInput::Elements(vec![elem("value", text("2")), elem("right", leaf("3"))]),
),
elem("right", leaf("4")),
]);
assert_eq!(
params.convert("tree", tree),
json!({
"value": 1,
"left": { "value": 2, "right": { "value": 3 } },
"right": { "value": 4 }
})
);
}
#[test]
fn mixed_enums_decode_text_spelling_a_non_string_literal_to_it() {
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"mode": { "enum": ["fast", 1] },
"flag": { "enum": ["auto", true] }
}
}));
assert_eq!(params.convert("mode", text("1")), json!(1));
assert_eq!(params.convert("mode", text("fast")), json!("fast"));
// Text matching no literal keeps the schema order, which tries the
// string first.
assert_eq!(params.convert("mode", text("2")), json!("2"));
assert_eq!(params.convert("flag", text("true")), json!(true));
assert_eq!(params.convert("flag", text("auto")), json!("auto"));
}
#[test]
fn integer_enums_convert_to_numbers() {
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": { "level": { "enum": [1, 2, 3] } }
}));
assert_eq!(params.convert("level", text("2")), json!(2));
}
#[test]
fn infers_type_from_schema_shape_without_type() {
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"choice": { "enum": ["a", "b"] },
@@ -845,7 +904,7 @@ mod tests {
// A `string`-typed param whose value is the literal text "null"/"NULL"
// must stay a string (the original case is preserved), rather than being
// coerced to JSON null. Non-string types keep coercing "null" to null.
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"name": { "type": "string" },
@@ -868,7 +927,7 @@ mod tests {
// must coerce to JSON null (matching Python's `extract_types_from_schema`,
// which infers `null` from the enum values), while a non-null enum keeps
// "null" as a string.
let params = ToolSchema::from_schema(&json!({
let params = ToolSchema::from_schema(json!({
"type": "object",
"properties": {
"mode": { "enum": [null, "auto"] },
+34 -1
View File
@@ -306,7 +306,7 @@ mod tests {
use serde_json::{Value, json};
use thiserror_ext::AsReport;
use super::{Qwen3CoderToolParser, ToolParser};
use super::{Qwen3CoderToolParser, Tool, ToolParser};
use crate::tool::test_utils::{collect_stream, split_by_chars, test_tools};
use crate::tool::tests::assert_tool_framing_preserves_body_whitespace;
use crate::tool::{ToolParserOutput, ToolParserTestExt as _};
@@ -545,6 +545,39 @@ mod tests {
);
}
#[test]
fn qwen_coder_parse_complete_resolves_schema_references() {
let tools = [Tool {
name: "plan_trip".to_string(),
description: None,
parameters: json!({
"$defs": {
"Place": { "type": "object", "properties": { "city": { "type": "string" } } },
"Days": { "type": "integer" }
},
"type": "object",
"properties": {
"place": { "$ref": "#/$defs/Place" },
"days": { "$ref": "#/$defs/Days" }
}
}),
strict: None,
defer_loading: None,
}];
let mut parser = Qwen3CoderToolParser::new(&tools);
let output = parser
.parse_complete(&build_tool_call(
"plan_trip",
&[("place", "\n{\"city\": \"Paris\"}\n"), ("days", "\n3\n")],
))
.unwrap();
assert_eq!(
serde_json::from_str::<Value>(&output.calls()[0].arguments).unwrap(),
json!({ "place": { "city": "Paris" }, "days": 3 })
);
}
#[test]
fn qwen_coder_streaming_extracts_single_tool_call() {
let mut parser = Qwen3CoderToolParser::new(&test_tools());
@@ -46,12 +46,12 @@ impl ArgumentSyntax for XtmlArguments {
}
ParameterKey::Free => ParameterKey::Free,
};
let arguments = group_by(options, |option| option.ty)
let arguments = group_by(options, |option| xtml_type(option.ty))
.into_iter()
.filter_map(|(ty, options)| {
.filter_map(|(type_name, options)| {
let values = options
.into_iter()
.filter_map(|option| match ty {
.filter_map(|option| match option.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]),
@@ -59,7 +59,7 @@ impl ArgumentSyntax for XtmlArguments {
})
.collect::<Vec<_>>();
(!values.is_empty()).then(|| {
let suffix = format!("\" type=\"{}\"{SEP}", ty.name());
let suffix = format!("\" type=\"{type_name}\"{SEP}");
key.tag(
&format!("{ARG_OPEN} key=\""),
&suffix,
@@ -73,6 +73,20 @@ impl ArgumentSyntax for XtmlArguments {
}
}
/// The `type` attribute K3 renders for a value of type `ty`, as
/// `_xtml_type` in the checkpoint's `encoding_k3.py`: integers and floats are
/// both `number`.
fn xtml_type(ty: JsonType) -> &'static str {
match ty {
JsonType::String => "string",
JsonType::Integer | JsonType::Number => "number",
JsonType::Boolean => "boolean",
JsonType::Null => "null",
JsonType::Object => "object",
JsonType::Array => "array",
}
}
/// Kimi K3 XTML structural-tag builder.
#[derive(Debug, Clone, Copy, Default)]
pub struct KimiK3StructuralTagBuilder;