Explainable AI Loan Approval System
LoanShap predicts loan approval decisions and explains exactly why - using real, verifiable evidence instead of a black-box score. Every verdict, every factor, and every follow-up answer traces back to an actual number, never a guess.
- Predict - an XGBoost classifier trained on 45,000 loan records predicts approve/reject with a probability score.
- Explain - SHAP's TreeExplainer computes exactly which applicant factors pushed the decision, and by how much (not approximated).
- Narrate - a Groq-powered LLM restates the SHAP output in plain language, constrained to cite only the values actually returned by the model.
- Interrogate - an "Ask" chat lets you question any factor in the decision; answers are grounded in the same SHAP data, not invented.
- Counterfactuals - for rejected applicants, a DiCE-inspired engine tests real, verified adjustments (credit score, loan-to-income ratio, credit history, etc.) against the live model and shows which ones would actually flip the verdict to approval and informs when none would.
| Layer | Technology |
|---|---|
| Prediction model | XGBoost (gradient-boosted trees) |
| Attribution | SHAP (TreeExplainer) |
| Narration / chat | Groq LLM |
| Counterfactuals | DiCE-inspired verified nudge search |
| Backend | FastAPI |
| Frontend | React + Vite, Tailwind |
LoanShap/
└── financial-advisor/
├── backend/
│ ├── agents/ # LLM client + explainer logic
│ ├── api/ # route handlers: predict, explain, ask, dice
│ ├── data/
│ ├── ml/ # model, schemas, predictor
│ ├── models/ # trained model artifacts
│ ├── app.py # FastAPI app entrypoint
│ ├── config.py
│ └── requirements.txt
└── frontend/
├── src/
│ ├── App.jsx # main UI - applicant input, decision, chat, counterfactuals
│ ├── RandomLetterSwap.jsx
│ ├── UserCursor.jsx
│ └── Snowfall.jsx
└── public/
└── demo.csv # sample applicants for the dashboard
| Endpoint | Method | Purpose |
|---|---|---|
/predict |
POST | Returns verdict, probability, risk level, and top SHAP factors for an applicant |
/explain |
POST | Returns a plain-language explanation of a prediction |
/ask |
POST | Answers a follow-up question, grounded in a given prediction's context |
/api/dice |
POST | Generates verified counterfactual scenarios for a rejected applicant |
git clone https://github.com/abhishek9paul/LoanShap.gitcd backend
pip install -r requirements.txtCreate a .env file in backend/ with:
GROQ_API_KEY=your_key_here
Run:
uvicorn app:app --reloadAPI docs available at http://127.0.0.1:8000/docs.
cd frontend
npm install
npm run devSet VITE_API_BASE in a .env file if the backend isn't running on localhost:8000.
Trained on the Loan Approval Classification dataset (Kaggle) - 45,000 records with applicant demographics, loan details, and credit history.
Most credit-scoring models are black boxes - an applicant or reviewer gets a yes/no with no reasoning. LoanShap closes that gap: every decision is backed by real attribution data, every explanation is grounded in that data, and every "what would it take to get approved" answer is verified against the actual model rather than guessed.