Metadata-Version: 2.4
Name: proofledger
Version: 0.2.0
Summary: Framework-agnostic, tamper-evident audit layer for AI agents. Hash chains verify byte-for-byte against the ProofLedger TypeScript SDK and dashboard.
Project-URL: Homepage, https://proofledger.dev
Project-URL: Repository, https://github.com/jorama/proofledger
Project-URL: Issues, https://github.com/jorama/proofledger/issues
Author: ProofLedger
License: MIT
License-File: LICENSE
Keywords: agents,ai,audit,hash-chain,llm,observability,proofledger,tamper-evident,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: cryptography>=41; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: signing
Requires-Dist: cryptography>=41; extra == 'signing'
Description-Content-Type: text/markdown

# 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

```bash
pip install proofledger
```

Or from this repo:

```bash
pip install packages/sdk-py
```

## Usage

```python
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.

```python
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`](examples/basic.py) for a complete, runnable example:

```bash
python examples/basic.py
```

## Hashing primitives

The same primitives the dashboard uses are re-exported:

```python
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.
