6S-Consulting-AI-Loan-Risk-Oracle

AI-Powered Financial Insight Engine
End-to-End Loan Risk System
Author: Kishore Muruganantham

---

🎯 Objective

This project goes beyond building a loan risk model — it delivers a complete, intelligent system that predicts, explains, and simulates risk.
Your story: Not just a predictive model, but a business-ready engine that demonstrates technical, analytical, and creative skills.

---

🚀 Features Overview (The 3 Pillars)

1️⃣ Dynamic Risk Segmentation

• Converts raw model probability into actionable business tiers: Prime, Subprime, High-Risk
• Enables real-world lending strategies and decision automation
• Thresholds are configurable (e.g., Prime <20%, Subprime <50%, High-Risk ≥50%)

2️⃣ Explainable AI Oracle (/explain Endpoint)

• Dedicated endpoint using SHAP to break the "black box"
• Reveals the "why" behind each decision: feature attributions, local/global importance, visual plots
• Shows mastery of responsible AI and regulatory compliance

3️⃣ Interactive "What-If" Scenario Simulator (/what-if Endpoint)

• Accepts an application + modifications to simulate outcomes
• Demonstrates how changes (e.g., lower loan amount, higher income) affect risk tier and recommendations
• Turns your API into a collaborative financial advisor — the "wow" factor

---

📁 Professional Project Structure

financial_insight_engine/
├── ml_service/
│   ├── __init__.py
│   ├── train_and_serve.py      # ML, EDA, training, artifacts
│   └── requirements.txt
├── fastapi_app/
│   ├── __init__.py
│   ├── main.py                 # All API endpoints
│   ├── models.py
│   └── requirements.txt
├── .env                        # NGROK URL goes here
└── README.md                   # This full guide

• ml_service/: All model training, EDA, and artifact generation
• fastapi_app/: The FastAPI backend, endpoints, and input validation
• .env: Paste your NGROK URL after training

Dataset:
Place 6S_AI_TASK-Loan_default_Loan_default.xlsx inside ml_service/.

---

🏗️ Ultimate A-Z Setup & Deployment Guide

Step 1: Prepare Your Kingdom (Local Setup)

1. Create the exact project structure above.
2. Copy code for each file into its location.
3. Place your dataset in ml_service/.

Step 2: Summon the Oracle (Run ML Service)

cd financial_insight_engine/ml_service
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python train_and_serve.py

• Script runs EDA, saves charts, trains model, prints NGROK URL.
• Copy the NGROK URL and leave this terminal running.

Step 3: Build the Temple (Run FastAPI App)

# Open a new terminal window
cd financial_insight_engine/fastapi_app
# Go to root, open .env, paste the NGROK URL
cd ..
nano .env
# Paste the NGROK URL
cd fastapi_app
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Step 4: Gaze Upon Your Creation

• ML service running, served to the world via NGROK
• FastAPI API running locally
• Open http://127.0.0.1:8000/docs for interactive API documentation

---

🧪 API Endpoint Testing Guide

1. /predict — POST

curl -X 'POST' \
  'http://127.0.0.1:8000/predict' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "Age": 46, "Income": 84208, "LoanAmount": 129188, "CreditScore": 451, "MonthsEmployed": 26, "NumCreditLines": 3, "InterestRate": 21.17, "LoanTerm": 24, "DTIRatio": 0.31, "Education": "Master", "EmploymentType": "Unemployed", "MaritalStatus": "Divorced", "HasMortgage": "Yes", "HasDependents": "Yes", "LoanPurpose": "Auto", "HasCoSigner": "No" }'

2. /explain — POST

curl -X 'POST' \
  'http://127.0.0.1:8000/explain' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "Age": 46, "Income": 84208, "LoanAmount": 129188, "CreditScore": 451, "MonthsEmployed": 26, "NumCreditLines": 3, "InterestRate": 21.17, "LoanTerm": 24, "DTIRatio": 0.31, "Education": "Master", "EmploymentType": "Unemployed", "MaritalStatus": "Divorced", "HasMortgage": "Yes", "HasDependents": "Yes", "LoanPurpose": "Auto", "HasCoSigner": "No" }'

3. /what-if — POST

curl -X 'POST' \
  'http://127.0.0.1:8000/what-if' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "original_application": { "Age": 46, "Income": 84208, "LoanAmount": 129188, "CreditScore": 451, "MonthsEmployed": 26, "NumCreditLines": 3, "InterestRate": 21.17, "LoanTerm": 24, "DTIRatio": 0.31, "Education": "Master", "EmploymentType": "Unemployed", "MaritalStatus": "Divorced", "HasMortgage": "Yes", "HasDependents": "Yes", "LoanPurpose": "Auto", "HasCoSigner": "No" }, "modifications": { "LoanAmount": 95000, "InterestRate": 15.5 } }'

---

📝 API Input Fields

Required fields:

• Age (int)
• Income (float)
• LoanAmount (float)
• CreditScore (int)
• MonthsEmployed (int)
• NumCreditLines (int)
• InterestRate (float)
• LoanTerm (int)
• DTIRatio (float)
• Education (str)
• EmploymentType (str)
• MaritalStatus (str)
• HasMortgage (Yes/No)
• HasDependents (Yes/No)
• LoanPurpose (str)
• HasCoSigner (Yes/No)

Validation is enforced with Pydantic schemas for data integrity.

---

🧠 Modeling & Engineering Details

• Preprocessing: Imputation, encoding, scaling, outlier handling
• Feature Engineering: Derived features, ratios, buckets
• Modeling: Logistic Regression, Random Forest/XGBoost, cross-validation, tuning
• Evaluation: ROC-AUC, Precision-Recall, confusion matrix, business KPIs
• Artifacts: Model file, pipeline, SHAP explainer, charts/plots, evaluation report

---

📊 Visualizations & Narrative

• EDA charts (distributions, correlations) and model performance plots (ROC, PR, confusion matrix) in ml_service/charts/
• SHAP global and local plots to explain predictions
• Short report in ml_service/report.md summarizing insights and model performance

---

🔄 Retraining & Regeneration

1. Replace dataset in ml_service/
2. Activate venv, run python train_and_serve.py
3. Artifacts and charts regenerate
4. Restart FastAPI app to load new model

---

✅ Evaluation Criteria

• Quality preprocessing & feature engineering
• Modeling rigor & evaluation depth
• API design, validation, error handling
• Clarity/insight in visualizations & explanation
• Modular code, repo hygiene, documentation

---

📦 Deliverables Checklist

• Model File: serialized model artifact
• FastAPI Backend: endpoints, validation, error handling
• Data & Modeling Script: preprocessing, training, EDA, visualization
• Documentation & Visuals: this README, EDA charts, reports

---

💡 Interview & Demo Tips

• Open with the story: the 3 pillars, business impact
• Demo /predict for speed and usability
• Use /explain to showcase interpretability and responsible AI
• Try /what-if for scenario simulation and actionable insights
• Display charts, artifacts, and report for reproducibility

---

🛠️ Troubleshooting

• Artifact loading errors? Check paths, venvs, file locations
• NGROK issues? Check account, tunnels, .env setup
• SHAP/large data: Use TreeExplainer for trees, limit sample size if needed

---

If you want to see more file details, please browse the repo directly on GitHub for the full file list.