zameer-Gimba/cash_liquidity_forecasting

# Predictive Liquidity Model for Agent Banking in Nigeria A production-oriented machine-learning project for forecasting next-day cash withdrawal and deposit demand for Nigerian POS agents and recommending cash reserves and float top-ups with configurable safety buffers. ## Problem Statement POS agents frequently face liquidity mismatches: insufficient physical cash for withdrawals or insufficient electronic float for deposits and transfers. This project predicts next-day withdrawal demand and next-day deposit demand, and supports operational decisions that reduce failed transactions, customer dissatisfaction, and idle cash. ## Dataset The canonical, immutable dataset is `data/feature_engineered_dataset/liquidity_dataset.csv`: 1,513 rows × 50 columns spanning 16 December 2021 to 22 May 2026, with zero missing values. It is never overwritten by any pipeline step; it is the single source of truth for training. Raw Moniepoint POS agent bank statements (`.xlsx`/`.csv`) can also be uploaded through the Streamlit sidebar. Raw statements include: - `TransactionDate`, `Narration`, `Reference`, `Debit`, `Credit`, `Balance` Uploads are auto-detected (`FEATURE_ENGINEERED`, `RAW_STATEMENT`, `PARTIALLY_ENGINEERED`, or `UNKNOWN`), cleaned, classified into 11 narration categories, feature-engineered, and validated against `reference_schema.json` — entirely in-memory (`st.session_state`), never written back to the canonical CSV. See `src/preprocessing/pipeline.py` and `src/utils/dataset_detector.py`. The dataset carries three targets: `Target_Next_Day_Withdrawal_Amount`, `Target_Next_Day_Deposit_Amount`, and `Target_Has_Deposit_Tomorrow` (binary). ## Repository Structure ```text cash_liquidity_forecasting/ ├── data/feature_engineered_dataset/ # canonical liquidity_dataset.csv (immutable) ├── notebooks/ ├── src/preprocessing/ # pipeline.py, path_setup helpers ├── src/models/ # train_*.py, evaluate_models.py, predict_deposit.py ├── …