32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# AGENTS.md
|
|
|
|
Overview
|
|
- CityPulse is a cross-domain urban resource optimization platform emphasizing privacy-preserving federated coordination with an offline-first delta-sync protocol.
|
|
- This repository contains a production-oriented MVP scaffold in Python that demonstrates core concepts: LocalProblems, SharedSignals, PlanDelta, DualVariables, and an auditable governance trail via AuditLog.
|
|
|
|
Architecture (high level)
|
|
- Core models (src/idea171_citypulse_participatory_digital/core.py): LocalProblem, SharedSignals, PlanDelta, DualVariables, and AuditLog.
|
|
- Delta store and replay (src/idea171_citypulse_participatory_digital/delta.py): deterministic delta history and replay capability.
|
|
- Solver (src/idea171_citypulse_participatory_digital/solver.py): a minimal ADMM-lite aggregator over dual variables.
|
|
- Adapters (src/idea171_citypulse_participatory_digital/adapters): starter bindings for DER and Water Pump controllers.
|
|
- Public APIs are intentionally lightweight for MVP; this repo provides a stable foundation for rapid pilots and extension via adapters and governance.
|
|
|
|
Tech Stack
|
|
- Language: Python 3.9+ (typing, dataclasses, lightweight architecture)
|
|
- Key concepts: LocalProblems (domain tasks), SharedSignals (privacy-preserving signals), PlanDelta (contractual delta actions), DualVariables (shadow prices), AuditLog (tamper-evident-like logging proxy).
|
|
- No external services required for MVP; simple in-process delta store and a toy ADMM-like solver to illustrate coordination.
|
|
|
|
Development and Testing
|
|
- Tests: pytest tests/test_core.py
|
|
- Test script: test.sh (runs pytest, then builds the package via python3 -m build)
|
|
- Packaging: pyproject.toml with a production-ready package name idea171-citypulse-participatory-digital
|
|
|
|
Running locally
|
|
- Install dependencies (none beyond stdlib for MVP)
|
|
- Run tests: ./test.sh
|
|
- Build package: python3 -m build
|
|
|
|
Contributing rules
|
|
- One change at a time, with tests updated accordingly.
|
|
- Ensure tests pass before publishing readiness.
|