loopengt 0.1.0__py3-none-any.whl

loopengt/core/models/state.py

@@ -0,0 +1,271 @@
+"""Runtime state models for loop execution."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunStatus(StrEnum):
+    """Overall status of a loop run."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class StepStatus(StrEnum):
+    """Status of a single step execution."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    RETRYING = "retrying"
+
+
+def _utc_now() -> datetime:
+    """Return the current UTC timestamp."""
+    return datetime.now(timezone.utc)
+
+
+def _new_id() -> str:
+    """Generate a new unique run/step ID."""
+    return uuid.uuid4().hex[:12]
+
+
+class StepResult(BaseModel):
+    """The output produced by a single step execution."""
+
+    model_config = ConfigDict(frozen=True)
+
+    output: Any = Field(default=None, description="Step output data")
+    error: str | None = Field(default=None, description="Error message if failed")
+    duration_seconds: float = Field(
+        default=0.0, ge=0, description="Wall-clock execution time"
+    )
+    token_usage: dict[str, int] = Field(
+        default_factory=dict,
+        description="Token usage breakdown (prompt_tokens, completion_tokens, …)",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Arbitrary result metadata"
+    )
+
+
+class StepState(BaseModel):
+    """Mutable runtime state for a single step."""
+
+    model_config = ConfigDict()
+
+    step_name: str = Field(..., description="Name of the step")
+    status: StepStatus = Field(
+        default=StepStatus.PENDING, description="Current status"
+    )
+    attempts: int = Field(default=0, ge=0, description="Number of attempts so far")
+    result: StepResult | None = Field(
+        default=None, description="Most recent execution result"
+    )
+    started_at: datetime | None = Field(
+        default=None, description="When execution began"
+    )
+    completed_at: datetime | None = Field(
+        default=None, description="When execution finished"
+    )
+
+    def mark_running(self) -> None:
+        """Transition to running status."""
+        self.status = StepStatus.RUNNING
+        self.attempts += 1
+        self.started_at = _utc_now()
+        self.completed_at = None
+
+    def mark_completed(self, result: StepResult) -> None:
+        """Transition to completed status with the given result."""
+        self.status = StepStatus.COMPLETED
+        self.result = result
+        self.completed_at = _utc_now()
+
+    def mark_failed(self, error: str) -> None:
+        """Transition to failed status."""
+        self.status = StepStatus.FAILED
+        self.result = StepResult(error=error)
+        self.completed_at = _utc_now()
+
+    def mark_retrying(self) -> None:
+        """Transition to retrying status."""
+        self.status = StepStatus.RETRYING
+
+
+class AgentState(BaseModel):
+    """Mutable runtime state for a single agent across the loop."""
+
+    model_config = ConfigDict()
+
+    agent_name: str = Field(..., description="Name of the agent")
+    invocations: int = Field(
+        default=0, ge=0, description="Total invocations in this run"
+    )
+    total_tokens: int = Field(
+        default=0, ge=0, description="Cumulative token usage"
+    )
+    errors: int = Field(
+        default=0, ge=0, description="Total errors encountered"
+    )
+    last_output: Any = Field(
+        default=None, description="Most recent output from this agent"
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Agent-local context / scratchpad",
+    )
+
+    def record_invocation(
+        self, tokens: int = 0, *, error: bool = False
+    ) -> None:
+        """Record one invocation, updating counters."""
+        self.invocations += 1
+        self.total_tokens += tokens
+        if error:
+            self.errors += 1
+
+
+class CheckpointData(BaseModel):
+    """Serializable snapshot of loop state for persistence and resumption."""
+
+    model_config = ConfigDict(frozen=True)
+
+    checkpoint_id: str = Field(
+        default_factory=_new_id, description="Unique checkpoint ID"
+    )
+    run_id: str = Field(..., description="Parent run ID")
+    created_at: datetime = Field(
+        default_factory=_utc_now, description="Creation timestamp"
+    )
+    current_step_index: int = Field(
+        ..., ge=0, description="Index of the step being executed"
+    )
+    step_states: list[StepState] = Field(
+        default_factory=list, description="Snapshot of all step states"
+    )
+    agent_states: list[AgentState] = Field(
+        default_factory=list, description="Snapshot of all agent states"
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict, description="Full loop context at checkpoint time"
+    )
+    history: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Ordered history of completed step outputs",
+    )
+
+
+class LoopState(BaseModel):
+    """Mutable runtime state for an entire loop run.
+
+    Created by the executor when a run starts.  Updated in-place as steps
+    execute.  Can be checkpointed and restored for pause/resume.
+    """
+
+    model_config = ConfigDict()
+
+    run_id: str = Field(
+        default_factory=_new_id, description="Unique run identifier"
+    )
+    loop_name: str = Field(..., description="Name of the loop spec being executed")
+    status: RunStatus = Field(
+        default=RunStatus.PENDING, description="Overall run status"
+    )
+    current_step_index: int = Field(
+        default=0, ge=0, description="Index of the step currently being executed"
+    )
+    turn: int = Field(
+        default=0, ge=0, description="Current turn number (across all agents)"
+    )
+    step_states: dict[str, StepState] = Field(
+        default_factory=dict,
+        description="Map of step name → StepState",
+    )
+    agent_states: dict[str, AgentState] = Field(
+        default_factory=dict,
+        description="Map of agent name → AgentState",
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Shared mutable context accessible to all agents",
+    )
+    history: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Ordered history of step results",
+    )
+    started_at: datetime = Field(
+        default_factory=_utc_now, description="Run start timestamp"
+    )
+    completed_at: datetime | None = Field(
+        default=None, description="Run completion timestamp"
+    )
+    error: str | None = Field(
+        default=None, description="Top-level error message if run failed"
+    )
+    checkpoints: list[str] = Field(
+        default_factory=list,
+        description="List of checkpoint IDs created during this run",
+    )
+
+    # ------------------------------------------------------------------
+    # Lifecycle helpers
+    # ------------------------------------------------------------------
+
+    def mark_running(self) -> None:
+        """Transition to running status."""
+        self.status = RunStatus.RUNNING
+
+    def mark_completed(self) -> None:
+        """Transition to completed status."""
+        self.status = RunStatus.COMPLETED
+        self.completed_at = _utc_now()
+
+    def mark_failed(self, error: str) -> None:
+        """Transition to failed status with an error message."""
+        self.status = RunStatus.FAILED
+        self.error = error
+        self.completed_at = _utc_now()
+
+    def mark_cancelled(self) -> None:
+        """Transition to cancelled status."""
+        self.status = RunStatus.CANCELLED
+        self.completed_at = _utc_now()
+
+    def increment_turn(self) -> None:
+        """Advance the turn counter."""
+        self.turn += 1
+
+    def add_to_history(self, step_name: str, result: Any) -> None:
+        """Append a step result to the history."""
+        self.history.append(
+            {
+                "step": step_name,
+                "turn": self.turn,
+                "result": result,
+                "timestamp": _utc_now().isoformat(),
+            }
+        )
+
+    def to_checkpoint(self) -> CheckpointData:
+        """Create a checkpoint snapshot of the current state."""
+        return CheckpointData(
+            run_id=self.run_id,
+            current_step_index=self.current_step_index,
+            step_states=list(self.step_states.values()),
+            agent_states=list(self.agent_states.values()),
+            context=self.context.copy(),
+            history=list(self.history),
+        )

loopengt/core/models/tool.py

@@ -0,0 +1,105 @@
+"""Tool and MCP capability definitions."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ToolType(StrEnum):
+    """Classification of tool integration type."""
+
+    MCP = "mcp"
+    FUNCTION = "function"
+    BUILTIN = "builtin"
+
+
+class ToolAuth(BaseModel):
+    """Authentication configuration for a tool.
+
+    Supports API key, OAuth, and bearer token patterns.  Secrets are
+    referenced by environment-variable name — never stored in plain text.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    method: str = Field(
+        default="none",
+        description="Auth method: none, api_key, bearer, oauth",
+    )
+    env_var: str | None = Field(
+        default=None,
+        description="Environment variable holding the secret",
+    )
+    header_name: str = Field(
+        default="Authorization",
+        description="HTTP header used to pass the credential",
+    )
+    extra: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional auth parameters",
+    )
+
+
+class ToolSpec(BaseModel):
+    """Specification for a tool available to agents in a loop.
+
+    Tools can be MCP server tools, local Python functions, or built-in
+    framework utilities.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Unique tool identifier"
+    )
+    description: str = Field(
+        default="",
+        max_length=2048,
+        description="Human-readable description of what the tool does",
+    )
+    tool_type: ToolType = Field(
+        default=ToolType.FUNCTION,
+        description="Integration type: mcp, function, or builtin",
+    )
+    schema_def: dict[str, Any] = Field(
+        default_factory=dict,
+        description="JSON Schema for the tool's input parameters",
+    )
+    return_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON Schema for the tool's return value",
+    )
+    auth: ToolAuth = Field(
+        default_factory=ToolAuth,
+        description="Authentication configuration",
+    )
+    timeout_seconds: float = Field(
+        default=60.0, gt=0, description="Maximum execution time"
+    )
+    mcp_server: str | None = Field(
+        default=None,
+        description="MCP server name (required when tool_type is 'mcp')",
+    )
+    function_ref: str | None = Field(
+        default=None,
+        description="Dotted import path for function tools (e.g. 'mymod.utils.do_thing')",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary key-value metadata",
+    )
+
+    def is_mcp(self) -> bool:
+        """Return True if this is an MCP-backed tool."""
+        return self.tool_type == ToolType.MCP
+
+    def is_function(self) -> bool:
+        """Return True if this is a local function tool."""
+        return self.tool_type == ToolType.FUNCTION
+
+    def is_builtin(self) -> bool:
+        """Return True if this is a framework built-in tool."""
+        return self.tool_type == ToolType.BUILTIN

loopengt/core/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtime engine for loop execution."""

loopengt/core/runtime/checkpoint.py

@@ -0,0 +1,152 @@
+"""State persistence via checkpoints for pause/resume support."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from loopengt.core.models.state import CheckpointData, LoopState
+
+logger = structlog.get_logger(__name__)
+
+
+class CheckpointError(Exception):
+    """Raised when a checkpoint operation fails."""
+
+
+class CheckpointManager:
+    """SQLite-backed (or file-backed) state persistence for loop resumption.
+
+    In the current implementation, checkpoints are stored as JSON files
+    under a runs directory.  A future version will use SQLite for better
+    query and concurrency support.
+
+    Usage::
+
+        mgr = CheckpointManager(runs_dir=Path(".loopengt/runs"))
+        cp_id = await mgr.save(state)
+        restored = await mgr.load(run_id, cp_id)
+    """
+
+    def __init__(self, runs_dir: Path | None = None) -> None:
+        self._runs_dir = runs_dir or Path(".loopengt/runs")
+        self._runs_dir.mkdir(parents=True, exist_ok=True)
+        self._log = logger.bind(component="checkpoint")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def save(self, state: LoopState) -> str:
+        """Create a checkpoint from the current loop state.
+
+        Returns the checkpoint ID.
+        """
+        checkpoint = state.to_checkpoint()
+        state.checkpoints.append(checkpoint.checkpoint_id)
+
+        cp_path = self._checkpoint_path(state.run_id, checkpoint.checkpoint_id)
+        cp_path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = checkpoint.model_dump(mode="json")
+        cp_path.write_text(
+            json.dumps(data, indent=2, default=str), encoding="utf-8"
+        )
+
+        self._log.info(
+            "checkpoint.saved",
+            run_id=state.run_id,
+            checkpoint_id=checkpoint.checkpoint_id,
+        )
+        return checkpoint.checkpoint_id
+
+    async def load(
+        self, run_id: str, checkpoint_id: str | None = None
+    ) -> CheckpointData:
+        """Load a checkpoint.
+
+        If *checkpoint_id* is ``None``, loads the latest checkpoint for
+        the given run.
+        """
+        if checkpoint_id:
+            cp_path = self._checkpoint_path(run_id, checkpoint_id)
+        else:
+            cp_path = self._latest_checkpoint_path(run_id)
+
+        if not cp_path.exists():
+            raise CheckpointError(
+                f"Checkpoint not found: {cp_path}"
+            )
+
+        data = json.loads(cp_path.read_text(encoding="utf-8"))
+        checkpoint = CheckpointData.model_validate(data)
+
+        self._log.info(
+            "checkpoint.loaded",
+            run_id=run_id,
+            checkpoint_id=checkpoint.checkpoint_id,
+        )
+        return checkpoint
+
+    async def list_checkpoints(self, run_id: str) -> list[str]:
+        """List checkpoint IDs for a given run."""
+        cp_dir = self._runs_dir / run_id / "checkpoints"
+        if not cp_dir.exists():
+            return []
+
+        return sorted(
+            p.stem for p in cp_dir.glob("*.json")
+        )
+
+    async def delete(self, run_id: str, checkpoint_id: str) -> None:
+        """Delete a specific checkpoint."""
+        cp_path = self._checkpoint_path(run_id, checkpoint_id)
+        if cp_path.exists():
+            cp_path.unlink()
+            self._log.info(
+                "checkpoint.deleted",
+                run_id=run_id,
+                checkpoint_id=checkpoint_id,
+            )
+
+    def restore_state(
+        self, checkpoint: CheckpointData, base_state: LoopState
+    ) -> LoopState:
+        """Apply checkpoint data to a LoopState, restoring it.
+
+        Returns the restored state (mutates *base_state* in-place).
+        """
+        base_state.current_step_index = checkpoint.current_step_index
+        base_state.context = dict(checkpoint.context)
+        base_state.history = list(checkpoint.history)
+
+        for ss in checkpoint.step_states:
+            base_state.step_states[ss.step_name] = ss
+
+        for ags in checkpoint.agent_states:
+            base_state.agent_states[ags.agent_name] = ags
+
+        return base_state
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _checkpoint_path(self, run_id: str, checkpoint_id: str) -> Path:
+        """Return the file path for a specific checkpoint."""
+        return self._runs_dir / run_id / "checkpoints" / f"{checkpoint_id}.json"
+
+    def _latest_checkpoint_path(self, run_id: str) -> Path:
+        """Return the path of the most recent checkpoint for a run."""
+        cp_dir = self._runs_dir / run_id / "checkpoints"
+        if not cp_dir.exists():
+            raise CheckpointError(f"No checkpoints for run {run_id}")
+
+        candidates = sorted(cp_dir.glob("*.json"), key=lambda p: p.stat().st_mtime)
+        if not candidates:
+            raise CheckpointError(f"No checkpoints for run {run_id}")
+
+        return candidates[-1]