🧠 CredInsight AI

Explainable Credit Risk Assessment powered by Machine Learning and AI.

CredInsight AI is a machine-learning-based credit risk assessment tool that predicts loan-default risk from an applicant's financial profile and turns that prediction into a plain-language explanation using an LLM. It combines a trained Random Forest classifier with Groq's Llama 3.1 to move beyond a raw "risk score" toward something a human can actually reason about.

🚀 Live Demo: credinsight-ai.streamlit.app 💻 Repository: github.com/commit-msuyog/Explainable-Credit-Risk-AI

📖 Table of Contents

Overview
Problem Statement
Proposed Solution
Key Features
How It Works
System Architecture
Machine Learning
Explainable AI / LLM Layer
Risk Assessment
Technology Stack
Project Structure
Installation
Environment Variables
Screenshots
Results / Model Performance
Limitations
Challenges
Future Scope
Open Innovation Angle
Ethical & Responsible AI
Disclaimer
Author
License

🔎 Overview

CredInsight AI predicts whether a loan applicant is likely to default, and then explains why, in plain financial language.

What it does: Takes applicant and loan details, runs them through a trained Random Forest model to get a default prediction and probability, then passes that result to an LLM which writes a short, human-readable financial assessment.
Who it's for: Anyone exploring how ML-based risk scoring can be paired with LLM explanations — recruiters, hackathon judges, and students learning applied ML/LLM integration.
Why it exists: A bare "High Risk / Low Risk" label doesn't tell you why. CredInsight closes that gap without hiding the underlying prediction.
What makes it different: It doesn't stop at classification. The pipeline goes:

Prediction → Probability → Financial Context → AI Explanation → Actionable Recommendation

❓ Problem Statement

Credit-risk decisions depend on a mix of applicant and loan-level variables — income, credit grade, loan-to-income ratio, employment history, repayment history, and more. A trained model can combine these into a single prediction, but that prediction alone is a number, not an explanation.

CredInsight is built around one question:

"How can credit-risk predictions be transformed into understandable financial insights?"

This involves:

Making sense of several interacting financial variables at once
Producing a consistent, repeatable risk assessment
Translating a probability into language a non-technical reader can act on

CredInsight AI is a prototype/educational project. It does not replace banks, lenders, credit bureaus, or licensed financial professionals.

🧩 Proposed Solution

Applicant Data
      │
      ▼
Feature Preparation (encoding & alignment)
      │
      ▼
Random Forest Model
      │
      ▼
Risk Prediction + Default Probability
      │
      ▼
Financial Context (applicant + loan details)
      │
      ▼
Groq API — Llama 3.1
      │
      ▼
Human-Readable Financial Explanation

The Random Forest model is solely responsible for the risk prediction and probability. The LLM never predicts risk — it only interprets and explains a prediction that has already been made.

✨ Key Features

🌲 ML-Based Risk Prediction

A trained Random Forest classifier (models/random_forest_model.pkl) predicts loan-default risk from 17 engineered applicant/loan features.

📊 Probability & Risk-Tier Analysis

Displays default probability, safe probability, and a Low / Medium / High risk tier with a color-coded gauge.

👤 Applicant Profile Input

Collects age, income, employment length, credit history length, loan amount, interest rate, credit grade, loan purpose, home ownership, and prior default history.

🔎 Pre-Assessment Signal Chips

Instantly flags each input (age, grade, interest rate, repayment history, debt-to-income ratio, employment length, credit history length) as green/yellow/red before the model even runs.

🧠 AI Financial Explanation

Sends the prediction, probability, and applicant context to Groq's llama-3.1-8b-instant model, which returns key strengths, key risks, and an overall assessment in natural language.

⚡ Interactive Streamlit Dashboard

A single-page, custom-styled Streamlit interface (dark sidebar, gradient hero, live DTI calculation) for entering data and viewing results instantly.

📋 Risk-Based Recommendation

Based on the default probability, the app surfaces one of three recommendations: Approve with Standard Terms, Manual Review Required, or Decline Recommended.

⚙️ How It Works

The user enters applicant and loan information in the Streamlit form (app/app.py).
The app computes the loan-to-income ratio live and shows a Healthy/Moderate/Stretched DTI badge.
On clicking "⚡ Assess Credit Risk", categorical inputs (credit grade, home ownership, loan purpose, default history) are converted into the one-hot / ordinal encoding the model expects.
The input is assembled into a DataFrame and reindexed against the saved feature list (models/model_features.pkl) so column order always matches training.
The saved Random Forest model (models/random_forest_model.pkl) produces a class prediction (default / no default) and a default probability via predict_proba.
CredInsight maps the probability to a risk tier: Low (< 40%), Medium (40–70%), High (≥ 70%).
The prediction, probability, and applicant/loan details are passed to generate_explanation() in src/ai_explain.py.
That function calls the Groq API (llama-3.1-8b-instant) with a structured prompt asking for strengths, risks, and an overall assessment.
The Streamlit UI renders the result card, risk gauge, probability metrics, AI explanation, and the risk-based recommendation.

🏗️ System Architecture

flowchart TD
    A[Applicant & Loan Data<br/>Streamlit Form Input]
    B[Feature Encoding &<br/>Column Alignment]
    C[Random Forest Model<br/>random_forest_model.pkl]
    D[Risk Prediction<br/>Default / No Default]
    E[Default Probability<br/>predict_proba]
    F[Groq API<br/>Llama 3.1 - 8B Instant]
    G[AI Financial Explanation]
    H[Streamlit Dashboard<br/>Result · Gauge · Recommendation]

    A --> B
    B --> C
    C --> D
    C --> E
    D --> F
    E --> F
    A --> F
    F --> G
    D --> H
    E --> H
    G --> H

🌲 Machine Learning

Model: RandomForestClassifier (n_estimators=100, random_state=42, class_weight="balanced")
Objective: Binary classification of loan_status (0 = no default, 1 = default)
Output: Predicted class + default probability (predict_proba)
Persistence: Model and the exact training feature order are serialized with joblib to models/random_forest_model.pkl and models/model_features.pkl, and loaded directly by the Streamlit app at runtime.

Why Random Forest: the dataset is structured/tabular with a mix of numeric and categorical features and a meaningful class imbalance (~78% non-default vs ~22% default). An ensemble of decision trees handles non-linear feature interactions (e.g. grade × interest rate × loan-to-income) well without heavy feature scaling, and class_weight="balanced" helps counter the imbalance.

Training pipeline (documented in Notebook/credit-rist.ipynb):

Source data: credit_risk_dataset.csv, loaded from a local Data/ folder. This folder is excluded via .gitignore and is not included in the repository — only the notebook and the resulting trained model are versioned.
Raw dataset: 32,581 rows × 12 columns before cleaning.
Cleaning: dropped unrealistic ages (> 100) and impossible employment lengths (> 60 years); missing loan_int_rate values filled with the column mean.
Encoding: one-hot encoding (pd.get_dummies, drop_first=True) for person_home_ownership, loan_intent, cb_person_default_on_file; loan_grade label-encoded.
Post-cleaning shape: 31,679 rows × 18 columns (17 features + target).
Split: 80/20 train/test (train_test_split, random_state=42).
A Logistic Regression baseline (with StandardScaler) was trained first for comparison before the Random Forest model was selected as the final model — see Results.

Top feature importances (from the notebook's feature_importances_ analysis):

Rank	Feature	Importance
1	`loan_percent_income`	0.205
2	`person_income`	0.161
3	`loan_grade`	0.143
4	`loan_int_rate`	0.117
5	`loan_amnt`	0.078
6	`person_emp_length`	0.054
7	`person_home_ownership_RENT`	0.052
8	`person_age`	0.050
9	`cb_person_cred_hist_length`	0.038
10	`person_home_ownership_OWN`	0.018

This feature-importance analysis exists in the notebook as part of model development; it is not exposed as a live feature inside the Streamlit app.

🧠 Explainable AI / LLM Layer

CredInsight combines two distinct layers that must not be confused:

Machine Learning Layer — responsible for

Risk prediction (default / no default)
Default probability

LLM Layer — responsible for

Interpreting the applicant's financial context
Explaining strengths (e.g. credit grade, income, employment stability)
Highlighting risks (e.g. loan-to-income ratio, loan amount)
Producing a human-readable overall assessment

The LLM (Groq API, llama-3.1-8b-instant) never predicts credit risk. It receives the model's prediction, probability, and the applicant's structured details, and its only job is to explain that result in natural language via generate_explanation() in src/ai_explain.py.

CredInsight does not currently implement SHAP, LIME, or any feature-attribution explainability method. SHAP-based explainability is listed under Future Scope only — it is not part of the current implementation.

📊 Risk Assessment

Based on the model's default probability, the app derives:

Probability	Risk Tier	Recommendation
< 40%	Low	✅ Approve with Standard Terms
40% – 70%	Medium	⚠️ Manual Review Required
≥ 70%	High	⛔ Decline Recommended

A separate, lighter-weight debt-to-income (DTI) check runs on the raw inputs before prediction: loan_amnt / person_income is labeled Healthy (< 30%), Moderate (< 60%), or Stretched (≥ 60%) as an early signal to the user.

🛠️ Technology Stack

Category	Technology	Purpose
Programming	Python	Core language for the app, ML, and notebook
Data	Pandas, NumPy	Data loading, cleaning, feature preparation
Machine Learning	Scikit-learn (Random Forest, Logistic Regression baseline)	Model training and evaluation
Model Persistence	Joblib	Saving/loading the trained model and feature list
LLM	Groq API, Llama 3.1 (`llama-3.1-8b-instant`)	Generating human-readable financial explanations
Frontend	Streamlit	Interactive web dashboard
Styling	Custom CSS (injected via `st.markdown`)	Hero section, sidebar, gauges, result cards, chips
Config	python-dotenv	Loading `GROQ_API_KEY` from a local `.env` file
Deployment	Streamlit Community Cloud	Hosting the live demo
Development	Git, GitHub, Jupyter Notebook, Dev Container (Codespaces)	Version control and model development

📁 Project Structure

Explainable-Credit-Risk-AI/
│
├── .devcontainer/
│   └── devcontainer.json        # Codespaces/dev container config; auto-runs the Streamlit app
├── Notebook/
│   └── credit-rist.ipynb        # EDA, cleaning, model training & evaluation
├── app/
│   └── app.py                   # Streamlit application (entry point)
├── assets/
│   ├── home.png                 # Dashboard screenshot
│   └── ai-explain.png           # AI explanation screenshot
├── models/
│   ├── random_forest_model.pkl  # Trained Random Forest model
│   └── model_features.pkl       # Ordered list of the 17 model input features
├── src/
│   ├── __init__.py
│   └── ai_explain.py            # Groq / Llama 3.1 explanation layer
├── .gitignore                   # Ignores venv/, Data/, __pycache__/, .ipynb_checkpoints/, .env
├── requirements.txt
└── README.md

Note: the raw training dataset (Data/credit_risk_dataset.csv) is referenced in the notebook but is excluded via .gitignore and is not part of this repository.

💻 Installation

Clone the repository

git clone https://github.com/commit-msuyog/Explainable-Credit-Risk-AI.git

Enter the project directory
```
cd Explainable-Credit-Risk-AI
```
Create a virtual environment
```
python -m venv venv
```
Activate the virtual environment (Windows)
```
venv\Scripts\activate
```
Install dependencies
```
pip install -r requirements.txt
```
Configure environment variables — see Environment Variables below.
Run the Streamlit application
```
streamlit run app/app.py
```

🔐 Environment Variables

CredInsight needs a Groq API key to generate AI explanations. Create a .env file in the project root:

GROQ_API_KEY=your_api_key_here

.env is already excluded via .gitignore — never commit your real key.
The repository does not currently include a .env.example file. Adding one is listed under Future Scope.

📸 Screenshots

Main Dashboard — applicant/loan input form, live snapshot metrics, and pre-assessment signal chips:

AI Financial Explanation — risk gauge, probability metrics, and the Groq-generated explanation:

📈 Results / Model Performance

Evaluation metrics below are from the notebook (Notebook/credit-rist.ipynb), computed on a 20% held-out test set (6,336 samples).

Random Forest (final model)

Class	Precision	Recall	F1-score	Support
0 – No Default	0.93	0.98	0.95	4,963
1 – Default	0.90	0.73	0.80	1,373
Accuracy			0.92	6,336
Macro avg	0.91	0.85	0.88	6,336
Weighted avg	0.92	0.92	0.92	6,336

ROC-AUC: 0.930

Confusion Matrix

	Predicted: No Default	Predicted: Default
Actual: No Default	4,846	117
Actual: Default	371	1,002

For comparison, a Logistic Regression baseline (with StandardScaler, class_weight="balanced") was also trained in the notebook and reached 78% accuracy with a 0.60 F1-score on the default class — the Random Forest model was selected as the final model based on these results.

⚠️ Limitations

Model performance depends entirely on the training data it saw; it has not been validated against out-of-distribution or real-world lending data.
Predictions should not be treated as guaranteed or final financial decisions.
LLM-generated explanations are supporting analysis, not verified financial advice — they can be inaccurate or incomplete.
Real-world lending requires broader validation, regulatory compliance, and domain review that this project does not implement.
Alternative-data credit scoring (beyond the current tabular features) is not implemented.
Fairness and bias across applicant subgroups have not been formally evaluated.

🧗 Challenges

Preparing and cleaning structured financial data (unrealistic ages, impossible employment lengths, missing interest rates).
Keeping feature ordering consistent between training and inference by persisting model_features.pkl alongside the model.
Converting categorical Streamlit inputs (grade, home ownership, loan purpose, repayment history) into the exact one-hot/ordinal encoding the model was trained on.
Connecting a deterministic ML prediction to a non-deterministic LLM explanation layer without letting the LLM influence the actual risk decision.
Managing the Groq API key securely via environment variables instead of hardcoding it.
Building a readable, informative single-page Streamlit dashboard (gauge, chips, recommendation) with custom CSS.

🚀 Future Scope

🔍 Advanced Explainability

SHAP-based feature-level explanations for individual predictions.

📊 Advanced Risk Analytics

More detailed risk visualizations and model diagnostics inside the app itself.

🤖 Multi-Model Comparison

Compare Random Forest against other suitable ML algorithms directly in the app.

📄 Automated Reports

Generate downloadable PDF financial-risk reports.

🌐 Alternative Financial Signals

Explore non-traditional financial signals for applicants with limited formal credit history.

⚖️ Fairness & Bias Monitoring

Evaluate model behavior across different applicant groups.

🔐 Privacy & Configuration

Add a .env.example file and improve secure handling of sensitive financial information.

🌍 Scalable Deployment

Move toward production-ready infrastructure beyond the current Streamlit Community Cloud demo.

💡 Why CredInsight?

This project is submitted under an Open Innovation category — it isn't built against a fixed problem statement, but around a specific interpretability gap in credit-risk tooling.

CredInsight layers three things together:

Traditional ML → Risk Prediction LLM → Human-Readable Financial Explanation Interactive Dashboard → Decision-Support Experience

The innovation isn't "using AI" — plenty of projects do that. It's the deliberate separation of concerns: the ML model stays responsible for the actual risk decision, while the LLM is constrained to explaining that decision rather than making it. The result is a Predict → Understand → Explain → Act flow that's more interpretable than a bare classification output.

This is a prototype/demo project — it is not deployed in, or affiliated with, any real financial institution.

🛡️ Ethical & Responsible AI

Predictions are meant to support, not replace, human judgment in lending decisions.
Financial decisions carry real consequences for applicants — this system should be treated as a decision-support aid, not an authority.
Training data can encode historical bias; this has not been formally audited here.
Sensitive financial information (income, credit history) should be handled and transmitted securely.
LLM explanations are generated interpretations, not unquestionable financial advice, and should be reviewed critically.

⚖️ Disclaimer

CredInsight AI is an educational/prototype machine-learning project and should not be used as the sole basis for real-world lending or financial decisions.

👨‍💻 Author

Suyog Verma

📄 License

No LICENSE file is currently present in this repository. All rights are reserved by the author unless a license is added.

FilesExpand file tree

README.md

Latest commit

History