Metadata-Version: 2.4
Name: zambo-smolagents
Version: 0.1.9
Summary: Verifiable execution receipts for smolagents agents. Every tool call mints a verifiable AER-1 receipt at zambo.dev.
Author-email: Zambo <brennanzambo@zambo.dev>
License: MIT
Project-URL: AER-1 standard, https://zambo.dev/aer1/
Project-URL: Add Zambo to your AI, https://zambo.dev/add
Project-URL: Homepage, https://zambo.dev
Project-URL: Documentation, https://zambo.dev/aer-1/
Keywords: smolagents,huggingface,agents,ai-agents,zambo,mcp,receipts,verification,verifiable-execution-receipts,execution-receipts,verifiable-receipt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: smolagents>=1.0
Dynamic: license-file

# zambo-smolagents

**AER-1, the agent execution receipt standard: [zambo.dev/aer-1](https://zambo.dev/aer-1/) | Add Zambo to your AI: [zambo.dev/add](https://zambo.dev/add)**

Zambo is the verifiable work layer for AI. This package connects smolagents agents to it, minting a verifiable AER-1 receipt for every tool call.

Receipt format: AER-1, IETF Internet-Draft [draft-zambo-aer1-26](https://datatracker.ietf.org/doc/draft-zambo-aer1/26/).

Verifiable execution receipts for smolagents agents. Give your smolagents agent Zambo's 153 live tools. Every tool call is executed by Zambo and mints a **verifiable AER-1 receipt**: a public URL carrying the tool, its arguments, the observed result, a SHA-256 fingerprint, and machine-readable JSON-LD.

```python
from smolagents import CodeAgent, InferenceClientModel
from zambo_smolagents import zambo_tools

agent = CodeAgent(
    tools=zambo_tools(["live_price", "prompt_shield"]),
    model=InferenceClientModel(),
)
agent.run("What is the live BTC price?")
```

No account. No API key. Free tier: 20 calls + 1 wrap-up free every day.

## What the receipt actually proves

Each receipt page (for example `https://zambo.dev/run/<id>`) is the public record of the call: the tool name, the exact arguments your agent sent, the observed result, a timestamp, and a SHA-256 fingerprint of the record, published as JSON-LD. Anyone can recompute the fingerprint and check that the saved result was not changed, with no account.

Every tool's output ends with the receipt URL (`Verifiable receipt: https://zambo.dev/run/<id>`), so the agent's trajectory shows proof next to every call. You can also collect receipts programmatically:

```python
from zambo_smolagents import zambo_tool

receipts = {}
tool = zambo_tool("live_price", on_receipt=lambda name, url: receipts.setdefault(name, []).append(url))
print(tool(arguments_json='{"symbol": "BTC"}'))
print(receipts)
```

## Install

```bash
pip install zambo-smolagents
```

## One tool, custom inputs

```python
from zambo_smolagents import zambo_tool

price_tool = zambo_tool(
    "live_price",
    inputs={
        "symbol": {"type": "string", "description": "Asset symbol, e.g. BTC."},
    },
)
print(price_tool(symbol="BTC"))
```

Browse the full catalog any time with `zambo_smolagents.list_tools()`, or pick tools by use case through Zambo's `capability_search` tool.

## Notes

- Zambo calls need no key and no signup. Heavy runs (dozens of tool calls) will reach the free daily limit; the tool raises a clear error and the agent run continues with the other tools.
- Receipts are public by design. Do not pass secrets as tool arguments.
- The client is pure stdlib (urllib) with retries: smolagents is the only third-party dependency.

## Links

- Zambo: https://zambo.dev
- AER-1 receipt spec: https://zambo.dev/aer-1/
- Framework agent execution receipts: https://zambo.dev/guides/framework-agent-execution-receipts/
- What is an AI agent execution receipt?: https://zambo.dev/guides/ai-agent-execution-receipt/

MIT License.

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

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

```python
from zambo_smolagents 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 ZAMBO-SMOLAGENTS`, naming this package as the recording system. They pass the same hash-recomputation check as any AER-1 receipt.
