# ELAC-Plan Agents

Architecture and MVP changes
- Added a FastAPI-based MVP API (elac_plan.api) exposing /problems, /status, and /deltas endpoints to drive the LocalProblem -> PlanDelta flow locally.
- In-memory MVP storage for LocalProblem and PlanDelta with a toy LocalSolver and two starter adapters (NBBOFeedAdapter, BrokerGatewayAdapter).
- Public Python package surface updated: elac_plan.api is importable via elac_plan.api.app (FastAPI app), and re-exported from elac_plan for convenience.
- Tests: Added tests/test_api.py to validate problem creation and status endpoints using FastAPI TestClient.
- Test runner: test.sh added to execute pytest and python -m build for packaging validation.
- Documentation: README updated with MVP overview (next iteration to expand with Phase 1 governance, phase 2 cross-venue demos, etc.).

Architecture overview:
- Primitives: LocalProblem, SharedVariables, DualVariables, PlanDelta, Governance/AuditLog
- Adapters: NBBOFeedAdapter (data feed), BrokerGatewayAdapter (execution gateway)
- Solver: LocalSolver (toy solver to generate PlanDelta from LocalProblem)
- API: FastAPI app exposing /problems and /status
- Audit: Governance/AuditLog stubs for future crypto-signed logging

Tech stack:
- Python 3.8+
- FastAPI + Uvicorn for REST API
- Pydantic for data modeling
- Lightweight, in-process Fed-Coord topology (ADMM-lite) via PlanDelta and DualVariables placeholders

Tests & packaging:
- Pytest for unit tests
- Build via python -m build
- Packaging metadata in pyproject.toml with package name edge_latency_aware_cross_venue_execution

How to contribute:
- Implement real adapters, enhance solver, and hook up a real consensus/secure-aggregation layer
- Add integration tests for end-to-end edge-to-edge flow

Enhancements plan (ELAC-Plan MVP refinement)
- Canonical primitives and interoperability: map ELAC primitives to a CatOpt-inspired canonical IR
  - LocalProblem -> Object, SharedVariables -> Morphisms, PlanDelta -> PlanDelta, DualVariables -> DualVariables, AuditLog -> Governance/Provenance
- MVP wiring (8–12 weeks, 2–3 adapters): phase 0 skeleton + 2 adapters (venue-feed and broker gateway) over TLS; lightweight local solver; deterministic end-to-end delta-sync; toy cross-venue objective
- Phase 1: governance ledger scaffolding and identity layer; adapter conformance tests
- Phase 2: cross-domain demo in a simulated environment; publish a reference ELAC SDK
- Phase 3: hardware-in-the-loop testing; latency, plan quality, delta-sync costs, and privacy budgets
- Security and privacy: TEEs/hardware attestation for edge solvers; secure aggregation; possible zk-proofs
- Testing and metrics: latency, convergence, data-sharing volume, and governance auditability coverage
- Artifacts: draft DSL sketch (LocalProblem/SharedVariables/PlanDelta/DualVariables/AuditLog), toy adapters, minimal transport spec, RFC for registry surface
## ELAC-Plan Architectural Rules
- The repository now includes a Python MVP for ELAC-Plan with a FastAPI app at `src/edge_latency_aware_cross_venue_execution/api/app.py`.
- Core primitives are defined in `src/edge_latency_aware_cross_venue_execution/models.py` (LocalProblem, SharedVariables, PlanDelta, DualVariables, AuditLog).
- A toy solver is provided in `src/edge_latency_aware_cross_venue_execution/solver.py`.
- A minimal API exposes `/problems` (POST) and `/status` (GET) to exercise the MVP flows.
- Tests can be run via `bash test.sh` which executes pytest and a package build.