theerealhenry/Liquidity-Stress-Early-Warning-Prediction-System

Mobile money is the primary access to cash for millions of households and small businesses across Africa, enabling people to receive income, transfer funds, pay bills and manage daily expenses. When financial pressure builds, customers often show early warning signs in their transactions before any formal default occurs. # 💧 Liquidity Stress Early Warning System ### Production-Grade Machine Learning Pipeline for Mobile Money Financial Risk --- ## 🚀 Live Deployment | Platform | Link | Purpose | |:---:|:---:|:---:| | 🚂 **Railway** | **API Endpoint** | Production REST API | | 📖 **Swagger UI** | **Interactive Docs** | Full API Documentation | | ❤️ **Health Check** | **/health** | Live Model Status | --- ## Table of Contents - Project Overview - Business Impact - Competition Details - Key Results - Tech Stack - ML Pipeline Architecture - Feature Engineering - Model Performance - SHAP Interpretability - API Reference - Docker Usage - Local Development - Deployment - Project Structure - Key Engineering Decisions - Reproducing Results - Author --- ## 🎯 Project Overview This project implements a **production-grade machine learning early warning system** that predicts whether a mobile money customer will experience **liquidity stress within the next 30 days**, using six months of transactional behavioural data. Built for the **AI for Economic Activity Challenge (AI4EAC)** on Zindi Africa, the system goes well beyond competition-level modelling to demonstrate real-world MLOps and production ML engineering practices: - **825 engineered features** from 183 raw transaction columns across 23 feature blocks - **5-model heterogeneous ensemble** (LightGBM + XGBoost + CatBoost + TabNet + Logistic Regression) with Platt calibration and Scipy-optimised weighting - **SHAP interpretability** analysis identifying balance deterioration (36% of signal) and income stability (19%) as the dominant risk themes - **Production FastAPI service** containerised with Docker, deployed on Railway, with 3 endpoints, structured middleware, and startup integrity verification - **Full MLOps pipeline**: Optuna hyperparameter tuning, MLflow experiment tracking, stratified K-fold CV, calibration curves, ablation studies, and comprehensive artefact management The competition metric is a **weight …