Credit Risk Engine

A machine learning project for credit risk assessment using LightGBM and FastAPI.

Project Structure

• data/: Data files
• notebooks/: Jupyter notebooks for EDA, feature engineering, etc.
• src/: Source code
• models/: Trained models
• api/: API for predictions
• reports/: Documentation and reports
• tests/: Unit tests

Documentation

• End-to-End Guide: Complete walkthrough of the project
• Model Development Document: Technical specification of model development
• Model Validation Report: Performance metrics, KS score, confusion matrix
• Decision Policy Document: Threshold selection and decision logic
• Explainability Document: SHAP analysis, feature importance
• Monitoring & Drift Policy: Drift detection, PSI, production monitoring
• API Documentation: API endpoints and usage
• MLflow Guide: Experiment tracking setup
• Deployment & Versioning Notes: Production deployment details
• Production Readiness Checklist: What's needed for production
• Business Approval Document: Business case and approval requirements
• ChatGPT Conversation Summary: Q&A insights on model building, LightGBM, thresholds, and production readiness

Setup

• Install dependencies:
  • pip install -r requirements.txt
• Place data files in data/raw/
• Train model (logs to MLflow and saves to models/):
  • python src/train_pipeline.py
• Start API locally:
  • python -m uvicorn api.main:app --host 127.0.0.1 --port 8000

Docker

Build and run with Docker:

docker build -t credit-risk .
docker run -p 8000:8000 credit-risk

Or with docker-compose:

GCP Deployment

Deploy to Google Cloud Platform using Cloud Run, BigQuery, and Vertex AI:

1. Setup GCP Project:

   export PROJECT_ID=your-project-id
   gcloud config set project $PROJECT_ID
   gcloud auth login

2. Run Deployment Script:

   chmod +x scripts/deploy_gcp.sh
   ./scripts/deploy_gcp.sh $PROJECT_ID

3. Upload Data to BigQuery (optional):

   python scripts/upload_to_bigquery.py

4. Train Model with Vertex AI:

   export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
   python src/train_pipeline.py

See GCP Deployment Guide for detailed instructions.

docker-compose up

API Overview

Endpoints:

• GET /healthz – liveness check
• GET /readiness – verifies model is loaded and can score
• GET /version – model metadata (path, hash, features, threshold)
• POST /predict – returns probability of default and decision
• POST /explain – returns probability and SHAP feature contributions

Request schema for /predict and /explain:

{
  "annual_income": 50000.0,
  "debt_to_income_ratio": 0.25,
  "credit_score": 700,
  "loan_amount": 200000.0,
  "interest_rate": 4.5,
  "gender": "Female",
  "marital_status": "Single",
  "education_level": "Bachelor's",
  "employment_status": "Employed",
  "loan_purpose": "Home",
  "grade_subgrade": "A1"
}

Decision logic:

• Model outputs probability of class 1 = default
• Threshold loaded from models/threshold.json (default 0.4542)
• Decision = REJECT if probability ≥ threshold, else APPROVE

Monitoring

• Data drift: PSI calculations (src/monitoring/)
• Model drift: KS statistic over time
• MLflow for experiment tracking

Tests

• Run tests: pytest