aer1-haystack 0.1.0__tar.gz

aer1_haystack-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: aer1-haystack
+Version: 0.1.0
+Summary: One-line verifiable execution receipts for Haystack pipelines. Free, no API key, offline verification, chain-head anchoring to Nostr and Bitcoin.
+License: Apache-2.0
+Project-URL: Homepage, https://zambo.dev
+Project-URL: IETF Draft, https://datatracker.ietf.org/doc/draft-zambo-aer1/
+Keywords: aer-1,haystack,ai-agents,verifiable-receipts,audit,tracing,mcp,zambo,audit-trail
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: haystack-ai>=2.0.0
+Provides-Extra: anchor
+Requires-Dist: coincurve>=18.0; extra == "anchor"
+Requires-Dist: websocket-client>=1.7; extra == "anchor"
+
+# aer1-haystack
+
+One-line install, no API key, free forever: wrap one pipeline and every [Haystack](https://github.com/deepset-ai/haystack) 2.x run emits a hash-chained, offline-verifiable **verifiable workflow receipt** (AER-1, an IETF Internet-Draft, Section 8). What each component did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes, the collector only observes. Receipt chain heads can anchor to Nostr and Bitcoin, so anyone can later confirm the record was not changed, without trusting any server.
+
+## The AER-1 framework collector family
+
+The Haystack collector in the AER-1 framework collector family. Any agent running on these frameworks can emit verifiable AER-1 execution receipts: every step recorded, hash-chained, one Merkle root over the whole run.
+
+- [aer1-haystack](https://pypi.org/project/aer1-haystack/), Haystack 2.x pipelines via run wrapping
+- [aer1-langchain](https://pypi.org/project/aer1-langchain/), LangChain chains, agents, tools, and retrievers via callback handler
+- [aer1-llamaindex](https://pypi.org/project/aer1-llamaindex/), LlamaIndex agents via callback handler
+- [aer1-smolagents](https://pypi.org/project/aer1-smolagents/), SmolAgents agents via step callbacks
+- [aer1-openai-agents](https://pypi.org/project/aer1-openai-agents/), the OpenAI Agents SDK via its TracingProcessor
+- [aer1-crewai](https://pypi.org/project/aer1-crewai/), CrewAI crews via the event bus
+- [aer1-langgraph](https://pypi.org/project/aer1-langgraph/), LangGraph swarms via callback handler
+- [aer1-autogen](https://pypi.org/project/aer1-autogen/), AutoGen multi-agent chats
+- [aer1-pydantic](https://pypi.org/project/aer1-pydantic/), Pydantic AI agents via run wrapping and manual tool-call recording
+- [aer1-strands](https://pypi.org/project/aer1-strands/), Strands Agents via the typed hook system
+
+See the [AER-1 implementation registry](https://rambozambodotdev.gitlab.io/registry.html) for every implementation.
+
+## Install
+
+```bash
+pip install aer1-haystack
+```
+
+## Use it (copy, paste, run, no API keys needed)
+
+```python
+# pip install aer1-haystack
+from haystack import Pipeline, component
+from aer1_haystack import AER1ReceiptCollector
+
+
+@component
+class Adder:
+    @component.output_types(total=int)
+    def run(self, a: int, b: int):
+        return {"total": a + b}
+
+
+@component
+class Doubler:
+    @component.output_types(doubled=int)
+    def run(self, total: int):
+        return {"doubled": total * 2}
+
+
+pipeline = Pipeline()
+pipeline.add_component("adder", Adder())
+pipeline.add_component("doubler", Doubler())
+pipeline.connect("adder.total", "doubler.total")
+
+collector = AER1ReceiptCollector(goal="add and double")
+collector.wrap_pipeline(pipeline)  # line 1: pipeline.run is now observed
+
+result = pipeline.run({"adder": {"a": 2, "b": 3}})
+receipt = collector.finalize(final_answer=result)  # line 2
+assert collector.verify(receipt) == []  # VALID
+collector.save("receipt.json", workflow=receipt)
+```
+
+That is the whole integration: wrap the pipeline, run, finalize.
+The receipt is a plain JSON object you can store, ship to an auditor,
+or render in a UI.
+
+## What the receipt contains
+
+Workflow level (AER-1 Section 8, Table 2):
+
+- `type`, `version`, `workflow_id`, `receipt_id`, `session_id`
+- `goal`, `status`
+- `steps`: one record per component, seq 1..n in order
+- `merkle_root`: Section 8.1 root over the ordered step receipt ids
+- `output_hash`: SHA-256 of the final answer
+- `verify_url`: where the verification procedure is documented
+
+Step level (AER-1 Section 8, Table 3):
+
+- `seq`, `receipt_id`, `tool`, `receipt_hash`, `started_at`, `ended_at`, `status`
+
+Each step `receipt_hash` is SHA-256 over the canonical JSON of what the
+component actually did: component name, input values, output values, and
+error if any. The hash commits to the content; the receipt stays compact.
+The wrapper asks the pipeline to include every component's outputs
+(`include_outputs_from`), so intermediate components are recorded, not
+just leaf outputs.
+
+## Verification
+
+`collector.verify(receipt)` runs the full offline check and returns a
+list of failure reasons, empty when valid:
+
+- all Table 2 / Table 3 members present and well-formed
+- `seq` values exactly 1..n in order, no gaps
+- no two steps share a `receipt_id` (MM-1)
+- `merkle_root` matches the recomputed Section 8.1 root
+- strict RFC 3339 timestamps, lowercase UUIDs, 64-char hex digests
+
+Tamper with any field and verification fails. Try it:
+
+```python
+receipt["steps"][0]["tool"] = ""
+assert collector.verify(receipt) != []  # fails, as it should
+```
+
+## Manual instrumentation
+
+For components that need finer control, skip `wrap_pipeline` and record
+steps from inside a component's own `run()` method:
+
+```python
+collector = AER1ReceiptCollector(goal="manual run")
+
+@component
+class LoudAdder:
+    @component.output_types(total=int)
+    def run(self, a: int, b: int):
+        out = {"total": a + b}
+        collector.record_component(
+            "loud_adder", inputs={"a": a, "b": b}, outputs=out)
+        return out
+```
+
+`record_component(name, inputs, outputs, error=None)` takes the
+component name as the step's tool field. If the wrapped `pipeline.run`
+raises, a single error step named `pipeline` is recorded and the
+exception is re-raised unchanged.
+
+## Notes
+
+- Works with any Haystack 2.x `Pipeline`. The collector never touches
+  the network and never changes pipeline behavior; it only observes.
+- Pass `goal=` to the collector; it becomes the receipt's goal field.
+- `session_id` defaults to a fresh UUID per collector; pass your own to
+  correlate receipts across runs.
+- `verify_url` defaults to the AER-1 specification page; point it at
+  your own verifier in production.
+- Steps accumulate across runs on the same wrapped pipeline; call
+  `collector.reset()` between runs to start fresh.
+
+## Spec
+
+AER-1: Agent Execution Receipts, `draft-zambo-aer1` (IETF Internet-Draft),
+https://datatracker.ietf.org/doc/draft-zambo-aer1/
+
+## See it live
+
+Your receipt is offline-verifiable, but you can also check it on the live verifier:
+
+1. Copy the receipt JSON your code produced
+2. Paste it at https://zambo.dev/verify
+3. See the verification result with the Merkle root and step hashes
+
+Or mint a live receipt directly: run any call at https://zambo.dev/demo and get a shareable receipt URL like https://zambo.dev/run/<id>.
+
+## License
+
+Apache-2.0

aer1_haystack-0.1.0/README.md

@@ -0,0 +1,160 @@
+# aer1-haystack
+
+One-line install, no API key, free forever: wrap one pipeline and every [Haystack](https://github.com/deepset-ai/haystack) 2.x run emits a hash-chained, offline-verifiable **verifiable workflow receipt** (AER-1, an IETF Internet-Draft, Section 8). What each component did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes, the collector only observes. Receipt chain heads can anchor to Nostr and Bitcoin, so anyone can later confirm the record was not changed, without trusting any server.
+
+## The AER-1 framework collector family
+
+The Haystack collector in the AER-1 framework collector family. Any agent running on these frameworks can emit verifiable AER-1 execution receipts: every step recorded, hash-chained, one Merkle root over the whole run.
+
+- [aer1-haystack](https://pypi.org/project/aer1-haystack/), Haystack 2.x pipelines via run wrapping
+- [aer1-langchain](https://pypi.org/project/aer1-langchain/), LangChain chains, agents, tools, and retrievers via callback handler
+- [aer1-llamaindex](https://pypi.org/project/aer1-llamaindex/), LlamaIndex agents via callback handler
+- [aer1-smolagents](https://pypi.org/project/aer1-smolagents/), SmolAgents agents via step callbacks
+- [aer1-openai-agents](https://pypi.org/project/aer1-openai-agents/), the OpenAI Agents SDK via its TracingProcessor
+- [aer1-crewai](https://pypi.org/project/aer1-crewai/), CrewAI crews via the event bus
+- [aer1-langgraph](https://pypi.org/project/aer1-langgraph/), LangGraph swarms via callback handler
+- [aer1-autogen](https://pypi.org/project/aer1-autogen/), AutoGen multi-agent chats
+- [aer1-pydantic](https://pypi.org/project/aer1-pydantic/), Pydantic AI agents via run wrapping and manual tool-call recording
+- [aer1-strands](https://pypi.org/project/aer1-strands/), Strands Agents via the typed hook system
+
+See the [AER-1 implementation registry](https://rambozambodotdev.gitlab.io/registry.html) for every implementation.
+
+## Install
+
+```bash
+pip install aer1-haystack
+```
+
+## Use it (copy, paste, run, no API keys needed)
+
+```python
+# pip install aer1-haystack
+from haystack import Pipeline, component
+from aer1_haystack import AER1ReceiptCollector
+
+
+@component
+class Adder:
+    @component.output_types(total=int)
+    def run(self, a: int, b: int):
+        return {"total": a + b}
+
+
+@component
+class Doubler:
+    @component.output_types(doubled=int)
+    def run(self, total: int):
+        return {"doubled": total * 2}
+
+
+pipeline = Pipeline()
+pipeline.add_component("adder", Adder())
+pipeline.add_component("doubler", Doubler())
+pipeline.connect("adder.total", "doubler.total")
+
+collector = AER1ReceiptCollector(goal="add and double")
+collector.wrap_pipeline(pipeline)  # line 1: pipeline.run is now observed
+
+result = pipeline.run({"adder": {"a": 2, "b": 3}})
+receipt = collector.finalize(final_answer=result)  # line 2
+assert collector.verify(receipt) == []  # VALID
+collector.save("receipt.json", workflow=receipt)
+```
+
+That is the whole integration: wrap the pipeline, run, finalize.
+The receipt is a plain JSON object you can store, ship to an auditor,
+or render in a UI.
+
+## What the receipt contains
+
+Workflow level (AER-1 Section 8, Table 2):
+
+- `type`, `version`, `workflow_id`, `receipt_id`, `session_id`
+- `goal`, `status`
+- `steps`: one record per component, seq 1..n in order
+- `merkle_root`: Section 8.1 root over the ordered step receipt ids
+- `output_hash`: SHA-256 of the final answer
+- `verify_url`: where the verification procedure is documented
+
+Step level (AER-1 Section 8, Table 3):
+
+- `seq`, `receipt_id`, `tool`, `receipt_hash`, `started_at`, `ended_at`, `status`
+
+Each step `receipt_hash` is SHA-256 over the canonical JSON of what the
+component actually did: component name, input values, output values, and
+error if any. The hash commits to the content; the receipt stays compact.
+The wrapper asks the pipeline to include every component's outputs
+(`include_outputs_from`), so intermediate components are recorded, not
+just leaf outputs.
+
+## Verification
+
+`collector.verify(receipt)` runs the full offline check and returns a
+list of failure reasons, empty when valid:
+
+- all Table 2 / Table 3 members present and well-formed
+- `seq` values exactly 1..n in order, no gaps
+- no two steps share a `receipt_id` (MM-1)
+- `merkle_root` matches the recomputed Section 8.1 root
+- strict RFC 3339 timestamps, lowercase UUIDs, 64-char hex digests
+
+Tamper with any field and verification fails. Try it:
+
+```python
+receipt["steps"][0]["tool"] = ""
+assert collector.verify(receipt) != []  # fails, as it should
+```
+
+## Manual instrumentation
+
+For components that need finer control, skip `wrap_pipeline` and record
+steps from inside a component's own `run()` method:
+
+```python
+collector = AER1ReceiptCollector(goal="manual run")
+
+@component
+class LoudAdder:
+    @component.output_types(total=int)
+    def run(self, a: int, b: int):
+        out = {"total": a + b}
+        collector.record_component(
+            "loud_adder", inputs={"a": a, "b": b}, outputs=out)
+        return out
+```
+
+`record_component(name, inputs, outputs, error=None)` takes the
+component name as the step's tool field. If the wrapped `pipeline.run`
+raises, a single error step named `pipeline` is recorded and the
+exception is re-raised unchanged.
+
+## Notes
+
+- Works with any Haystack 2.x `Pipeline`. The collector never touches
+  the network and never changes pipeline behavior; it only observes.
+- Pass `goal=` to the collector; it becomes the receipt's goal field.
+- `session_id` defaults to a fresh UUID per collector; pass your own to
+  correlate receipts across runs.
+- `verify_url` defaults to the AER-1 specification page; point it at
+  your own verifier in production.
+- Steps accumulate across runs on the same wrapped pipeline; call
+  `collector.reset()` between runs to start fresh.
+
+## Spec
+
+AER-1: Agent Execution Receipts, `draft-zambo-aer1` (IETF Internet-Draft),
+https://datatracker.ietf.org/doc/draft-zambo-aer1/
+
+## See it live
+
+Your receipt is offline-verifiable, but you can also check it on the live verifier:
+
+1. Copy the receipt JSON your code produced
+2. Paste it at https://zambo.dev/verify
+3. See the verification result with the Merkle root and step hashes
+
+Or mint a live receipt directly: run any call at https://zambo.dev/demo and get a shareable receipt URL like https://zambo.dev/run/<id>.
+
+## License
+
+Apache-2.0

aer1_haystack-0.1.0/aer1_haystack/__init__.py

@@ -0,0 +1,39 @@
+"""aer1-haystack: AER-1 verifiable workflow receipts for Haystack."""
+
+from .anchor import (
+    AnchorError,
+    NostrBackend,
+    OTSBackend,
+    anchor_chain_head,
+    bip340_verify,
+    proof_from_json,
+    proof_to_json,
+    verify_anchor,
+)
+from .collector import (
+    AER1ReceiptCollector,
+    DEFAULT_VERIFY_URL,
+    WORKFLOW_TYPE,
+    WORKFLOW_VERSION,
+    merkle_root,
+    verify_workflow_receipt,
+)
+
+__all__ = [
+    "AER1ReceiptCollector",
+    "DEFAULT_VERIFY_URL",
+    "WORKFLOW_TYPE",
+    "WORKFLOW_VERSION",
+    "AnchorError",
+    "NostrBackend",
+    "OTSBackend",
+    "anchor_chain_head",
+    "bip340_verify",
+    "merkle_root",
+    "proof_from_json",
+    "proof_to_json",
+    "verify_anchor",
+    "verify_workflow_receipt",
+]
+
+__version__ = "0.1.0"