Metadata-Version: 2.4
Name: aer1kit
Version: 0.1.0
Summary: Verifiable AER-1 execution receipts for hackathon agents. Three lines and your agent can explain why.
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,agents,hackathon,verifiable,mcp
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 your hackathon agent

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. Clone and install (no dependencies, no API keys):**

```bash
git clone <this-repo>
cd aer1-hackathon-kit
pip install .
```

**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
