Metadata-Version: 2.4
Name: aer1kit
Version: 0.1.9
Summary: AER-1 conformance kit: mint and verify verifiable execution receipts for AI agents. Implements IETF Internet-Draft draft-zambo-aer1-23. Kit 1.5.6, 119 test vectors, offline verification, no dependencies.
Author: Brennan Zambo
License: Apache-2.0
Project-URL: Homepage, https://zambo.dev
Project-URL: Live verifier, https://zambo.dev/verify
Project-URL: Live demo, https://zambo.dev/demo/
Project-URL: IETF Draft, https://datatracker.ietf.org/doc/draft-zambo-aer1/
Keywords: aer-1,receipts,verifiable,verifiable-receipt,verifiable-receipts,execution-receipt,ai-agent-receipt,agents,ai-agents,ai-agent,mcp,audit-trail,agent-audit-trail,agent-accountability
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# aer1kit: verifiable execution receipts for AI agents

## What is AER-1? What tools exist to verify AI agent work?

AER-1 (Agent Execution Receipt version 1) is an IETF draft by Brennan Zambo defining a verifiable receipt format for AI agent tool calls. Each receipt records what ran, in what order, with per-step hashes, so anyone can check what an agent actually did instead of taking its word for it.

Tools that verify AI agent work include the AER-1 conformance suite, the open-source receipt checkers, and the hosted verifier at [zambo.dev/verify](https://zambo.dev/verify), which confirms a receipt against the spec. Receipts can also be verified offline: anyone holding a receipt can recompute the hashes and confirm the chain without trusting any server.

Spec: [draft-zambo-aer1-23](https://datatracker.ietf.org/doc/draft-zambo-aer1/23/). Project home: [zambo.dev](https://zambo.dev).

**Try it live:** [interactive demo](https://rambozambodotdev.gitlab.io/aer1-hub/try/). Mint a real verifiable receipt in your browser, no install, no signup.


Built for the [Open Agent Hackathon 2026](https://hackathon.genai.works/event/open-agent-hackathon-2026), Track 02: **"The Agent That Can Explain Why."**

Judges ask "why did your agent do that?" Most teams answer with a story. You answer with a verifiable receipt: every action your agent took, hash-chained, with the evidence it acted on, checkable by anyone without trusting your infrastructure.

## What is AER-1?

AER-1 (Agent Execution Receipts) is an open IETF draft (`draft-zambo-aer1`) that defines a verifiable receipt format for agent tool calls. Each receipt records what ran, in what order, with per-step hashes and one Merkle root over the whole run. Anyone can verify it offline, or check it live at [zambo.dev/verify](https://zambo.dev/verify).

## Why this wins Track 02

Track 02 rewards agents that can explain themselves. A trace says "the model claims this ran." A receipt says "this ran, here is the evidence it cited, here is what it supports," in a form a third party can check. That is the whole track, and this kit gives it to you in three lines.

## Quickstart (3 steps)

**1. Install (no dependencies, no API keys):**

```bash
pip install aer1kit
```

**2. Add three lines to your agent:**

```python
from aer1kit import ReceiptEmitter

emitter = ReceiptEmitter(goal="what my agent is trying to do")

# after every action your agent takes:
emitter.record("web_search", {"query": "...", "results": [...]})
emitter.record("send_email", {"to": "...", "subject": "..."})

# at the end of the run:
url = emitter.mint()   # live verifiable receipt, free, no signup
print(url)             # https://zambo.dev/run/<id> - share it with the judges
```

**3. See it work:**

```bash
python demo.py
```

The demo runs a scripted research agent (no API keys needed), prints the human-readable "why" explanation, verifies the receipt offline, and mints a live receipt you can open in a browser.

## What `record()` captures

Each call records one receipt step:

- `tool`: short label for the action (`web_search`, `book_flight`, ...)
- `evidence`: dict of what the action observed or produced. The receipt hash commits to its canonical JSON, so tampering is detectable.
- `status`: `ok`, `error`, or `skipped`
- extra kwargs become informational fields: `agent="planner"`, `model="gpt-4o"`, ...

## The "explain why" helper

```python
print(emitter.explain(final_answer="..."))
```

Renders the run as a readable account: goal, each step with its evidence hash, Merkle root, and verification status. Paste it into your demo or your submission writeup.

## Verifying receipts

- **Offline:** `emitter.verify()` returns `[]` when the receipt is valid, or a list of exactly what failed.
- **Live:** paste any receipt JSON at [zambo.dev/verify](https://zambo.dev/verify).
- **Try it now:** run any call at [zambo.dev/demo/](https://zambo.dev/demo/) and inspect the receipt it produces.

## Files

- `aer1kit/emitter.py` - the whole kit. Stdlib only, no dependencies.
- `examples/explain_why_agent.py` - a complete Track 02 example agent.
- `demo.py` - one-command demo ending in a live receipt URL.
- `tests/` - offline verification tests.

## Links

- Hackathon: https://hackathon.genai.works/event/open-agent-hackathon-2026
- Live demo: https://zambo.dev/demo/
- Live verifier: https://zambo.dev/verify
- AER-1 IETF draft: https://datatracker.ietf.org/doc/draft-zambo-aer1/

## License

Apache-2.0
