# CivicMesh Studio Federated

CivicMesh Studio Federated is a Python package for coordinating neighborhood-scale resilience planning without requiring full data centralization.

It provides three core building blocks:

- Canonical contracts for `LocalModel`, `SharedSignals`, `PlanDelta`, and `DualVariable`
- A Graph-of-Contracts registry for adapter compatibility and versioning
- A deterministic delta-sync log and a lightweight ADMM-style coordination solver

## What it does

The package models each neighborhood as a local optimization problem with its own assets, limits, and signals. Neighborhoods can exchange compact summaries instead of raw operational data, then coordinate incremental plan updates under a shared district constraint.

Included starter adapters:

- `gis-layer`: turns simple GeoJSON-like feature collections into a `LocalModel`
- `weather-forecast`: converts weather feed summaries into `SharedSignals`
- `water-pump-controller`: emits `PlanDelta` updates from pump telemetry

## Repository layout

- `src/idea154_civicmesh_studio_federated/`
- `tests/`
- `test.sh`
- `AGENTS.md`

## How to run

```bash
bash test.sh
```

## Packaging

The published project name is `idea154-civicmesh-studio-federated`.

## Notes for contributors

- Keep serialized outputs deterministic.
- Keep adapter input/output contracts explicit.
- Expand tests when changing solver behavior or contract fields.