ai-audit-trail

Prove what your AI did, why, and that nobody changed the record.

Tamper-evident Decision Receipts with Ed25519 signatures, SHA-256 hash-chains, and formal compliance mappings. No blockchain, no SaaS, no lock-in. Self-hosted, offline-verifiable, Python-native.

---

Why this exists

The EU AI Act becomes mandatory for high-risk AI systems in August 2026. It requires tamper-evident logs proving every decision was made correctly (Art. 12). Most teams are solving this with normal logging — which is neither tamper-evident nor legally defensible in an audit.

ai-audit-trail closes this gap with cryptographic receipts that any auditor can verify offline, without accessing your systems. Same principle as a blockchain — without the blockchain overhead, the SaaS dependency, or the vendor lock-in.

Who is this for

• Regulated AI teams (FinTech, HealthTech, LegalTech, InsurTech) who must prove compliance
• Enterprise platform teams deploying LLM agents with tool access
• Security and compliance officers who need audit-ready evidence packages
• Developers who want pip install and 3 lines of code, not a platform migration

What this library provides

ai-audit-trail provides the technical building blocks that support EU AI Act, ISO 42001, and NIST AI RMF compliance. It does not, by itself, guarantee regulatory compliance — compliance is an organizational obligation that extends beyond any single software component. See our Shared Responsibility Model below.

---

Installation

pip install ai-audit-trail                    # Core (Ed25519 + SHA-256 + PII)
pip install "ai-audit-trail[redis]"           # + Redis persistence
pip install "ai-audit-trail[otel]"            # + OpenTelemetry metrics
pip install "ai-audit-trail[all]"             # Everything

Requirements: Python 3.11+ | No external services required | Works air-gapped

---

Quickstart

from ai_audit import (
    AuditConfig, init_audit_config,
    ReceiptCollector, ReceiptStore, ReceiptAction,
    verify_chain, get_verify_key_hex,
)

# 1. Configure once at startup
init_audit_config(AuditConfig(is_production=False))
store = ReceiptStore()

# 2. Wrap every AI request
collector = ReceiptCollector(trace_id="req-1", tenant_id="acme")
collector.set_input("What is our GDPR policy?")
collector.add_check("safety", score=0.02, threshold=0.8, fired=False)
collector.set_output("Our GDPR policy states that...")
collector.set_action(ReceiptAction.ALLOW)
collector.emit(store)
collector.cleanup()

# 3. Verify tamper-evidence
result = verify_chain(store.get_by_tenant("acme"), get_verify_key_hex())
assert result.valid  # Ed25519 + SHA-256 + hash-chain verified

---

Architecture Overview

Receipt Creation        Verification & Compliance       Agentic AI Audit
─────────────────       ──────────────────────────      ──────────────────
ReceiptCollector   ──>  verify_chain()                  ToolCallReceipt
  set_input()           build_compliance_summary()      TraceGraph (DAG)
  add_check()           build_crosswalk()               BehavioralContract
  set_output()          export_evidence_package()       ProvenanceChain
  set_action()          SPRTMonitor
  emit()                DriftMonitor
       │                EpochManager
       v
  ReceiptStore     ──>  StorageBackend ABC
  (in-memory LRU)       InMemoryBackend
  + Redis (optional)    (your custom backends)
  + AuditBuffer

---

Core Features

Decision Receipts (Ed25519 + SHA-256 + Hash-Chain)

Every AI pipeline decision produces a Decision Receipt — a cryptographically sealed, hash-chained record:

What's proven	How
Input integrity	SHA-256 of NFKC-normalized, PII-stripped input
Output integrity	SHA-256 of generated output
Check results	Ordered check records with scores and thresholds
Decision	Action taken (ALLOW / REJECT / ESCALATE / ...)
Model provenance	Model ID + config digest
Non-repudiation	Ed25519 signature (libsodium)
Ordering	Hash-chain linkage (prev_receipt_hash)

Three-stage verification (< 0.1 ms per receipt):

Ed25519 signature  →  detects forgery
SHA-256 self-hash  →  detects corruption
Hash-chain link    →  detects insertions / deletions / reordering

PII Redaction (GDPR Art. 17)

Personal data is stripped before hashing — the audit log never contains raw PII.

from ai_audit import PiiConfig, PiiMode, PiiType

config = PiiConfig(
    enabled_types=frozenset({PiiType.EMAIL, PiiType.PHONE, PiiType.IP}),
    mode=PiiMode.REDACT,  # or HASH (SHA-256) or MASK (a***m)
)
collector = ReceiptCollector(tenant_id="acme", pii_config=config)

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗