# SunHub Open City-Scale Solar Siting and Dispatch Planner

SunHub is an open-source platform for optimizing solar siting, rooftop solar deployment, community solar integration, and distributed storage across a city. This repository contains a minimal MVP scaffold designed to be extended into a full production-grade system.

Project goals
- Provide a canonical data model: Object (neighborhood target), SharedSignal (aggregated signals), PlanDelta (incremental actions).
- Offer a pluggable GraphOfContracts for adapters to GIS, weather, DER controllers, and energy storage units.
- Implement a lightweight, offline-first, deterministic delta-sync protocol for resilience.
- Provide an extensible SDK with sample adapters.

Structure
- src/sunhub/: Core Python package with data models and orchestration skeleton.
- tests/: Unit tests for the MVP components.
- AGENTS.md: Architecture and contribution guidelines for future agents.
- pyproject.toml: Packaging metadata (Python) for a production-ready package.
- test.sh: Execute tests and packaging as part of CI checks.
- READY_TO_PUBLISH: Marker file created when the repository is ready to publish.

Getting started
- Install Python 3.10+: see pyproject.toml for build requirements.
- Run tests: `bash test.sh`.
- Run quick demos by importing sunhub.core in Python and constructing a SunHub instance.

This repository follows a pragmatic, minimal MVP approach. Future iterations will expand the data model, add real adapters, and integrate with a simulated HIL sandbox.

Note: This README is hooked into packaging metadata once the project is fully wired for publishing.