Metadata-Version: 2.1
Name: aer1kit
Version: 0.1.14
Summary: AER-1 conformance kit: mint and verify verifiable execution receipts for AI agents. Implements IETF Internet-Draft draft-zambo-aer1-26. Kit 1.5.7, 126 test vectors and 129 checks, offline verification, no dependencies.
Author: Brennan Zambo
License: Apache-2.0
Project-URL: Homepage, https://zambo.dev
Project-URL: AER-1 standard, https://zambo.dev/aer1/
Project-URL: Add Zambo to your AI, https://zambo.dev/add
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/
Project-URL: Issues, https://gitlab.com/rambozambodotdev/zambo/-/issues
Project-URL: Repository, https://gitlab.com/rambozambodotdev/zambo
Project-URL: Conformance corpus (Zenodo), https://zenodo.org/records/23677115
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

**AER-1, the agent execution receipt standard: [zambo.dev/aer-1](https://zambo.dev/aer-1/) | Add Zambo to your AI: [zambo.dev/add](https://zambo.dev/add)**

Zambo is the verifiable work layer for AI. This kit implements its receipt format, AER-1.

## 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-26](https://datatracker.ietf.org/doc/draft-zambo-aer1/26/). 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


## Permanent archive

The conformance corpus in this kit is permanently archived on Zenodo: https://zenodo.org/records/23677115 (DOI: https://doi.org/10.5281/zenodo.23677115).

## The kit, and the live layer behind it: Zambo

aer1kit is the AER-1 conformance kit: it mints and verifies verifiable execution receipts for AI agents, and it has been downloaded 5,349 times on PyPI. The receipts it mints and checks belong to Zambo, the verifiable work layer for AI. Connect any AI to the live endpoint at https://zambo.dev/mcp or add Zambo to your AI in one step at https://zambo.dev/add/

Free tier: 20 calls + 1 wrap-up free every day; picking up in another AI is always free. The Day Pass is $0.99 for 24 hours, unlimited.

Install:

    pip install aer1kit
