looplet 0.1.7__py3-none-any.whl

looplet/__init__.py

@@ -0,0 +1,177 @@
+"""looplet — composable tool-calling LLM agent harness.
+
+A minimal, composable framework for building tool-calling LLM agent loops.
+
+Only symbols listed in ``__all__`` are imported here. For everything
+else, import from the relevant submodule::
+
+    from looplet.backends import OpenAIStreamingBackend, AsyncOpenAIBackend
+    from looplet.provenance import ProvenanceSink, replay_loop
+    from looplet.cache import CacheBreakDetector, compute_breakpoints
+"""
+
+__version__ = "0.1.6"
+
+# ── Public re-exports (one import per submodule, alphabetical) ──────────
+# ruff: noqa: F401 — __init__.py intentionally re-exports for `from looplet import X`
+
+from looplet.approval import ApprovalHook
+from looplet.backends import AnthropicBackend, OpenAIBackend
+from looplet.budget import ContextBudget, ThresholdCompactHook
+from looplet.cache import CachePolicy
+from looplet.checkpoint import FileCheckpointStore
+from looplet.compact import (
+    CompactOutcome,
+    CompactService,
+    PruneToolResults,
+    SummarizeCompact,
+    TruncateCompact,
+    compact_chain,
+    run_compact,
+)
+from looplet.conversation import Conversation, Message
+from looplet.evals import (
+    EvalContext,
+    EvalHook,
+    EvalResult,
+    eval_cli,
+    eval_discover,
+    eval_mark,
+    eval_run,
+    eval_run_batch,
+)
+from looplet.events import EventPayload, LifecycleEvent
+from looplet.hook_decision import (
+    Allow,
+    Block,
+    Continue,
+    Deny,
+    HookDecision,
+    InjectContext,
+    Stop,
+)
+from looplet.loop import DomainAdapter, LoopConfig, LoopHook, composable_loop, emit_event
+from looplet.mcp import MCPToolAdapter
+from looplet.memory import CallableMemorySource, StaticMemorySource
+from looplet.permissions import (
+    PermissionDecision,
+    PermissionEngine,
+    PermissionHook,
+    PermissionRule,
+)
+from looplet.presets import (
+    AgentPreset,
+    coding_agent_preset,
+    minimal_preset,
+    research_agent_preset,
+)
+from looplet.prompts import preview_prompt
+from looplet.provenance import ProvenanceSink, TrajectoryRecorder, replay_loop
+from looplet.session import SessionLog
+from looplet.skills import Skill
+from looplet.streaming import StreamingHook
+from looplet.subagent import run_sub_loop
+from looplet.telemetry import MetricsCollector, MetricsHook, Tracer, TracingHook
+from looplet.testing import AsyncMockLLMBackend, MockLLMBackend
+from looplet.tools import BaseToolRegistry, ToolSpec
+from looplet.types import (
+    CancelToken,
+    DefaultState,
+    ErrorKind,
+    LLMBackend,
+    NativeToolBackend,
+    Step,
+    ToolCall,
+    ToolContext,
+    ToolError,
+    ToolResult,
+)
+
+__all__ = [
+    # ── ESSENTIALS (what you need for your first agent) ──────────
+    "__version__",
+    "composable_loop",
+    "LoopConfig",
+    "LoopHook",
+    "Step",
+    "ToolCall",
+    "ToolResult",
+    "ToolSpec",
+    "BaseToolRegistry",
+    "Skill",
+    "DefaultState",
+    "LLMBackend",
+    "HookDecision",
+    "Allow",
+    "Block",
+    "Continue",
+    "Deny",
+    "Stop",
+    "InjectContext",
+    "preview_prompt",
+    # ── BACKENDS ─────────────────────────────────────────────────
+    "OpenAIBackend",
+    "AnthropicBackend",
+    "NativeToolBackend",
+    "MCPToolAdapter",
+    # ── CONTEXT MANAGEMENT ──────────────────────────────────────
+    "CompactService",
+    "CompactOutcome",
+    "TruncateCompact",
+    "SummarizeCompact",
+    "PruneToolResults",
+    "compact_chain",
+    "run_compact",
+    "ContextBudget",
+    "ThresholdCompactHook",
+    "CachePolicy",
+    "StaticMemorySource",
+    "CallableMemorySource",
+    # ── APPROVAL / PERMISSIONS ──────────────────────────────────
+    "ApprovalHook",
+    "PermissionEngine",
+    "PermissionHook",
+    "PermissionRule",
+    "PermissionDecision",
+    # ── CHECKPOINTS ─────────────────────────────────────────────
+    "FileCheckpointStore",
+    # ── OBSERVABILITY ───────────────────────────────────────────
+    "TrajectoryRecorder",
+    "ProvenanceSink",
+    "replay_loop",
+    "StreamingHook",
+    "Tracer",
+    "TracingHook",
+    "MetricsCollector",
+    "MetricsHook",
+    # ── EVALS ────────────────────────────────────────────────────
+    "EvalHook",
+    "EvalContext",
+    "EvalResult",
+    "eval_discover",
+    "eval_run",
+    "eval_run_batch",
+    "eval_mark",
+    "eval_cli",
+    # ── TESTING ─────────────────────────────────────────────────
+    "MockLLMBackend",
+    "AsyncMockLLMBackend",
+    # ── ADVANCED (power users import from submodules directly) ──
+    "DomainAdapter",
+    "emit_event",
+    "LifecycleEvent",
+    "EventPayload",
+    "CancelToken",
+    "ToolContext",
+    "ToolError",
+    "ErrorKind",
+    "SessionLog",
+    "Conversation",
+    "Message",
+    "run_sub_loop",
+    # ── PRESETS (one-liner agent setup) ─────────────────────────
+    "AgentPreset",
+    "coding_agent_preset",
+    "research_agent_preset",
+    "minimal_preset",
+]

looplet/__main__.py

@@ -0,0 +1,143 @@
+"""``python -m looplet`` — CLI entry point.
+
+Subcommands:
+    show <trace-dir>    One-page summary of a captured trace directory.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _fmt_ms(ms: float | int | None) -> str:
+    if ms is None:
+        return "   -  "
+    return f"{int(ms):>5}ms"
+
+
+def _render_show(trace_dir: Path) -> int:
+    if not trace_dir.exists():
+        print(f"error: {trace_dir} does not exist", file=sys.stderr)
+        return 1
+
+    # ── trajectory.json (optional; short-circuit if missing) ─────
+    traj_path = trace_dir / "trajectory.json"
+    manifest_path = trace_dir / "manifest.jsonl"
+    traj: dict[str, Any] = {}
+    if traj_path.exists():
+        try:
+            traj = json.loads(traj_path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            print(f"error: could not parse {traj_path}: {exc}", file=sys.stderr)
+            return 1
+
+    # ── manifest.jsonl (optional) ────────────────────────────────
+    calls: list[dict[str, Any]] = []
+    if manifest_path.exists():
+        for line in manifest_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                calls.append(json.loads(line))
+            except Exception:
+                continue
+
+    if not traj and not calls:
+        print(f"error: {trace_dir} contains no trajectory.json or "
+              "manifest.jsonl — not a trace directory", file=sys.stderr)
+        return 1
+
+    # ── Header ──────────────────────────────────────────────────
+    run_id = traj.get("run_id") or trace_dir.name
+    term = traj.get("termination_reason", "?")
+    term_glyph = {"done": "✓", "error": "✗"}.get(term, "·")
+    step_count = traj.get("step_count", len(traj.get("steps", [])))
+    llm_count = traj.get("llm_call_count", len(calls))
+    # Total duration: sum step durations if available, else call durations.
+    total_ms = sum(s.get("duration_ms", 0) for s in traj.get("steps", []))
+    if total_ms == 0 and calls:
+        total_ms = sum(c.get("duration_ms", 0) for c in calls)
+
+    print(
+        f"{run_id}  {term_glyph} {term}  "
+        f"{step_count} steps  {llm_count} LLM calls  {int(total_ms)}ms"
+    )
+    print()
+
+    # ── Steps ───────────────────────────────────────────────────
+    for s in traj.get("steps", []):
+        num = s.get("step_num", "?")
+        tc = s.get("tool_call", {}) or {}
+        tr = s.get("tool_result", {}) or {}
+        tool = tc.get("tool") or tc.get("action") or "?"
+        args = s.get("args_summary") or tr.get("args") or ""
+        err = tr.get("error") or s.get("error")
+        ok = "✗" if err else "✓"
+        data = tr.get("data")
+        if err:
+            tail = f"ERROR: {str(err)[:40]}"
+        elif isinstance(data, list):
+            tail = f"{len(data)} items"
+        elif isinstance(data, dict):
+            tail = f"{tr.get('total_items') or len(data)} keys"
+        elif data is None:
+            tail = ""
+        else:
+            snippet = str(data)
+            tail = snippet if len(snippet) <= 30 else snippet[:27] + "..."
+        dur = _fmt_ms(s.get("duration_ms"))
+        linked = s.get("llm_call_indices") or []
+        link_str = f"call {linked[0]}" if linked else ""
+        print(f"#{num}  {ok} {tool}({str(args)[:30]:<30}) "
+              f"→ {tail:<20} [{dur}] {link_str}")
+
+    # ── LLM summary ─────────────────────────────────────────────
+    if calls:
+        total_prompt = sum(c.get("prompt_chars") or 0 for c in calls)
+        total_resp = sum(c.get("response_chars") or 0 for c in calls)
+        errors = sum(1 for c in calls if c.get("error"))
+        print()
+        print(
+            f"LLM: {len(calls)} calls, "
+            f"{total_prompt:,} in / {total_resp:,} out chars, "
+            f"{errors} errors"
+        )
+
+    # ── Failure modes (if present) ──────────────────────────────
+    modes = traj.get("failure_modes") or []
+    if modes:
+        print()
+        for fm in modes:
+            print(f"!! {fm}")
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m looplet",
+        description="looplet — inspect captured trace directories",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    show = sub.add_parser(
+        "show",
+        help="Show a one-page summary of a captured trace directory",
+    )
+    show.add_argument("trace_dir", type=Path, help="Path to a trace directory")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "show":
+        return _render_show(args.trace_dir)
+    # Unreachable — argparse rejects unknown commands.
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

looplet/approval.py

@@ -0,0 +1,135 @@
+"""Async approval for tool actions that need human sign-off.
+
+The pattern:
+  1. A tool detects a high-risk action and sets
+     ``{"needs_approval": True, "approval_description": "..."}``
+     in its result data.
+  2. ``ApprovalHook.post_dispatch`` detects this and stops the loop
+     with ``stop_reason="waiting_for_approval"``.
+  3. The loop checkpoints (if ``checkpoint_dir`` is configured) and
+     the generator terminates.
+  4. An external system (webhook, Slack bot, email, human on CLI)
+     records the approval.
+  5. The caller restarts the loop — ``checkpoint_dir`` auto-resumes
+     from the last step, and the approval is injected into context
+     via a ``StaticMemorySource`` or ``pre_prompt`` hook.
+
+Usage::
+
+    from looplet import ApprovalHook, LoopConfig
+
+    config = LoopConfig(
+        checkpoint_dir="./checkpoints",  # auto-save + auto-resume
+        approval_handler=my_sync_handler,  # or None for async-only
+    )
+    hooks = [ApprovalHook()]
+
+For **sync approval** (blocks until human responds)::
+
+    config = LoopConfig(
+        approval_handler=lambda prompt, opts: input(f"{prompt} {opts}: "),
+    )
+    # No ApprovalHook needed — tools call ctx.approve() inline.
+
+For **async approval** (suspend → external approval → resume)::
+
+    config = LoopConfig(
+        checkpoint_dir="./ckpt",
+        approval_handler=None,   # tools get None → set needs_approval
+    )
+    hooks = [ApprovalHook()]
+    # Loop stops at approval request.
+    # Resume: restart the loop, approval injected via memory_sources.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from looplet.session import SessionLog
+    from looplet.types import AgentState, ToolCall, ToolResult
+
+__all__ = ["ApprovalHook", "ApprovalRequest"]
+
+logger = logging.getLogger(__name__)
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """Record of a pending approval request.
+
+    Stored by :class:`ApprovalHook` when a tool result contains
+    ``needs_approval=True``. Callers can inspect ``pending`` after
+    the loop stops to build notifications, webhooks, or UIs.
+    """
+
+    step: int
+    tool: str
+    description: str = ""
+    options: list[str] = field(default_factory=lambda: ["approve", "deny"])
+
+class ApprovalHook:
+    """Hook that stops the loop when a tool requests approval.
+
+    Detects ``needs_approval=True`` in any tool result's ``data``
+    dict and stops the loop so an external system can provide the
+    approval before the loop resumes.
+
+    When the loop stops, ``self.pending`` contains the
+    :class:`ApprovalRequest` — use it to send a notification,
+    create a webhook, or prompt a human.
+
+    Combine with ``LoopConfig(checkpoint_dir=...)`` for full
+    crash-safe async approval::
+
+        hook = ApprovalHook()
+        config = LoopConfig(checkpoint_dir="./ckpt")
+        gen = composable_loop(..., hooks=[hook], config=config)
+        for step in gen:
+            print(step)
+        if hook.pending:
+            print(f"Waiting for approval: {hook.pending}")
+            # ... external approval happens ...
+            # On next run, checkpoint_dir auto-resumes.
+    """
+
+    def __init__(self) -> None:
+        self._pending: ApprovalRequest | None = None
+
+    @property
+    def pending(self) -> ApprovalRequest | None:
+        """The pending approval request, or None if none is pending."""
+        return self._pending
+
+    def post_dispatch(
+        self,
+        state: AgentState,
+        session_log: SessionLog,
+        tool_call: ToolCall,
+        tool_result: ToolResult,
+        step_num: int,
+    ) -> Any:
+        """Detect ``needs_approval`` in tool result and stop the loop."""
+        from looplet.hook_decision import HookDecision  # noqa: PLC0415
+
+        data = getattr(tool_result, "data", None) or {}
+        if not data.get("needs_approval"):
+            return None
+
+        self._pending = ApprovalRequest(
+            step=step_num,
+            tool=getattr(tool_call, "tool", ""),
+            description=data.get("approval_description", ""),
+            options=data.get("approval_options", ["approve", "deny"]),
+        )
+        logger.info(
+            "approval_required step=%d tool=%s desc=%s",
+            step_num, self._pending.tool, self._pending.description,
+        )
+        return HookDecision(stop="waiting_for_approval")
+
+    def should_stop(self, state: AgentState, step_num: int, new_entities: int) -> bool:
+        return False
+