voxagent 0.1.0__py3-none-any.whl

voxagent/streaming/events.py

@@ -0,0 +1,255 @@
+"""Stream event data types.
+
+This module defines typed event payloads for the streaming event system.
+Each event type is a Pydantic model that can be serialized/deserialized.
+
+Event Categories:
+- Lifecycle Events: RunStartEvent, RunEndEvent, RunErrorEvent
+- Inference Events: AssistantStartEvent, TextDeltaEvent, AssistantEndEvent
+- Tool Events: ToolStartEvent, ToolOutputEvent, ToolEndEvent
+- Context Events: CompactionStartEvent, CompactionEndEvent
+"""
+
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from voxagent.types import Message, ToolCall, ToolResult
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time."""
+    return datetime.now(timezone.utc)
+
+
+# =============================================================================
+# Base Event
+# =============================================================================
+
+
+class BaseEvent(BaseModel):
+    """Base class for all stream events.
+
+    Attributes:
+        run_id: Unique identifier for the current agent run.
+    """
+
+    run_id: str
+
+
+# =============================================================================
+# Lifecycle Events
+# =============================================================================
+
+
+class RunStartEvent(BaseEvent):
+    """Event emitted when an agent run starts.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        session_key: Session key for the run.
+        timestamp: When the run started.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    session_key: str
+    timestamp: datetime = Field(default_factory=_utc_now)
+    event_type: Literal["run_start"] = "run_start"
+
+
+class RunEndEvent(BaseEvent):
+    """Event emitted when an agent run ends.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        messages: Final list of messages from the run.
+        aborted: Whether the run was aborted.
+        timed_out: Whether the run timed out.
+        timestamp: When the run ended.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    messages: list[Message]
+    aborted: bool = False
+    timed_out: bool = False
+    timestamp: datetime = Field(default_factory=_utc_now)
+    event_type: Literal["run_end"] = "run_end"
+
+
+class RunErrorEvent(BaseEvent):
+    """Event emitted when an agent run encounters an error.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        error: Error message.
+        timestamp: When the error occurred.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    error: str
+    timestamp: datetime = Field(default_factory=_utc_now)
+    event_type: Literal["run_error"] = "run_error"
+
+
+# =============================================================================
+# Inference Events
+# =============================================================================
+
+
+class AssistantStartEvent(BaseEvent):
+    """Event emitted when the assistant starts generating a response.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    event_type: Literal["assistant_start"] = "assistant_start"
+
+
+class TextDeltaEvent(BaseEvent):
+    """Event emitted for each text chunk from the assistant.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        delta: The text chunk.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    delta: str
+    event_type: Literal["text_delta"] = "text_delta"
+
+
+class AssistantEndEvent(BaseEvent):
+    """Event emitted when the assistant finishes generating a response.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        message: The complete assistant message.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    message: Message
+    event_type: Literal["assistant_end"] = "assistant_end"
+
+
+# =============================================================================
+# Tool Events
+# =============================================================================
+
+
+class ToolStartEvent(BaseEvent):
+    """Event emitted when a tool execution starts.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        tool_call: The tool call being executed.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    tool_call: ToolCall
+    event_type: Literal["tool_start"] = "tool_start"
+
+
+class ToolOutputEvent(BaseEvent):
+    """Event emitted for streaming tool output.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        tool_call_id: ID of the tool call.
+        delta: Output chunk from the tool.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    tool_call_id: str
+    delta: str
+    event_type: Literal["tool_output"] = "tool_output"
+
+
+class ToolEndEvent(BaseEvent):
+    """Event emitted when a tool execution ends.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        tool_call_id: ID of the tool call.
+        result: The tool result.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    tool_call_id: str
+    result: ToolResult
+    event_type: Literal["tool_end"] = "tool_end"
+
+
+# =============================================================================
+# Context Events
+# =============================================================================
+
+
+class CompactionStartEvent(BaseEvent):
+    """Event emitted when context compaction starts.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        message_count: Number of messages before compaction.
+        token_count: Number of tokens before compaction.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    message_count: int
+    token_count: int
+    event_type: Literal["compaction_start"] = "compaction_start"
+
+
+class CompactionEndEvent(BaseEvent):
+    """Event emitted when context compaction ends.
+
+    Attributes:
+        run_id: Unique identifier for the run.
+        messages_removed: Number of messages removed.
+        tokens_saved: Number of tokens saved.
+        event_type: Discriminator field for type narrowing.
+    """
+
+    messages_removed: int
+    tokens_saved: int
+    event_type: Literal["compaction_end"] = "compaction_end"
+
+
+# =============================================================================
+# Union Type
+# =============================================================================
+
+
+StreamEventData = (
+    RunStartEvent
+    | RunEndEvent
+    | RunErrorEvent
+    | AssistantStartEvent
+    | TextDeltaEvent
+    | AssistantEndEvent
+    | ToolStartEvent
+    | ToolOutputEvent
+    | ToolEndEvent
+    | CompactionStartEvent
+    | CompactionEndEvent
+)
+
+
+__all__ = [
+    "AssistantEndEvent",
+    "AssistantStartEvent",
+    "BaseEvent",
+    "CompactionEndEvent",
+    "CompactionStartEvent",
+    "RunEndEvent",
+    "RunErrorEvent",
+    "RunStartEvent",
+    "StreamEventData",
+    "TextDeltaEvent",
+    "ToolEndEvent",
+    "ToolOutputEvent",
+    "ToolStartEvent",
+]
+

voxagent/subagent/__init__.py

@@ -0,0 +1,20 @@
+"""Sub-agent support for voxagent.
+
+This module provides the ability to register agents as tools that can be called
+by parent agents, enabling hierarchical agent composition and delegation.
+"""
+
+from voxagent.subagent.context import (
+    DEFAULT_MAX_DEPTH,
+    MaxDepthExceededError,
+    SubAgentContext,
+)
+from voxagent.subagent.definition import SubAgentDefinition
+
+__all__ = [
+    "SubAgentDefinition",
+    "SubAgentContext",
+    "MaxDepthExceededError",
+    "DEFAULT_MAX_DEPTH",
+]
+

voxagent/subagent/context.py

@@ -0,0 +1,124 @@
+"""Sub-agent context for depth tracking and propagation.
+
+This module provides SubAgentContext which extends ToolContext with
+depth tracking to prevent infinite recursion in nested agent calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import ConfigDict, Field
+
+from voxagent.providers.base import AbortSignal
+from voxagent.tools.context import ToolContext
+
+T = TypeVar("T")
+
+# Default maximum depth for nested agent calls
+DEFAULT_MAX_DEPTH = 5
+
+
+class MaxDepthExceededError(Exception):
+    """Raised when sub-agent call exceeds maximum depth."""
+
+    def __init__(self, depth: int, max_depth: int) -> None:
+        self.depth = depth
+        self.max_depth = max_depth
+        super().__init__(
+            f"Maximum sub-agent depth exceeded: {depth} > {max_depth}. "
+            "This may indicate infinite recursion or an overly deep agent hierarchy."
+        )
+
+
+class SubAgentContext(ToolContext[T]):
+    """Extended context for sub-agent execution with depth tracking.
+
+    Extends ToolContext with:
+    - depth: Current nesting level (0 = root agent)
+    - max_depth: Maximum allowed nesting depth
+    - parent_run_id: Run ID of the parent agent (for tracing)
+
+    Attributes:
+        depth: Current depth in the agent hierarchy (0 = root).
+        max_depth: Maximum allowed depth before raising MaxDepthExceededError.
+        parent_run_id: The run_id of the parent agent that spawned this sub-agent.
+    """
+
+    depth: int = Field(default=0, ge=0)
+    max_depth: int = Field(default=DEFAULT_MAX_DEPTH, ge=1)
+    parent_run_id: str | None = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def check_depth(self) -> None:
+        """Raise MaxDepthExceededError if depth exceeds max_depth."""
+        if self.depth >= self.max_depth:
+            raise MaxDepthExceededError(self.depth, self.max_depth)
+
+    def child_context(
+        self,
+        abort_signal: AbortSignal | None = None,
+        deps: Any = None,
+        session_id: str | None = None,
+        run_id: str | None = None,
+    ) -> "SubAgentContext[Any]":
+        """Create a child context with incremented depth.
+
+        Args:
+            abort_signal: Abort signal for the child (uses parent's if None).
+            deps: Dependencies for the child (uses parent's if None).
+            session_id: Session ID for the child (uses parent's if None).
+            run_id: Run ID for the child agent.
+
+        Returns:
+            New SubAgentContext with depth + 1.
+
+        Raises:
+            MaxDepthExceededError: If the new depth exceeds max_depth.
+        """
+        new_depth = self.depth + 1
+        if new_depth > self.max_depth:
+            raise MaxDepthExceededError(new_depth, self.max_depth)
+
+        return SubAgentContext(
+            abort_signal=abort_signal or self.abort_signal,
+            deps=deps if deps is not None else self.deps,
+            session_id=session_id or self.session_id,
+            run_id=run_id,
+            retry_count=0,  # Reset retry count for child
+            depth=new_depth,
+            max_depth=self.max_depth,
+            parent_run_id=self.run_id,  # Current run becomes parent
+        )
+
+    @classmethod
+    def from_tool_context(
+        cls,
+        context: ToolContext,
+        depth: int = 0,
+        max_depth: int = DEFAULT_MAX_DEPTH,
+        parent_run_id: str | None = None,
+    ) -> "SubAgentContext[Any]":
+        """Create SubAgentContext from a regular ToolContext.
+
+        Args:
+            context: The source ToolContext.
+            depth: Initial depth (default 0).
+            max_depth: Maximum depth (default DEFAULT_MAX_DEPTH).
+            parent_run_id: Parent run ID for tracing.
+
+        Returns:
+            New SubAgentContext with depth tracking.
+        """
+        return cls(
+            abort_signal=context.abort_signal,
+            deps=context.deps,
+            session_id=context.session_id,
+            run_id=context.run_id,
+            retry_count=context.retry_count,
+            depth=depth,
+            max_depth=max_depth,
+            parent_run_id=parent_run_id,
+        )
+

voxagent/subagent/definition.py

@@ -0,0 +1,172 @@
+"""Sub-agent definition for voxagent.
+
+This module provides SubAgentDefinition, a ToolDefinition subclass that wraps
+an Agent and makes it callable as a tool by a parent agent.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from voxagent.subagent.context import (
+    DEFAULT_MAX_DEPTH,
+    MaxDepthExceededError,
+    SubAgentContext,
+)
+from voxagent.tools.context import ToolContext
+from voxagent.tools.definition import ToolDefinition
+
+if TYPE_CHECKING:
+    from voxagent.agent.core import Agent
+
+
+class SubAgentDefinition(ToolDefinition):
+    """A ToolDefinition that wraps an Agent as a callable tool.
+
+    This allows parent agents to delegate tasks to specialized child agents.
+    The child agent inherits context (abort signal, deps, session) from parent.
+
+    Example:
+        researcher = Agent(model="...", system_prompt="You research topics...")
+        
+        parent = Agent(
+            model="...",
+            sub_agents=[researcher],  # Auto-converted to SubAgentDefinition
+        )
+    """
+
+    def __init__(
+        self,
+        agent: "Agent[Any, Any]",
+        name: str | None = None,
+        description: str | None = None,
+        max_depth: int = DEFAULT_MAX_DEPTH,
+    ) -> None:
+        """Initialize SubAgentDefinition.
+
+        Args:
+            agent: The Agent instance to wrap as a tool.
+            name: Tool name (defaults to agent name or 'sub_agent').
+            description: Tool description (defaults to agent's system prompt).
+            max_depth: Maximum nesting depth for recursive calls.
+        """
+        # Determine tool name
+        tool_name = name or getattr(agent, "name", None) or "sub_agent"
+        tool_name = self._sanitize_name(tool_name)
+
+        # Determine description
+        tool_desc = description or agent._system_prompt or f"Delegate to {tool_name}"
+        # Truncate long descriptions for tool schema
+        if len(tool_desc) > 500:
+            tool_desc = tool_desc[:497] + "..."
+
+        # Validate name manually (don't call parent __init__ with execute)
+        if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", tool_name):
+            raise ValueError(
+                f"Tool name '{tool_name}' is invalid. "
+                "Must contain only alphanumeric characters and underscores."
+            )
+
+        self.name = tool_name
+        self.description = tool_desc
+        self.parameters = {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "The task or query to delegate to this agent.",
+                }
+            },
+            "required": ["task"],
+        }
+        self.is_async = True
+
+        # Sub-agent specific attributes
+        self._agent = agent
+        self._max_depth = max_depth
+
+        # Set execute placeholder
+        self.execute = self._execute_placeholder
+
+    @staticmethod
+    def _sanitize_name(name: str) -> str:
+        """Sanitize agent name to be a valid tool name."""
+        # Replace spaces and invalid chars with underscores
+        sanitized = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+        # Ensure doesn't start with digit
+        if sanitized and sanitized[0].isdigit():
+            sanitized = "_" + sanitized
+        return sanitized or "sub_agent"
+
+    async def _execute_placeholder(self, **params: Any) -> Any:
+        """Placeholder - actual execution happens in run()."""
+        raise NotImplementedError("Use run() instead")
+
+    async def run(self, params: dict[str, Any], context: ToolContext) -> Any:
+        """Execute the sub-agent with the given task.
+
+        Args:
+            params: Must contain 'task' key with the prompt for the sub-agent.
+            context: The ToolContext from the parent agent.
+
+        Returns:
+            The sub-agent's response text.
+
+        Raises:
+            MaxDepthExceededError: If nesting depth exceeds max_depth.
+        """
+        task = params.get("task", "")
+        if not task:
+            return "Error: No task provided for sub-agent"
+
+        # Convert or get SubAgentContext with depth tracking
+        if isinstance(context, SubAgentContext):
+            sub_context = context
+        else:
+            sub_context = SubAgentContext.from_tool_context(
+                context, depth=0, max_depth=self._max_depth
+            )
+
+        # Check depth before spawning child
+        try:
+            child_context = sub_context.child_context(
+                run_id=None,  # Agent.run() will create new run_id
+            )
+        except MaxDepthExceededError as e:
+            return f"Error: {e}"
+
+        # Run the sub-agent
+        try:
+            print(f"\n🤖 SUB-AGENT CALLED: {self.name}")
+            print(f"   Task: {task[:100]}{'...' if len(task) > 100 else ''}")
+            print(f"   Depth: {child_context.depth}/{child_context.max_depth}")
+
+            result = await self._agent.run(
+                prompt=task,
+                deps=child_context.deps,
+                session_key=child_context.session_id,
+                # Pass depth info via message_history metadata (optional)
+            )
+
+            if result.error:
+                return f"Sub-agent error: {result.error}"
+
+            # Return the agent's response
+            if result.assistant_texts:
+                return result.assistant_texts[-1]  # Last response
+            return "Sub-agent completed with no response"
+
+        except Exception as e:
+            return f"Sub-agent execution error: {type(e).__name__}: {e}"
+
+    @property
+    def agent(self) -> "Agent[Any, Any]":
+        """Get the wrapped Agent instance."""
+        return self._agent
+
+    @property
+    def max_depth(self) -> int:
+        """Get the maximum nesting depth."""
+        return self._max_depth
+

voxagent/tools/__init__.py

@@ -0,0 +1,32 @@
+"""Tool system for agent tool definitions and execution.
+
+This subpackage provides:
+- Tool definitions with typed parameters
+- Tool registry for dynamic registration
+- Tool policies for allow/deny filtering
+- Tool execution with abort signal support
+"""
+
+from voxagent.tools.context import AbortError, ToolContext
+from voxagent.tools.decorator import tool
+from voxagent.tools.definition import ToolDefinition
+from voxagent.tools.executor import execute_tool
+from voxagent.tools.policy import ToolPolicy, apply_tool_policies
+from voxagent.tools.registry import (
+    ToolAlreadyRegisteredError,
+    ToolNotFoundError,
+    ToolRegistry,
+)
+
+__all__ = [
+    "AbortError",
+    "ToolAlreadyRegisteredError",
+    "ToolContext",
+    "ToolDefinition",
+    "ToolNotFoundError",
+    "ToolPolicy",
+    "ToolRegistry",
+    "apply_tool_policies",
+    "execute_tool",
+    "tool",
+]

voxagent/tools/context.py

@@ -0,0 +1,50 @@
+"""Tool context for voxagent."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+from voxagent.providers.base import AbortSignal
+
+T = TypeVar("T")
+
+
+class AbortError(Exception):
+    """Raised when an operation is aborted."""
+
+    def __init__(self, message: str = "Operation aborted") -> None:
+        super().__init__(message)
+
+
+class ToolContext(BaseModel, Generic[T]):
+    """Runtime context passed to tool functions.
+
+    Replaces PydanticAI's RunContext with a simpler, more focused API.
+
+    Attributes:
+        abort_signal: Signal to check for abort requests
+        deps: Optional dependencies injected by the agent
+        session_id: Current session ID
+        run_id: Current run ID
+        retry_count: Number of times this tool has been retried
+    """
+
+    abort_signal: AbortSignal
+    deps: T | None = None
+    session_id: str | None = None
+    run_id: str | None = None
+    retry_count: int = 0
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def is_aborted(self) -> bool:
+        """Check if the operation has been aborted."""
+        return self.abort_signal.aborted
+
+    def check_abort(self) -> None:
+        """Raise AbortError if aborted."""
+        if self.abort_signal.aborted:
+            raise AbortError("Operation aborted")
+