Metadata-Version: 2.1
Name: zambo-haystack
Version: 0.2.7
Summary: Verifiable execution receipts for Haystack 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: haystack,deepset,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

# zambo-haystack

**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 Haystack 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 Haystack agents. Give your Haystack agent Zambo's 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 haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from zambo_haystack import zambo_tools

agent = Agent(
    chat_generator=OpenAIChatGenerator(),  # any Haystack chat generator works
    tools=zambo_tools(["live_price", "prompt_shield"]),
)
result = agent.run([{"role": "user", "content": "What is the live BTC price?"}])
```

Bring any Haystack chat generator (`OpenAIChatGenerator` above needs `OPENAI_API_KEY`; the Zambo calls themselves need no account and no key).
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 Haystack tool returned by `zambo_tool` appends the minted receipt URL to its result text, and records it in a registry you can query with `lookup_receipt(tool_name, arguments_json)`:

```python
from zambo_haystack import lookup_receipt

url = lookup_receipt("live_price", '{"symbol": "BTC"}')
print(url)  # https://zambo.dev/run/<id>
```

Or register a callback to capture each receipt as it is minted:

```python
from zambo_haystack import zambo_tool

price_tool = zambo_tool(
    "live_price",
    on_receipt=lambda tool, url: print(f"[receipt] {tool}: {url}"),
)
```

## Install

```bash
pip install zambo-haystack
```

## One tool, custom schema

```python
from zambo_haystack import zambo_tool

price_tool = zambo_tool(
    "live_price",
    params_json_schema={
        "type": "object",
        "properties": {"symbol": {"type": "string"}},
        "required": ["symbol"],
    },
)
```

Browse the full catalog any time with `zambo_haystack.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.
- The receipt registry is thread-safe and never breaks your run: the wrapper only reads and writes its own registry entry, and it ignores anything else in the pipeline.
- Receipts are public by design. Do not pass secrets as tool arguments.

## 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.

## Where these receipts run live: Zambo

zambo-haystack connects Haystack agents to Zambo, minting a verifiable AER-1 receipt for every tool call, and it has been downloaded 4,295 times on PyPI. The live home of those receipts is Zambo, the verifiable work layer for AI. Connect any AI to the live endpoint at https://zambo.dev/mcp or add Zambo to your AI in one step at https://zambo.dev/add/

Free tier: 20 calls + 1 wrap-up free every day; picking up in another AI is always free. The Day Pass is $0.99 for 24 hours, unlimited.

Install:

    pip install zambo-haystack
