voxagent 0.1.0__py3-none-any.whl

voxagent/__init__.py

@@ -0,0 +1,143 @@
+"""voxagent - A lightweight, model-agnostic LLM provider abstraction.
+
+voxagent provides:
+- Multi-Provider: Unified interface for OpenAI, Anthropic, Google, Groq, Ollama
+- Streaming: Typed StreamChunk union (TextDelta, ToolUse, MessageEnd, Error)
+- Tool System: @tool decorator, typed definitions, abort signal propagation
+- MCP Integration: First-class Model Context Protocol support
+- Sub-Agent Support: Hierarchical agent composition with depth-limited delegation
+- Session Management: File-based sessions with context compaction
+
+Quick Start:
+    >>> from voxagent import Agent
+    >>> agent = Agent(model="openai:gpt-4o")
+    >>> result = await agent.run("Hello!")
+
+With Tools:
+    >>> from voxagent import Agent
+    >>> from voxagent.tools import tool
+    >>>
+    >>> @tool()
+    ... def get_weather(city: str) -> str:
+    ...     '''Get weather for a city.'''
+    ...     return f"Sunny in {city}"
+    >>>
+    >>> agent = Agent(model="anthropic:claude-3-5-sonnet", tools=[get_weather])
+    >>> result = await agent.run("What's the weather in Paris?")
+
+Streaming:
+    >>> from voxagent import Agent
+    >>> from voxagent.providers import TextDeltaChunk
+    >>>
+    >>> agent = Agent(model="openai:gpt-4o")
+    >>> async for chunk in agent.stream("Tell me a story"):
+    ...     if isinstance(chunk, TextDeltaChunk):
+    ...         print(chunk.delta, end="")
+
+For more information, see: https://github.com/voxdomus/voxagent
+"""
+
+from ._version import __version__, __version_info__
+
+# =============================================================================
+# Lazy imports for top-level convenience
+# =============================================================================
+# We use __getattr__ to avoid importing the full dependency chain on module load.
+# This keeps `import voxagent` fast and allows users to import only what they need.
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for top-level classes."""
+    # Core Agent class
+    if name == "Agent":
+        from .agent import Agent
+
+        return Agent
+
+    # Provider base classes and chunks
+    if name in (
+        "BaseProvider",
+        "StreamChunk",
+        "TextDeltaChunk",
+        "ToolUseChunk",
+        "MessageEndChunk",
+        "ErrorChunk",
+        "AbortSignal",
+    ):
+        from . import providers
+
+        return getattr(providers, name)
+
+    # Tool system
+    if name in ("tool", "ToolDefinition", "ToolContext"):
+        from . import tools
+
+        return getattr(tools, name)
+
+    # Message types
+    if name in ("Message", "ToolCall", "ToolResult"):
+        from . import types
+
+        return getattr(types, name)
+
+    # Sub-agent support
+    if name == "SubAgentDefinition":
+        from .subagent import SubAgentDefinition
+
+        return SubAgentDefinition
+    if name == "SubAgentContext":
+        from .subagent import SubAgentContext
+
+        return SubAgentContext
+    if name == "MaxDepthExceededError":
+        from .subagent import MaxDepthExceededError
+
+        return MaxDepthExceededError
+
+    # MCP
+    if name == "MCPServerManager":
+        from .mcp import MCPServerManager
+
+        return MCPServerManager
+
+    # Registry
+    if name in ("ProviderRegistry", "get_default_registry"):
+        from . import providers
+
+        return getattr(providers, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    "__version_info__",
+    # Core
+    "Agent",
+    # Providers
+    "BaseProvider",
+    "StreamChunk",
+    "TextDeltaChunk",
+    "ToolUseChunk",
+    "MessageEndChunk",
+    "ErrorChunk",
+    "AbortSignal",
+    "ProviderRegistry",
+    "get_default_registry",
+    # Tools
+    "tool",
+    "ToolDefinition",
+    "ToolContext",
+    # Types
+    "Message",
+    "ToolCall",
+    "ToolResult",
+    # Sub-agents
+    "SubAgentDefinition",
+    "SubAgentContext",
+    "MaxDepthExceededError",
+    # MCP
+    "MCPServerManager",
+]
+

voxagent/_version.py

@@ -0,0 +1,5 @@
+"""Version information for voxagent."""
+
+__version__ = "0.1.0"
+__version_info__ = tuple(int(x) for x in __version__.split("."))
+

voxagent/agent/__init__.py

@@ -0,0 +1,32 @@
+"""Agent core module for voxagent.
+
+This subpackage provides:
+- Agent class for managing AI agent interactions
+- AbortController for abort signal management
+- TimeoutHandler for timeout-based abort triggering
+- Error recovery and failover handling
+"""
+
+from voxagent.agent.abort import (
+    AbortController,
+    AllProfilesExhausted,
+    FailoverError,
+    FailoverReason,
+    TimeoutHandler,
+    handle_context_overflow,
+)
+from voxagent.agent.core import Agent
+
+# Import providers to ensure they are registered with the default registry
+import voxagent.providers  # noqa: F401
+
+__all__ = [
+    "AbortController",
+    "Agent",
+    "AllProfilesExhausted",
+    "FailoverError",
+    "FailoverReason",
+    "TimeoutHandler",
+    "handle_context_overflow",
+]
+

voxagent/agent/abort.py

@@ -0,0 +1,178 @@
+"""Abort and error handling for voxagent agent runs.
+
+This module provides:
+- AbortController: Controller for aborting agent runs
+- TimeoutHandler: Handles timeout for agent runs
+- handle_context_overflow: Handle context overflow errors
+- FailoverError: Error for failover scenarios (re-exported from auth)
+- FailoverReason: Enum for failover reasons (re-exported from auth)
+- AllProfilesExhausted: Error when all auth profiles are exhausted
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from voxagent.providers.auth import FailoverError, FailoverReason
+from voxagent.providers.base import AbortSignal
+from voxagent.session.compaction import compact_context
+
+if TYPE_CHECKING:
+    from voxagent.types.messages import Message
+
+
+# =============================================================================
+# Custom Error Types
+# =============================================================================
+
+
+class AllProfilesExhausted(Exception):
+    """Error raised when all auth profiles have been exhausted."""
+
+    def __init__(self, message: str = "All authentication profiles exhausted") -> None:
+        """Initialize AllProfilesExhausted.
+
+        Args:
+            message: Error message.
+        """
+        super().__init__(message)
+
+
+# =============================================================================
+# AbortController
+# =============================================================================
+
+
+class AbortController:
+    """Controller for aborting agent runs.
+
+    Provides a signal that can be checked by tools and providers to abort
+    operations, plus cleanup capabilities.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the abort controller."""
+        self._signal = AbortSignal()
+        self._cleaned_up = False
+
+    @property
+    def signal(self) -> AbortSignal:
+        """Get the abort signal."""
+        return self._signal
+
+    def abort(self, reason: str = "Aborted") -> None:
+        """Trigger abort.
+
+        Args:
+            reason: The reason for aborting.
+        """
+        self._signal._aborted = True
+        self._signal._reason = reason
+
+    def cleanup(self) -> None:
+        """Cleanup resources. Safe to call multiple times."""
+        if not self._cleaned_up:
+            self._cleaned_up = True
+
+
+# =============================================================================
+# TimeoutHandler
+# =============================================================================
+
+
+class TimeoutHandler:
+    """Handles timeout for agent runs."""
+
+    def __init__(self, timeout_ms: int) -> None:
+        """Initialize the timeout handler.
+
+        Args:
+            timeout_ms: Timeout in milliseconds.
+        """
+        self.timeout_ms = timeout_ms
+        self._task: asyncio.Task | None = None
+        self._expired = False
+        self._started = False
+
+    async def start(self, abort_controller: AbortController) -> None:
+        """Start timeout timer.
+
+        Args:
+            abort_controller: The abort controller to trigger on timeout.
+        """
+        if self._started:
+            return
+        self._started = True
+
+        async def _timeout_task() -> None:
+            await asyncio.sleep(self.timeout_ms / 1000.0)
+            self._expired = True
+            abort_controller.abort(f"Timeout after {self.timeout_ms}ms")
+
+        self._task = asyncio.create_task(_timeout_task())
+
+    def cancel(self) -> None:
+        """Cancel timeout timer."""
+        if self._task and not self._task.done():
+            self._task.cancel()
+
+    @property
+    def expired(self) -> bool:
+        """Check if timeout expired."""
+        return self._expired
+
+
+# =============================================================================
+# Context Overflow Handler
+# =============================================================================
+
+
+async def handle_context_overflow(
+    messages: list[Message],
+    error: Exception,
+    model: str,
+) -> list[Message]:
+    """Handle context overflow error.
+
+    Applies aggressive compaction to reduce context size.
+
+    Args:
+        messages: The messages that caused the overflow.
+        error: The context overflow error.
+        model: The model name.
+
+    Returns:
+        Compacted list of messages.
+    """
+    if not messages:
+        return []
+
+    # Determine max tokens based on model
+    max_tokens = 4000  # Conservative default
+    if "gpt-4" in model:
+        max_tokens = 128000
+    elif "claude" in model:
+        max_tokens = 200000
+    elif "gpt-3.5" in model:
+        max_tokens = 16000
+
+    # Compact to 30% of max for safety margin after overflow
+    target_tokens = int(max_tokens * 0.3)
+
+    # Use aggressive compaction with minimal preserve_recent
+    return compact_context(messages, target_tokens, preserve_recent=2, model=model, aggressive=True)
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__ = [
+    "AbortController",
+    "TimeoutHandler",
+    "handle_context_overflow",
+    "FailoverError",
+    "FailoverReason",
+    "AllProfilesExhausted",
+]