voxagent 0.1.0__py3-none-any.whl

voxagent/tools/decorator.py

@@ -0,0 +1,175 @@
+"""Tool decorator for auto-generating ToolDefinition from functions.
+
+This module provides the @tool decorator that creates a ToolDefinition
+from a function's signature, type hints, and docstring.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from typing import Any, Callable, TypeVar, Union, get_args, get_origin, get_type_hints
+
+from voxagent.tools.definition import ToolDefinition
+
+R = TypeVar("R")
+
+
+def tool(
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[[Callable[..., R]], ToolDefinition]:
+    """Decorator to create a ToolDefinition from a function.
+
+    Args:
+        name: Tool name (defaults to function name)
+        description: Tool description (defaults to docstring first line)
+
+    Returns:
+        A decorator that converts a function to a ToolDefinition
+
+    Example:
+        @tool()
+        def get_weather(city: str) -> str:
+            '''Get weather for a city.'''
+            return f"Weather in {city}: Sunny"
+
+        # get_weather is now a ToolDefinition
+        assert get_weather.name == "get_weather"
+        assert get_weather.description == "Get weather for a city."
+    """
+
+    def decorator(fn: Callable[..., R]) -> ToolDefinition:
+        # Determine name
+        tool_name = name if name is not None else fn.__name__
+
+        # Validate name
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", tool_name):
+            raise ValueError(f"Invalid tool name: {tool_name}")
+
+        # Determine description from docstring
+        tool_description = description
+        if tool_description is None:
+            if fn.__doc__:
+                # Use first line of docstring
+                tool_description = fn.__doc__.strip().split("\n")[0].strip()
+            else:
+                tool_description = ""
+
+        # Check if async
+        is_async = inspect.iscoroutinefunction(fn)
+
+        # Build parameters schema from type hints
+        parameters = _build_parameters_schema(fn)
+
+        return ToolDefinition(
+            name=tool_name,
+            description=tool_description,
+            parameters=parameters,
+            execute=fn,
+            is_async=is_async,
+        )
+
+    return decorator
+
+
+def _build_parameters_schema(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Build JSON Schema from function type hints."""
+    sig = inspect.signature(fn)
+    hints: dict[str, Any] = {}
+    try:
+        hints = get_type_hints(fn)
+    except Exception:
+        pass
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        # Skip 'context' parameter (ToolContext)
+        if param_name == "context":
+            continue
+
+        # Skip *args and **kwargs
+        if param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+
+        # Get type hint
+        type_hint = hints.get(param_name, Any)
+
+        # Convert type to JSON Schema
+        prop_schema = _type_to_json_schema(type_hint)
+        properties[param_name] = prop_schema
+
+        # Check if required (no default value)
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+        else:
+            # Add default to schema
+            if param.default is not None:
+                properties[param_name]["default"] = param.default
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+
+    if required:
+        schema["required"] = required
+    else:
+        schema["required"] = []
+
+    return schema
+
+
+def _type_to_json_schema(type_hint: Any) -> dict[str, Any]:
+    """Convert a Python type hint to JSON Schema."""
+    # Handle None/NoneType
+    if type_hint is type(None):
+        return {"type": "null"}
+
+    # Handle basic types
+    if type_hint is str:
+        return {"type": "string"}
+    if type_hint is int:
+        return {"type": "integer"}
+    if type_hint is float:
+        return {"type": "number"}
+    if type_hint is bool:
+        return {"type": "boolean"}
+
+    # Handle Optional (Union with None)
+    origin = get_origin(type_hint)
+    args = get_args(type_hint)
+
+    if origin is Union:
+        # Check if it's Optional (Union[X, None])
+        non_none_args = [a for a in args if a is not type(None)]
+        if len(non_none_args) == 1 and type(None) in args:
+            # It's Optional[X]
+            inner_schema = _type_to_json_schema(non_none_args[0])
+            inner_schema["nullable"] = True
+            return inner_schema
+        # General Union - use anyOf
+        return {"anyOf": [_type_to_json_schema(a) for a in args]}
+
+    # Handle list
+    if origin is list:
+        if args:
+            return {"type": "array", "items": _type_to_json_schema(args[0])}
+        return {"type": "array"}
+
+    # Handle dict
+    if origin is dict:
+        return {"type": "object"}
+
+    # Handle Any
+    if type_hint is Any:
+        return {}
+
+    # Default to object for unknown types
+    return {"type": "object"}
+

voxagent/tools/definition.py

@@ -0,0 +1,131 @@
+"""Tool definition classes.
+
+This module provides ToolDefinition and ToolContext for the agent tool system.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Callable
+
+
+class ToolContext:
+    """Context passed to tool functions during execution.
+
+    Provides access to abort signals, dependencies, and other runtime context.
+
+    Attributes:
+        abort_signal: An asyncio.Event that can be used to signal cancellation.
+    """
+
+    def __init__(self, abort_signal: asyncio.Event | None = None) -> None:
+        """Initialize ToolContext.
+
+        Args:
+            abort_signal: Optional event for signaling tool cancellation.
+        """
+        self.abort_signal = abort_signal
+
+
+class ToolDefinition:
+    """Definition of a tool that can be called by an agent.
+
+    Attributes:
+        name: The tool name (alphanumeric and underscores only).
+        description: Human-readable description for the LLM.
+        parameters: JSON Schema for the tool's parameters.
+        execute: The callable that implements the tool.
+        is_async: Whether the execute function is async.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        execute: Callable[..., Any],
+        parameters: dict[str, Any] | None = None,
+        is_async: bool = False,
+    ) -> None:
+        """Initialize ToolDefinition.
+
+        Args:
+            name: Tool name (alphanumeric and underscores only).
+            description: Description for the LLM.
+            execute: The function that implements the tool.
+            parameters: JSON Schema for parameters. Defaults to empty dict.
+            is_async: Whether execute is an async function.
+
+        Raises:
+            ValueError: If name contains invalid characters.
+        """
+        # Validate name
+        import re
+
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
+            raise ValueError(
+                f"Tool name '{name}' is invalid. "
+                "Must contain only alphanumeric characters and underscores, "
+                "and cannot start with a digit."
+            )
+
+        self.name = name
+        self.description = description
+        self.execute = execute
+        self.parameters = parameters if parameters is not None else {}
+        self.is_async = is_async
+
+    async def run(self, params: dict[str, Any], context: ToolContext) -> Any:
+        """Execute the tool with given parameters.
+
+        Args:
+            params: Dictionary of parameter values.
+            context: The ToolContext for this execution.
+
+        Returns:
+            The result from the tool execution.
+        """
+        # Check if execute function accepts 'context' or 'ctx' parameter
+        sig = inspect.signature(self.execute)
+        accepts_context = "context" in sig.parameters
+        accepts_ctx = "ctx" in sig.parameters
+
+        call_params = dict(params)
+        if accepts_context:
+            call_params["context"] = context
+        elif accepts_ctx:
+            call_params["ctx"] = context
+
+        if self.is_async:
+            return await self.execute(**call_params)
+        else:
+            # Run sync function directly
+            return self.execute(**call_params)
+
+    def to_openai_schema(self) -> dict[str, Any]:
+        """Convert to OpenAI function calling format.
+
+        Returns:
+            Dictionary in OpenAI's function calling format.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters if self.parameters else {"type": "object", "properties": {}},
+            },
+        }
+
+    def to_anthropic_schema(self) -> dict[str, Any]:
+        """Convert to Anthropic tool format.
+
+        Returns:
+            Dictionary in Anthropic's tool format.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters if self.parameters else {"type": "object", "properties": {}},
+        }
+

voxagent/tools/executor.py

@@ -0,0 +1,109 @@
+"""Tool executor for voxagent."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from voxagent.providers.base import AbortSignal
+from voxagent.tools.context import AbortError, ToolContext
+from voxagent.tools.definition import ToolDefinition
+from voxagent.types.messages import ToolResult
+
+
+async def execute_tool(
+    name: str,
+    params: dict[str, Any],
+    tools: list[ToolDefinition],
+    abort_signal: AbortSignal,
+    tool_use_id: str,
+    deps: Any = None,
+    session_id: str | None = None,
+    run_id: str | None = None,
+) -> ToolResult:
+    """Execute a tool by name.
+
+    Args:
+        name: Tool name to execute
+        params: Parameters to pass to the tool
+        tools: List of available tools
+        abort_signal: Signal to check for abort
+        tool_use_id: ID for the tool use (from LLM)
+        deps: Optional dependencies to inject
+        session_id: Current session ID
+        run_id: Current run ID
+
+    Returns:
+        ToolResult with content or error
+    """
+    # Find tool
+    tool = next((t for t in tools if t.name == name), None)
+
+    if tool is None:
+        return ToolResult(
+            tool_use_id=tool_use_id,
+            content=f"Unknown tool: {name}",
+            is_error=True,
+        )
+
+    # Check abort before execution
+    if abort_signal.aborted:
+        return ToolResult(
+            tool_use_id=tool_use_id,
+            content="Aborted",
+            is_error=True,
+        )
+
+    # Create context
+    context = ToolContext(
+        abort_signal=abort_signal,
+        deps=deps,
+        session_id=session_id,
+        run_id=run_id,
+    )
+
+    try:
+        # Execute tool
+        result = await tool.run(params, context)
+
+        # Sanitize result
+        content = _sanitize_result(result)
+
+        return ToolResult(
+            tool_use_id=tool_use_id,
+            content=content,
+            is_error=False,
+        )
+
+    except AbortError:
+        return ToolResult(
+            tool_use_id=tool_use_id,
+            content="Aborted",
+            is_error=True,
+        )
+
+    except Exception as e:
+        return ToolResult(
+            tool_use_id=tool_use_id,
+            content=_format_error(e),
+            is_error=True,
+        )
+
+
+def _sanitize_result(result: Any) -> str:
+    """Convert tool result to string."""
+    if result is None:
+        return ""
+    if isinstance(result, str):
+        return result
+    # JSON serialize dicts, lists, etc.
+    try:
+        return json.dumps(result)
+    except (TypeError, ValueError):
+        return str(result)
+
+
+def _format_error(e: Exception) -> str:
+    """Format exception for tool result."""
+    return f"{type(e).__name__}: {e}"
+

voxagent/tools/policy.py

@@ -0,0 +1,89 @@
+"""Tool policy for voxagent."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from voxagent.tools.definition import ToolDefinition
+
+
+class ToolPolicy(BaseModel):
+    """Policy for filtering available tools.
+
+    Attributes:
+        allow_list: List of allowed tool names, or None to allow all.
+        deny_list: List of denied tool names.
+    """
+
+    allow_list: list[str] | None = None  # None = allow all
+    deny_list: list[str] = Field(default_factory=list)
+
+    def allows(self, tool_name: str) -> bool:
+        """Check if this policy allows a tool.
+
+        Deny list takes precedence over allow list.
+
+        Args:
+            tool_name: The name of the tool to check.
+
+        Returns:
+            True if the tool is allowed, False otherwise.
+        """
+        # Deny list takes precedence
+        if tool_name in self.deny_list:
+            return False
+        # If allow_list is set, tool must be in it
+        if self.allow_list is not None and tool_name not in self.allow_list:
+            return False
+        return True
+
+
+def apply_tool_policies(
+    tools: list[ToolDefinition],
+    policies: list[ToolPolicy],
+) -> list[ToolDefinition]:
+    """Apply layered policies to filter tools.
+
+    Policies are applied in order:
+    - Allow lists are intersected (each policy can only restrict further)
+    - Deny lists are unioned (each policy can add more denials)
+
+    Args:
+        tools: List of tools to filter.
+        policies: List of policies to apply in order.
+
+    Returns:
+        Filtered list of tools.
+    """
+    if not policies:
+        return tools
+
+    # Compute effective allow and deny lists
+    effective_allow: set[str] | None = None
+    effective_deny: set[str] = set()
+
+    for policy in policies:
+        # Intersect allow lists
+        if policy.allow_list is not None:
+            policy_allow = set(policy.allow_list)
+            if effective_allow is None:
+                effective_allow = policy_allow
+            else:
+                effective_allow = effective_allow.intersection(policy_allow)
+
+        # Union deny lists
+        effective_deny = effective_deny.union(policy.deny_list)
+
+    # Filter tools
+    result = []
+    for tool in tools:
+        # Check allow list (if set)
+        if effective_allow is not None and tool.name not in effective_allow:
+            continue
+        # Check deny list
+        if tool.name in effective_deny:
+            continue
+        result.append(tool)
+
+    return result
+

voxagent/tools/registry.py

@@ -0,0 +1,89 @@
+"""Tool registry for voxagent."""
+
+from __future__ import annotations
+
+from voxagent.tools.definition import ToolDefinition
+
+
+class ToolNotFoundError(Exception):
+    """Raised when a tool is not found in the registry."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Tool not found: {name}")
+
+
+class ToolAlreadyRegisteredError(Exception):
+    """Raised when trying to register a tool that already exists."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(f"Tool already registered: {name}")
+
+
+class ToolRegistry:
+    """Registry for managing tool definitions."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolDefinition] = {}
+
+    def register(self, tool: ToolDefinition, prefix: str | None = None) -> None:
+        """Register a tool.
+
+        Args:
+            tool: The tool definition to register
+            prefix: Optional namespace prefix (e.g., "mcp_server_name")
+
+        Raises:
+            ToolAlreadyRegisteredError: If tool with same name already registered
+        """
+        name = f"{prefix}_{tool.name}" if prefix else tool.name
+        if name in self._tools:
+            raise ToolAlreadyRegisteredError(name)
+        self._tools[name] = tool
+
+    def unregister(self, name: str) -> None:
+        """Unregister a tool by name.
+
+        Raises:
+            ToolNotFoundError: If tool not found
+        """
+        if name not in self._tools:
+            raise ToolNotFoundError(name)
+        del self._tools[name]
+
+    def get(self, name: str) -> ToolDefinition | None:
+        """Get a tool by name, returns None if not found."""
+        return self._tools.get(name)
+
+    def get_or_raise(self, name: str) -> ToolDefinition:
+        """Get a tool by name.
+
+        Raises:
+            ToolNotFoundError: If tool not found
+        """
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolNotFoundError(name)
+        return tool
+
+    def list(self) -> list[ToolDefinition]:
+        """List all registered tools."""
+        return list(self._tools.values())
+
+    def list_names(self) -> list[str]:
+        """List all registered tool names."""
+        return list(self._tools.keys())
+
+    def clear(self) -> None:
+        """Clear all registered tools."""
+        self._tools.clear()
+
+    def __contains__(self, name: str) -> bool:
+        """Check if a tool is registered."""
+        return name in self._tools
+
+    def __len__(self) -> int:
+        """Return number of registered tools."""
+        return len(self._tools)
+

voxagent/types/__init__.py

@@ -0,0 +1,46 @@
+"""Core type definitions.
+
+This subpackage provides:
+- Message types (user, assistant, system messages)
+- ContentBlock types (text, image, tool_use, tool_result)
+- ToolCall and ToolResult types for tool interactions
+- ModelConfig and AgentConfig for agent configuration
+- RunParams and RunResult for run lifecycle
+- ToolPolicy and ToolMeta for tool management
+"""
+
+from voxagent.types.messages import (
+    ContentBlock,
+    ImageBlock,
+    Message,
+    TextBlock,
+    ToolCall,
+    ToolResult,
+    ToolResultBlock,
+    ToolUseBlock,
+)
+from voxagent.types.run import (
+    AgentConfig,
+    ModelConfig,
+    RunParams,
+    RunResult,
+    ToolMeta,
+    ToolPolicy,
+)
+
+__all__ = [
+    "AgentConfig",
+    "ContentBlock",
+    "ImageBlock",
+    "Message",
+    "ModelConfig",
+    "RunParams",
+    "RunResult",
+    "TextBlock",
+    "ToolCall",
+    "ToolMeta",
+    "ToolPolicy",
+    "ToolResult",
+    "ToolResultBlock",
+    "ToolUseBlock",
+]