Metadata-Version: 2.4
Name: aer1-pydantic
Version: 0.1.0
Summary: One-line verifiable execution receipts for Pydantic AI agents. Free, no API key, offline verification, chain-head anchoring to Nostr and Bitcoin.
License: Apache-2.0
Project-URL: Homepage, https://zambo.dev
Project-URL: IETF Draft, https://datatracker.ietf.org/doc/draft-zambo-aer1/
Keywords: aer-1,pydantic-ai,pydantic,ai-agents,verifiable-receipts,audit,tracing,mcp,zambo,audit-trail
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic-ai>=0.1.0
Provides-Extra: anchor
Requires-Dist: coincurve>=18.0; extra == "anchor"
Requires-Dist: websocket-client>=1.7; extra == "anchor"

# aer1-pydantic

One-line install, no API key, free forever: wrap one collector around your [Pydantic AI](https://github.com/pydantic/pydantic-ai) agent and every run emits a hash-chained, offline-verifiable **verifiable workflow receipt** (AER-1, an IETF Internet-Draft, Section 8). What the agent did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes, the collector only observes. Receipt chain heads can anchor to Nostr and Bitcoin, so anyone can later confirm the record was not changed, without trusting any server.

## The AER-1 framework collector family

The Pydantic AI collector in the AER-1 framework collector family. Any agent running on these frameworks can emit verifiable AER-1 execution receipts: every step recorded, hash-chained, one Merkle root over the whole run.

- [aer1-pydantic](https://pypi.org/project/aer1-pydantic/), Pydantic AI agents via run wrapping and manual tool-call recording
- [aer1-langchain](https://pypi.org/project/aer1-langchain/), LangChain chains, agents, tools, and retrievers via callback handler
- [aer1-llamaindex](https://pypi.org/project/aer1-llamaindex/), LlamaIndex agents via callback handler
- [aer1-smolagents](https://pypi.org/project/aer1-smolagents/), SmolAgents agents via step callbacks
- [aer1-openai-agents](https://pypi.org/project/aer1-openai-agents/), the OpenAI Agents SDK via its TracingProcessor
- [aer1-crewai](https://pypi.org/project/aer1-crewai/), CrewAI crews via the event bus
- [aer1-langgraph](https://pypi.org/project/aer1-langgraph/), LangGraph swarms via callback handler
- [aer1-autogen](https://pypi.org/project/aer1-autogen/), AutoGen multi-agent chats
- [aer1-haystack](https://pypi.org/project/aer1-haystack/), Haystack 2.x pipelines via run wrapping
- [aer1-strands](https://pypi.org/project/aer1-strands/), Strands Agents via the typed hook system

See the [AER-1 implementation registry](https://rambozambodotdev.gitlab.io/registry.html) for every implementation.

## Install

```bash
pip install aer1-pydantic
```

## Use it (copy, paste, run, no API keys needed)

```python
# pip install aer1-pydantic
from aer1_pydantic import AER1ReceiptCollector
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel

collector = AER1ReceiptCollector(goal="Check the Paris weather")

agent = Agent(TestModel())  # swap for your real model in production

@agent.tool_plain
def get_weather(location: str) -> str:
    out = f"Sunny, 22C in {location}"
    collector.record_tool_call("get_weather", {"location": location}, out)
    return out

collector.wrap_agent(agent)  # line 1

result = agent.run_sync("What is the weather in Paris?")
receipt = collector.finalize(final_answer=str(result.output))  # line 2
assert collector.verify(receipt) == []  # VALID
collector.save("receipt.json", workflow=receipt)
```

That is the whole integration: wrap the agent, run, finalize.
The receipt is a plain JSON object you can store, ship to an auditor,
or render in a UI.

Two recording modes, and they compose:

- `wrap_agent(agent)` patches `agent.run()` and `agent.run_sync()` to
  record each completed run from the result's message history. Every
  tool call becomes a step (tool name, arguments, tool returns); a
  model response with no tool calls becomes a single `"model"` step.
  The wrappers call the original methods unchanged, so agent behavior
  is identical with or without the collector.
- `record_tool_call(name, args, result, error=None)` records one tool
  call manually, for use inside `@agent.tool_plain` functions when you
  want the tool's own view of what happened.

## What the receipt contains

Workflow level (AER-1 Section 8, Table 2):

- `type`, `version`, `workflow_id`, `receipt_id`, `session_id`
- `goal`, `status`
- `steps`: one record per agent step, seq 1..n in order
- `merkle_root`: Section 8.1 root over the ordered step receipt ids
- `output_hash`: SHA-256 of the final answer
- `verify_url`: where the verification procedure is documented

Step level (AER-1 Section 8, Table 3):

- `seq`, `receipt_id`, `tool`, `receipt_hash`, `started_at`, `ended_at`, `status`

Each step `receipt_hash` is SHA-256 over the canonical JSON of what the
step actually did: tool name, arguments, observations, and error if any.
The hash commits to the content; the receipt stays compact.

## Verification

`collector.verify(receipt)` runs the full offline check and returns a
list of failure reasons, empty when valid:

- all Table 2 / Table 3 members present and well-formed
- `seq` values exactly 1..n in order, no gaps
- no two steps share a `receipt_id` (MM-1)
- `merkle_root` matches the recomputed Section 8.1 root
- strict RFC 3339 timestamps, lowercase UUIDs, 64-char hex digests

Tamper with any field and verification fails. Try it:

```python
receipt["steps"][0]["tool"] = ""
assert collector.verify(receipt) != []  # fails, as it should
```

## Notes

- Works with `agent.run()` (async) and `agent.run_sync()`. If
  `run_sync` delegates to `run` internally, the outermost call is
  recorded once, never double-counted.
- Pass `goal=` to the collector; when no goal is given, the prompt of
  the first wrapped run is used as the goal.
- `session_id` defaults to a fresh UUID per collector; pass your own to
  correlate receipts across runs.
- `verify_url` defaults to the AER-1 specification page; point it at
  your own verifier in production.
- Recording a failed tool call: pass `error=` to `record_tool_call`;
  the step is marked `"error"` and the workflow status becomes
  `"error"` at `finalize()`.

## Spec

AER-1: Agent Execution Receipts, IETF Internet-Draft
`draft-zambo-aer1`,
https://datatracker.ietf.org/doc/draft-zambo-aer1/

## See it live

Your receipt is offline-verifiable, but you can also check it on the live verifier:

1. Copy the receipt JSON your code produced
2. Paste it at https://zambo.dev/verify
3. See the verification result with the Merkle root and step hashes

Or mint a live receipt directly: run any call at https://zambo.dev/demo and get a shareable receipt URL like https://zambo.dev/run/<id>.

## License

Apache-2.0
