# AGENTS

Architecture overview for CommonsGrid (Community-Managed, Privacy-Preserving Energy Commons Marketplace).

Tech stack
- Language: Python 3.11+
- Core primitives: governance ledger, local problem representation, shared signals, plan deltas, and privacy budgets.
- Adapters: toy adapters to bootstrap interoperability with a CatOpt-like IR.
- Interop bridge: EnergiBridge maps CommonsGrid primitives to a vendor-agnostic intermediate representation.
- Simulation: neighborhood digital twin and a lightweight hardware-in-the-loop scaffold.
- Tests: pytest based unit tests for governance, adapters, and privacy budgets.

Repository structure
- idea165_commonsgrid_community_managed/  -- Python package root
- tests/                                    -- unit tests
- AGENTS.md                                 -- this document
- README.md                                 -- product overview
- pyproject.toml                              -- packaging metadata + build-system
- test.sh                                    -- test runner
- READY_TO_PUBLISH                           -- marker for publishing readiness

How to contribute
- Run tests with: ./test.sh
- Extend: implement real ADMM solver, richer DP, and additional adapters.
- Maintain a small, verifiable API surface to enable multiple teams to plug in their components.

New Extensions (Proposed):
- Adapters: Added two starter toy adapters (InverterControllerAdapter, NeighborhoodBatteryAdapter) to bootstrap interop with local controllers. They are exported from the package for quick experimentation.
- DSL Sketch: Added idea165_commonsgrid_community_managed/dsl.py as a lightweight DSL sketch for LocalProblemDSL, SharedSignals DSL, PlanDelta DSL, and PrivacyBudget DSL to bootstrap community policy and problem representations.
- Publishing Mark: READY_TO_PUBLISH marker file to signal readiness after CI/tests pass.