agentic-loop 0.3.0__py3-none-any.whl

agentic_loop/__init__.py

@@ -0,0 +1,31 @@
+"""Agentic Loop — lightweight Loop Engineering orchestrator."""
+
+from agentic_loop.api import execute_run, iter_run
+from agentic_loop.config import RunConfig
+from agentic_loop.connectors.base import ConnectorRegistry, ConnectorResult
+from agentic_loop.connectors.mcp import MCPConnector, MCPServerConfig
+from agentic_loop.loop import query_loop, run_loop
+from agentic_loop.orchestration.orchestrator import Orchestrator
+from agentic_loop.terminal import Terminal, TerminalKind
+from agentic_loop.tools.mcp_bridge import register_mcp_tools
+from agentic_loop.tools.registry import ToolRegistry, build_default_registry
+
+__all__ = [
+    "ConnectorRegistry",
+    "ConnectorResult",
+    "MCPConnector",
+    "MCPServerConfig",
+    "Orchestrator",
+    "RunConfig",
+    "Terminal",
+    "TerminalKind",
+    "ToolRegistry",
+    "build_default_registry",
+    "execute_run",
+    "iter_run",
+    "query_loop",
+    "register_mcp_tools",
+    "run_loop",
+]
+
+__version__ = "0.3.0"

agentic_loop/abort.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import asyncio
+
+
+class AbortController:
+    """Cooperative cancellation signal checked between loop steps."""
+
+    def __init__(self) -> None:
+        self._event = asyncio.Event()
+
+    def abort(self) -> None:
+        self._event.set()
+
+    def is_set(self) -> bool:
+        return self._event.is_set()
+
+    def clear(self) -> None:
+        self._event.clear()

agentic_loop/api.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+
+from agentic_loop.config import RunConfig
+from agentic_loop.llm.openai_compat import OpenAICompatClient
+from agentic_loop.loop import LoopEvent, query_loop, terminal_from_event
+from agentic_loop.observability.journal import RunJournal
+from agentic_loop.terminal import Terminal
+from agentic_loop.tools.registry import build_default_registry
+
+
+async def execute_run(
+    prompt: str,
+    *,
+    config: RunConfig,
+    system_prompt: str | None = None,
+    on_event: Callable[[LoopEvent], None] | None = None,
+) -> tuple[Terminal, RunJournal]:
+    if config.dry_run:
+        journal = RunJournal(config.runs_dir, run_id="dry-run")
+        terminal = Terminal.completed(
+            f"[dry-run] Would run with model={config.model}, tools={build_default_registry(cwd=config.cwd, allow_bash=config.allow_bash).list_names()}, stream={config.stream}",
+            turns=0,
+        )
+        return terminal, journal
+
+    config.require_api_key()
+    journal = RunJournal(config.runs_dir)
+    started = time.perf_counter()
+
+    journal.started(
+        prompt=prompt,
+        config={
+            "model": config.model,
+            "cwd": str(config.cwd),
+            "max_turns": config.max_turns,
+            "allow_bash": config.allow_bash,
+            "stream": config.stream,
+        },
+    )
+
+    messages: list[dict[str, Any]] = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    llm = OpenAICompatClient(
+        api_key=config.api_key or "",
+        base_url=config.base_url,
+        model=config.model,
+        max_retries=config.max_retries,
+    )
+    tools = build_default_registry(cwd=config.cwd, allow_bash=config.allow_bash)
+
+    terminal: Terminal | None = None
+    async for event in query_loop(
+        messages,
+        tools=tools,
+        llm=llm,
+        max_turns=config.max_turns,
+        journal=journal,
+        stream=config.stream,
+        tool_timeout=config.tool_timeout,
+    ):
+        if on_event:
+            on_event(event)
+        if event.kind == "terminal":
+            terminal = terminal_from_event(event.data)
+
+    if terminal is None:
+        terminal = Terminal.failed("Run ended without terminal event", turns=0)
+
+    journal.finished(
+        terminal=terminal.to_dict(),
+        duration_ms=(time.perf_counter() - started) * 1000,
+    )
+    return terminal, journal
+
+
+async def iter_run(
+    prompt: str,
+    *,
+    config: RunConfig,
+    system_prompt: str | None = None,
+) -> AsyncIterator[LoopEvent]:
+    """Public API: stream loop events for integrations."""
+    if config.dry_run:
+        yield LoopEvent(
+            kind="terminal",
+            data=Terminal.completed("[dry-run]", turns=0).to_dict(),
+        )
+        return
+
+    config.require_api_key()
+    messages: list[dict[str, Any]] = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    llm = OpenAICompatClient(
+        api_key=config.api_key or "",
+        base_url=config.base_url,
+        model=config.model,
+        max_retries=config.max_retries,
+    )
+    tools = build_default_registry(cwd=config.cwd, allow_bash=config.allow_bash)
+
+    async for event in query_loop(
+        messages,
+        tools=tools,
+        llm=llm,
+        max_turns=config.max_turns,
+        stream=config.stream,
+        tool_timeout=config.tool_timeout,
+    ):
+        yield event

agentic_loop/cli.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from agentic_loop.abort import AbortController
+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 parse_interval
+from agentic_loop.orchestration.orchestrator import Orchestrator
+
+RUN_EPILOG = """
+Examples:
+  agentic-loop run "List Python files" --dry-run
+  agentic-loop run "Find TODO comments" --max-turns 10
+  agentic-loop run "Explain README" --no-stream
+"""
+
+LOOP_EPILOG = """
+Examples:
+  agentic-loop loop --every 5m "Triage open issues" --once
+  agentic-loop loop --every 30s "Check deploy" --skill triage --dry-run
+"""
+
+GOAL_EPILOG = """
+Examples:
+  agentic-loop goal "pytest tests/ passes" "Fix failing tests" --max-rounds 5
+  agentic-loop goal "lint is clean" "Run linter and fix issues" --dry-run
+"""
+
+STATE_EPILOG = """
+Examples:
+  agentic-loop state show
+  agentic-loop state reset
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentic-loop",
+        description="Lightweight Loop Engineering orchestrator",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="Single agent run", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=RUN_EPILOG)
+    run.add_argument("prompt")
+    _add_common_run_flags(run)
+
+    loop = sub.add_parser("loop", help="Scheduled automation", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=LOOP_EPILOG)
+    loop.add_argument("prompt")
+    loop.add_argument("--every", required=True, help="Interval: 30s, 5m, 2h, 1d")
+    loop.add_argument("--once", action="store_true", help="Run once instead of forever")
+    _add_common_run_flags(loop)
+
+    goal = sub.add_parser("goal", help="Run until goal condition passes", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=GOAL_EPILOG)
+    goal.add_argument("condition", help="Verifiable stopping condition")
+    goal.add_argument("prompt", help="Worker task prompt")
+    goal.add_argument("--max-rounds", type=int, default=10)
+    _add_common_run_flags(goal)
+
+    state = sub.add_parser("state", help="Project memory", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=STATE_EPILOG)
+    state_sub = state.add_subparsers(dest="state_cmd", required=True)
+    state_show = state_sub.add_parser("show", help="Print state markdown")
+    state_show.add_argument("--cwd", type=Path, default=Path.cwd())
+    state_show.add_argument("--json", action="store_true")
+    state_reset = state_sub.add_parser("reset", help="Clear state and triage")
+    state_reset.add_argument("--cwd", type=Path, default=Path.cwd())
+    state_reset.add_argument("--yes", action="store_true", help="Skip confirmation")
+
+    return parser
+
+
+def _add_common_run_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--cwd", type=Path, default=Path.cwd())
+    parser.add_argument("--max-turns", type=int, default=20)
+    parser.add_argument("--model")
+    parser.add_argument("--api-base", dest="base_url")
+    parser.add_argument("--allow-bash", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--no-stream", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--skill", help="Skill to load into system prompt")
+    parser.add_argument("--agent", help="Sub-agent role")
+
+
+def _print_error(message: str) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+
+
+def _config_from_args(args: argparse.Namespace) -> RunConfig:
+    overrides = {
+        "cwd": args.cwd.resolve(),
+        "max_turns": getattr(args, "max_turns", 20),
+        "allow_bash": getattr(args, "allow_bash", False),
+        "dry_run": getattr(args, "dry_run", False),
+        "stream": not getattr(args, "no_stream", False),
+    }
+    if getattr(args, "model", None):
+        overrides["model"] = args.model
+    if getattr(args, "base_url", None):
+        overrides["base_url"] = args.base_url
+    return RunConfig.from_env(overrides=overrides)
+
+
+def _make_event_handler(*, stream_output: bool, json_mode: bool):
+    streamed_header = False
+
+    def on_event(event: LoopEvent) -> None:
+        nonlocal streamed_header
+        if json_mode:
+            return
+        if event.kind == "turn_start":
+            print(f"\n--- turn {event.data.get('turn')} ---", file=sys.stderr)
+        elif event.kind == "assistant_delta" and stream_output:
+            if not streamed_header:
+                print("\n--- assistant ---", file=sys.stderr)
+                streamed_header = True
+            print(event.data.get("text", ""), end="", flush=True)
+        elif event.kind == "tool_result":
+            print(f"\n[tool:{event.data.get('tool')}]", file=sys.stderr)
+
+    return on_event
+
+
+def _print_terminal(terminal, journal, *, config: RunConfig, json_mode: bool) -> int:
+    if json_mode:
+        print(json.dumps({"run_id": journal.run_id, "terminal": terminal.to_dict()}, ensure_ascii=False, indent=2))
+        return terminal.exit_code
+    if config.stream:
+        print()
+    print(f"run_id: {journal.run_id}")
+    print(f"terminal: {terminal.kind.value}")
+    print(f"turns: {terminal.turns}")
+    if terminal.content:
+        print("\n--- result ---\n")
+        print(terminal.content)
+    if terminal.error and terminal.kind.value != "completed":
+        print(f"\nerror: {terminal.error}", file=sys.stderr)
+    return terminal.exit_code
+
+
+async def _cmd_run(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    on_event = _make_event_handler(stream_output=config.stream, json_mode=args.json)
+    try:
+        if args.skill or args.agent:
+            orch = Orchestrator(config)
+            terminal, run_id = await orch.run(
+                args.prompt,
+                skill=args.skill,
+                agent=args.agent,
+                on_event=on_event,
+            )
+            if args.json:
+                print(json.dumps({"run_id": run_id, "terminal": terminal.to_dict()}, ensure_ascii=False, indent=2))
+                return terminal.exit_code
+            print(f"run_id: {run_id}")
+            print(f"terminal: {terminal.kind.value}")
+            if terminal.content:
+                print(terminal.content)
+            return terminal.exit_code
+
+        terminal, journal = await execute_run(args.prompt, config=config, on_event=on_event)
+    except ValueError as exc:
+        _print_error(str(exc))
+        return 1
+    except KeyboardInterrupt:
+        print("\nAborted.", file=sys.stderr)
+        return 130
+    return _print_terminal(terminal, journal, config=config, json_mode=args.json)
+
+
+async def _cmd_loop(args: argparse.Namespace) -> int:
+    try:
+        parse_interval(args.every)
+    except ValueError as exc:
+        _print_error(str(exc))
+        return 1
+
+    config = _config_from_args(args)
+    orch = Orchestrator(config)
+    on_event = _make_event_handler(stream_output=config.stream, json_mode=args.json)
+
+    if args.dry_run:
+        print(f"[dry-run] Would run every {args.every}: {args.prompt}")
+        return 0
+
+    print(f"Automation started: every {args.every}" + (" (once)" if args.once else ""), file=sys.stderr)
+    try:
+        result = await orch.automation(
+            args.prompt,
+            every=args.every,
+            skill=args.skill,
+            once=args.once,
+            on_event=on_event,
+        )
+    except KeyboardInterrupt:
+        print("\nAutomation stopped.", file=sys.stderr)
+        return 130
+
+    if args.json:
+        print(json.dumps({"runs": result.runs, "last_error": result.last_error}, indent=2))
+    else:
+        print(f"runs: {result.runs}")
+        if result.last_error:
+            print(f"last_error: {result.last_error}", file=sys.stderr)
+    return 0 if not result.last_error else 1
+
+
+async def _cmd_goal(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    orch = Orchestrator(config)
+    on_event = _make_event_handler(stream_output=config.stream, json_mode=args.json)
+    try:
+        terminal, evaluations = await orch.run_goal(
+            condition=args.condition,
+            prompt=args.prompt,
+            skill=args.skill,
+            agent=args.agent,
+            max_rounds=args.max_rounds,
+            on_event=on_event,
+        )
+    except ValueError as exc:
+        _print_error(str(exc))
+        return 1
+    except KeyboardInterrupt:
+        print("\nAborted.", file=sys.stderr)
+        return 130
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "terminal": terminal.to_dict(),
+                    "evaluations": [e.__dict__ for e in evaluations],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        print(f"terminal: {terminal.kind.value}")
+        for idx, ev in enumerate(evaluations, start=1):
+            print(f"round {idx}: satisfied={ev.satisfied} reason={ev.reason}")
+        if terminal.content:
+            print("\n--- result ---\n")
+            print(terminal.content)
+    return terminal.exit_code
+
+
+async def _cmd_state(args: argparse.Namespace) -> int:
+    config = RunConfig.from_env(overrides={"cwd": args.cwd.resolve()})
+    store = Orchestrator(config).memory
+
+    if args.state_cmd == "show":
+        if args.json:
+            print(json.dumps(store.load_state().__dict__, ensure_ascii=False, indent=2))
+        else:
+            print(store.format_markdown())
+        return 0
+
+    if args.state_cmd == "reset":
+        if not args.yes:
+            _print_error("Pass --yes to clear state.json and triage.json")
+            return 1
+        if store.state_path.exists():
+            store.state_path.unlink()
+        if store.triage_path.exists():
+            store.triage_path.unlink()
+        print("State cleared.")
+        return 0
+
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        return asyncio.run(_cmd_run(args))
+    if args.command == "loop":
+        return asyncio.run(_cmd_loop(args))
+    if args.command == "goal":
+        return asyncio.run(_cmd_goal(args))
+    if args.command == "state":
+        return asyncio.run(_cmd_state(args))
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentic_loop/config.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from dotenv import load_dotenv
+
+
+def _find_project_root(start: Path | None = None) -> Path:
+    current = (start or Path.cwd()).resolve()
+    for path in [current, *current.parents]:
+        if (path / "agentic-loop.toml").exists() or (path / "pyproject.toml").exists():
+            return path
+    return current
+
+
+@dataclass
+class RunConfig:
+    cwd: Path = field(default_factory=Path.cwd)
+    model: str = "gpt-4o-mini"
+    evaluator_model: str | None = None
+    api_key: str | None = None
+    base_url: str | None = None
+    max_turns: int = 20
+    allow_bash: bool = False
+    dry_run: bool = False
+    stream: bool = True
+    max_retries: int = 3
+    tool_timeout: float = 120.0
+    agentic_loop_dir: Path | None = None
+
+    @property
+    def state_dir(self) -> Path:
+        base = self.agentic_loop_dir or (self.cwd / ".agentic-loop")
+        return base
+
+    @property
+    def runs_dir(self) -> Path:
+        return self.state_dir / "runs"
+
+    @property
+    def effective_evaluator_model(self) -> str:
+        return self.evaluator_model or self.model
+
+    @classmethod
+    def from_env(cls, *, cwd: Path | None = None, overrides: dict[str, Any] | None = None) -> RunConfig:
+        root = _find_project_root(cwd)
+        load_dotenv(root / ".env")
+        load_dotenv()
+
+        cfg = cls(
+            cwd=(cwd or Path.cwd()).resolve(),
+            model=os.getenv("OPENAI_MODEL") or os.getenv("MODEL") or "gpt-4o-mini",
+            evaluator_model=os.getenv("EVALUATOR_MODEL"),
+            api_key=os.getenv("OPENAI_API_KEY"),
+            base_url=os.getenv("OPENAI_BASE_URL"),
+        )
+        if overrides:
+            for key, value in overrides.items():
+                if value is not None and hasattr(cfg, key):
+                    setattr(cfg, key, value)
+        return cfg
+
+    def require_api_key(self) -> str:
+        if not self.api_key:
+            raise ValueError(
+                "OPENAI_API_KEY is not set.\n"
+                "Copy .env.example to .env and set your key.\n"
+                "Example: agentic-loop run \"hello\" --dry-run  # no API key needed"
+            )
+        return self.api_key

agentic_loop/connectors/base.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Protocol
+
+
+@dataclass
+class ConnectorResult:
+    ok: bool
+    message: str
+    data: dict[str, Any] | None = None
+
+
+class Connector(Protocol):
+    name: str
+
+    async def invoke(self, action: str, **params: Any) -> ConnectorResult: ...
+
+
+ConnectorHandler = Callable[..., Awaitable[ConnectorResult] | ConnectorResult]
+
+
+class ConnectorRegistry:
+    def __init__(self) -> None:
+        self._handlers: dict[str, ConnectorHandler] = {}
+
+    def register(self, name: str, handler: ConnectorHandler) -> None:
+        self._handlers[name] = handler
+
+    async def invoke(self, name: str, action: str, **params: Any) -> ConnectorResult:
+        if name not in self._handlers:
+            return ConnectorResult(ok=False, message=f"Unknown connector '{name}'")
+        result = self._handlers[name](action=action, **params)
+        if hasattr(result, "__await__"):
+            return await result
+        return result
+
+    def list_names(self) -> list[str]:
+        return sorted(self._handlers.keys())

agentic_loop/connectors/mcp.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from agentic_loop.connectors.base import ConnectorResult
+
+
+@dataclass
+class MCPServerConfig:
+    """Stdio MCP server launch configuration."""
+
+    command: str
+    args: list[str]
+    env: dict[str, str] | None = None
+
+
+class MCPConnector:
+    """
+    Minimal MCP client wrapper (stdio transport).
+
+    Requires optional dependency: pip install agentic-loop[mcp]
+    """
+
+    def __init__(self, config: MCPServerConfig) -> None:
+        self.config = config
+        self._session = None
+        self._context = None
+
+    async def __aenter__(self) -> MCPConnector:
+        try:
+            from mcp import ClientSession, StdioServerParameters
+            from mcp.client.stdio import stdio_client
+        except ImportError as exc:
+            raise ImportError(
+                "MCP support requires: pip install agentic-loop[mcp]"
+            ) from exc
+
+        params = StdioServerParameters(
+            command=self.config.command,
+            args=self.config.args,
+            env=self.config.env,
+        )
+        self._context = stdio_client(params)
+        read, write = await self._context.__aenter__()
+        self._session = ClientSession(read, write)
+        await self._session.__aenter__()
+        await self._session.initialize()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        if self._session is not None:
+            await self._session.__aexit__(*args)
+        if self._context is not None:
+            await self._context.__aexit__(*args)
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        assert self._session is not None
+        result = await self._session.list_tools()
+        return [
+            {
+                "name": tool.name,
+                "description": tool.description or "",
+                "inputSchema": tool.inputSchema,
+            }
+            for tool in result.tools
+        ]
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> ConnectorResult:
+        assert self._session is not None
+        try:
+            result = await self._session.call_tool(name, arguments)
+            text_parts = [
+                item.text
+                for item in result.content
+                if hasattr(item, "text") and item.text
+            ]
+            message = "\n".join(text_parts) if text_parts else json.dumps(
+                [item.model_dump() if hasattr(item, "model_dump") else str(item) for item in result.content],
+                ensure_ascii=False,
+            )
+            return ConnectorResult(ok=not result.isError, message=message)
+        except Exception as exc:  # noqa: BLE001
+            return ConnectorResult(ok=False, message=str(exc))
+
+    async def invoke(self, action: str, **params: Any) -> ConnectorResult:
+        if action == "list_tools":
+            tools = await self.list_tools()
+            return ConnectorResult(ok=True, message=f"{len(tools)} tools", data={"tools": tools})
+        if action == "call_tool":
+            name = str(params.get("name", ""))
+            arguments = params.get("arguments") or {}
+            if not name:
+                return ConnectorResult(ok=False, message="Missing tool name")
+            if not isinstance(arguments, dict):
+                return ConnectorResult(ok=False, message="arguments must be an object")
+            return await self.call_tool(name, arguments)
+        return ConnectorResult(ok=False, message=f"Unknown MCP action '{action}'")