agentic-loop 0.3.0__py3-none-any.whl

agentic_loop/llm/client.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: str
+
+
+@dataclass
+class LLMResponse:
+    content: str | None
+    tool_calls: list[ToolCall]
+    raw_message: dict[str, Any]
+    finish_reason: str | None = None
+
+
+@dataclass
+class StreamChunk:
+    kind: str
+    text: str = ""
+    response: LLMResponse | None = None
+
+
+@runtime_checkable
+class LLMClient(Protocol):
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> LLMResponse: ...
+
+    def stream_chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[StreamChunk]: ...

agentic_loop/llm/openai_compat.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+from openai import AsyncOpenAI
+
+from agentic_loop.llm.client import LLMResponse, StreamChunk, ToolCall
+from agentic_loop.llm.retry import with_retry
+
+
+def parse_tool_arguments(arguments: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(arguments or "{}")
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid tool arguments JSON: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise ValueError("Tool arguments must be a JSON object")
+    return parsed
+
+
+def _build_raw_message(content: str | None, tool_calls: list[ToolCall]) -> dict[str, Any]:
+    raw: dict[str, Any] = {"role": "assistant", "content": content}
+    if tool_calls:
+        raw["tool_calls"] = [
+            {
+                "id": tc.id,
+                "type": "function",
+                "function": {"name": tc.name, "arguments": tc.arguments},
+            }
+            for tc in tool_calls
+        ]
+    return raw
+
+
+def _parse_tool_calls(message_tool_calls: Any) -> list[ToolCall]:
+    tool_calls: list[ToolCall] = []
+    if not message_tool_calls:
+        return tool_calls
+    for call in message_tool_calls:
+        tool_calls.append(
+            ToolCall(
+                id=call.id,
+                name=call.function.name,
+                arguments=call.function.arguments or "{}",
+            )
+        )
+    return tool_calls
+
+
+class OpenAICompatClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        model: str,
+        timeout: float = 120.0,
+        max_retries: int = 3,
+    ) -> None:
+        self.model = model
+        self.max_retries = max_retries
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def _request_kwargs(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None,
+        stream: bool,
+    ) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+            "stream": stream,
+        }
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+        return kwargs
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> LLMResponse:
+        async def _call() -> LLMResponse:
+            completion = await self._client.chat.completions.create(
+                **self._request_kwargs(messages, tools=tools, stream=False)
+            )
+            message = completion.choices[0].message
+            tool_calls = _parse_tool_calls(message.tool_calls)
+            return LLMResponse(
+                content=message.content,
+                tool_calls=tool_calls,
+                raw_message=_build_raw_message(message.content, tool_calls),
+                finish_reason=completion.choices[0].finish_reason,
+            )
+
+        return await with_retry(_call, max_retries=self.max_retries)
+
+    async def stream_chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        async def _create_stream():
+            return await self._client.chat.completions.create(
+                **self._request_kwargs(messages, tools=tools, stream=True)
+            )
+
+        stream = await with_retry(_create_stream, max_retries=self.max_retries)
+
+        content_parts: list[str] = []
+        tool_calls_by_index: dict[int, dict[str, str]] = {}
+        finish_reason: str | None = None
+
+        async for chunk in stream:
+            if not chunk.choices:
+                continue
+            choice = chunk.choices[0]
+            finish_reason = choice.finish_reason or finish_reason
+            delta = choice.delta
+
+            if delta.content:
+                content_parts.append(delta.content)
+                yield StreamChunk(kind="text_delta", text=delta.content)
+
+            if delta.tool_calls:
+                for tool_delta in delta.tool_calls:
+                    idx = tool_delta.index
+                    entry = tool_calls_by_index.setdefault(
+                        idx,
+                        {"id": "", "name": "", "arguments": ""},
+                    )
+                    if tool_delta.id:
+                        entry["id"] = tool_delta.id
+                    if tool_delta.function:
+                        if tool_delta.function.name:
+                            entry["name"] = tool_delta.function.name
+                        if tool_delta.function.arguments:
+                            entry["arguments"] += tool_delta.function.arguments
+
+        tool_calls = [
+            ToolCall(
+                id=entry["id"] or f"call_{index}",
+                name=entry["name"],
+                arguments=entry["arguments"] or "{}",
+            )
+            for index, entry in sorted(tool_calls_by_index.items())
+            if entry["name"]
+        ]
+        content = "".join(content_parts) or None
+        response = LLMResponse(
+            content=content,
+            tool_calls=tool_calls,
+            raw_message=_build_raw_message(content, tool_calls),
+            finish_reason=finish_reason,
+        )
+        yield StreamChunk(kind="done", response=response)

agentic_loop/llm/retry.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from openai import APIStatusError, APITimeoutError, RateLimitError
+
+T = TypeVar("T")
+
+RETRYABLE_EXCEPTIONS = (RateLimitError, APITimeoutError, APIStatusError)
+
+
+def _is_retryable(exc: Exception) -> bool:
+    if isinstance(exc, RateLimitError | APITimeoutError):
+        return True
+    if isinstance(exc, APIStatusError) and exc.status_code >= 500:
+        return True
+    return False
+
+
+async def with_retry(
+    operation: Callable[[], Awaitable[T]],
+    *,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+) -> T:
+    delay = base_delay
+    last_exc: Exception | None = None
+    for attempt in range(max_retries):
+        try:
+            return await operation()
+        except RETRYABLE_EXCEPTIONS as exc:
+            last_exc = exc
+            if not _is_retryable(exc) or attempt >= max_retries - 1:
+                raise
+            await asyncio.sleep(delay)
+            delay *= 2
+    if last_exc:
+        raise last_exc
+    raise RuntimeError("with_retry exhausted without result")

agentic_loop/loop.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from agentic_loop.llm.client import LLMClient, LLMResponse, ToolCall
+from agentic_loop.observability.journal import RunJournal
+from agentic_loop.state import LoopState
+from agentic_loop.terminal import Terminal, TerminalKind
+from agentic_loop.tools.registry import ToolRegistry
+
+TRUNCATION_NUDGE = (
+    "Your previous response was truncated due to output length limits. "
+    "Continue directly from where you stopped. Do not repeat earlier content."
+)
+
+
+@dataclass
+class LoopEvent:
+    kind: str
+    data: dict[str, Any]
+
+
+@runtime_checkable
+class AbortSignal(Protocol):
+    def is_set(self) -> bool: ...
+
+
+def _tool_result_message(call: ToolCall, content: str) -> dict[str, Any]:
+    return {
+        "role": "tool",
+        "tool_call_id": call.id,
+        "content": content,
+    }
+
+
+def terminal_from_event(data: dict[str, Any]) -> Terminal:
+    return Terminal(
+        kind=TerminalKind(data["kind"]),
+        content=data.get("content"),
+        error=data.get("error"),
+        turns=data.get("turns", 0),
+    )
+
+
+async def _call_llm(
+    llm: LLMClient,
+    messages: list[dict[str, Any]],
+    *,
+    tools: ToolRegistry,
+    stream: bool,
+) -> tuple[LLMResponse, list[str]]:
+    deltas: list[str] = []
+    if stream and hasattr(llm, "stream_chat"):
+        response: LLMResponse | None = None
+        async for chunk in llm.stream_chat(messages, tools=tools.schemas()):
+            if chunk.kind == "text_delta" and chunk.text:
+                deltas.append(chunk.text)
+            elif chunk.kind == "done" and chunk.response:
+                response = chunk.response
+        if response is None:
+            raise RuntimeError("Stream ended without a final response")
+        return response, deltas
+
+    response = await llm.chat(messages, tools=tools.schemas())
+    if response.content:
+        deltas.append(response.content)
+    return response, deltas
+
+
+async def _execute_tools_parallel(
+    calls: list[ToolCall],
+    *,
+    tools: ToolRegistry,
+    turn: int,
+    journal: RunJournal | None,
+    abort: AbortSignal | None,
+    tool_timeout: float,
+) -> list[tuple[ToolCall, str]] | Terminal:
+    async def _one(call: ToolCall) -> tuple[ToolCall, str]:
+        started = time.perf_counter()
+        try:
+            result = await asyncio.wait_for(
+                tools.execute(call.name, call.arguments),
+                timeout=tool_timeout,
+            )
+        except asyncio.TimeoutError:
+            result = f"Error: tool '{call.name}' timed out after {tool_timeout}s"
+        duration_ms = (time.perf_counter() - started) * 1000
+        if journal:
+            journal.tool_result(
+                turn=turn,
+                name=call.name,
+                duration_ms=duration_ms,
+                preview=result,
+            )
+        return call, result
+
+    if abort and abort.is_set():
+        return Terminal.aborted(turns=turn)
+
+    return await asyncio.gather(*[_one(call) for call in calls])
+
+
+async def query_loop(
+    messages: list[dict[str, Any]],
+    *,
+    tools: ToolRegistry,
+    llm: LLMClient,
+    max_turns: int = 20,
+    journal: RunJournal | None = None,
+    abort: AbortSignal | None = None,
+    stream: bool = True,
+    tool_timeout: float = 120.0,
+    max_truncation_retries: int = 2,
+) -> AsyncIterator[LoopEvent]:
+    state = LoopState(messages=list(messages))
+
+    for turn in range(1, max_turns + 1):
+        if abort and abort.is_set():
+            yield LoopEvent(kind="terminal", data=Terminal.aborted(turns=turn - 1).to_dict())
+            return
+
+        yield LoopEvent(kind="turn_start", data={"turn": turn})
+
+        truncation_attempts = 0
+        while True:
+            try:
+                response, deltas = await _call_llm(
+                    llm,
+                    state.messages,
+                    tools=tools,
+                    stream=stream,
+                )
+            except Exception as exc:  # noqa: BLE001
+                yield LoopEvent(
+                    kind="terminal",
+                    data=Terminal.model_error(str(exc), turns=turn - 1).to_dict(),
+                )
+                return
+
+            for delta in deltas:
+                if stream and delta:
+                    yield LoopEvent(kind="assistant_delta", data={"turn": turn, "text": delta})
+
+            if response.finish_reason == "length" and truncation_attempts < max_truncation_retries:
+                truncation_attempts += 1
+                state = state.with_messages(
+                    [
+                        *state.messages,
+                        {"role": "system", "content": TRUNCATION_NUDGE},
+                    ]
+                )
+                continue
+            break
+
+        state = state.with_messages([*state.messages, response.raw_message])
+
+        if not response.tool_calls:
+            if journal:
+                journal.turn(turn=turn, tool_names=[])
+            terminal = Terminal.completed(response.content, turns=turn)
+            yield LoopEvent(kind="terminal", data=terminal.to_dict())
+            return
+
+        tool_names = [call.name for call in response.tool_calls]
+        if journal:
+            journal.turn(turn=turn, tool_names=tool_names)
+
+        tool_outcome = await _execute_tools_parallel(
+            response.tool_calls,
+            tools=tools,
+            turn=turn,
+            journal=journal,
+            abort=abort,
+            tool_timeout=tool_timeout,
+        )
+        if isinstance(tool_outcome, Terminal):
+            yield LoopEvent(kind="terminal", data=tool_outcome.to_dict())
+            return
+
+        for call, result in tool_outcome:
+            yield LoopEvent(
+                kind="tool_result",
+                data={"turn": turn, "tool": call.name, "preview": result[:500]},
+            )
+            state = state.with_messages([*state.messages, _tool_result_message(call, result)])
+
+        state = state.next_turn(state.messages)
+
+    last_content = None
+    for msg in reversed(state.messages):
+        if msg.get("role") == "assistant" and msg.get("content"):
+            last_content = msg["content"]
+            break
+    yield LoopEvent(
+        kind="terminal",
+        data=Terminal.max_turns(turns=max_turns, last_content=last_content).to_dict(),
+    )
+
+
+async def run_loop(
+    messages: list[dict[str, Any]],
+    *,
+    tools: ToolRegistry,
+    llm: LLMClient,
+    max_turns: int = 20,
+    journal: RunJournal | None = None,
+    abort: AbortSignal | None = None,
+    stream: bool = False,
+    tool_timeout: float = 120.0,
+) -> Terminal:
+    async for event in query_loop(
+        messages,
+        tools=tools,
+        llm=llm,
+        max_turns=max_turns,
+        journal=journal,
+        abort=abort,
+        stream=stream,
+        tool_timeout=tool_timeout,
+    ):
+        if event.kind == "terminal":
+            return terminal_from_event(event.data)
+    return Terminal.failed("Loop ended without terminal event", turns=0)

agentic_loop/observability/journal.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+class RunJournal:
+    def __init__(self, runs_dir: Path, run_id: str | None = None) -> None:
+        self.run_id = run_id or uuid.uuid4().hex[:12]
+        self.runs_dir = runs_dir
+        self.path = runs_dir / f"{self.run_id}.jsonl"
+        self.runs_dir.mkdir(parents=True, exist_ok=True)
+
+    def _write(self, event: dict[str, Any]) -> None:
+        event = {"ts": datetime.now(timezone.utc).isoformat(), **event}
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, ensure_ascii=False) + "\n")
+
+    def started(self, *, prompt: str, config: dict[str, Any]) -> None:
+        self._write({"event": "run_started", "prompt": prompt, "config": config})
+
+    def turn(self, *, turn: int, tool_names: list[str]) -> None:
+        self._write({"event": "turn", "turn": turn, "tools": tool_names})
+
+    def tool_result(self, *, turn: int, name: str, duration_ms: float, preview: str) -> None:
+        self._write(
+            {
+                "event": "tool_result",
+                "turn": turn,
+                "tool": name,
+                "duration_ms": round(duration_ms, 2),
+                "preview": preview[:500],
+            }
+        )
+
+    def finished(self, *, terminal: dict[str, Any], duration_ms: float) -> None:
+        self._write(
+            {
+                "event": "run_finished",
+                "terminal": terminal,
+                "duration_ms": round(duration_ms, 2),
+            }
+        )

agentic_loop/orchestration/automations.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import asyncio
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+_INTERVAL_RE = re.compile(r"^(\d+)(s|m|h|d)$", re.IGNORECASE)
+
+
+def parse_interval(value: str) -> float:
+    """Parse interval like 30s, 5m, 2h into seconds."""
+    match = _INTERVAL_RE.match(value.strip())
+    if not match:
+        raise ValueError(
+            f"Invalid interval '{value}'. Use formats like 30s, 5m, 2h, 1d.\n"
+            "Example: agentic-loop loop --every 5m \"triage open issues\""
+        )
+    amount = int(match.group(1))
+    unit = match.group(2).lower()
+    multipliers = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+    return float(amount * multipliers[unit])
+
+
+@dataclass
+class AutomationResult:
+    runs: int
+    last_error: str | None = None
+
+
+async def run_interval(
+    *,
+    every: str,
+    task: Callable[[], Awaitable[Any]],
+    once: bool = False,
+    max_runs: int | None = None,
+) -> AutomationResult:
+    seconds = parse_interval(every)
+    runs = 0
+    last_error: str | None = None
+
+    while True:
+        try:
+            await task()
+        except Exception as exc:  # noqa: BLE001
+            last_error = str(exc)
+        runs += 1
+        if once or (max_runs is not None and runs >= max_runs):
+            break
+        await asyncio.sleep(seconds)
+
+    return AutomationResult(runs=runs, last_error=last_error)

agentic_loop/orchestration/goal.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agentic_loop.config import RunConfig
+from agentic_loop.llm.openai_compat import OpenAICompatClient
+from agentic_loop.terminal import Terminal
+
+
+@dataclass
+class GoalEvaluation:
+    satisfied: bool
+    reason: str
+
+
+EVALUATOR_SYSTEM = """You are an independent goal evaluator for an agent loop.
+You do NOT execute tools. You judge whether a stopping condition is satisfied based on:
+1) the goal condition text, and
+2) the worker agent's final response and run summary.
+
+Reply with JSON only: {"satisfied": true|false, "reason": "..."}"""
+
+
+class GoalRunner:
+    def __init__(self, *, config: RunConfig) -> None:
+        self.config = config
+
+    async def evaluate(self, *, condition: str, worker_result: str, turns: int) -> GoalEvaluation:
+        if self.config.dry_run:
+            return GoalEvaluation(satisfied=True, reason="[dry-run] goal assumed satisfied")
+
+        self.config.require_api_key()
+        client = OpenAICompatClient(
+            api_key=self.config.api_key or "",
+            base_url=self.config.base_url,
+            model=self.config.effective_evaluator_model,
+            max_retries=self.config.max_retries,
+        )
+        user_content = (
+            f"Goal condition:\n{condition}\n\n"
+            f"Worker turns: {turns}\n\n"
+            f"Worker final output:\n{worker_result}\n\n"
+            "Is the goal condition satisfied?"
+        )
+        response = await client.chat(
+            [
+                {"role": "system", "content": EVALUATOR_SYSTEM},
+                {"role": "user", "content": user_content},
+            ]
+        )
+        text = (response.content or "").strip()
+        match = re.search(r"\{.*\}", text, re.DOTALL)
+        if match:
+            try:
+                data = json.loads(match.group(0))
+                return GoalEvaluation(
+                    satisfied=bool(data.get("satisfied")),
+                    reason=str(data.get("reason", "")),
+                )
+            except json.JSONDecodeError:
+                pass
+        lowered = text.lower()
+        satisfied = any(word in lowered for word in ("true", "satisfied", "yes", "complete", "passed"))
+        return GoalEvaluation(satisfied=satisfied, reason=text[:500] or "Could not parse evaluator output")
+
+    async def run_until_goal(
+        self,
+        *,
+        condition: str,
+        prompt: str,
+        system_prompt: str | None = None,
+        max_rounds: int = 10,
+        on_event=None,
+    ) -> tuple[Terminal, list[GoalEvaluation]]:
+        from agentic_loop.api import execute_run
+
+        evaluations: list[GoalEvaluation] = []
+        last_terminal: Terminal | None = None
+
+        for round_idx in range(1, max_rounds + 1):
+            round_prompt = prompt
+            if round_idx > 1 and last_terminal and last_terminal.content:
+                round_prompt = (
+                    f"{prompt}\n\nPrevious attempt summary:\n{last_terminal.content}\n"
+                    f"Continue working toward the goal."
+                )
+
+            terminal, _journal = await execute_run(
+                round_prompt,
+                config=self.config,
+                system_prompt=system_prompt,
+                on_event=on_event,
+            )
+            last_terminal = terminal
+            evaluation = await self.evaluate(
+                condition=condition,
+                worker_result=terminal.content or terminal.error or "",
+                turns=terminal.turns,
+            )
+            evaluations.append(evaluation)
+            if evaluation.satisfied:
+                return Terminal.completed(
+                    f"Goal satisfied after round {round_idx}: {evaluation.reason}\n\n"
+                    f"{terminal.content or ''}",
+                    turns=terminal.turns,
+                ), evaluations
+
+        return Terminal.failed(
+            f"Goal not satisfied after {max_rounds} rounds. Last reason: {evaluations[-1].reason if evaluations else 'none'}",
+            turns=last_terminal.turns if last_terminal else 0,
+        ), evaluations