idea154-civicmesh-studio-federated/AGENTS.md

AGENTS.md

Architecture

This repository contains idea154-civicmesh-studio-federated, a Python package for federated urban resilience coordination.

Core modules:

• contracts.py: canonical Pydantic contracts for LocalModel, SharedSignals, PlanDelta, and DualVariable.
• registry.py: Graph-of-Contracts adapter registry plus starter GIS, weather, and pump adapters.
• sync.py: deterministic delta log with audit hashes and replay.
• solver.py: lightweight ADMM-style coordinator for cross-neighborhood plan updates.

Tech Stack

• Python 3.11+
• pydantic for validation and canonical serialization
• pytest for tests
• setuptools build backend

Rules

• Keep contracts canonical and deterministic.
• Prefer small, explicit changes over broad abstractions.
• Preserve reproducible serialization and replay behavior.
• Add or update tests when changing contract shapes, adapter behavior, or solver math.

Testing

• bash test.sh
• python3 -m pytest
• python3 -m build