Metadata-Version: 2.4
Name: epi-recorder
Version: 4.1.0
Summary: Portable repro artifacts for AI agent runs. Capture, open, share, and verify failures in any browser.
Author-email: Mohd Ibrahim Afridi <mohdibrahim@epilabs.org>
Maintainer-email: Mohd Ibrahim Afridi <mohdibrahim@epilabs.org>
Project-URL: Homepage, https://epilabs.org
Project-URL: Documentation, https://epilabs.org/docs
Project-URL: Repository, https://github.com/mohdibrahimaiml/epi-recorder
Project-URL: Issues, https://github.com/mohdibrahimaiml/epi-recorder/issues
Project-URL: Discussions, https://github.com/mohdibrahimaiml/epi-recorder/discussions
Keywords: evidence,forensics,audit,compliance,cryptography,ai,llm,verification,artifact,debugging,bug-report,incident-response,pytest,ci,execution-trace,reproducibility,tamper-evident
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<=2.12.3,>=2.0.0
Requires-Dist: cryptography<44,>=41.0.0
Requires-Dist: cbor2>=5.6.0
Requires-Dist: typer<0.26.0,>=0.16.0
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: rich<14,>=13.0.0
Provides-Extra: ai
Requires-Dist: google-generativeai>=0.4.0; extra == "ai"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == "litellm"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-api>=1.25.0; extra == "opentelemetry"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "opentelemetry"
Provides-Extra: integrations
Requires-Dist: openai>=1.0.0; extra == "integrations"
Requires-Dist: anthropic>=0.25.0; extra == "integrations"
Requires-Dist: litellm>=1.0.0; extra == "integrations"
Requires-Dist: langchain-core>=0.2.0; extra == "integrations"
Requires-Dist: langgraph>=0.2.0; extra == "integrations"
Requires-Dist: opentelemetry-api>=1.25.0; extra == "integrations"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "integrations"
Requires-Dist: wrapt>=1.16.0; extra == "integrations"
Provides-Extra: analytics
Requires-Dist: pandas>=1.5.0; extra == "analytics"
Requires-Dist: matplotlib>=3.5.0; extra == "analytics"
Provides-Extra: gateway
Requires-Dist: fastapi<1,>=0.111.0; extra == "gateway"
Requires-Dist: uvicorn<1,>=0.30.0; extra == "gateway"
Requires-Dist: boto3>=1.34.0; extra == "gateway"
Provides-Extra: all
Requires-Dist: google-generativeai>=0.4.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.25.0; extra == "all"
Requires-Dist: litellm>=1.0.0; extra == "all"
Requires-Dist: langchain-core>=0.2.0; extra == "all"
Requires-Dist: langgraph>=0.2.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.25.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "all"
Requires-Dist: pandas>=1.5.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: fastapi<1,>=0.111.0; extra == "all"
Requires-Dist: uvicorn<1,>=0.30.0; extra == "all"
Requires-Dist: boto3>=1.34.0; extra == "all"
Requires-Dist: wrapt>=1.16.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pandas>=1.5.0; extra == "dev"
Requires-Dist: fastapi<1,>=0.111.0; extra == "dev"
Requires-Dist: uvicorn<1,>=0.30.0; extra == "dev"
Requires-Dist: wrapt>=1.16.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-timeout>=2.3.1; extra == "test"
Requires-Dist: pytest-playwright>=0.5.0; extra == "test"
Requires-Dist: playwright>=1.45.0; extra == "test"
Requires-Dist: httpx>=0.27.0; extra == "test"
Requires-Dist: fastapi<1,>=0.111.0; extra == "test"
Requires-Dist: uvicorn<1,>=0.30.0; extra == "test"
Requires-Dist: pandas>=1.5.0; extra == "test"
Requires-Dist: litellm>=1.0.0; extra == "test"
Requires-Dist: langchain-core>=0.2.0; extra == "test"
Requires-Dist: opentelemetry-api>=1.25.0; extra == "test"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "test"
Requires-Dist: wrapt>=1.16.0; extra == "test"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/mohdibrahimaiml/epi-recorder/main/docs/assets/logo.png" alt="EPI Logo" width="180"/>
  <br>
  <h1 align="center">EPI</h1>
  <p align="center"><strong>Capture any AI agent run into one portable <code>.epi</code> file you can open, share, and verify anywhere.</strong></p>
  <p align="center">
    <em>The forensic bug report artifact for AI systems. No cloud. No login. No internet required.</em>
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/epi-recorder/"><img src="https://img.shields.io/pypi/v/epi-recorder?style=flat-square&label=PyPI&color=0073b7" alt="PyPI Version"/></a>
  <a href="https://github.com/mohdibrahimaiml/epi-recorder/actions/workflows/release-gate.yml"><img src="https://github.com/mohdibrahimaiml/epi-recorder/actions/workflows/release-gate.yml/badge.svg" alt="Build Status"/></a>
  <a href="https://github.com/mohdibrahimaiml/epi-recorder/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mohdibrahimaiml/epi-recorder?style=flat-square&label=license&color=0073b7" alt="License"/></a>
</p>

Reference implementation of **EPI (Evidence Packaged Infrastructure) v4.1.0** — the open format for packaging AI execution as tamper-evident, portable evidence.

---

## Install

```bash
pip install epi-recorder
```

## Get Started in 60 Seconds

```bash
epi demo
```

Runs a sample refund workflow and gives you the full developer repro loop:
1. **Capture** an AI agent run into a portable `.epi` artifact.
2. **View** the case in a browser with `Overview`, `Evidence`, `Policy`, and `Trust`.
3. **Verify** the cryptographic integrity of the file.

---

## Core API

```python
from epi_recorder import record, wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

with record("my_agent.epi", workflow_name="Investigation"):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Analyze this data."}]
    )
```

Open and verify the artifact:

```bash
epi view my_agent.epi    # Browser review (offline)
epi verify my_agent.epi  # Ed25519 integrity check
```

---

## The `.epi` Format

```
my_agent.epi
|- EPI1 header            # outer identity, payload length, SHA-256
`- ZIP evidence payload
   |- manifest.json        # metadata + Ed25519 signature + content hashes
   |- steps.jsonl          # execution timeline (NDJSON)
   |- environment.json     # runtime snapshot
   `- viewer.html          # self-contained offline viewer
```

```mermaid
flowchart LR
    A["Agent Code"] -->|"record()"| B["Capture Layer"]
    B --> C["SQLite WAL"]
    C --> D["ZIP Payload Builder"]
    E["Private Key"] -->|"Ed25519 Sign Manifest"| D
    D -->|"Wrap with EPI1 Envelope"| G["agent.epi"]
```

See [EPI Specification](docs/EPI-SPEC.md) for details. EPI supports evidence workflows for EU AI Act, FDA, and financial services; it does not provide legal advice and is not a compliance guarantee.

---

## Framework Integrations

EPI provides native hooks for major AI frameworks:

- **LiteLLM**: `litellm.callbacks = [EPICallback()]`
- **LangChain**: `ChatOpenAI(..., callbacks=[EPICallbackHandler()])`
- **Guardrails AI**: `instrument(output_path="audit.epi")`
- **OpenTelemetry**: `setup_epi_tracing(service_name="my-agent")`
- **pytest**: `pytest --epi` (records signed evidence for failing tests)

See [Framework Integrations Guide](docs/FRAMEWORK-INTEGRATIONS-5-MINUTES.md) for details.

---

## CLI Reference

| Command | Purpose |
|:--------|:--------|
| `epi run <script.py>` | Record execution to `.epi` |
| `epi view <file.epi>` | Open in browser review view |
| `epi verify <file.epi>` | Verify integrity and signature |
| `epi import agt <bundle>` | Convert AGT evidence to `.epi` |
| `epi export-summary` | Generate a printable Decision Record |
| `epi init` | Initialize a starter demo |
| `epi keys list` | Manage signing keys |

Full reference: [docs/CLI.md](docs/CLI.md)

---

## Technical Documentation

- **[EPI Specification](docs/EPI-SPEC.md)**: Technical details of the `.epi` format.
- **[Policy Guide](docs/POLICY.md)**: How policy, fault analysis, and rulebooks work.
- **[EU AI Act Evidence Prep](docs/EU-AI-ACT-EVIDENCE-PREP.md)**: Evidence workflow guide.
- **[AGT Import Quickstart](docs/AGT-IMPORT-QUICKSTART.md)**: `AGT -> EPI` path.

---

## Contributing

```bash
git clone https://github.com/mohdibrahimaiml/epi-recorder.git
cd epi-recorder
pip install -e ".[dev]"
pytest
```

MIT License. Built by [EPI Labs](https://epilabs.org).
Making AI agent execution verifiable.
