agentbyte 0.25.0__tar.gz → 0.26.0__tar.gz

{agentbyte-0.25.0 → agentbyte-0.26.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to Agentbyte are documented in this file.
 
 The format follows Keep a Changelog principles and semantic versioning.
 
+## [0.26.0] - 2026-09-04
+
+### Added
+
+- `FunctionTool` now supports structured parameters backed by Pydantic models, including nested models, optional collections, typed dictionaries, tuples, unions, field constraints, and `Annotated` parameter descriptions.
+
+### Changed
+
+- Function-tool schema generation and execution now share one strict Pydantic validation model. Validated object arguments reach Pydantic-annotated functions as model instances, dictionary annotations remain dictionaries, and JSON arrays are converted to declared tuple types.
+- Function tools now reject unexpected arguments and unsupported annotations at the boundary instead of silently accepting or flattening them.
+
+### Fixed
+
+- Fixed optional and model-shaped tool parameters being incorrectly advertised as strings, which caused valid object-shaped LLM tool calls to fail with `Invalid parameters provided` before tool execution.
+- Parameter schemas now use author-provided `Field` or string `Annotated` descriptions instead of leaking Python builtin and typing documentation.
+
 ## [0.25.0] - 2026-09-01
 
 ### Added

{agentbyte-0.25.0 → agentbyte-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.25.0
+Version: 0.26.0
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -86,7 +86,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.25.0**
+Current release: **0.26.0**
 
 ## Building an Agent
 

{agentbyte-0.25.0 → agentbyte-0.26.0}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.25.0**
+Current release: **0.26.0**
 
 ## Building an Agent
 

agentbyte-0.26.0/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.26.0"
+VERSION = __version__

{agentbyte-0.25.0 → agentbyte-0.26.0}/src/agentbyte/tools/base.py

@@ -10,10 +10,24 @@ Includes:
 - FunctionTool: Tool that wraps Python functions
 """
 import inspect
+import json
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
 from enum import Enum
-from typing import Any, Callable, Dict, List, Optional, Union, get_type_hints
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    Dict,
+    Optional,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, create_model
+from pydantic.fields import FieldInfo
 
 from ..types import ToolResult
 
@@ -365,10 +379,17 @@ class FunctionTool(BaseTool):
 
         super().__init__(tool_name, tool_description, version, approval_mode)
 
-        # Extract function metadata for schema generation
+        # Extract function metadata for schema generation and validation.
         self.signature = inspect.signature(func)
-        self.type_hints = get_type_hints(func)
-        self._parameters_schema = self._build_parameters_schema()
+        try:
+            self.type_hints = get_type_hints(func, include_extras=True)
+            self._parameters_model = self._build_parameters_model()
+            self._parameters_schema = self._parameters_model.model_json_schema()
+        except Exception as exc:
+            raise TypeError(
+                f"Unable to generate a parameter schema for tool {tool_name!r}: {exc}"
+            ) from exc
+        self._parameters_schema.pop("title", None)
 
     @property
     def parameters(self) -> Dict[str, Any]:
@@ -405,20 +426,34 @@ class FunctionTool(BaseTool):
             ToolResult with function execution outcome
         """
         try:
-            # Validate parameters before execution
-            if not self.validate_parameters(parameters):
-                return ToolResult(
-                    success=False,
-                    result=None,
-                    error="Invalid parameters provided",
-                    metadata={"tool_name": self.name},
-                )
+            validated_parameters = self._validate_and_convert_parameters(parameters)
+        except ValidationError as exc:
+            return ToolResult(
+                success=False,
+                result=None,
+                error=self._format_validation_error(exc),
+                metadata={
+                    "tool_name": self.name,
+                    "exception_type": type(exc).__name__,
+                },
+            )
+        except (TypeError, ValueError) as exc:
+            return ToolResult(
+                success=False,
+                result=None,
+                error=f"Invalid parameters provided: {exc}",
+                metadata={
+                    "tool_name": self.name,
+                    "exception_type": type(exc).__name__,
+                },
+            )
 
+        try:
             # Execute function (handle both sync and async)
             if inspect.iscoroutinefunction(self.func):
-                result = await self.func(**parameters)
+                result = await self.func(**validated_parameters)
             else:
-                result = self.func(**parameters)
+                result = self.func(**validated_parameters)
 
             return ToolResult(
                 success=True,
@@ -438,145 +473,83 @@ class FunctionTool(BaseTool):
                 },
             )
 
-    def _build_parameters_schema(self) -> Dict[str, Any]:
-        """
-        Build JSON schema from function signature and type hints.
-
-        This is the core schema generation logic that converts Python
-        type hints into JSON Schema format for LLMs. It:
-        1. Iterates through function parameters
-        2. Extracts type hints for each parameter
-        3. Converts Python types to JSON Schema types
-        4. Identifies required vs optional parameters
-        5. Extracts enum values from Literal types
-
-        Returns:
-            JSON schema dictionary
-        """
-        schema = {
-            "type": "object",
-            "properties": {},
-            "required": []
-        }
+    def validate_parameters(self, params: Dict[str, Any]) -> bool:
+        """Return whether parameters satisfy the wrapped function contract."""
+        try:
+            self._validate_and_convert_parameters(params)
+        except (TypeError, ValueError, ValidationError):
+            return False
+        return True
 
+    def _build_parameters_model(self) -> type[BaseModel]:
+        """Build the shared Pydantic schema and validation model."""
+        fields: dict[str, tuple[Any, Any]] = {}
         for param_name, param in self.signature.parameters.items():
-            # Skip 'self' parameter for methods
             if param_name == "self":
                 continue
+            if param.kind in {
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            }:
+                raise TypeError(
+                    f"Tool parameter {param_name!r} uses unsupported kind "
+                    f"{param.kind.description!r}"
+                )
 
-            # Get parameter type from type hints
-            param_type = self.type_hints.get(param_name)
-            json_type = self._python_type_to_json_type(param_type)
-
-            property_schema = {"type": json_type}
-
-            # Add enum constraint for Literal types or Enum classes
-            enum_values = self._extract_enum_values(param_type)
-            if enum_values:
-                property_schema["enum"] = enum_values
-
-            # Add description from docstring if available
-            # (Simplified - full implementation would parse docstrings)
-            if hasattr(param, "annotation") and hasattr(
-                param.annotation, "__doc__"
-            ):
-                property_schema["description"] = param.annotation.__doc__
-
-            schema["properties"][param_name] = property_schema
-
-            # Add to required if no default value
-            if param.default == inspect.Parameter.empty:
-                schema["required"].append(param_name)
-
-        return schema
-
-    def _python_type_to_json_type(self, python_type: Any) -> str:
-        """
-        Convert Python type hints to JSON schema types.
-
-        Type mapping:
-        - str -> "string"
-        - int -> "integer"
-        - float -> "number"
-        - bool -> "boolean"
-        - list/List -> "array"
-        - dict/Dict -> "object"
-        - None/Optional -> "null"
-        - Unknown/Union -> "string" (fallback)
-
-        Args:
-            python_type: Python type annotation
-
-        Returns:
-            JSON schema type string
-        """
-        if python_type is None or python_type is type(None):
-            return "null"
-        elif python_type is str:
-            return "string"
-        elif python_type is int:
-            return "integer"
-        elif python_type is float:
-            return "number"
-        elif python_type is bool:
-            return "boolean"
-        elif python_type is list or (
-            hasattr(python_type, "__origin__") and
-            python_type.__origin__ is list
-        ):
-            return "array"
-        elif python_type is dict or (
-            hasattr(python_type, "__origin__") and
-            python_type.__origin__ is dict
-        ):
-            return "object"
-        else:
-            # For Union types, complex types, etc., default to string
-            return "string"
-
-    def _extract_enum_values(self, param_type: Any) -> Optional[List[Any]]:
-        """
-        Extract enum values from Literal types or Enum classes.
-
-        Supports:
-        - typing.Literal["a", "b", "c"]
-        - enum.Enum classes
+            annotation = self.type_hints.get(param_name, str)
+            annotation = self._with_string_description(annotation)
+            default = ... if param.default is inspect.Parameter.empty else param.default
+            fields[param_name] = (annotation, default)
 
-        Args:
-            param_type: Python type annotation
+        model_name = f"{self.name.title().replace('_', '')}Parameters"
+        return create_model(
+            model_name,
+            __config__=ConfigDict(extra="forbid", strict=True),
+            **fields,
+        )
 
-        Returns:
-            List of enum values or None
-        """
-        # Handle typing.Literal (Python 3.8+)
-        if hasattr(param_type, "__origin__"):
-            origin = getattr(param_type, "__origin__", None)
-
-            # Check for Literal type
-            try:
-                from typing import Literal, get_args, get_origin
-
-                if get_origin(param_type) is Literal:
-                    return list(get_args(param_type))
-            except (ImportError, AttributeError):
-                pass
-
-            # Fallback for older Python or typing_extensions
-            if hasattr(param_type, "__args__"):
-                type_name = str(origin) if origin else str(param_type)
-                if "Literal" in type_name:
-                    return list(param_type.__args__)
-
-        # Handle Enum classes
-        try:
-            from enum import Enum
+    @staticmethod
+    def _with_string_description(annotation: Any) -> Any:
+        """Promote string ``Annotated`` metadata to a field description."""
+        if get_origin(annotation) is not Annotated:
+            return annotation
 
-            if isinstance(param_type, type) and issubclass(param_type, Enum):
-                return [e.value for e in param_type]
-        except (TypeError, AttributeError):
-            pass
+        annotated_type, *metadata = get_args(annotation)
+        has_description = any(
+            isinstance(item, FieldInfo) and item.description for item in metadata
+        )
+        description = next(
+            (item for item in metadata if isinstance(item, str) and item.strip()),
+            None,
+        )
+        if has_description or description is None:
+            return annotation
+        return Annotated[annotated_type, *metadata, Field(description=description)]
+
+    def _validate_and_convert_parameters(
+        self, parameters: Dict[str, Any]
+    ) -> dict[str, Any]:
+        """Validate JSON-compatible parameters and preserve declared types."""
+        encoded_parameters = json.dumps(parameters)
+        validated = self._parameters_model.model_validate_json(
+            encoded_parameters,
+            strict=True,
+        )
+        return {
+            name: getattr(validated, name)
+            for name in self._parameters_model.model_fields
+        }
 
-        return None
+    @staticmethod
+    def _format_validation_error(exc: ValidationError) -> str:
+        """Format Pydantic errors as concise tool-call feedback."""
+        details = []
+        for error in exc.errors(include_url=False, include_context=False):
+            location = ".".join(str(part) for part in error["loc"])
+            prefix = f"{location}: " if location else ""
+            details.append(f"{prefix}{error['msg']}")
+        return "Invalid parameters provided: " + "; ".join(details)
 
 
 __all__ = ["ApprovalMode", "BaseTool", "FunctionTool"]

{agentbyte-0.25.0 → agentbyte-0.26.0}/tests/tools/test_tools.py

@@ -14,9 +14,10 @@ Run with: uv run pytest tests/tools/test_tools.py -v
 """
 import asyncio
 from enum import Enum
-from typing import Literal
+from typing import Annotated, Any, Literal
 
 import pytest
+from pydantic import BaseModel, Field
 
 from agentbyte.tools import ApprovalMode, FunctionTool, tool
 
@@ -33,6 +34,19 @@ class Color(Enum):
     BLUE = "blue"
 
 
+class DocumentScope(BaseModel):
+    """Document included in a search scope."""
+
+    internal_document_id: str
+    project_id: str | None = None
+
+
+class SearchDocumentFilters(BaseModel):
+    """Structured document search filters."""
+
+    documents: list[DocumentScope] = Field(description="Documents to search")
+
+
 def simple_add(a: int, b: int) -> int:
     """Add two numbers."""
     return a + b
@@ -221,9 +235,9 @@ class TestParameterValidation:
         assert tool_instance.validate_parameters({"name": "Alice"}) is True
 
     def test_validate_parameters_extra_params(self):
-        """Test validation with extra parameters (should still pass)."""
+        """Test validation rejects unexpected function parameters."""
         tool_instance = FunctionTool(simple_add)
-        assert tool_instance.validate_parameters({"a": 5, "b": 3, "extra": "ignored"}) is True
+        assert tool_instance.validate_parameters({"a": 5, "b": 3, "extra": "ignored"}) is False
 
 
 # ============================================================================
@@ -406,6 +420,172 @@ class TestTypeConversion:
         schema = tool_func.parameters
         assert schema["properties"]["data"]["type"] == "object"
 
+    def test_optional_typed_collections_have_structural_schemas(self):
+        """Optional containers retain their JSON structure and item types."""
+        @tool
+        def tool_func(
+            filters: dict[str, Any] | None = None,
+            items: list[str] | None = None,
+            identifiers: tuple[str, ...] | None = None,
+        ) -> None:
+            return None
+
+        properties = tool_func.parameters["properties"]
+        assert {item["type"] for item in properties["filters"]["anyOf"]} == {
+            "object",
+            "null",
+        }
+        array_schema = next(
+            item for item in properties["items"]["anyOf"] if item["type"] == "array"
+        )
+        assert array_schema["items"] == {"type": "string"}
+        tuple_schema = next(
+            item
+            for item in properties["identifiers"]["anyOf"]
+            if item["type"] == "array"
+        )
+        assert tuple_schema["items"] == {"type": "string"}
+
+    def test_pydantic_model_schema_preserves_nested_contract(self):
+        """Pydantic parameters publish nested fields and descriptions."""
+        @tool
+        def tool_func(
+            filters: Annotated[
+                SearchDocumentFilters | None,
+                Field(description="Optional search override"),
+            ] = None,
+        ) -> None:
+            return None
+
+        schema = tool_func.parameters
+        filters_schema = schema["properties"]["filters"]
+        assert filters_schema["description"] == "Optional search override"
+        assert any("$ref" in item for item in filters_schema["anyOf"])
+        model_schema = schema["$defs"]["SearchDocumentFilters"]
+        assert model_schema["type"] == "object"
+        assert model_schema["properties"]["documents"]["type"] == "array"
+        assert model_schema["properties"]["documents"]["description"] == (
+            "Documents to search"
+        )
+
+    def test_annotated_string_is_used_as_description(self):
+        """String Annotated metadata becomes the parameter description."""
+        @tool
+        def tool_func(filters: Annotated[dict[str, Any], "Search scope"]) -> None:
+            return None
+
+        assert tool_func.parameters["properties"]["filters"]["description"] == (
+            "Search scope"
+        )
+
+    def test_builtin_annotation_docs_are_not_parameter_descriptions(self):
+        """Schema descriptions never leak Python builtin documentation."""
+        @tool
+        def tool_func(text: str, values: list[str]) -> None:
+            return None
+
+        properties = tool_func.parameters["properties"]
+        assert "description" not in properties["text"]
+        assert "description" not in properties["values"]
+
+    @pytest.mark.asyncio
+    async def test_structured_inputs_are_converted_to_declared_runtime_types(self):
+        """Validated objects and arrays reach the function as declared types."""
+        received: dict[str, Any] = {}
+
+        @tool
+        def tool_func(
+            filters: SearchDocumentFilters,
+            raw_filters: dict[str, Any],
+            identifiers: tuple[str, ...],
+        ) -> str:
+            received.update(
+                filters=filters,
+                raw_filters=raw_filters,
+                identifiers=identifiers,
+            )
+            return "ok"
+
+        result = await tool_func.execute(
+            {
+                "filters": {
+                    "documents": [{"internal_document_id": "Doc1"}],
+                },
+                "raw_filters": {"project_id": "Project1"},
+                "identifiers": ["Doc1"],
+            }
+        )
+
+        assert result.success is True
+        assert isinstance(received["filters"], SearchDocumentFilters)
+        assert isinstance(received["filters"].documents[0], DocumentScope)
+        assert isinstance(received["raw_filters"], dict)
+        assert received["identifiers"] == ("Doc1",)
+
+    @pytest.mark.asyncio
+    async def test_nested_validation_error_identifies_field_path(self):
+        """Invalid nested model input fails before function execution."""
+        executed = False
+
+        @tool
+        def tool_func(filters: SearchDocumentFilters) -> None:
+            nonlocal executed
+            executed = True
+
+        result = await tool_func.execute({"filters": {"documents": [{}]}})
+
+        assert result.success is False
+        assert executed is False
+        assert result.error is not None
+        assert "filters.documents.0.internal_document_id" in result.error
+        assert "Field required" in result.error
+
+    @pytest.mark.asyncio
+    async def test_extra_parameter_error_is_actionable(self):
+        """Unexpected arguments fail before invoking the function."""
+        result = await FunctionTool(simple_add).execute(
+            {"a": 1, "b": 2, "unexpected": True}
+        )
+
+        assert result.success is False
+        assert result.error is not None
+        assert "unexpected" in result.error
+        assert "Extra inputs are not permitted" in result.error
+
+    def test_required_nullable_parameter_remains_required(self):
+        """Nullability does not make a parameter optional without a default."""
+        @tool
+        def tool_func(value: str | None) -> None:
+            return None
+
+        assert tool_func.parameters["required"] == ["value"]
+        assert tool_func.validate_parameters({"value": None}) is True
+        assert tool_func.validate_parameters({}) is False
+
+    def test_unsupported_annotation_fails_during_tool_construction(self):
+        """Arbitrary classes do not silently degrade to string schemas."""
+        class Unsupported:
+            pass
+
+        def tool_func(value: Unsupported) -> None:
+            return None
+
+        with pytest.raises(TypeError, match="Unable to generate a parameter schema"):
+            FunctionTool(tool_func)
+
+    @pytest.mark.asyncio
+    async def test_function_value_error_is_not_reported_as_invalid_parameters(self):
+        """Errors raised by valid tool calls retain their original meaning."""
+        @tool
+        def tool_func(value: int) -> None:
+            raise ValueError(f"Cannot process {value}")
+
+        result = await tool_func.execute({"value": 3})
+
+        assert result.success is False
+        assert result.error == "Cannot process 3"
+        assert result.metadata["exception_type"] == "ValueError"
+
 
 # ============================================================================
 # Tests: Integration

agentbyte-0.25.0/src/agentbyte/__about__.py

@@ -1,2 +0,0 @@
-__version__ = "0.25.0"
-VERSION = __version__