aer1-middleware 0.2.0__tar.gz

aer1_middleware-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# TLA+
+*.tlacfg
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.vscode/
+.idea/
+*.swp

aer1_middleware-0.2.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: aer1-middleware
+Version: 0.2.0
+Summary: AER-1 verifiable execution receipts for AI agent frameworks
+Project-URL: Homepage, https://zambo.dev
+Project-URL: Repository, https://gitlab.com/rambozambodotdev/zambo
+Project-URL: Documentation, https://datatracker.ietf.org/doc/draft-zambo-aer1/
+Author: Brennan Zambo
+License: MIT
+Keywords: aer1,agents,mcp,receipts,verifiable
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: cryptography>=41.0.0; extra == 'all'
+Requires-Dist: fastmcp>=0.1.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: openai-agents>=0.1.0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.0.0; extra == 'all'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=0.1.0; extra == 'fastmcp'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1.0; extra == 'openai-agents'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.0.0; extra == 'otel'
+Provides-Extra: signatures
+Requires-Dist: cryptography>=41.0.0; extra == 'signatures'
+Description-Content-Type: text/markdown
+
+# AER-1 Middleware
+
+Verifiable execution receipts for AI agent frameworks.
+
+Implements [IETF draft-zambo-aer1](https://datatracker.ietf.org/doc/draft-zambo-aer1/) — an IETF Internet-Draft for verifiable AI agent execution receipts.
+
+> **Status:** the framework adapters have been validated end to end against
+> the real framework SDKs (FastMCP, langchain-core, openai-agents,
+> opentelemetry-sdk), and generated receipts pass the AER-1 conformance
+> kit's core check against draft-zambo-aer1-10. The package is not yet
+> published on PyPI.
+
+## Installation
+
+Not yet published on PyPI. Install from source:
+
+```bash
+git clone https://gitlab.com/rambozambodotdev/zambo.git
+cd zambo/aer1-middleware
+pip install -e .
+```
+
+## FastMCP (one line)
+
+```python
+from fastmcp import FastMCP
+from aer1_middleware.fastmcp import AER1Middleware
+
+mcp = FastMCP("my-server")
+mcp.add_middleware(AER1Middleware())  # That's it. Every tool call now generates a receipt.
+```
+
+## LangChain (one line)
+
+```python
+from langchain_openai import ChatOpenAI
+from aer1_middleware.langchain import AER1Callback
+
+llm = ChatOpenAI(callbacks=[AER1Callback()])
+```
+
+## OpenAI Agents SDK (one decorator)
+
+```python
+from agents import function_tool
+from aer1_middleware.openai_agents import with_aer1
+
+@function_tool
+@with_aer1
+def search(query: str) -> str:
+    return f"Results for {query}"
+```
+
+(`with_aer1` must wrap the raw function, so it goes directly above `def`,
+inside `function_tool`. Retrieve receipts with
+`from aer1_middleware.openai_agents import get_receipts`.)
+
+## OpenTelemetry (span exporter)
+
+```python
+from aer1_middleware.otel import AER1SpanExporter
+
+exporter = AER1SpanExporter()
+exporter.export_receipt(receipt)
+```
+
+## Manual usage
+
+```python
+from aer1_middleware import create_receipt, verify_receipt
+
+receipt = create_receipt(
+    tool_name="search",
+    inputs={"query": "AER-1"},
+    output={"results": [...]},
+)
+
+is_valid, reason = verify_receipt(receipt)
+```
+
+## What is AER-1?
+
+AER-1 (Agent Execution Receipt v1) is an IETF Internet-Draft for verifiable records of AI agent tool executions. Each receipt contains:
+
+- SHA-256 commitment over the canonical tool-call payload
+- Timestamp and unique IDs
+- Optional Ed25519 signature
+- Independently verifiable against the conformance kit
+
+A receipt proves the saved result has not changed. It does not prove the model was right, and it does not by itself prove an external outcome.
+
+## License
+
+MIT

aer1_middleware-0.2.0/README.md

@@ -0,0 +1,94 @@
+# AER-1 Middleware
+
+Verifiable execution receipts for AI agent frameworks.
+
+Implements [IETF draft-zambo-aer1](https://datatracker.ietf.org/doc/draft-zambo-aer1/) — an IETF Internet-Draft for verifiable AI agent execution receipts.
+
+> **Status:** the framework adapters have been validated end to end against
+> the real framework SDKs (FastMCP, langchain-core, openai-agents,
+> opentelemetry-sdk), and generated receipts pass the AER-1 conformance
+> kit's core check against draft-zambo-aer1-10. The package is not yet
+> published on PyPI.
+
+## Installation
+
+Not yet published on PyPI. Install from source:
+
+```bash
+git clone https://gitlab.com/rambozambodotdev/zambo.git
+cd zambo/aer1-middleware
+pip install -e .
+```
+
+## FastMCP (one line)
+
+```python
+from fastmcp import FastMCP
+from aer1_middleware.fastmcp import AER1Middleware
+
+mcp = FastMCP("my-server")
+mcp.add_middleware(AER1Middleware())  # That's it. Every tool call now generates a receipt.
+```
+
+## LangChain (one line)
+
+```python
+from langchain_openai import ChatOpenAI
+from aer1_middleware.langchain import AER1Callback
+
+llm = ChatOpenAI(callbacks=[AER1Callback()])
+```
+
+## OpenAI Agents SDK (one decorator)
+
+```python
+from agents import function_tool
+from aer1_middleware.openai_agents import with_aer1
+
+@function_tool
+@with_aer1
+def search(query: str) -> str:
+    return f"Results for {query}"
+```
+
+(`with_aer1` must wrap the raw function, so it goes directly above `def`,
+inside `function_tool`. Retrieve receipts with
+`from aer1_middleware.openai_agents import get_receipts`.)
+
+## OpenTelemetry (span exporter)
+
+```python
+from aer1_middleware.otel import AER1SpanExporter
+
+exporter = AER1SpanExporter()
+exporter.export_receipt(receipt)
+```
+
+## Manual usage
+
+```python
+from aer1_middleware import create_receipt, verify_receipt
+
+receipt = create_receipt(
+    tool_name="search",
+    inputs={"query": "AER-1"},
+    output={"results": [...]},
+)
+
+is_valid, reason = verify_receipt(receipt)
+```
+
+## What is AER-1?
+
+AER-1 (Agent Execution Receipt v1) is an IETF Internet-Draft for verifiable records of AI agent tool executions. Each receipt contains:
+
+- SHA-256 commitment over the canonical tool-call payload
+- Timestamp and unique IDs
+- Optional Ed25519 signature
+- Independently verifiable against the conformance kit
+
+A receipt proves the saved result has not changed. It does not prove the model was right, and it does not by itself prove an external outcome.
+
+## License
+
+MIT

aer1_middleware-0.2.0/aer1_middleware/__init__.py

@@ -0,0 +1,258 @@
+"""
+AER-1 Middleware: Verifiable execution receipts for AI agent frameworks.
+
+This package provides integrations for popular agent frameworks
+to generate IETF draft-zambo-aer1 execution receipts.
+
+Supported frameworks (validated against the real framework SDKs):
+- FastMCP (via aer1_middleware.fastmcp)
+- LangChain (via aer1_middleware.langchain)
+- OpenAI Agents SDK (via aer1_middleware.openai_agents)
+
+Plus an OpenTelemetry span exporter (via aer1_middleware.otel).
+
+Generated receipts conform to the AER-1 conformance kit core schema
+(draft-zambo-aer1-10, Section 3) and pass the kit's check().
+
+Each receipt is a verifiable, hash-chained record of tool execution
+that can be independently verified against the AER-1 specification.
+
+A receipt proves the saved result has not changed. It does not prove the
+model was right, and it does not by itself prove an external outcome.
+"""
+
+__version__ = "0.2.0"
+__all__ = ["create_receipt", "verify_receipt", "generate_keypair", "sign_receipt"]
+
+import base64
+import hashlib
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+
+try:
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+    from cryptography.hazmat.primitives import serialization
+    HAS_CRYPTO = True
+except ImportError:
+    HAS_CRYPTO = False
+
+# Kit-conformance patterns (mirrors aer-1/conformance.py)
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-"
+                      r"[0-9a-f]{4}-[0-9a-f]{12}\Z")
+_RFC3339_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:"
+                         r"[0-9]{2}(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})\Z")
+_HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}\Z")
+_B64_RE = re.compile(r"\A[A-Za-z0-9+/]*={0,2}\Z")
+_PROV_RE = re.compile(r"^(EXECUTED BY [A-Z0-9][A-Z0-9 ._-]*|"
+                      r"OBSERVED VIA GATEWAY|LOGGED BY AGENT)\Z")
+_KIT_CORE = ["id", "receipt_schema_version", "created_at", "tool",
+             "provenance_class", "canonical_bytes", "output_hash",
+             "verification_status"]
+
+
+def generate_keypair():
+    """
+    Generate an Ed25519 keypair for signing receipts.
+    
+    Returns:
+        Tuple of (private_key_pem, public_key_pem) as strings.
+        Requires the 'cryptography' package.
+    """
+    if not HAS_CRYPTO:
+        raise ImportError("Ed25519 signatures require the 'cryptography' package: pip install cryptography")
+    
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption()
+    ).decode('utf-8')
+    
+    public_pem = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo
+    ).decode('utf-8')
+    
+    return private_pem, public_pem
+
+
+def sign_receipt(receipt, private_key_pem):
+    """
+    Sign a receipt with Ed25519.
+    
+    Signs the receipt's output_hash (the content commitment).
+    
+    Args:
+        receipt: Dict containing the receipt (must have 'output_hash' field)
+        private_key_pem: PEM-encoded Ed25519 private key
+    
+    Returns:
+        Receipt dict with 'signature' and 'public_key' fields added.
+    """
+    if not HAS_CRYPTO:
+        raise ImportError("Ed25519 signatures require the 'cryptography' package")
+    
+    private_key = serialization.load_pem_private_key(
+        private_key_pem.encode('utf-8'),
+        password=None
+    )
+    
+    # Sign the output_hash (the content commitment)
+    signature = private_key.sign(receipt['output_hash'].encode('utf-8'))
+    
+    # Get public key for verification
+    public_key = private_key.public_key()
+    public_pem = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo
+    ).decode('utf-8')
+    
+    receipt['signature'] = signature.hex()
+    receipt['public_key'] = public_pem
+    receipt['signature_algorithm'] = 'Ed25519'
+    
+    return receipt
+
+
+def create_receipt(tool_name, inputs, output, job_id=None, did=None, profile="public-v1", trust_boundary=None, tool_version="1.0.0", tool_scope="public"):
+    """
+    Create an AER-1 execution receipt for a tool call.
+
+    The receipt conforms to the AER-1 conformance kit core schema
+    (draft-zambo-aer1-10, Section 3): id, receipt_schema_version,
+    created_at, tool, provenance_class, canonical_bytes, output_hash,
+    verification_status.
+
+    Args:
+        tool_name: Name of the tool that was executed
+        inputs: Dict of input parameters
+        output: Tool output (will be hashed, not stored)
+        job_id: Optional job ID for chaining (generates one if not provided)
+        did: Optional DID string recorded as metadata (e.g., "did:key:z6Mk...").
+            Recorded only -- no DID resolution, key validation, or delegation
+            verification is performed.
+        profile: Receipt profile label ("public-v1" default, or "private-v1").
+            Recorded only -- no encryption or access control is applied.
+        trust_boundary: Optional URN recorded as metadata scoping the trust
+            boundary. Recorded only -- not enforced.
+        tool_version: Version string for the tool object (default "1.0.0")
+        tool_scope: Scope string for the tool object (default "public")
+
+    Returns:
+        Dict containing the AER-1 receipt
+    """
+    receipt_id = str(uuid.uuid4())
+    job_id = job_id or str(uuid.uuid4())
+    created_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    # Canonical payload per draft Sections 3-4
+    payload = {
+        "tool": tool_name,
+        "inputs": inputs,
+        "outputs": output if isinstance(output, dict) else {"result": output},
+    }
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    canonical_bytes = base64.b64encode(canonical.encode("utf-8")).decode("ascii")
+    output_hash = "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+    receipt = {
+        "id": receipt_id,
+        "receipt_schema_version": "0.3",
+        "created_at": created_at,
+        "tool": {"name": tool_name, "version": tool_version, "scope": tool_scope},
+        "provenance_class": "EXECUTED BY ZAMBO",
+        "canonical_bytes": canonical_bytes,
+        "output_hash": output_hash,
+        "verification_status": "verified",
+        "job_id": job_id,
+        "profile": profile,
+    }
+
+    # Add DID identity binding if provided (metadata only)
+    if did:
+        receipt["identity"] = {
+            "did": did,
+            "proof_purpose": "assertionMethod"
+        }
+
+    # Add trust boundary for private profile (metadata only)
+    if trust_boundary:
+        receipt["trust_boundary"] = trust_boundary
+        receipt["visibility"] = "private" if profile == "private-v1" else "public"
+
+    return receipt
+
+
+
+
+def verify_receipt(receipt):
+    """
+    Verify an AER-1 receipt against the conformance kit core schema
+    (draft-zambo-aer1-10, Section 3) plus Ed25519 signature if present.
+
+    Args:
+        receipt: Dict containing the receipt to verify
+
+    Returns:
+        Tuple of (is_valid, reason)
+    """
+    if not isinstance(receipt, dict):
+        return False, "receipt is not a JSON object"
+    for field in _KIT_CORE:
+        if field not in receipt:
+            return False, f"missing required member: {field}"
+    if not isinstance(receipt["id"], str) or not _UUID_RE.match(receipt["id"]):
+        return False, "id is not a lowercase UUID"
+    if (not isinstance(receipt["receipt_schema_version"], str)
+            or not receipt["receipt_schema_version"]):
+        return False, "receipt_schema_version is not a non-empty string"
+    if (not isinstance(receipt["created_at"], str)
+            or not _RFC3339_RE.match(receipt["created_at"])):
+        return False, "created_at is not RFC 3339"
+    tool = receipt["tool"]
+    if not isinstance(tool, dict) or not all(
+            isinstance(tool.get(k), str) and tool[k]
+            for k in ("name", "version", "scope")):
+        return False, "tool is not an object with name/version/scope strings"
+    if (not isinstance(receipt["provenance_class"], str)
+            or not _PROV_RE.match(receipt["provenance_class"])):
+        return False, "provenance_class is not a known class"
+    cb = receipt["canonical_bytes"]
+    raw = None
+    if not isinstance(cb, str) or not _B64_RE.match(cb):
+        return False, "canonical_bytes is not valid base64"
+    try:
+        raw = base64.b64decode(cb, validate=True)
+        raw.decode("utf-8")
+    except Exception:
+        return False, "canonical_bytes is not valid base64 UTF-8"
+    oh = receipt["output_hash"]
+    if not isinstance(oh, str) or not _HASH_RE.match(oh):
+        return False, "output_hash is not sha256: + lowercase hex digest"
+    want = "sha256:" + hashlib.sha256(raw).hexdigest()
+    if oh != want:
+        return False, "output_hash does not match sha256(canonical_bytes)"
+    if receipt["verification_status"] != "verified":
+        return False, "verification_status is not verified"
+
+    # Verify Ed25519 signature if present (signs the output_hash commitment)
+    if "signature" in receipt:
+        if not HAS_CRYPTO:
+            return False, "receipt is signed but 'cryptography' not installed"
+        if "public_key" not in receipt:
+            return False, "signature present but public_key missing"
+        try:
+            public_key = serialization.load_pem_public_key(
+                receipt["public_key"].encode("utf-8")
+            )
+            signature = bytes.fromhex(receipt["signature"])
+            public_key.verify(signature, receipt["output_hash"].encode("utf-8"))
+        except Exception as e:
+            return False, f"signature verification failed: {e}"
+        return True, "receipt is valid and signature verified"
+
+    return True, "receipt is valid (unsigned)"

aer1_middleware-0.2.0/aer1_middleware/fastmcp.py

@@ -0,0 +1,98 @@
+"""
+FastMCP integration for AER-1 verifiable execution receipts.
+
+One-line integration:
+    from aer1_middleware.fastmcp import AER1Middleware
+    mcp.add_middleware(AER1Middleware())
+
+Every tool call automatically generates an AER-1 receipt.
+"""
+
+try:
+    from fastmcp.server.middleware import Middleware, MiddlewareContext
+    HAS_FASTMCP = True
+except ImportError:
+    HAS_FASTMCP = False
+    # Stub for documentation without dependency
+    class Middleware:
+        pass
+    class MiddlewareContext:
+        pass
+
+from . import create_receipt
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize_output(output):
+    """Convert framework result objects to JSON-serializable values."""
+    if isinstance(output, list):
+        parts = [_serialize_output(item) for item in output]
+        return parts[0] if len(parts) == 1 else parts
+    if hasattr(output, "text") and isinstance(output.text, str):
+        return output.text
+    if hasattr(output, "model_dump"):
+        try:
+            return output.model_dump()
+        except Exception:
+            pass
+    try:
+        json.dumps(output)
+        return output
+    except TypeError:
+        return str(output)
+
+
+class AER1Middleware(Middleware if HAS_FASTMCP else object):
+    """
+    FastMCP middleware that generates AER-1 receipts for every tool call.
+    
+    Usage:
+        from fastmcp import FastMCP
+        from aer1_middleware.fastmcp import AER1Middleware
+        
+        mcp = FastMCP("my-server")
+        mcp.add_middleware(AER1Middleware())
+    
+    Each tool execution will automatically generate a verifiable
+    AER-1 receipt that can be retrieved via get_receipts().
+    """
+    
+    def __init__(self, job_id=None):
+        self.job_id = job_id
+        self.receipts = []
+    
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        """Intercept tool calls and generate receipts."""
+        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
+        inputs = context.message.arguments if hasattr(context.message, 'arguments') else {}
+        
+        # Execute the tool
+        result = await call_next(context)
+        
+        # Generate receipt
+        try:
+            raw_output = result.content if hasattr(result, 'content') else str(result)
+            output = _serialize_output(raw_output)
+            receipt = create_receipt(
+                tool_name=tool_name,
+                inputs=inputs,
+                output=output,
+                job_id=self.job_id,
+            )
+            self.receipts.append(receipt)
+            logger.info(f"AER-1 receipt generated: {receipt['id']}")
+        except Exception as e:
+            logger.warning(f"Failed to generate AER-1 receipt: {e}")
+        
+        return result
+    
+    def get_receipts(self):
+        """Return all generated receipts."""
+        return self.receipts
+    
+    def clear_receipts(self):
+        """Clear the receipt buffer."""
+        self.receipts = []

aer1_middleware-0.2.0/aer1_middleware/langchain.py

@@ -0,0 +1,64 @@
+"""
+LangChain integration for AER-1 verifiable execution receipts.
+
+One-line integration:
+    from aer1_middleware.langchain import AER1Callback
+    llm = ChatOpenAI(callbacks=[AER1Callback()])
+
+Every tool call automatically generates an AER-1 receipt.
+"""
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    HAS_LANGCHAIN = True
+except ImportError:
+    HAS_LANGCHAIN = False
+    class BaseCallbackHandler:
+        pass
+
+from . import create_receipt
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AER1Callback(BaseCallbackHandler if HAS_LANGCHAIN else object):
+    """
+    LangChain callback handler that generates AER-1 receipts.
+    
+    Usage:
+        from langchain_openai import ChatOpenAI
+        from aer1_middleware.langchain import AER1Callback
+        
+        llm = ChatOpenAI(callbacks=[AER1Callback()])
+    
+    Every tool execution will automatically generate a verifiable
+    AER-1 receipt.
+    """
+    
+    def __init__(self, job_id=None):
+        self.job_id = job_id
+        self.receipts = []
+    
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        """Called when a tool starts."""
+        self._current_tool = serialized.get("name", "unknown")
+        self._current_inputs = {"input": input_str}
+    
+    def on_tool_end(self, output, **kwargs):
+        """Called when a tool ends - generate receipt."""
+        try:
+            receipt = create_receipt(
+                tool_name=getattr(self, '_current_tool', 'unknown'),
+                inputs=getattr(self, '_current_inputs', {}),
+                output=str(output),
+                job_id=self.job_id,
+            )
+            self.receipts.append(receipt)
+            logger.info(f"AER-1 receipt generated: {receipt['id']}")
+        except Exception as e:
+            logger.warning(f"Failed to generate AER-1 receipt: {e}")
+    
+    def get_receipts(self):
+        """Return all generated receipts."""
+        return self.receipts

aer1_middleware-0.2.0/aer1_middleware/openai_agents.py

@@ -0,0 +1,90 @@
+"""
+OpenAI Agents SDK integration for AER-1 verifiable execution receipts.
+
+One-line integration via function wrapper:
+    from aer1_middleware.openai_agents import with_aer1, get_receipts
+
+    @function_tool
+    @with_aer1
+    def search(query: str) -> str:
+        ...
+
+`with_aer1` must wrap the raw function, so it goes directly above `def`,
+inside `function_tool`. Retrieve receipts via get_receipts().
+"""
+
+from . import create_receipt
+import functools
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Module-level registry: tool name -> list of receipts. FunctionTool objects
+# don't expose the wrapped function, so receipts are also tracked here.
+_receipt_registry = {}
+
+
+def get_receipts(tool_name=None):
+    """Return generated receipts, optionally filtered by tool name."""
+    if tool_name:
+        return list(_receipt_registry.get(tool_name, []))
+    return [r for receipts in _receipt_registry.values() for r in receipts]
+
+
+def clear_receipts(tool_name=None):
+    """Clear generated receipts, optionally filtered by tool name."""
+    if tool_name:
+        _receipt_registry.pop(tool_name, None)
+    else:
+        _receipt_registry.clear()
+
+
+def with_aer1(func):
+    """
+    Decorator that generates AER-1 receipts for OpenAI Agents SDK tools.
+
+    Usage:
+        from agents import function_tool
+        from aer1_middleware.openai_agents import with_aer1, get_receipts
+
+        @function_tool
+        @with_aer1
+        def search(query: str) -> str:
+            return f"Results for {query}"
+
+        receipts = get_receipts("search")
+
+    `with_aer1` must wrap the raw function, so it goes directly above `def`,
+    inside `function_tool`.
+    
+    Every tool execution will automatically generate a verifiable
+    AER-1 receipt accessible via func.aer1_receipts.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # Extract tool name and inputs
+        tool_name = func.__name__
+        inputs = {"args": str(args), "kwargs": str(kwargs)}
+        
+        # Execute the tool
+        result = func(*args, **kwargs)
+        
+        # Generate receipt
+        try:
+            receipt = create_receipt(
+                tool_name=tool_name,
+                inputs=inputs,
+                output=str(result),
+            )
+            if not hasattr(wrapper, 'aer1_receipts'):
+                wrapper.aer1_receipts = []
+            wrapper.aer1_receipts.append(receipt)
+            _receipt_registry.setdefault(tool_name, []).append(receipt)
+            logger.info(f"AER-1 receipt generated: {receipt['id']}")
+        except Exception as e:
+            logger.warning(f"Failed to generate AER-1 receipt: {e}")
+        
+        return result
+    
+    wrapper.aer1_receipts = []
+    return wrapper

aer1_middleware-0.2.0/aer1_middleware/otel.py

@@ -0,0 +1,100 @@
+"""
+OpenTelemetry exporter bridge for AER-1.
+
+Converts AER-1 receipts to OTel spans for integration with
+Datadog, Honeycomb, Jaeger, and other observability platforms.
+
+Usage:
+    from aer1_middleware.otel import AER1SpanExporter
+    exporter = AER1SpanExporter()
+    exporter.export_receipt(receipt)
+"""
+
+try:
+    from opentelemetry.trace import SpanKind, Status, StatusCode
+    from opentelemetry.sdk.trace import TracerProvider
+    HAS_OTEL = True
+except ImportError:
+    HAS_OTEL = False
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AER1SpanExporter:
+    """
+    Exports AER-1 receipts as OpenTelemetry spans.
+    
+    This bridges AER-1's verifiable receipts with the OTel ecosystem,
+    enabling integration with Datadog, Honeycomb, Jaeger, LangGraph,
+    CrewAI, AutoGen, and other platforms that consume OTel.
+    
+    Each receipt becomes a span with:
+    - Span name: aer1.tool.{tool_name}
+    - Attributes: receipt ID, job ID, hashes, signature status
+    - Events: receipt creation, verification
+    """
+    
+    def __init__(self, tracer_provider=None):
+        if not HAS_OTEL:
+            raise ImportError(
+                "OTel bridge requires 'opentelemetry-sdk': "
+                "pip install opentelemetry-sdk"
+            )
+        self.tracer_provider = tracer_provider or TracerProvider()
+        self.tracer = self.tracer_provider.get_tracer("aer1-middleware")
+    
+    def export_receipt(self, receipt):
+        """
+        Export an AER-1 receipt as an OTel span.
+        
+        Args:
+            receipt: Dict containing the AER-1 receipt
+        """
+        tool = receipt.get("tool", {})
+        tool_name = tool.get("name", "unknown") if isinstance(tool, dict) else str(tool)
+        span_name = f"aer1.tool.{tool_name}"
+        
+        with self.tracer.start_as_current_span(
+            span_name,
+            kind=SpanKind.INTERNAL,
+        ) as span:
+            # Set span attributes from receipt
+            span.set_attribute("aer1.receipt_id", receipt.get("id", ""))
+            span.set_attribute("aer1.job_id", receipt.get("job_id", ""))
+            span.set_attribute("aer1.schema_version", receipt.get("receipt_schema_version", ""))
+            span.set_attribute("aer1.tool", tool_name)
+            span.set_attribute("aer1.created_at", receipt.get("created_at", ""))
+            span.set_attribute("aer1.output_hash", receipt.get("output_hash", ""))
+            
+            # Signature status
+            is_signed = "signature" in receipt
+            span.set_attribute("aer1.signed", is_signed)
+            if is_signed:
+                span.set_attribute(
+                    "aer1.signature_algorithm",
+                    receipt.get("signature_algorithm", "unknown")
+                )
+            
+            # Provenance
+            span.set_attribute(
+                "aer1.provenance_class",
+                receipt.get("provenance_class", "")
+            )
+            
+            # Add event for receipt creation
+            span.add_event(
+                "aer1.receipt_created",
+                attributes={
+                    "receipt.id": receipt.get("id", ""),
+                }
+            )
+            
+            span.set_status(Status(StatusCode.OK))
+            logger.info(f"Exported AER-1 receipt {receipt.get('id', '')[:8]} as OTel span")
+    
+    def export_receipts(self, receipts):
+        """Export multiple receipts."""
+        for receipt in receipts:
+            self.export_receipt(receipt)

aer1_middleware-0.2.0/demo.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""
+AER-1 Live Demo: Verifiable receipts in action.
+
+Run this to see AER-1 generate verifiable receipts for tool calls.
+No setup required - uses the middleware directly.
+"""
+
+from aer1_middleware import create_receipt, verify_receipt
+import json
+
+def demo():
+    print("=" * 60)
+    print("AER-1 Verifiable Execution Receipts - Live Demo")
+    print("=" * 60)
+    print()
+    
+    # Simulate a tool call
+    print("1. Agent calls a tool...")
+    tool_name = "search"
+    inputs = {"query": "verifiable receipts"}
+    output = {"results": ["AER-1 draft", "conformance kit", "middleware"]}
+    
+    print(f"   Tool: {tool_name}")
+    print(f"   Inputs: {inputs}")
+    print()
+    
+    # Generate receipt
+    print("2. AER-1 middleware generates a receipt...")
+    receipt = create_receipt(tool_name, inputs, output)
+    print(f"   Receipt ID: {receipt['id']}")
+    print(f"   Output hash: {receipt['output_hash'][:20]}...")
+    print(f"   Timestamp: {receipt['created_at']}")
+    print()
+    
+    # Verify it
+    print("3. Anyone can verify the receipt...")
+    is_valid, reason = verify_receipt(receipt)
+    print(f"   Valid: {is_valid}")
+    print(f"   Reason: {reason}")
+    print()
+    
+    # Tamper with it
+    print("4. Tampering is detected...")
+    tampered = receipt.copy()
+    tampered["canonical_bytes"] = "dGFtcGVyZWQ="  # not the original payload
+    is_valid2, reason2 = verify_receipt(tampered)
+    print(f"   Valid after tamper: {is_valid2}")
+    print(f"   Reason: {reason2}")
+    print()
+    
+    print("=" * 60)
+    print("That's AER-1. Verifiable. Tamper-evident.")
+    print("IETF Internet-Draft. MIT licensed.")
+    print("=" * 60)
+
+if __name__ == "__main__":
+    demo()

aer1_middleware-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aer1-middleware"
+version = "0.2.0"
+description = "AER-1 verifiable execution receipts for AI agent frameworks"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Brennan Zambo"},
+]
+keywords = ["aer1", "mcp", "agents", "receipts", "verifiable"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+fastmcp = ["fastmcp>=0.1.0"]
+langchain = ["langchain-core>=0.1.0"]
+openai-agents = ["openai-agents>=0.1.0"]
+otel = ["opentelemetry-sdk>=1.0.0"]
+signatures = ["cryptography>=41.0.0"]
+all = ["fastmcp>=0.1.0", "langchain-core>=0.1.0", "openai-agents>=0.1.0", "opentelemetry-sdk>=1.0.0", "cryptography>=41.0.0"]
+
+[project.urls]
+Homepage = "https://zambo.dev"
+Repository = "https://gitlab.com/rambozambodotdev/zambo"
+Documentation = "https://datatracker.ietf.org/doc/draft-zambo-aer1/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["aer1_middleware"]