traceseal-langchain

Signed execution receipts for every LangChain model and tool call. Drop in one callback. Hand the receipts to your auditor.

What it does

Add a single callback handler to your LangChain chain, agent, or runnable. Every LLM invocation and every tool call produces a signed Traceseal Execution Receipt — cryptographic proof of what your agent ran, verifiable by any third party.

• No rewrite. Works with existing LangChain code via the standard callback API.
• No vendor lock-in. Receipts verify with pip install traceseal-verify on any machine, no access to your infrastructure.
• Privacy-preserving. Hashes of inputs/outputs, not the values themselves. Safe to share with auditors.
• Workflow chaining. Optional: roll every child call into a single signed orchestration receipt.

Install

pip install traceseal-langchain

Quick start

from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from traceseal_observe import OperatorKey
from traceseal_langchain import TracesealCallbackHandler

key = OperatorKey.load_from_file("~/.traceseal/keys/my-operator.key")
handler = TracesealCallbackHandler(
    operator_key=key,
    workflow_name="research-assistant",
    workflow_version="1.0",
)

@tool
def search(query: str) -> str:
    """Search the web."""
    return f"results for {query}"

llm = ChatOpenAI(model="gpt-4o-mini").bind_tools([search])
result = llm.invoke("research AI safety", config={"callbacks": [handler]})

# One receipt per LLM call and per tool call:
for r in handler.receipts:
    print(r.execution["receipt_type"], r.receipt_hash)

# A single signed orchestration over all of them:
workflow = handler.workflow_receipt()
open("run.json", "w").write(workflow.to_json())

Verify it on any machine:

pip install traceseal-verify
traceseal-verify run.json

What the receipts record

Every receipt is a JSON file signed with the operator's ed25519 key and conforms to RECEIPT-SPEC.md v1.0.

Works with

• langchain-core >= 0.3
• LangChain, LangGraph, LangChain Community — any runnable that accepts a callbacks= config.
• LangGraph agents — the handler captures each node's LLM/tool calls and emits a workflow receipt over the whole graph.

What receipts prove, and what they don't

The operator attests:

"I observed these N LLM calls and M tool calls, in this order, with these input and output hashes."

A third party can verify the signature, confirm the chain hasn't been tampered with, and confirm the operator's key signed it. They cannot confirm (from the receipt alone) that the provider actually returned what was recorded, or that the tool functions behaved honestly. The receipt is an operator attestation, not a zero-knowledge proof — same trust model as any audit log, but cryptographically portable.

See RECEIPT-SPEC.md §6 for the full trust analysis.

Why this matters

Compliance officers, auditors, and regulators are starting to ask: "can you prove what your AI agent actually did?" Today most answers are "trust our logs." Traceseal receipts are the cryptographic primitive that makes the question answerable in portable, verifiable form — third parties don't need access to your machines or your LangSmith account.

License

Apache 2.0.