AI-inspired smart energy grid simulation for the ten largest US cities: demand, renewable supply, storage, risk, and animated inter-city power flows. Built for hackathon demos with a FastAPI backend and a React + Leaflet front end.
- Python 3.11+ (3.13 tested)
- Node.js 20+ and npm (for the frontend)
cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000API (default http://127.0.0.1:8000):
| Method | Path | Description |
|---|---|---|
| GET | /city-state |
Current metrics for all 10 cities |
| POST | /simulate |
Body: temperature, solar_factor, ev_multiplier, data_center_multiplier — updates simulation and returns cities |
| GET | /forecast |
Predicted demand for next 3 hours per city |
| GET | /energy-flow |
{ "flows": [ { "from", "to", "mw" } ] } for visualization |
| GET | /recommendations |
Grid stabilization actions |
| POST | /ai-query |
Body: { "query": "..." } — short natural-language answers + structured hints |
| GET | /health |
Liveness check |
Interactive docs: http://127.0.0.1:8000/docs
In a second terminal:
cd frontend
npm install
npm run devOpen http://127.0.0.1:5173. The dev server proxies API calls to the backend on port 8000.
Production build:
cd frontend
npm run build
npm run previewServe frontend/dist behind any static host; configure that host to proxy /simulate, /city-state, /forecast, /energy-flow, /recommendations, and /ai-query to the API, or set VITE_API_BASE (see below).
By default the app uses same-origin paths (Vite proxy in dev). For a deployed frontend pointing at a remote API, create frontend/.env:
VITE_API_BASE=https://your-api.example.comThen rebuild; src/api.ts prepends this base to requests when set.
New York City, Los Angeles, Chicago, Houston, Phoenix, Philadelphia, San Antonio, San Diego, Dallas, San Jose.
- Move scenario sliders (temperature, solar, EV, data centers) and watch risk-colored nodes and animated flow lines update.
- Click a city for demand, renewables, storage, risk, and inbound/outbound flows.
- Use the Decision agent panel for sample questions (risk, routing, EV scenario).
- Open Swagger at
/docsto show the API contract.
Flux/
backend/ # FastAPI app + simulation engine
frontend/ # React + Leaflet UI
README.md
- All numbers are synthetic — tuned for visual clarity, not grid certification.
- Risk bands: low < 50, medium 50–150, high 150–300, critical > 300 (on the internal score).
- No external ML dependencies; “AI” panel uses lightweight rule + template responses over live simulation state.