Metadata-Version: 2.4
Name: zambo-haystack
Version: 0.1.1
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: Homepage, https://zambo.dev
Project-URL: Documentation, https://zambo.dev/aer-1/
Project-URL: Repository, https://zambo.dev
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
Requires-Dist: haystack-ai>=2.0
Dynamic: license-file

# zambo-haystack

Verifiable execution receipts for Haystack agents. Give your Haystack agent Zambo's 100+ 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 per tool per day.

## What the receipt actually proves

Each receipt page (for example `https://zambo.dev/run/<id>`) is Zambo's tamper-evident record that **Zambo executed the tool call itself**: 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 re-verify it 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/

MIT License.
