README.md

---
language:
- en
tags:
- tabular-classification
- credit-score
- random-forest
- sklearn
- finance
- banking
pipeline_tag: tabular-classification
library_name: sklearn
datasets:
- custom
metrics:
- accuracy
- f1
- precision
- recall
model-index:
- name: credit-score-classifier
  results:
  - task:
      type: tabular-classification
      name: Credit Score Classification
    metrics:
    - type: accuracy
      value: 0.80
      name: Accuracy
---

# 💳 Credit Score Classifier

A **Random Forest Classifier** trained to predict customer credit scores into three categories: **Good**, **Standard**, and **Poor**.

## Model Description

This model analyzes customer financial data and behavioral patterns to classify their credit worthiness. It was trained on a comprehensive dataset containing financial metrics, payment history, and credit utilization patterns.

### Model Details

| Property | Value |
|----------|-------|
| **Model Type** | Random Forest Classifier |
| **Framework** | Scikit-learn |
| **Number of Trees** | 100 |
| **Target Classes** | Good, Standard, Poor |
| **Input Features** | 17 numerical + 5 categorical |

## Intended Use

### Primary Use Cases
- **Credit Risk Assessment**: Evaluate creditworthiness of loan applicants
- **Financial Services**: Automate preliminary credit screening
- **Banking Applications**: Support credit limit decisions

### Out-of-Scope Use
- This model should not be the sole decision-maker for credit approvals
- Not intended for use without human oversight
- Should not be used for discriminatory purposes

## How to Use

### Installation

```bash
pip install huggingface_hub scikit-learn pandas numpy
```

### Loading the Model

```python
from huggingface_hub import hf_hub_download
import pickle

# Download model files
model_path = hf_hub_download(repo_id="AdityaaXD/credit-score-classifier", filename="models/final_model.pkl")
scaler_path = hf_hub_download(repo_id="AdityaaXD/credit-score-classifier", filename="models/scaler.pkl")
label_encoder_path = hf_hub_download(repo_id="AdityaaXD/credit-score-classifier", filename="models/label_encoder.pkl")
feature_info_path = hf_hub_download(repo_id="AdityaaXD/credit-score-classifier", filename="models/feature_info.pkl")

# Load the model
with open(model_path, "rb") as f:
    model = pickle.load(f)

with open(scaler_path, "rb") as f:
    scaler = pickle.load(f)

with open(label_encoder_path, "rb") as f:
    label_encoder = pickle.load(f)
```

### Making Predictions

```python
import pandas as pd
import numpy as np

# Example: Prepare your input data
numerical_features = {
    'Age': 30,
    'Annual_Income': 50000,
    'Monthly_Inhand_Salary': 4000,
    'Num_Bank_Accounts': 4,
    'Num_Credit_Card': 3,
    'Interest_Rate': 12,
    'Num_of_Loan': 2,
    'Delay_from_due_date': 5,
    'Num_of_Delayed_Payment': 3,
    'Changed_Credit_Limit': 8.0,
    'Num_Credit_Inquiries': 4,
    'Outstanding_Debt': 1200,
    'Credit_Utilization_Ratio': 28.5,
    'Credit_History_Age_Months': 180,
    'Total_EMI_per_month': 150,
    'Amount_invested_monthly': 200,
    'Monthly_Balance': 500
}

# Scale numerical features
num_df = pd.DataFrame([numerical_features])
scaled_features = scaler.transform(num_df)

# Make prediction (note: categorical features need one-hot encoding)
prediction = model.predict(scaled_features)
predicted_class = label_encoder.inverse_transform(prediction)
print(f"Predicted Credit Score: {predicted_class[0]}")
```

## Training Data

The model was trained on a credit score dataset containing:

| Feature Type | Count | Examples |
|--------------|-------|----------|
| **Numerical** | 17 | Age, Annual Income, Outstanding Debt, Credit Utilization |
| **Categorical** | 5 | Occupation, Credit Mix, Payment Behavior |

### Input Features

#### Numerical Features
- `Age` - Customer's age
- `Annual_Income` - Yearly income
- `Monthly_Inhand_Salary` - Monthly take-home salary
- `Num_Bank_Accounts` - Number of bank accounts
- `Num_Credit_Card` - Number of credit cards
- `Interest_Rate` - Average interest rate
- `Num_of_Loan` - Number of active loans
- `Delay_from_due_date` - Average payment delay (days)
- `Num_of_Delayed_Payment` - Count of delayed payments
- `Changed_Credit_Limit` - Credit limit changes
- `Num_Credit_Inquiries` - Number of credit inquiries
- `Outstanding_Debt` - Total outstanding debt
- `Credit_Utilization_Ratio` - Credit utilization percentage
- `Credit_History_Age_Months` - Credit history length
- `Total_EMI_per_month` - Monthly EMI payments
- `Amount_invested_monthly` - Monthly investments
- `Monthly_Balance` - Average monthly balance

#### Categorical Features
- `Month` - Month of record
- `Occupation` - Employment type
- `Credit_Mix` - Types of credit accounts
- `Payment_of_Min_Amount` - Minimum payment behavior
- `Payment_Behaviour` - Spending patterns

## Model Files

| File | Description |
|------|-------------|
| `models/final_model.pkl` | Trained Random Forest model |
| `models/scaler.pkl` | StandardScaler for numerical features |
| `models/label_encoder.pkl` | LabelEncoder for target classes |
| `models/feature_info.pkl` | Feature metadata and column names |
| `models/onehot_encoder.pkl` | OneHotEncoder for categorical features |

## Limitations

- **Data Bias**: Model performance depends on training data quality and may not generalize to all populations
- **Feature Availability**: Requires all 17 numerical and 5 categorical features for accurate predictions
- **Temporal Drift**: Financial patterns change over time; periodic retraining recommended
- **Geographic Scope**: Trained on specific regional data; may need adaptation for other regions

## Ethical Considerations

⚠️ **Important**: This model is intended as a decision-support tool, not a replacement for human judgment.

- Always combine model predictions with human review
- Be aware of potential biases in credit scoring
- Ensure compliance with local financial regulations
- Provide explanations for credit decisions when required by law

## Demo Application

Try the interactive Streamlit demo: [Credit Score Classifier App](https://github.com/ADITYA-tp01/Credit-Score-Clasification)

## Citation

```bibtex
@misc{credit-score-classifier,
  author = {Aditya},
  title = {Credit Score Classification using Random Forest},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/AdityaaXD/credit-score-classifier}
}
```

## Contact

- **Hugging Face**: [@AdityaaXD](https://huggingface.co/AdityaaXD)
- **GitHub**: [@ADITYA-tp01](https://github.com/ADITYA-tp01)