OpenEnergySphere EnergiBridge MVP

Overview
- EnergiBridge provides a canonical, vendor-agnostic interoperability layer for cross-domain energy planning. It translates domain primitives into a compact IR (Object, SharedVariables, PlanDelta) and enables plug-and-play adapters across DERs, meters, pumps, and buildings while preserving offline-first operation and governance hooks.

Architecture
- Core primitives: LocalProblem (per-site optimization), SharedVariables (signals and priors), PlanDelta (incremental actions with provenance), and a Graph-of-Contracts (GoC) registry for adapters and data schemas.
- EnergiBridgeMapper (in src/energysphere/energi_bridge.py) maps Energysphere primitives to a canonical IR representation and supports round-tripping LocalProblem objects.
- Registry: In-memory GraphContractRegistry with metadata for auditing and replay protection. LocalProblems get stored with version, timestamp, and nonce metadata.
- Adapters: Starter adapters implemented under energysphere/adapters/ (SubstationMeterAdapter, DERAggregatorAdapter).
- Server API: Lightweight FastAPI app in energysphere/server/main.py exposing contract and adapter endpoints.

Roadmap (MVP, 8–12 weeks)
- Phase 0: Protocol skeleton, 2 starter adapters, TLS transport, ADMM-lite local solver, delta-sync with deterministic replay.
- Phase 1: Governance ledger scaffold, identity management (DIDs/certs), secure aggregation for SharedVariables.
- Phase 2: Cross-domain demo with toy cross-domain objective and EnergiBridge SDK.
- Phase 3: Hardware-in-the-loop validation and KPI dashboards.

Data Contracts Seeds
- LocalProblem, SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog; a Graph-of-Contracts registry; minimal contract example and conformance harness for adapters.

Security & Governance
- Hardware-backed attestation for adapters; DID/short-lived certs; attestation for plan deltas; optional local DP budgets.

How to run (current MVP)
- Install dependencies and run tests:
  - bash test.sh
- Start API (dev):
  - uvicorn energysphere.server.main:app --reload --port 8000

Notes
- This project uses a pyproject.toml with a proper build-system. Packaging metadata is wired to README.md via readme = "README.md" in pyproject.toml.
- The goal is to keep a tight MVP surface while enabling gradual expansion into a production-grade, privacy-preserving federation platform.