idea144-crossvenuearbx-federated-deterministic/AGENTS.md

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.