openai-agents-python/tests/test_function_schema.py

1609 lines
57 KiB
Python

from collections.abc import Callable, Mapping
from enum import Enum
from typing import Annotated, Any, Literal
import pytest
from pydantic import AfterValidator, BaseModel, Field, PositiveInt, TypeAdapter, ValidationError
from pydantic.json_schema import PydanticJsonSchemaWarning
from typing_extensions import TypedDict
from agents import Agent, RunConfig, RunContextWrapper, Runner, function_tool
from agents.decorators import tool
from agents.exceptions import ModelBehaviorError, UserError
from agents.function_schema import function_schema, generate_func_documentation
from agents.testing import ScriptedModel, function_call
def no_args_function():
"""This function has no args."""
return "ok"
def test_no_args_function():
func_schema = function_schema(no_args_function)
assert func_schema.params_json_schema.get("title") == "no_args_function_args"
assert func_schema.description == "This function has no args."
assert not func_schema.takes_context
parsed = func_schema.params_pydantic_model()
args, kwargs_dict = func_schema.to_call_args(parsed)
result = no_args_function(*args, **kwargs_dict)
assert result == "ok"
def no_args_function_with_context(ctx: RunContextWrapper[str]):
return "ok"
def test_no_args_function_with_context() -> None:
func_schema = function_schema(no_args_function_with_context)
assert func_schema.takes_context
context = RunContextWrapper(context="test")
parsed = func_schema.params_pydantic_model()
args, kwargs_dict = func_schema.to_call_args(parsed)
result = no_args_function_with_context(context, *args, **kwargs_dict)
assert result == "ok"
def simple_function(a: int, b: int = 5):
"""
Args:
a: The first argument
b: The second argument
Returns:
The sum of a and b
"""
return a + b
def test_simple_function():
"""Test a function that has simple typed parameters and defaults."""
func_schema = function_schema(simple_function)
# Check that the JSON schema is a dictionary with title, type, etc.
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "simple_function_args"
assert (
func_schema.params_json_schema.get("properties", {}).get("a").get("description")
== "The first argument"
)
assert (
func_schema.params_json_schema.get("properties", {}).get("b").get("description")
== "The second argument"
)
assert not func_schema.takes_context
# Valid input
valid_input = {"a": 3}
parsed = func_schema.params_pydantic_model(**valid_input)
args_tuple, kwargs_dict = func_schema.to_call_args(parsed)
result = simple_function(*args_tuple, **kwargs_dict)
assert result == 8 # 3 + 5
# Another valid input
valid_input2 = {"a": 3, "b": 10}
parsed2 = func_schema.params_pydantic_model(**valid_input2)
args_tuple2, kwargs_dict2 = func_schema.to_call_args(parsed2)
result2 = simple_function(*args_tuple2, **kwargs_dict2)
assert result2 == 13 # 3 + 10
# Invalid input: 'a' must be int
with pytest.raises(ValidationError):
func_schema.params_pydantic_model(**{"a": "not an integer"})
def function_with_model_extra_param(query: str, model_extra: str) -> str:
return f"{query}:{model_extra}"
def function_with_model_fields_set_param(query: str, model_fields_set: int) -> str:
return f"{query}:{model_fields_set}"
def test_to_call_args_does_not_shadow_pydantic_model_extra():
"""A parameter named ``model_extra`` must not be replaced by BaseModel.model_extra."""
with pytest.warns(UserWarning, match="model_extra"):
func_schema = function_schema(function_with_model_extra_param, use_docstring_info=False)
parsed = func_schema.params_pydantic_model.model_validate(
{"query": "hello", "model_extra": "gpt-4.1"}
)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = function_with_model_extra_param(*args, **kwargs_dict)
assert result == "hello:gpt-4.1"
def test_to_call_args_does_not_shadow_pydantic_model_fields_set():
"""A parameter named ``model_fields_set`` must not be replaced by BaseModel.model_fields_set."""
with pytest.warns(UserWarning, match="model_fields_set"):
func_schema = function_schema(
function_with_model_fields_set_param, use_docstring_info=False
)
parsed = func_schema.params_pydantic_model.model_validate(
{"query": "hello", "model_fields_set": 42}
)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = function_with_model_fields_set_param(*args, **kwargs_dict)
assert result == "hello:42"
def varargs_function(x: int, *numbers: float, flag: bool = False, **kwargs: Any):
return x, numbers, flag, kwargs
def test_varargs_function():
"""Test a function that uses *args and **kwargs."""
func_schema = function_schema(varargs_function, strict_json_schema=False)
# Check JSON schema structure
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "varargs_function_args"
# Valid input including *args in 'numbers' and **kwargs in 'kwargs'
valid_input = {
"x": 10,
"numbers": [1.1, 2.2, 3.3],
"flag": True,
"kwargs": {"extra1": "hello", "extra2": 42},
}
parsed = func_schema.params_pydantic_model(**valid_input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = varargs_function(*args, **kwargs_dict)
# result should be (10, (1.1, 2.2, 3.3), True, {"extra1": "hello", "extra2": 42})
assert result[0] == 10
assert result[1] == (1.1, 2.2, 3.3)
assert result[2] is True
assert result[3] == {"extra1": "hello", "extra2": 42}
# Missing 'x' should raise error
with pytest.raises(ValidationError):
func_schema.params_pydantic_model(**{"numbers": [1.1, 2.2]})
# 'flag' can be omitted because it has a default
valid_input_no_flag = {"x": 7, "numbers": [9.9], "kwargs": {"some_key": "some_value"}}
parsed2 = func_schema.params_pydantic_model(**valid_input_no_flag)
args2, kwargs_dict2 = func_schema.to_call_args(parsed2)
result2 = varargs_function(*args2, **kwargs_dict2)
# result2 should be (7, (9.9,), False, {'some_key': 'some_value'})
assert result2 == (7, (9.9,), False, {"some_key": "some_value"})
class Foo(TypedDict):
a: int
b: str
class InnerModel(BaseModel):
a: int
b: str
class OuterModel(BaseModel):
inner: InnerModel
foo: Foo
def complex_args_function(model: OuterModel) -> str:
return f"{model.inner.a}, {model.inner.b}, {model.foo['a']}, {model.foo['b']}"
def test_nested_data_function():
func_schema = function_schema(complex_args_function)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "complex_args_function_args"
# Valid input
model = OuterModel(inner=InnerModel(a=1, b="hello"), foo=Foo(a=2, b="world"))
valid_input = {
"model": model.model_dump(),
}
parsed = func_schema.params_pydantic_model(**valid_input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = complex_args_function(*args, **kwargs_dict)
assert result == "1, hello, 2, world"
def complex_args_and_docs_function(model: OuterModel, some_flag: int = 0) -> str:
"""
This function takes a model and a flag, and returns a string.
Args:
model: A model with an inner and foo field
some_flag: An optional flag with a default of 0
Returns:
A string with the values of the model and flag
"""
return f"{model.inner.a}, {model.inner.b}, {model.foo['a']}, {model.foo['b']}, {some_flag or 0}"
def test_complex_args_and_docs_function():
func_schema = function_schema(complex_args_and_docs_function)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "complex_args_and_docs_function_args"
# Check docstring is parsed correctly
properties = func_schema.params_json_schema.get("properties", {})
assert properties.get("model").get("description") == "A model with an inner and foo field"
assert properties.get("some_flag").get("description") == "An optional flag with a default of 0"
# Valid input
model = OuterModel(inner=InnerModel(a=1, b="hello"), foo=Foo(a=2, b="world"))
valid_input = {
"model": model.model_dump(),
}
parsed = func_schema.params_pydantic_model(**valid_input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = complex_args_and_docs_function(*args, **kwargs_dict)
assert result == "1, hello, 2, world, 0"
# Invalid input: 'some_flag' must be int
with pytest.raises(ValidationError):
func_schema.params_pydantic_model(
**{"model": model.model_dump(), "some_flag": "not an int"}
)
# Valid input: 'some_flag' can be omitted because it has a default
valid_input_no_flag = {"model": model.model_dump()}
parsed2 = func_schema.params_pydantic_model(**valid_input_no_flag)
args2, kwargs_dict2 = func_schema.to_call_args(parsed2)
result2 = complex_args_and_docs_function(*args2, **kwargs_dict2)
assert result2 == "1, hello, 2, world, 0"
def function_with_context(ctx: RunContextWrapper[str], a: int, b: int = 5):
return a + b
def test_function_with_context():
func_schema = function_schema(function_with_context)
assert func_schema.takes_context
context = RunContextWrapper(context="test")
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = function_with_context(context, *args, **kwargs_dict)
assert result == 3
class MyClass:
def foo(self, a: int, b: int = 5):
return a + b
def foo_ctx(self, ctx: RunContextWrapper[str], a: int, b: int = 5):
return a + b
@classmethod
def bar(cls, a: int, b: int = 5):
return a + b
@classmethod
def bar_ctx(cls, ctx: RunContextWrapper[str], a: int, b: int = 5):
return a + b
@staticmethod
def baz(a: int, b: int = 5):
return a + b
@staticmethod
def baz_ctx(ctx: RunContextWrapper[str], a: int, b: int = 5):
return a + b
def test_class_based_functions():
context = RunContextWrapper(context="test")
# Instance method
instance = MyClass()
func_schema = function_schema(instance.foo)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "foo_args"
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = instance.foo(*args, **kwargs_dict)
assert result == 3
# Instance method with context
func_schema = function_schema(instance.foo_ctx)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "foo_ctx_args"
assert func_schema.takes_context
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = instance.foo_ctx(context, *args, **kwargs_dict)
assert result == 3
# Class method
func_schema = function_schema(MyClass.bar)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "bar_args"
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = MyClass.bar(*args, **kwargs_dict)
assert result == 3
# Class method with context
func_schema = function_schema(MyClass.bar_ctx)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "bar_ctx_args"
assert func_schema.takes_context
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = MyClass.bar_ctx(context, *args, **kwargs_dict)
assert result == 3
# Static method
func_schema = function_schema(MyClass.baz)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "baz_args"
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = MyClass.baz(*args, **kwargs_dict)
assert result == 3
# Static method with context
func_schema = function_schema(MyClass.baz_ctx)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "baz_ctx_args"
assert func_schema.takes_context
input = {"a": 1, "b": 2}
parsed = func_schema.params_pydantic_model(**input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = MyClass.baz_ctx(context, *args, **kwargs_dict)
assert result == 3
class MyEnum(str, Enum):
FOO = "foo"
BAR = "bar"
BAZ = "baz"
def enum_and_literal_function(a: MyEnum, b: Literal["a", "b", "c"]) -> str:
return f"{a.value} {b}"
def test_enum_and_literal_function():
func_schema = function_schema(enum_and_literal_function)
assert isinstance(func_schema.params_json_schema, dict)
assert func_schema.params_json_schema.get("title") == "enum_and_literal_function_args"
# Check that the enum values are included in the JSON schema
assert func_schema.params_json_schema.get("$defs", {}).get("MyEnum", {}).get("enum") == [
"foo",
"bar",
"baz",
]
# Check that the enum is expressed as a def
assert (
func_schema.params_json_schema.get("properties", {}).get("a", {}).get("$ref")
== "#/$defs/MyEnum"
)
# Check that the literal values are included in the JSON schema
assert func_schema.params_json_schema.get("properties", {}).get("b", {}).get("enum") == [
"a",
"b",
"c",
]
# Valid input
valid_input = {"a": "foo", "b": "a"}
parsed = func_schema.params_pydantic_model(**valid_input)
args, kwargs_dict = func_schema.to_call_args(parsed)
result = enum_and_literal_function(*args, **kwargs_dict)
assert result == "foo a"
# Invalid input: 'a' must be a valid enum value
with pytest.raises(ValidationError):
func_schema.params_pydantic_model(**{"a": "not an enum value", "b": "a"})
# Invalid input: 'b' must be a valid literal value
with pytest.raises(ValidationError):
func_schema.params_pydantic_model(**{"a": "foo", "b": "not a literal value"})
def test_run_context_in_non_first_position_raises_value_error():
# When a parameter (after the first) is annotated as RunContextWrapper,
# function_schema() should raise a UserError.
def func(a: int, context: RunContextWrapper) -> None:
pass
with pytest.raises(UserError):
function_schema(func, use_docstring_info=False)
def test_var_positional_tuple_annotation():
# A variadic tuple annotation applies to each positional argument.
def func(*args: tuple[int, ...]) -> int:
total = 0
for arg in args:
total += sum(arg)
return total
fs = function_schema(func, use_docstring_info=False)
properties = fs.params_json_schema.get("properties", {})
args_schema = properties.get("args", {})
assert args_schema.get("type") == "array"
assert args_schema.get("items", {}).get("type") == "array"
assert args_schema.get("items", {}).get("items", {}).get("type") == "integer"
parsed = fs.params_pydantic_model.model_validate({"args": [[1, 2], [3]]})
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == 6
with pytest.raises(ValidationError):
fs.params_pydantic_model.model_validate({"args": [1, 2, 3]})
def _var_positional_fixed_pair(*args: tuple[int, str]) -> int:
return len(args)
def _var_positional_fixed_single(*args: tuple[int]) -> int:
return len(args)
def _var_positional_empty_tuple(*args: tuple[()]) -> int:
return len(args)
@pytest.mark.parametrize(
"func",
[_var_positional_fixed_pair, _var_positional_fixed_single, _var_positional_empty_tuple],
)
def test_var_positional_fixed_length_tuple_annotation_is_rejected(func: Any):
# A fixed-length tuple cannot describe every positional argument, so reject it at
# construction instead of silently widening each argument to Any. tuple[()] reports no
# args yet is still parameterized, so it belongs in this group.
with pytest.raises(UserError, match=r"use tuple\[T, \.\.\.\] or list\[T\] instead"):
function_schema(func, use_docstring_info=False)
def _var_positional_homogeneous_tuple(*args: tuple[int, ...]) -> int:
return len(args)
def _var_positional_list(*args: list[int]) -> int:
return len(args)
def _var_positional_scalar(*args: int) -> int:
return len(args)
@pytest.mark.parametrize(
"func",
[_var_positional_homogeneous_tuple, _var_positional_list, _var_positional_scalar],
)
def test_var_positional_supported_annotations_still_build(func: Any):
# The alternatives named by the rejection message must keep working.
fs = function_schema(func, use_docstring_info=False)
assert fs.params_json_schema["properties"]["args"]["type"] == "array"
def test_var_keyword_dict_annotation():
# Case 3:
# A ``**kwargs: X`` annotation applies to each keyword *value* (PEP 484), so a
# ``**kwargs: dict[str, int]`` parameter collects into ``dict[str, dict[str, int]]`` --
# mirroring the variadic-positional handling in test_var_positional_tuple_annotation.
def func(**kwargs: dict[str, int]):
return kwargs
fs = function_schema(func, use_docstring_info=False, strict_json_schema=False)
properties = fs.params_json_schema.get("properties", {})
# The name of the field is "kwargs", and it's a JSON object i.e. a dict.
kwargs_schema = properties.get("kwargs", {})
assert kwargs_schema.get("type") == "object"
# Each keyword value is itself a dict[str, int].
value_schema = kwargs_schema.get("additionalProperties", {})
assert value_schema.get("type") == "object"
assert value_schema.get("additionalProperties", {}).get("type") == "integer"
# A correctly-shaped input round-trips back to the original call.
parsed = fs.params_pydantic_model.model_validate({"kwargs": {"a": {"x": 1}, "b": {"y": 2}}})
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == {"a": {"x": 1}, "b": {"y": 2}}
# A flat mapping of ints no longer matches the declared value type.
with pytest.raises(ValidationError):
fs.params_pydantic_model.model_validate({"kwargs": {"a": 1, "b": 2}})
def test_var_keyword_scalar_annotation():
# A ``**kwargs: int`` parameter collects each keyword value as an int: ``dict[str, int]``.
def func(**kwargs: int) -> int:
return sum(kwargs.values())
fs = function_schema(func, use_docstring_info=False, strict_json_schema=False)
kwargs_schema = fs.params_json_schema.get("properties", {}).get("kwargs", {})
assert kwargs_schema.get("type") == "object"
assert kwargs_schema.get("additionalProperties", {}).get("type") == "integer"
parsed = fs.params_pydantic_model.model_validate({"kwargs": {"a": 2, "b": 3}})
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == 5
def _var_positional_field_constraints(*scores: Annotated[int, Field(ge=0, le=10)]) -> int:
return sum(scores)
def _var_keyword_field_constraints(**scores: Annotated[int, Field(ge=0, le=10)]) -> int:
return sum(scores.values())
@pytest.mark.parametrize(
"func, strict, container_type, value_key",
[
(_var_positional_field_constraints, True, "array", "items"),
(_var_keyword_field_constraints, False, "object", "additionalProperties"),
],
)
def test_variadic_field_constraints_in_schema(func, strict, container_type, value_key):
fs = function_schema(func, strict_json_schema=strict)
scores = fs.params_json_schema["properties"]["scores"]
assert scores["type"] == container_type
assert scores[value_key] == {"type": "integer", "minimum": 0, "maximum": 10}
assert "minimum" not in scores
assert "maximum" not in scores
def test_variadic_field_constraints_apply_to_each_string():
def func(*names: Annotated[str, Field(min_length=2)]) -> str:
return ",".join(names)
fs = function_schema(func)
names = fs.params_json_schema["properties"]["names"]
assert names["items"]["minLength"] == 2
assert "minItems" not in names
parsed = fs.params_pydantic_model.model_validate({"names": ["ok"]})
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == "ok"
with pytest.raises(ValidationError):
fs.params_pydantic_model.model_validate({"names": ["ok", "x"]})
def test_variadic_field_constraints_preserve_collection_defaults():
def func(
*scores: Annotated[int, Field(default=5, alias="values", ge=0)],
**extras: Annotated[int, Field(..., alias="options", ge=0)],
) -> int:
return sum(scores) + sum(extras.values())
fs = function_schema(func, strict_json_schema=False)
assert set(fs.params_json_schema["properties"]) == {"scores", "extras"}
assert not fs.params_json_schema.get("required")
for payload in ({}, {"scores": [], "extras": {}}):
parsed = fs.params_pydantic_model.model_validate(payload)
assert parsed.model_dump() == {"scores": [], "extras": {}}
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == 0
def test_variadic_field_constraints_preserve_homogeneous_tuple_values():
def func(*pairs: Annotated[tuple[int, ...], Field(min_length=2)]) -> int:
return sum(sum(pair) for pair in pairs)
fs = function_schema(func)
pairs = fs.params_json_schema["properties"]["pairs"]
assert pairs["items"]["minItems"] == 2
assert pairs["items"]["items"] == {"type": "integer"}
parsed = fs.params_pydantic_model.model_validate({"pairs": [[1, 2]]})
args, kwargs = fs.to_call_args(parsed)
assert args == [(1, 2)]
assert func(*args, **kwargs) == 3
with pytest.raises(ValidationError):
fs.params_pydantic_model.model_validate({"pairs": [[1]]})
def test_variadic_field_constraints_do_not_bypass_fixed_tuple_rejection():
def func(*pairs: Annotated[tuple[int, str], Field(min_length=2)]) -> int:
return len(pairs)
with pytest.raises(UserError, match=r"use tuple\[T, \.\.\.\] or list\[T\] instead"):
function_schema(func)
def test_schema_with_mapping_raises_strict_mode_error():
"""A mapping type is not allowed in strict mode. Same for dicts. Ensure we raise a UserError."""
def func_with_mapping(test_one: Mapping[str, int]) -> str:
return "foo"
with pytest.raises(UserError):
function_schema(func_with_mapping)
def test_name_override_without_docstring() -> None:
"""name_override should be used even when not parsing docstrings."""
def foo(x: int) -> int:
return x
fs = function_schema(foo, use_docstring_info=False, name_override="custom")
assert fs.name == "custom"
assert fs.params_json_schema.get("title") == "custom_args"
def test_function_with_field_required_constraints():
"""Test function with required Field parameter that has constraints."""
def func_with_field_constraints(my_number: int = Field(..., gt=10, le=100)) -> int:
return my_number * 2
fs = function_schema(func_with_field_constraints, use_docstring_info=False)
# Check that the schema includes the constraints
properties = fs.params_json_schema.get("properties", {})
my_number_schema = properties.get("my_number", {})
assert my_number_schema.get("type") == "integer"
assert my_number_schema.get("exclusiveMinimum") == 10 # gt=10
assert my_number_schema.get("maximum") == 100 # le=100
# Valid input should work
valid_input = {"my_number": 50}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_field_constraints(*args, **kwargs_dict)
assert result == 100
# Invalid input: too small (should violate gt=10)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"my_number": 5})
# Invalid input: too large (should violate le=100)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"my_number": 150})
def test_function_with_field_optional_with_default():
"""Test function with optional Field parameter that has default and constraints."""
def func_with_optional_field(
required_param: str,
optional_param: float = Field(default=5.0, ge=0.0),
) -> str:
return f"{required_param}: {optional_param}"
fs = function_schema(func_with_optional_field, use_docstring_info=False)
# Check that the schema includes the constraints and description
properties = fs.params_json_schema.get("properties", {})
optional_schema = properties.get("optional_param", {})
assert optional_schema.get("type") == "number"
assert optional_schema.get("minimum") == 0.0 # ge=0.0
assert optional_schema.get("default") == 5.0
# Valid input with default
valid_input = {"required_param": "test"}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_optional_field(*args, **kwargs_dict)
assert result == "test: 5.0"
# Valid input with explicit value
valid_input2 = {"required_param": "test", "optional_param": 10.5}
parsed2 = fs.params_pydantic_model(**valid_input2)
args2, kwargs_dict2 = fs.to_call_args(parsed2)
result2 = func_with_optional_field(*args2, **kwargs_dict2)
assert result2 == "test: 10.5"
# Invalid input: negative value (should violate ge=0.0)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"required_param": "test", "optional_param": -1.0})
def test_function_uses_annotated_descriptions_without_docstring() -> None:
"""Test that Annotated metadata populates parameter descriptions when docstrings are ignored."""
def add(
a: Annotated[int, "First number to add"],
b: Annotated[int, "Second number to add"],
) -> int:
return a + b
fs = function_schema(add, use_docstring_info=False)
properties = fs.params_json_schema.get("properties", {})
assert properties["a"].get("description") == "First number to add"
assert properties["b"].get("description") == "Second number to add"
def test_function_prefers_docstring_descriptions_over_annotated_metadata() -> None:
"""Test that docstring parameter descriptions take precedence over Annotated metadata."""
def add(
a: Annotated[int, "Annotated description for a"],
b: Annotated[int, "Annotated description for b"],
) -> int:
"""Adds two integers.
Args:
a: Docstring provided description.
"""
return a + b
fs = function_schema(add)
properties = fs.params_json_schema.get("properties", {})
assert properties["a"].get("description") == "Docstring provided description."
assert properties["b"].get("description") == "Annotated description for b"
def test_function_with_field_description_merge():
"""Test that Field descriptions are merged with docstring descriptions."""
def func_with_field_and_docstring(
param_with_field_desc: int = Field(..., description="Field description"),
param_with_both: str = Field(default="hello", description="Field description"),
) -> str:
"""
Function with both field and docstring descriptions.
Args:
param_with_field_desc: Docstring description
param_with_both: Docstring description
"""
return f"{param_with_field_desc}: {param_with_both}"
fs = function_schema(func_with_field_and_docstring, use_docstring_info=True)
# Check that docstring description takes precedence when both exist
properties = fs.params_json_schema.get("properties", {})
param1_schema = properties.get("param_with_field_desc", {})
param2_schema = properties.get("param_with_both", {})
# The docstring description should be used when both are present
assert param1_schema.get("description") == "Docstring description"
assert param2_schema.get("description") == "Docstring description"
def func_with_field_desc_only(
param_with_field_desc: int = Field(..., description="Field description only"),
param_without_desc: str = Field(default="hello"),
) -> str:
return f"{param_with_field_desc}: {param_without_desc}"
def test_function_with_field_description_only():
"""Test that Field descriptions are used when no docstring info."""
fs = function_schema(func_with_field_desc_only)
# Check that field description is used when no docstring
properties = fs.params_json_schema.get("properties", {})
param1_schema = properties.get("param_with_field_desc", {})
param2_schema = properties.get("param_without_desc", {})
assert param1_schema.get("description") == "Field description only"
assert param2_schema.get("description") is None
def test_function_with_field_string_constraints():
"""Test function with Field parameter that has string-specific constraints."""
def func_with_string_field(
name: str = Field(..., min_length=3, max_length=20, pattern=r"^[A-Za-z]+$"),
) -> str:
return f"Hello, {name}!"
fs = function_schema(func_with_string_field, use_docstring_info=False)
# Check that the schema includes string constraints
properties = fs.params_json_schema.get("properties", {})
name_schema = properties.get("name", {})
assert name_schema.get("type") == "string"
assert name_schema.get("minLength") == 3
assert name_schema.get("maxLength") == 20
assert name_schema.get("pattern") == r"^[A-Za-z]+$"
# Valid input
valid_input = {"name": "Alice"}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_string_field(*args, **kwargs_dict)
assert result == "Hello, Alice!"
# Invalid input: too short
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "Al"})
# Invalid input: too long
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "A" * 25})
# Invalid input: doesn't match pattern (contains numbers)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "Alice123"})
def test_function_with_field_multiple_constraints():
"""Test function with multiple Field parameters having different constraint types."""
def func_with_multiple_field_constraints(
score: int = Field(..., ge=0, le=100, description="Score from 0 to 100"),
name: str = Field(default="Unknown", min_length=1, max_length=50),
factor: float = Field(default=1.0, gt=0.0, description="Positive multiplier"),
) -> str:
final_score = score * factor
return f"{name} scored {final_score}"
fs = function_schema(func_with_multiple_field_constraints, use_docstring_info=False)
# Check schema structure
properties = fs.params_json_schema.get("properties", {})
# Check score field
score_schema = properties.get("score", {})
assert score_schema.get("type") == "integer"
assert score_schema.get("minimum") == 0
assert score_schema.get("maximum") == 100
assert score_schema.get("description") == "Score from 0 to 100"
# Check name field
name_schema = properties.get("name", {})
assert name_schema.get("type") == "string"
assert name_schema.get("minLength") == 1
assert name_schema.get("maxLength") == 50
assert name_schema.get("default") == "Unknown"
# Check factor field
factor_schema = properties.get("factor", {})
assert factor_schema.get("type") == "number"
assert factor_schema.get("exclusiveMinimum") == 0.0
assert factor_schema.get("default") == 1.0
assert factor_schema.get("description") == "Positive multiplier"
# Valid input with defaults
valid_input = {"score": 85}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_multiple_field_constraints(*args, **kwargs_dict)
assert result == "Unknown scored 85.0"
# Valid input with all parameters
valid_input2 = {"score": 90, "name": "Alice", "factor": 1.5}
parsed2 = fs.params_pydantic_model(**valid_input2)
args2, kwargs_dict2 = fs.to_call_args(parsed2)
result2 = func_with_multiple_field_constraints(*args2, **kwargs_dict2)
assert result2 == "Alice scored 135.0"
# Test various validation errors
with pytest.raises(ValidationError): # score too high
fs.params_pydantic_model(**{"score": 150})
with pytest.raises(ValidationError): # empty name
fs.params_pydantic_model(**{"score": 50, "name": ""})
with pytest.raises(ValidationError): # zero factor
fs.params_pydantic_model(**{"score": 50, "factor": 0.0})
# --- Annotated + Field: same behavior as Field as default ---
def test_function_with_annotated_field_required_constraints():
"""Test function with required Annotated[int, Field(...)] parameter that has constraints."""
def func_with_annotated_field_constraints(
my_number: Annotated[int, Field(..., gt=10, le=100)],
) -> int:
return my_number * 2
fs = function_schema(func_with_annotated_field_constraints, use_docstring_info=False)
# Check that the schema includes the constraints
properties = fs.params_json_schema.get("properties", {})
my_number_schema = properties.get("my_number", {})
assert my_number_schema.get("type") == "integer"
assert my_number_schema.get("exclusiveMinimum") == 10 # gt=10
assert my_number_schema.get("maximum") == 100 # le=100
# Valid input should work
valid_input = {"my_number": 50}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_annotated_field_constraints(*args, **kwargs_dict)
assert result == 100
# Invalid input: too small (should violate gt=10)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"my_number": 5})
# Invalid input: too large (should violate le=100)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"my_number": 150})
def test_function_with_annotated_field_optional_with_default():
"""Optional Annotated[float, Field(...)] param with default and constraints."""
def func_with_annotated_optional_field(
required_param: str,
optional_param: Annotated[float, Field(default=5.0, ge=0.0)],
) -> str:
return f"{required_param}: {optional_param}"
fs = function_schema(func_with_annotated_optional_field, use_docstring_info=False)
# Check that the schema includes the constraints and description
properties = fs.params_json_schema.get("properties", {})
optional_schema = properties.get("optional_param", {})
assert optional_schema.get("type") == "number"
assert optional_schema.get("minimum") == 0.0 # ge=0.0
assert optional_schema.get("default") == 5.0
# Valid input with default
valid_input = {"required_param": "test"}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_annotated_optional_field(*args, **kwargs_dict)
assert result == "test: 5.0"
# Valid input with explicit value
valid_input2 = {"required_param": "test", "optional_param": 10.5}
parsed2 = fs.params_pydantic_model(**valid_input2)
args2, kwargs_dict2 = fs.to_call_args(parsed2)
result2 = func_with_annotated_optional_field(*args2, **kwargs_dict2)
assert result2 == "test: 10.5"
# Invalid input: negative value (should violate ge=0.0)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"required_param": "test", "optional_param": -1.0})
def test_function_with_annotated_field_string_constraints():
"""Annotated[str, Field(...)] parameter with string constraints (min/max length, pattern)."""
def func_with_annotated_string_field(
name: Annotated[
str,
Field(..., min_length=3, max_length=20, pattern=r"^[A-Za-z]+$"),
],
) -> str:
return f"Hello, {name}!"
fs = function_schema(func_with_annotated_string_field, use_docstring_info=False)
# Check that the schema includes string constraints
properties = fs.params_json_schema.get("properties", {})
name_schema = properties.get("name", {})
assert name_schema.get("type") == "string"
assert name_schema.get("minLength") == 3
assert name_schema.get("maxLength") == 20
assert name_schema.get("pattern") == r"^[A-Za-z]+$"
# Valid input
valid_input = {"name": "Alice"}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_annotated_string_field(*args, **kwargs_dict)
assert result == "Hello, Alice!"
# Invalid input: too short
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "Al"})
# Invalid input: too long
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "A" * 25})
# Invalid input: doesn't match pattern (contains numbers)
with pytest.raises(ValidationError):
fs.params_pydantic_model(**{"name": "Alice123"})
def test_function_with_annotated_field_multiple_constraints():
"""Test function with multiple Annotated params with Field having different constraint types."""
def func_with_annotated_multiple_field_constraints(
score: Annotated[
int,
Field(..., ge=0, le=100, description="Score from 0 to 100"),
],
name: Annotated[str, Field(default="Unknown", min_length=1, max_length=50)],
factor: Annotated[float, Field(default=1.0, gt=0.0, description="Positive multiplier")],
) -> str:
final_score = score * factor
return f"{name} scored {final_score}"
fs = function_schema(func_with_annotated_multiple_field_constraints, use_docstring_info=False)
# Check schema structure
properties = fs.params_json_schema.get("properties", {})
# Check score field
score_schema = properties.get("score", {})
assert score_schema.get("type") == "integer"
assert score_schema.get("minimum") == 0
assert score_schema.get("maximum") == 100
assert score_schema.get("description") == "Score from 0 to 100"
# Check name field
name_schema = properties.get("name", {})
assert name_schema.get("type") == "string"
assert name_schema.get("minLength") == 1
assert name_schema.get("maxLength") == 50
assert name_schema.get("default") == "Unknown"
# Check factor field
factor_schema = properties.get("factor", {})
assert factor_schema.get("type") == "number"
assert factor_schema.get("exclusiveMinimum") == 0.0
assert factor_schema.get("default") == 1.0
assert factor_schema.get("description") == "Positive multiplier"
# Valid input with defaults
valid_input = {"score": 85}
parsed = fs.params_pydantic_model(**valid_input)
args, kwargs_dict = fs.to_call_args(parsed)
result = func_with_annotated_multiple_field_constraints(*args, **kwargs_dict)
assert result == "Unknown scored 85.0"
# Valid input with all parameters
valid_input2 = {"score": 90, "name": "Alice", "factor": 1.5}
parsed2 = fs.params_pydantic_model(**valid_input2)
args2, kwargs_dict2 = fs.to_call_args(parsed2)
result2 = func_with_annotated_multiple_field_constraints(*args2, **kwargs_dict2)
assert result2 == "Alice scored 135.0"
# Test various validation errors
with pytest.raises(ValidationError): # score too high
fs.params_pydantic_model(**{"score": 150})
with pytest.raises(ValidationError): # empty name
fs.params_pydantic_model(**{"score": 50, "name": ""})
with pytest.raises(ValidationError): # zero factor
fs.params_pydantic_model(**{"score": 50, "factor": 0.0})
def missing_blank_line_google_function(city: str, units: str):
"""Get the weather for a city.
Args:
city: The city to get weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
def blank_line_google_function(city: str, units: str):
"""Get the weather for a city.
Args:
city: The city to get weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
def test_google_docstring_missing_blank_line_before_args():
"""A Google docstring whose summary is immediately followed by ``Args:`` (no blank line)
should still yield parameter descriptions and a clean function description."""
fs = function_schema(missing_blank_line_google_function, strict_json_schema=False)
properties = fs.params_json_schema.get("properties", {})
assert properties["city"]["description"] == "The city to get weather for."
assert properties["units"]["description"] == "Temperature units to use."
assert fs.description == "Get the weather for a city."
assert "Args:" not in (fs.description or "")
def test_google_docstring_missing_blank_line_matches_blank_line_form():
"""The missing-blank-line variant must produce the exact same schema as the well-formed
variant that includes the blank line."""
fixed = function_schema(missing_blank_line_google_function, strict_json_schema=False)
control = function_schema(blank_line_google_function, strict_json_schema=False)
assert fixed.description == control.description
assert fixed.params_json_schema["properties"] == control.params_json_schema["properties"]
def test_google_docstring_blank_line_form_is_unchanged():
"""Well-formed docstrings (with the blank line already present) must be parsed
byte-identically before and after the normalization: this guards against the helper
accidentally rewriting docstrings that do not need it."""
doc = generate_func_documentation(blank_line_google_function)
assert doc.description == "Get the weather for a city."
assert doc.param_descriptions == {
"city": "The city to get weather for.",
"units": "Temperature units to use.",
}
def test_google_docstring_missing_blank_line_function_tool():
"""End-to-end: a @function_tool-decorated function with the missing-blank-line docstring
must expose parameter descriptions and a clean tool description."""
@function_tool
def weather(city: str, units: str) -> str:
"""Get the weather for a city.
Args:
city: The city to get weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
properties = weather.params_json_schema.get("properties", {})
assert properties["city"]["description"] == "The city to get weather for."
assert properties["units"]["description"] == "Temperature units to use."
assert "Args:" not in (weather.description or "")
@pytest.mark.parametrize("style", [None, "google"])
def test_google_docstring_without_summary(style):
def weather(city: str, units: str) -> str:
"""
Args:
city: The city to get
weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
weather_tool = tool(weather, docstring_style=style)
properties = weather_tool.params_json_schema["properties"]
assert properties["city"]["description"] == "The city to get\nweather for."
assert properties["units"]["description"] == "Temperature units to use."
assert weather_tool.description == ""
assert function_schema(weather, docstring_style=style).description is None
def section_body_before_args_google_function(city: str, units: str):
"""Get the weather for a city.
Note:
Results are cached.
Args:
city: The city to get weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
def section_body_before_args_blank_line_google_function(city: str, units: str):
"""Get the weather for a city.
Note:
Results are cached.
Args:
city: The city to get weather for.
units: Temperature units to use.
"""
return f"{city} {units}"
def test_google_docstring_missing_blank_line_after_section_body():
"""A Google docstring whose ``Args:`` directly follows another section's indented body
(no blank line) should still yield parameter descriptions. griffe skips the header
whenever no blank line sits above it, regardless of how the preceding line is indented."""
fs = function_schema(section_body_before_args_google_function, strict_json_schema=False)
properties = fs.params_json_schema.get("properties", {})
assert properties["city"]["description"] == "The city to get weather for."
assert properties["units"]["description"] == "Temperature units to use."
assert "Args:" not in (fs.description or "")
def test_google_docstring_after_section_body_matches_blank_line_form():
"""The variant missing the blank line after a preceding section's body must produce the
exact same schema as the well-formed variant that includes it."""
fixed = function_schema(section_body_before_args_google_function, strict_json_schema=False)
control = function_schema(
section_body_before_args_blank_line_google_function, strict_json_schema=False
)
assert fixed.description == control.description
assert fixed.params_json_schema["properties"] == control.params_json_schema["properties"]
def starred_args_google_function(x: int, *numbers: float, **kwargs: str) -> str:
"""Add numbers to a base.
Args:
x: The base value.
*numbers: The numbers to add.
**kwargs: Extra options.
"""
return f"{x} {numbers} {kwargs}"
def starred_args_numpy_function(x: int, *numbers: float, **kwargs: str) -> str:
"""Add numbers to a base.
Parameters
----------
x : int
The base value.
*numbers : float
The numbers to add.
**kwargs : str
Extra options.
"""
return f"{x} {numbers} {kwargs}"
def starred_args_sphinx_function(x: int, *numbers: float, **kwargs: str) -> str:
"""Add numbers to a base.
:param x: The base value.
:param numbers: The numbers to add.
:param kwargs: Extra options.
"""
return f"{x} {numbers} {kwargs}"
@pytest.mark.parametrize(
"func,style",
[
(starred_args_google_function, "google"),
(starred_args_numpy_function, "numpy"),
(starred_args_sphinx_function, "sphinx"),
],
)
def test_variadic_param_descriptions_preserved(func, style):
"""Google and NumPy style docstrings write variadic parameters with their stars
("*numbers:", "**kwargs:"). The parsed descriptions must still attach to the bare
signature names in the JSON schema, matching the sphinx form."""
fs = function_schema(func, docstring_style=style, strict_json_schema=False)
properties = fs.params_json_schema.get("properties", {})
assert properties["x"]["description"] == "The base value."
assert properties["numbers"]["description"] == "The numbers to add."
assert properties["kwargs"]["description"] == "Extra options."
class _ElementwiseEqual:
"""Mimics numpy-array equality: ``==`` returns a container whose truthiness raises."""
# Annotated ``Any`` like numpy's own stubs: elementwise ``__eq__`` does not
# return ``bool``.
def __eq__(self, other: object) -> Any:
return _ElementwiseEqual()
def __ne__(self, other: object) -> Any:
return _ElementwiseEqual()
def __bool__(self) -> bool:
raise ValueError("The truth value of an elementwise comparison is ambiguous.")
def __hash__(self) -> int:
return 0
class _AlwaysEqual:
"""A default value whose ``__eq__`` answers True for anything, including sentinels."""
def __eq__(self, other: object) -> bool:
return True
def __ne__(self, other: object) -> bool:
return False
def __hash__(self) -> int:
return 0
_ELEMENTWISE_DEFAULT = _ElementwiseEqual()
_ALWAYS_EQUAL_DEFAULT = _AlwaysEqual()
def _function_with_elementwise_default(x: int, value: Any = _ELEMENTWISE_DEFAULT) -> int:
return x
def _function_with_always_equal_default(x: int, value: Any = _ALWAYS_EQUAL_DEFAULT) -> int:
return x
@pytest.mark.parametrize(
("func", "default_type"),
[
pytest.param(
_function_with_elementwise_default,
_ElementwiseEqual,
id="elementwise-equality",
),
pytest.param(
_function_with_always_equal_default,
_AlwaysEqual,
id="always-true-equality",
),
],
)
def test_default_equality_is_not_used_for_sentinel_comparison(
func: Callable[..., Any], default_type: type[Any]
) -> None:
"""Defaults with non-boolean or always-true equality remain optional and are preserved."""
with pytest.warns(PydanticJsonSchemaWarning, match="is not JSON serializable"):
fs = function_schema(func, strict_json_schema=False)
assert fs.params_json_schema.get("required", []) == ["x"]
parsed = fs.params_pydantic_model(x=1)
args, kwargs = fs.to_call_args(parsed)
assert isinstance((args + list(kwargs.values()))[-1], default_type)
def _kwargs_keyword_only(*, opt: int = 1, **kw: Any) -> tuple[int, dict[str, Any]]:
return opt, kw
def _kwargs_positional_or_keyword(x: int, *rest: int, **kw: Any) -> tuple[int, tuple[int, ...]]:
return x, rest
def _kwargs_after_var_positional(*rest: int, y: int = 0, **kw: Any) -> tuple[int, int]:
return y, len(rest)
def _kwargs_with_context(ctx: RunContextWrapper[str], n: int, **kw: Any) -> int:
return n
@pytest.mark.parametrize(
("func", "payload", "conflict"),
[
pytest.param(
_kwargs_keyword_only,
{"opt": 5, "kw": {"opt": 9}},
"'opt'",
id="keyword-only",
),
pytest.param(
_kwargs_positional_or_keyword,
{"x": 1, "rest": [2, 3], "kw": {"x": 99}},
"'x'",
id="positional-or-keyword",
),
pytest.param(
_kwargs_after_var_positional,
{"rest": [1], "y": 2, "kw": {"y": 3}},
"'y'",
id="keyword-only-after-var-positional",
),
pytest.param(
_kwargs_with_context,
{"n": 1, "kw": {"ctx": 9}},
"'ctx'",
id="context-parameter",
),
],
)
def test_to_call_args_rejects_kwargs_keys_that_collide_with_named_params(
func: Callable[..., Any], payload: dict[str, Any], conflict: str
) -> None:
"""A **kwargs key naming a keyword-bindable parameter is not a callable combination.
Splatting it would either replace the validated value for that parameter or make the
call fail with "got multiple values for argument", so it is reported to the model.
"""
fs = function_schema(func, strict_json_schema=False)
parsed = fs.params_pydantic_model(**payload)
with pytest.raises(ModelBehaviorError) as exc_info:
fs.to_call_args(parsed)
assert conflict in str(exc_info.value)
assert fs.name in str(exc_info.value)
def _kwargs_positional_only(a: int, /, **kw: Any) -> tuple[int, dict[str, Any]]:
return a, kw
def _kwargs_var_positional_name(*rest: int, **kw: Any) -> tuple[tuple[int, ...], dict[str, Any]]:
return rest, kw
def test_to_call_args_allows_kwargs_key_matching_positional_only_param() -> None:
"""``f(1, a=2)`` is legal for ``def f(a, /, **kw)``: the key belongs to ``**kw``."""
fs = function_schema(_kwargs_positional_only, strict_json_schema=False)
parsed = fs.params_pydantic_model(**{"a": 1, "kw": {"a": 2}})
args, kwargs_dict = fs.to_call_args(parsed)
assert _kwargs_positional_only(*args, **kwargs_dict) == (1, {"a": 2})
def test_to_call_args_allows_kwargs_key_matching_var_positional_param() -> None:
"""``*args`` binds no name, so a key of the same name belongs to ``**kw``."""
fs = function_schema(_kwargs_var_positional_name, strict_json_schema=False)
parsed = fs.params_pydantic_model(**{"rest": [1], "kw": {"rest": 5}})
args, kwargs_dict = fs.to_call_args(parsed)
assert _kwargs_var_positional_name(*args, **kwargs_dict) == ((1,), {"rest": 5})
@pytest.mark.parametrize(
"annotation, invalid_value, bounds",
[
(PositiveInt, -1, {"exclusiveMinimum": 0}),
(Annotated[int, Field(ge=0), Field(le=10)], 20, {"minimum": 0, "maximum": 10}),
],
)
@pytest.mark.parametrize("kind", ["ordinary", "positional", "keyword"])
@pytest.mark.asyncio
async def test_annotated_constraints_reject_arguments_before_tool_execution(
annotation, invalid_value, bounds, kind
):
invocations = []
if kind == "ordinary":
def update_ordinary(ctx: Annotated[RunContextWrapper[None], "Context"], quantity):
invocations.append(quantity)
return str(quantity)
update_inventory = update_ordinary
valid_payload = {"quantity": 5}
invalid_payload = {"quantity": invalid_value}
elif kind == "positional":
def update_positional(*quantity):
invocations.extend(quantity)
return str(quantity[0])
update_inventory = update_positional
valid_payload = {"quantity": [5]}
invalid_payload = {"quantity": [invalid_value]}
else:
def update_keyword(**quantity):
invocations.extend(quantity.values())
return str(quantity["value"])
update_inventory = update_keyword
valid_payload = {"quantity": {"value": 5}}
invalid_payload = {"quantity": {"value": invalid_value}}
update_inventory.__annotations__["quantity"] = annotation
decorated = tool(
update_inventory,
name_override="update_inventory",
strict_mode=kind != "keyword",
failure_error_function=None,
)
value_schema = decorated.params_json_schema["properties"]["quantity"]
if kind != "ordinary":
value_schema = value_schema["items" if kind == "positional" else "additionalProperties"]
assert value_schema["type"] == "integer"
for key, value in bounds.items():
assert value_schema[key] == value
with pytest.raises(ValidationError):
TypeAdapter(annotation).validate_python(invalid_value)
async def run(payload):
agent = Agent(
name="inventory",
tools=[decorated],
model=ScriptedModel([[function_call("update_inventory", payload, call_id="call-1")]]),
tool_use_behavior="stop_on_first_tool",
)
return await Runner.run(
agent, "Update inventory", run_config=RunConfig(tracing_disabled=True)
)
with pytest.raises(ModelBehaviorError, match="Invalid JSON input for tool"):
await run(invalid_payload)
assert invocations == []
result = await run(valid_payload)
assert result.final_output == "5"
assert invocations == [5]
@pytest.mark.parametrize("default", [0, Field(default=0)])
def test_annotated_metadata_preserves_validator_order(default):
def add_one(value: int) -> int:
return value + 1
def double(value: int) -> int:
return value * 2
def func(
value: Annotated[
int, AfterValidator(add_one), Field(ge=0), AfterValidator(double)
] = default,
):
return value
fs = function_schema(func)
parsed = fs.params_pydantic_model.model_validate({"value": 2})
args, kwargs = fs.to_call_args(parsed)
assert func(*args, **kwargs) == 6
def test_annotated_fields_preserve_description_and_default_precedence():
def func(
quantity: Annotated[
int,
Field(default=1, ge=0, description="First field"),
Field(le=10, description="Second field"),
"Annotated description",
] = 5,
):
"""Update inventory.
Args:
quantity: Docstring description.
"""
return quantity
for use_docstring_info, expected_description in (
(True, "Docstring description."),
(False, "Annotated description"),
):
fs = function_schema(func, use_docstring_info=use_docstring_info)
quantity = fs.params_json_schema["properties"]["quantity"]
assert quantity["minimum"] == 0
assert quantity["maximum"] == 10
assert quantity["description"] == expected_description
assert quantity["default"] == 5
assert fs.params_pydantic_model().quantity == 5
def test_annotated_description_overrides_field_default_description():
def func(
quantity: Annotated[int, "Annotated description"] = Field(
default=5, ge=0, description="Default description"
),
):
"""Update inventory.
Args:
quantity: Docstring description.
"""
return quantity
for use_docstring_info, expected_description in (
(True, "Docstring description."),
(False, "Annotated description"),
):
fs = function_schema(func, use_docstring_info=use_docstring_info)
quantity = fs.params_json_schema["properties"]["quantity"]
assert quantity["description"] == expected_description
assert quantity["minimum"] == 0
assert quantity["default"] == 5
assert fs.params_pydantic_model().quantity == 5