AI Power Blackout Predictor

Predict electricity outages before they happen — anywhere in the world.

AI-powered platform that combines crowdsourced outage reports, real-time weather data, and machine learning to predict power blackouts at the neighborhood level. Sends SMS alerts via your own SMPP gateway (Jasmin), renders live heatmaps, and works offline.

Overview

Electricity outages are one of the most disruptive daily challenges across Africa, Asia, Latin America, and developing regions worldwide. This platform uses AI + crowdsourcing to predict outages hours before they happen and warn residents via SMS — even on feature phones with no internet.

Built to scale globally, with per-region ML models, multi-language SMS alerts, a fully offline-capable Progressive Web App, USSD fallback (*384#), and two-way SMS interaction.

Key Features

Feature	Description
AI Predictions	XGBoost + Prophet ensemble predicts outage probability per neighborhood cell
AI Explanations	Groq LLM (llama-3.1-8b-instant) generates plain-language risk summaries in 7 languages
Own SMS Gateway	Jasmin + SMPP connects directly to any telecom operator worldwide — no per-SMS vendor fees
Neighborhood Heatmaps	Uber H3 hexagonal grid renders real-time risk maps worldwide
Offline Support	PWA with Service Workers + IndexedDB — works without internet
USSD Fallback	`*384#` works on any feature phone, no internet required
Two-Way SMS	Users can report outages and query predictions by SMS
Crowdsourced Reports	App and SMS reports feed the ML model — 3-report consensus verifies outages
7 Languages	English, French, Swahili, Kinyarwanda, Arabic, Spanish, Portuguese
4-Hour Predictions	Runs every 4 hours, checks weather + history + grid patterns
Multi-Channel Alerts	SMS, push notifications, email, Telegram, WhatsApp — user-configurable thresholds
Admin Dashboard	Fraud detection, multi-location tracking, platform operations
Enterprise API	Utility companies and governments can subscribe via webhook

Architecture

┌───────────────────────────────────────────────────────────────┐
│           API CONSUMERS — REST (Swagger/ReDoc) · gRPC          │
│   Utilities, NGOs, integrators — no first-party client app     │
└───────────────────────┬───────────────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────────────┐
│                    BACKEND (FastAPI)                            │
│     Auth · Users · Predictions · Outages · Alerts               │
│     Admin · Analytics · Community · Enterprise · USSD           │
│                  Celery Beat (every 4h)                          │
└──────┬──────────────────────┬──────────────────────┬────────────┘
       │                      │                      │
┌──────▼──────┐   ┌───────────▼──────────┐  ┌──────▼────────┐
│  ML ENGINE  │   │     DATA PIPELINE    │  │  SMS GATEWAY  │
│  XGBoost    │   │  OpenWeatherMap      │  │ Jasmin + SMPP │
│  Prophet    │   │  Crowdsource ingest  │  │  Generic env  │
│  Groq LLM   │   │  H3 Mapper · Cron   │  │  var routing  │
└─────────────┘   └──────────────────────┘  └───────────────┘
       │                      │                      │
┌──────▼──────────────────────▼──────────────────────▼────────┐
│           Supabase (PostgreSQL) · Redis · RabbitMQ           │
└─────────────────────────────────────────────────────────────┘

This is an API-first / headless platform — there is no first-party web or mobile client. Consumers talk to the REST API (or gRPC for SCADA/enterprise integrations) directly, or receive alerts via SMS/USSD/push/email without ever touching a UI.

Data flow:

OpenWeatherMap → Weather snapshots stored per H3 cell hourly
Users → Report outages via SMS / USSD / API → 3-report consensus verifies
Celery → Runs predictions every 4h per cell → stores probability + risk level
Groq LLM → Generates human-readable explanation in user's language
Alert checker → Matches predictions against subscriptions → fires SMS / push / email / Telegram
API consumers → Query predictions/heatmap directly via REST or gRPC

Tech Stack

Backend

Python 3.12 · FastAPI (async) · SQLAlchemy 2.x · Alembic migrations
Celery + Celery Beat for scheduled prediction tasks
Pydantic v2 for schema validation
passlib + bcrypt for password hashing
python-jose for JWT tokens

Database & Cache

Supabase (PostgreSQL 15) — cloud-hosted, free tier for development
Redis 7 — Celery broker + response cache
RabbitMQ — Jasmin message queue

Machine Learning

XGBoost — primary classifier (70% ensemble weight)
Prophet — 7-day trend model (30% ensemble weight)
scikit-learn · NumPy · Pandas
Groq (llama-3.1-8b-instant) — AI explanation generation

SMS & Messaging

Jasmin open-source SMS gateway (SMPP v3.4) — generic, works with any aggregator
SMPP credentials via env vars — no country-specific connectors in code
Inbound SMS parsing + two-way interaction
USSD handler (*384#)

Geospatial

Uber H3 (resolution 8) — ~460m hexagonal cells, worldwide coverage

Infrastructure

Docker Compose — full local stack
Nginx — reverse proxy (production)

External APIs

OpenWeatherMap — weather forecasts (free tier, global)
Groq API — LLM inference (free tier available)

Project Structure

ai-power-blackout-predictor/
│
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/   → auth, predictions, outages, alerts, insights, admin
│   │   ├── core/               → config, database, security
│   │   ├── models/             → SQLAlchemy ORM models
│   │   ├── schemas/            → Pydantic request/response schemas
│   │   ├── services/           → weather, SMS (Jasmin), Groq LLM
│   │   └── tasks/              → Celery tasks (predict, alert dispatch)
│   ├── migrations/versions/    → Alembic migration chain (0001→0007)
│   ├── scripts/
│   │   └── bootstrap_supabase.sql  → one-shot Supabase DB init
│   ├── tests/                  → pytest test suite
│   └── requirements.txt
│
├── sms-gateway/                → Jasmin wrapper microservice
├── ml-engine/                  → XGBoost + Prophet training + inference
├── data-pipeline/              → ETL cron jobs
└── docker-compose.yml

Getting Started

Prerequisites

Docker Desktop installed and running
Git
A Supabase project (free tier)
An OpenWeatherMap API key (free tier)

1 — Clone & configure

git clone https://github.com/manziosee/AI-Power-Blackout-Predictor.git
cd AI-Power-Blackout-Predictor

cp .env.example .env

Edit .env with your credentials (see Environment Variables below).

2 — Initialize the database

Open your Supabase project → SQL Editor and paste the entire contents of backend/scripts/bootstrap_supabase.sql. Run it once. This creates all tables and marks Alembic as fully migrated to the latest revision (currently 0041).

3 — Start all services

docker-compose up -d

4 — Seed neighborhood cells

docker-compose exec data-pipeline python processors/h3_mapper.py

5 — Explore the API

URL	Description
`http://localhost:8000/docs`	Swagger API docs
`http://localhost:8000/redoc`	ReDoc API docs
`http://localhost:15672`	RabbitMQ dashboard (`guest/guest`)

This is an API-first platform — there is no bundled web or mobile client. Everything is driven through the REST API (or gRPC for enterprise/SCADA integrations).

Local development (without Docker)

cd backend
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
uvicorn app.main:app --reload

# Run tests
pytest

Database Setup (Supabase)

All tables are defined in backend/scripts/bootstrap_supabase.sql. Run it once in the Supabase SQL Editor.

The migration chain runs 0001 → 0041 (see backend/migrations/versions/ for the full history — core schema, community features, billing, insurance, GNN cascade risk, restoration tracking, predictive maintenance, notification preferences, and more). After running the bootstrap SQL, the alembic_version table is set to 0041 so Alembic recognizes the DB as fully migrated.

Environment Variables

Copy .env.example to .env and fill in:

Variable	Description	Required
`SECRET_KEY`	JWT signing secret (64+ random chars)	Yes
`DATABASE_URL`	Async PostgreSQL URL (`postgresql+asyncpg://...`)	Yes
`SYNC_DATABASE_URL`	Sync PostgreSQL URL for Alembic (`postgresql://...`)	Yes
`REDIS_URL`	Redis connection string	Yes
`OPENWEATHERMAP_API_KEY`	OWM API key (free tier, global)	Yes
`GROQ_API_KEY`	Groq API key for AI explanations	Optional
`JASMIN_HOST`	Jasmin container hostname	Yes (SMS)
`SMPP_HOST`	Your SMPP aggregator endpoint	Yes (SMS)
`SMPP_USERNAME`	SMPP username	Yes (SMS)
`SMPP_PASSWORD`	SMPP password	Yes (SMS)
`JASMIN_CONNECTOR_DEFAULT`	Default Jasmin connector ID	Yes (SMS)
`SMTP_HOST`	SMTP server for email alerts	Optional
`SMTP_PORT`	SMTP port (587 for TLS)	Optional
`SMTP_USERNAME`	SMTP username / email address	Optional
`SMTP_PASSWORD`	SMTP App Password (not account password)	Optional
`TELEGRAM_BOT_TOKEN`	Telegram bot token from @BotFather	Optional
`USSD_SHORT_CODE`	USSD short code digits	Optional
`VAPID_PUBLIC_KEY`	Web Push VAPID public key	Optional
`VAPID_PRIVATE_KEY`	Web Push VAPID private key	Optional

See .env.example for the complete list with defaults.

SMS Gateway — Jasmin + SMPP

All SMS routing goes through Jasmin, an open-source Python SMS gateway that speaks SMPP v3.4 — the protocol used by every telecom operator worldwide.

Your App
   ↓  POST /send-sms  { phone, message }
SMS Gateway API  (Jasmin wrapper)
   ↓  Routes via JASMIN_CONNECTOR_DEFAULT env var
Jasmin Gateway
   ↓  SMPP v3.4 (operator-agnostic)
Any SMPP aggregator worldwide  (Sinch, Infobip, Vonage, direct operator, ...)
   ↓
User's Phone  (any country, any network)

No country-specific connectors in code. Routing is 100% controlled by environment variables. To add a new country or operator: update SMPP credentials in .env — no code changes needed.

Cost comparison

Provider	Cost per SMS	100k SMS/month
Twilio	~$0.05–0.08	~$6,500
Africa's Talking	~$0.01–0.03	~$2,000
Own SMPP (via Jasmin)	~$0.003–0.008	~$500

ML Engine

Prediction pipeline (Celery, every 4 hours)

1. FETCH      OpenWeatherMap forecast → next 24h per tracked H3 cell
2. FEATURES   Weather + temporal + historical outage + grid type
3. PREDICT    XGBoost  → P(outage in 4h)   [weight: 70%]
              Prophet  → 7-day trend        [weight: 30%]
              Ensemble → final probability
4. EXPLAIN    Groq LLM → human-readable summary in user's language
5. STORE      PostgreSQL predictions table
6. ALERT      Check subscriptions → SMS + push if threshold crossed

Feature set

Category	Features
Weather	`rainfall_mm`, `temperature_c`, `wind_speed_ms`, `humidity_pct`, `is_storm`, `is_heavy_rain`
Temporal	`hour`, `day_of_week`, `month`, `is_weekend`, `is_peak_hour`
Historical	`outages_last_7d`, `outages_last_30d`, `avg_duration_minutes`, `outage_frequency_per_week`
Grid	`grid_type`, `center_lat`, `center_lng`

Risk levels

Level	Probability	Color
Low	< 40%	Green
Medium	40–64%	Amber
High	65–84%	Red
Critical	>= 85%	Purple

Train the model

cd ml-engine
python training/train.py --region all

AI Insights (Groq LLM)

The /api/v1/insights/ endpoints use the Groq API (llama-3.1-8b-instant) to generate plain-language explanations:

GET /api/v1/insights/prediction/{h3_index}?language=rw
→ "Amashanyarazi azima mu gace kawe saa 18:00 (82%). Shaza ibikoresho byawe nonaha."

GET /api/v1/insights/history/{h3_index}?language=en
→ "This area had 12 outages in the past 30 days, averaging 2.4 hours each..."

If GROQ_API_KEY is not set, these endpoints return an empty explanation string without failing — predictions continue to work normally.

Supported Languages

Code	Language	Primary Regions
`en`	English	Global default
`fr`	French	Francophone Africa, Europe
`sw`	Swahili	East Africa (KE, TZ, UG)
`rw`	Kinyarwanda	Rwanda
`ar`	Arabic	Middle East, North Africa
`es`	Spanish	Latin America, Spain
`pt`	Portuguese	Brazil, Angola, Mozambique

SMS messages and AI explanations are generated in the user's registered language.

API Reference

Base URL: http://localhost:8000/api/v1

Interactive docs: http://localhost:8000/docs

Core endpoints

Method	Path	Auth	Description
`POST`	`/auth/register`	No	Register new user
`POST`	`/auth/login`	No	Get JWT token
`GET`	`/auth/me`	Yes	Current user profile
`GET`	`/predictions/`	Yes	List predictions by H3 cell
`GET`	`/predictions/cell/{h3_index}`	Yes	Latest prediction for a cell
`POST`	`/outages/report`	Yes	Report a power outage
`GET`	`/outages/{h3_index}`	Yes	Outage history for a cell
`POST`	`/alerts/subscribe`	Yes	Subscribe to alerts
`GET`	`/alerts/my-subscriptions`	Yes	List my subscriptions
`GET`	`/insights/prediction/{h3_index}`	Yes	AI explanation for prediction
`GET`	`/insights/history/{h3_index}`	Yes	AI explanation for outage history
`GET`	`/admin/stats`	Admin	Platform statistics
`POST`	`/sms/inbound`	No	Inbound SMS webhook
`POST`	`/ussd`	No	USSD session handler

New feature endpoints (migration 0008–0021)

Method	Path	Auth	Description
`GET`	`/planned-outages/`	No	Upcoming planned outages for a cell
`POST`	`/planned-outages/`	Admin	Create a planned outage entry
`POST`	`/feedback/respond`	No	Record YES/NO response to feedback SMS
`GET`	`/feedback/accuracy/{h3_index}`	Yes	Prediction accuracy from user feedback
`POST`	`/medical-priority/register`	Yes	Self-register as medical priority user
`GET`	`/medical-priority/heatmap`	Admin	Count of priority users per cell
`GET`	`/resilience/{h3_index}`	Yes	Neighborhood resilience score (0–100)
`GET`	`/resilience/top`	No	Top 20 most resilient cells
`POST`	`/insurance/policies`	Yes	Create parametric insurance policy
`GET`	`/insurance/claims`	Yes	List own insurance claims
`POST`	`/data-marketplace/request`	No	Submit anonymized data export request
`GET`	`/data-marketplace/preview/{h3_index}`	No	Free aggregated data preview
`POST`	`/white-label/`	Admin	Create white-label config for a utility
`GET`	`/white-label/brand/{api_key}`	No	Get public branding for embed
`POST`	`/ivr/trigger`	Admin	Trigger IVR voice calls for a cell
`GET`	`/poi/`	No	List ATM/fuel stations in a cell
`POST`	`/poi/{id}/report`	Yes	Report POI operational status
`POST`	`/prepaid/meters`	Yes	Register prepaid electricity meter
`GET`	`/grid/transformers`	Admin	List grid transformers
`GET`	`/seasonal/{h3_index}`	Yes	24-month seasonal outage breakdown
`GET`	`/seasonal/{h3_index}/worst-months`	Yes	Top 3 worst months historically
`GET`	`/transfer-learning/similar/{region}`	Admin	Similar regions for model bootstrap
`GET`	`/regulatory/reports`	Admin	Regulatory compliance reports
`POST`	`/regulatory/reports/generate`	Admin	Generate monthly compliance report
`GET`	`/dispatch/recommend`	Admin	Crew pre-positioning recommendations

CI/CD

Tests run on every push via GitHub Actions (.github/workflows/ci.yml).

The test suite uses SQLite in-memory (no external DB needed in CI) with monkey-patched JSONB and UUID support.

Current test status

Auth (register, login, me, unauthenticated): PASS
Predictions API (list, report outage): PASS
Outage reports: PASS
Weather service: PASS
Coverage threshold: >= 40%

Run tests locally

cd backend
pip install -r requirements.txt
pytest -v --cov=app --cov-report=term-missing

Build Phases

Phase 1 — Foundation (Complete)

PostgreSQL schema + H3 cell seeder
FastAPI backend (auth, users, outage reports, H3 lookup, predictions)
OpenWeatherMap weather integration
Jasmin SMS gateway + SMPP routing via env vars (no vendor lock-in)
Celery tasks (weather fetch + prediction + alert dispatch)
7-language SMS templates (en/fr/sw/rw/ar/es/pt)
Alembic migration chain (0001→0007)
Supabase database bootstrap script (bootstrap_supabase.sql)
CI/CD pipeline (GitHub Actions, SQLite in-memory, coverage ≥ 40%)

Phase 2 — Intelligence (Complete)

Phase 3 — Scale & Polish

ML training scripts — XGBoost (ml_training/train_xgboost.py) + Prophet (ml_training/train_prophet.py) per-cell time-series training
Mapbox heatmap — H3 hexagon overlay ready via existing neighborhood data + predictions
PWA Service Worker + offline mode — IndexedDB sync architecture in place
ENTSO-E / EIA grid load integration — GET /grid-load/{region}, POST /grid-load/{region}/fetch, history endpoint; fetches Europe (ENTSO-E) and US (EIA) grid data
Web Push notifications (VAPID) — GET /push/vapid-public-key, Celery task tasks.send_push_alert, VAPID keys via env vars
Stripe billing — GET /billing/plans, POST /billing/subscribe, POST /billing/webhook; Free / Pro ($9.99) / Business ($49) / Enterprise ($199) tiers; falls back to direct activation if no Stripe key
Public REST API for governments and NGOs — POST /public/keys/register (SHA-256 hashed keys), GET /public/outages, GET /public/predictions/{h3_index}, GET /public/stats/{country_code}
GNN cascade prediction — GET /gnn/predictions/{h3_index}, GET /gnn/cascade-risk/{transformer_id}; GraphSAGE scaffold in ml_training/gnn_model.py with heuristic fallback
Migration chain extended to 0001→0026 (26 migrations, 40+ tables)

Phase 4 — High Impact Core

Outage duration prediction — Second XGBoost regression model predicts min/median/max duration per outage; wired into every 4-hour prediction run for MEDIUM+ risk cells; predicted_duration_min/median/max exposed in PredictionOut; training script ml_training/train_duration_model.py
Restoration ETA tracking — RestorationEvent lifecycle (reported → crew_assigned → crew_en_route → crew_on_site → restored); GET /restoration/cell/{h3}, GET /restoration/outage/{id}, PATCH /restoration/{id}/status; auto-created when outage is verified; Celery task broadcast_restoration_update pushes ETA to all cell subscribers
Predictive maintenance scoring — maintenance_risk_score per transformer (age × outage density × GNN cascade risk × maintenance lag); GET /maintenance/transformers/at-risk returns top-N ranked list; weekly Celery task score_transformers; CRITICAL/HIGH/MEDIUM/LOW labels
Community trust-weighted verification — trust_score (0.1–1.0) on each user; confirmation adds trust_score to weighted_verification_score; outage verified when score ≥ 3.0 (not just raw count 3); trust auto-recomputes after each confirm via recompute_trust_score()
Migration chain extended to 0001→0029 (29 migrations, 45+ tables)

Contributing

Pull requests are welcome. For major changes, open an issue first.

git checkout -b feature/your-feature-name
# make changes
git commit -m "feat: describe your change"
git push origin feature/your-feature-name
# open a PR

License

Built for the world — from Osee to everywhere.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
charts/blackout-predictor		charts/blackout-predictor
data-pipeline		data-pipeline
infrastructure		infrastructure
ml-engine		ml-engine
monitoring		monitoring
notebooks		notebooks
sms-gateway		sms-gateway
terraform/aws		terraform/aws
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
docker-compose.demo.yml		docker-compose.demo.yml
docker-compose.yml		docker-compose.yml
render.yaml		render.yaml

Latest commit

History

Folders and files

Repository files navigation

AI Power Blackout Predictor

Table of Contents

Overview

Key Features

Architecture

Tech Stack

Backend

Database & Cache

Machine Learning

SMS & Messaging

Geospatial

Infrastructure

External APIs

Project Structure

Getting Started

Prerequisites

1 — Clone & configure

2 — Initialize the database

3 — Start all services

4 — Seed neighborhood cells

5 — Explore the API

Local development (without Docker)

Database Setup (Supabase)

Environment Variables

SMS Gateway — Jasmin + SMPP

Cost comparison

ML Engine

Prediction pipeline (Celery, every 4 hours)

Feature set

Risk levels

Train the model

AI Insights (Groq LLM)

Supported Languages

API Reference

Core endpoints

New feature endpoints (migration 0008–0021)

CI/CD

Current test status

Run tests locally

Build Phases

Phase 1 — Foundation (Complete)

Phase 2 — Intelligence (Complete)

Phase 3 — Scale & Polish

Phase 4 — High Impact Core

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages