Dep-Sight / README.md
StillWorking's picture
Upload 10 files
2996c62 verified
|
Raw History Blame Contribute Delete
2.87 kB
---
title: Deep Sight
emoji: πŸ“Š
colorFrom: blue
colorTo: pink
sdk: docker
app_file: app.py
pinned: false
---
# DeepSight EWS - Loan Default Prediction System
**IDBI Bank Innovation 2026** - Early Warning System for Loan Defaults
This is a FastAPI-based backend deployed on Hugging Face Spaces that provides loan default prediction capabilities using a dual-branch machine learning model combining structured financial data and NLP-based narrative analysis.
## πŸš€ Features
- **Portfolio Summary**: Real-time overview of loan portfolio health
- **High-Risk Alerts**: Identification of borrowers with high probability of default (PD > 0.65)
- **Borrower Explanations**: Detailed SHAP-based explanations showing which features drive risk
- **Loan Prediction API**: Make predictions for new loan applications
- **SHAP Visualizations**: Global feature importance and individual borrower waterfalls
## πŸ“Š Model Architecture
The DeepSight model uses a **dual-branch architecture**:
### Branch A: Structured Financial Data
- Loan amount, interest rate, DTI ratio
- Annual income, FICO score
- Credit history metrics (open accounts, delinquencies)
- Employment length, revolving utilization
### Branch B: NLP Narrative Analysis
- Borrower narrative text processing
- FinBERT sentiment analysis (positive, negative, neutral)
- Distress indicators from loan descriptions
- Combined text features (title + description + purpose)
## πŸ”§ API Endpoints
### Health Check
```bash
GET /
GET /health
```
### Portfolio Management
```bash
GET /api/portfolio/summary
# Returns: total loans, high-risk alerts, portfolio health score
GET /api/borrowers/alerts?limit=50
# Returns: List of high-risk borrowers with PD scores
GET /api/borrowers/{borrower_id}/explain
# Returns: Detailed explanation with SHAP visualization
```
### Predictions
```bash
POST /api/predict
# Body: {
# "loan_amnt": 15000,
# "int_rate": 14.5,
# "dti": 22.5,
# "annual_inc": 65000,
# "installment": 425,
# "fico_score": 680,
# "open_acc": 12,
# "delinq_2yrs": 1
# }
# Returns: Probability of default and risk category
```
## πŸ“š API Documentation
Once deployed, interactive API documentation is available at:
- Swagger UI: `/docs`
- ReDoc: `/redoc`
## πŸ“Š Model Performance
- **Architecture**: LightGBM with dual-branch input
- **Training Data**: 2.2M+ loans from LendingClub (2007-2018)
- **Features**: 150+ engineered features (structured + NLP)
- **Explainability**: SHAP values for model interpretability
## πŸ› οΈ Technology Stack
- **Framework**: FastAPI 0.109.0
- **ML Libraries**: scikit-learn, LightGBM, XGBoost
- **Data Processing**: pandas, numpy
- **Explainability**: SHAP 0.44.1
- **Server**: Uvicorn with ASGI
---
**Deployed with ❀️ on Hugging Face Spaces**