tightloop 0.1.0__py3-none-any.whl

loop/__init__.py

@@ -0,0 +1,40 @@
+"""Loop — production-grade loops for AI agents.
+
+A structured runtime for reliable, observable, governable agent loops.
+"""
+from .approval import (
+    ApprovalDecision,
+    ApprovalRequest,
+    CallbackApprovalRunner,
+    CLIApprovalRunner,
+    HeadlessApprovalRunner,
+)
+from .blueprints import PytestFailureMetric, TestFixLoop
+from .core.engine import Loop, LoopConfigError, NestedLoopError
+from .core.result import LoopResult, LoopStatus
+from .core.state import (
+    ArtifactDriftError,
+    MetricSnapshot,
+    SchemaChangedError,
+    State,
+)
+from .exit import Exit, ExitCondition
+from .llm import CallableLLM, LLMClient, LLMResponse, ToolCallReq
+from .policy import CostLimit, NoProgress, Policy, RequireApproval
+from .progress import GoalMetric
+from .tools import Tool, ToolRegistry, UnsupportedTypeError, run_command, tool
+from .trace import explain
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Loop", "LoopResult", "LoopStatus", "State", "MetricSnapshot",
+    "Exit", "ExitCondition", "Policy", "NoProgress", "CostLimit", "RequireApproval",
+    "GoalMetric", "Tool", "tool", "ToolRegistry", "run_command",
+    "LLMClient", "LLMResponse", "ToolCallReq", "CallableLLM",
+    "ApprovalRequest", "ApprovalDecision", "CLIApprovalRunner",
+    "CallbackApprovalRunner", "HeadlessApprovalRunner",
+    "TestFixLoop", "PytestFailureMetric", "explain",
+    "NestedLoopError", "LoopConfigError", "SchemaChangedError",
+    "ArtifactDriftError", "UnsupportedTypeError",
+]

loop/approval/__init__.py

@@ -0,0 +1,87 @@
+"""Human approval checkpoints.
+
+ApprovalRequest is frozen at type level: callbacks get a
+read-only payload — action, args, reason, digests — never the full context.
+Callback runner: 60s timeout, deny-on-exception, every invocation traced by the engine.
+"""
+from __future__ import annotations
+
+import secrets
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeout
+from enum import Enum
+from typing import Any, Callable
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ApprovalDecision(str, Enum):
+    APPROVED = "APPROVED"
+    DENIED = "DENIED"
+    PENDING = "PENDING"  # headless: serialize state, resume by token
+
+
+class ApprovalRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    token: str
+    tool: str
+    args: dict[str, Any]
+    reason: str
+    action_hash: str
+    state_version: int
+    created_at: float
+    ttl_s: float
+
+
+def new_token() -> str:
+    return secrets.token_urlsafe(8)
+
+
+class ApprovalRunner:
+    def request(self, req: ApprovalRequest) -> tuple[ApprovalDecision, str]:
+        raise NotImplementedError
+
+
+class CLIApprovalRunner(ApprovalRunner):
+    """Interactive default: prompts on stdin."""
+
+    def request(self, req: ApprovalRequest) -> tuple[ApprovalDecision, str]:
+        print(f"\n[loop] approval required: {req.tool}({req.args})\nreason: {req.reason}")
+        answer = input("approve? [y/N] ").strip().lower()
+        if answer in ("y", "yes"):
+            return ApprovalDecision.APPROVED, "approved via CLI"
+        return ApprovalDecision.DENIED, "denied via CLI"
+
+
+class CallbackApprovalRunner(ApprovalRunner):
+    def __init__(self, fn: Callable[[ApprovalRequest], bool], timeout_s: float = 60.0):
+        self.fn = fn
+        self.timeout_s = timeout_s
+
+    def request(self, req: ApprovalRequest) -> tuple[ApprovalDecision, str]:
+        executor = ThreadPoolExecutor(max_workers=1)
+        try:
+            future = executor.submit(self.fn, req)
+            try:
+                approved = future.result(timeout=self.timeout_s)
+            except FutureTimeout:
+                return ApprovalDecision.DENIED, f"callback timed out after {self.timeout_s}s (deny-on-timeout)"
+            except Exception as e:
+                return ApprovalDecision.DENIED, f"callback raised {type(e).__name__}: {e} (deny-on-exception)"
+            if approved:
+                return ApprovalDecision.APPROVED, "approved via callback"
+            return ApprovalDecision.DENIED, "denied via callback"
+        finally:
+            executor.shutdown(wait=False)
+
+
+class HeadlessApprovalRunner(ApprovalRunner):
+    """Always returns PENDING: the engine serializes state and exits AWAITING_APPROVAL;
+    resume with Loop.resume(path, approval={'token': ..., 'approved': True})."""
+
+    def __init__(self, ttl_s: float = 3600.0):
+        self.ttl_s = ttl_s
+
+    def request(self, req: ApprovalRequest) -> tuple[ApprovalDecision, str]:
+        return ApprovalDecision.PENDING, f"awaiting approval, token={req.token}"

loop/blueprints/__init__.py

@@ -0,0 +1,3 @@
+from .testfix import PytestFailureMetric, TestFixLoop
+
+__all__ = ["TestFixLoop", "PytestFailureMetric"]

loop/blueprints/testfix.py

@@ -0,0 +1,117 @@
+"""TestFixLoop blueprint: fix failing tests until all pass.
+
+Progress tracks test IDENTITY, not counts: value = originally_failing_fixed −
+newly_broken, and newly-broken tests flag `regression` even when totals improve.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ..core.engine import Loop
+from ..core.state import MetricSnapshot, State
+from ..llm import LLMClient
+from ..progress import GoalMetric
+from ..tools import Tool, run_command
+
+_FAILED_RE = re.compile(r"^(?:FAILED|ERROR)\s+(\S+)", re.MULTILINE)
+_EXIT_RE = re.compile(r"\[exit code: (-?\d+)\]")
+
+
+def parse_failing(output: str) -> set[str]:
+    return {m.split(" - ")[0] for m in _FAILED_RE.findall(output)}
+
+
+class PytestFailureMetric(GoalMetric):
+    def measure(self, observation: str, state: State) -> MetricSnapshot:
+        failing = parse_failing(observation)
+        exit_match = _EXIT_RE.search(observation)
+        exit_code = int(exit_match.group(1)) if exit_match else None
+
+        baseline: set[str] | None = None
+        prev: set[str] | None = None
+        for it in state.iterations:
+            if it.metric and "failing" in it.metric.detail:
+                if baseline is None:
+                    baseline = set(it.metric.detail["baseline"] or it.metric.detail["failing"])
+                prev = set(it.metric.detail["failing"])
+        if baseline is None:
+            baseline = set(failing)
+
+        fixed = baseline - failing
+        newly_broken = failing - baseline
+        regressed_vs_prev = bool(failing - prev) if prev is not None else False
+        return MetricSnapshot(
+            value=float(len(fixed) - len(newly_broken)),
+            regression=bool(newly_broken) or regressed_vs_prev,
+            detail={
+                "failing": sorted(failing),
+                "baseline": sorted(baseline),
+                "fixed": len(fixed),
+                "newly_broken": len(newly_broken),
+                "exit_code": exit_code,
+            },
+        )
+
+    def is_success(self, snapshot: MetricSnapshot) -> bool:
+        return not snapshot.detail.get("failing") and snapshot.detail.get("exit_code") == 0
+
+
+class TestFixLoop(Loop):
+    __test__ = False  # not a pytest test class, despite the name
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        repo: str = ".",
+        test_cmd: str = "python -m pytest -q -rf --tb=short",
+        test_timeout_s: float = 300.0,
+        goal: str | None = None,
+        **kwargs: Any,
+    ):
+        repo_path = Path(repo).resolve()
+
+        def _run_tests() -> str:
+            res = run_command(test_cmd, timeout_s=test_timeout_s, cwd=str(repo_path))
+            suffix = " [timed out]" if res.timed_out else ""
+            return f"{res.stdout}\n{res.stderr}\n[exit code: {res.code}]{suffix}"
+
+        def run_tests() -> str:
+            """Run the test suite and return its output."""
+            return _run_tests()
+
+        def read_file(path: str) -> str:
+            """Read a file from the repository."""
+            target = (repo_path / path).resolve()
+            if not target.is_relative_to(repo_path):
+                raise ValueError(f"path {path!r} escapes the repository")
+            return target.read_text()
+
+        def edit_file(path: str, content: str) -> str:
+            """Replace the full contents of a file in the repository."""
+            target = (repo_path / path).resolve()
+            if not target.is_relative_to(repo_path):
+                raise ValueError(f"path {path!r} escapes the repository")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content)
+            # drop stale bytecode: pyc validation uses whole-second mtime + size,
+            # so a same-size edit within the same second would be masked by the cache
+            cache_dir = target.parent / "__pycache__"
+            if target.suffix == ".py" and cache_dir.is_dir():
+                for pyc in cache_dir.glob(f"{target.stem}.*.pyc"):
+                    pyc.unlink(missing_ok=True)
+            return f"wrote {len(content)} chars to {path}"
+
+        super().__init__(
+            goal=goal or f"Fix failing tests in {repo_path.name} until all pass",
+            tools=[
+                Tool(run_tests, timeout_s=test_timeout_s + 10),
+                Tool(read_file),
+                Tool(edit_file),
+            ],
+            llm=llm,
+            observe=lambda state: _run_tests(),
+            goal_metric=PytestFailureMetric(),
+            **kwargs,
+        )

loop/context/__init__.py

@@ -0,0 +1,144 @@
+"""Context manager: pinned facts never summarized away,
+failed-approaches registry always in context, version-stamped summaries
+computed once and stored (deterministic resume), transparent token accounting.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from ..core.state import (
+    ENGINE_VERSION,
+    ArtifactStamp,
+    ContextArtifact,
+    IterationRecord,
+    State,
+)
+from ..llm import LLMClient
+
+SUMMARY_PROMPT = (
+    "Summarize this agent-loop iteration in 3 sentences or fewer. Preserve: what was "
+    "attempted, the outcome, and any error messages verbatim.\n\n{body}"
+)
+_PROMPT_HASH = hashlib.sha256(SUMMARY_PROMPT.encode()).hexdigest()[:16]
+
+
+def _render_iteration(it: IterationRecord, result_cap: int = 2000) -> str:
+    lines = [f"### Iteration {it.index}"]
+    if it.observation:
+        lines.append(f"Observed:\n{it.observation[:result_cap]}")
+    if it.plan_text:
+        lines.append(f"Planned: {it.plan_text[:600]}")
+    if it.plan_invalid:
+        lines.append("(plan failed tool-argument validation)")
+    for a in it.actions:
+        lines.append(f"Action {a.tool}({a.args_excerpt[:300]}) -> [{a.status}] {a.result_excerpt[:result_cap]}")
+    if it.metric:
+        lines.append(f"Metric: {it.metric.value}" + (" (REGRESSION)" if it.metric.regression else ""))
+    return "\n".join(lines)
+
+
+def _est_tokens(text: str) -> int:
+    return len(text) // 4  # documented heuristic; itemized, not hidden
+
+
+class ContextManager:
+    def __init__(self, verbatim_window: int = 3, summarizer: LLMClient | None = None,
+                 summary_max_tokens: int = 400):
+        self.verbatim_window = verbatim_window
+        self.summarizer = summarizer
+        self.summary_max_tokens = summary_max_tokens
+
+    @property
+    def stamp(self) -> ArtifactStamp:
+        model_id = self.summarizer.model_id if self.summarizer else "deterministic-truncate"
+        return ArtifactStamp(engine_version=ENGINE_VERSION, model_id=model_id, prompt_hash=_PROMPT_HASH)
+
+    def check_artifact_drift(self, state: State) -> list[str]:
+        """Returns mismatch descriptions for artifacts produced under a different config."""
+        current = self.stamp
+        problems = []
+        for a in state.artifacts:
+            if a.kind == "summary" and a.stamp != current:
+                problems.append(
+                    f"summary for iteration {a.iteration}: produced by "
+                    f"{a.stamp.engine_version}/{a.stamp.model_id}, current is "
+                    f"{current.engine_version}/{current.model_id}"
+                )
+        return problems
+
+    def ensure_summaries(self, state: State) -> list[int]:
+        """Summarize iterations that just left the verbatim window. Computed once,
+        stored, reused on resume — never recomputed."""
+        done = {a.iteration for a in state.artifacts if a.kind == "summary"}
+        cutoff = len(state.iterations) - self.verbatim_window
+        created = []
+        for it in state.iterations[:cutoff] if cutoff > 0 else []:
+            if it.index in done:
+                continue
+            body = _render_iteration(it, result_cap=600)
+            if self.summarizer:
+                resp = self.summarizer.complete(
+                    [{"role": "user", "content": SUMMARY_PROMPT.format(body=body)}],
+                    [], self.summary_max_tokens,
+                )
+                content = resp.text
+                state.metrics.input_tokens += resp.input_tokens
+                state.metrics.output_tokens += resp.output_tokens
+                state.metrics.llm_calls += 1
+            else:
+                content = body[:800]  # deterministic fallback
+            state.artifacts.append(
+                ContextArtifact(kind="summary", iteration=it.index, content=content, stamp=self.stamp)
+            )
+            created.append(it.index)
+        return created
+
+    def build(self, state: State, observation: str) -> list[dict[str, str]]:
+        system_parts = [
+            "You are an agent executing one step of a structured loop. Use the provided "
+            "tools to make progress toward the goal. Respond with tool calls.",
+            f"Goal: {state.goal}",
+        ]
+        if state.pinned_facts:
+            system_parts.append("Key facts (pinned):\n" + "\n".join(f"- {f}" for f in state.pinned_facts))
+        if state.failed_approaches:
+            system_parts.append(
+                "Approaches already tried that FAILED (do not repeat):\n"
+                + "\n".join(f"- {f}" for f in state.failed_approaches)
+            )
+
+        user_parts = []
+        summaries = [a for a in state.artifacts if a.kind == "summary"]
+        if summaries:
+            user_parts.append(
+                "## Earlier iterations (summarized)\n"
+                + "\n".join(f"- iter {a.iteration}: {a.content}" for a in summaries)
+            )
+        recent = state.iterations[-self.verbatim_window:]
+        if recent:
+            user_parts.append("## Recent iterations\n" + "\n\n".join(_render_iteration(it) for it in recent))
+        user_parts.append(f"## Current observation\n{observation}\n\nDecide the next action(s).")
+
+        return [
+            {"role": "system", "content": "\n\n".join(system_parts)},
+            {"role": "user", "content": "\n\n".join(user_parts)},
+        ]
+
+    def budget_report(self, state: State, observation: str = "") -> dict[str, Any]:
+        """Itemized token accounting per section."""
+        messages = self.build(state, observation)
+        system, user = messages[0]["content"], messages[1]["content"]
+        summaries = [a for a in state.artifacts if a.kind == "summary"]
+        return {
+            "pinned_system_tokens": _est_tokens(system),
+            "summary_tokens": _est_tokens("\n".join(a.content for a in summaries)),
+            "verbatim_tokens": _est_tokens(
+                "\n".join(_render_iteration(it) for it in state.iterations[-self.verbatim_window:])
+            ),
+            "observation_tokens": _est_tokens(observation),
+            "total_context_tokens": _est_tokens(system) + _est_tokens(user),
+            "spent_input_tokens": state.metrics.input_tokens,
+            "spent_output_tokens": state.metrics.output_tokens,
+            "note": "estimates use a len/4 heuristic; provider-reported usage is authoritative",
+        }