agent-runtime-core 0.5.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

agent_runtime_core/__init__.py

@@ -34,7 +34,7 @@ Example usage:
             return RunResult(final_output={"message": "Hello!"})
 """
 
-__version__ = "0.5.2"
+__version__ = "0.7.0"
 
 # Core interfaces
 from agent_runtime_core.interfaces import (
@@ -91,6 +91,12 @@ from agent_runtime_core.steps import (
     StepCancelledError,
 )
 
+# Concrete RunContext implementations for different use cases
+from agent_runtime_core.contexts import (
+    InMemoryRunContext,
+    FileRunContext,
+)
+
 # Testing utilities
 from agent_runtime_core.testing import (
     MockRunContext,
@@ -169,6 +175,9 @@ __all__ = [
     "ExecutionState",
     "StepExecutionError",
     "StepCancelledError",
+    # Concrete RunContext implementations
+    "InMemoryRunContext",
+    "FileRunContext",
     # Testing
     "MockRunContext",
     "MockLLMClient",

agent_runtime_core/contexts.py

@@ -0,0 +1,348 @@
+"""
+Concrete RunContext implementations for different use cases.
+
+These implementations satisfy the RunContext protocol and can be used
+directly with StepExecutor and agent runtimes.
+
+Usage:
+    # For simple scripts (in-memory, no persistence)
+    ctx = InMemoryRunContext(run_id=uuid4())
+    
+    # For scripts that need persistence across restarts
+    ctx = FileRunContext(run_id=uuid4(), checkpoint_dir="./checkpoints")
+    
+    # Use with StepExecutor
+    from agent_runtime_core.steps import StepExecutor, Step
+    executor = StepExecutor(ctx)
+    results = await executor.run([
+        Step("fetch", fetch_data),
+        Step("process", process_data),
+    ])
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Optional
+from uuid import UUID, uuid4
+
+from agent_runtime_core.interfaces import EventType, Message, ToolRegistry
+
+
+class InMemoryRunContext:
+    """
+    In-memory RunContext implementation.
+    
+    Good for:
+    - Unit testing
+    - Simple scripts that don't need persistence
+    - Development and prototyping
+    
+    State is lost when the process exits.
+    
+    Example:
+        ctx = InMemoryRunContext(
+            run_id=uuid4(),
+            input_messages=[{"role": "user", "content": "Hello"}],
+        )
+        
+        # Use with an agent
+        result = await my_agent.run(ctx)
+        
+        # Or with StepExecutor
+        executor = StepExecutor(ctx)
+        results = await executor.run(steps)
+    """
+    
+    def __init__(
+        self,
+        run_id: Optional[UUID] = None,
+        *,
+        conversation_id: Optional[UUID] = None,
+        input_messages: Optional[list[Message]] = None,
+        params: Optional[dict] = None,
+        metadata: Optional[dict] = None,
+        tool_registry: Optional[ToolRegistry] = None,
+        on_event: Optional[Callable[[str, dict], None]] = None,
+    ):
+        """
+        Initialize an in-memory run context.
+        
+        Args:
+            run_id: Unique identifier for this run (auto-generated if not provided)
+            conversation_id: Associated conversation ID (optional)
+            input_messages: Input messages for this run
+            params: Additional parameters
+            metadata: Run metadata
+            tool_registry: Registry of available tools
+            on_event: Optional callback for events (for testing/debugging)
+        """
+        self._run_id = run_id or uuid4()
+        self._conversation_id = conversation_id
+        self._input_messages = input_messages or []
+        self._params = params or {}
+        self._metadata = metadata or {}
+        self._tool_registry = tool_registry or ToolRegistry()
+        self._cancelled = False
+        self._state: Optional[dict] = None
+        self._events: list[dict] = []
+        self._on_event = on_event
+    
+    @property
+    def run_id(self) -> UUID:
+        """Unique identifier for this run."""
+        return self._run_id
+    
+    @property
+    def conversation_id(self) -> Optional[UUID]:
+        """Conversation this run belongs to (if any)."""
+        return self._conversation_id
+    
+    @property
+    def input_messages(self) -> list[Message]:
+        """Input messages for this run."""
+        return self._input_messages
+    
+    @property
+    def params(self) -> dict:
+        """Additional parameters for this run."""
+        return self._params
+    
+    @property
+    def metadata(self) -> dict:
+        """Metadata associated with this run."""
+        return self._metadata
+    
+    @property
+    def tool_registry(self) -> ToolRegistry:
+        """Registry of available tools for this agent."""
+        return self._tool_registry
+    
+    async def emit(self, event_type: EventType | str, payload: dict) -> None:
+        """Emit an event (stored in memory)."""
+        event_type_str = event_type.value if hasattr(event_type, 'value') else str(event_type)
+        event = {
+            "event_type": event_type_str,
+            "payload": payload,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+        self._events.append(event)
+        if self._on_event:
+            self._on_event(event_type_str, payload)
+    
+    async def checkpoint(self, state: dict) -> None:
+        """Save a state checkpoint (in memory)."""
+        self._state = state
+    
+    async def get_state(self) -> Optional[dict]:
+        """Get the last checkpointed state."""
+        return self._state
+    
+    def cancelled(self) -> bool:
+        """Check if cancellation has been requested."""
+        return self._cancelled
+    
+    def cancel(self) -> None:
+        """Request cancellation of this run."""
+        self._cancelled = True
+    
+    @property
+    def events(self) -> list[dict]:
+        """Get all emitted events (for testing/debugging)."""
+        return self._events.copy()
+    
+    def clear_events(self) -> None:
+        """Clear all events (for testing)."""
+        self._events.clear()
+
+
+class FileRunContext:
+    """
+    File-based RunContext implementation with persistent checkpoints.
+
+    Good for:
+    - Scripts that need to resume after restart
+    - Long-running processes without a database
+    - Simple persistence without external dependencies
+
+    Checkpoints are saved as JSON files in the specified directory.
+
+    Example:
+        ctx = FileRunContext(
+            run_id=uuid4(),
+            checkpoint_dir="./checkpoints",
+            input_messages=[{"role": "user", "content": "Process this"}],
+        )
+
+        # Checkpoints are saved to ./checkpoints/{run_id}.json
+        executor = StepExecutor(ctx)
+        results = await executor.run(steps)
+
+        # To resume after restart, use the same run_id:
+        ctx = FileRunContext(run_id=previous_run_id, checkpoint_dir="./checkpoints")
+        results = await executor.run(steps, resume=True)
+    """
+
+    def __init__(
+        self,
+        run_id: Optional[UUID] = None,
+        *,
+        checkpoint_dir: str = "./checkpoints",
+        conversation_id: Optional[UUID] = None,
+        input_messages: Optional[list[Message]] = None,
+        params: Optional[dict] = None,
+        metadata: Optional[dict] = None,
+        tool_registry: Optional[ToolRegistry] = None,
+        on_event: Optional[Callable[[str, dict], None]] = None,
+    ):
+        """
+        Initialize a file-based run context.
+
+        Args:
+            run_id: Unique identifier for this run (auto-generated if not provided)
+            checkpoint_dir: Directory to store checkpoint files
+            conversation_id: Associated conversation ID (optional)
+            input_messages: Input messages for this run
+            params: Additional parameters
+            metadata: Run metadata
+            tool_registry: Registry of available tools
+            on_event: Optional callback for events
+        """
+        self._run_id = run_id or uuid4()
+        self._checkpoint_dir = Path(checkpoint_dir)
+        self._conversation_id = conversation_id
+        self._input_messages = input_messages or []
+        self._params = params or {}
+        self._metadata = metadata or {}
+        self._tool_registry = tool_registry or ToolRegistry()
+        self._cancelled = False
+        self._on_event = on_event
+        self._state_cache: Optional[dict] = None
+
+        # Ensure checkpoint directory exists
+        self._checkpoint_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def run_id(self) -> UUID:
+        """Unique identifier for this run."""
+        return self._run_id
+
+    @property
+    def conversation_id(self) -> Optional[UUID]:
+        """Conversation this run belongs to (if any)."""
+        return self._conversation_id
+
+    @property
+    def input_messages(self) -> list[Message]:
+        """Input messages for this run."""
+        return self._input_messages
+
+    @property
+    def params(self) -> dict:
+        """Additional parameters for this run."""
+        return self._params
+
+    @property
+    def metadata(self) -> dict:
+        """Metadata associated with this run."""
+        return self._metadata
+
+    @property
+    def tool_registry(self) -> ToolRegistry:
+        """Registry of available tools for this agent."""
+        return self._tool_registry
+
+    def _checkpoint_path(self) -> Path:
+        """Get the path to the checkpoint file for this run."""
+        return self._checkpoint_dir / f"{self._run_id}.json"
+
+    def _events_path(self) -> Path:
+        """Get the path to the events file for this run."""
+        return self._checkpoint_dir / f"{self._run_id}_events.jsonl"
+
+    async def emit(self, event_type: EventType | str, payload: dict) -> None:
+        """Emit an event (appended to events file)."""
+        event_type_str = event_type.value if hasattr(event_type, 'value') else str(event_type)
+        event = {
+            "event_type": event_type_str,
+            "payload": payload,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+
+        # Append to events file (JSONL format)
+        with open(self._events_path(), "a") as f:
+            f.write(json.dumps(event) + "\n")
+
+        if self._on_event:
+            self._on_event(event_type_str, payload)
+
+    async def checkpoint(self, state: dict) -> None:
+        """Save a state checkpoint to file."""
+        self._state_cache = state
+        checkpoint_data = {
+            "run_id": str(self._run_id),
+            "state": state,
+            "updated_at": datetime.utcnow().isoformat(),
+        }
+
+        # Write atomically using temp file
+        temp_path = self._checkpoint_path().with_suffix(".tmp")
+        with open(temp_path, "w") as f:
+            json.dump(checkpoint_data, f, indent=2)
+        temp_path.rename(self._checkpoint_path())
+
+    async def get_state(self) -> Optional[dict]:
+        """Get the last checkpointed state from file."""
+        if self._state_cache is not None:
+            return self._state_cache
+
+        checkpoint_path = self._checkpoint_path()
+        if not checkpoint_path.exists():
+            return None
+
+        try:
+            with open(checkpoint_path) as f:
+                data = json.load(f)
+            self._state_cache = data.get("state")
+            return self._state_cache
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    def cancelled(self) -> bool:
+        """Check if cancellation has been requested."""
+        return self._cancelled
+
+    def cancel(self) -> None:
+        """Request cancellation of this run."""
+        self._cancelled = True
+
+    def get_events(self) -> list[dict]:
+        """Read all events from the events file."""
+        events_path = self._events_path()
+        if not events_path.exists():
+            return []
+
+        events = []
+        with open(events_path) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        pass
+        return events
+
+    def clear(self) -> None:
+        """Delete checkpoint and events files for this run."""
+        checkpoint_path = self._checkpoint_path()
+        events_path = self._events_path()
+
+        if checkpoint_path.exists():
+            checkpoint_path.unlink()
+        if events_path.exists():
+            events_path.unlink()
+
+        self._state_cache = None
+

agent_runtime_core/registry.py

@@ -3,72 +3,151 @@ Agent runtime registry.
 
 Provides a global registry for agent runtimes, allowing them to be
 looked up by key.
+
+Supports:
+- Manual registration via register_runtime()
+- Factory functions for lazy instantiation
+- Class registration (auto-instantiation)
 """
 
-from typing import Optional
+import logging
+from typing import Callable, Optional, Type, Union
 
 from agent_runtime_core.interfaces import AgentRuntime
 
+logger = logging.getLogger(__name__)
 
 # Global registry
 _runtimes: dict[str, AgentRuntime] = {}
+_runtime_factories: dict[str, Callable[[], AgentRuntime]] = {}
+
+
+def _is_agent_runtime(obj) -> bool:
+    """Check if an object is an AgentRuntime instance."""
+    return isinstance(obj, AgentRuntime)
+
 
+def _is_agent_runtime_class(cls) -> bool:
+    """Check if a class is an AgentRuntime subclass."""
+    if not isinstance(cls, type):
+        return False
+    try:
+        return issubclass(cls, AgentRuntime)
+    except TypeError:
+        return False
 
-def register_runtime(runtime: AgentRuntime) -> None:
+
+def register_runtime(
+    runtime: Union[AgentRuntime, Type[AgentRuntime], Callable[[], AgentRuntime]],
+    key: Optional[str] = None,
+) -> None:
     """
     Register an agent runtime.
-    
+
     Args:
-        runtime: The runtime to register
-        
+        runtime: Runtime instance, class, or factory function
+        key: Optional key override (uses runtime.key if not provided)
+
+    Examples:
+        # Register an instance
+        register_runtime(MyRuntime())
+
+        # Register a class (will be instantiated)
+        register_runtime(MyRuntime)
+
+        # Register with custom key
+        register_runtime(MyRuntime(), key="custom-key")
+
+        # Register a factory
+        register_runtime(lambda: MyRuntime(config=get_config()), key="my-runtime")
+
     Raises:
-        ValueError: If a runtime with the same key is already registered
+        ValueError: If key is required but not provided
+        TypeError: If runtime is not a valid type
     """
-    key = runtime.key
-    if key in _runtimes:
-        raise ValueError(f"Runtime already registered: {key}")
-    _runtimes[key] = runtime
+    if _is_agent_runtime(runtime):
+        # Instance provided
+        runtime_key = key or runtime.key
+        _runtimes[runtime_key] = runtime
+        logger.info(f"Registered agent runtime: {runtime_key}")
+
+    elif _is_agent_runtime_class(runtime):
+        # Class provided - instantiate it
+        instance = runtime()
+        runtime_key = key or instance.key
+        _runtimes[runtime_key] = instance
+        logger.info(f"Registered agent runtime: {runtime_key}")
 
+    elif callable(runtime):
+        # Factory function provided
+        if not key:
+            raise ValueError("key is required when registering a factory function")
+        _runtime_factories[key] = runtime
+        logger.info(f"Registered agent runtime factory: {key}")
 
-def get_runtime(key: str) -> Optional[AgentRuntime]:
+    else:
+        raise TypeError(
+            f"runtime must be AgentRuntime instance, class, or callable, got {type(runtime)}"
+        )
+
+
+def get_runtime(key: str) -> AgentRuntime:
     """
     Get a registered runtime by key.
-    
+
     Args:
         key: The runtime key
-        
+
     Returns:
-        The runtime, or None if not found
+        The runtime instance
+
+    Raises:
+        KeyError: If runtime not found
     """
-    return _runtimes.get(key)
+    # Check instances first
+    if key in _runtimes:
+        return _runtimes[key]
+
+    # Check factories
+    if key in _runtime_factories:
+        instance = _runtime_factories[key]()
+        _runtimes[key] = instance
+        return instance
+
+    raise KeyError(f"Agent runtime not found: {key}. Available: {list_runtimes()}")
 
 
 def list_runtimes() -> list[str]:
     """
     List all registered runtime keys.
-    
+
     Returns:
         List of runtime keys
     """
-    return list(_runtimes.keys())
+    return list(set(_runtimes.keys()) | set(_runtime_factories.keys()))
 
 
 def unregister_runtime(key: str) -> bool:
     """
     Unregister a runtime.
-    
+
     Args:
         key: The runtime key
-        
+
     Returns:
         True if unregistered, False if not found
     """
+    removed = False
     if key in _runtimes:
         del _runtimes[key]
-        return True
-    return False
+        removed = True
+    if key in _runtime_factories:
+        del _runtime_factories[key]
+        removed = True
+    return removed
 
 
 def clear_registry() -> None:
     """Clear all registered runtimes. Useful for testing."""
     _runtimes.clear()
+    _runtime_factories.clear()

{agent_runtime_core-0.5.2.dist-info → agent_runtime_core-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.5.2
+Version: 0.7.0
 Summary: Framework-agnostic Python library for executing AI agents with consistent patterns
 Project-URL: Homepage, https://github.com/makemore/agent-runtime-core
 Project-URL: Repository, https://github.com/makemore/agent-runtime-core
@@ -53,6 +53,7 @@ A lightweight, framework-agnostic Python library for building AI agent systems.
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **0.6.0** | 2025-01-23 | Enhanced registry with factory functions and class registration |
 | **0.5.2** | 2025-01-14 | Add ToolCallingAgent base class, execute_with_events helper |
 | **0.5.1** | 2025-01-13 | Bug fixes and improvements |
 | **0.5.0** | 2025-01-12 | Initial stable release |

{agent_runtime_core-0.5.2.dist-info → agent_runtime_core-0.7.0.dist-info}/RECORD

@@ -1,7 +1,8 @@
-agent_runtime_core/__init__.py,sha256=pn2I6UI_nbnho9K8KViC05RsWTRm0ftXyi7TF0dbyLQ,4139
+agent_runtime_core/__init__.py,sha256=2agzUmo3HGFMoj8K6xeXC0aWU_rrhU6kSt1HbtaVjnE,4380
 agent_runtime_core/config.py,sha256=e3_uB5brAuQcWU36sOhWF9R6RoJrngtCS-xEB3n2fas,4986
+agent_runtime_core/contexts.py,sha256=41UVkSqRJ3E9yIxfCQ-BQ7-wetUfSnDNGdr5-dQOWiY,11349
 agent_runtime_core/interfaces.py,sha256=T74pgS229tvarQD-_o25oflylUR7jq_jbgUjnvVs6IA,12191
-agent_runtime_core/registry.py,sha256=hrbEdNNdqEz7-uN-82qofsXFTZBRDxZ2Ht9qwmp1qkw,1476
+agent_runtime_core/registry.py,sha256=QmazCAcHTsPt236Z_xEBJjdppm6jUuufE-gfvcGMUCk,3959
 agent_runtime_core/runner.py,sha256=M3It72UhfmLt17jVnSvObiSfQ1_RN4JVUIJsjnRd2Ps,12771
 agent_runtime_core/steps.py,sha256=XpVFK7P-ZOpr7NwaP7XFygduIpjrKld-OIig7dHNMKE,11994
 agent_runtime_core/testing.py,sha256=ordECGprBappLBMWxlETvuf2AoIPNomJFeSedXaY30E,11131
@@ -32,7 +33,7 @@ agent_runtime_core/state/sqlite.py,sha256=HKZwDiC_7F1W8Z_Pz8roEs91XhQ9rUHfGpuQ7W
 agent_runtime_core/tracing/__init__.py,sha256=u1QicGc39e30gWyQD4cQWxGGjITnkwoOPUhNrG6aNyI,1266
 agent_runtime_core/tracing/langfuse.py,sha256=Rj2sUlatk5sFro0y68tw5X6fQcSwWxcBOSOjB0F7JTU,3660
 agent_runtime_core/tracing/noop.py,sha256=SpsbpsUcNG6C3xZG3uyiNPUHY8etloISx3w56Q8D3KE,751
-agent_runtime_core-0.5.2.dist-info/METADATA,sha256=Lu_Z_hwn2hWC8czhLGqaUFcT7dEOQ2GSXRlx12RR9KE,23765
-agent_runtime_core-0.5.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-agent_runtime_core-0.5.2.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
-agent_runtime_core-0.5.2.dist-info/RECORD,,
+agent_runtime_core-0.7.0.dist-info/METADATA,sha256=-z-4oebI9V6-mq7wivGR-E-x0WS2dqE5exIz9jnE04M,23858
+agent_runtime_core-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+agent_runtime_core-0.7.0.dist-info/licenses/LICENSE,sha256=fDlWep3_mUrj8KHV_jk275tHVEW7_9sJRhkNuGCZ_TA,1068
+agent_runtime_core-0.7.0.dist-info/RECORD,,