EPI (Evidence Packaged Infrastructure) — Evidence for AI agents

Record. Seal. Verify offline. The answer is a file.

pip install epi-recorder
epi demo --no-browser    # record → seal → verify (no API key)

60-second path · What a .epi is · CLI · How to use it · Docs · Standards

How it works: ARCHITECTURE.md — packages, integrity model, and where to read next. Docs map: docs/README.md.

When someone asks what your agent did six months ago,
the answer should be a .epi file — not a dashboard login and a shrug.

epi-recorder turns an AI agent's run into evidence a third party can verify. Not a log you have to trust, but a portable, signed artifact that leaves your platform and declares exactly what it captured — verifiable offline with open tooling. No account and no EPI server: verification is fully offline. When sealing, EPI asks public RFC 3161 timestamp services for a trusted time (only a hash is sent; switch off with EPI_NOTARIZE=0 or use your own with EPI_TSA_URLS).

Open a sealed .epi offline — epi view run.epi

Forensic case view of a sealed run. Sample artifact: docs/assets/readme-demo.epi

60-second path

Works without any LLM API key:

# demo.py
from epi_recorder import record, get_current_session

with record("demo.epi", goal="show the golden path"):
    s = get_current_session()
    s.log("tool.call", tool="lookup", id="A-1")
    s.log("tool.response", tool="lookup", ok=True, balance=250)
    s.log("decision", action="approve", reason="within limit")

python demo.py
epi verify demo.epi
epi-register demo.epi
epi view demo.epi

record("demo.epi") writes epi-recordings/demo.epi: a bare file name goes into ./epi-recordings/. A path with a folder, such as ./demo.epi or out/demo.epi, is written exactly there. Run the commands above from the same folder as demo.py; epi verify demo.epi finds the file in ./epi-recordings/.

Running python demo.py again never replaces earlier evidence: the second run seals to epi-recordings/demo-2.epi (then demo-3.epi, …) and says so. Set EPI_OVERWRITE=1 to replace demo.epi in place instead.

$ python demo.py
[EPI] 3 steps → epi-recordings/demo.epi  Signed ✓

Typical first-run verify:

First-run WARN / LOCAL identity is normal — seal integrity and signature can still pass.
Identity is separate from seal. A customer pins the sender's key, obtained out of band, with epi keys trust <sender-key-file> --name <name> (the sender's .pub, did.json or saved epi keys export line — never the .epi you are checking) or epi keys trust --from-did did:web:vendor.com --name <name>.
Policy / “did the run break our rules?” is separate again: epi analyze — see docs/POLICY.md.

epi-register is a standalone alias for epi scitt register (same options, same result). Without --service <url> it creates a LOCAL self-issued receipt signed by your own key, not an entry in an independent transparency ledger; pass --service for that.

That’s the product. Everything below is optional depth.

With OpenAI

from openai import OpenAI
from epi_recorder import record, wrap_openai

client = wrap_openai(OpenAI())  # needs OPENAI_API_KEY

with record("agent.epi", goal="Answer a user question"):
    client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello"}],
    )

python agent.py
epi verify agent.epi
epi view agent.epi

API keys in prompts/headers are redacted automatically before they land in the file.

What a .epi file is

Every .epi uses the Envelope v2 container format — a polyglot HTML+ZIP binary that opens natively in any browser and can be extracted programmatically.

demo.epi
├── mimetype
├── manifest.json              # Ed25519 signature + SHA-256 file hashes
├── steps.jsonl                # Timeline (hash-linked steps)
├── environment.json           # Runtime snapshot (sensitive env redacted)
├── policy.json                # Sealed rulebook copy (when policy ran)
├── policy_evaluation.json     # Control results (when policy ran)
├── analysis.json              # Fault / policy analysis (when generated at seal)
├── viewer.html                # Offline forensic UI
├── VERIFY.txt                 # Plain-text auditor instructions
└── artifacts/notarization/    # RFC 3161 tokens (when a TSA answered)

Samples: docs/assets/SAMPLES.md · try docs/assets/readme-demo.epi.

Integrations

# LangChain (canonical adapter)
from langchain_openai import ChatOpenAI
from epi_recorder import record
from epi_recorder.adapters.langchain import EpiCallbackHandler

with record("run.epi") as session:
    handler = EpiCallbackHandler(session)
    llm = ChatOpenAI(model="gpt-4o-mini", callbacks=[handler])
    llm.invoke("…")

# pytest — attach evidence to failing tests
pytest --epi

pytest --epi writes one .epi per failing test to ./test-evidence/ (--epi-dir DIR to change it, --epi-on-pass to keep passing tests too). Files are named after the test (test_x.py_test_bad.epi); unlike record(), a re-run replaces the file for the same test in place.

TRACE export (honest claims)

epi export trace run.epi --out run.trace.json --transcript-uri https://host/run.epi

Signing key order: --key → private key that sealed the .epi → TRACE_PRIVATE_KEY_PEM → ephemeral (warning). allow_embedded_key=True when verifying only proves internal consistency of the record against its own cnf.jwk. It does not prove the record came from a trusted issuer. What we claim: the JSON is self-consistent and bound to the key that signed it (the sealing key when that key is available).

policy.bundle_hash in TRACE is specified as a Cedar policy hash. We hash policy.json (the sealed EPI policy document), not a Cedar bundle. policy.enforcement_mode is "declared" — we did not run a Cedar engine. appraisal.status is "none".

More: docs/FRAMEWORK-INTEGRATIONS-5-MINUTES.md

CLI

Policy + fault analyzer guide: docs/POLICY.md

EPI Cloud (share a run with a customer)

Sealed runs stay offline by default. To share one with a customer (a bank reviewer, an auditor), push it to EPI Cloud and send them a trust link they open in a browser — nothing to install on their side.

Install inside a virtual environment, so EPI's libraries stay separate from your other tools:

python -m venv epienv
epienv\Scripts\activate
pip install epi-recorder
epi --version

(source epienv/bin/activate on macOS/Linux. If Windows says epi is "not on PATH" after install, the program landed in a folder Windows doesn't search: activate the environment first and install/run in that same window, or run python -m epi_cli instead of epi.)

Then, in order:

1. epi cloud login — the terminal shows a short code. Type it at cloud.epilabs.org/auth/device and pick the customer this computer records for. Nothing secret to copy.
2. epi demo — records, seals and uploads a sample run for that customer.
3. On cloud.epilabs.org, create a share link for the customer and send it to them. They verify the run in their browser, or offline with epi verify.

Free plan: 1 customer. A second customer needs an upgrade (Plans page).

Security defaults

• Redaction is on (redact=True). Keys/tokens/PII become placeholders.
• Prefer not using redact=False in production (it warns).
• Verification is local — no network required for integrity/signature.
• First-run identity WARN / LOCAL is expected until you trust a key.
• Seal ≠ identity ≠ policy. Verify proves the file; analyze grades the run against rules/heuristics.

Docs

Start at docs/README.md. Do not treat old search hits or forks as current.

Standards & compliance

EPI produces evidence files that help with audit trails. It is not a compliance guarantee and does not provide legal advice. Whether evidence satisfies a specific regulatory threshold is for the auditor or notified body to determine.

epi verify agent.epi --aiuc1   # evidence grouped by AIUC-1 domain (not a certification)

Troubleshooting

Trust-model note: Integrity checks whether the sealed record was altered since sealing — not that every real-world action was captured.

Project layout (contributors)

Core (actively developed, covered by the release gate):

Experimental (frozen — works as documented, bug fixes allowed, no new features until a paying user asks; not on the critical path):

Website edits: only under website/. npm run build copies it to site/ for Cloudflare Pages; python scripts/sync_website.py mirrors it to verify_portal/static/ and epi-official/. Details: docs/WEBSITE.md, ARCHITECTURE.md.

License

MIT — see LICENSE.

Site: epilabs.org · Issues: GitHub Issues