Metadata-Version: 2.4
Name: aer1kit
Version: 0.1.17
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, 143 test vectors and 146 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 (live counts: https://zambo.dev/numbers/). 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.

## Chain it: a job, not a lookup

One call answers a question. A job chains calls and ends in a record a person can open. Same agent, longer instruction:

```text
Check the live price of BTC, ETH and SOL, save the run to memory, then wrap it into a handover addressed to Dana Whitfield, with the receipt link for every call.
```

The kit receipts every call in the chain; when the agent's tools are Zambo's, the wrap is the handover call at the end of the run.

Three prices, a save and the wrap fit inside one free day: every tool free once a day, plus 3 continue calls, and one free wrap-up handover per day. A longer run finishes in one sitting on a Day Pass ($0.99, unlimited for 24 hours). The handover is the part the person opens: the steps, the saved results, and the receipt for every call, checkable instead of trusted. Ready-made run cards for jobs shaped like this: https://rambozambodotdev.gitlab.io/aer1-hub/handover-templates.html

## 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. 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: every tool free once a day, plus 3 continue calls; picking up in another AI is always free. The Day Pass is $0.99 for 24 hours, unlimited.

Install:

    pip install aer1kit
