Playbook 09 · Compliance

An audit trail regulators can trust

Goal: a tamper-evident record of every agent decision, guardrail block, tool call, and human handover, one you can hand an auditor knowing that any edit, deletion, or reordering is detectable. Add a live containment scorecard and a read-only dashboard, and the ongoing-monitoring and traceability obligations of modern AI rules stop being a spreadsheet exercise and become a service that is simply running.

No external provider. The audit log, verification, scorecard, and dashboard are all self-hosted Zolva components reading a local database. Nothing leaves your infrastructure.

The shape: the audit log attaches to the same bus every other plugin uses, so it records by construction, no new instrumentation at your call sites. Each entry is hash-chained to the one before it, verification walks the chain from genesis, and the dashboard opens the database read-only to render topology, transcripts, and the scorecard.

Prerequisites #

A running AgentApp and a path for the audit database (for example audit.sqlite).
For the dashboard: pip install "zolva[dashboard]" (adds FastAPI and Uvicorn).
Python ≥ 3.11.

Step 1 · Attach the audit chain #

One attach records everything that crosses the bus. The store sits behind a four-method protocol; SQLite ships as the default, and you can back it with Postgres by implementing the same four methods when you go multi-replica.

app.py

from zolva import AgentApp, AuditLog

app = AgentApp.from_config("agents/")
log = AuditLog("audit.sqlite")   # hash-chained: edits, deletes, reordering all detectable
log.attach(app)

Because the log is downstream of the bus, a guardrail refusal is recorded with the same fidelity as a normal reply: the blocked content, the rule that fired, and the escalation that followed are all on the chain.

Step 2 · Verify the chain and read the scorecard #

Verification is the evidence. A full pass walks from genesis; monitors use an incremental pass plus a periodic full pass. The scorecard reports SARR, the Safe Automated Resolution Rate, alongside its containment counter-metric.

python

from zolva import scorecard

assert log.verify()                       # False if any entry was altered
print(scorecard(log).summary())           # SARR + containment

terminal

zolva scorecard audit.sqlite   # verifies the chain and prints the scorecard

Run zolva scorecard in a scheduled job and alert on a failed verification; a broken chain is the one signal you never want to discover during an audit instead of before it.

Step 3 · Stand up the read-only dashboard #

The dashboard is a self-hosted web UI over the config and the audit database: agent, tool, and handoff topology, a live-tailing session feed with full transcripts, tool-call stats, and the SARR scorecard behind a continuous chain-verification badge. It opens the database read-only and adds no instrumentation.

terminal

pip install "zolva[dashboard]"
zolva dashboard agents/ --audit audit.sqlite    # http://127.0.0.1:8600

It binds to localhost by default and has no auth of its own by design; put your reverse proxy and access controls in front of it, the same way you would any internal ops tool. To see it populated before you have traffic, seed the demo dataset that ships with the examples.

Mapping to the rules #

Traceability: the hash chain makes every decision reconstructable and tamper-evident; verification is a single call that either holds or does not.
Human oversight: handovers are first-class entries, so the record shows when and why a human took over, and how the session resumed.
Ongoing monitoring: the scorecard plus scheduled verification give a standing measure of safe automated resolution, not a one-time validation.
Config provenance: entries are stamped against the config version in force, so you can tell which policy governed any given conversation.

← All playbooks