agnt5 0.3.2a1__cp310-abi3-manylinux_2_34_aarch64.whl

agnt5/events.py

@@ -0,0 +1,567 @@
+"""Streaming event types for AGNT5 SDK.
+
+These events are sent over SSE connections from gateway to clients
+during component execution (agents, workflows, functions).
+
+Event types align with the journal event taxonomy defined in:
+platform/pkg/repository/dto/journal_event.go
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+import json
+import time
+
+
+class EventType(str, Enum):
+    """All streaming event types."""
+
+    # Run lifecycle
+    RUN_STARTED = "run.started"
+    RUN_COMPLETED = "run.completed"
+    RUN_FAILED = "run.failed"
+    RUN_PAUSED = "run.paused"
+    RUN_RESUMED = "run.resumed"
+    RUN_CANCELLED = "run.cancelled"
+    RUN_TIMEOUT = "run.timeout"
+
+    # LM streaming lifecycle
+    LM_STREAM_STARTED = "lm.stream.started"
+    LM_STREAM_COMPLETED = "lm.stream.completed"
+    LM_STREAM_FAILED = "lm.stream.failed"
+
+    # LM thinking content blocks (extended thinking / chain-of-thought)
+    LM_THINKING_START = "lm.thinking.start"
+    LM_THINKING_DELTA = "lm.thinking.delta"
+    LM_THINKING_STOP = "lm.thinking.stop"
+
+    # LM message content blocks (assistant output)
+    LM_MESSAGE_START = "lm.message.start"
+    LM_MESSAGE_DELTA = "lm.message.delta"
+    LM_MESSAGE_STOP = "lm.message.stop"
+
+    # LM tool call content blocks (LLM deciding to call a tool)
+    LM_TOOL_CALL_START = "lm.tool_call.start"
+    LM_TOOL_CALL_DELTA = "lm.tool_call.delta"
+    LM_TOOL_CALL_STOP = "lm.tool_call.stop"
+
+    # User code output streaming
+    OUTPUT_START = "output.start"
+    OUTPUT_DELTA = "output.delta"
+    OUTPUT_STOP = "output.stop"
+
+    # Progress indicators
+    PROGRESS_UPDATE = "progress.update"
+
+    # Tool execution events
+    TOOL_INVOKED = "tool.invoked"
+    TOOL_COMPLETED = "tool.completed"
+    TOOL_FAILED = "tool.failed"
+
+    # Agent events
+    AGENT_STARTED = "agent.started"
+    AGENT_COMPLETED = "agent.completed"
+    AGENT_FAILED = "agent.failed"
+    AGENT_ITERATION_STARTED = "agent.iteration.started"
+    AGENT_ITERATION_COMPLETED = "agent.iteration.completed"
+    AGENT_MAX_ITERATIONS = "agent.max_iterations.reached"
+    AGENT_TOOL_CALL_STARTED = "agent.tool_call.started"
+    AGENT_TOOL_CALL_COMPLETED = "agent.tool_call.completed"
+
+    # HITL: Approval events
+    APPROVAL_REQUESTED = "approval.requested"
+    APPROVAL_APPROVED = "approval.approved"
+    APPROVAL_REJECTED = "approval.rejected"
+    APPROVAL_EXPIRED = "approval.expired"
+
+    # HITL: Input events
+    INPUT_REQUESTED = "input.requested"
+    INPUT_PROVIDED = "input.provided"
+    INPUT_EXPIRED = "input.expired"
+
+    # HITL: Feedback events
+    FEEDBACK_REQUESTED = "feedback.requested"
+    FEEDBACK_PROVIDED = "feedback.provided"
+    FEEDBACK_EXPIRED = "feedback.expired"
+
+    # Workflow step events
+    WORKFLOW_STEP_STARTED = "workflow.step.started"
+    WORKFLOW_STEP_COMPLETED = "workflow.step.completed"
+    WORKFLOW_STEP_FAILED = "workflow.step.failed"
+
+
+# --- Data payloads for streaming events ---
+
+
+@dataclass
+class ContentBlockStart:
+    """Start of a content block (thinking, message, tool_call, output)."""
+
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"index": self.index}
+
+
+@dataclass
+class ContentBlockDelta:
+    """Delta (incremental content) for a content block."""
+
+    content: str
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"content": self.content, "index": self.index}
+
+
+@dataclass
+class ContentBlockStop:
+    """End of a content block."""
+
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"index": self.index}
+
+
+@dataclass
+class ToolCallStart:
+    """Start of a tool call block."""
+
+    id: str
+    name: str
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"id": self.id, "name": self.name, "index": self.index}
+
+
+@dataclass
+class ToolCallDelta:
+    """Delta for tool call input arguments."""
+
+    input_delta: str
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"input_delta": self.input_delta, "index": self.index}
+
+
+@dataclass
+class ToolCallStop:
+    """End of a tool call block with complete input."""
+
+    id: str
+    name: str
+    input: Dict[str, Any]
+    index: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"id": self.id, "name": self.name, "input": self.input, "index": self.index}
+
+
+@dataclass
+class ProgressUpdate:
+    """Progress indicator update."""
+
+    message: Optional[str] = None
+    percent: Optional[float] = None
+    current: Optional[int] = None
+    total: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {}
+        if self.message is not None:
+            d["message"] = self.message
+        if self.percent is not None:
+            d["percent"] = self.percent
+        if self.current is not None:
+            d["current"] = self.current
+        if self.total is not None:
+            d["total"] = self.total
+        return d
+
+
+@dataclass
+class TokenUsage:
+    """Token usage statistics."""
+
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    thinking_tokens: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "total_tokens": self.total_tokens,
+        }
+        if self.thinking_tokens is not None:
+            d["thinking_tokens"] = self.thinking_tokens
+        return d
+
+
+@dataclass
+class ErrorDetail:
+    """Error details."""
+
+    code: str
+    message: str
+    details: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = {"code": self.code, "message": self.message}
+        if self.details:
+            d["details"] = self.details
+        return d
+
+
+# --- Event class ---
+
+
+@dataclass
+class Event:
+    """A streaming event with typed data payload.
+
+    This is the primary class for emitting events during streaming execution.
+    Events are serialized and sent via the gRPC response stream to the gateway,
+    which then emits them as SSE events to clients.
+
+    For delta events (message_delta, thinking_delta, etc.), data should be
+    the raw content value. The gateway wraps it with {"content": <data>, "index": ...}.
+    For other events, data is typically a dict with structured information.
+    """
+
+    event_type: EventType
+    data: Any  # Raw value for deltas, dict for structured events
+    content_index: int = 0
+    sequence: int = 0
+    source_timestamp_ns: int = field(default_factory=time.time_ns)
+
+    def to_response_fields(self) -> Dict[str, Any]:
+        """Convert to fields for ExecuteComponentResponse proto.
+
+        Returns dict with:
+        - event_type: str
+        - content_index: int
+        - sequence: int
+        - output_data: bytes (JSON-encoded data)
+        """
+        return {
+            "event_type": self.event_type.value,
+            "content_index": self.content_index,
+            "sequence": self.sequence,
+            "output_data": json.dumps(self.data).encode("utf-8") if self.data else b"",
+        }
+
+    @classmethod
+    def thinking_start(cls, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a thinking.start event."""
+        return cls(
+            event_type=EventType.LM_THINKING_START,
+            data=ContentBlockStart(index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def thinking_delta(cls, content: str, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a thinking.delta event.
+
+        Note: data is just the content string. Gateway wraps it with
+        {"content": <data>, "index": content_index}.
+        """
+        return cls(
+            event_type=EventType.LM_THINKING_DELTA,
+            data=content,  # Raw content, gateway adds wrapper
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def thinking_stop(cls, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a thinking.stop event."""
+        return cls(
+            event_type=EventType.LM_THINKING_STOP,
+            data=ContentBlockStop(index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def message_start(cls, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a message.start event."""
+        return cls(
+            event_type=EventType.LM_MESSAGE_START,
+            data=ContentBlockStart(index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def message_delta(cls, content: str, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a message.delta event.
+
+        Note: data is just the content string. Gateway wraps it with
+        {"content": <data>, "index": content_index}.
+        """
+        return cls(
+            event_type=EventType.LM_MESSAGE_DELTA,
+            data=content,  # Raw content, gateway adds wrapper
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def message_stop(cls, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a message.stop event."""
+        return cls(
+            event_type=EventType.LM_MESSAGE_STOP,
+            data=ContentBlockStop(index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def tool_call_start(
+        cls, id: str, name: str, index: int = 0, sequence: int = 0
+    ) -> "Event":
+        """Create a tool_call.start event."""
+        return cls(
+            event_type=EventType.LM_TOOL_CALL_START,
+            data=ToolCallStart(id=id, name=name, index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def tool_call_delta(cls, input_delta: str, index: int = 0, sequence: int = 0) -> "Event":
+        """Create a tool_call.delta event.
+
+        Note: data is just the input_delta string. Gateway wraps it with
+        {"content": <data>, "index": content_index}.
+        """
+        return cls(
+            event_type=EventType.LM_TOOL_CALL_DELTA,
+            data=input_delta,  # Raw input delta, gateway adds wrapper
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def tool_call_stop(
+        cls, id: str, name: str, input: Dict[str, Any], index: int = 0, sequence: int = 0
+    ) -> "Event":
+        """Create a tool_call.stop event."""
+        return cls(
+            event_type=EventType.LM_TOOL_CALL_STOP,
+            data=ToolCallStop(id=id, name=name, input=input, index=index).to_dict(),
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def output_start(cls, index: int = 0, sequence: int = 0, content_type: str = "text/plain") -> "Event":
+        """Create an output.start event for user code streaming."""
+        return cls(
+            event_type=EventType.OUTPUT_START,
+            data={"index": index, "content_type": content_type},
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def output_delta(cls, content: Any, index: int = 0, sequence: int = 0) -> "Event":
+        """Create an output.delta event for user code streaming.
+
+        Note: data is just the content value. Gateway wraps it with
+        {"content": <data>, "index": content_index}.
+        """
+        return cls(
+            event_type=EventType.OUTPUT_DELTA,
+            data=content,  # Raw content, gateway adds wrapper
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def output_stop(cls, index: int = 0, sequence: int = 0) -> "Event":
+        """Create an output.stop event for user code streaming."""
+        return cls(
+            event_type=EventType.OUTPUT_STOP,
+            data={"index": index},
+            content_index=index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def progress(
+        cls,
+        message: Optional[str] = None,
+        percent: Optional[float] = None,
+        current: Optional[int] = None,
+        total: Optional[int] = None,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create a progress.update event."""
+        return cls(
+            event_type=EventType.PROGRESS_UPDATE,
+            data=ProgressUpdate(
+                message=message, percent=percent, current=current, total=total
+            ).to_dict(),
+            content_index=0,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def run_completed(cls, output: Any, usage: Optional[TokenUsage] = None, sequence: int = 0) -> "Event":
+        """Create a run.completed event."""
+        data: Dict[str, Any] = {"output": output}
+        if usage:
+            data["usage"] = usage.to_dict()
+        return cls(
+            event_type=EventType.RUN_COMPLETED,
+            data=data,
+            content_index=0,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def run_failed(cls, error: ErrorDetail, sequence: int = 0) -> "Event":
+        """Create a run.failed event."""
+        return cls(
+            event_type=EventType.RUN_FAILED,
+            data={"error": error.to_dict()},
+            content_index=0,
+            sequence=sequence,
+        )
+
+    # --- Agent events ---
+
+    @classmethod
+    def agent_started(
+        cls,
+        agent_name: str,
+        model: str,
+        tools: Optional[List[str]] = None,
+        max_iterations: int = 10,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create an agent.started event."""
+        return cls(
+            event_type=EventType.AGENT_STARTED,
+            data={
+                "agent_name": agent_name,
+                "model": model,
+                "tools": tools or [],
+                "max_iterations": max_iterations,
+            },
+            sequence=sequence,
+        )
+
+    @classmethod
+    def agent_completed(
+        cls,
+        output: str,
+        iterations: int = 1,
+        tool_calls: Optional[List[Dict[str, Any]]] = None,
+        handoff_to: Optional[str] = None,
+        max_iterations_reached: bool = False,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create an agent.completed event."""
+        return cls(
+            event_type=EventType.AGENT_COMPLETED,
+            data={
+                "output": output,
+                "iterations": iterations,
+                "tool_calls": tool_calls or [],
+                "handoff_to": handoff_to,
+                "max_iterations_reached": max_iterations_reached,
+            },
+            sequence=sequence,
+        )
+
+    @classmethod
+    def agent_failed(
+        cls,
+        error: str,
+        error_type: str,
+        agent_name: Optional[str] = None,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create an agent.failed event."""
+        return cls(
+            event_type=EventType.AGENT_FAILED,
+            data={
+                "error": error,
+                "error_type": error_type,
+                "agent_name": agent_name,
+            },
+            sequence=sequence,
+        )
+
+    @classmethod
+    def agent_tool_call_started(
+        cls,
+        tool_name: str,
+        arguments: str,
+        tool_call_id: Optional[str] = None,
+        content_index: int = 0,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create an agent.tool_call.started event.
+
+        Args:
+            tool_name: Name of the tool being called
+            arguments: JSON-encoded arguments string
+            tool_call_id: Optional unique ID for this tool call (from LLM)
+            content_index: Index for parallel tool calls (0-based)
+            sequence: Event sequence number
+        """
+        return cls(
+            event_type=EventType.AGENT_TOOL_CALL_STARTED,
+            data={
+                "tool_name": tool_name,
+                "arguments": arguments,
+                "tool_call_id": tool_call_id,
+            },
+            content_index=content_index,
+            sequence=sequence,
+        )
+
+    @classmethod
+    def agent_tool_call_completed(
+        cls,
+        tool_name: str,
+        result: Any,
+        error: Optional[str] = None,
+        tool_call_id: Optional[str] = None,
+        content_index: int = 0,
+        sequence: int = 0,
+    ) -> "Event":
+        """Create an agent.tool_call.completed event.
+
+        Args:
+            tool_name: Name of the tool that was called
+            result: The tool's return value (JSON-serializable)
+            error: Error message if tool failed
+            tool_call_id: Optional unique ID for this tool call (from LLM)
+            content_index: Index for parallel tool calls (must match started event)
+            sequence: Event sequence number
+        """
+        return cls(
+            event_type=EventType.AGENT_TOOL_CALL_COMPLETED,
+            data={
+                "tool_name": tool_name,
+                "result": result,
+                "error": error,
+                "tool_call_id": tool_call_id,
+            },
+            content_index=content_index,
+            sequence=sequence,
+        )

agnt5/exceptions.py

@@ -0,0 +1,110 @@
+"""AGNT5 SDK exceptions and error types."""
+
+from typing import Dict, List, Optional
+
+
+class AGNT5Error(Exception):
+    """Base exception for all AGNT5 SDK errors."""
+
+    pass
+
+
+class ConfigurationError(AGNT5Error):
+    """Raised when SDK configuration is invalid."""
+
+    pass
+
+
+class ExecutionError(AGNT5Error):
+    """Raised when function or workflow execution fails."""
+
+    pass
+
+
+class RetryError(ExecutionError):
+    """Raised when a function exceeds maximum retry attempts."""
+
+    def __init__(self, message: str, attempts: int, last_error: Exception) -> None:
+        super().__init__(message)
+        self.attempts = attempts
+        self.last_error = last_error
+
+
+class StateError(AGNT5Error):
+    """Raised when state operations fail."""
+
+    pass
+
+
+class CheckpointError(AGNT5Error):
+    """Raised when checkpoint operations fail."""
+
+    pass
+
+
+class NotImplementedError(AGNT5Error):
+    """Raised when a feature is not yet implemented."""
+
+    pass
+
+
+class WaitingForUserInputException(BaseException):
+    """Raised when workflow needs to pause for user input.
+
+    This exception is used internally by ctx.wait_for_user() to signal
+    that a workflow execution should pause and wait for user input.
+
+    IMPORTANT: This inherits from BaseException (not Exception) to prevent
+    accidental catching by broad `except Exception:` blocks. This is the same
+    pattern Python uses for KeyboardInterrupt and SystemExit.
+
+    The platform catches this exception and:
+    1. Saves the workflow checkpoint state
+    2. Returns awaiting_user_input status to the client
+    3. Presents the question and options to the user
+    4. Resumes execution when user responds
+
+    Attributes:
+        question: The question to ask the user
+        input_type: Type of input ("text", "approval", or "choice")
+        options: List of options for approval/choice inputs
+        checkpoint_state: Current workflow state for resume
+        pause_index: The index of this pause point (for multi-step HITL)
+        agent_context: Optional agent execution state for agent-level HITL
+            Contains: agent_name, iteration, messages, tool_results, pending_tool_call, etc.
+    """
+
+    def __init__(
+        self,
+        question: str,
+        input_type: str,
+        options: Optional[List[Dict]],
+        checkpoint_state: Dict,
+        pause_index: int = 0,
+        agent_context: Optional[Dict] = None,
+    ) -> None:
+        """Initialize WaitingForUserInputException.
+
+        Args:
+            question: Question to ask the user
+            input_type: Type of input - "text", "approval", or "choice"
+            options: List of option dicts (for approval/choice)
+            checkpoint_state: Workflow state snapshot for resume
+            pause_index: Index of this pause point (0-indexed, for multi-step HITL)
+            agent_context: Optional agent execution state for resuming agents
+                Required fields when provided:
+                - agent_name: Name of the agent that paused
+                - iteration: Current iteration number (0-indexed)
+                - messages: LLM conversation history as list of dicts
+                - tool_results: Partial tool results for current iteration
+                - pending_tool_call: The HITL tool call awaiting response
+                - all_tool_calls: All tool calls made so far
+                - model_config: Model settings for resume
+        """
+        super().__init__(f"Waiting for user input: {question}")
+        self.question = question
+        self.input_type = input_type
+        self.options = options or []
+        self.checkpoint_state = checkpoint_state
+        self.pause_index = pause_index
+        self.agent_context = agent_context