Metadata-Version: 2.4
Name: fixtura
Version: 1.0.4
Summary: Deterministic execution recording and replay for AI agents
Author: Yashrajsinh Rathod
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: requests<3.0,>=2.0
Requires-Dist: zstandard<1.0,>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests>=2.0; extra == "dev"
Dynamic: license-file

# Fixtura

**Deterministic execution recording and replay for AI agents — turn real agent runs into regression tests.**

## What this is

Fixtura watches an AI agent's tool calls (filesystem, database, API, etc.), records everything that happens through a permission-checked execution layer, and lets you replay that recording later — deterministically, without touching live systems — to debug failures or gate CI on regressions.

It's built to work with **OpenEval**, a deterministic (non-LLM-judge) agent evaluation engine already built and published separately. Fixtura produces the recordings; OpenEval scores them.

## Why this exists

Most "agent observability" tools (Langfuse, Phoenix, Braintrust, Laminar) are built for production monitoring at scale. Fixtura's angle is narrower and more testable: **recorded traces as literal test fixtures**, replayable offline, usable to gate pull requests the same way unit test snapshots do. See ARCHITECTURE.md for why this is scoped the way it is, and what was deliberately cut.

## Status

✅ v1.0.2 is released. See ROADMAP.md for future features like counterfactual replay (Live Branching).

## OpenEval Adapter (optional, manual install required)

The OpenEval evaluation harness (Acceptance Test 4) relies on OpenEval, which is currently unpublished on PyPI. Note that the openeval namespace on PyPI is occupied by an unrelated placeholder package. 

To use the OpenEval Adapter, you must manually install OpenEval via git:
`ash
pip install git+https://github.com/yash161004/OpenEval.git@4cb6cfe362c770a7674f5b0111ff54646883709b
`
Without this, pip install fixtura will give you the core recording, permissions, and replay capabilities, but importing ixtura.tools.openeval_adapter will raise a clear RuntimeError prompting this manual installation.

## Documents in this repo

| Doc | Purpose |
|---|---|
| ARCHITECTURE.md | System design, components, data flow |
| THREAT_MODEL.md | Trust boundaries, what could go wrong, mitigations |
| ROADMAP.md | Frozen v1 scope table + acceptance tests + v1.1/v2 future work |
| docs/TRACE_FORMAT_SPEC.md | Exact schema every recording must produce |
| docs/COLLABORATION.md | How the owner, Claude, ChatGPT, and Antigravity work together on this project |

## Core components

1. Tool Execution Layer
2. Permission Engine
3. Execution Recorder + Sanitizer
4. Passive Replay + Step Inspection
5. Trace Viewer UI (minimal)
6. OpenEval adapter (evaluation harness reuse)

## License

[MIT License](LICENSE)
