tightloop 0.1.0__py3-none-any.whl

loop/core/state.py

@@ -0,0 +1,143 @@
+"""Explicit, serializable loop state."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+SCHEMA_VERSION = 1
+ENGINE_VERSION = "0.1.0"
+INLINE_CAP = 16 * 1024  # max inline chars per record; large payloads live in the trace
+
+
+class StateError(Exception):
+    pass
+
+
+class SchemaChangedError(StateError):
+    """Tool schemas changed since the state was saved (resume requires allow_schema_change)."""
+
+
+class ArtifactDriftError(StateError):
+    """Stored context artifacts were produced by a different engine/summarizer version."""
+
+
+def digest(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()[:16]
+
+
+def excerpt(text: str, cap: int = INLINE_CAP) -> str:
+    if len(text) <= cap:
+        return text
+    return text[:cap] + f"\n...[truncated {len(text) - cap} chars, digest={digest(text)}]"
+
+
+class ArtifactStamp(BaseModel):
+    engine_version: str
+    model_id: str
+    prompt_hash: str
+
+
+class ContextArtifact(BaseModel):
+    kind: Literal["summary", "fact"]
+    iteration: int | None = None
+    content: str
+    stamp: ArtifactStamp
+
+
+class MetricSnapshot(BaseModel):
+    value: float
+    regression: bool = False
+    detail: dict[str, Any] = Field(default_factory=dict)
+
+
+class ActionRecord(BaseModel):
+    tool: str
+    args_excerpt: str
+    status: Literal["ok", "error", "aborted"]
+    result_excerpt: str
+    duration_s: float
+    fingerprint: str
+
+
+class IterationRecord(BaseModel):
+    index: int
+    observation: str
+    plan_text: str = ""
+    actions: list[ActionRecord] = Field(default_factory=list)
+    metric: MetricSnapshot | None = None
+    repetition: bool = False
+    plan_invalid: bool = False
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class Metrics(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    llm_calls: int = 0
+    elapsed_s: float = 0.0
+    cost_usd: float | None = None
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+class PendingApproval(BaseModel):
+    token: str
+    tool: str
+    args: dict[str, Any]
+    reason: str
+    action_hash: str
+    state_version: int
+    created_at: float
+    ttl_s: float
+    plan_text: str = ""
+    precondition_metric: MetricSnapshot | None = None
+
+
+class State(BaseModel):
+    schema_version: int = SCHEMA_VERSION
+    goal: str
+    config: dict[str, Any] = Field(default_factory=dict)
+    tool_schema_hash: str = ""
+    iterations: list[IterationRecord] = Field(default_factory=list)
+    artifacts: list[ContextArtifact] = Field(default_factory=list)
+    pinned_facts: list[str] = Field(default_factory=list)
+    failed_approaches: list[str] = Field(default_factory=list)
+    metrics: Metrics = Field(default_factory=Metrics)
+    no_progress_streak: int = 0
+    plan_invalid_streak: int = 0
+    state_version: int = 0
+    pending_approval: PendingApproval | None = None
+
+    def save(self, path: str | Path) -> None:
+        payload = self.model_dump(mode="json")
+        body = json.dumps(payload, sort_keys=True)
+        wrapper = {
+            "integrity": hashlib.sha256(body.encode()).hexdigest(),
+            "state": payload,
+        }
+        Path(path).write_text(json.dumps(wrapper, indent=2))
+
+    @classmethod
+    def load(cls, path: str | Path) -> "State":
+        try:
+            wrapper = json.loads(Path(path).read_text())
+        except (OSError, json.JSONDecodeError) as e:
+            raise StateError(f"cannot read state file {path}: {e}") from e
+        payload = wrapper.get("state")
+        if payload is None:
+            raise StateError(f"{path} is not a Loop state file")
+        body = json.dumps(payload, sort_keys=True)
+        if hashlib.sha256(body.encode()).hexdigest() != wrapper.get("integrity"):
+            raise StateError(f"integrity check failed for {path}")
+        if payload.get("schema_version") != SCHEMA_VERSION:
+            raise StateError(
+                f"state schema_version {payload.get('schema_version')} != supported {SCHEMA_VERSION}"
+            )
+        return cls.model_validate(payload)

loop/exit/__init__.py

@@ -0,0 +1,60 @@
+"""Declarative exit conditions. Evaluated after each iteration;
+first matching exit wins. The always-on ceilings (max_iterations, token_limit,
+wall-clock) are engine constructor args — these are additional conditions."""
+from __future__ import annotations
+
+from typing import Callable
+
+from ..core.result import LoopStatus
+from ..core.state import State
+
+
+class ExitCondition:
+    def evaluate(self, state: State) -> tuple[LoopStatus, str] | None:
+        raise NotImplementedError
+
+
+class _Lambda(ExitCondition):
+    def __init__(self, fn: Callable[[State], tuple[LoopStatus, str] | None]):
+        self.fn = fn
+
+    def evaluate(self, state: State) -> tuple[LoopStatus, str] | None:
+        return self.fn(state)
+
+
+class Exit:
+    @staticmethod
+    def success(predicate: Callable[[State], bool], reason: str = "goal achieved") -> ExitCondition:
+        return _Lambda(lambda s: (LoopStatus.SUCCESS, reason) if predicate(s) else None)
+
+    @staticmethod
+    def max_iterations(n: int = 20) -> ExitCondition:
+        return _Lambda(
+            lambda s: (LoopStatus.BUDGET_EXHAUSTED, f"max_iterations {n} reached")
+            if len(s.iterations) >= n
+            else None
+        )
+
+    @staticmethod
+    def token_limit(n: int) -> ExitCondition:
+        return _Lambda(
+            lambda s: (LoopStatus.BUDGET_EXHAUSTED, f"token_limit {n} reached")
+            if s.metrics.total_tokens >= n
+            else None
+        )
+
+    @staticmethod
+    def cost_limit(usd: float) -> ExitCondition:
+        return _Lambda(
+            lambda s: (LoopStatus.BUDGET_EXHAUSTED, f"cost_limit ${usd:.2f} reached")
+            if s.metrics.cost_usd is not None and s.metrics.cost_usd >= usd
+            else None
+        )
+
+    @staticmethod
+    def stagnation(n: int = 3) -> ExitCondition:
+        return _Lambda(
+            lambda s: (LoopStatus.NO_PROGRESS, f"stagnation: {s.no_progress_streak} flat iterations")
+            if s.no_progress_streak >= n
+            else None
+        )

loop/llm/__init__.py

@@ -0,0 +1,70 @@
+"""LLMClient protocol + canonical ToolCall normalization.
+
+Provider responses are normalized into LLMResponse/ToolCallReq at this
+boundary, so the engine handles hallucinated or malformed tool calls uniformly
+regardless of provider leniency.
+
+Timeout defaults are recommended values, not SLA-backed (see README).
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+DEFAULT_TIMEOUT_S = 120.0
+
+
+class ToolCallReq(BaseModel):
+    id: str = ""
+    name: str
+    args: dict[str, Any] = Field(default_factory=dict)
+
+
+class LLMResponse(BaseModel):
+    text: str = ""
+    tool_calls: list[ToolCallReq] = Field(default_factory=list)
+    input_tokens: int = 0
+    output_tokens: int = 0
+    model_id: str = ""
+
+
+class LLMClient:
+    """Adapter protocol. Subclasses implement complete()."""
+
+    model_id: str = "unknown"
+    timeout_s: float = DEFAULT_TIMEOUT_S
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        tool_schemas: list[dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        raise NotImplementedError
+
+
+class CallableLLM(LLMClient):
+    """Wraps any fn(messages, tool_schemas) -> LLMResponse. Useful for tests and raw APIs."""
+
+    def __init__(self, fn: Callable[[list[dict], list[dict]], LLMResponse], model_id: str = "callable"):
+        self.fn = fn
+        self.model_id = model_id
+
+    def complete(self, messages, tool_schemas, max_tokens):
+        return self.fn(messages, tool_schemas)
+
+
+def complete_with_retry(
+    client: LLMClient,
+    messages: list[dict[str, str]],
+    tool_schemas: list[dict[str, Any]],
+    max_tokens: int,
+) -> LLMResponse:
+    """One retry with backoff on timeout/transient errors."""
+    try:
+        return client.complete(messages, tool_schemas, max_tokens)
+    except Exception:
+        time.sleep(1.0)
+        return client.complete(messages, tool_schemas, max_tokens)

loop/llm/anthropic.py

@@ -0,0 +1,45 @@
+"""Anthropic adapter. Requires the `anthropic` extra. Default timeout: 120s (not SLA-backed)."""
+from __future__ import annotations
+
+from typing import Any
+
+from . import DEFAULT_TIMEOUT_S, LLMClient, LLMResponse, ToolCallReq
+
+
+class AnthropicLLM(LLMClient):
+    def __init__(self, model: str = "claude-sonnet-4-6", timeout_s: float = DEFAULT_TIMEOUT_S, **client_kwargs: Any):
+        import anthropic  # lazy: optional dependency
+
+        self.model_id = model
+        self.timeout_s = timeout_s
+        self._client = anthropic.Anthropic(timeout=timeout_s, **client_kwargs)
+
+    def complete(self, messages, tool_schemas, max_tokens):
+        system = "\n\n".join(m["content"] for m in messages if m["role"] == "system")
+        convo = [m for m in messages if m["role"] != "system"]
+        tools = [
+            {"name": s["name"], "description": s.get("description", ""), "input_schema": s["input_schema"]}
+            for s in tool_schemas
+        ]
+        resp = self._client.messages.create(
+            model=self.model_id,
+            system=system or None,
+            messages=convo,
+            tools=tools or None,
+            max_tokens=max_tokens,
+        )
+        text_parts: list[str] = []
+        calls: list[ToolCallReq] = []
+        for block in resp.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "tool_use":
+                args = block.input if isinstance(block.input, dict) else {}
+                calls.append(ToolCallReq(id=block.id, name=block.name, args=args))
+        return LLMResponse(
+            text="\n".join(text_parts),
+            tool_calls=calls,
+            input_tokens=resp.usage.input_tokens,
+            output_tokens=resp.usage.output_tokens,
+            model_id=self.model_id,
+        )

loop/llm/openai.py

@@ -0,0 +1,55 @@
+"""OpenAI adapter. Requires the `openai` extra. Default timeout: 120s (not SLA-backed)."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from . import DEFAULT_TIMEOUT_S, LLMClient, LLMResponse, ToolCallReq
+
+
+class OpenAILLM(LLMClient):
+    def __init__(self, model: str = "gpt-4o", timeout_s: float = DEFAULT_TIMEOUT_S, **client_kwargs: Any):
+        import openai  # lazy: optional dependency
+
+        self.model_id = model
+        self.timeout_s = timeout_s
+        self._client = openai.OpenAI(timeout=timeout_s, **client_kwargs)
+
+    def complete(self, messages, tool_schemas, max_tokens):
+        tools = [
+            {
+                "type": "function",
+                "function": {
+                    "name": s["name"],
+                    "description": s.get("description", ""),
+                    "parameters": s["input_schema"],
+                },
+            }
+            for s in tool_schemas
+        ]
+        resp = self._client.chat.completions.create(
+            model=self.model_id,
+            messages=messages,
+            tools=tools or None,
+            max_tokens=max_tokens,
+        )
+        choice = resp.choices[0].message
+        calls: list[ToolCallReq] = []
+        for tc in choice.tool_calls or []:
+            try:
+                args = json.loads(tc.function.arguments)
+            except json.JSONDecodeError:
+                # malformed args become an empty call; engine-side validation feeds
+                # a structured error back to the model
+                args = {"__malformed__": tc.function.arguments}
+            if not isinstance(args, dict):
+                args = {"__malformed__": tc.function.arguments}
+            calls.append(ToolCallReq(id=tc.id, name=tc.function.name, args=args))
+        usage = resp.usage
+        return LLMResponse(
+            text=choice.content or "",
+            tool_calls=calls,
+            input_tokens=usage.prompt_tokens if usage else 0,
+            output_tokens=usage.completion_tokens if usage else 0,
+            model_id=self.model_id,
+        )

loop/policy/__init__.py

@@ -0,0 +1,96 @@
+"""Composable policies.
+
+Precedence note: hard ceilings (iterations/tokens/wall-clock) are enforced by
+the engine itself before every action and before granting any approval —
+policies layer on top of those guarantees, they don't replace them.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Callable, Iterable
+
+from pydantic import BaseModel
+
+from ..core.result import LoopStatus
+from ..core.state import State
+from ..pricing import DEFAULT_PRICING, estimate_cost
+
+
+class DecisionKind(str, Enum):
+    CONTINUE = "CONTINUE"
+    STOP = "STOP"
+    PAUSE = "PAUSE"  # request human approval
+
+
+class Decision(BaseModel):
+    kind: DecisionKind = DecisionKind.CONTINUE
+    reason: str = ""
+    status: LoopStatus | None = None  # for STOP
+
+
+CONTINUE = Decision()
+
+
+class Policy:
+    def before_iteration(self, state: State) -> Decision:
+        return CONTINUE
+
+    def before_action(self, state: State, tool_name: str, args: dict[str, Any]) -> Decision:
+        return CONTINUE
+
+
+class NoProgress(Policy):
+    """Fires after `window` consecutive flagged iterations with zero goal-metric delta
+   . Streak accounting is done by the ProgressEngine; this reads it."""
+
+    def __init__(self, window: int = 3):
+        self.window = window
+
+    def before_iteration(self, state: State) -> Decision:
+        if state.no_progress_streak >= self.window:
+            return Decision(
+                kind=DecisionKind.STOP,
+                status=LoopStatus.NO_PROGRESS,
+                reason=(
+                    f"{state.no_progress_streak} consecutive iterations with repeated/invalid "
+                    "actions and zero goal-metric delta"
+                ),
+            )
+        return CONTINUE
+
+
+class CostLimit(Policy):
+    def __init__(self, usd: float, model_id: str, pricing: dict | None = None):
+        self.usd = usd
+        self.model_id = model_id
+        self.pricing = pricing or DEFAULT_PRICING
+
+    def before_iteration(self, state: State) -> Decision:
+        cost = estimate_cost(
+            state.metrics.input_tokens, state.metrics.output_tokens, self.model_id, self.pricing
+        )
+        if cost is not None and cost >= self.usd:
+            return Decision(
+                kind=DecisionKind.STOP,
+                status=LoopStatus.BUDGET_EXHAUSTED,
+                reason=f"estimated cost ${cost:.2f} >= limit ${self.usd:.2f} (tokens are authoritative)",
+            )
+        return CONTINUE
+
+
+class RequireApproval(Policy):
+    """Pause for human approval when an action matches. Matcher: tool-name iterable
+    or callable(tool_name, args) -> bool."""
+
+    def __init__(self, matcher: Iterable[str] | Callable[[str, dict], bool], reason: str = "requires approval"):
+        if callable(matcher):
+            self._match = matcher
+        else:
+            names = set(matcher)
+            self._match = lambda name, args: name in names
+        self.reason = reason
+
+    def before_action(self, state: State, tool_name: str, args: dict[str, Any]) -> Decision:
+        if self._match(tool_name, args):
+            return Decision(kind=DecisionKind.PAUSE, reason=self.reason)
+        return CONTINUE

loop/pricing.py

@@ -0,0 +1,47 @@
+"""USD cost estimation. Tokens are the authoritative unit; USD is a convenience
+derived from a pricing table that carries an as-of date.
+"""
+from __future__ import annotations
+
+import warnings
+from datetime import date, datetime
+from typing import Any
+
+STALENESS_DAYS = 90
+
+DEFAULT_PRICING: dict[str, Any] = {
+    "as_of": "2026-01-15",
+    "models": {
+        # USD per million tokens
+        "claude-sonnet-4-6": {"input": 3.00, "output": 15.00},
+        "claude-haiku-4-5-20251001": {"input": 1.00, "output": 5.00},
+        "claude-opus-4-8": {"input": 15.00, "output": 75.00},
+        "gpt-4o": {"input": 2.50, "output": 10.00},
+    },
+}
+
+
+class PricingStalenessError(Exception):
+    pass
+
+
+def check_staleness(pricing: dict[str, Any], behavior: str = "warn", today: date | None = None) -> bool:
+    """Returns True if cost accounting should proceed in USD; False for token-only fallback."""
+    as_of = datetime.strptime(pricing["as_of"], "%Y-%m-%d").date()
+    age = ((today or date.today()) - as_of).days
+    if age <= STALENESS_DAYS:
+        return True
+    msg = f"pricing table as_of={pricing['as_of']} is {age} days old (> {STALENESS_DAYS})"
+    if behavior == "refuse":
+        raise PricingStalenessError(msg + "; refusing USD cost accounting")
+    if behavior == "token-only":
+        return False
+    warnings.warn(msg + "; USD figures are estimates — tokens remain authoritative", stacklevel=2)
+    return True
+
+
+def estimate_cost(input_tokens: int, output_tokens: int, model_id: str, pricing: dict[str, Any]) -> float | None:
+    rates = pricing["models"].get(model_id)
+    if not rates:
+        return None
+    return (input_tokens * rates["input"] + output_tokens * rates["output"]) / 1_000_000

loop/progress/__init__.py

@@ -0,0 +1,72 @@
+"""Progress engine: raw signals, no fake-precision score.
+
+Signals: blueprint goal metric (regression-aware), repetition detection via
+per-tool fingerprints (advisory), LLM self-assessment (trace-only, never gates
+exits in v1 — by design).
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from ..core.state import IterationRecord, MetricSnapshot, State
+
+
+class GoalMetric:
+    """Blueprint-supplied. measure() returns a snapshot; is_success() gates SUCCESS."""
+
+    def measure(self, observation: str, state: State) -> MetricSnapshot:
+        raise NotImplementedError
+
+    def is_success(self, snapshot: MetricSnapshot) -> bool:
+        return False
+
+
+class ProgressReport(BaseModel):
+    trend: str  # improving | flat | regressing | unknown
+    repetition: bool
+    no_progress_streak: int
+    metric_delta: float | None = None
+
+
+class ProgressEngine:
+    def evaluate(self, state: State, iteration: IterationRecord) -> ProgressReport:
+        prev = state.iterations[-1] if state.iterations else None
+
+        # repetition: identical fingerprint set to the previous iteration's (non-empty)
+        fps = {a.fingerprint for a in iteration.actions}
+        prev_fps = {a.fingerprint for a in prev.actions} if prev else set()
+        iteration.repetition = bool(fps) and fps == prev_fps
+
+        delta: float | None = None
+        if iteration.metric and prev and prev.metric:
+            delta = iteration.metric.value - prev.metric.value
+
+        if iteration.metric and iteration.metric.regression:
+            trend = "regressing"
+        elif delta is None:
+            trend = "unknown"
+        elif delta > 0:
+            trend = "improving"
+        elif delta < 0:
+            trend = "regressing"
+        else:
+            trend = "flat"
+
+        flat = delta is None or delta == 0
+        flagged = iteration.repetition or iteration.plan_invalid
+        if flagged and flat:
+            state.no_progress_streak += 1
+        else:
+            state.no_progress_streak = 0
+
+        if iteration.plan_invalid:
+            state.plan_invalid_streak += 1
+        else:
+            state.plan_invalid_streak = 0
+
+        return ProgressReport(
+            trend=trend,
+            repetition=iteration.repetition,
+            no_progress_streak=state.no_progress_streak,
+            metric_delta=delta,
+        )