CityGrid Agent Architecture

This repository contains a production-ready scaffold for CityGrid MVP: a policy-driven federated optimization platform across cross-utility districts.
Core primitives implemented in Python: LocalProblem, SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog, PolicyBlock.
Registry and bridge stubs: GoCRegistry, EnergiaBridge for adapter interoperability.
MVP wiring: 2 starter adapters with a lightweight ADMM-like delta-sync workflow.
Build and test: includes a test.sh script that runs unit tests and python packaging sanity checks.

Contributing

Run tests with: ./test.sh
Packaging: python3 -m build, install via pip if needed.
Follow the existing architectural contracts described in this file; future work expands to a multi-agent, cross-domain MVP.
Objective: Build a policy-driven, privacy-preserving federated optimization platform for cross-utility districts.
Core primitives (Canonical IR): LocalProblem, SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog, PolicyBlock.
Graph-of-Contracts registry (GoC): versioned schemas for adapters and data contracts; conformance tests.
MVP Adapters: at least two starters (DER controller and district-chiller controller) translating to the canonical IR.
Transport: TLS-like, delta-sync with bounded staleness via EnergiBridge.
Privacy and governance: secure aggregation, privacy budgets, tamper-evident logs, DID-based identities.
Testing: unit tests for core data models, adapter interop tests, end-to-end demo hints.

This document serves as the architectural contract for contributors. See README for running instructions.