# AGENTS.md

This repository implements CrossVenueArbX, a lightweight federated, deterministic cross-venue equity arbitrage framework (MVP). The goal of this document is to define the architecture, testing, contribution rules, and onboarding expectations for contributors.

Overview
- Core modules live under `crossvenue_arbx/`:
  - `core.py`: Data contracts for local signals, shared signals, deltas, and governance primitives.
  - `adapters.py`: Starter adapters for venue price feeds and simulated broker execution.
  - `coordinator.py`: Central coordinator implementing a minimal async-ADMM-like flow and deterministic replay.
  - `demo.py`: A small end-to-end demo wiring adapters and the coordinator.
  - `governance.py`: In-memory Graph-of-Contracts registry used for versioning adapters and data contracts.
- Tests exercise core data contracts and a small integration flow via the demo. The test suite is designed to be fast and deterministic.

Getting Started
- Run tests and build: `bash test.sh` (this runs `pytest`, builds the package, and installs it in editable mode).
- To run the demo locally: `python -m crossvenue_arbx.demo --iterations 3` or use `python crossvenue_arbx/demo.py --iterations 3`.

Architecture Guidelines
- LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget form the canonical IR (data contracts).
- Async ADMM-lite: each venue computes local deltas; a central coordinator merges aggregated signals with bounded staleness.
- Privacy and governance: use secure aggregation stubs and a Graph-of-Contracts registry for versioning adapters and data contracts.
- Deterministic replay on reconnects via CRDT-like delta merges and explicit signatures.

Testing & Validation
- Use `test.sh` for quick end-to-end validation. It runs unit tests, builds the package, and ensures packaging metadata compiles.
- Additional checks can be added to CI to exercise the demo end-to-end with more iterations and randomized seeds.

Contribution Rules
- All changes should be covered by tests. If you introduce breaking changes, add or adjust tests accordingly.
- Follow the existing naming conventions used in `crossvenue_arbx/` (CamelCase class names, snake_case functions).
- Update `README.md` with user-facing changes and new data contracts or adapters.

If you are releasing an idea or patch that affects the governance contract or adapters, please ensure you
- add a tag/remark to `governance.py` and wire up versioning in `GraphOfContracts`.
- keep the scope small and well-scoped to enable incremental onboarding and testing.