build(agent): new-agents#a6e6ec iteration

AGENTS.md

@@ -25,3 +25,28 @@ Branching and publishing
 - When ready to publish, ensure pyproject.toml or setup.py exists and README.md documents package usage.
 
 End of document
+
+## ExoRoute Interoperability & MVP Roadmap (EnergiBridge)
+
+- Canonical interop bridge: EnergiBridge maps ExoRoute primitives into a CatOpt-style canonical IR.
+- Core mappings:
+  - Objects = LocalProblem (per-venue routing/hedging tasks)
+  - Morphisms = SharedVariables / DualVariables (signals and multipliers)
+  - PlanDelta = incremental plan updates with provenance
+  - PrivacyBudget / AuditLog blocks for governance and provenance
+  - Graph-of-Contracts registry for adapters and schemas
+
+- MVP wiring (8–12 weeks, 2–3 agents to start):
+  - Phase 0: protocol skeleton + 2 starter adapters (FIX/WebSocket feed adaptor and simulated venue) over TLS, lightweight ADMM-lite local solver, deterministic delta-sync
+  - Phase 1: governance ledger & identity layer, secure aggregation defaults
+  - Phase 2: cross-domain demo with EnergiBridge SDK and toy adapters
+  - Phase 3: hardware-in-loop or network-simulated validation
+
+- Deliverables:
+  - DSL seeds for interoperability (LocalProblem, SharedVariables, PlanDelta, DualVariables, PrivacyBudget, AuditLog, GraphOfContractsRegistry)
+  - Toy payload sketches and starter repository layout to seed EnergiBridge integration
+  - Minimal EnergiBridge Python SDK bridging to adapters
+
+- Tests & metrics: delta size, replay determinism, convergence speed, adapter conformance, governance auditability
+
+If helpful, we will add a small toy sandbox demonstrating a 2-adapter MVP to seed interoperability with SignalVault/SignalCanvas-style ecosystems.

exoroute/__init__.py

@@ -6,6 +6,9 @@ CatOpt-like ecosystems.
 """
 
 from .dsl import LocalProblem, SharedVariables, PlanDelta, DualVariables, PrivacyBudget, AuditLog, GraphOfContractsRegistry, GraphOfContractsRegistryEntry
+from .energi_bridge import EnergiBridge
+from .adapters.fix_ws_feed_adapter import FIXWebSocketFeedAdapter
+from .adapters.simulated_venue_adapter import SimulatedVenueAdapter
 
 __all__ = [
     "LocalProblem",
@@ -16,4 +19,7 @@ __all__ = [
     "AuditLog",
     "GraphOfContractsRegistry",
     "GraphOfContractsRegistryEntry",
+    "EnergiBridge",
+    "FIXWebSocketFeedAdapter",
+    "SimulatedVenueAdapter",
 ]

exoroute/adapters/__init__.py

@@ -1 +1,6 @@
-"""Adapters package for ExoRoute: starter adapters for price feeds and simulated venues."""
+"""Adapter registry for ExoRoute starter adapters."""
+
+from .fix_ws_feed_adapter import FIXWebSocketFeedAdapter
+from .simulated_venue_adapter import SimulatedVenueAdapter
+
+__all__ = ["FIXWebSocketFeedAdapter", "SimulatedVenueAdapter"]

exoroute/adapters/fix_ws_feed_adapter.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Dict, Any, List
+
+from ..dsl import LocalProblem, SharedVariables
+
+
+class FIXWebSocketFeedAdapter:
+    """Minimal FIX/WebSocket price-feed adapter skeleton.
+
+    This adapter exposes a tiny surface to produce mock price feed data that
+    can be injected into EnergiBridge mappings or local problem instances.
+    """
+
+    def __init__(self, address: str, topics: List[str] | None = None) -> None:
+        self.address = address
+        self.topics = topics or []
+        self.connected = False
+
+    def connect(self) -> None:
+        # In a real implementation, establish TLS-secured FIX/WebSocket session
+        self.connected = True
+
+    def fetch_latest(self) -> Dict[str, Any]:
+        if not self.connected:
+            self.connect()
+        # Return a tiny, deterministic mock price feed payload
+        return {
+            "venue": "FIX-WS-Mock",
+            "data": {
+                "bid": 100.0,
+                "ask": 100.5,
+                "volume": 1000,
+            },
+        }
+
+    def to_local_problem(self, lp: LocalProblem) -> LocalProblem:
+        # In a real wire-up this would translate feed data into constraints/objectives
+        return lp

exoroute/adapters/simulated_venue_adapter.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import random
+from typing import Dict, Any
+
+from ..dsl import PlanDelta, LocalProblem, SharedVariables
+
+
+class SimulatedVenueAdapter:
+    """A lightweight simulated venue adapter for MVP testing."""
+
+    def __init__(self, venue_id: str = "SIM-VENUE-1") -> None:
+        self.venue_id = venue_id
+
+    def generate_signal(self) -> Dict[str, Any]:
+        # Produce a tiny, deterministic-ish signal mix for testing
+        price = 100.0 + random.uniform(-1.0, 1.0)
+        return {
+            "venue": self.venue_id,
+            "signal": {
+                "price": price,
+                "spread": random.uniform(0.01, 0.05),
+                "latency_ms": random.randint(1, 15),
+            },
+        }
+
+    def to_local_problem(self, lp: LocalProblem) -> LocalProblem:
+        # In a full MVP, this would modify the LocalProblem with simulated data
+        return lp
+
+    def produce_plan_delta(self, lp: LocalProblem, sv: SharedVariables) -> PlanDelta:
+        # Minimal delta that encodes a trivial adjustment
+        delta = {"venue_delta": {self.venue_id: {"adjustment": 0.0}}}
+        return PlanDelta(delta=delta, timestamp=__import__('time').time(), author=self.venue_id, contract_id=lp.id)

exoroute/energi_bridge.py

@@ -1,43 +1,50 @@
 from __future__ import annotations
-from typing import Dict, Any, Optional
+
-from .core import LocalProblem, SharedVariables, PlanDelta, GraphOfContractsRegistry
+from dataclasses import asdict
+from typing import Dict, Any
+
+from .dsl import LocalProblem, SharedVariables, PlanDelta
+
 
 class EnergiBridge:
-    """Minimal bridge translating ExoRoute primitives to a canonical IR (EnergiBridge-style).
+    """Minimal EnergiBridge-like interoperability bridge.
-    This is a lightweight, extensible mapping scaffold for interoperability with CatOpt-like ecosystems.
+
+    This is a tiny, production-light skeleton that maps existing ExoRoute
+    primitives into a canonical, CatOpt-style IR. It is intentionally small
+    to keep the MVP focused while providing a hook for future integration with
+    other adapters and governance modules.
     """
-    @staticmethod
+
-    def to_canonical(local: LocalProblem, shared: SharedVariables, delta: Optional[PlanDelta] = None, registry: Optional[GraphOfContractsRegistry] = None) -> Dict[str, Any]:
+    def __init__(self) -> None:
-        can = {
+        # In a real system this would be a persistent registry of adapters and
-            "Objects": {
+        # schemas. For this skeleton we just keep a minimal in-memory map.
-                "LocalProblem": {
+        self._registry: Dict[str, Any] = {}
-                    "id": local.id,
+
-                    "domain": local.domain,
+    def register_adapter(self, adapter_id: str, contract_version: str, domains: list[str]) -> None:
-                    "assets": local.assets,
+        self._registry[adapter_id] = {
-                    "objective": local.objective,
+            "contract_version": contract_version,
-                    "constraints": local.constraints,
+            "domains": domains,
-                    "solver_hint": local.solver_hint,
         }
+
+    def map_to_ir(self, lp: LocalProblem, sv: SharedVariables, pd: PlanDelta) -> Dict[str, Any]:
+        """Create a canonical IR payload from ExoRoute primitives.
+
+        This payload is deliberately lightweight but designed to be serializable
+        and replayable. It can be extended to include per-message metadata,
+        signatures, and versioning as the project matures.
+        """
+        ir = {
+            "object": {
+                "type": "LocalProblem",
+                "payload": asdict(lp),
             },
-            "Morphisms": {
+            "morphisms": {
-                "SharedVariables": {
+                "shared_variables": asdict(sv) if isinstance(sv, SharedVariables) else sv,
-                    "forecasts": getattr(shared, "forecasts", {}),
+                "dual_variables": {},  # placeholder for future expansion
-                    "priors": getattr(shared, "priors", {}),
-                    "version": getattr(shared, "version", 0),
-                    "timestamp": getattr(shared, "timestamp", 0.0),
             },
-                "DualVariables": {},
+            "plan_delta": asdict(pd) if isinstance(pd, PlanDelta) else pd,
-            },
-            "PlanDelta": delta.delta if delta else {},
         }
-        # Optional registry embedding for interoperability and provenance
+        return ir
-        if registry is not None:
+
-            can["GraphOfContractsRegistry"] = {
+    def __repr__(self) -> str:
-                entry_id: {
+        return f" EnergiBridge(registry_entries={len(self._registry)})"
-                    "adapter_id": entry.adapter_id,
-                    "supported_domains": entry.supported_domains,
-                    "contract_version": entry.contract_version,
-                }
-                for entry_id, entry in registry.entries.items()
-            }
-        return can

tests/test_energi_bridge_basic.py

@@ -0,0 +1,17 @@
+import time
+from exoroute import LocalProblem, SharedVariables, PlanDelta, EnergiBridge
+
+
+def test_energi_bridge_map_to_ir_basic():
+    lp = LocalProblem(id="LP-001", domain="equities", assets=["AAPL", "MSFT"], objective="min_latency", constraints={})
+    sv = SharedVariables(forecasts={"AAPL": 150.0}, priors={"AAPL": 149.5}, version=1)
+    pd = PlanDelta(delta={"route": {"AAPL": "optim"}}, timestamp=time.time(), author="tester", contract_id=lp.id)
+
+    bridge = EnergiBridge()
+    ir = bridge.map_to_ir(lp, sv, pd)
+
+    # Basic structural checks
+    assert "object" in ir
+    assert ir["object"]["type"] == "LocalProblem"
+    assert ir["morphisms"]["shared_variables"]["forecasts"]["AAPL"] == 150.0
+    assert ir["plan_delta"]["author"] == "tester"