CreditSense — ML Credit Scoring API

Real-time credit risk prediction using an ensemble of ML models, served via FastAPI

---

Analysis Graphs

Run from the repo root (requires matplotlib, numpy, scipy, scikit-learn):

python graphs/roc_curves.py          # ROC comparison: LR vs RF vs GBM
python graphs/feature_importance.py  # GBM feature importance bar chart
python graphs/score_distribution.py  # Risk score KDE by default/non-default class

Script	What it shows
roc_curves.py	ROC curves and AUC for all three ensemble models
feature_importance.py	Normalised feature importances from the GBM model
score_distribution.py	KDE of predicted risk scores split by applicant outcome

---

What It Does

CreditSense takes three applicant inputs — age, monthly income, and debt-to-income ratio — and returns a credit score (0–100), a risk tier, and a plain-language explanation of the key risk drivers.

POST /score
{
  "age": 32,
  "monthly_income": 4500,
  "debt_ratio": 0.38
}

→ { "credit_score": 71, "risk_level": "Low Risk", "summary": "..." }

---

Architecture

credit_risk_dataset.csv
        │
        ▼
┌──────────────────────────────────┐
│  train_model.py                  │
│                                  │
│  Logistic Regression             │
│  + Random Forest                 │
│  + Gradient Boosting             │
│  → VotingClassifier ensemble     │
│  → Serialised → model.pkl        │
└──────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────┐
│  main.py — FastAPI               │
│                                  │
│  POST /score  → risk score       │
│  GET  /health → service status   │
└──────────────────────────────────┘
        │
        ▼
   Render (free tier)

---

Setup

git clone https://github.com/Hridambiswas/creditsense-backend.git
cd creditsense-backend
pip install -r requirements.txt

# Train the model first
python train_model.py

# Start the API
uvicorn main:app --reload

API docs auto-generated at http://localhost:8000/docs

---

Project Structure

creditsense-backend/
│
├── main.py                  # FastAPI app — POST /score endpoint
├── train_model.py           # Trains VotingClassifier, saves model.pkl
├── ml_decision.py           # Data preprocessing + model training utilities
├── frontend_app.py          # Streamlit frontend (optional UI)
├── credit_risk_dataset.csv  # Training data (23,000+ loan records)
├── requirements.txt
├── runtime.txt              # Python version pin for Render
└── render.yaml              # One-click Render deployment config

---

Model Details

Model	Role
Logistic Regression	Linear baseline, interpretable coefficients
Random Forest	Non-linear patterns, handles missing data
Gradient Boosting	Sequential error correction, highest accuracy
VotingClassifier	Soft-vote ensemble — final predictor

Training data: 23,000+ real loan applications with features including age, income, employment length, loan purpose, and historical default behavior.

---

API Endpoints

Method	Endpoint	Description
GET	/health	Service health check
POST	/score	Returns credit score + risk breakdown

---

Deployment

Pre-configured for Render free tier via render.yaml. Push to GitHub and connect the repo — zero-config deploy.

---

Author

Hridam Biswas — IEEE Researcher, KIIT University
GitHub · Portfolio