epi-recorder 2.1.3__tar.gz → 2.3.0__tar.gz

epi_recorder-2.3.0/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+All notable changes to EPI Recorder are documented here.
+
+EPI follows [Semantic Versioning](https://semver.org/) and treats version changes as
+**corrections to evidence guarantees**, not just feature updates.
+
+---
+
+## [3.0.0] – Planned
+
+> **Status:** Pre-RFC. This is a directional commitment, not a release.
+
+### Intent
+
+v3.0.0 will finalize EPI as a **stable evidence specification**.
+
+#### Planned Changes
+
+- **Removal of legacy patching**
+  - `legacy_patching=True` will no longer be supported
+  - All evidence capture will be explicit
+
+- **Stabilized evidence specification**
+  - Manifest schema frozen
+  - Backward-compatibility guarantees for `.epi` files
+
+- **Forward-compatibility primitives**
+  - Versioned step schemas
+  - Extension mechanism for custom evidence types
+
+- **Trust model refinements** (under consideration)
+  - Organization-level key management
+  - Multi-party signing
+  - Delegation chains
+
+#### Design Philosophy
+
+v3.0.0 is not about features. It is about **guarantees**.
+
+After v3.0.0, the `.epi` format should be:
+- readable by any future version
+- verifiable without the original tooling
+- suitable for long-term archival
+
+---
+
+## [2.3.0] – 2026-02-06
+
+### ⚠️ Design Correction (Migration Required)
+
+This release clarifies EPI's role as an **evidence system**, not a passive logger.
+
+#### Breaking
+- **Implicit monkey-patching disabled by default**
+  - Automatic interception of LLM calls is no longer enabled
+  - Evidence capture is now **explicit by design**
+
+#### Rationale
+Evidence systems must be:
+- intentional
+- reviewable in code
+- stable across SDK versions
+
+Implicit interception was convenient but fragile.  
+Explicit capture provides stronger evidentiary guarantees.
+
+#### Added
+- **Explicit evidence API**
+  - `log_llm_call(response)` — structured capture of LLM responses
+  - `log_chat(data)` — simplified, framework-agnostic capture
+- **Wrapper clients**
+  - `wrap_openai()` — proxy wrapper enabling capture without SDK modification
+- **TracedOpenAI**
+  - Fully wrapped OpenAI client with automatic evidence capture
+
+#### Deprecated
+- `legacy_patching=True`
+  - Temporary compatibility flag
+  - Will be removed in v3.0.0
+
+---
+
+## [2.2.1] – 2026-02-06
+
+### Fixed
+- Guaranteed creation of `steps.jsonl` at recording start
+- Updated tests to match current evidence specification
+- Removed brittle test return semantics
+
+### Added
+- `unpatch_all()` to restore original methods in legacy patching mode
+- Viewer support for error-level evidence steps:
+  - `llm.error`
+  - `http.request`
+  - `http.response`
+  - `http.error`
+
+### Changed
+- Evidence spec version bumped to 2.2.1
+
+---
+
+## [2.2.0] – 2026-01-30
+
+### Clarified Scope
+- EPI's primary artifact is a **portable execution evidence file (.epi)**
+- Debugging tools are treated as **secondary consumers** of evidence
+
+### Added
+- Thread-safe recording using `contextvars`
+- Crash-safe SQLite-based evidence storage
+- `epi debug` — heuristic analysis of recorded evidence
+- Async recording API for concurrent workflows
+
+### Changed
+- License standardized to MIT
+- Documentation updated to emphasize execution evidence
+
+### Technical
+- Replaced global state with context-isolated recording
+- Introduced atomic, append-only storage guarantees
+
+---
+
+## [2.1.3] – 2026-01-24
+
+### Added
+- Google Gemini evidence capture
+- `epi chat` — natural language querying of evidence files
+
+### Fixed
+- Windows terminal compatibility issues
+- Improved error classification and reporting
+- Reduced SDK deprecation noise
+
+---
+
+## [2.1.2] – 2026-01-17
+
+### Security
+- Client-side, offline signature verification in embedded viewer
+- Canonical serialization and public-key inclusion in evidence manifests
+
+### Changed
+- Viewer trust indicators updated
+- Evidence specification versioned
+
+---
+
+## [2.1.1] – 2025-12-16
+
+### Added
+- Reliable `python -m epi_cli` fallback
+- Automatic PATH repair on Windows
+- Universal install scripts
+- Self-healing `epi doctor` diagnostics
+
+### Fixed
+- Windows Unicode terminal issues
+- Packaging and installer reliability
+
+---
+
+## [2.1.0] – 2025-12-15
+
+### Initial Release
+- Portable `.epi` evidence format
+- Cryptographic sealing with Ed25519
+- Embedded offline viewer
+- Zero-config CLI recording

epi_recorder-2.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 EPI Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{epi_recorder-2.1.3 → epi_recorder-2.3.0}/MANIFEST.in

@@ -18,3 +18,5 @@ global-exclude *.pyo
 global-exclude __pycache__
 global-exclude *.so
 global-exclude .DS_Store
+
+ 

epi_recorder-2.3.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: epi-recorder
+Version: 2.3.0
+Summary: Verifiable execution evidence for AI systems. Portable, cryptographically signed artifacts.
+Author-email: EPI Labs <mohdibrahim@epilabs.org>
+Maintainer-email: Mohd Ibrahim Afridi <mohdibrahim@epilabs.org>
+License: MIT
+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,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: License :: OSI Approved :: MIT License
+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.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: cbor2>=5.6.0
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: google-generativeai>=0.4.0
+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: black>=24.0.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+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>Verifiable Execution Evidence for AI Systems / AI Agents</strong></p>
+  <p align="center">
+    <em>A portable, cryptographically sealed artifact format for AI execution records.</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=for-the-badge&color=00d4ff&label=PyPI" alt="PyPI"/></a>
+  <a href="https://github.com/mohdibrahimaiml/epi-recorder"><img src="https://img.shields.io/badge/python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/></a>
+</p>
+
+---
+
+## What is EPI?
+
+EPI (Evidence Package for AI) is a **file format** for capturing and verifying AI execution evidence.
+
+An `.epi` file is to AI execution what PDF is to documents:
+- **Self-contained** — prompts, responses, environment, viewer — all in one file
+- **Universally viewable** — opens in any browser, no software required
+- **Tamper-evident** — Ed25519 signatures prove the record wasn't altered
+
+EPI is designed for **adversarial review**: audits, incident response, compliance, litigation.
+
+---
+
+## Design Guarantees
+
+EPI artifacts provide the following guarantees:
+
+| Guarantee | Implementation |
+|:----------|:---------------|
+| **Explicitness** | Evidence capture is intentional and reviewable in source code |
+| **Portability** | Single file, no external dependencies, works offline |
+| **Offline Verifiability** | Signature verification requires no network or cloud services |
+| **Adversarial Review** | Format assumes the reviewer does not trust the producer |
+
+These are not features. They are **constraints** that define what EPI is.
+
+---
+
+## Quick Start
+
+```bash
+pip install epi-recorder
+```
+
+### Capture Evidence (Explicit API)
+
+```python
+from epi_recorder import record
+
+with record("evidence.epi") as epi:
+    response = client.chat.completions.create(model="gpt-4", messages=[...])
+    epi.log_llm_call(response)  # Explicit capture
+```
+
+### Capture Evidence (Wrapper Client)
+
+```python
+from epi_recorder import record, wrap_openai
+from openai import OpenAI
+
+client = wrap_openai(OpenAI())
+
+with record("evidence.epi"):
+    response = client.chat.completions.create(...)  # Captured via wrapper
+```
+
+### Verify Evidence
+
+```bash
+epi verify evidence.epi
+```
+
+---
+
+## The `.epi` Artifact Format
+
+An `.epi` file is a ZIP archive with a defined structure. See [docs/EPI-SPEC.md](docs/EPI-SPEC.md) for the full specification.
+
+```
+evidence.epi
+├── mimetype              # "application/epi+zip"
+├── manifest.json         # Metadata + Ed25519 signature
+├── steps.jsonl           # Execution steps (NDJSON)
+├── env.json              # Runtime environment snapshot
+└── viewer/
+    └── index.html        # Self-contained offline viewer
+```
+
+The embedded viewer allows any recipient to:
+- View the complete execution timeline
+- Verify cryptographic integrity
+- Inspect individual steps
+
+No software installation required.
+
+---
+
+## CLI Reference
+
+### Primary Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `epi run <script.py>` | Capture execution evidence to `.epi` |
+| `epi verify <file.epi>` | Verify artifact integrity and signature |
+| `epi view <file.epi>` | Open artifact in browser viewer |
+| `epi keys list` | Manage signing keys |
+
+### Secondary Tools
+
+These tools consume evidence artifacts for analysis:
+
+| Command | Purpose |
+|:--------|:--------|
+| `epi debug <file.epi>` | Heuristic analysis (loops, errors, inefficiencies) |
+| `epi chat <file.epi>` | Natural language querying via LLM |
+
+> **Note:** `debug` and `chat` are convenience tools built on top of the evidence format.
+> They are not part of the core specification.
+
+---
+
+## Cryptographic Properties
+
+| Property | Implementation |
+|:---------|:---------------|
+| **Signatures** | Ed25519 (RFC 8032) |
+| **Hashing** | SHA-256 content addressing |
+| **Key Storage** | Local keyring, user-controlled |
+| **Verification** | Client-side, zero external dependencies |
+
+Signatures are **optional but recommended**. Unsigned artifacts are still valid but cannot prove origin.
+
+---
+
+## When to Use EPI
+
+### Appropriate Use Cases
+
+- Post-incident forensics
+- Compliance documentation
+- Audit trails for autonomous systems
+- Reproducibility evidence for research
+- Litigation-grade execution records
+
+### Not Designed For
+
+- Real-time monitoring dashboards
+- High-frequency telemetry
+- System health metrics
+- Application performance monitoring
+
+EPI produces **artifacts**, not **streams**.
+
+---
+
+## Supported Providers
+
+| Provider | Capture Method |
+|:---------|:---------------|
+| OpenAI | Wrapper client or explicit API |
+| Anthropic | Explicit API |
+| Google Gemini | Explicit API |
+| Any HTTP-based LLM | Explicit API via `log_llm_call()` |
+
+EPI does not depend on provider-specific integrations. The explicit API works with any response format.
+
+---
+
+## v2.3.0 — Design Correction
+
+This release corrects EPI's evidence capture model.
+
+| Before (v2.2.x) | After (v2.3.0) |
+|:----------------|:---------------|
+| Implicit monkey-patching | Explicit capture |
+| Fragile to SDK changes | Stable across versions |
+| Hidden instrumentation | Reviewable in source |
+
+**Rationale:** Evidence systems must be intentional. Implicit capture was convenient but violated the explicitness guarantee.
+
+**Migration:** Replace implicit capture with `epi.log_llm_call(response)` or `wrap_openai()`.
+
+**Legacy mode:** `record(legacy_patching=True)` is deprecated and will be removed in v3.0.
+
+---
+
+## Release History
+
+| Version | Date | Summary |
+|:--------|:-----|:--------|
+| **2.3.0** | 2026-02-06 | Explicit capture, wrapper clients, design correction |
+| **2.2.0** | 2026-01-30 | SQLite storage, async support, context isolation |
+| **2.1.3** | 2026-01-24 | Gemini capture, evidence querying |
+| **2.1.0** | 2025-12-15 | Initial release |
+
+See [CHANGELOG.md](./CHANGELOG.md) for full details.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/mohdibrahimaiml/epi-recorder.git
+cd epi-recorder
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).

epi_recorder-2.3.0/README.md

@@ -0,0 +1,224 @@
+<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>Verifiable Execution Evidence for AI Systems / AI Agents</strong></p>
+  <p align="center">
+    <em>A portable, cryptographically sealed artifact format for AI execution records.</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=for-the-badge&color=00d4ff&label=PyPI" alt="PyPI"/></a>
+  <a href="https://github.com/mohdibrahimaiml/epi-recorder"><img src="https://img.shields.io/badge/python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white" alt="Python"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/></a>
+</p>
+
+---
+
+## What is EPI?
+
+EPI (Evidence Package for AI) is a **file format** for capturing and verifying AI execution evidence.
+
+An `.epi` file is to AI execution what PDF is to documents:
+- **Self-contained** — prompts, responses, environment, viewer — all in one file
+- **Universally viewable** — opens in any browser, no software required
+- **Tamper-evident** — Ed25519 signatures prove the record wasn't altered
+
+EPI is designed for **adversarial review**: audits, incident response, compliance, litigation.
+
+---
+
+## Design Guarantees
+
+EPI artifacts provide the following guarantees:
+
+| Guarantee | Implementation |
+|:----------|:---------------|
+| **Explicitness** | Evidence capture is intentional and reviewable in source code |
+| **Portability** | Single file, no external dependencies, works offline |
+| **Offline Verifiability** | Signature verification requires no network or cloud services |
+| **Adversarial Review** | Format assumes the reviewer does not trust the producer |
+
+These are not features. They are **constraints** that define what EPI is.
+
+---
+
+## Quick Start
+
+```bash
+pip install epi-recorder
+```
+
+### Capture Evidence (Explicit API)
+
+```python
+from epi_recorder import record
+
+with record("evidence.epi") as epi:
+    response = client.chat.completions.create(model="gpt-4", messages=[...])
+    epi.log_llm_call(response)  # Explicit capture
+```
+
+### Capture Evidence (Wrapper Client)
+
+```python
+from epi_recorder import record, wrap_openai
+from openai import OpenAI
+
+client = wrap_openai(OpenAI())
+
+with record("evidence.epi"):
+    response = client.chat.completions.create(...)  # Captured via wrapper
+```
+
+### Verify Evidence
+
+```bash
+epi verify evidence.epi
+```
+
+---
+
+## The `.epi` Artifact Format
+
+An `.epi` file is a ZIP archive with a defined structure. See [docs/EPI-SPEC.md](docs/EPI-SPEC.md) for the full specification.
+
+```
+evidence.epi
+├── mimetype              # "application/epi+zip"
+├── manifest.json         # Metadata + Ed25519 signature
+├── steps.jsonl           # Execution steps (NDJSON)
+├── env.json              # Runtime environment snapshot
+└── viewer/
+    └── index.html        # Self-contained offline viewer
+```
+
+The embedded viewer allows any recipient to:
+- View the complete execution timeline
+- Verify cryptographic integrity
+- Inspect individual steps
+
+No software installation required.
+
+---
+
+## CLI Reference
+
+### Primary Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `epi run <script.py>` | Capture execution evidence to `.epi` |
+| `epi verify <file.epi>` | Verify artifact integrity and signature |
+| `epi view <file.epi>` | Open artifact in browser viewer |
+| `epi keys list` | Manage signing keys |
+
+### Secondary Tools
+
+These tools consume evidence artifacts for analysis:
+
+| Command | Purpose |
+|:--------|:--------|
+| `epi debug <file.epi>` | Heuristic analysis (loops, errors, inefficiencies) |
+| `epi chat <file.epi>` | Natural language querying via LLM |
+
+> **Note:** `debug` and `chat` are convenience tools built on top of the evidence format.
+> They are not part of the core specification.
+
+---
+
+## Cryptographic Properties
+
+| Property | Implementation |
+|:---------|:---------------|
+| **Signatures** | Ed25519 (RFC 8032) |
+| **Hashing** | SHA-256 content addressing |
+| **Key Storage** | Local keyring, user-controlled |
+| **Verification** | Client-side, zero external dependencies |
+
+Signatures are **optional but recommended**. Unsigned artifacts are still valid but cannot prove origin.
+
+---
+
+## When to Use EPI
+
+### Appropriate Use Cases
+
+- Post-incident forensics
+- Compliance documentation
+- Audit trails for autonomous systems
+- Reproducibility evidence for research
+- Litigation-grade execution records
+
+### Not Designed For
+
+- Real-time monitoring dashboards
+- High-frequency telemetry
+- System health metrics
+- Application performance monitoring
+
+EPI produces **artifacts**, not **streams**.
+
+---
+
+## Supported Providers
+
+| Provider | Capture Method |
+|:---------|:---------------|
+| OpenAI | Wrapper client or explicit API |
+| Anthropic | Explicit API |
+| Google Gemini | Explicit API |
+| Any HTTP-based LLM | Explicit API via `log_llm_call()` |
+
+EPI does not depend on provider-specific integrations. The explicit API works with any response format.
+
+---
+
+## v2.3.0 — Design Correction
+
+This release corrects EPI's evidence capture model.
+
+| Before (v2.2.x) | After (v2.3.0) |
+|:----------------|:---------------|
+| Implicit monkey-patching | Explicit capture |
+| Fragile to SDK changes | Stable across versions |
+| Hidden instrumentation | Reviewable in source |
+
+**Rationale:** Evidence systems must be intentional. Implicit capture was convenient but violated the explicitness guarantee.
+
+**Migration:** Replace implicit capture with `epi.log_llm_call(response)` or `wrap_openai()`.
+
+**Legacy mode:** `record(legacy_patching=True)` is deprecated and will be removed in v3.0.
+
+---
+
+## Release History
+
+| Version | Date | Summary |
+|:--------|:-----|:--------|
+| **2.3.0** | 2026-02-06 | Explicit capture, wrapper clients, design correction |
+| **2.2.0** | 2026-01-30 | SQLite storage, async support, context isolation |
+| **2.1.3** | 2026-01-24 | Gemini capture, evidence querying |
+| **2.1.0** | 2025-12-15 | Initial release |
+
+See [CHANGELOG.md](./CHANGELOG.md) for full details.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/mohdibrahimaiml/epi-recorder.git
+cd epi-recorder
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License. See [LICENSE](./LICENSE).

epi_recorder-2.3.0/epi_analyzer/__init__.py

@@ -0,0 +1,9 @@
+"""EPI Analyzer package - Agent mistake detection"""
+
+from .detector import MistakeDetector
+
+__all__ = ['MistakeDetector']
+
+
+
+