Skip to content

Zero deps · Four hooks · One iterator

The loop is the product.

looplet is a for-loop you own for LLM tool-calling agents. Yield every step, intercept every tool call, redact every prompt, eval every trajectory. No graph DSL, no agent runtime, no hidden state. Works with any OpenAI-compatible endpoint or Anthropic directly.

PyPI Python License CI GitHub stars

Quickstart → 5-step tutorial GitHub ⭐

289ms

Cold import

0

Runtime deps

4

Hook protocols

1,062

Tests, ~1s

from looplet import composable_loop

for step in composable_loop(llm=llm, tools=tools, task=task, config=cfg, state=state):
    print(step.pretty())          # "#1 search(query='…') → 12 items [340ms]"
    if step.usage.total_tokens > BUDGET:
        break                      # your loop, your control flow

pip install looplet                  # core — zero third-party packages
pip install "looplet[openai]"        # OpenAI, Ollama, Groq, Together, vLLM
pip install "looplet[anthropic]"     # Anthropic

looplet demo — three-step investigation loop

How it works

flowchart LR
    subgraph Loop["composable_loop()"]
        direction LR
        P[pre_prompt] --> L[llm.generate]
        L --> D[pre_dispatch]
        D --> T[tool.execute]
        T --> R[post_dispatch]
        R --> C{check_done}
        C -- no --> P
        C -- yes --> Y([yield Step])
    end
    Y --> Caller[Your for-loop]
    Caller -. "stop / log / score" .-> Loop

    classDef hook fill:#EEF2FF,stroke:#4F46E5,stroke-width:1.5px,color:#1E1B4B
    class P,D,R,C hook

Four hook methods on any Python object. Implement only the ones you need. The loop uses hasattr — no base class, no registration.

Why looplet?

  • Fast to start, fast to run

    289 ms cold import. Zero runtime dependencies. pip install stays snappy on serverless and short-lived scripts.

    Benchmarks

  • Composable by Protocol

    Four @runtime_checkable hook methods. Any object implementing one or more is a hook. No base classes, no registration.

    Hooks

  • Observable by default

    step.pretty(), ProvenanceSink, and eval_* all read the same Step dataclass. One artifact, three uses.

    Provenance

  • Safe by design

    redact= scrubs PII before the provider sees it and before the trace is written. No wrapping-order footguns.

    Pitfalls

  • Compose agents as tools

    Any looplet agent is a function that returns a result. Wrap it in a ToolSpec and plug it into the next agent.

    Recipes

  • Debugging is evaluation

    What you do while debugging (print(step.pretty())) is a trajectory. Evals are pytest-style functions over the same data.

    Evals

See the difference

from langgraph.prebuilt import create_react_agent

agent = create_react_agent(
    model=llm,
    tools=[search, fetch],
    state_schema=State,
)
result = agent.invoke({"messages": [task]})
# Where does the loop stop?
# Where does the tool call happen?
# How do I intercept it?
# → read the framework source.

for step in composable_loop(
    llm=llm, tools=tools, task=task,
    hooks=[BudgetCap(10_000), Redactor()],
):
    if step.tool_call.tool == "delete":
        if not approve(step):           # (1)
            break
    log(step)                            # (2)
  1. Intercept any tool call with ordinary Python — no custom graph node needed.
  2. One Step object is the trace, the eval context, and the checkpoint unit.

Honest benchmarks

All numbers regenerate in one command on a fresh Python 3.11 venv. See Benchmarks for the full methodology.

looplet 289 ms · 0 deps

strands-agents 1,885 ms · 6 deps

LangGraph 2,294 ms · 31 deps

Claude Agent SDK 2,409 ms · 13 deps

Pydantic AI 3,975 ms · 12 deps

Cold-import time, median of 9 fresh subprocess runs. Python 3.11.13, Linux x86_64, PyPI wheels from 2026-04-21.

Start here

  • Quickstart

    Install. Run. Understand the loop in five minutes.

  • Tutorial

    Build an agent with hooks, context management, crash-resume, and approval — in five steps.

  • Hooks

    The four extension points. Recipes for every common pattern.

  • Evals

    pytest-style scoring over the same trajectory you debug with.

  • Provenance

    Capture every prompt and step to a diff-friendly directory.

  • Recipes

    Ollama, OTel, MCP, cost accounting, checkpoints.

  • Pitfalls

    Ten sharp edges worth knowing — with the "right way" for each.

  • Benchmarks

    Cold import and dependency footprint, with the harness.

Extension points at a glance

  • pre_prompt

    Inject context into the next prompt. Context managers, retrieval-augmented briefings, step-specific guidance.

  • pre_dispatch

    Intercept a tool call before it runs. Cache hits, permission gates, argument rewriting, approval flows.

  • post_dispatch

    React to a tool result. Duplicate-call warnings, error remediation messages, metric collection, streaming events.

  • check_done

    Reject premature completion. Quality gates, minimum-evidence thresholds, required-tool checks.

Talks and writing

GitHub PyPI Blog