# SolFuse

SolFuse is a privacy-preserving federation layer for hybrid microgrids.
It coordinates solar, wind, and thermal storage sites through summarized signals, incremental plan deltas, and auditable governance instead of raw data exchange.

## What It Provides

- Canonical protocol primitives for local optimization, shared signals, dual variables, and plan deltas
- A SQLite-backed graph-of-contracts registry for adapter versioning and schema conformance
- An ADMM-lite solver for federated dispatch planning
- A federation bridge that packages solver rounds, audit records, and privacy-budget charges
- Deterministic starter adapters for solar inverter and thermal storage controllers
- Signed message envelopes and DID-style identities for short-lived trust
- Audit logging and privacy-budget accounting
- Delta-sync journaling for islanded/offline operation

## Package Layout

- `solfuse.models`: protocol objects and canonical payload schemas
- `solfuse.identity`: identity generation, signing, and verification
- `solfuse.registry`: adapter registry and schema conformance checks
- `solfuse.solver`: federated consensus solver
- `solfuse.bridge`: round orchestration and governance-aware packaging
- `solfuse.adapters`: starter inverter and thermal controller adapters
- `solfuse.delta_sync`: incremental plan journal and replay helpers
- `solfuse.governance`: audit log and privacy budget ledger
- `solfuse.transport`: canonical envelope serialization and TLS context helpers
- `solfuse.cli`: small demo entry point

## Quick Start

```bash
python3 -m pip install -e .[dev]
pytest
solfuse demo
```

## Minimal Example

```python
from solfuse.bridge import FederationBridge
from solfuse.adapters import SolarInverterAdapter, ThermalStorageAdapter

bridge = FederationBridge()
solar = SolarInverterAdapter().to_local_problem({"site_id": "solar-a", "forecast_kw": [4.0, 4.5]}, round_id=1)
thermal = ThermalStorageAdapter().to_local_problem({"site_id": "storage-b", "cooling_load_kw": [1.0, 1.5], "capacity_kw": 2.0}, round_id=1)
result = bridge.solve_round([solar, thermal], round_id=1)

print(result.solver_result.consensus)
```

## Governance Model

Each message can be wrapped in a signed envelope, recorded in the audit ledger, and charged against a privacy budget.
Contract adapters are versioned and validated against JSON Schema so controllers can be swapped without changing the federation core.

## Testing And Build

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