2.0 KiB

Raw Blame History

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.