1hamzaachour-ai/tunisia-outage-predictor
Domaine:
environment and energydigital infrastructureType de record:
software
Créateur:
1ha
Hôte:
Nationwide SONEDE/STEG outage prediction for Tunisia - ML + RAG + WhatsApp/Email/SMS alerts (Streamlit)
# Tunisia Outage Predictor
Streamlit dashboard that predicts water (SONEDE) and electricity (STEG) outages
across Tunisia's 24 governorates and notifies residents over WhatsApp, email or SMS.
**Live browser demo** —
static version of the dashboard (GitHub Pages, no backend).
## Features
- Per-governorate outage risk from two RandomForest classifiers (temperature,
dam level, grid load, seasonality)
- 7-day risk forecast chart (Altair) with hover tooltips
- Retrieval-augmented explanations: relevant SONEDE/STEG/INM alerts are ranked
and summarized into a two-sentence "why" for each predicted cut (LLM when an
OpenAI key is set, offline template otherwise)
- Alert gateway with four delivery channels: Twilio WhatsApp sandbox, Gmail
SMTP (any recipient), Resend, CallMeBot — each falls back to a console
simulator when credentials are missing
- Self-bootstrapping: a fresh clone generates its dataset and trains its
models on first launch
## Tech stack
Python 3.11+, Streamlit, scikit-learn, pandas, Altair, Twilio, Resend, python-dotenv.
## Setup
```bash
git clone github.com
cd tunisia-outage-predictor
pip install -r requirements.txt
cp .env.example .env # then fill in the keys you have (all optional)
streamlit run app.py
```
First launch takes ~30 seconds while the dataset and models are built.
## Usage
- Pick a governorate and drag the temperature / dam-level sliders, or use the
**Crisis** / **Calm day** presets in the sidebar.
- When a cut is predicted, the situation analysis explains why and the
**Send Alert to Residents** button becomes active.
- Choose the delivery channel in the sidebar gateway panel. Without keys the
send is simulated and printed to the console.
CLI delivery test (polls Twilio for the delivery receipt):
```bash
python scripts/send_test_alert.py --to +216XXXXXXXX
```
Rebuild the data or models manually:
```bash
python -m outage.data
python -m outage.train
```
## Project layout
``` …