[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:
co-authored by
Claude Opus 5.5
parent
90f4936d9e
commit
bc8dd4ad27
@@ -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;
|
||||
|
||||
@@ -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>`
|
||||
|
||||
@@ -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\"}",
|
||||
]
|
||||
"#]],
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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(¶m_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"] },
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user