agent-runtime-core 0.1.0__py3-none-any.whl

agent_runtime/events/sqlite.py

@@ -0,0 +1,168 @@
+"""
+SQLite event bus implementation.
+
+Good for:
+- Local development with persistence
+- Single-process deployments
+- Testing with real database
+"""
+
+import asyncio
+import json
+import sqlite3
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+from agent_runtime.events.base import EventBus, Event
+
+
+class SQLiteEventBus(EventBus):
+    """
+    SQLite-backed event bus implementation.
+    
+    Stores events in a local SQLite database.
+    Uses polling for subscriptions (no real-time push).
+    """
+    
+    def __init__(self, path: str = "agent_runtime.db"):
+        self.path = path
+        self._initialized = False
+    
+    @contextmanager
+    def _get_connection(self):
+        """Get a database connection."""
+        conn = sqlite3.connect(self.path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+    
+    def _ensure_initialized(self):
+        """Ensure the database schema exists."""
+        if self._initialized:
+            return
+        
+        with self._get_connection() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS events (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    run_id TEXT NOT NULL,
+                    seq INTEGER NOT NULL,
+                    event_type TEXT NOT NULL,
+                    payload TEXT NOT NULL,
+                    timestamp TEXT NOT NULL,
+                    UNIQUE(run_id, seq)
+                )
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_events_run_id 
+                ON events(run_id)
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_events_run_seq 
+                ON events(run_id, seq)
+            """)
+            conn.commit()
+        
+        self._initialized = True
+    
+    async def publish(self, event: Event) -> None:
+        """Publish an event."""
+        self._ensure_initialized()
+        
+        with self._get_connection() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO events (run_id, seq, event_type, payload, timestamp)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    str(event.run_id),
+                    event.seq,
+                    event.event_type,
+                    json.dumps(event.payload),
+                    event.timestamp.isoformat(),
+                ),
+            )
+            conn.commit()
+    
+    async def subscribe(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        check_complete: Optional[callable] = None,
+        poll_interval: float = 0.5,
+    ) -> AsyncIterator[Event]:
+        """
+        Subscribe to events for a run.
+        
+        Uses polling since SQLite doesn't support real-time notifications.
+        """
+        current_seq = from_seq
+        
+        while True:
+            # Get new events
+            events = await self.get_events(run_id, from_seq=current_seq)
+            
+            for event in events:
+                yield event
+                current_seq = event.seq + 1
+            
+            # Check if run is complete
+            if check_complete and await check_complete():
+                break
+            
+            # Poll interval
+            await asyncio.sleep(poll_interval)
+    
+    async def get_events(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        to_seq: Optional[int] = None,
+    ) -> list[Event]:
+        """Get historical events for a run."""
+        self._ensure_initialized()
+        
+        with self._get_connection() as conn:
+            query = """
+                SELECT run_id, seq, event_type, payload, timestamp
+                FROM events
+                WHERE run_id = ? AND seq >= ?
+            """
+            params = [str(run_id), from_seq]
+            
+            if to_seq is not None:
+                query += " AND seq <= ?"
+                params.append(to_seq)
+            
+            query += " ORDER BY seq ASC"
+            
+            rows = conn.execute(query, params).fetchall()
+            
+            return [
+                Event(
+                    run_id=UUID(row["run_id"]),
+                    seq=row["seq"],
+                    event_type=row["event_type"],
+                    payload=json.loads(row["payload"]),
+                    timestamp=datetime.fromisoformat(row["timestamp"]),
+                )
+                for row in rows
+            ]
+    
+    async def get_next_seq(self, run_id: UUID) -> int:
+        """Get the next sequence number for a run."""
+        self._ensure_initialized()
+        
+        with self._get_connection() as conn:
+            row = conn.execute(
+                "SELECT MAX(seq) as max_seq FROM events WHERE run_id = ?",
+                (str(run_id),),
+            ).fetchone()
+            
+            max_seq = row["max_seq"]
+            return (max_seq + 1) if max_seq is not None else 0

agent_runtime/interfaces.py

@@ -0,0 +1,390 @@
+"""
+Core interfaces for the agent runtime.
+
+These interfaces are the stable public API. Everything else can change.
+Agent frameworks (LangGraph, CrewAI, custom) adapt to these interfaces.
+
+SEMVER PROTECTED - Breaking changes require major version bump.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable, Optional, Protocol, TypedDict, AsyncIterator
+from uuid import UUID
+
+
+class EventType(str, Enum):
+    """
+    Standard event types emitted by agent runtimes.
+
+    All agent frameworks must emit through these types.
+    """
+
+    # Lifecycle events
+    RUN_STARTED = "run.started"
+    RUN_HEARTBEAT = "run.heartbeat"
+    RUN_SUCCEEDED = "run.succeeded"
+    RUN_FAILED = "run.failed"
+    RUN_CANCELLED = "run.cancelled"
+    RUN_TIMED_OUT = "run.timed_out"
+
+    # Message events
+    ASSISTANT_DELTA = "assistant.delta"  # Token streaming (optional)
+    ASSISTANT_MESSAGE = "assistant.message"  # Complete message
+
+    # Tool events
+    TOOL_CALL = "tool.call"
+    TOOL_RESULT = "tool.result"
+
+    # State events
+    STATE_CHECKPOINT = "state.checkpoint"
+
+
+class Message(TypedDict, total=False):
+    """
+    Framework-neutral message format.
+
+    Compatible with OpenAI, Anthropic, and other providers.
+    """
+
+    role: str  # "system" | "user" | "assistant" | "tool"
+    content: str | dict | list  # String or structured content
+    name: Optional[str]  # For tool messages
+    tool_call_id: Optional[str]  # For tool results
+    tool_calls: Optional[list]  # For assistant tool calls
+    metadata: dict  # Additional metadata
+
+
+@dataclass
+class RunResult:
+    """
+    Result returned by an agent runtime after execution.
+
+    This is what the runner receives when an agent completes.
+    """
+
+    final_output: dict = field(default_factory=dict)
+    final_messages: list[Message] = field(default_factory=list)
+    usage: dict = field(default_factory=dict)  # Token usage, costs, etc.
+    artifacts: dict = field(default_factory=dict)  # Files, images, etc.
+
+
+@dataclass
+class ErrorInfo:
+    """Structured error information for failed runs."""
+
+    type: str  # Error class name
+    message: str
+    stack: str = ""
+    retriable: bool = True
+    details: dict = field(default_factory=dict)
+
+
+class RunContext(Protocol):
+    """
+    Context provided to agent runtimes during execution.
+
+    This is what agent frameworks use to interact with the runtime.
+    Implementations are provided by the runner.
+    """
+
+    @property
+    def run_id(self) -> UUID:
+        """Unique identifier for this run."""
+        ...
+
+    @property
+    def conversation_id(self) -> Optional[UUID]:
+        """Conversation this run belongs to (if any)."""
+        ...
+
+    @property
+    def input_messages(self) -> list[Message]:
+        """Input messages for this run."""
+        ...
+
+    @property
+    def params(self) -> dict:
+        """Additional parameters for this run."""
+        ...
+
+    @property
+    def metadata(self) -> dict:
+        """Metadata associated with this run (e.g., channel_id, user context)."""
+        ...
+
+    @property
+    def tool_registry(self) -> "ToolRegistry":
+        """Registry of available tools for this agent."""
+        ...
+
+    async def emit(self, event_type: EventType | str, payload: dict) -> None:
+        """
+        Emit an event to the event bus.
+
+        Args:
+            event_type: Type of event (use EventType enum)
+            payload: Event payload data
+        """
+        ...
+
+    async def checkpoint(self, state: dict) -> None:
+        """
+        Save a state checkpoint for recovery.
+
+        Args:
+            state: Serializable state to checkpoint
+        """
+        ...
+
+    async def get_state(self) -> Optional[dict]:
+        """
+        Get the last checkpointed state.
+
+        Returns:
+            The last saved state, or None if no checkpoint exists.
+        """
+        ...
+
+    def cancelled(self) -> bool:
+        """
+        Check if cancellation has been requested.
+
+        Agent runtimes should check this between steps.
+        """
+        ...
+
+
+class AgentRuntime(ABC):
+    """
+    Base class for agent runtime implementations.
+
+    Subclass this to create custom agent runtimes.
+    Each runtime is identified by a unique key.
+    """
+
+    @property
+    @abstractmethod
+    def key(self) -> str:
+        """
+        Unique identifier for this runtime.
+
+        Used to route runs to the correct runtime.
+        """
+        ...
+
+    @abstractmethod
+    async def run(self, ctx: RunContext) -> RunResult:
+        """
+        Execute an agent run.
+
+        Args:
+            ctx: Runtime context with input, tools, and event emission
+
+        Returns:
+            RunResult with final output and messages
+
+        Raises:
+            Exception: On unrecoverable errors (will be caught by runner)
+        """
+        ...
+
+    async def cancel(self, ctx: RunContext) -> None:
+        """
+        Handle cancellation request.
+
+        Override for custom cleanup. Default does nothing.
+        Called when cancellation is requested but run is still active.
+        """
+        pass
+
+    async def on_error(self, ctx: RunContext, error: Exception) -> Optional[ErrorInfo]:
+        """
+        Handle an error during execution.
+
+        Override to customize error handling/classification.
+        Return ErrorInfo to control retry behavior.
+        """
+        return ErrorInfo(
+            type=type(error).__name__,
+            message=str(error),
+            retriable=True,
+        )
+
+
+@dataclass
+class Tool:
+    """Definition of a tool available to agents."""
+
+    name: str
+    description: str
+    parameters: dict  # JSON Schema for parameters
+    handler: Callable  # async def handler(**kwargs) -> Any
+    has_side_effects: bool = False
+    requires_confirmation: bool = False
+    metadata: dict = field(default_factory=dict)
+
+
+# Alias for backwards compatibility
+ToolDefinition = Tool
+
+
+class ToolRegistry:
+    """
+    Registry of tools available to a specific agent.
+
+    Tools are allow-listed per agent_key for security.
+    """
+
+    def __init__(self):
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a tool."""
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Optional[Tool]:
+        """Get a tool by name."""
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[Tool]:
+        """List all registered tools."""
+        return list(self._tools.values())
+
+    def to_openai_format(self) -> list[dict]:
+        """Convert tools to OpenAI function calling format."""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                },
+            }
+            for tool in self._tools.values()
+        ]
+
+    async def execute(self, name: str, arguments: dict) -> Any:
+        """
+        Execute a tool by name.
+
+        Args:
+            name: Tool name
+            arguments: Tool arguments
+
+        Returns:
+            Tool result
+
+        Raises:
+            KeyError: If tool not found
+        """
+        tool = self._tools.get(name)
+        if not tool:
+            raise KeyError(f"Tool not found: {name}")
+        return await tool.handler(**arguments)
+
+
+class LLMClient(ABC):
+    """
+    Abstract LLM client interface.
+
+    Implementations: OpenAIClient, AnthropicClient, LiteLLMClient, etc.
+    This abstraction is what makes the runtime model-agnostic.
+    """
+
+    @abstractmethod
+    async def generate(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        stream: bool = False,
+        tools: Optional[list[dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        **kwargs,
+    ) -> "LLMResponse":
+        """
+        Generate a completion from the LLM.
+
+        Args:
+            messages: Conversation messages
+            model: Model identifier (uses default if not specified)
+            stream: Whether to stream the response
+            tools: Tool definitions in OpenAI format
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+            **kwargs: Provider-specific parameters
+
+        Returns:
+            LLMResponse with message and usage info
+        """
+        ...
+
+    @abstractmethod
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = None,
+        tools: Optional[list[dict]] = None,
+        **kwargs,
+    ) -> AsyncIterator["LLMStreamChunk"]:
+        """
+        Stream a completion from the LLM.
+
+        Yields:
+            LLMStreamChunk objects with deltas
+        """
+        ...
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM generation."""
+
+    message: Message
+    usage: dict = field(default_factory=dict)  # prompt_tokens, completion_tokens, etc.
+    model: str = ""
+    finish_reason: str = ""
+    raw_response: Optional[Any] = None
+
+
+@dataclass
+class LLMStreamChunk:
+    """A chunk from a streaming LLM response."""
+
+    delta: str = ""
+    tool_calls: Optional[list] = None
+    finish_reason: Optional[str] = None
+    usage: Optional[dict] = None
+
+
+class TraceSink(ABC):
+    """
+    Abstract trace sink for observability.
+
+    Implementations: NoopTraceSink, LangfuseTraceSink, OpenTelemetrySink, etc.
+    """
+
+    @abstractmethod
+    def start_run(self, run_id: UUID, metadata: dict) -> None:
+        """Start tracing a run."""
+        ...
+
+    @abstractmethod
+    def log_event(self, run_id: UUID, event_type: str, payload: dict) -> None:
+        """Log an event within a run."""
+        ...
+
+    @abstractmethod
+    def end_run(self, run_id: UUID, outcome: str, metadata: Optional[dict] = None) -> None:
+        """End tracing a run."""
+        ...
+
+    def flush(self) -> None:
+        """Flush any buffered traces. Default is no-op."""
+        pass

agent_runtime/llm/__init__.py

@@ -0,0 +1,83 @@
+"""
+LLM client implementations.
+
+Provides:
+- LLMClient: Abstract interface (from interfaces.py)
+- OpenAIClient: OpenAI API client
+- AnthropicClient: Anthropic API client
+- LiteLLMClient: LiteLLM adapter (optional)
+"""
+
+from agent_runtime.interfaces import LLMClient, LLMResponse, LLMStreamChunk
+
+__all__ = [
+    "LLMClient",
+    "LLMResponse",
+    "LLMStreamChunk",
+    "get_llm_client",
+    "OpenAIConfigurationError",
+    "AnthropicConfigurationError",
+]
+
+
+class OpenAIConfigurationError(Exception):
+    """Raised when OpenAI API key is not configured."""
+    pass
+
+
+class AnthropicConfigurationError(Exception):
+    """Raised when Anthropic API key is not configured."""
+    pass
+
+
+def get_llm_client(provider: str = None, **kwargs) -> LLMClient:
+    """
+    Factory function to get an LLM client.
+
+    Args:
+        provider: "openai", "anthropic", "litellm", etc.
+        **kwargs: Provider-specific configuration (e.g., api_key, default_model)
+
+    Returns:
+        LLMClient instance
+        
+    Raises:
+        OpenAIConfigurationError: If OpenAI is selected but API key is not configured
+        AnthropicConfigurationError: If Anthropic is selected but API key is not configured
+        ValueError: If an unknown provider is specified
+        
+    Example:
+        # Using config (recommended)
+        from agent_runtime.config import configure
+        configure(model_provider="openai", openai_api_key="sk-...")
+        llm = get_llm_client()
+        
+        # Or with explicit API key
+        llm = get_llm_client(api_key='sk-...')
+        
+        # Or with a different provider
+        llm = get_llm_client(provider='anthropic', api_key='sk-ant-...')
+    """
+    from agent_runtime.config import get_config
+
+    config = get_config()
+    provider = provider or config.model_provider
+
+    if provider == "openai":
+        from agent_runtime.llm.openai import OpenAIClient
+        return OpenAIClient(**kwargs)
+
+    elif provider == "anthropic":
+        from agent_runtime.llm.anthropic import AnthropicClient
+        return AnthropicClient(**kwargs)
+
+    elif provider == "litellm":
+        from agent_runtime.llm.litellm_client import LiteLLMClient
+        return LiteLLMClient(**kwargs)
+
+    else:
+        raise ValueError(
+            f"Unknown LLM provider: {provider}\n\n"
+            f"Supported providers: 'openai', 'anthropic', 'litellm'\n"
+            f"Set model_provider in your configuration."
+        )