zambo-adk 0.1.0__tar.gz

zambo_adk-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: zambo-adk
+Version: 0.1.0
+Summary: Zambo verifiable execution receipts for Google ADK agents
+Author: Brennan Zambo
+License: Apache-2.0
+Project-URL: Homepage, https://zambo.dev
+Keywords: zambo,aer-1,google-adk,ai-agents,verifiable-receipts,audit,tracing
+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: google-adk>=1.0
+
+# zambo-adk
+
+Zambo verifiable execution receipts for [Google ADK](https://google.github.io/adk-docs/) (Agent Development Kit) agents.
+
+Attach receipt recording to any ADK agent and every tool execution
+becomes a hash-chained step in a **verifiable workflow receipt**
+(AER-1, Section 8): each step carries the tool name, arguments,
+result, agent identity, and timestamps, with one Merkle root over the
+whole run. The hooks only observe: every callback returns `None`, so
+ADK executes tools exactly as it would without us. No network calls
+until you call `mint()`.
+
+Works with `LlmAgent` and any agent carrying the standard ADK tool
+callbacks, via per-agent callbacks or a runner-wide plugin.
+
+## Install
+
+```bash
+pip install zambo-adk
+```
+
+Requires `google-adk>=1.0` (installed automatically).
+
+## Quickstart (zero API keys)
+
+This runs a real ADK agent end to end with a scripted fake model, no
+keys, no network, and ends at a live receipt URL on zambo.dev:
+
+```python
+import asyncio
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types as genai_types
+
+from zambo_adk import AER1ADKCollector, attach_receipts
+from zambo_adk.testing import scripted_agent
+
+
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+async def main():
+    collector = AER1ADKCollector(goal="Add 40 and 2")
+
+    agent = scripted_agent(
+        "calc", [add],
+        script=[("add", {"a": 40, "b": 2})],
+        final_text="42",
+    )
+    attach_receipts(agent, collector)          # line 1: attach
+
+    session_service = InMemorySessionService()
+    session = await session_service.create_session(app_name="app", user_id="u1")
+    runner = Runner(agent=agent, app_name="app", session_service=session_service)
+    message = genai_types.Content(
+        parts=[genai_types.Part(text="Add 40 and 2")], role="user"
+    )
+    async for _event in runner.run_async(
+        user_id="u1", session_id=session.id, new_message=message
+    ):
+        pass                                   # line 2: run
+
+    receipt = collector.finalize(final_answer="42")
+    assert collector.verify(receipt) == []     # VALID
+    print(collector.mint(receipt))             # line 3: live receipt URL
+
+asyncio.run(main())
+```
+
+Output:
+
+```
+recorded 1 tool call(s), receipt is VALID
+live receipt: https://zambo.dev/run/6b3e89e9-1952-4850-aef4-a9534688637c
+```
+
+Swap `scripted_agent` for your own `LlmAgent` with a real model and
+the same three lines give you receipts on every tool call.
+
+## Runner-wide plugin
+
+To cover every agent under a Runner, including sub-agents, register
+the plugin on the App instead of attaching per-agent callbacks:
+
+```python
+from google.adk.apps import App
+from zambo_adk import AER1ADKCollector, AER1ADKPlugin
+
+collector = AER1ADKCollector(goal="Research the launch plan")
+plugin = AER1ADKPlugin(collector)
+app = App(name="my_app", root_agent=agent, plugins=[plugin])
+```
+
+Plugins run before agent-level callbacks, so the plugin also sees
+tool calls that an agent callback short-circuits.
+
+## 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 execution, 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), plus agent identity:
+
+- `seq`, `receipt_id`, `tool`, `receipt_hash`, `started_at`, `ended_at`, `status`
+- `agent`: the name of the ADK agent that acted (every step)
+
+Each step `receipt_hash` is SHA-256 over the canonical JSON of the
+tool name, arguments, result, and error flag. The hash commits to the
+content; the receipt stays compact. Tool errors are recorded as steps
+with `status: "error"` and the exception captured, so failures are
+auditable too.
+
+## 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`
+- `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
+```
+
+## Minting a live Zambo receipt
+
+`collector.mint(receipt)` submits the finalized AER-1 receipt to
+zambo.dev for verification and returns the live audit URL
+(`https://zambo.dev/run/<receipt-id>`). It uses the free zambo.dev
+MCP tier: no auth, no API keys. The mint itself is a Zambo tool call,
+so it carries its own verifiable Zambo receipt.
+
+## Notes
+
+- `attach_receipts` preserves callbacks already on the agent: ours are
+  appended to the existing callback lists.
+- The collector never touches the network and never changes what the
+  agents do until `mint()` is called. A recording failure can never
+  break a run.
+- `session_id` defaults to a fresh UUID per collector; pass your own to
+  correlate receipts across runs.
+- `ScriptedModel` / `scripted_agent` in `zambo_adk.testing` are test
+  helpers: scripted tool-call sequences with no model credentials.
+- Verified against `google-adk` 2.11.0.
+
+## Spec
+
+AER-1: Agent Execution Receipts, `draft-zambo-aer1`
+(an IETF draft):
+https://datatracker.ietf.org/doc/draft-zambo-aer1/
+
+## License
+
+Apache-2.0

zambo_adk-0.1.0/README.md

@@ -0,0 +1,168 @@
+# zambo-adk
+
+Zambo verifiable execution receipts for [Google ADK](https://google.github.io/adk-docs/) (Agent Development Kit) agents.
+
+Attach receipt recording to any ADK agent and every tool execution
+becomes a hash-chained step in a **verifiable workflow receipt**
+(AER-1, Section 8): each step carries the tool name, arguments,
+result, agent identity, and timestamps, with one Merkle root over the
+whole run. The hooks only observe: every callback returns `None`, so
+ADK executes tools exactly as it would without us. No network calls
+until you call `mint()`.
+
+Works with `LlmAgent` and any agent carrying the standard ADK tool
+callbacks, via per-agent callbacks or a runner-wide plugin.
+
+## Install
+
+```bash
+pip install zambo-adk
+```
+
+Requires `google-adk>=1.0` (installed automatically).
+
+## Quickstart (zero API keys)
+
+This runs a real ADK agent end to end with a scripted fake model, no
+keys, no network, and ends at a live receipt URL on zambo.dev:
+
+```python
+import asyncio
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types as genai_types
+
+from zambo_adk import AER1ADKCollector, attach_receipts
+from zambo_adk.testing import scripted_agent
+
+
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+async def main():
+    collector = AER1ADKCollector(goal="Add 40 and 2")
+
+    agent = scripted_agent(
+        "calc", [add],
+        script=[("add", {"a": 40, "b": 2})],
+        final_text="42",
+    )
+    attach_receipts(agent, collector)          # line 1: attach
+
+    session_service = InMemorySessionService()
+    session = await session_service.create_session(app_name="app", user_id="u1")
+    runner = Runner(agent=agent, app_name="app", session_service=session_service)
+    message = genai_types.Content(
+        parts=[genai_types.Part(text="Add 40 and 2")], role="user"
+    )
+    async for _event in runner.run_async(
+        user_id="u1", session_id=session.id, new_message=message
+    ):
+        pass                                   # line 2: run
+
+    receipt = collector.finalize(final_answer="42")
+    assert collector.verify(receipt) == []     # VALID
+    print(collector.mint(receipt))             # line 3: live receipt URL
+
+asyncio.run(main())
+```
+
+Output:
+
+```
+recorded 1 tool call(s), receipt is VALID
+live receipt: https://zambo.dev/run/6b3e89e9-1952-4850-aef4-a9534688637c
+```
+
+Swap `scripted_agent` for your own `LlmAgent` with a real model and
+the same three lines give you receipts on every tool call.
+
+## Runner-wide plugin
+
+To cover every agent under a Runner, including sub-agents, register
+the plugin on the App instead of attaching per-agent callbacks:
+
+```python
+from google.adk.apps import App
+from zambo_adk import AER1ADKCollector, AER1ADKPlugin
+
+collector = AER1ADKCollector(goal="Research the launch plan")
+plugin = AER1ADKPlugin(collector)
+app = App(name="my_app", root_agent=agent, plugins=[plugin])
+```
+
+Plugins run before agent-level callbacks, so the plugin also sees
+tool calls that an agent callback short-circuits.
+
+## 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 execution, 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), plus agent identity:
+
+- `seq`, `receipt_id`, `tool`, `receipt_hash`, `started_at`, `ended_at`, `status`
+- `agent`: the name of the ADK agent that acted (every step)
+
+Each step `receipt_hash` is SHA-256 over the canonical JSON of the
+tool name, arguments, result, and error flag. The hash commits to the
+content; the receipt stays compact. Tool errors are recorded as steps
+with `status: "error"` and the exception captured, so failures are
+auditable too.
+
+## 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`
+- `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
+```
+
+## Minting a live Zambo receipt
+
+`collector.mint(receipt)` submits the finalized AER-1 receipt to
+zambo.dev for verification and returns the live audit URL
+(`https://zambo.dev/run/<receipt-id>`). It uses the free zambo.dev
+MCP tier: no auth, no API keys. The mint itself is a Zambo tool call,
+so it carries its own verifiable Zambo receipt.
+
+## Notes
+
+- `attach_receipts` preserves callbacks already on the agent: ours are
+  appended to the existing callback lists.
+- The collector never touches the network and never changes what the
+  agents do until `mint()` is called. A recording failure can never
+  break a run.
+- `session_id` defaults to a fresh UUID per collector; pass your own to
+  correlate receipts across runs.
+- `ScriptedModel` / `scripted_agent` in `zambo_adk.testing` are test
+  helpers: scripted tool-call sequences with no model credentials.
+- Verified against `google-adk` 2.11.0.
+
+## Spec
+
+AER-1: Agent Execution Receipts, `draft-zambo-aer1`
+(an IETF draft):
+https://datatracker.ietf.org/doc/draft-zambo-aer1/
+
+## License
+
+Apache-2.0

zambo_adk-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zambo-adk"
+version = "0.1.0"
+description = "Zambo verifiable execution receipts for Google ADK agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Brennan Zambo" }]
+dependencies = ["google-adk>=1.0"]
+keywords = ["zambo", "aer-1", "google-adk", "ai-agents", "verifiable-receipts", "audit", "tracing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://zambo.dev"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["zambo_adk*"]

zambo_adk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zambo_adk-0.1.0/tests/test_collector.py

@@ -0,0 +1,173 @@
+"""Tests for zambo-adk. No google-adk and no network required, except
+test_mint which hits the live zambo.dev MCP (free tier, no auth)."""
+
+import json
+
+import pytest
+
+from zambo_adk import AER1ADKCollector, attach_receipts
+from zambo_adk.collector import (
+    _mint_audit_url,
+    merkle_root,
+    verify_workflow_receipt,
+)
+from zambo_adk.hooks import _CallbackState
+
+
+class FakeTool:
+    def __init__(self, name):
+        self.name = name
+
+
+class FakeContext:
+    def __init__(self, agent_name="test_agent"):
+        self.agent_name = agent_name
+
+
+class FakeAgent:
+    def __init__(self):
+        self.before_tool_callback = None
+        self.after_tool_callback = None
+        self.on_tool_error_callback = None
+
+
+def run_tool_through_callbacks(agent, tool_name, args, result):
+    tool = FakeTool(tool_name)
+    ctx = FakeContext()
+    for cb in agent.before_tool_callback:
+        assert cb(tool=tool, args=args, tool_context=ctx) is None
+    for cb in agent.after_tool_callback:
+        assert (
+            cb(tool=tool, args=args, tool_context=ctx, tool_response=result)
+            is None
+        )
+
+
+def test_tool_call_recorded_as_step():
+    collector = AER1ADKCollector(goal="add numbers")
+    agent = attach_receipts(FakeAgent(), collector)
+    run_tool_through_callbacks(
+        agent, "add", {"a": 2, "b": 3}, {"result": 5}
+    )
+    assert collector.step_count == 1
+    receipt = collector.finalize(final_answer="5")
+    assert collector.verify(receipt) == []
+    step = receipt["steps"][0]
+    assert step["tool"] == "add"
+    assert step["status"] == "ok"
+    assert step["agent"] == "test_agent"
+
+
+def test_error_tool_call_recorded_as_error():
+    collector = AER1ADKCollector(goal="risky run")
+    agent = attach_receipts(FakeAgent(), collector)
+    tool = FakeTool("divide")
+    ctx = FakeContext()
+    for cb in agent.before_tool_callback:
+        cb(tool=tool, args={"a": 1, "b": 0}, tool_context=ctx)
+    boom = ZeroDivisionError("division by zero")
+    for cb in agent.on_tool_error_callback:
+        assert (
+            cb(tool=tool, args={}, tool_context=ctx, exception=boom) is None
+        )
+    receipt = collector.finalize()
+    assert receipt["status"] == "error"
+    assert receipt["steps"][0]["status"] == "error"
+    assert collector.verify(receipt) == []
+
+
+def test_existing_callbacks_preserved():
+    seen = []
+
+    def existing_before(tool=None, args=None, tool_context=None):
+        seen.append(("before", getattr(tool, "name", None)))
+        return None
+
+    collector = AER1ADKCollector(goal="preserve")
+    agent = FakeAgent()
+    agent.before_tool_callback = existing_before
+    attach_receipts(agent, collector)
+    run_tool_through_callbacks(agent, "search", {"q": "x"}, {"hits": []})
+    assert seen == [("before", "search")]
+    assert collector.step_count == 1
+
+
+def test_callbacks_never_short_circuit():
+    # Every zambo-adk callback must return None: a non-None return
+    # would make ADK skip the tool entirely.
+    collector = AER1ADKCollector(goal="passthrough")
+    agent = attach_receipts(FakeAgent(), collector)
+    tool, ctx = FakeTool("t"), FakeContext()
+    for cb in agent.before_tool_callback:
+        assert cb(tool=tool, args={}, tool_context=ctx) is None
+    for cb in agent.after_tool_callback:
+        assert cb(tool=tool, args={}, tool_context=ctx, tool_response={}) is None
+    for cb in agent.on_tool_error_callback:
+        assert (
+            cb(tool=tool, args={}, tool_context=ctx, exception=ValueError())
+            is None
+        )
+
+
+def test_receipt_hash_commits_to_result():
+    c1 = AER1ADKCollector(goal="g")
+    a1 = attach_receipts(FakeAgent(), c1)
+    run_tool_through_callbacks(a1, "add", {"a": 1}, {"result": 1})
+    c2 = AER1ADKCollector(goal="g")
+    a2 = attach_receipts(FakeAgent(), c2)
+    run_tool_through_callbacks(a2, "add", {"a": 1}, {"result": 999})
+    h1 = c1.finalize()["steps"][0]["receipt_hash"]
+    h2 = c2.finalize()["steps"][0]["receipt_hash"]
+    assert h1 != h2
+
+
+def test_tampered_receipt_fails_verification():
+    collector = AER1ADKCollector(goal="g")
+    agent = attach_receipts(FakeAgent(), collector)
+    run_tool_through_callbacks(agent, "add", {"a": 1}, {"result": 1})
+    receipt = collector.finalize()
+    receipt["steps"][0]["tool"] = ""
+    assert collector.verify(receipt) != []
+
+
+def test_merkle_root_matches_recomputed():
+    collector = AER1ADKCollector(goal="g")
+    agent = attach_receipts(FakeAgent(), collector)
+    for i in range(3):
+        run_tool_through_callbacks(agent, f"tool_{i}", {}, {"i": i})
+    receipt = collector.finalize()
+    assert receipt["merkle_root"] == merkle_root(
+        [s["receipt_id"] for s in receipt["steps"]]
+    )
+    assert verify_workflow_receipt(receipt) == []
+
+
+def test_seq_ordering_and_agent_identity():
+    collector = AER1ADKCollector(goal="g")
+    state = _CallbackState(collector)
+    for i in range(2):
+        ctx = FakeContext(agent_name=f"agent_{i}")
+        state.begin(FakeTool("t"), {}, ctx)
+        state.end(ctx, result={"i": i})
+    receipt = collector.finalize()
+    assert [s["seq"] for s in receipt["steps"]] == [1, 2]
+    assert [s["agent"] for s in receipt["steps"]] == ["agent_0", "agent_1"]
+
+
+def test_receipt_serializes_to_json():
+    collector = AER1ADKCollector(goal="g")
+    agent = attach_receipts(FakeAgent(), collector)
+    run_tool_through_callbacks(agent, "add", {"a": 1}, {"result": 1})
+    text = collector.to_json()
+    assert json.loads(text)["type"] == "verifiable-workflow-receipt"
+
+
+def test_mint_returns_live_audit_url():
+    collector = AER1ADKCollector(goal="mint test")
+    agent = attach_receipts(FakeAgent(), collector)
+    run_tool_through_callbacks(agent, "add", {"a": 40, "b": 2}, {"result": 42})
+    receipt = collector.finalize(final_answer="42")
+    assert collector.verify(receipt) == []
+    url = collector.mint(receipt)
+    assert url.startswith("https://zambo.dev/run/")
+    print(f"\nlive audit url: {url}")

zambo_adk-0.1.0/zambo_adk/__init__.py

@@ -0,0 +1,51 @@
+"""zambo-adk: Zambo verifiable execution receipts for Google ADK agents.
+
+Attach AER-1 receipt recording to any Google Agent Development Kit
+agent. Every tool execution becomes a hash-chained step in a
+verifiable workflow receipt (AER-1, Section 8); finalize() emits the
+receipt, verify() checks it offline, and mint() submits it to
+zambo.dev for a live audit URL.
+
+Two integration routes:
+
+    from zambo_adk import AER1ADKCollector, attach_receipts
+
+    collector = AER1ADKCollector(goal="Research the launch plan")
+    agent = attach_receipts(my_adk_agent, collector)
+    # ... run the agent ...
+    receipt = collector.finalize(final_answer="done")
+    assert collector.verify(receipt) == []      # VALID
+    print(collector.mint(receipt))              # live audit URL
+
+Or runner-wide, covering every agent under the Runner:
+
+    from zambo_adk import AER1ADKPlugin
+    app = App(name="my_app", root_agent=agent,
+              plugins=[AER1ADKPlugin(collector)])
+
+The hooks only observe: every callback returns None, so ADK executes
+tools exactly as it would without us. No network calls until you call
+mint(). A recording failure can never break a run.
+"""
+
+from .collector import (
+    AER1ADKCollector,
+    ZAMBO_MCP_URL,
+    merkle_root,
+    verify_workflow_receipt,
+)
+from .hooks import AER1ADKPlugin, attach_receipts
+from .testing import ScriptedModel, scripted_agent
+
+__all__ = [
+    "AER1ADKCollector",
+    "AER1ADKPlugin",
+    "attach_receipts",
+    "ScriptedModel",
+    "scripted_agent",
+    "ZAMBO_MCP_URL",
+    "merkle_root",
+    "verify_workflow_receipt",
+]
+
+__version__ = "0.1.0"