README.md

---
title: FinRisk-AI
emoji: ⚡
colorFrom: indigo
colorTo: green
sdk: docker
sdk_version: 0.0.1
app_file: app.py
pinned: false
license: mit
---

# FinRisk-AI / Credit Score Classification

## 1. Problem Definition
The objective of this project is to build a machine learning model to classify customers' credit scores into three categories: **Good, Standard, and Poor**. This automated system aims to reduce manual underwriting time and improve risk assessment accuracy.

## 2. Project Scope 
### 2.1.Documentation
- [Setup & Installation](docs/00_setup.md)
- [Data Overview](docs/01_data_overview.md)
- [Baseline Models](docs/02_baseline.md) 
- [Feature Engineering](docs/03_feature_engineering.md) 
- [Model Optimization](docs/04_model_optimization.md) 
- [API Deployment](docs/api_deployment.md) 
## 3. Deployment
**Try the Model Instantly:**
[Link to Live Demo (Simulated)] (e.g., HuggingFace Spaces URL)

To run locally:
1.  Install dependencies: `pip install -r requirements.txt`
2.  Run the app: `python src/app.py`
3.  Open browser at `http://localhost:7860`

## 4. Key Findings & Results
*   **Baseline Score**: 60% Accuracy (Logistic Regression).
*   **Final Score**: **80% Accuracy** (XGBoost).
*   **Top Predictors**: Outstanding Debt, Credit Mix, and Interest Rate.
*   **Business Impact**: Potential to reduce default rates by 15% and cut processing time by 90%.

## 5. Repository Structure


```
FinRisk-AI/
│
├── README.md                          # Project Overview
├── requirements.txt                   # Dependencies
├── .gitignore                         
│
├── data/                              # Raw and Processed Data
│   ├── raw/
│   │   ├── train.csv
│   │   └── test.csv              
│   └── processed/
│       ├── train_processed.csv
│       └── test_processed.csv
│
├── docs/                             # Detailed Documentation
│   ├── 00_setup.md
│   ├── 01_data_overview.md
│   ├── 02_baseline.md
│   ├── 03_feature_engineering.md
│   ├── 04_model_optimization.md
│   └── 05_evaluation_report.md
│
├── notebooks/                         # Jupyter Notebooks (EDA -> Pipeline)
│   ├── Analysis/
│   │   └── 00_Data_Preparation_Training.ipynb
│   └── Modeling/
│       ├── 01_EDA.ipynb
│       ├── 02_baseline_model.ipynb
│       ├── 03_feature_engineering.ipynb
│       ├── 04_model_optimization.ipynb
│       └── 05_model_evaluation.ipynb
│       
│
├── src/                               # Source Code
│   ├── templates/                     #UI
│   │   └── index.html
│   ├── models/                        # Saved Artifacts
│   │   ├── final_model.pkl
│   │   └── features.json
│   └── tests/
│       ├── app.py                   # App
│       ├── config.py                # Configuration
│       ├── inference.py             # Prediction Logic
│       └── pipeline.py              # Training Pipeline
│
└── OIG2.png
```
<img width="1862" height="853" alt="image" src="https://github.com/user-attachments/assets/0e259956-69d9-4c82-99d3-0ad0fbb619a3" />


## Contact
*   **Author**: Rana Irem Turhan
*   **GitHub**: github.com/Rana-Irem-Turhan
*   **LinkedIn**: https://www.linkedin.com/in/irem-turhan/