openenergysphere-federated-contract-driv/AGENTS.md

AGENTS.md

Architecture, testing, and contribution guide for OpenEnergySphere EnergiBridge MVP.

Overview

• A production-ready Python-based MVP that enables cross-domain energy planning with privacy-first primitives.
• Core concepts (OpenEnergySphere analogies): Objects (LocalProblems), Morphisms (SharedVariables), PlanDelta, and a registry of Graph-of-Contracts. Adapters implement plug-and-play data/model interfaces.
• EnergiBridge maps OpenEnergySphere primitives to canonical IR concepts and enables cross-domain adapters with offline-first capabilities.

Tech Stack (current MVP)

• Language: Python 3.10+
• Web API: FastAPI
• Data Modeling: Pydantic
• Storage: In-memory registry (extensible to SQLite/PostgreSQL)
• Packaging: pyproject.toml with setuptools build backend
• Testing: pytest

Project Structure (high level)

• energysphere/ - Python package with models, registry, sdk, adapters, and server.
• energysphere/server/ - FastAPI app exposing contract/adapter endpoints.
• energysphere/adapters/ - Starter adapters (substation_meter, der_aggregator).
• tests/ - Pytest unit tests for registry and adapters.
• test.sh - Test runner including packaging build step.
• AGENTS.md - This document.

How to run locally

• Install dependencies (in a virtualenv):
  • python -m pip install --upgrade pip setuptools wheel
  • pip install -r requirements.txt (if you add one later) or rely on pyproject tooling
• Run tests:
  • bash test.sh
• Run the API (in dev):
  • uvicorn energysphere.server.main:app --reload --port 8000

Development workflow

• Implement minimal MVP features in small, testable units.
• Add tests for all new functionality and ensure test.sh passes before merging.
• Extend registry with persistent storage and implement authentication and governance ledger in future iterations.

Contribution rules

• All changes should pass tests (pytest) and packaging build (python -m build).
• Follow existing naming conventions and keep public APIs stable where possible.
• Document any breaking changes in the changelog and update AGENTS.md accordingly.