1hamzaachour-ai/tunisia-outage-predictor

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 ``` …