Metadata-Version: 2.5
Name: smolagents-aer1
Version: 0.1.0
Summary: AER-1 verifiable execution receipts for smolagents agents: one checkable receipt per tool call.
Project-URL: Homepage, https://zambo.dev
Project-URL: Spec (IETF draft), https://datatracker.ietf.org/doc/draft-zambo-aer1/
Project-URL: Conformance kit, https://gitlab.com/rambozambodotdev/zambo
Author: Brennan Zambo
License: MIT
License-File: LICENSE
Keywords: aer-1,ai-agents,audit,receipts,smolagents,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: smolagents>=1.0
Description-Content-Type: text/markdown

# smolagents-aer1

Every tool call your smolagents agent makes, recorded as an AER-1 verifiable execution receipt. Five lines of code. No new infrastructure.

AER-1 is an open IETF Internet-Draft (draft-zambo-aer1) defining a small vocabulary for recording one AI agent tool call as a portable, independently checkable receipt. A receipt proves the recorded result was not changed. It does not prove the tool was correct.

## Install

```bash
pip install smolagents-aer1
```

## 10-minute quickstart

```python
from smolagents import CodeAgent, InferenceClientModel
from smolagents_aer1 import AER1Recorder

recorder = AER1Recorder()
agent = CodeAgent(
    tools=[],
    model=InferenceClientModel(),
    step_callbacks=[recorder],
)
agent.run("What is 17 * 24?")

print(f"{len(recorder.receipts)} receipts recorded")
recorder.save("receipts.jsonl")
```

That is the whole integration. `step_callbacks` is smolagents' blessed hook for observing steps (the same pattern tracing integrations use). The recorder watches each action step and emits one receipt per tool call.

## What a receipt looks like

```json
{
  "id": "3f9a2c1e-7b4d-4f8a-9c2e-1a5b6d7e8f90",
  "receipt_schema_version": "0.3",
  "created_at": "2026-10-05T21:20:00.123456Z",
  "tool": {"name": "python_interpreter", "version": "1.26.0", "scope": "public"},
  "provenance_class": "EXECUTED BY SMOLAGENTS",
  "canonical_bytes": "eyJpbnB1dHMiOi...",
  "output_hash": "sha256:9f2c...",
  "verification_status": "verified"
}
```

The canonical bytes are a deterministic JSON payload (`tool`, `inputs`, `output`). Anyone can base64-decode them, recompute SHA-256, and compare with `output_hash`. That is the entire verification procedure.

## Verify a receipt yourself

```python
from smolagents_aer1 import verify_receipt

failures = verify_receipt(recorder.receipts[0])
assert failures == [], failures
print("receipt checks out")
```

Or run the full open conformance suite against your receipts: https://gitlab.com/rambozambodotdev/zambo

## Notes

- Provenance class is `EXECUTED BY SMOLAGENTS`: the recorder runs inside the agent process and records what the agent did.
- `CodeAgent` records each code execution as one `python_interpreter` tool call. `ToolCallingAgent` records each named tool call separately.
- When one step contains several tool calls, each receipt commits to the step's full observation string.
- The `tool.version` field records the smolagents runtime version.
- Receipts are local JSON. Nothing is sent anywhere. Publishing or anchoring them is your choice.

## Links

- Spec: https://datatracker.ietf.org/doc/draft-zambo-aer1/ (IETF Internet-Draft, informational)
- Conformance kit: https://gitlab.com/rambozambodotdev/zambo
- Zambo: https://zambo.dev

## License

MIT. See LICENSE.
