agent-runtime-core 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

agent_runtime_core/config_schema.py

@@ -0,0 +1,307 @@
+"""
+AgentConfig - Canonical JSON schema for portable agent definitions.
+
+This schema defines the format for agent configurations that can be:
+1. Stored in Django as JSON revisions
+2. Loaded from standalone .json files
+3. Used by agent_runtime_core without Django dependency
+
+Example:
+    # Load from file
+    config = AgentConfig.from_file("my_agent.json")
+    
+    # Create runtime and run
+    runtime = JsonAgentRuntime(config, llm_client)
+    result = await runtime.run(ctx)
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+import json
+from pathlib import Path
+
+
+@dataclass
+class SubAgentToolConfig:
+    """
+    Configuration for a sub-agent tool (agent-as-tool pattern).
+
+    This allows an agent to delegate to another agent as if it were a tool.
+    The sub-agent can either be referenced by slug (resolved at runtime)
+    or embedded inline (for portable standalone configs).
+    """
+
+    name: str  # Tool name the parent uses to invoke this agent
+    description: str  # When to use this agent (shown to parent LLM)
+
+    # Reference to sub-agent (one of these should be set)
+    agent_slug: str = ""  # Reference by slug (resolved at runtime from registry)
+    agent_config: Optional["AgentConfig"] = None  # Embedded config (for standalone)
+
+    # Invocation settings
+    invocation_mode: str = "delegate"  # "delegate" or "handoff"
+    context_mode: str = "full"  # "full", "summary", or "message_only"
+    max_turns: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "tool_type": "subagent",
+            "invocation_mode": self.invocation_mode,
+            "context_mode": self.context_mode,
+        }
+        if self.agent_slug:
+            result["agent_slug"] = self.agent_slug
+        if self.agent_config:
+            result["agent_config"] = self.agent_config.to_dict()
+        if self.max_turns is not None:
+            result["max_turns"] = self.max_turns
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SubAgentToolConfig":
+        agent_config = None
+        if "agent_config" in data and data["agent_config"]:
+            # Defer import to avoid circular dependency
+            agent_config = AgentConfig.from_dict(data["agent_config"])
+
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            agent_slug=data.get("agent_slug", ""),
+            agent_config=agent_config,
+            invocation_mode=data.get("invocation_mode", "delegate"),
+            context_mode=data.get("context_mode", "full"),
+            max_turns=data.get("max_turns"),
+        )
+
+
+@dataclass
+class ToolConfig:
+    """Configuration for a single tool."""
+
+    name: str
+    description: str
+    parameters: dict  # JSON Schema for parameters
+    function_path: str  # Import path like "myapp.services.orders.lookup_order"
+
+    # Optional metadata
+    requires_confirmation: bool = False
+    is_safe: bool = True  # No side effects
+    timeout_seconds: int = 30
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+            "function_path": self.function_path,
+            "requires_confirmation": self.requires_confirmation,
+            "is_safe": self.is_safe,
+            "timeout_seconds": self.timeout_seconds,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ToolConfig":
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            parameters=data.get("parameters", {}),
+            function_path=data.get("function_path", ""),
+            requires_confirmation=data.get("requires_confirmation", False),
+            is_safe=data.get("is_safe", True),
+            timeout_seconds=data.get("timeout_seconds", 30),
+        )
+
+
+@dataclass
+class KnowledgeConfig:
+    """Configuration for a knowledge source."""
+    
+    name: str
+    knowledge_type: str  # "text", "file", "url"
+    inclusion_mode: str = "always"  # "always", "on_demand", "rag"
+    
+    # Content (depends on type)
+    content: str = ""  # For text type
+    file_path: str = ""  # For file type
+    url: str = ""  # For url type
+    
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "type": self.knowledge_type,
+            "inclusion_mode": self.inclusion_mode,
+            "content": self.content,
+            "file_path": self.file_path,
+            "url": self.url,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "KnowledgeConfig":
+        return cls(
+            name=data["name"],
+            knowledge_type=data.get("type", "text"),
+            inclusion_mode=data.get("inclusion_mode", "always"),
+            content=data.get("content", ""),
+            file_path=data.get("file_path", ""),
+            url=data.get("url", ""),
+        )
+
+
+@dataclass
+class AgentConfig:
+    """
+    Canonical configuration for an agent.
+
+    This is the portable format that can be serialized to JSON and
+    loaded by any runtime (Django or standalone).
+
+    For multi-agent systems, sub_agents contains embedded agent configs
+    that this agent can delegate to. The sub_agent_tools list defines
+    how each sub-agent is exposed as a tool.
+    """
+
+    # Identity
+    name: str
+    slug: str
+    description: str = ""
+
+    # Core configuration
+    system_prompt: str = ""
+    model: str = "gpt-4o"
+    model_settings: dict = field(default_factory=dict)
+
+    # Tools and knowledge
+    tools: list[ToolConfig] = field(default_factory=list)
+    knowledge: list[KnowledgeConfig] = field(default_factory=list)
+
+    # Sub-agent tools (agent-as-tool pattern)
+    # These define other agents this agent can delegate to
+    sub_agent_tools: list[SubAgentToolConfig] = field(default_factory=list)
+
+    # Metadata
+    version: str = "1.0"
+    schema_version: str = "1"  # For future schema migrations
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    # Extra config (for extensibility)
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Serialize to dictionary (JSON-compatible)."""
+        result = {
+            "schema_version": self.schema_version,
+            "version": self.version,
+            "name": self.name,
+            "slug": self.slug,
+            "description": self.description,
+            "system_prompt": self.system_prompt,
+            "model": self.model,
+            "model_settings": self.model_settings,
+            "tools": [t.to_dict() for t in self.tools],
+            "knowledge": [k.to_dict() for k in self.knowledge],
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "extra": self.extra,
+        }
+        # Only include sub_agent_tools if there are any
+        if self.sub_agent_tools:
+            result["sub_agent_tools"] = [s.to_dict() for s in self.sub_agent_tools]
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        """Serialize to JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def save(self, path: str | Path) -> None:
+        """Save to a JSON file."""
+        path = Path(path)
+        path.write_text(self.to_json())
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AgentConfig":
+        """Load from dictionary."""
+        # Parse regular tools (skip subagent tools - they're in sub_agent_tools)
+        tools = []
+        for t in data.get("tools", []):
+            if t.get("tool_type") != "subagent":
+                tools.append(ToolConfig.from_dict(t))
+
+        knowledge = [KnowledgeConfig.from_dict(k) for k in data.get("knowledge", [])]
+
+        # Parse sub-agent tools
+        sub_agent_tools = []
+        for s in data.get("sub_agent_tools", []):
+            sub_agent_tools.append(SubAgentToolConfig.from_dict(s))
+        # Also check tools list for subagent type (backwards compat)
+        for t in data.get("tools", []):
+            if t.get("tool_type") == "subagent":
+                sub_agent_tools.append(SubAgentToolConfig.from_dict(t))
+
+        return cls(
+            name=data["name"],
+            slug=data["slug"],
+            description=data.get("description", ""),
+            system_prompt=data.get("system_prompt", ""),
+            model=data.get("model", "gpt-4o"),
+            model_settings=data.get("model_settings", {}),
+            tools=tools,
+            knowledge=knowledge,
+            sub_agent_tools=sub_agent_tools,
+            version=data.get("version", "1.0"),
+            schema_version=data.get("schema_version", "1"),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+            extra=data.get("extra", {}),
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "AgentConfig":
+        """Load from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "AgentConfig":
+        """Load from a JSON file."""
+        path = Path(path)
+        return cls.from_json(path.read_text())
+
+    def with_timestamp(self) -> "AgentConfig":
+        """Return a copy with updated timestamp."""
+        now = datetime.utcnow().isoformat() + "Z"
+        return AgentConfig(
+            name=self.name,
+            slug=self.slug,
+            description=self.description,
+            system_prompt=self.system_prompt,
+            model=self.model,
+            model_settings=self.model_settings,
+            tools=self.tools,
+            knowledge=self.knowledge,
+            sub_agent_tools=self.sub_agent_tools,
+            version=self.version,
+            schema_version=self.schema_version,
+            created_at=self.created_at or now,
+            updated_at=now,
+            extra=self.extra,
+        )
+
+    def get_all_embedded_agents(self) -> dict[str, "AgentConfig"]:
+        """
+        Get all embedded agent configs (for standalone execution).
+
+        Returns a dict mapping slug -> AgentConfig for all sub-agents
+        that have embedded configs (not just slug references).
+        """
+        agents = {}
+        for sub_tool in self.sub_agent_tools:
+            if sub_tool.agent_config:
+                agents[sub_tool.agent_config.slug] = sub_tool.agent_config
+                # Recursively get nested sub-agents
+                agents.update(sub_tool.agent_config.get_all_embedded_agents())
+        return agents
+

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
+