When an AI system takes an action — issues a refund, moves money, files a ticket — "we have logs" is not the same as having evidence. incident-ledger turns an inference log into evidence by enforcing three properties in code, not prose:

This is the minimal reference implementation accompanying the paper "Implementing Agentic-AI Accountability". It implements the logging / audit-trail control common to the IMDA MGF, EU AI Act, NIST AI RMF, and ISO/IEC 42001 — and it is deliberately small: every line is meant to be read.

How the chain works

graph LR
    G["GENESIS<br/>(0 × 64)"] --> R1["seq 1<br/>H(content₁ + GENESIS)"]
    R1 --> R2["seq 2<br/>H(content₂ + hash₁)"]
    R2 --> R3["seq 3<br/>H(content₃ + hash₂)"]
    R3 --> D["…"]
    style G fill:#e8e8e8,stroke:#888,color:#000
    style R1 fill:#d7ebff,stroke:#3b82f6,color:#000
    style R2 fill:#d7ebff,stroke:#3b82f6,color:#000
    style R3 fill:#d7ebff,stroke:#3b82f6,color:#000

Each seal depends on the one before it, so history can only be appended — never quietly rewritten.

Install

pip install incident-ledger

git clone https://github.com/MaqAnquor/incident-ledger
cd incident-ledger
pip install -e .

Requires Python ≥ 3.10. No third-party dependencies.

Quickstart

from incident_ledger import IncidentLedger

# Open on a file for a durable ledger (":memory:" for tests).
ledger = IncidentLedger("evidence.db")

entry = ledger.append(
    query="Is order #9871244 refundable?",
    answer="Yes — $487 refund issued.",
    confidence=0.91,
    model_version="refund-clf-v3@sha-9c1a2f",   # pin the exact model; never "latest"
    context_snapshot="Policy R-12: refunds within 30 days of delivery.",
    sources=("policy://refunds/R-12", "order://9871244"),
    disclosed_limits=("partial-refund case untested",),
    downstream_action="refund.issue",
    trace={"sampling": {"seed": 482991, "temperature": 0.0}},
)

# The chain is intact...
assert ledger.verify().ok

# ...and tampering is detectable, even done directly against the file.
import sqlite3
raw = sqlite3.connect("evidence.db")
raw.execute("UPDATE ledger SET answer = 'No refund' WHERE seq = 1")
raw.commit(); raw.close()

result = IncidentLedger("evidence.db").verify()
assert not result.ok
print(result.broken_seq, result.reason)   # 1  "altered content at seq 1: seal does not recompute"

Replay a sealed decision

from incident_ledger import replay_from_ledger

# Reconstruct the bundle from a sealed row and rerun it. The attempt itself
# is sealed back into the ledger as a new contemporaneous entry.
outcome = replay_from_ledger(ledger, seq=1)
print(outcome.mode, outcome.reproduced)   # "deterministic" True

A row sealed with no captured seed is reported not-replayable rather than silently treated as deterministic — a gap you disclose, not one you paper over.

Independent verification: checkpoints

A hash chain the deployer controls end-to-end is still only tamper-evident: an owner who edits one row can recompute every later seal and present a clean chain. A checkpoint — a single RFC 6962 Merkle root over the sealed entries — is one short value you can hand to a counterparty or auditor. Once that root is witnessed outside your control, you can no longer rewrite any history it covers.

from incident_ledger import verify_inclusion

cp = ledger.checkpoint()          # one root over all entries — publish/witness this
proof = ledger.prove_inclusion(seq=1)   # O(log n) path, not the whole ledger

# A third party checks one entry against the root they witnessed — no ledger copy,
# no cooperation from the deployer at check time.
assert verify_inclusion(ledger.get(1), proof, cp.root)

The point, in one line: an owner can rewrite the whole chain so that verify() still passes — but the rewritten ledger's checkpoint root will not match a root witnessed beforehand.

What this does and does not buy. A root you compute locally is still owner-recomputable — by itself that's still tamper-evidence, not independence. This module supplies the machinery (a compact digest and O(log n) proofs); reaching true independent verifiability requires a party who is not the deployer to hold the checkpoint. The code makes witnessing cheap; it cannot make it unnecessary. No external service, no blockchain, no network — stdlib-only.

API

Measured overhead

Tamper-evidence is cheap. On a modern laptop (file-backed SQLite, one synchronous commit per append), over 1,000 appends:

The hash chain adds far less than the SQLite commit already costs. Regenerate the numbers on your own machine:

python benchmarks/ledger_overhead.py --n 1000 --reps 3

Figures are measured on a single machine, single thread, one payload shape and one durability setting; they do not extrapolate to production write-concurrency or a different retention policy.

Tests

pip install pytest
pytest -q

Citing

If you use this software, please cite both the software and the paper — see CITATION.cff.

• Software: 10.5281/zenodo.21387489
• Paper: 10.5281/zenodo.21387487 — Implementing Agentic-AI Accountability: A Minimal, From-Scratch Reference Stack Mapped to the IMDA MGF, EU AI Act, NIST, and ISO/IEC 42001

Both the software and the paper are permanently archived on Zenodo under the DOIs above.

License

MIT © Abhijeet Verma