Metadata-Version: 2.4
Name: looptail
Version: 0.2.3
Summary: Record every AI decision as a signed, append-only trail. Every loop leaves a tail.
Project-URL: Homepage, https://looptail.ai
Project-URL: Documentation, https://looptail.ai/docs
Project-URL: Source, https://github.com/maxfain/looptail
Author-email: Looptail <hello@looptail.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,audit-trail,eu-ai-act,evals,llm,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: cryptography>=41
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Description-Content-Type: text/markdown

# looptail

Record every AI decision as a signed, append-only trail. Every loop leaves a tail.

```bash
pip install looptail
```

```python
import looptail

looptail.init(app="support-agent")

@looptail.trail
def handle_ticket(ticket):
    ...

# report an outcome signal when you learn how it went
looptail.outcome(looptail.last_event_id(), csat=5)
```

Every call becomes a **hash-chained, Ed25519-signed loop event** appended to
`.looptail/support-agent.jsonl`. Nothing is edited in place; any modification,
deletion, or reorder of past records is detectable:

```bash
npx @looptail/cli verify --app support-agent

✔ 2 loop events
✔ chain intact · signatures valid
```

Or from Python: `looptail.verify_trail()`.

## The whole loop, CLI-first

```bash
looptail-evals run --rubric rubrics/refund-policy.json --app support-agent
looptail-issues cluster --app support-agent
looptail-improve propose --app support-agent --issue refund-policy/v1/criterion-0 \
    --prompt-file prompts/support.txt
looptail-improve replay --app support-agent --proposal prop_... \
    --cases regression.jsonl --runner myapp.replay:run --rubric rubrics/refund-policy.json
looptail-improve approve --app support-agent --proposal prop_... --apply
```

Evaluators score recorded events against **your rubrics** with an LLM judge
(`pip install "looptail[anthropic]"` or `[openai]`); failing verdicts cluster
into tracked issues; the improve loop drafts a patch, replays your regression
set, and gates approval on a passing replay. Every step lands in the trail as
a signed event. Guide: [looptail.ai/docs/improve](https://looptail.ai/docs/improve).

## How it works

- A signing key is created on first use at `~/.looptail/signing-key`
  (override with `LOOPTAIL_SIGNING_KEY`, hex seed).
- Events follow the open trail format —
  [spec/trail-format.md](https://github.com/maxfain/looptail/blob/main/spec/trail-format.md) —
  and are verifiable by any implementation, including the JS CLI.
- The local trail is the source of truth. With an API key
  (`looptail.init(app=..., api_key=...)` or `LOOPTAIL_API_KEY`), events also
  sync to the hosted Tail (private beta); sync is best-effort and never blocks
  or crashes your app.

Read the trust model in the spec before relying on local trails as evidence:
self-signed trails are tamper-evident; hosted anchoring (v0.2) makes them
stronger.

Docs: [looptail.ai/docs](https://looptail.ai/docs) · License: Apache-2.0
