36 lines
2.5 KiB
Markdown
36 lines
2.5 KiB
Markdown
# 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.
|