# 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.