InnovativeSphere/meridian

A dual‑model economic resilience forecaster — predicts staple food prices and classifies household vulnerability in Nigeria. ```markdown # Meridian — Economic Resilience Forecaster A dual‑model system that forecasts staple food prices across Nigerian markets and classifies household economic vulnerability — then connects the two, so that forward‑looking price risk feeds directly into vulnerability scoring. Built with **classical ML (scikit‑learn)**, real **WFP price data**, and raw **NLSS household survey data** — no pre‑cleaned Kaggle datasets. ## Features - **Price Forecaster** — predicts staple food prices at 1‑month, 6‑month, and 1‑year horizons per market using RandomForestRegressor. - **Regional Baseline & Differential** — calculates the price markup between a specific market and the regional average, turning raw prices into meaningful risk signals. - **Vulnerability Classifier** — computes two parallel scores (poverty/consumption and risk/shock exposure) then combines them into a final Low/Medium/High tier using a “worse of the two” logic that respects households under invisible stress. - **Rainfall Anomaly Integration** — fetches historical weather data from the free Open‑Meteo API and computes rainfall deviation from the 10‑year average, improving price forecasts with real climate signals. - **PostgreSQL Storage** — all price predictions and household assessments are persisted in a relational database for querying and historical tracking. - **Auto‑generated PDF Reports** — each household assessment produces a clean, human‑readable document with tables, a written summary, and a score‑breakdown chart. - **Fully Typed Configuration** — Pydantic‑validated settings loaded from a `.env` file, with `config.example.py` for GitHub safety. ## How It Works 1. **Ingest** WFP food price data and NLSS household survey data (the latter is decoded from a 240k‑line XML codebook). 2. **Engineer features** — lagged prices, rainfall anomalies, rolling inflation proxy, regional identifiers. 3. **Train** three Random Forest regressors (1‑month, 6‑month, 1‑year horizons). 4. **Score** every house …