Install and configure¶

Looplet requires Python 3.11 or newer. The core package has no third-party runtime dependencies. Model provider adapters are optional extras.

Install the current build¶

The complete Quickstart uses the pinned preview below from its first step. Choose that environment before starting if you need the editable starter or factory commands. Keep it active throughout the guide, including optional provider setup.

Use release 0.4.1 for new integrations. It includes the safety fixes missing from 0.4.0. Install it in your own project without Git or a repository checkout:

python -m venv .venv
source .venv/bin/activate
python -m pip install "looplet==0.4.1"

This installs a non-editable package at a fixed version. Installation needs network access, but not Git. The fixed-response tutorial itself needs neither a model key nor a model service. Record package hashes in your dependency lockfile for deployment. Use looplet doctor --no-backend --json when you also need the library source fingerprint.

Try unreleased factory commands¶

The editable starter and factory shell workflow require unreleased source, not the PyPI 0.4.1 package. This is the same environment used at the start of the Quickstart:

python -m venv .venv-looplet-preview
source .venv-looplet-preview/bin/activate
python -m pip install "looplet @ https://github.com/hsaghir/looplet/archive/81d0ad13c74ae4e8365bed8da7ae739238fedfaa.zip"
looplet doctor --no-backend --json

This non-editable install pins commit 81d0ad1 with factory commands and the complete one-file starter. The starter selects providers, saves replay evidence, and runs repeat-safe experiments. Failed grades explain mismatches; experiment inspection shows stage status, errors, and available traces. Factory inspection supports declaration-only reports and explicit runtime wiring checks. Human runtime reports list tools and limits; --json includes the full blueprint. Its cases keep tasks and expectations together. CLI replay preserves the captured protocol and saved expectations. Installation needs network access, but not Git or a model key. It does not install a new PyPI release. Both builds report version 0.4.1; the preview appends its source fingerprint to looplet --version. This matches the doctor's build check and distinguishes same-version source builds without Git or provider calls. Experiment trace paths are report-relative; copied legacy reports prefer their colocated capture and replay directories. Malformed saved starter input returns concise recovery guidance without changing evidence. Eval help introduces Python factories first. Inspection lists saved suite cases and opens separately saved assessments without rerunning graders. Rescoring supports a named assessment file while preserving capture-time grades. Human rescoring keeps result labels and includes available failure explanations. Exhausted replay fails immediately with replay_exhausted, without retry backoff. Inspection lists saved experiment history, including unreadable reports and child navigation. Keep the commit and source fingerprint with experiment results. The ordinary Python, pytest, capture, and replay examples work with released 0.4.1. Do not install the published package over this environment midway through the Quickstart. Add provider extras from the same pinned archive, as shown in the guide.

Install the published package¶

The latest PyPI release is 0.4.1. Run this inside an activated virtual environment:

python -m pip install "looplet==0.4.1"

Add [openai], [anthropic], or [all] before ==0.4.1 for provider adapters. Use 0.4.0 only when reproducing that older release; it lacks the fixes below.

Safety fixes in 0.4.1¶

Release 0.4.1 includes the later safety fixes previously available only in source builds. Run looplet doctor --no-backend --json to record the version and library source fingerprint. These differences matter for completion, budgets, tool contracts, native calls, and captured evidence:

Behavior	Published `0.4.0`	Release `0.4.1`
Serial native batches	A batch may execute before its first yielded `Step`.	Each serial call runs before its own step; stopping prevents later calls.
Native response redaction	`redact=` does not scrub native response blocks.	`redact=` scrubs nested string values and keys.
Python replay defaults	Uses model-call count as the budget and an empty task.	Uses saved tool steps and task when omitted.
Tool timeout errors	May report a blank, retryable timeout.	Warns about unknown effects and requires reconciliation before retrying.
Rich Python annotations	`Annotated`, `Any`, and multi-type unions may become string schemas.	Preserves supported contracts and rejects unsupported annotations clearly.
Callable preset typing	Accepts functions at runtime but declares only `ToolSpec` inputs.	Type annotations match callable inputs and reusable sequences.
Failed terminal dispatch	May report accepted completion with no output, even with `--require-completed`.	Rejects failed calls and permits correction within the remaining budget.
Free tool budget	`DefaultState` charges every recorded step despite `free=True`.	Successful free calls preserve budget; failures and terminal attempts still consume steps.
CLI failure details	Completion output may omit the underlying error.	Human and JSON output include bounded last-error details for incomplete runs.
Missing terminal setup	Unknown terminal calls consume turns before failure.	Warns before the first model call when no configured terminal tool is registered.

Do not treat published 0.4.0 native captures as redacted. Keep them private and review evidence before sharing it. The recommended install includes these fixes without an editable checkout. Explicit concurrent dispatch still runs a batch before yielding its results.

Develop Looplet¶

Clone the repository only when changing Looplet itself. Run these commands in a directory where you want the repository:

git clone https://github.com/hsaghir/looplet.git
cd looplet
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

On Windows, activate the environment with .venv\Scripts\Activate.ps1 in PowerShell.

Install a provider extra from that checkout when you need a real model:

python -m pip install -e ".[openai]"

Use .[anthropic] for Anthropic or .[all] for both adapters.

Choose provider extras¶

Use these commands for the fixed release inside a virtual environment.

Goal	Command
Core APIs or fixed model responses	`python -m pip install "looplet==0.4.1"`
OpenAI or a compatible endpoint	`python -m pip install "looplet[openai]==0.4.1"`
Anthropic	`python -m pip install "looplet[anthropic]==0.4.1"`
Both provider adapters	`python -m pip install "looplet[all]==0.4.1"`

For published versions, pin the minor version in your application:

pyproject.toml

dependencies = ["looplet>=0.4.1,<0.5"]

Before version 1.0, a minor release can change an API incompatibly. Read the changelog before you change the minor version. The published Python examples and safety fixes are included in 0.4.1. Preview-only features are marked unreleased.

Verify without a provider¶

This command runs a loop with fixed model responses and checks its results. It does not need a model key or network connection:

python -m looplet.examples.hello_world --scripted

Use the Quickstart to write a loop that you control. Then run the regression example to check a tool change:

looplet-proof

Configure OpenAI¶

export LOOPLET_PROVIDER=openai
export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-4o

from looplet import OpenAIBackend

llm = OpenAIBackend.from_env()

OPENAI_MODEL is optional. Its default is gpt-4o. You do not need OPENAI_BASE_URL for the OpenAI cloud endpoint.

Configure an OpenAI-compatible endpoint¶

Looplet uses the OpenAI adapter for compatible endpoints. These include Ollama, vLLM, and llama.cpp servers:

export LOOPLET_PROVIDER=openai
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3.1:8b
export OPENAI_API_KEY=x

If a base URL has no key, OpenAIBackend.from_env() supplies a placeholder key. You can set OPENAI_API_KEY=x explicitly if other clients read the same environment.

Some compatible endpoints do not support native tool calls. Looplet uses native tool calls by default. It reports an error if the backend does not support them. It does not switch protocols without your choice. Check the configured provider with:

looplet doctor

Use this configuration to state the default explicitly:

from looplet import LoopConfig

config = LoopConfig(use_native_tools=True)

Set use_native_tools=False if your backend needs the JSON-text protocol.

See provider recipes for Ollama, Groq, Together, and explicit clients.

Configure Anthropic¶

export LOOPLET_PROVIDER=anthropic
export ANTHROPIC_API_KEY=...
export ANTHROPIC_MODEL=claude-sonnet-4-20250514

from looplet import AnthropicBackend

llm = AnthropicBackend.from_env()

ANTHROPIC_MODEL is optional. Set an explicit model in release environments instead of the library default.

Bring your own backend¶

composable_loop() accepts a backend object with this synchronous method. Replace my_client with the client that your application uses:

class MyBackend:
    def generate(
        self,
        prompt: str,
        *,
        max_tokens: int = 2000,
        system_prompt: str = "",
        temperature: float = 0.2,
    ) -> str:
        return my_client.complete(prompt)

Set LoopConfig(use_native_tools=False) if the backend implements only generate(...). A backend with generate_with_tools(...) can use native tool calls. The loop reports an error if the backend rejects native calls. See the Python API for the full backend interface.

Diagnose the environment¶

looplet doctor

Option	Effect
`--no-backend`	Check local settings without network access
`--json`	Print a JSON report
`--strict`	Return a non-zero exit code for warnings too

The command-line interface shares backend selection across doctor, new, run, and eval. It selects Anthropic if an Anthropic key is present. Otherwise, it selects OpenAI if an OpenAI key or compatible base URL is present. Set LOOPLET_PROVIDER=openai or LOOPLET_PROVIDER=anthropic to choose explicitly. An explicit --base-url on examples or evals selects an OpenAI-compatible endpoint. Automatic selection warns when Anthropic and OpenAI settings are both configured. doctor --strict treats this ambiguity as a failed configuration check. An explicit provider choice removes the warning without changing stored credentials.

Looplet 0.4.0 includes these selection rules for both providers. See the command-line guide for options and older command names.

Prepare a package release¶

Maintainers can qualify a distribution without publishing. Use the version declared in the selected revision:

gh workflow run publish.yml --repo hsaghir/looplet --ref master -f version=0.4.1

A non-tag dispatch runs tests, builds distributions, and checks an installed wheel. It uploads build artifacts but does not publish to PyPI or create a GitHub release. This qualifies a source candidate; it does not publish a new package version. Publication requires a matching release tag and the configured PyPI environment. Before tagging, update the versioned changelog and obtain release approval. Publish only the qualified commit after its pull request has merged.

Next¶

Quickstart: run, inspect, and stop one loop.
Migration: replace a loop without new tool implementations.
Troubleshooting: find causes of provider, tool, hook, replay, and eval errors.