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