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

agent_runtime/__init__.py

@@ -0,0 +1,110 @@
+"""
+agent_runtime - A standalone Python package for building AI agent systems.
+
+This package provides:
+- Core interfaces for agent runtimes
+- Queue, event bus, and state store implementations
+- LLM client abstractions
+- Tracing and observability
+- A runner for executing agent runs
+
+Example usage:
+    from agent_runtime import (
+        AgentRuntime,
+        RunContext,
+        RunResult,
+        Tool,
+        configure,
+    )
+    
+    # Configure the runtime
+    configure(
+        model_provider="openai",
+        queue_backend="memory",
+    )
+    
+    # Create a custom agent runtime
+    class MyAgent(AgentRuntime):
+        @property
+        def key(self) -> str:
+            return "my-agent"
+        
+        async def run(self, ctx: RunContext) -> RunResult:
+            # Your agent logic here
+            return RunResult(final_output={"message": "Hello!"})
+"""
+
+__version__ = "0.1.0"
+
+# Core interfaces
+from agent_runtime.interfaces import (
+    AgentRuntime,
+    EventType,
+    ErrorInfo,
+    LLMClient,
+    LLMResponse,
+    LLMStreamChunk,
+    Message,
+    RunContext,
+    RunResult,
+    Tool,
+    ToolDefinition,
+    ToolRegistry,
+    TraceSink,
+)
+
+# Configuration
+from agent_runtime.config import (
+    RuntimeConfig,
+    configure,
+    get_config,
+)
+
+# Registry
+from agent_runtime.registry import (
+    register_runtime,
+    get_runtime,
+    list_runtimes,
+    unregister_runtime,
+    clear_registry,
+)
+
+# Runner
+from agent_runtime.runner import (
+    AgentRunner,
+    RunnerConfig,
+    RunContextImpl,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Interfaces
+    "AgentRuntime",
+    "LLMClient",
+    "LLMResponse",
+    "LLMStreamChunk",
+    "Message",
+    "RunContext",
+    "RunResult",
+    "ToolRegistry",
+    "Tool",
+    "ToolDefinition",
+    "TraceSink",
+    "EventType",
+    "ErrorInfo",
+    # Configuration
+    "RuntimeConfig",
+    "configure",
+    "get_config",
+    # Registry
+    "register_runtime",
+    "get_runtime",
+    "list_runtimes",
+    "unregister_runtime",
+    "clear_registry",
+    # Runner
+    "AgentRunner",
+    "RunnerConfig",
+    "RunContextImpl",
+]

agent_runtime/config.py

@@ -0,0 +1,172 @@
+"""
+Configuration system for agent_runtime.
+
+Supports:
+- Programmatic configuration via configure()
+- Environment variables
+- Default values
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class RuntimeConfig:
+    """
+    Configuration for the agent runtime.
+    
+    All settings can be overridden via environment variables with
+    AGENT_RUNTIME_ prefix (e.g., AGENT_RUNTIME_MODEL_PROVIDER).
+    """
+    
+    # LLM Provider
+    model_provider: str = "openai"  # openai, anthropic, litellm
+    default_model: str = "gpt-4o"
+    
+    # API Keys (loaded from env if not set)
+    openai_api_key: Optional[str] = None
+    anthropic_api_key: Optional[str] = None
+    
+    # Queue backend
+    queue_backend: str = "memory"  # memory, redis, sqlite
+    
+    # Event bus backend
+    event_bus_backend: str = "memory"  # memory, redis, sqlite
+    
+    # State store backend
+    state_store_backend: str = "memory"  # memory, redis, sqlite
+    
+    # Tracing backend
+    tracing_backend: Optional[str] = None  # noop, langfuse
+    
+    # Redis settings
+    redis_url: Optional[str] = None
+    
+    # SQLite settings
+    sqlite_path: Optional[str] = None
+    
+    # Langfuse settings
+    langfuse_public_key: Optional[str] = None
+    langfuse_secret_key: Optional[str] = None
+    langfuse_host: Optional[str] = None
+    
+    # Runner settings
+    run_timeout_seconds: int = 300
+    heartbeat_interval_seconds: int = 30
+    lease_ttl_seconds: int = 60
+    max_retries: int = 3
+    retry_backoff_base: int = 2
+    retry_backoff_max: int = 300
+    
+    def get_openai_api_key(self) -> Optional[str]:
+        """Get OpenAI API key from config or environment."""
+        return self.openai_api_key or os.environ.get("OPENAI_API_KEY")
+    
+    def get_anthropic_api_key(self) -> Optional[str]:
+        """Get Anthropic API key from config or environment."""
+        return self.anthropic_api_key or os.environ.get("ANTHROPIC_API_KEY")
+
+
+# Global configuration instance
+_config: Optional[RuntimeConfig] = None
+
+
+def configure(**kwargs) -> RuntimeConfig:
+    """
+    Configure the agent runtime.
+    
+    Args:
+        **kwargs: Configuration options (see RuntimeConfig)
+        
+    Returns:
+        The configured RuntimeConfig instance
+        
+    Example:
+        from agent_runtime import configure
+        
+        configure(
+            model_provider="openai",
+            openai_api_key="sk-...",
+            queue_backend="redis",
+            redis_url="redis://localhost:6379",
+        )
+    """
+    global _config
+    
+    # Start with defaults
+    config = RuntimeConfig()
+    
+    # Apply environment variables
+    _apply_env_vars(config)
+    
+    # Apply explicit kwargs
+    for key, value in kwargs.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+        else:
+            raise ValueError(f"Unknown configuration option: {key}")
+    
+    _config = config
+    return config
+
+
+def get_config() -> RuntimeConfig:
+    """
+    Get the current configuration.
+    
+    If not configured, returns default configuration with env vars applied.
+    
+    Returns:
+        RuntimeConfig instance
+    """
+    global _config
+    
+    if _config is None:
+        _config = RuntimeConfig()
+        _apply_env_vars(_config)
+    
+    return _config
+
+
+def reset_config() -> None:
+    """Reset configuration to defaults. Useful for testing."""
+    global _config
+    _config = None
+
+
+def _apply_env_vars(config: RuntimeConfig) -> None:
+    """Apply environment variables to config."""
+    env_mapping = {
+        "AGENT_RUNTIME_MODEL_PROVIDER": "model_provider",
+        "AGENT_RUNTIME_DEFAULT_MODEL": "default_model",
+        "AGENT_RUNTIME_QUEUE_BACKEND": "queue_backend",
+        "AGENT_RUNTIME_EVENT_BUS_BACKEND": "event_bus_backend",
+        "AGENT_RUNTIME_STATE_STORE_BACKEND": "state_store_backend",
+        "AGENT_RUNTIME_TRACING_BACKEND": "tracing_backend",
+        "AGENT_RUNTIME_REDIS_URL": "redis_url",
+        "AGENT_RUNTIME_SQLITE_PATH": "sqlite_path",
+        "AGENT_RUNTIME_LANGFUSE_PUBLIC_KEY": "langfuse_public_key",
+        "AGENT_RUNTIME_LANGFUSE_SECRET_KEY": "langfuse_secret_key",
+        "AGENT_RUNTIME_LANGFUSE_HOST": "langfuse_host",
+    }
+    
+    int_fields = {
+        "AGENT_RUNTIME_RUN_TIMEOUT_SECONDS": "run_timeout_seconds",
+        "AGENT_RUNTIME_HEARTBEAT_INTERVAL_SECONDS": "heartbeat_interval_seconds",
+        "AGENT_RUNTIME_LEASE_TTL_SECONDS": "lease_ttl_seconds",
+        "AGENT_RUNTIME_MAX_RETRIES": "max_retries",
+        "AGENT_RUNTIME_RETRY_BACKOFF_BASE": "retry_backoff_base",
+        "AGENT_RUNTIME_RETRY_BACKOFF_MAX": "retry_backoff_max",
+    }
+    
+    for env_var, attr in env_mapping.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            setattr(config, attr, value)
+    
+    for env_var, attr in int_fields.items():
+        value = os.environ.get(env_var)
+        if value is not None:
+            setattr(config, attr, int(value))

agent_runtime/events/__init__.py

@@ -0,0 +1,55 @@
+"""
+Event bus implementations for agent communication.
+
+Provides:
+- EventBus: Abstract interface
+- Event: Event data structure
+- InMemoryEventBus: For testing and simple use cases
+- RedisEventBus: For production with pub/sub
+- SQLiteEventBus: For persistent local storage
+"""
+
+from agent_runtime.events.base import EventBus, Event
+from agent_runtime.events.memory import InMemoryEventBus
+
+__all__ = [
+    "EventBus",
+    "Event",
+    "InMemoryEventBus",
+    "get_event_bus",
+]
+
+
+def get_event_bus(backend: str = None, **kwargs) -> EventBus:
+    """
+    Factory function to get an event bus.
+    
+    Args:
+        backend: "memory", "redis", or "sqlite"
+        **kwargs: Backend-specific configuration
+        
+    Returns:
+        EventBus instance
+    """
+    from agent_runtime.config import get_config
+    
+    config = get_config()
+    backend = backend or config.event_bus_backend
+    
+    if backend == "memory":
+        return InMemoryEventBus()
+    
+    elif backend == "redis":
+        from agent_runtime.events.redis import RedisEventBus
+        url = kwargs.get("url") or config.redis_url
+        if not url:
+            raise ValueError("redis_url is required for redis event bus backend")
+        return RedisEventBus(url=url, **kwargs)
+    
+    elif backend == "sqlite":
+        from agent_runtime.events.sqlite import SQLiteEventBus
+        path = kwargs.get("path") or config.sqlite_path or "agent_runtime.db"
+        return SQLiteEventBus(path=path)
+    
+    else:
+        raise ValueError(f"Unknown event bus backend: {backend}")

agent_runtime/events/base.py

@@ -0,0 +1,86 @@
+"""
+Abstract base class for event bus implementations.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, AsyncIterator, Callable, Optional
+from uuid import UUID
+
+
+@dataclass
+class Event:
+    """An event emitted by an agent run."""
+    
+    run_id: UUID
+    event_type: str
+    payload: dict = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    sequence: int = 0
+
+
+class EventBus(ABC):
+    """
+    Abstract interface for event bus implementations.
+    
+    Event buses handle:
+    - Publishing events from agent runs
+    - Subscribing to events for a run
+    - Event persistence (optional)
+    """
+    
+    @abstractmethod
+    async def publish(
+        self,
+        run_id: UUID,
+        event_type: str,
+        payload: dict,
+    ) -> None:
+        """
+        Publish an event.
+        
+        Args:
+            run_id: Run that emitted the event
+            event_type: Type of event
+            payload: Event data
+        """
+        ...
+    
+    @abstractmethod
+    async def subscribe(
+        self,
+        run_id: UUID,
+    ) -> AsyncIterator[Event]:
+        """
+        Subscribe to events for a run.
+        
+        Args:
+            run_id: Run to subscribe to
+            
+        Yields:
+            Events as they are published
+        """
+        ...
+    
+    @abstractmethod
+    async def get_events(
+        self,
+        run_id: UUID,
+        since_sequence: int = 0,
+    ) -> list[Event]:
+        """
+        Get historical events for a run.
+        
+        Args:
+            run_id: Run to get events for
+            since_sequence: Only return events after this sequence
+            
+        Returns:
+            List of events
+        """
+        ...
+    
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass

agent_runtime/events/memory.py

@@ -0,0 +1,89 @@
+"""
+In-memory event bus implementation.
+
+Good for:
+- Unit testing
+- Local development
+- Simple single-process scripts
+"""
+
+import asyncio
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+from agent_runtime.events.base import EventBus, Event
+
+
+class InMemoryEventBus(EventBus):
+    """
+    In-memory event bus implementation.
+    
+    Stores events in memory. Data is lost when the process exits.
+    """
+    
+    def __init__(self):
+        # run_id -> list of events
+        self._events: dict[UUID, list[Event]] = defaultdict(list)
+        # run_id -> list of subscriber queues
+        self._subscribers: dict[UUID, list[asyncio.Queue]] = defaultdict(list)
+        self._lock = asyncio.Lock()
+    
+    async def publish(
+        self,
+        run_id: UUID,
+        event_type: str,
+        payload: dict,
+    ) -> None:
+        """Publish an event."""
+        async with self._lock:
+            events = self._events[run_id]
+            sequence = len(events)
+            
+            event = Event(
+                run_id=run_id,
+                event_type=event_type,
+                payload=payload,
+                timestamp=datetime.now(timezone.utc),
+                sequence=sequence,
+            )
+            
+            events.append(event)
+            
+            # Notify subscribers
+            for queue in self._subscribers[run_id]:
+                await queue.put(event)
+    
+    async def subscribe(
+        self,
+        run_id: UUID,
+    ) -> AsyncIterator[Event]:
+        """Subscribe to events for a run."""
+        queue: asyncio.Queue[Event] = asyncio.Queue()
+        
+        async with self._lock:
+            self._subscribers[run_id].append(queue)
+        
+        try:
+            while True:
+                event = await queue.get()
+                yield event
+        finally:
+            async with self._lock:
+                if queue in self._subscribers[run_id]:
+                    self._subscribers[run_id].remove(queue)
+    
+    async def get_events(
+        self,
+        run_id: UUID,
+        since_sequence: int = 0,
+    ) -> list[Event]:
+        """Get historical events for a run."""
+        events = self._events.get(run_id, [])
+        return [e for e in events if e.sequence >= since_sequence]
+    
+    def clear(self) -> None:
+        """Clear all events. Useful for testing."""
+        self._events.clear()
+        self._subscribers.clear()

agent_runtime/events/redis.py

@@ -0,0 +1,185 @@
+"""
+Redis-backed event bus using pub/sub and streams.
+
+Good for:
+- Production deployments
+- Multi-process/distributed setups
+- Real-time streaming
+"""
+
+import asyncio
+import json
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+from agent_runtime.events.base import EventBus, Event
+
+
+class RedisEventBus(EventBus):
+    """
+    Redis-backed event bus implementation.
+
+    Uses Redis Streams for event storage and pub/sub for real-time notifications.
+    """
+
+    STREAM_PREFIX = "agent_runtime:events:"
+    CHANNEL_PREFIX = "agent_runtime:notify:"
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379",
+        event_ttl_seconds: int = 3600 * 6,  # 6 hours
+    ):
+        self.url = url
+        self.event_ttl_seconds = event_ttl_seconds
+        self._client = None
+
+    async def _get_client(self):
+        """Get or create Redis client."""
+        if self._client is None:
+            try:
+                import redis.asyncio as redis
+            except ImportError:
+                raise ImportError(
+                    "redis package is required for RedisEventBus. "
+                    "Install with: pip install agent_runtime[redis]"
+                )
+            self._client = redis.from_url(self.url)
+        return self._client
+
+    def _stream_key(self, run_id: UUID) -> str:
+        """Get Redis stream key for a run."""
+        return f"{self.STREAM_PREFIX}{run_id}"
+
+    def _channel_key(self, run_id: UUID) -> str:
+        """Get Redis pub/sub channel for a run."""
+        return f"{self.CHANNEL_PREFIX}{run_id}"
+
+    async def publish(self, event: Event) -> None:
+        """Publish event to Redis."""
+        client = await self._get_client()
+
+        # Add to stream
+        stream_key = self._stream_key(event.run_id)
+        await client.xadd(
+            stream_key,
+            {"data": json.dumps(event.to_dict())},
+        )
+
+        # Set TTL on stream
+        await client.expire(stream_key, self.event_ttl_seconds)
+
+        # Notify subscribers
+        channel_key = self._channel_key(event.run_id)
+        await client.publish(channel_key, str(event.seq))
+
+    async def subscribe(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        check_complete: Optional[callable] = None,
+    ) -> AsyncIterator[Event]:
+        """
+        Subscribe to events using pub/sub for notifications.
+        
+        Args:
+            run_id: Run to subscribe to
+            from_seq: Start from this sequence number
+            check_complete: Optional async callable that returns True when run is complete
+        """
+        client = await self._get_client()
+        pubsub = client.pubsub()
+        channel_key = self._channel_key(run_id)
+
+        await pubsub.subscribe(channel_key)
+
+        try:
+            # First, get any existing events
+            events = await self.get_events(run_id, from_seq=from_seq)
+            current_seq = from_seq
+
+            for event in events:
+                yield event
+                current_seq = event.seq + 1
+
+            # Then listen for new events
+            while True:
+                # Check if run is complete
+                if check_complete and await check_complete():
+                    # Get any final events
+                    final_events = await self.get_events(run_id, from_seq=current_seq)
+                    for event in final_events:
+                        yield event
+                    break
+
+                # Wait for notification with timeout
+                try:
+                    message = await asyncio.wait_for(
+                        pubsub.get_message(ignore_subscribe_messages=True),
+                        timeout=1.0,
+                    )
+                    if message:
+                        # Get new events
+                        new_events = await self.get_events(run_id, from_seq=current_seq)
+                        for event in new_events:
+                            yield event
+                            current_seq = event.seq + 1
+                except asyncio.TimeoutError:
+                    continue
+
+        finally:
+            await pubsub.unsubscribe(channel_key)
+            await pubsub.close()
+
+    async def get_events(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        to_seq: Optional[int] = None,
+    ) -> list[Event]:
+        """Get events from Redis stream."""
+        client = await self._get_client()
+        stream_key = self._stream_key(run_id)
+
+        # Read from stream
+        messages = await client.xrange(stream_key)
+
+        events = []
+        for msg_id, data in messages:
+            data_bytes = data.get(b"data", data.get("data"))
+            if isinstance(data_bytes, bytes):
+                data_bytes = data_bytes.decode()
+            event_data = json.loads(data_bytes)
+            event = Event.from_dict(event_data)
+
+            if event.seq < from_seq:
+                continue
+            if to_seq is not None and event.seq > to_seq:
+                continue
+
+            events.append(event)
+
+        return sorted(events, key=lambda e: e.seq)
+
+    async def get_next_seq(self, run_id: UUID) -> int:
+        """Get next sequence number from Redis."""
+        client = await self._get_client()
+        stream_key = self._stream_key(run_id)
+
+        # Check Redis stream
+        messages = await client.xrevrange(stream_key, count=1)
+        if messages:
+            msg_id, data = messages[0]
+            data_bytes = data.get(b"data", data.get("data"))
+            if isinstance(data_bytes, bytes):
+                data_bytes = data_bytes.decode()
+            event_data = json.loads(data_bytes)
+            return event_data["seq"] + 1
+
+        return 0
+
+    async def close(self) -> None:
+        """Close Redis connection."""
+        if self._client:
+            await self._client.close()
+            self._client = None