agentic-loop 0.3.0__py3-none-any.whl

agentic_loop/orchestration/memory.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class TriageItem:
+    id: str
+    title: str
+    status: str = "pending"
+    detail: str = ""
+    created_at: str = field(default_factory=_utc_now)
+    updated_at: str = field(default_factory=_utc_now)
+    run_id: str | None = None
+
+    @classmethod
+    def create(cls, title: str, *, detail: str = "") -> TriageItem:
+        return cls(id=uuid.uuid4().hex[:10], title=title, detail=detail)
+
+
+@dataclass
+class ProjectState:
+    attempted: list[str] = field(default_factory=list)
+    passed: list[str] = field(default_factory=list)
+    pending: list[str] = field(default_factory=list)
+    last_run_at: str | None = None
+    last_run_id: str | None = None
+    notes: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProjectState:
+        return cls(
+            attempted=list(data.get("attempted", [])),
+            passed=list(data.get("passed", [])),
+            pending=list(data.get("pending", [])),
+            last_run_at=data.get("last_run_at"),
+            last_run_id=data.get("last_run_id"),
+            notes=data.get("notes", ""),
+        )
+
+
+class StateStore:
+    """Persistent loop memory on disk (models forget; the repo does not)."""
+
+    def __init__(self, state_dir: Path) -> None:
+        self.state_dir = state_dir
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        self.state_path = self.state_dir / "state.json"
+        self.triage_path = self.state_dir / "triage.json"
+
+    def load_state(self) -> ProjectState:
+        if not self.state_path.exists():
+            return ProjectState()
+        data = json.loads(self.state_path.read_text(encoding="utf-8"))
+        return ProjectState.from_dict(data)
+
+    def save_state(self, state: ProjectState) -> None:
+        self.state_path.write_text(
+            json.dumps(asdict(state), ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+    def load_triage(self) -> list[TriageItem]:
+        if not self.triage_path.exists():
+            return []
+        raw = json.loads(self.triage_path.read_text(encoding="utf-8"))
+        return [TriageItem(**item) for item in raw.get("items", [])]
+
+    def save_triage(self, items: list[TriageItem]) -> None:
+        payload = {"items": [asdict(item) for item in items]}
+        self.triage_path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+    def record_run(self, *, run_id: str, summary: str, passed: bool) -> ProjectState:
+        state = self.load_state()
+        state.last_run_at = _utc_now()
+        state.last_run_id = run_id
+        key = summary[:200]
+        if key not in state.attempted:
+            state.attempted.append(key)
+        if passed:
+            if key not in state.passed:
+                state.passed.append(key)
+            state.pending = [item for item in state.pending if item != key]
+        elif key not in state.pending:
+            state.pending.append(key)
+        self.save_state(state)
+        return state
+
+    def add_triage(self, title: str, *, detail: str = "", dedupe: bool = True) -> TriageItem:
+        items = self.load_triage()
+        if dedupe:
+            for item in items:
+                if item.title == title and item.status == "pending":
+                    return item
+        entry = TriageItem.create(title, detail=detail)
+        items.append(entry)
+        self.save_triage(items)
+        return entry
+
+    def update_triage_status(self, item_id: str, status: str) -> TriageItem | None:
+        items = self.load_triage()
+        for item in items:
+            if item.id == item_id:
+                item.status = status
+                item.updated_at = _utc_now()
+                self.save_triage(items)
+                return item
+        return None
+
+    def format_markdown(self) -> str:
+        state = self.load_state()
+        triage = self.load_triage()
+        lines = [
+            "# Agentic Loop State",
+            "",
+            f"- last_run_at: {state.last_run_at or '(none)'}",
+            f"- last_run_id: {state.last_run_id or '(none)'}",
+            "",
+            "## Attempted",
+        ]
+        lines.extend(f"- {item}" for item in state.attempted[-20:]) or ["- (none)"]
+        lines.extend(["", "## Passed"])
+        lines.extend(f"- {item}" for item in state.passed[-20:]) or ["- (none)"]
+        lines.extend(["", "## Pending"])
+        lines.extend(f"- {item}" for item in state.pending) or ["- (none)"]
+        lines.extend(["", "## Triage Inbox"])
+        pending_triage = [t for t in triage if t.status == "pending"]
+        if not pending_triage:
+            lines.append("- (empty)")
+        else:
+            for item in pending_triage[:20]:
+                lines.append(f"- [{item.id}] {item.title}")
+        return "\n".join(lines) + "\n"

agentic_loop/orchestration/orchestrator.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from agentic_loop.api import execute_run
+from agentic_loop.config import RunConfig
+from agentic_loop.loop import LoopEvent
+from agentic_loop.orchestration.automations import AutomationResult, run_interval
+from agentic_loop.orchestration.goal import GoalEvaluation, GoalRunner
+from agentic_loop.orchestration.memory import StateStore, TriageItem
+from agentic_loop.orchestration.subagents import load_agent_specs, merge_run_config
+from agentic_loop.skills.loader import SkillLoader
+from agentic_loop.terminal import Terminal
+
+
+class Orchestrator:
+    """Loop Engineering orchestration layer (memory, skills, sub-agents, goal, automations)."""
+
+    def __init__(self, config: RunConfig) -> None:
+        self.config = config
+        self.memory = StateStore(config.state_dir)
+        self.skills = SkillLoader(config.cwd, config.state_dir)
+        self.agents_dir = config.state_dir / "agents"
+        self.agent_specs = load_agent_specs(self.agents_dir)
+
+    def _system_prompt(self, *, skill: str | None = None, agent: str | None = None) -> str | None:
+        parts: list[str] = []
+        if skill:
+            parts.append(self.skills.load_skill(skill))
+        if agent and agent in self.agent_specs:
+            spec_prompt = self.agent_specs[agent].system_prompt.strip()
+            if spec_prompt:
+                parts.append(spec_prompt)
+        if not parts:
+            return self.skills.default_system_prompt()
+        return "\n\n".join(parts)
+
+    async def run(
+        self,
+        prompt: str,
+        *,
+        skill: str | None = None,
+        agent: str | None = None,
+        on_event: Callable[[LoopEvent], None] | None = None,
+    ) -> tuple[Terminal, str]:
+        config = self.config
+        system_prompt = self._system_prompt(skill=skill, agent=agent)
+
+        if agent and agent in self.agent_specs:
+            config, agent_prompt, _tools = merge_run_config(config, self.agent_specs[agent])
+            if agent_prompt:
+                system_prompt = "\n\n".join(filter(None, [system_prompt, agent_prompt]))
+
+        state_context = self.memory.format_markdown()
+        enriched_prompt = f"{prompt}\n\n--- project state ---\n{state_context}"
+
+        terminal, journal = await execute_run(
+            enriched_prompt,
+            config=config,
+            system_prompt=system_prompt,
+            on_event=on_event,
+        )
+        passed = terminal.kind.value == "completed"
+        summary = terminal.content or terminal.error or prompt[:200]
+        self.memory.record_run(run_id=journal.run_id, summary=summary, passed=passed)
+        return terminal, journal.run_id
+
+    async def run_goal(
+        self,
+        *,
+        condition: str,
+        prompt: str,
+        skill: str | None = None,
+        agent: str | None = None,
+        max_rounds: int = 10,
+        on_event: Callable[[LoopEvent], None] | None = None,
+    ) -> tuple[Terminal, list[GoalEvaluation]]:
+        config = self.config
+        system_prompt = self._system_prompt(skill=skill, agent=agent)
+        if agent and agent in self.agent_specs:
+            config, agent_prompt, _ = merge_run_config(config, self.agent_specs[agent])
+            if agent_prompt:
+                system_prompt = "\n\n".join(filter(None, [system_prompt, agent_prompt]))
+
+        runner = GoalRunner(config=config)
+        terminal, evaluations = await runner.run_until_goal(
+            condition=condition,
+            prompt=prompt,
+            system_prompt=system_prompt,
+            max_rounds=max_rounds,
+            on_event=on_event,
+        )
+        return terminal, evaluations
+
+    async def automation(
+        self,
+        prompt: str,
+        *,
+        every: str,
+        skill: str | None = None,
+        once: bool = False,
+        on_event: Callable[[LoopEvent], None] | None = None,
+    ) -> AutomationResult:
+        async def _task() -> None:
+            terminal, run_id = await self.run(prompt, skill=skill, on_event=on_event)
+            if terminal.kind.value != "completed":
+                self.memory.add_triage(
+                    f"Automation run needs review ({run_id})",
+                    detail=terminal.error or terminal.content or "",
+                )
+
+        return await run_interval(every=every, task=_task, once=once)
+
+    def triage_pending(self) -> list[TriageItem]:
+        return [item for item in self.memory.load_triage() if item.status == "pending"]
+
+    def state_markdown(self) -> str:
+        return self.memory.format_markdown()

agentic_loop/orchestration/subagents.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class SubAgentSpec:
+    name: str
+    description: str = ""
+    system_prompt: str = ""
+    model: str | None = None
+    allow_bash: bool | None = None
+    tools: list[str] | None = None
+    max_turns: int | None = None
+
+
+def load_agent_specs(agents_dir: Path) -> dict[str, SubAgentSpec]:
+    if not agents_dir.exists():
+        return {}
+
+    specs: dict[str, SubAgentSpec] = {}
+    for path in sorted(agents_dir.glob("*.toml")):
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+        name = str(data.get("name") or path.stem)
+        specs[name] = SubAgentSpec(
+            name=name,
+            description=str(data.get("description", "")),
+            system_prompt=str(data.get("system_prompt", "")),
+            model=data.get("model"),
+            allow_bash=data.get("allow_bash"),
+            tools=list(data["tools"]) if data.get("tools") else None,
+            max_turns=data.get("max_turns"),
+        )
+    return specs
+
+
+def merge_run_config(base, spec: SubAgentSpec):
+    from agentic_loop.config import RunConfig
+
+    overrides: dict = {}
+    if spec.model:
+        overrides["model"] = spec.model
+    if spec.allow_bash is not None:
+        overrides["allow_bash"] = spec.allow_bash
+    if spec.max_turns is not None:
+        overrides["max_turns"] = spec.max_turns
+
+    merged = RunConfig(
+        cwd=base.cwd,
+        model=overrides.get("model", base.model),
+        evaluator_model=base.evaluator_model,
+        api_key=base.api_key,
+        base_url=base.base_url,
+        max_turns=overrides.get("max_turns", base.max_turns),
+        allow_bash=overrides.get("allow_bash", base.allow_bash),
+        dry_run=base.dry_run,
+        stream=base.stream,
+        max_retries=base.max_retries,
+        tool_timeout=base.tool_timeout,
+        agentic_loop_dir=base.agentic_loop_dir,
+    )
+    return merged, spec.system_prompt or None, spec.tools

agentic_loop/skills/loader.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class SkillLoader:
+    def __init__(self, cwd: Path, state_dir: Path) -> None:
+        self.cwd = cwd
+        self.search_dirs = [
+            state_dir / "skills",
+            cwd / "skills",
+            cwd / ".agentic-loop" / "skills",
+        ]
+
+    def _find_skill_file(self, name: str) -> Path | None:
+        for base in self.search_dirs:
+            direct = base / name / "SKILL.md"
+            if direct.is_file():
+                return direct
+            flat = base / f"{name}.md"
+            if flat.is_file():
+                return flat
+        return None
+
+    def load_skill(self, name: str) -> str:
+        path = self._find_skill_file(name)
+        if not path:
+            raise ValueError(
+                f"Skill '{name}' not found. Expected SKILL.md under one of: "
+                + ", ".join(str(d / name) for d in self.search_dirs)
+            )
+        return path.read_text(encoding="utf-8").strip()
+
+    def list_skills(self) -> list[str]:
+        names: set[str] = set()
+        for base in self.search_dirs:
+            if not base.exists():
+                continue
+            for path in base.rglob("SKILL.md"):
+                names.add(path.parent.name)
+            for path in base.glob("*.md"):
+                names.add(path.stem)
+        return sorted(names)
+
+    def default_system_prompt(self) -> str | None:
+        parts: list[str] = []
+        for name in self.list_skills():
+            try:
+                parts.append(self.load_skill(name))
+            except ValueError:
+                continue
+        return "\n\n".join(parts) if parts else None

agentic_loop/state.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Literal
+
+TransitionReason = Literal[
+    "next_turn",
+    "max_output_tokens_recovery",
+    "stop_hook_blocking",
+]
+
+
+@dataclass(frozen=True)
+class LoopState:
+    messages: list[dict[str, Any]]
+    turn_count: int = 0
+    transition: TransitionReason | None = None
+
+    def with_messages(self, messages: list[dict[str, Any]]) -> LoopState:
+        return replace(self, messages=list(messages))
+
+    def next_turn(self, messages: list[dict[str, Any]], reason: TransitionReason = "next_turn") -> LoopState:
+        return replace(
+            self,
+            messages=list(messages),
+            turn_count=self.turn_count + 1,
+            transition=reason,
+        )

agentic_loop/terminal.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TerminalKind(str, Enum):
+    COMPLETED = "completed"
+    MAX_TURNS = "max_turns"
+    ERROR = "error"
+    ABORTED = "aborted"
+    MODEL_ERROR = "model_error"
+
+
+class Terminal(BaseModel):
+    kind: TerminalKind
+    content: str | None = None
+    error: str | None = None
+    turns: int = 0
+
+    @classmethod
+    def completed(cls, content: str | None, *, turns: int) -> Terminal:
+        return cls(kind=TerminalKind.COMPLETED, content=content, turns=turns)
+
+    @classmethod
+    def max_turns(cls, *, turns: int, last_content: str | None = None) -> Terminal:
+        return cls(
+            kind=TerminalKind.MAX_TURNS,
+            content=last_content,
+            turns=turns,
+            error=f"Reached max turns ({turns})",
+        )
+
+    @classmethod
+    def failed(cls, message: str, *, turns: int = 0) -> Terminal:
+        return cls(kind=TerminalKind.ERROR, error=message, turns=turns)
+
+    @classmethod
+    def aborted(cls, *, turns: int) -> Terminal:
+        return cls(kind=TerminalKind.ABORTED, turns=turns, error="Run aborted")
+
+    @classmethod
+    def model_error(cls, message: str, *, turns: int) -> Terminal:
+        return cls(kind=TerminalKind.MODEL_ERROR, error=message, turns=turns)
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(exclude_none=True)
+
+    @property
+    def exit_code(self) -> int:
+        if self.kind == TerminalKind.COMPLETED:
+            return 0
+        return 1

agentic_loop/tools/__init__.py

@@ -0,0 +1,3 @@
+from agentic_loop.tools.registry import ToolRegistry, build_default_registry
+
+__all__ = ["ToolRegistry", "build_default_registry"]

agentic_loop/tools/builtin.py

@@ -0,0 +1,3 @@
+from agentic_loop.tools.registry import build_default_registry
+
+__all__ = ["build_default_registry"]

agentic_loop/tools/mcp_bridge.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agentic_loop.connectors.mcp import MCPConnector, MCPServerConfig
+from agentic_loop.tools.registry import ToolRegistry
+
+
+async def register_mcp_tools(
+    registry: ToolRegistry,
+    connector: MCPConnector,
+    *,
+    prefix: str = "mcp",
+) -> list[str]:
+    """Register MCP server tools into a ToolRegistry with optional name prefix."""
+    tools = await connector.list_tools()
+    registered: list[str] = []
+
+    for spec in tools:
+        name = spec["name"]
+        tool_name = f"{prefix}_{name}" if prefix else name
+        schema = spec.get("inputSchema") or {"type": "object", "properties": {}}
+
+        async def handler(args: dict[str, Any], *, _tool=name) -> str:
+            result = await connector.call_tool(_tool, args)
+            return result.message if result.ok else f"Error: {result.message}"
+
+        registry.register(
+            tool_name,
+            spec.get("description") or f"MCP tool {name}",
+            schema,
+            handler,
+        )
+        registered.append(tool_name)
+
+    return registered