# CityGrid

Policy-driven Federated Optimization for Cross-Utility Districts (Electricity, Heating/Cooling, Water).

Overview
- Core primitives: LocalProblem, SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog, PolicyBlock.
- GoC registry for adapters and data contracts (versioned schemas).
- Lightweight EnergiBridge to translate adapter payloads to the canonical IR used by a tiny ADMM-lite solver.
- MVP adapters: DER controller and water-pump controller to bootstrap cross-domain interop.

Project structure
- citygrid/__init__.py: core dataclasses and public API surface.
- citygrid/registry/: in-memory Graph-of-Contracts registry.
- citygrid/bridge/: EnergiBridge for primitive mapping.
- citygrid/solver/: lightweight ADMM-like solver for MVP.
- citygrid/adapters/: toy adapters (DER, water pump).
- citygrid/demo/: small demo harness.
- AGENTS.md: architectural rules and testing guidance.
- pyproject.toml: packaging metadata.

How to run (local development)
- Ensure Python 3.8+ is installed.
- Install dependencies and run tests:
  - python -m pip install -e .
  - pytest -q
  - python -m build
- Run the demo: python -m citygrid.demo.core_demo

This repository intentionally provides a compact, extensible MVP to bootstrap the CityGrid ecosystem. Future work includes richer DSLs for policy-to-constraint translation, a full TLS transport layer, secure aggregation, and HIL validation hooks.