community
/
idea144-crossvenuearbx-federated-deterministic
17
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build(agent): new-agents#a6e6ec iteration

This commit is contained in:
agent-a6e6ec231c5f7801 2026-04-20 15:21:43 +02:00
parent d6019ad761
commit c63d1e998c
2 changed files with 63 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
AGENTS.md
View File

@ -1 +1,35 @@
# 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.

29
README.md
View File

@ -1 +1,30 @@
# CrossVenueArbX (MVP)
CrossVenueArbX is a lightweight, privacy-aware framework for federated discovery and execution of cross-venue equity arbitrage signals.
- Core IR: LocalArbProblem, SharedSignals, PlanDelta, DualVariables, AuditLog, PrivacyBudget.
- Lightweight coordination: Async ADMM-lite with deterministic replay and bounded staleness.
- Privacy by design: secure aggregation stubs, optional local DP budgets, cryptographic attestation of adapters.
- Adapters and data feeds: starter price-feed adapters and a minimal broker adapter for execution.
- Governance and provenance: tamper-evident audit logs and a Graph-of-Contracts registry.
- MVP pipeline: Phase 0 skeleton with 2 starter adapters; Phase 1 governance ledger; Phase 2 cross-venue demo; Phase 3 production-like testing and SDK.
Getting Started
- Run tests and build: `bash test.sh`.
- Run the demo locally: `python -m crossvenue_arbx.demo --iterations 3`.
- View coverage and governance artefacts in `crossvenue_arbx/governance.py` and `crossvenue_arbx/core.py`.
Architecture Summary
- Local signal discovery per venue; aggregated signals managed by a central coordinator.
- PlanDelta encodes actionable cross-venue arb legs.
- Graph-of-Contracts provides versioning for adapters and data contracts.
- CRDT-like delta merges enable deterministic replay after reconnects.
Usage and API surface
- LocalArbProblem: per-asset, per-venue problem statement.
- SharedSignals: cross-venue deltas, correlations, liquidity estimates.
- PlanDelta: incremental arb actions with timestamps and signatures.
- AuditLog/PrivacyBudget: governance and data-leakage controls.
Notes
- This release aims for a production-ready architecture rather than a bare MVP. See AGENTS.md for contribution rules and testing commands.