openenergysphere-federated-contract-driv/README.md

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.
• The current codebase includes a signed governance ledger, deterministic delta-sync, a contract template registry, a lightweight marketplace listing flow, and optional SQLite persistence for the registry.

Architecture

• Core primitives: LocalProblem (per-site optimization), SharedVariables (signals and priors), PlanDelta (incremental actions with provenance), DeltaEnvelope (offline sync packaging), and a Graph-of-Contracts registry for adapters, templates, and data schemas.
• Governance: GovernanceLedger produces chained, HMAC-signed audit entries for approvals and policy changes.
• EnergiBridgeMapper (in src/energysphere/energi_bridge.py) maps Energysphere primitives to a canonical IR representation and supports round-tripping LocalProblem objects.
• Registry: GraphContractRegistry supports in-memory operation and optional SQLite-backed persistence. LocalProblems get stored with version, timestamp, and nonce metadata.
• Adapters: Starter adapters implemented under energysphere/adapters/ (SubstationMeterAdapter, DERAggregatorAdapter) and marketplace capability publishing.
• Server API: FastAPI app in energysphere/server/main.py exposing contract, template, delta-sync, and governance endpoints.

Roadmap

• Phase 0: Protocol skeleton, 2 starter adapters, TLS transport, 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, DeltaEnvelope, ContractTemplate, GovernanceEvent, 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; append-only governance audit chain.

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.
• Optional SQLite persistence can be enabled by constructing GraphContractRegistry(db_path=...).