agent-runtime-core 0.1.0__tar.gz

agent_runtime_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Olstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_runtime_core-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: agent-runtime-core
+Version: 0.1.0
+Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
+Project-URL: Homepage, https://github.com/colstrom/agent_runtime
+Project-URL: Repository, https://github.com/colstrom/agent_runtime
+Author: Chris Olstrom
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,async,llm,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: anthropic>=0.18.0; extra == 'all'
+Requires-Dist: langfuse>=2.0.0; extra == 'all'
+Requires-Dist: litellm>=1.0.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=2.0.0; extra == 'langfuse'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0.0; extra == 'litellm'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# agent_runtime
+
+Framework-agnostic agent runtime library for Python.
+
+## Installation
+
+```bash
+pip install agent_runtime
+```
+
+## Quick Start
+
+```python
+from agent_runtime import configure, get_llm_client
+
+# Configure
+configure(
+    model_provider="openai",
+    openai_api_key="sk-..."
+)
+
+# Get LLM client
+llm = get_llm_client()
+```
+
+## Features
+
+- Pluggable backends (memory, redis, sqlite)
+- LLM client abstractions (OpenAI, Anthropic, LiteLLM)
+- Event streaming
+- State management
+- Queue-based execution

agent_runtime_core-0.1.0/README.md

@@ -0,0 +1,32 @@
+# agent_runtime
+
+Framework-agnostic agent runtime library for Python.
+
+## Installation
+
+```bash
+pip install agent_runtime
+```
+
+## Quick Start
+
+```python
+from agent_runtime import configure, get_llm_client
+
+# Configure
+configure(
+    model_provider="openai",
+    openai_api_key="sk-..."
+)
+
+# Get LLM client
+llm = get_llm_client()
+```
+
+## Features
+
+- Pluggable backends (memory, redis, sqlite)
+- LLM client abstractions (OpenAI, Anthropic, LiteLLM)
+- Event streaming
+- State management
+- Queue-based execution

agent_runtime_core-0.1.0/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_core-0.1.0/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_core-0.1.0/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_core-0.1.0/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_core-0.1.0/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()