🛡️ Customer Financial Wellness Engine

A full-stack, machine learning-powered fintech prototype built with Python and Streamlit.

This system acts as a proactive risk engine designed to identify customer financial stress before a missed payment occurs (financial wellness deviation). By generating realistic synthetic financial behavior and analyzing it with an XGBoost classifier, the engine flags at-risk accounts and automatically recommends personalized intervention strategies (e.g., payment holidays, EMI restructuring) to bank agents.

---

🚀 Key Features

• Data Simulation Engine: Generates realistic financial profiles for 1000+ customers, injecting complex behavioral patterns like salary delays, gradual savings depletion, and increased borrowing.
• XGBoost Predictive Model: A highly accurate binary classification model trained to predict the probability of financial stress within a 30-day window based on engineered features.
• Dynamic Risk Scoring: Converts raw prediction probabilities into actionable Low, Medium, and High risk tiers.
• Proactive Intervention Panel: Generates specific, contextual recommendations and pre-written outreach messages for agents based on early warning signals.
• Explainability & Analytics: Features interactive Plotly visualizations including radar charts comparing individual behavior to population medians, and model feature importance breakdowns.

---

🛠️ Tech Stack

• Frontend: Streamlit
• Machine Learning: XGBoost, Scikit-Learn
• Data Processing: Pandas, NumPy
• Visualization: Plotly

---

📂 Architecture

The codebase is organized into four distinct modules:

• data_generation.py - Simulates synthetic raw financial data and behavioral patterns.
• feature_engineering.py - Transforms raw data into ML-ready features (calculating EMI-to-salary ratios, discretionary spending indices, etc.).
• model.py - Configures, trains, and evaluates the XGBClassifier, and houses the logic for assigning risk tiers and generating interventions.
• app.py - The main Streamlit dashboard application that orchestrates the flow and presents the UI.

---

⚙️ Quickstart Guide

1. Requirements

Ensure you have Python 3.8+ installed. You can install all necessary dependencies using pip:

pip install streamlit pandas numpy xgboost scikit-learn plotly

2. Run the Application

Execute the Streamlit application from your terminal:

streamlit run app.py

Note: If Streamlit is not in your system Path, you can also run it via Python directly:

python -m streamlit run app.py

3. Usage

1. Open your browser and navigate to http://localhost:8501.
2. Use the Left Sidebar to regenerate data sets, tweak the dataset size, adjust strictness thresholds, and select individual customer IDs to investigate.
3. Review the Main Dashboard to see the selected customer's Risk Score, triggered Early Warning Signals, and the Recommended Action.
4. Explore the Bottom Tabs to view the customer behavior radar chart, global XGBoost performance metrics, and the macroscopic risk distribution of the portfolio.