agnt5 0.3.0a8__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

agnt5/agent/decorator.py

@@ -0,0 +1,112 @@
+"""Agent decorator for registering agents."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, List, Optional
+
+from ..lm import LanguageModel
+
+from .core import Agent
+from .registry import AgentRegistry
+
+
+def agent(
+    _func: Optional[Callable] = None,
+    *,
+    name: Optional[str] = None,
+    model: Optional[LanguageModel] = None,
+    instructions: Optional[str] = None,
+    tools: Optional[List[Any]] = None,
+    model_name: str = "gpt-4o-mini",
+    temperature: float = 0.7,
+    max_iterations: int = 10,
+) -> Callable:
+    """
+    Decorator to register a function as an agent and automatically register it.
+
+    This decorator allows you to define agents as functions that create and return Agent instances.
+    The agent will be automatically registered in the AgentRegistry for discovery by the worker.
+
+    Args:
+        name: Agent name (defaults to function name)
+        model: Language model instance (required if not provided in function)
+        instructions: System instructions (required if not provided in function)
+        tools: List of tools available to the agent
+        model_name: Model name to use
+        temperature: LLM temperature
+        max_iterations: Maximum reasoning iterations
+
+    Returns:
+        Decorated function that returns an Agent instance
+
+    Example:
+        ```python
+        from agnt5 import agent, tool
+        from agnt5.lm import OpenAILanguageModel
+
+        @agent(
+            name="research_agent",
+            model=OpenAILanguageModel(),
+            instructions="You are a research assistant.",
+            tools=[search_web, analyze_data]
+        )
+        def create_researcher():
+            # Agent is created and registered automatically
+            pass
+
+        # Or create agent directly
+        @agent
+        def my_agent():
+            from agnt5.lm import OpenAILanguageModel
+            return Agent(
+                name="my_agent",
+                model=OpenAILanguageModel(),
+                instructions="You are a helpful assistant."
+            )
+        ```
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Determine agent name
+        agent_name = name or func.__name__
+
+        # Create the agent
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Agent:
+            # Check if function returns an Agent
+            result = func(*args, **kwargs)
+            if isinstance(result, Agent):
+                # Function creates its own agent
+                agent_instance = result
+            elif model is not None and instructions is not None:
+                # Create agent from decorator parameters
+                agent_instance = Agent(
+                    name=agent_name,
+                    model=model,
+                    instructions=instructions,
+                    tools=tools,
+                    model_name=model_name,
+                    temperature=temperature,
+                    max_iterations=max_iterations,
+                )
+            else:
+                raise ValueError(
+                    f"Agent decorator for '{agent_name}' requires either "
+                    "the decorated function to return an Agent instance, "
+                    "or 'model' and 'instructions' parameters to be provided"
+                )
+
+            # Register agent
+            AgentRegistry.register(agent_instance)
+            return agent_instance
+
+        # Create agent immediately and store reference
+        agent_instance = wrapper()
+
+        # Return the agent instance itself (so it can be used directly)
+        return agent_instance
+
+    if _func is None:
+        return decorator
+    return decorator(_func)

agnt5/agent/handoff.py

@@ -0,0 +1,105 @@
+"""Agent handoff support for multi-agent systems.
+
+Handoffs enable one agent to delegate control to another specialized agent,
+following the pattern popularized by LangGraph and OpenAI Agents SDK.
+"""
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import Agent
+
+
+class Handoff:
+    """Configuration for agent-to-agent handoff.
+
+    The handoff is exposed to the LLM as a tool named 'transfer_to_{agent_name}'
+    that allows explicit delegation with conversation history.
+
+    Example:
+        ```python
+        specialist = Agent(name="specialist", ...)
+
+        # Simple: Pass agent directly (auto-wrapped with defaults)
+        coordinator = Agent(
+            name="coordinator",
+            handoffs=[specialist]  # Agent auto-converted to Handoff
+        )
+
+        # Advanced: Use Handoff for custom configuration
+        coordinator = Agent(
+            name="coordinator",
+            handoffs=[
+                Handoff(
+                    agent=specialist,
+                    description="Custom description for LLM",
+                    tool_name="custom_transfer_name",
+                    pass_full_history=False
+                )
+            ]
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        agent: "Agent",
+        description: Optional[str] = None,
+        tool_name: Optional[str] = None,
+        pass_full_history: bool = True,
+    ):
+        """Initialize handoff configuration.
+
+        Args:
+            agent: Target agent to hand off to
+            description: Description shown to LLM (defaults to agent instructions)
+            tool_name: Custom tool name (defaults to 'transfer_to_{agent_name}')
+            pass_full_history: Whether to pass full conversation history to target agent
+        """
+        self.agent = agent
+        self.description = description or agent.instructions or f"Transfer to {agent.name}"
+        self.tool_name = tool_name or f"transfer_to_{agent.name}"
+        self.pass_full_history = pass_full_history
+
+
+def handoff(
+    agent: "Agent",
+    description: Optional[str] = None,
+    tool_name: Optional[str] = None,
+    pass_full_history: bool = True,
+) -> Handoff:
+    """Create a handoff configuration for agent-to-agent delegation.
+
+    This is a convenience function for creating Handoff instances with a clean API.
+
+    Args:
+        agent: Target agent to hand off to
+        description: Description shown to LLM
+        tool_name: Custom tool name
+        pass_full_history: Whether to pass full conversation history
+
+    Returns:
+        Handoff configuration
+
+    Example:
+        ```python
+        from agnt5 import Agent, handoff
+
+        research_agent = Agent(name="researcher", ...)
+        writer_agent = Agent(name="writer", ...)
+
+        coordinator = Agent(
+            name="coordinator",
+            handoffs=[
+                handoff(research_agent, "Transfer for research tasks"),
+                handoff(writer_agent, "Transfer for writing tasks"),
+            ]
+        )
+        ```
+    """
+    return Handoff(
+        agent=agent,
+        description=description,
+        tool_name=tool_name,
+        pass_full_history=pass_full_history,
+    )

agnt5/agent/registry.py

@@ -0,0 +1,68 @@
+"""Global agent registry for lookups."""
+
+import logging
+from typing import Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import Agent
+
+logger = logging.getLogger(__name__)
+
+# Global registry for agents
+_AGENT_REGISTRY: Dict[str, "Agent"] = {}
+
+
+class AgentRegistry:
+    """Registry for looking up agents by name.
+
+    This provides a global registry where agents can be registered
+    and looked up by name. Useful for multi-agent systems where
+    agents need to discover each other.
+
+    Example:
+        ```python
+        # Register agent
+        agent = Agent(name="researcher", ...)
+        AgentRegistry.register(agent)
+
+        # Look up agent
+        found = AgentRegistry.get("researcher")
+        ```
+    """
+
+    @staticmethod
+    def register(agent: "Agent") -> None:
+        """Register an agent.
+
+        Args:
+            agent: Agent to register
+        """
+        if agent.name in _AGENT_REGISTRY:
+            logger.warning(f"Overwriting existing agent '{agent.name}'")
+        _AGENT_REGISTRY[agent.name] = agent
+
+    @staticmethod
+    def get(name: str) -> Optional["Agent"]:
+        """Get agent by name.
+
+        Args:
+            name: Name of agent to look up
+
+        Returns:
+            Agent if found, None otherwise
+        """
+        return _AGENT_REGISTRY.get(name)
+
+    @staticmethod
+    def all() -> Dict[str, "Agent"]:
+        """Get all registered agents.
+
+        Returns:
+            Copy of the agent registry
+        """
+        return _AGENT_REGISTRY.copy()
+
+    @staticmethod
+    def clear() -> None:
+        """Clear all registered agents."""
+        _AGENT_REGISTRY.clear()

agnt5/agent/result.py

@@ -0,0 +1,39 @@
+"""Agent execution result."""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..context import Context
+
+
+class AgentResult:
+    """Result from agent execution.
+
+    Attributes:
+        output: The final text output from the agent
+        tool_calls: List of tool calls made during execution
+        context: The execution context
+        handoff_to: Name of agent that was handed off to (if any)
+        handoff_metadata: Additional metadata from handoff
+    """
+
+    def __init__(
+        self,
+        output: str,
+        tool_calls: List[Dict[str, Any]],
+        context: "Context",
+        handoff_to: Optional[str] = None,
+        handoff_metadata: Optional[Dict[str, Any]] = None,
+    ):
+        self.output = output
+        self.tool_calls = tool_calls
+        self.context = context
+        self.handoff_to = handoff_to
+        self.handoff_metadata = handoff_metadata or {}
+
+    def __repr__(self) -> str:
+        return (
+            f"AgentResult(output={self.output[:50]!r}..., "
+            f"tool_calls={len(self.tool_calls)}, "
+            f"handoff_to={self.handoff_to})"
+        )

agnt5/checkpoint.py

@@ -0,0 +1,246 @@
+"""Step-level checkpoint client for durable workflow execution.
+
+This module provides the CheckpointClient class for step-level memoization,
+enabling workflows to skip re-execution of completed steps after crashes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from ._telemetry import setup_module_logger
+
+logger = setup_module_logger(__name__)
+
+
+@dataclass
+class CheckpointResult:
+    """Result of a checkpoint operation.
+
+    Attributes:
+        success: Whether the checkpoint was processed successfully
+        error_message: Error message if the checkpoint failed
+        memoized: Whether the step was already memoized (for step_started)
+        cached_output: Cached output if memoized (as bytes)
+    """
+
+    success: bool
+    error_message: Optional[str] = None
+    memoized: bool = False
+    cached_output: Optional[bytes] = None
+
+
+class CheckpointClient:
+    """Client for step-level checkpoint and memoization.
+
+    This client provides synchronous checkpoint calls that enable
+    durable step execution with platform-side memoization.
+
+    The typical flow for a durable step:
+    1. Call step_started() before execution
+    2. If memoized, return the cached result
+    3. Otherwise, execute the step
+    4. Call step_completed() with the result
+
+    Example:
+        ```python
+        async with CheckpointClient() as client:
+            result = await client.step_started(run_id, "step:fetch_data:0", "fetch_data", "function")
+            if result.memoized:
+                return json.loads(result.cached_output)
+
+            # Execute the step
+            data = await fetch_data()
+
+            # Record completion
+            await client.step_completed(run_id, "step:fetch_data:0", "fetch_data", "function", json.dumps(data).encode())
+            return data
+        ```
+    """
+
+    def __init__(self, endpoint: Optional[str] = None):
+        """Initialize checkpoint client.
+
+        Args:
+            endpoint: Worker Coordinator endpoint URL.
+                     Defaults to AGNT5_COORDINATOR_ENDPOINT env var or http://localhost:34186
+        """
+        try:
+            from ._core import PyCheckpointClient
+
+            self._client = PyCheckpointClient(endpoint)
+            self._connected = False
+        except ImportError as e:
+            logger.warning(f"Checkpoint client not available (Rust core not loaded): {e}")
+            self._client = None
+            self._connected = False
+
+    async def connect(self) -> None:
+        """Connect to the Worker Coordinator.
+
+        Must be called before making checkpoint calls.
+        """
+        if self._client is None:
+            raise RuntimeError("Checkpoint client not available (Rust core not loaded)")
+
+        await self._client.connect()
+        self._connected = True
+        logger.debug("Checkpoint client connected to coordinator")
+
+    async def __aenter__(self) -> "CheckpointClient":
+        """Async context manager entry - connects to coordinator."""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Async context manager exit."""
+        # No explicit disconnect needed - connection is cleaned up on drop
+        pass
+
+    async def step_started(
+        self,
+        run_id: str,
+        step_key: str,
+        step_name: str,
+        step_type: str = "function",
+        input_payload: Optional[bytes] = None,
+    ) -> CheckpointResult:
+        """Send a step started checkpoint and check for memoized result.
+
+        Call this before executing a step. If the step is memoized,
+        the result will contain the cached output.
+
+        Args:
+            run_id: The workflow run ID
+            step_key: Unique key for this step (e.g., "step:greet:0")
+            step_name: Human-readable step name
+            step_type: Type of step (e.g., "function", "activity", "llm_call")
+            input_payload: Input data for the step (optional, for logging)
+
+        Returns:
+            CheckpointResult with memoized=True and cached_output if step was memoized
+        """
+        if self._client is None:
+            return CheckpointResult(success=False, error_message="Client not available")
+
+        if not self._connected:
+            await self.connect()
+
+        result = await self._client.step_started(
+            run_id, step_key, step_name, step_type, input_payload
+        )
+
+        return CheckpointResult(
+            success=result.success,
+            error_message=result.error_message,
+            memoized=result.memoized,
+            cached_output=result.cached_output,
+        )
+
+    async def step_completed(
+        self,
+        run_id: str,
+        step_key: str,
+        step_name: str,
+        step_type: str,
+        output_payload: bytes,
+        latency_ms: Optional[int] = None,
+    ) -> CheckpointResult:
+        """Send a step completed checkpoint.
+
+        Call this after successfully executing a step to record the result
+        for future memoization.
+
+        Args:
+            run_id: The workflow run ID
+            step_key: Unique key for this step
+            step_name: Human-readable step name
+            step_type: Type of step
+            output_payload: Output data from the step
+            latency_ms: Step execution latency in milliseconds
+
+        Returns:
+            CheckpointResult indicating success or failure
+        """
+        if self._client is None:
+            return CheckpointResult(success=False, error_message="Client not available")
+
+        if not self._connected:
+            await self.connect()
+
+        result = await self._client.step_completed(
+            run_id, step_key, step_name, step_type, output_payload, latency_ms
+        )
+
+        return CheckpointResult(
+            success=result.success,
+            error_message=result.error_message,
+            memoized=result.memoized,
+            cached_output=result.cached_output,
+        )
+
+    async def step_failed(
+        self,
+        run_id: str,
+        step_key: str,
+        step_name: str,
+        step_type: str,
+        error_message: str,
+        error_type: str,
+    ) -> CheckpointResult:
+        """Send a step failed checkpoint.
+
+        Call this when a step fails to record the error.
+
+        Args:
+            run_id: The workflow run ID
+            step_key: Unique key for this step
+            step_name: Human-readable step name
+            step_type: Type of step
+            error_message: Error message
+            error_type: Error type/class name
+
+        Returns:
+            CheckpointResult indicating success or failure
+        """
+        if self._client is None:
+            return CheckpointResult(success=False, error_message="Client not available")
+
+        if not self._connected:
+            await self.connect()
+
+        result = await self._client.step_failed(
+            run_id, step_key, step_name, step_type, error_message, error_type
+        )
+
+        return CheckpointResult(
+            success=result.success,
+            error_message=result.error_message,
+            memoized=result.memoized,
+            cached_output=result.cached_output,
+        )
+
+    async def get_memoized_step(
+        self, run_id: str, step_key: str
+    ) -> Optional[bytes]:
+        """Check if a step result is memoized.
+
+        Use this for quick memoization lookups before executing expensive steps.
+
+        Args:
+            run_id: The workflow run ID
+            step_key: Unique key for this step
+
+        Returns:
+            The cached output bytes if memoized, None otherwise
+        """
+        if self._client is None:
+            return None
+
+        if not self._connected:
+            await self.connect()
+
+        return await self._client.get_memoized_step(run_id, step_key)