CreditXAI Enterprise

An explainable AI platform for credit risk assessment. Built with Streamlit, SHAP, LIME, and scikit-learn. Covers the full ML lifecycle: data preprocessing, model training, explainability, fairness auditing, drift monitoring, and regulatory reporting.

---

Project Structure

Xai/
├── app/
│   ├── main.py                     # Streamlit entry point
│   ├── components/
│   │   ├── layout.py               # UI components, nav bar, CSS
│   │   └── charts.py               # Shared Plotly chart helpers
│   └── pages/
│       ├── 01_Risk_Prediction.py   # Applicant risk scoring
│       ├── 02_Global_Explainability.py
│       ├── 03_Local_Explainability.py
│       ├── 04_Counterfactual_Analysis.py
│       ├── 05_Surrogate_Rules.py
│       ├── 06_Feature_Interactions.py
│       ├── 07_Fairness_Audit.py
│       ├── 08_Model_Comparison.py
│       ├── 09_Drift_Monitor.py
│       └── 10_Regulatory_Report.py
├── src/
│   ├── data_preprocessing.py       # Feature engineering pipeline
│   ├── model_training.py           # Train LR, RF, XGBoost, LightGBM
│   ├── explainability/
│   │   ├── global_xai.py           # Feature importance, SHAP summary, PDP/ICE
│   │   ├── local_xai.py            # SHAP waterfall, force plot, LIME
│   │   ├── interaction.py          # SHAP interaction heatmap
│   │   ├── surrogate.py            # Decision tree surrogate rules
│   │   └── counterfactual.py       # DiCE counterfactual generation
│   ├── fairness/
│   │   ├── metrics.py              # Demographic parity, equal opportunity, etc.
│   │   └── mitigation.py          # Reweighing, threshold adjustment
│   └── monitoring/
│       ├── drift.py                # PSI-based feature drift
│       └── stability.py            # Model stability tracking
├── data/
│   ├── german_credit_data.csv      # Raw dataset (UCI German Credit)
│   └── processed/                  # Generated after training
├── models/                         # Generated after training
├── requirements.txt
└── Makefile

---

Setup

1. Prerequisites

• Python 3.10+
• pip

2. Install dependencies

cd /Users/pavanpradeep/Downloads/Xai
pip install -r requirements.txt

Or use Make:

make install

---

Running the App

Step 1 — Train models (required before launching the app)

This preprocesses the German Credit dataset, trains 4 models (Logistic Regression, Random Forest, XGBoost, LightGBM), computes SHAP values, and saves all artifacts to models/.

cd /Users/pavanpradeep/Downloads/Xai
python src/model_training.py

Or:

make train

Expected output files after training:

models/
├── lr_model.pkl
├── rf_model.pkl
├── xgb_model.pkl
├── lgbm_model.pkl
├── metrics.json
└── shap_values/
    ├── lr_shap.npy
    ├── rf_shap.npy
    ├── xgb_shap.npy
    ├── lgbm_shap.npy
    ├── lr_expected.npy
    └── ...
data/processed/
├── X_train.parquet
├── X_test.parquet
├── y_train.parquet
├── y_test.parquet
├── df_raw_test.parquet
└── feature_names.json

Step 2 — Launch the Streamlit app

cd /Users/pavanpradeep/Downloads/Xai
streamlit run app/main.py --server.port=8501

Or:

make run

Then open your browser at: http://localhost:8501

One-command setup (install + train + run)

make all

---

Pages Overview

Page	URL	Description
01 Risk Prediction	/Risk_Prediction	Enter applicant details, get risk score and SHAP explanation
02 Global Explainability	/Global_Explainability	Feature importance, SHAP beeswarm, PDP+ICE, SHAP dependence
03 Local Explainability	/Local_Explainability	Per-instance SHAP waterfall, decision plot, LIME, force plot
04 Counterfactual Analysis	/Counterfactual_Analysis	What-if scenarios using DiCE to find minimal changes for loan approval
05 Surrogate Rules	/Surrogate_Rules	Human-readable decision tree rules extracted from black-box models
06 Feature Interactions	/Feature_Interactions	SHAP interaction heatmap, pairwise dependence plots
07 Fairness Audit	/Fairness_Audit	Demographic parity, equal opportunity, disparate impact across age/sex/job
08 Model Comparison	/Model_Comparison	Side-by-side performance metrics, ROC curves, PR curves, calibration
09 Drift Monitor	/Drift_Monitor	Population Stability Index (PSI) to detect feature drift over time
10 Regulatory Report	/Regulatory_Report	Model cards, compliance checklist, downloadable HTML audit report with charts

---

Models Trained

Model	Key
Logistic Regression	lr
Random Forest	rf
XGBoost	xgb
LightGBM	lgbm

All models are trained with 5-fold cross-validation and evaluated on a held-out test set (20%).

---

Explainability Methods

• SHAP — Global feature importance, beeswarm, waterfall, force plot, decision plot, interaction heatmap
• LIME — Local surrogate model per instance
• PDP + ICE — Partial dependence and individual conditional expectation curves
• Surrogate Tree — Decision tree fitted to model predictions, extracting human-readable rules
• Counterfactuals — DiCE framework to generate actionable recourse suggestions

---

Fairness Metrics

• Demographic Parity Difference (DPD)
• Equal Opportunity Difference (EOD)
• Disparate Impact Ratio (DIR — 80% rule)
• Equalized Odds (TPR and FPR gap)
• Predictive Parity Difference

Assessed across: Age Group, Sex, Employment Level

---

Audit Report

On page 10, click Generate Audit Report to download an HTML file containing:

• Model performance comparison chart
• Feature importance chart
• SHAP mean importance chart
• Compliance checklist (auto-detected from artifacts)
• Regulatory alignment notes (GDPR Art. 22, SR 11-7, EU AI Act)

Open the downloaded .html file in any browser and use Ctrl+P → Save as PDF to export a PDF.

---

Troubleshooting

Charts not loading / errors after file edits: Always restart the Streamlit server to pick up module changes:

# Kill existing server
pkill -f "streamlit run"

# Clear Python bytecode cache
find . -name "*.pyc" -delete
find . -name "__pycache__" -type d -exec rm -rf {} +

# Restart
streamlit run app/main.py --server.port=8501

Models not found: Run python src/model_training.py from the project root before launching the app.

Port already in use:

lsof -ti:8501 | xargs kill -9
streamlit run app/main.py --server.port=8501

---

Dataset

German Credit Dataset — UCI Machine Learning Repository 1,000 applicants, 20 features, binary outcome (Good Risk / Bad Risk). Features include: credit amount, duration, age, employment status, housing, savings, and more.

---

Regulatory Frameworks Covered

• GDPR Article 22 — Right to explanation for automated decisions
• SR 11-7 (Federal Reserve / OCC) — Model risk management guidance
• EU AI Act — High-risk AI system transparency and bias requirements (Annex III, Category 5b)