aer1-strands 0.1.0__tar.gz

aer1_strands-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: aer1-strands
+Version: 0.1.0
+Summary: One-line verifiable execution receipts for Strands Agents. 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,strands,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: strands-agents>=1.0
+Provides-Extra: anchor
+Requires-Dist: coincurve>=18.0; extra == "anchor"
+Requires-Dist: websocket-client>=1.7; extra == "anchor"
+
+# aer1-strands
+
+One-line install, no API key, free forever: attach this collector to an `Agent` and every [Strands Agents](https://strandsagents.com/) run emits a hash-chained, offline-verifiable **verifiable workflow receipt** (AER-1, an IETF Internet-Draft, Section 8). What the agent did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes: every hook callback returns `None`, so Strands executes exactly as it would without us. 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 Strands 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-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.
+- [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-haystack](https://pypi.org/project/aer1-haystack/), Haystack 2.x pipelines via run wrapping
+- [aer1-pydantic](https://pypi.org/project/aer1-pydantic/), Pydantic AI agents via run wrapping and manual tool-call recording
+
+## Install
+
+```bash
+pip install aer1-strands
+```
+
+## Use it (copy, paste, run, no API keys needed)
+
+```python
+# pip install aer1-strands
+from aer1_strands import AER1StrandsCollector
+from strands.hooks import HookRegistry
+from strands.hooks.events import (
+    BeforeModelCallEvent, AfterModelCallEvent,
+    BeforeToolCallEvent, AfterToolCallEvent,
+)
+
+class FakeAgent:
+    """Stand-in for strands.Agent: a name plus a real HookRegistry."""
+    def __init__(self, name="assistant"):
+        self.name = name
+        self.hooks = HookRegistry()
+
+def get_weather(location: str) -> str:
+    """Local mock tool: executed on this machine, no network."""
+    return f"Sunny, 22C in {location}"
+
+collector = AER1StrandsCollector(goal="check the Paris weather")
+agent = FakeAgent("assistant")
+collector.attach(agent)  # line 1: register the hooks
+
+# A two-step flow: model reasoning, then a tool call. In production
+# Strands fires these events itself as your real agent runs, so you
+# call collector.attach(your_real_agent) instead of this script.
+agent.hooks.invoke_callbacks(BeforeModelCallEvent(
+    agent=agent, invocation_state={}, projected_input_tokens=96))
+agent.hooks.invoke_callbacks(AfterModelCallEvent(
+    agent=agent, invocation_state={},
+    stop_response={"stopReason": "tool_use"}, exception=None))
+
+tool_use = {"toolUseId": "t1", "name": "get_weather",
+            "input": {"location": "Paris"}}
+agent.hooks.invoke_callbacks(BeforeToolCallEvent(
+    agent=agent, selected_tool=None, tool_use=tool_use,
+    invocation_state={}))
+observation = get_weather("Paris")
+agent.hooks.invoke_callbacks(AfterToolCallEvent(
+    agent=agent, selected_tool=None, tool_use=tool_use,
+    invocation_state={},
+    result={"toolUseId": "t1", "status": "success",
+            "content": [{"text": observation}]},
+    exception=None))
+
+receipt = collector.finalize(final_answer=observation)  # line 2
+assert collector.verify(receipt) == []  # VALID
+collector.save("receipt.json", workflow=receipt)
+```
+
+That is the whole integration: attach the collector, run, finalize.
+The receipt is a plain JSON object you can store, ship to an auditor,
+or render in a UI. In production, attach to your real `strands.Agent`
+(the typed hook events fire automatically) instead of the scripted
+stand-in above.
+
+The hooks used are Strands' typed lifecycle events
+(`BeforeToolCallEvent` / `AfterToolCallEvent` for tools,
+`BeforeModelCallEvent` / `AfterModelCallEvent` for model calls),
+registered on the agent's own `HookRegistry` without disturbing any
+hooks you already have. For a multi-agent graph, call
+`collector.attach(...)` on each agent; every step carries its agent's
+name.
+
+## 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 tool/model call, 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 tool step's `tool` is the tool name (for example `get_weather`);
+each model step's `tool` is `model`. The `receipt_hash` is SHA-256 over
+the canonical JSON of the observed content (tool name, model-supplied
+input, tool result or stop response), so the hash commits to what
+actually happened. The receipt stays compact while the hash commits to
+the content. Steps also carry the agent name when the collector is
+attached to more than one agent.
+
+## 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
+```
+
+### Separate verification verdicts
+
+For honest reporting, use `verify_receipt_verdicts()` instead of a
+single boolean. Each dimension gets its own verdict; they are never
+conflated:
+
+```python
+from aer1_strands import verify_receipt_verdicts, verdicts_summary
+
+verdicts = verify_receipt_verdicts(receipt)
+print(verdicts_summary(verdicts))
+# byte_integrity=pass schema_validity=pass issuer_authenticity=not_checked
+# evidence_linkage=not_checked anchor_verification=not_checked
+# chain_integrity=pass
+```
+
+| Dimension | What it checks | Collector behavior |
+|---|---|---|
+| `byte_integrity` | Merkle root matches the recomputed root | `pass` / `fail` |
+| `schema_validity` | All required fields present and well-formed | `pass` / `fail` |
+| `issuer_authenticity` | Cryptographic proof of who issued the receipt | Always `not_checked`; the collector does not verify signatures |
+| `evidence_linkage` | Upstream evidence bytes match their digests | Always `not_checked`; the collector does not capture upstream evidence |
+| `anchor_verification` | Anchor proof is valid and binds the root | `pass` / `fail` / `not_checked` (no proof provided) |
+| `chain_integrity` | `seq` values are 1..n in order, no duplicate receipt ids | `pass` / `fail` |
+
+Verdict values are `pass`, `fail`, `not_checked`, and `unavailable`.
+`not_checked` is neither a successful check nor evidence of failure.
+
+### What the commitment covers (and what it does not)
+
+The `merkle_root` commits to the ordered list of step `receipt_id`
+values. Each step `receipt_hash` commits to that step's tool name,
+arguments, and observations. The `output_hash` commits to the final
+answer bytes.
+
+What this does **not** cover:
+
+- The commitment does not prove the bytes are unchanged since issuance.
+  An attacker able to replace both bytes and digest creates another
+  matching pair. Continuity requires comparing against a digest from
+  an independently trusted path (a retained receipt, a verified
+  signature with a trusted key, or a separately verified anchor).
+- A matching hash does not prove the action ran, the data is true, or
+  any external outcome occurred. It proves the supplied bytes agree
+  with the supplied digest.
+- The receipt records the collector's observations. It does not prove
+  provider truth, correct reasoning, authorization, or business success.
+- Without an anchor, truncation (deleting steps from the end and
+  recomputing the root) is not detectable.
+
+### Construction versions
+
+This package uses these exact constructions (see `CONSTRUCTION_VERSIONS`
+in the `verdicts` module):
+
+- Merkle tree: `section-8.1-binary-merkle-v1`
+- Step digest: `sha256-canonical-json-v1`
+- Output commitment: `sha256-utf8-v1`
+- Anchor proof: `aer1-anchor-proof-v1`
+
+## Notes
+
+- `attach(agent)` appends to the agent's existing hook callbacks; call
+  it once per agent (repeat calls are no-ops).
+- A tool result with `status: "error"`, or a model call that raised, is
+  recorded with `status: "error"`, which marks the whole receipt error.
+- Tool before/after events are correlated by `toolUseId`; an
+  after-event that arrives without its before-event still becomes a
+  step, so no observation is lost.
+- `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.
+
+## Spec
+
+AER-1: Agent Execution Receipts is an IETF Internet-Draft,
+`draft-zambo-aer1`,
+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_strands-0.1.0/README.md

@@ -0,0 +1,227 @@
+# aer1-strands
+
+One-line install, no API key, free forever: attach this collector to an `Agent` and every [Strands Agents](https://strandsagents.com/) run emits a hash-chained, offline-verifiable **verifiable workflow receipt** (AER-1, an IETF Internet-Draft, Section 8). What the agent did, in what order, with per-step hashes and a Merkle root over the whole run. No network calls, no behavior changes: every hook callback returns `None`, so Strands executes exactly as it would without us. 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 Strands 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-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.
+- [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-haystack](https://pypi.org/project/aer1-haystack/), Haystack 2.x pipelines via run wrapping
+- [aer1-pydantic](https://pypi.org/project/aer1-pydantic/), Pydantic AI agents via run wrapping and manual tool-call recording
+
+## Install
+
+```bash
+pip install aer1-strands
+```
+
+## Use it (copy, paste, run, no API keys needed)
+
+```python
+# pip install aer1-strands
+from aer1_strands import AER1StrandsCollector
+from strands.hooks import HookRegistry
+from strands.hooks.events import (
+    BeforeModelCallEvent, AfterModelCallEvent,
+    BeforeToolCallEvent, AfterToolCallEvent,
+)
+
+class FakeAgent:
+    """Stand-in for strands.Agent: a name plus a real HookRegistry."""
+    def __init__(self, name="assistant"):
+        self.name = name
+        self.hooks = HookRegistry()
+
+def get_weather(location: str) -> str:
+    """Local mock tool: executed on this machine, no network."""
+    return f"Sunny, 22C in {location}"
+
+collector = AER1StrandsCollector(goal="check the Paris weather")
+agent = FakeAgent("assistant")
+collector.attach(agent)  # line 1: register the hooks
+
+# A two-step flow: model reasoning, then a tool call. In production
+# Strands fires these events itself as your real agent runs, so you
+# call collector.attach(your_real_agent) instead of this script.
+agent.hooks.invoke_callbacks(BeforeModelCallEvent(
+    agent=agent, invocation_state={}, projected_input_tokens=96))
+agent.hooks.invoke_callbacks(AfterModelCallEvent(
+    agent=agent, invocation_state={},
+    stop_response={"stopReason": "tool_use"}, exception=None))
+
+tool_use = {"toolUseId": "t1", "name": "get_weather",
+            "input": {"location": "Paris"}}
+agent.hooks.invoke_callbacks(BeforeToolCallEvent(
+    agent=agent, selected_tool=None, tool_use=tool_use,
+    invocation_state={}))
+observation = get_weather("Paris")
+agent.hooks.invoke_callbacks(AfterToolCallEvent(
+    agent=agent, selected_tool=None, tool_use=tool_use,
+    invocation_state={},
+    result={"toolUseId": "t1", "status": "success",
+            "content": [{"text": observation}]},
+    exception=None))
+
+receipt = collector.finalize(final_answer=observation)  # line 2
+assert collector.verify(receipt) == []  # VALID
+collector.save("receipt.json", workflow=receipt)
+```
+
+That is the whole integration: attach the collector, run, finalize.
+The receipt is a plain JSON object you can store, ship to an auditor,
+or render in a UI. In production, attach to your real `strands.Agent`
+(the typed hook events fire automatically) instead of the scripted
+stand-in above.
+
+The hooks used are Strands' typed lifecycle events
+(`BeforeToolCallEvent` / `AfterToolCallEvent` for tools,
+`BeforeModelCallEvent` / `AfterModelCallEvent` for model calls),
+registered on the agent's own `HookRegistry` without disturbing any
+hooks you already have. For a multi-agent graph, call
+`collector.attach(...)` on each agent; every step carries its agent's
+name.
+
+## 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 tool/model call, 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 tool step's `tool` is the tool name (for example `get_weather`);
+each model step's `tool` is `model`. The `receipt_hash` is SHA-256 over
+the canonical JSON of the observed content (tool name, model-supplied
+input, tool result or stop response), so the hash commits to what
+actually happened. The receipt stays compact while the hash commits to
+the content. Steps also carry the agent name when the collector is
+attached to more than one agent.
+
+## 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
+```
+
+### Separate verification verdicts
+
+For honest reporting, use `verify_receipt_verdicts()` instead of a
+single boolean. Each dimension gets its own verdict; they are never
+conflated:
+
+```python
+from aer1_strands import verify_receipt_verdicts, verdicts_summary
+
+verdicts = verify_receipt_verdicts(receipt)
+print(verdicts_summary(verdicts))
+# byte_integrity=pass schema_validity=pass issuer_authenticity=not_checked
+# evidence_linkage=not_checked anchor_verification=not_checked
+# chain_integrity=pass
+```
+
+| Dimension | What it checks | Collector behavior |
+|---|---|---|
+| `byte_integrity` | Merkle root matches the recomputed root | `pass` / `fail` |
+| `schema_validity` | All required fields present and well-formed | `pass` / `fail` |
+| `issuer_authenticity` | Cryptographic proof of who issued the receipt | Always `not_checked`; the collector does not verify signatures |
+| `evidence_linkage` | Upstream evidence bytes match their digests | Always `not_checked`; the collector does not capture upstream evidence |
+| `anchor_verification` | Anchor proof is valid and binds the root | `pass` / `fail` / `not_checked` (no proof provided) |
+| `chain_integrity` | `seq` values are 1..n in order, no duplicate receipt ids | `pass` / `fail` |
+
+Verdict values are `pass`, `fail`, `not_checked`, and `unavailable`.
+`not_checked` is neither a successful check nor evidence of failure.
+
+### What the commitment covers (and what it does not)
+
+The `merkle_root` commits to the ordered list of step `receipt_id`
+values. Each step `receipt_hash` commits to that step's tool name,
+arguments, and observations. The `output_hash` commits to the final
+answer bytes.
+
+What this does **not** cover:
+
+- The commitment does not prove the bytes are unchanged since issuance.
+  An attacker able to replace both bytes and digest creates another
+  matching pair. Continuity requires comparing against a digest from
+  an independently trusted path (a retained receipt, a verified
+  signature with a trusted key, or a separately verified anchor).
+- A matching hash does not prove the action ran, the data is true, or
+  any external outcome occurred. It proves the supplied bytes agree
+  with the supplied digest.
+- The receipt records the collector's observations. It does not prove
+  provider truth, correct reasoning, authorization, or business success.
+- Without an anchor, truncation (deleting steps from the end and
+  recomputing the root) is not detectable.
+
+### Construction versions
+
+This package uses these exact constructions (see `CONSTRUCTION_VERSIONS`
+in the `verdicts` module):
+
+- Merkle tree: `section-8.1-binary-merkle-v1`
+- Step digest: `sha256-canonical-json-v1`
+- Output commitment: `sha256-utf8-v1`
+- Anchor proof: `aer1-anchor-proof-v1`
+
+## Notes
+
+- `attach(agent)` appends to the agent's existing hook callbacks; call
+  it once per agent (repeat calls are no-ops).
+- A tool result with `status: "error"`, or a model call that raised, is
+  recorded with `status: "error"`, which marks the whole receipt error.
+- Tool before/after events are correlated by `toolUseId`; an
+  after-event that arrives without its before-event still becomes a
+  step, so no observation is lost.
+- `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.
+
+## Spec
+
+AER-1: Agent Execution Receipts is an IETF Internet-Draft,
+`draft-zambo-aer1`,
+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_strands-0.1.0/aer1_strands/__init__.py

@@ -0,0 +1,58 @@
+"""aer1-strands: AER-1 verifiable workflow receipts for Strands Agents."""
+
+from .anchor import (
+    AnchorError,
+    NostrBackend,
+    OTSBackend,
+    anchor_chain_head,
+    bip340_verify,
+    proof_from_json,
+    proof_to_json,
+    verify_anchor,
+)
+from .collector import (
+    AER1StrandsCollector,
+    DEFAULT_VERIFY_URL,
+    WORKFLOW_TYPE,
+    WORKFLOW_VERSION,
+    merkle_root,
+    verify_workflow_receipt,
+)
+from .verdicts import (
+    CONSTRUCTION_VERSIONS,
+    VERDICT_FAIL,
+    VERDICT_NOT_CHECKED,
+    VERDICT_PASS,
+    VERDICT_UNAVAILABLE,
+    all_verdicts_pass,
+    verdicts_summary,
+    verify_receipt_verdicts,
+)
+
+
+__all__ = [
+    "AER1StrandsCollector",
+    "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",
+    "CONSTRUCTION_VERSIONS",
+    "VERDICT_FAIL",
+    "VERDICT_NOT_CHECKED",
+    "VERDICT_PASS",
+    "VERDICT_UNAVAILABLE",
+    "all_verdicts_pass",
+    "verdicts_summary",
+    "verify_receipt_verdicts",
+]
+
+__version__ = "0.1.0"