Decision records for AI agents
Every AI decision, in one file your customer can check.
Record what the model saw, what it decided and why, which model answered, and who approved it.
Seal it into a signed .epi. Anyone can verify it offline — no account, no server, and no Python
required if they use the browser verifier.
pip install epi-recorder
epi demo --no-browser # record → seal → verify, no API key
Current release: v4.10.0 (prepared; PyPI publish pending) — changelog
See a real decision record ·
What a .epi is ·
Verify one ·
CLI ·
Docs
What this proves, and what it does not. A sealed
.epiproves the record has not changed since it was sealed, and that it was signed by the key you pinned. It does not prove the agent captured everything it did, that the decision was correct, or that you are compliant. It is evidence input, not a certificate.EPI is not a compliance guarantee and does not provide legal advice. Whether evidence satisfies a specific regulatory threshold is for your auditor or notified body to decide.
Who this is for
AI vendors selling decision-making agents into insurance, lending and banking — and the carriers, banks and auditors reviewing them.
The question that stalls those reviews is always the same: "For claim 4471, what did your model see, what did it decide, why, which version answered, and who overrode it?" Logs do not answer it, and a vendor-hosted dashboard is the thing the reviewer is least willing to trust.
EPI answers it with one file per decision that leaves your platform and can be checked by the party who does not trust you.
60-second path
No API key, no account:
# 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 view demo.epi
| Step | Command | What you get |
|---|---|---|
| Record + seal | python demo.py |
Signed epi-recordings/demo.epi, secrets redacted by default |
| Verify | epi verify demo.epi |
SHA-256 integrity, Ed25519 signature, step chain — offline |
| View | epi view demo.epi |
Local browser viewer (screenshot below) |
| Explain | epi analyze demo.epi |
Fault and policy summary, without opening the viewer |
First-run identity is LOCAL / UNKNOWN, and that is normal. Seal integrity and identity are
separate facts. A reviewer pins your key, obtained out of band — never from the file being checked:
epi keys trust vendor.pub --name acme
epi keys trust --from-did did:web:vendor.example --name acme
A bare filename goes to ./epi-recordings/. A path with a folder (./demo.epi) is written exactly
there. Re-running never overwrites evidence: it writes demo-2.epi, demo-3.epi, and says so.
EPI_OVERWRITE=1 replaces in place.
Forensic view of a sealed run. Sample artifact: docs/assets/readme-demo.epi
What a .epi file is
A sealed .epi is data-only by default: a plain ZIP that verifies offline and opens in the
local viewer with epi view, with no HTML inside.
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)
├── VERIFY.txt # Plain-text auditor instructions
└── artifacts/notarization/ # RFC 3161 tokens (when a TSA answered)
Seal with --with-viewer (record(..., with_viewer=True), epi demo --with-viewer) and the file
also becomes an Envelope v2 polyglot HTML+ZIP: it opens by double-click in any browser and still
extracts as a ZIP. The HTML shell is the only difference; both forms verify identically.
| Guarantee | How |
|---|---|
| Integrity | SHA-256 over every sealed member |
| Authenticity | Ed25519 signature on the manifest |
| Chain | Each step's prev_hash links the timeline |
| Time | Optional RFC 3161 timestamp from a public TSA — only a hash is sent |
| Privacy | Redaction on by default: API keys, tokens, email, phone, card and US SSN patterns |
Redaction is pattern-based. It does not catch names, IBANs or domain-specific identifiers — allowlist the fields you must preserve, and read FILE-SAFETY.md before sending a file outside your organisation.
Verify a file you received
This is the path your customer, auditor or examiner takes. It needs no account, no licence and no network:
pip install epi-recorder
epi verify claim-4471.epi --policy strict
--policy strictis what you rely on for a pass/fail exit code; a plain WARN exits 0.- Add
--witness-log received.jsonlto prove this is the version that was reported to you, not one re-signed later with a valid key. - No Python on the reviewer's machine? They can use the browser verifier or the standalone verifier.
Three separate questions, three separate answers — do not conflate them:
| Question | Command |
|---|---|
| Is the file intact and signed? | epi verify FILE |
| Do I know who signed it? | pin the key with epi keys trust, then verify |
| Did the run follow our rules? | epi analyze FILE / epi_policy.json |
Install what you need
The base install is small: it records, seals and verifies. Framework support is optional.
| Extra | Adds |
|---|---|
epi-recorder[openai] |
wrap_openai |
epi-recorder[anthropic] |
wrap_anthropic |
epi-recorder[aws-kms] / [gcp-kms] / [pkcs11] |
HSM/KMS signing |
epi-recorder[all] |
everything except the dev/test toolchains |
The team gateway (epi gateway serve, epi connect) and the framework
adapters (LangChain, LangGraph, LiteLLM, OpenAI Agents, OpenTelemetry,
Guardrails) ship in the paid epi-enterprise package. The base install
above records, seals and verifies.
# pip install "epi-recorder[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"}],
)
API keys in prompts and headers are redacted before they reach the file.
Integrations
| Stack | How |
|---|---|
| OpenAI | wrap_openai(OpenAI()) |
| Anthropic | wrap_anthropic(Anthropic()) |
| LangChain | EpiCallbackHandler(session) inside with record(...) as session |
| LiteLLM | EPICallback |
| pytest | pytest --epi — one .epi per failing test in ./test-evidence/ (--epi-on-pass keeps passes too) |
| Microsoft AGT | epi import agt <path> |
| Any HTTP client | epi gateway serve records traffic without the SDK |
TRACE export (epi export trace) produces a self-consistent Level 0 record. Signing order is
--key → the key that sealed the .epi → TRACE_PRIVATE_KEY_PEM → ephemeral. policy.enforcement_mode
is "declared": we did not run a Cedar engine, and policy.bundle_hash hashes the sealed EPI policy,
not a Cedar bundle. Details:
FRAMEWORK-INTEGRATIONS-5-MINUTES.md.
Open core: what is free, what is paid
Free forever, Apache-2.0, in this repository: the .epi format, epi verify, the viewer, the recorder
and its integrations, the gateway, the customer-side witness (epi witness serve / report), the
policy engine, epi approvers, epi review, single-user epi oversight report, epi org bundle,
and every offline proof check.
Paid, and not in this repository: EPI Enterprise (epi audit, epi annex, epi notify,
epi chat, regulatory mappings) and EPI Cloud (hosted witnessing, trust pages, retention, team
review). The Cloud client and witness protocol stay open so anyone can build a compatible service.
The promise that makes the file worth anything: epi verify will never require an account, a
licence, a server or a network connection. scripts/audit_wheel.py and
tests/test_open_core_boundary.py enforce both halves — no paid code in the wheel, no gate in the
verifier. Exact boundary:
LICENSING.md.
Share a run with a customer (optional)
Sealed runs stay offline unless you push them. EPI Cloud gives a reviewer a link they open in a browser — nothing to install:
epi cloud login # device code; nothing secret to copy
epi demo # record, seal, upload for that customer
# then create a share link on cloud.epilabs.org
Free workspace: 1 customer, 1 share link, 50 stored runs, 30 days. Team and Business are arranged directly — there is no public checkout. Recording and verification never depend on Cloud.
Security defaults
- Redaction on (
redact=True);redact=Falsewarns. - Verification local — integrity and signature checks need no network.
- Sealing asks a public TSA only for a hash, never the file. Switch off with
EPI_NOTARIZE=0, or point at your own withEPI_TSA_URLS. - Seal ≠ identity ≠ policy. Three checks, three answers.
CLI
| Command | Purpose |
|---|---|
epi demo |
Guided: record → seal → verify |
epi verify <file.epi> |
Offline integrity + signature (--policy strict for exit-code trust) |
epi view <file.epi> |
Local browser viewer |
epi analyze <file.epi> |
Fault / policy summary from the sealed analysis |
epi export-summary <file.epi> |
One-page HTML or text summary per decision |
epi keys generate / list / trust / revoke |
Signing and pinned keys; fingerprints printed |
epi policy init |
Create epi_policy.json |
epi approvers / epi review |
Pin approver keys; the approver signs |
epi witness serve / report |
Customer-side witness receiver |
epi oversight report |
Decisions by outcome, model and approval over a period |
epi org bundle |
The customer's own key history |
epi import agt / epi export trace |
Microsoft AGT in, TRACE Level 0 out |
epi scitt register |
SCITT receipt (local self-issued unless --service <url>) |
Full surface: CLI.md.
Docs
| Topic | Link |
|---|---|
| How to use it (what / where / how) | USER-GUIDE.md |
You received a .epi (one page, no jargon) |
RECIPIENT-CARD.md |
| Verify with no Python installed | STANDALONE-VERIFIER.md |
| What verify means | VERIFICATION_CONTRACT.md |
| Known limitations (read before a security review) | KNOWN_LIMITATIONS.md |
| Is the file safe to open? | FILE-SAFETY.md |
| Architecture, packages, integrity model | ARCHITECTURE.md |
| Bank / auditor briefing | AUDITORS-GUIDE.md |
| EU AI Act Annex IV (templates, not a certificate) | ANNEX-IV.md |
| Docs map | docs/README.md |
Runnable examples — pytest plugin, gateway, witness, AGT and TRACE:
examples/.
Break the seal — try to break the guarantees. Credit only, no bounty: CHALLENGE.md.
Contributing, security, support
- Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md
- Security reports: SECURITY.md — please do not open a public issue
- Support and scope: SUPPORT.md
- License: Apache-2.0 from 4.10.0 - LICENSE and NOTICE. Versions up to and including 4.9.0 are MIT and stay MIT.
Built by Mohd Ibrahim Afridi at EPI Labs · epilabs.org · Issues
EPI is not affiliated with the NAIC, and nothing here is legal advice. Whether evidence satisfies a regulatory threshold is for your auditor or notified body to decide.
Metadata
Release files for epi-recorder 4.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| epi_recorder-4.10.0.tar.gz | 1.5 MB | With provenance | Details for epi_recorder-4.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| epi_recorder-4.10.0-py3-none-any.whl | Python 3 | none | any | Details for epi_recorder-4.10.0-py3-none-any.whl |
Total release size: 2.4 MB
Release files / epi_recorder-4.10.0.tar.gz
| Download URL | epi_recorder-4.10.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d0434481f5c460af45b798a78f71e90d515ab363f36a2a18ad92450422dc4681
|
|
BLAKE2b-256 checksum How to use checksums |
b9c96e8bec1d58767afcf39750b32567808ec0a4ba7b65511d63ea7b2d7983b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / epi_recorder-4.10.0-py3-none-any.whl
| Download URL | epi_recorder-4.10.0-py3-none-any.whl |
|---|---|
| Size | 921.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e4e51050dc141127416eab4bdd7244bd6b4185711e9bb7b13c5c100fdc9d7f69
|
|
BLAKE2b-256 checksum How to use checksums |
3032e31a066b9662edd97c7488a0b2c218b2b59c18d0b93405b0a922d56091d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for epi-recorder 4.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for epi_recorder-4.10.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.