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