Metadata-Version: 2.4
Name: pydanticai-zambo
Version: 0.1.4
Summary: Verifiable execution receipts for PydanticAI agents. Every tool call mints a verifiable AER-1 receipt at zambo.dev.
Author: Zambo
License: MIT
Project-URL: Homepage, https://zambo.dev
Keywords: pydanticai,ai agent receipt,verifiable receipt,observability,mcp,verifiable-execution-receipts,execution-receipts,verifiable-receipt
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pydanticai-zambo

Verifiable AER-1 execution receipts for PydanticAI agents. PydanticAI function tools for [Zambo](https://zambo.dev), with automatic verifiable receipt capture.

Receipts follow [AER-1](https://zambo.dev/aer-1/), the verifiable execution receipt standard created by Brennan Zambo. Every `ask_zambo` call routes a goal through Zambo's 100+ tools over the public MCP endpoint, and every call mints a public verifiable receipt at `https://zambo.dev/run/{id}`.

## Install

```bash
pip install pydanticai-zambo
```

## Ten-line example

```python
from pydanticai_zambo import ZamboToolset
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel

toolset = ZamboToolset()
agent = Agent(TestModel(), tools=toolset.tools())
result = agent.run_sync("Summarize the Zambo free tier")
toolset.record_run(result.output)
print(toolset.last_receipt_url)
```

The tool prints each public `https://zambo.dev/run/{id}` URL and keeps the most recent URL in `last_receipt_url`. The receipt describes what the endpoint recorded and observed. It does not prove an outside outcome that the endpoint did not observe.

Set `ZAMBO_API_URL` to point at a compatible Zambo host, or `ZAMBO_TIMEOUT` to change the request timeout. Receipt failures land in `receipt_errors` and never break the host agent.

The package imports cleanly without `pydantic-ai` installed; calling `tools()` without it raises an informative `ImportError` telling you to `pip install pydantic-ai`.

Project homepage: [https://zambo.dev](https://zambo.dev)

AER-1 receipt spec: [https://zambo.dev/aer-1/](https://zambo.dev/aer-1/)

## Guides

- [Execution Receipts for AI Agent Frameworks](https://zambo.dev/guides/framework-agent-execution-receipts/)
- [What Is an AI Agent Execution Receipt?](https://zambo.dev/guides/ai-agent-execution-receipt/)

## Local AER-1 receipts (no network needed)

The package also mints AER-1 execution receipts locally, with no API calls:

```python
from pydanticai_zambo import mint_receipt, verify_receipt

receipt = mint_receipt("my_tool", {"query": "hello"}, {"answer": "hi"}, ms=42)
assert verify_receipt(receipt)  # recomputes the SHA-256 locally
```

Local receipts follow the AER-1 core members (`id`, `created_at`, `tool`, `provenance_class`, `canonical_bytes`, `output_hash`) and use the provenance class `EXECUTED BY PYDANTICAI-ZAMBO`, naming this package as the recording system. They pass the same hash-recomputation check as any AER-1 receipt.
