aer1kit 0.1.0__py3-none-any.whl

aer1kit/__init__.py

@@ -0,0 +1,19 @@
+"""aer1kit: verifiable execution receipts for hackathon agents."""
+
+from .emitter import (
+    ReceiptEmitter,
+    merkle_root,
+    verify_receipt,
+    ZAMBO_MCP_URL,
+    ZAMBO_VERIFY_URL,
+)
+
+__all__ = [
+    "ReceiptEmitter",
+    "merkle_root",
+    "verify_receipt",
+    "ZAMBO_MCP_URL",
+    "ZAMBO_VERIFY_URL",
+]
+
+__version__ = "0.1.0"

aer1kit/emitter.py

@@ -0,0 +1,397 @@
+"""AER-1 receipt emitter for hackathon builders.
+
+Three lines and your agent emits verifiable execution receipts:
+
+    from aer1kit import ReceiptEmitter
+    emitter = ReceiptEmitter(goal="answer the user's question")
+    emitter.record("web_search", {"query": "AER-1", "results": 3})
+    url = emitter.mint()   # live verifiable receipt on zambo.dev
+
+No API keys. No signup. The basic flow is fully offline; mint() submits
+the receipt to the free zambo.dev verifier and returns a shareable URL.
+
+AER-1 is an IETF draft (draft-zambo-aer1). This emitter implements the
+Section 8 workflow receipt with the Section 8.1 Merkle construction.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+import uuid
+from datetime import datetime, timezone
+
+WORKFLOW_TYPE = "verifiable-workflow-receipt"
+WORKFLOW_VERSION = "1"
+
+ZAMBO_MCP_URL = "https://zambo.dev/mcp"
+ZAMBO_VERIFY_URL = "https://zambo.dev/verify"
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z"
+)
+_RFC3339_RE = re.compile(
+    r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}"
+    r"(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})\Z"
+)
+_HEX64_RE = re.compile(r"^[0-9a-f]{64}\Z")
+
+
+def _new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def _rfc3339(ts: float) -> str:
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _json_safe(value):
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, dict):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(v) for v in value]
+    if isinstance(value, set):
+        return sorted((_json_safe(v) for v in value), key=repr)
+    return str(value)
+
+
+def _canonical(obj) -> bytes:
+    return json.dumps(
+        _json_safe(obj),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def merkle_root(receipt_ids: list) -> str:
+    """AER-1 Section 8.1 normative Merkle construction.
+
+    leaf = SHA-256 over the UTF-8 bytes of receipt_id; internal node =
+    SHA-256 over raw 32-byte left || raw 32-byte right; an odd trailing
+    node is duplicated.
+    """
+    if not receipt_ids:
+        return hashlib.sha256(b"").hexdigest()
+    level = [hashlib.sha256(rid.encode("utf-8")).digest() for rid in receipt_ids]
+    while len(level) > 1:
+        if len(level) % 2:
+            level.append(level[-1])
+        level = [
+            hashlib.sha256(level[i] + level[i + 1]).digest()
+            for i in range(0, len(level), 2)
+        ]
+    return level[0].hex()
+
+
+def verify_receipt(workflow) -> list:
+    """Offline-verify an AER-1 workflow receipt.
+
+    Returns a list of failure reasons; [] means the receipt is valid.
+    """
+    failures = []
+    if not isinstance(workflow, dict):
+        return ["workflow is not a JSON object"]
+    if workflow.get("type") != WORKFLOW_TYPE:
+        failures.append('workflow type is not "verifiable-workflow-receipt"')
+    version = workflow.get("version")
+    if not isinstance(version, str) or not version:
+        failures.append("workflow version is not a non-empty string")
+    for field in ("workflow_id", "receipt_id"):
+        if not isinstance(workflow.get(field), str) or not _UUID_RE.match(
+            workflow.get(field)
+        ):
+            failures.append(f"workflow {field} is not a lowercase UUID")
+    if not isinstance(workflow.get("session_id"), str) or not workflow.get("session_id"):
+        failures.append("workflow session_id is not a non-empty string")
+    if not isinstance(workflow.get("goal"), str) or not workflow.get("goal"):
+        failures.append("workflow goal is not a non-empty string")
+    if not isinstance(workflow.get("status"), str) or not workflow.get("status"):
+        failures.append("workflow status is not a non-empty string")
+    oh = workflow.get("output_hash")
+    if not isinstance(oh, str) or not _HEX64_RE.match(oh):
+        failures.append("workflow output_hash is not a 64-char lowercase hex digest")
+    vu = workflow.get("verify_url")
+    if not isinstance(vu, str) or not (
+        vu.startswith("http://") or vu.startswith("https://")
+    ):
+        failures.append("workflow verify_url is not an http(s) URL string")
+    steps = workflow.get("steps")
+    if not isinstance(steps, list) or not steps:
+        failures.append("workflow steps is not a non-empty list")
+        return failures
+    for i, step in enumerate(steps):
+        if not isinstance(step, dict):
+            failures.append(f"step {i + 1} is not an object")
+            continue
+        seq = step.get("seq")
+        if isinstance(seq, bool) or not (
+            isinstance(seq, int) or (isinstance(seq, float) and seq.is_integer())
+        ):
+            failures.append(f"step {i + 1} seq is not an integer")
+        if not isinstance(step.get("receipt_id"), str):
+            failures.append(f"step {i + 1} receipt_id is not a string")
+        if not isinstance(step.get("tool"), str) or not step.get("tool"):
+            failures.append(f"step {i + 1} tool is not a non-empty string")
+        rh = step.get("receipt_hash")
+        if not isinstance(rh, str) or not _HEX64_RE.match(rh):
+            failures.append(
+                f"step {i + 1} receipt_hash is not a 64-char lowercase hex digest"
+            )
+        for ts_field in ("started_at", "ended_at"):
+            if not isinstance(step.get(ts_field), str) or not _RFC3339_RE.match(
+                step.get(ts_field)
+            ):
+                failures.append(
+                    f"step {i + 1} {ts_field} is not a valid RFC 3339 timestamp"
+                )
+        if not isinstance(step.get("status"), str) or not step.get("status"):
+            failures.append(f"step {i + 1} status is not a non-empty string")
+    if failures:
+        return failures
+    n = len(steps)
+    for i, step in enumerate(steps):
+        if step["seq"] != i + 1:
+            failures.append(
+                f"step seq values are not 1..{n} in order "
+                f"(index {i} carries seq {step['seq']})"
+            )
+            break
+    seen = set()
+    for step in steps:
+        rid = step["receipt_id"]
+        if rid in seen:
+            failures.append(f"duplicate receipt_id: {rid}")
+            break
+        seen.add(rid)
+    root = merkle_root([step["receipt_id"] for step in steps])
+    mr = workflow.get("merkle_root")
+    if not isinstance(mr, str) or mr != root:
+        failures.append("merkle_root does not match the recomputed Section 8.1 root")
+    return failures
+
+
+def _mint_audit_url(workflow, timeout=60) -> str:
+    """Submit a finalized AER-1 receipt to zambo.dev and return the live URL.
+
+    Free tier, no auth, no API keys. Every submission mints a verifiable
+    receipt at https://zambo.dev/run/<id>.
+    """
+    import urllib.error
+    import urllib.request
+
+    body = json.dumps(
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {
+                "name": "zambo_check",
+                "arguments": {
+                    "check": (
+                        "Verify this AER-1 verifiable workflow receipt: "
+                        "confirm the step sequence, receipt hashes, and "
+                        "Merkle root are well-formed."
+                    ),
+                    "context": json.dumps(
+                        _json_safe(workflow), ensure_ascii=False
+                    ),
+                    "type": "execution",
+                },
+            },
+        }
+    ).encode("utf-8")
+    last_error = None
+    for attempt in range(3):
+        try:
+            req = urllib.request.Request(
+                ZAMBO_MCP_URL,
+                data=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                },
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                raw = resp.read().decode("utf-8")
+            break
+        except Exception as exc:
+            last_error = exc
+            time.sleep(0.6 * (attempt + 1))
+    else:
+        raise RuntimeError(
+            f"zambo.dev mint failed after 3 attempts: {last_error}"
+        )
+
+    payload = None
+    text = raw.strip()
+    if text.startswith("{"):
+        payload = json.loads(text)
+    else:
+        for line in text.splitlines():
+            if line.startswith("data:"):
+                try:
+                    payload = json.loads(line[5:].strip())
+                except ValueError:
+                    continue
+                if payload:
+                    break
+    if not payload:
+        raise RuntimeError("zambo.dev mint returned an unreadable response")
+    if "error" in payload and payload["error"]:
+        raise RuntimeError(f"zambo.dev mint error: {payload['error']}")
+    result = payload.get("result") or {}
+    receipt = result.get("_receipt") or {}
+    audit = receipt.get("audit") or (
+        f"https://zambo.dev/run/{receipt['id']}" if receipt.get("id") else None
+    )
+    if not audit:
+        raise RuntimeError("zambo.dev mint returned no receipt id")
+    return audit
+
+
+class ReceiptEmitter:
+    """Emit AER-1 verifiable execution receipts for any agent.
+
+    Framework-independent: works with LangChain, CrewAI, raw API calls,
+    or a hand-rolled agent loop. Record one step per action your agent
+    takes; finalize when the run ends.
+
+        emitter = ReceiptEmitter(goal="book a flight to Austin")
+        emitter.record("search_flights", {"origin": "JFK", "dest": "AUS"})
+        emitter.record("book_flight", {"flight": "AA123", "price_usd": 249})
+        url = emitter.mint()   # live verifiable receipt
+    """
+
+    def __init__(self, goal=None, session_id=None, verify_url=None):
+        self._goal = goal
+        self._session_id = session_id or _new_uuid()
+        self._verify_url = verify_url or ZAMBO_VERIFY_URL
+        self._steps = []
+        self._seq = 0
+
+    def record(self, tool, evidence, status="ok", started=None, ended=None, **extra):
+        """Record one receipt step for an action the agent took.
+
+        tool: short label for the action (e.g. "web_search", "send_email").
+        evidence: dict of what the action observed or produced; the
+            receipt_hash commits to its canonical JSON, so anyone can
+            check later that the evidence has not changed.
+        status: "ok", "error", or "skipped".
+        extra: informational members, e.g. agent="planner", model="gpt-4o".
+            None values are dropped.
+        """
+        self._seq += 1
+        now = time.time()
+        if started is None:
+            started = now
+        if ended is None or ended < started:
+            ended = started
+        step = {
+            "seq": self._seq,
+            "receipt_id": _new_uuid(),
+            "tool": str(tool),
+            "receipt_hash": _sha256_hex(_canonical(evidence)),
+            "started_at": _rfc3339(started),
+            "ended_at": _rfc3339(ended),
+            "status": status,
+        }
+        for key, value in extra.items():
+            if value is not None:
+                step[key] = _json_safe(value)
+        self._steps.append(step)
+        return step
+
+    def finalize(self, final_answer=None) -> dict:
+        """Build the AER-1 verifiable workflow receipt for the run."""
+        status = "error" if any(s["status"] == "error" for s in self._steps) else "ok"
+        answer_text = "" if final_answer is None else str(final_answer)
+        return {
+            "type": WORKFLOW_TYPE,
+            "version": WORKFLOW_VERSION,
+            "workflow_id": _new_uuid(),
+            "receipt_id": _new_uuid(),
+            "session_id": self._session_id,
+            "goal": self._goal or "agent run",
+            "status": status,
+            "steps": list(self._steps),
+            "merkle_root": merkle_root([s["receipt_id"] for s in self._steps]),
+            "output_hash": _sha256_hex(answer_text.encode("utf-8")),
+            "verify_url": self._verify_url,
+        }
+
+    def verify(self, workflow=None) -> list:
+        """Offline-verify a receipt. [] means valid."""
+        if workflow is None:
+            workflow = self.finalize()
+        return verify_receipt(workflow)
+
+    def mint(self, final_answer=None) -> str:
+        """Finalize the run and mint a LIVE verifiable receipt on zambo.dev.
+
+        Returns the shareable audit URL (https://zambo.dev/run/<id>).
+        Free tier, no API key, no signup.
+        """
+        return _mint_audit_url(self.finalize(final_answer=final_answer))
+
+    def explain(self, final_answer=None) -> str:
+        """Render a human-readable "why" summary of the run.
+
+        Built for Track 02 ("The Agent That Can Explain Why"): every
+        step becomes one line of what the agent did and what evidence
+        it acted on, ending with the verification status.
+        """
+        workflow = self.finalize(final_answer=final_answer)
+        problems = verify_receipt(workflow)
+        lines = [
+            f"Goal: {workflow['goal']}",
+            f"Steps: {len(workflow['steps'])} (status: {workflow['status']})",
+            "",
+        ]
+        for step in workflow["steps"]:
+            lines.append(
+                f"{step['seq']}. {step['tool']} [{step['status']}] "
+                f"evidence sha256:{step['receipt_hash'][:12]}..."
+            )
+        lines.append("")
+        lines.append(f"Merkle root: {workflow['merkle_root'][:16]}...")
+        if problems:
+            lines.append("Verification: FAILED")
+            lines.extend(f"  - {p}" for p in problems)
+        else:
+            lines.append("Verification: VALID (offline check passed)")
+        lines.append(f"Check it live: {self._verify_url}")
+        return "\n".join(lines)
+
+    def to_json(self, final_answer=None, indent=2) -> str:
+        return json.dumps(
+            self.finalize(final_answer=final_answer),
+            indent=indent,
+            ensure_ascii=False,
+        )
+
+    def save(self, path, final_answer=None) -> str:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(self.to_json(final_answer=final_answer))
+        return path
+
+    def reset(self):
+        self._steps = []
+        self._seq = 0
+
+    @property
+    def step_count(self) -> int:
+        return len(self._steps)
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id

aer1kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+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

aer1kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+aer1kit/__init__.py,sha256=YScODcjnOr3DjBM95Iq6Y2XU5QCGBEotG9Y9dqrB4Pg,337
+aer1kit/emitter.py,sha256=V7ZO6TkAEdZ4fCo8rR_or6kdvhyM8kVSG_S9FBLSxGI,14619
+aer1kit-0.1.0.dist-info/METADATA,sha256=TnG6U-sWGLCuuGsIOZ3WpKKuitljZja50fgcSw2uPEs,4246
+aer1kit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+aer1kit-0.1.0.dist-info/top_level.txt,sha256=ZAvFhX_jxUxwthwTl1Ex6oFv45k2dx87oo8NW9Ug2wQ,8
+aer1kit-0.1.0.dist-info/RECORD,,

aer1kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aer1kit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aer1kit