# OpenImpact Agent Guide

## Architecture

- `src/openimpact/contracts.py`: shared data contracts for requests, plan deltas, and venue batches.
- `src/openimpact/model.py`: deterministic temporary-impact regression model.
- `src/openimpact/federated.py`: local venue training, secure aggregation, and federated orchestration.
- `src/openimpact/synthetic.py`: deterministic synthetic market generator for safe testing.
- `src/openimpact/replay.py`: replay engine with deterministic latency jitter.
- `src/openimpact/ledger.py`: SQLite governance ledger for model updates.
- `src/openimpact/evaluation.py`: RMSE, latency, and leakage-style metrics.
- `src/openimpact/pipeline.py`: end-to-end demo runner.

## Tech Stack

- Python 3.11+
- `numpy` and `pandas` for numeric and tabular work.
- `sqlite3` from the standard library for durable audit logging.
- `pytest` for tests.

## Rules

- Keep the synthetic generator deterministic for a fixed seed.
- Prefer the smallest correct change that preserves the model/evaluation contract.
- Update tests whenever behavior changes.
- Keep public APIs importable from `openimpact`.
- `test.sh` must keep passing `pytest` and `python3 -m build`.

## Verification

- `bash test.sh`
- `python -m openimpact`