agent-runtime-core 0.6.0__tar.gz → 0.7.0__tar.gz

{agent_runtime_core-0.6.0 → agent_runtime_core-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-core
-Version: 0.6.0
+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

{agent_runtime_core-0.6.0 → agent_runtime_core-0.7.0}/agent_runtime_core/__init__.py

@@ -34,7 +34,7 @@ Example usage:
             return RunResult(final_output={"message": "Hello!"})
 """
 
-__version__ = "0.6.0"
+__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-0.7.0/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-0.6.0 → agent_runtime_core-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-runtime-core"
-version = "0.6.0"
+version = "0.7.0"
 description = "Framework-agnostic Python library for executing AI agents with consistent patterns"
 readme = "README.md"
 license = "MIT"

agent_runtime_core-0.7.0/tests/test_contexts.py

@@ -0,0 +1,263 @@
+"""
+Tests for concrete RunContext implementations.
+"""
+
+import asyncio
+import json
+import tempfile
+from pathlib import Path
+from uuid import uuid4
+
+import pytest
+
+from agent_runtime_core.contexts import InMemoryRunContext, FileRunContext
+from agent_runtime_core.interfaces import EventType, ToolRegistry
+from agent_runtime_core.steps import Step, StepExecutor
+
+
+class TestInMemoryRunContext:
+    """Tests for InMemoryRunContext."""
+    
+    def test_init_defaults(self):
+        """Test initialization with defaults."""
+        ctx = InMemoryRunContext()
+        
+        assert ctx.run_id is not None
+        assert ctx.conversation_id is None
+        assert ctx.input_messages == []
+        assert ctx.params == {}
+        assert ctx.metadata == {}
+        assert isinstance(ctx.tool_registry, ToolRegistry)
+        assert ctx.cancelled() is False
+    
+    def test_init_with_values(self):
+        """Test initialization with custom values."""
+        run_id = uuid4()
+        conv_id = uuid4()
+        messages = [{"role": "user", "content": "Hello"}]
+        params = {"temperature": 0.7}
+        metadata = {"user_id": "123"}
+        
+        ctx = InMemoryRunContext(
+            run_id=run_id,
+            conversation_id=conv_id,
+            input_messages=messages,
+            params=params,
+            metadata=metadata,
+        )
+        
+        assert ctx.run_id == run_id
+        assert ctx.conversation_id == conv_id
+        assert ctx.input_messages == messages
+        assert ctx.params == params
+        assert ctx.metadata == metadata
+    
+    @pytest.mark.asyncio
+    async def test_checkpoint_and_get_state(self):
+        """Test checkpointing and retrieving state."""
+        ctx = InMemoryRunContext()
+        
+        # Initially no state
+        state = await ctx.get_state()
+        assert state is None
+        
+        # Checkpoint some state
+        await ctx.checkpoint({"step": 1, "data": "test"})
+        
+        # Retrieve state
+        state = await ctx.get_state()
+        assert state == {"step": 1, "data": "test"}
+        
+        # Update state
+        await ctx.checkpoint({"step": 2, "data": "updated"})
+        state = await ctx.get_state()
+        assert state == {"step": 2, "data": "updated"}
+    
+    @pytest.mark.asyncio
+    async def test_emit_events(self):
+        """Test event emission."""
+        events_received = []
+        
+        def on_event(event_type, payload):
+            events_received.append((event_type, payload))
+        
+        ctx = InMemoryRunContext(on_event=on_event)
+        
+        await ctx.emit(EventType.RUN_STARTED, {"agent": "test"})
+        await ctx.emit("custom.event", {"data": "value"})
+        
+        # Check callback was called
+        assert len(events_received) == 2
+        assert events_received[0] == ("run.started", {"agent": "test"})
+        assert events_received[1] == ("custom.event", {"data": "value"})
+        
+        # Check events are stored
+        assert len(ctx.events) == 2
+        assert ctx.events[0]["event_type"] == "run.started"
+        assert ctx.events[1]["event_type"] == "custom.event"
+    
+    def test_cancellation(self):
+        """Test cancellation."""
+        ctx = InMemoryRunContext()
+        
+        assert ctx.cancelled() is False
+        ctx.cancel()
+        assert ctx.cancelled() is True
+
+
+class TestFileRunContext:
+    """Tests for FileRunContext."""
+    
+    @pytest.fixture
+    def temp_dir(self):
+        """Create a temporary directory for checkpoints."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            yield tmpdir
+    
+    def test_init_creates_directory(self, temp_dir):
+        """Test that init creates the checkpoint directory."""
+        checkpoint_dir = Path(temp_dir) / "nested" / "checkpoints"
+        ctx = FileRunContext(checkpoint_dir=str(checkpoint_dir))
+        
+        assert checkpoint_dir.exists()
+    
+    @pytest.mark.asyncio
+    async def test_checkpoint_and_get_state(self, temp_dir):
+        """Test checkpointing and retrieving state from file."""
+        run_id = uuid4()
+        ctx = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+        
+        # Initially no state
+        state = await ctx.get_state()
+        assert state is None
+        
+        # Checkpoint some state
+        await ctx.checkpoint({"step": 1, "data": "test"})
+        
+        # Verify file was created
+        checkpoint_path = Path(temp_dir) / f"{run_id}.json"
+        assert checkpoint_path.exists()
+        
+        # Retrieve state
+        state = await ctx.get_state()
+        assert state == {"step": 1, "data": "test"}
+        
+        # Create new context with same run_id - should load existing state
+        ctx2 = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+        state2 = await ctx2.get_state()
+        assert state2 == {"step": 1, "data": "test"}
+    
+    @pytest.mark.asyncio
+    async def test_emit_events_to_file(self, temp_dir):
+        """Test event emission to file."""
+        run_id = uuid4()
+        ctx = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+        
+        await ctx.emit(EventType.RUN_STARTED, {"agent": "test"})
+        await ctx.emit(EventType.STEP_COMPLETED, {"step": "fetch"})
+        
+        # Verify events file was created
+        events_path = Path(temp_dir) / f"{run_id}_events.jsonl"
+        assert events_path.exists()
+        
+        # Read events back
+        events = ctx.get_events()
+        assert len(events) == 2
+        assert events[0]["event_type"] == "run.started"
+        assert events[1]["event_type"] == "step.completed"
+    
+    @pytest.mark.asyncio
+    async def test_clear(self, temp_dir):
+        """Test clearing checkpoint and events."""
+        run_id = uuid4()
+        ctx = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+        
+        await ctx.checkpoint({"data": "test"})
+        await ctx.emit(EventType.RUN_STARTED, {})
+        
+        checkpoint_path = Path(temp_dir) / f"{run_id}.json"
+        events_path = Path(temp_dir) / f"{run_id}_events.jsonl"
+        
+        assert checkpoint_path.exists()
+        assert events_path.exists()
+        
+        ctx.clear()
+        
+        assert not checkpoint_path.exists()
+        assert not events_path.exists()
+        assert await ctx.get_state() is None
+
+
+class TestContextsWithStepExecutor:
+    """Test that contexts work correctly with StepExecutor."""
+    
+    @pytest.mark.asyncio
+    async def test_in_memory_context_with_executor(self):
+        """Test InMemoryRunContext with StepExecutor."""
+        ctx = InMemoryRunContext()
+        
+        async def step1(ctx, state):
+            state["step1"] = "done"
+            return "step1_result"
+        
+        async def step2(ctx, state):
+            assert state["step1"] == "done"
+            return "step2_result"
+        
+        executor = StepExecutor(ctx)
+        results = await executor.run([
+            Step("step1", step1),
+            Step("step2", step2),
+        ])
+        
+        assert results["step1"] == "step1_result"
+        assert results["step2"] == "step2_result"
+    
+    @pytest.mark.asyncio
+    async def test_file_context_resume(self):
+        """Test FileRunContext resume capability."""
+        with tempfile.TemporaryDirectory() as temp_dir:
+            run_id = uuid4()
+            execution_count = {"step1": 0, "step2": 0}
+            
+            async def step1(ctx, state):
+                execution_count["step1"] += 1
+                return "step1_result"
+            
+            async def step2(ctx, state):
+                execution_count["step2"] += 1
+                # Simulate failure on first attempt
+                if execution_count["step2"] == 1:
+                    raise RuntimeError("Simulated failure")
+                return "step2_result"
+            
+            # First run - step1 succeeds, step2 fails
+            ctx1 = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+            executor1 = StepExecutor(ctx1)
+            
+            with pytest.raises(Exception):
+                await executor1.run([
+                    Step("step1", step1),
+                    Step("step2", step2),
+                ])
+            
+            assert execution_count["step1"] == 1
+            assert execution_count["step2"] == 1
+            
+            # Second run - should resume from checkpoint, skip step1
+            ctx2 = FileRunContext(run_id=run_id, checkpoint_dir=temp_dir)
+            executor2 = StepExecutor(ctx2)
+            
+            results = await executor2.run([
+                Step("step1", step1),
+                Step("step2", step2),
+            ], resume=True)
+            
+            # step1 should NOT have been re-executed
+            assert execution_count["step1"] == 1
+            # step2 should have been retried
+            assert execution_count["step2"] == 2
+            
+            assert results["step1"] == "step1_result"
+            assert results["step2"] == "step2_result"
+