ProofLedger Python SDK

A framework-agnostic, tamper-evident audit layer for AI agents. ProofLedger sits underneath or beside any agent framework (LangGraph, CrewAI, OpenAI Agents SDK, AutoGen, or a custom stack) and records every run, event, and tool call into a SHA-256 hash chain.

The chains this SDK produces are byte-for-byte compatible with the ProofLedger TypeScript SDK: runs captured from Python verify correctly in the ProofLedger dashboard, which verifies using the TS implementation.

No third-party runtime dependencies — standard library only (Python >= 3.9).

Install

pip install proofledger

Or from this repo:

pip install packages/sdk-py

Usage

from proofledger import enable, track, with_run, verify_run

# Cloud mode — sends to your ProofLedger backend.
enable(
    api_key="tl_live_...",
    base_url="https://proofledger.dev",
    project_id="proj_...",
)

# One-shot tracking of a complete, verifiable run.
track(
    agent_id="support-agent",
    input="Hello",
    output="Hi there",
    model="gpt-4.1",
    provider="openai",
)

If you call enable() without an api_key (or pass local=True), the SDK runs in local dev mode: events are kept in memory and best-effort appended to ./.proofledger/events.jsonl, with no server required.

Wrapping a unit of work with with_run

with_run opens a run, runs your function, records the result (or the error), and closes the run — all on a verifiable chain. The callback receives a RunHandle you can use to record tool calls and custom events.

from proofledger import enable, with_run, verify_run

enable(local=True)  # local dev mode, no api key

def do_work(run):
    # Record a tool call — emits tool.called + tool.returned around the record.
    run.record_tool_call(
        tool_name="search_kb",
        input={"query": "refund policy"},
        output={"hits": 3},
    )
    return {"answer": "Refunds within 30 days."}

result = with_run({"agent_id": "support-agent", "model": "gpt-4.1"}, do_work)

# Verify the run's hash chain.
report = verify_run(...)  # pass the run id; see examples/basic.py
print(report["valid"])    # True

See examples/basic.py for a complete, runnable example:

python examples/basic.py

Hashing primitives

The same primitives the dashboard uses are re-exported:

from proofledger import (
    create_payload_hash,
    create_event_hash,
    verify_event_chain,
    GENESIS_HASH,
)

• Canonical JSON: object keys are sorted recursively and serialized with no whitespace and literal Unicode, matching JS JSON.stringify with sorted keys.
• GENESIS_HASH is 64 zeros — the previousHash of the first event.
• create_event_hash commits to the event id, type, timestamp, payload hash, and the previous event's hash, chaining every event to the one before it.

Because the canonicalization and digests match the TypeScript SDK exactly, a chain captured in Python verifies identically in the ProofLedger dashboard.