44 lines
2.0 KiB
Markdown
44 lines
2.0 KiB
Markdown
# 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.
|