Credit-Risk-Modeling

🛡️ FinRisk AI: Multi-Agent Credit Risk & Financial Intelligence Suite

Python 3.10+ LangGraph LightGBM Regulatory Compliance License: Proprietary

An End-to-End Enterprise Underwriting System featuring 5 Collaborative Multi-Agent Working Layers, LangGraph State Orchestration, Regulatory RAG, Basel III/IV Expected Loss Quantification, and CCAR Macroeconomic Stress Testing.

Executive Summary

Modern bank-standard credit underwriting cannot rely on black-box ML models alone. Global banking regulations (Basel III/IV IRB Accords, ECOA Regulation B - 12 CFR § 1002.9, and FCRA § 615) mandate continuous policy reconciliation, auditable explainability (SHAP), disparate impact fairness checks, and macro shock resilience.

FinRisk AI re-architects loan evaluation by replacing monolithic scoring scripts with a collaborative 5-layer autonomous agent committee. Each agent layer specializes in a discrete pillar of credit risk analysis, collaborating through a typed LangGraph StateGraph to produce auditable, executive-grade Credit Memorandums.

Multi-Agent Working Layers Architecture

graph TD
    Start([Applicant Profile Ingestion]) --> L1[Layer 1: Identity & KYC Anomaly Agent]
    L1 -->|Validated Profile & Anomaly Score| L2[Layer 2: Quantitative ML & Risk Agent]
    L2 -->|Calibrated PD, EL & SHAP Values| L3[Layer 3: Regulatory RAG & Policy Retrieval Agent]
    L3 -->|Policy Gates & Statutory Citations| L4[Layer 4: Fair Lending & Macro Stress Agent]
    L4 -->|Four-Fifths AIR & CCAR Shock Multipliers| L5[Layer 5: Senior Credit Committee Orchestrator]
    L5 --> Finish([Executive Credit Memorandum & Dossier])

    subgraph "Knowledge Base & Policy RAG"
        KB1[(Basel III/IV IRB Accords)]
        KB2[(12 CFR § 1002.9 Regulation B)]
        KB3[(Institutional Underwriting Manual)]
        KB4[(Federal Reserve CCAR Framework)]
    end

    L3 -.->|Semantic Search & Retrieval| KB1
    L3 -.->|Statutory Mandates| KB2
    L3 -.->|Tier Limits & DTI Cutoffs| KB3
    L3 -.->|Stress Multipliers| KB4

The 5 Autonomous Agent Layers

  1. Layer 1: KYC, Identity & Data Anomaly Agent (kyc_fraud_agent)
    • Audits borrower data for consistency, anomalous debt spikes, unverified income ratios, and synthetic identity indicators.
  2. Layer 2: Quantitative ML Risk Modeling Agent (quantitative_risk_agent)
    • Executes the LightGBM default prediction model, produces calibrated Probability of Default ($PD$), computes Basel Expected Loss ($EL = PD \times EAD \times LGD$), and maps borrower ratings to institutional credit tiers (AAA through Subprime).
  3. Layer 3: Regulatory RAG & Policy Retrieval Agent (policy_rag_agent)
    • Interrogates the banking knowledge base using a lexical & semantic RAG retriever. Fetches exact legal citations for adverse action disclosures (12 CFR § 1002.9) and checks hard underwriting gates (DTI ceilings, minimum credit scores).
  4. Layer 4: Fair Lending Auditor & Stress Testing Agent (fairness_stress_agent)
    • Audits Disparate Impact across cohorts using the Four-Fifths (80%) Rule ($AIR \ge 0.80$). Simulates CCAR Severely Adverse macroeconomic shocks (+300 bps interest rate spike, 10% peak unemployment).
  5. Layer 5: Senior Credit Committee Orchestrator (credit_committee_agent)
    • Synthesizes findings from all prior layers, establishes Risk-Adjusted Return on Capital (RAROC) APR pricing, constructs actionable counterfactual advice, and drafts a comprehensive Credit Memorandum.

Key Technical Innovations

Quickstart Guide

1. Set Up Virtual Environment & Dependencies

# Clone the repository
git clone https://github.com/niraj987/Credit-Risk-Modeling.git
cd Credit-Risk-Modeling

# Create & activate virtual environment
python -m venv .venv
# On Windows:
.\.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Full-Stack End-to-End Production Mode (React + TypeScript + Tailwind CSS + Three.js + FastAPI + SQLite WAL)

Start the FastAPI Backend Server

# Start backend API on port 8000
python -m uvicorn backend.main:app --reload --port 8000

Start the React Frontend Web Application

cd frontend
npm install
npm run dev

Navigate to http://localhost:5173 to explore the 3D Physical Glass Risk Manifold, live multi-agent telemetry, interactive loan calculator, RAG pop-up tiles, and the Enterprise SQLite WAL & IndexedDB Dual-Sync Database Hub.

🗄️ Enterprise Database Architecture

This platform deploys a resilient Dual-Sync Database Architecture engineered for institutional credit underwriting:

🌿 Natural Taste & Biophilic FinTech Design

Enterprise Database Architecture

This platform deploys a resilient Dual-Sync Database Architecture engineered for institutional credit underwriting:

Natural Taste & Biophilic FinTech Design

1-Click Cloud Deployment (Vercel & Render)

Deploying the Frontend to Vercel

  1. Import this repository into Vercel.
  2. Set the Root Directory to ./ (Vercel automatically detects vercel.json).
  3. (Optional) Set VITE_API_URL environment variable pointing to your deployed FastAPI backend.
  4. Click Deploy!

Deploying the Backend to Render

  1. Create a new Web Service on Render linking this repository.
  2. Select Python runtime (or apply render.yaml blueprint).
  3. Set Build Command: pip install -r backend/requirements.txt
  4. Set Start Command: uvicorn backend.main:app --host 0.0.0.0 --port $PORT
  5. Click Create Web Service!

3. Streamlit Dashboard Mode (Alternative Quick Demo)

streamlit run app.py

Navigate to http://localhost:8501.

4. Run via Command Line Interface (CLI)

# Run multi-agent underwriting on an applicant profile
python -m credit_agents.cli run --score 710 --income 85000 --loan 20000 --dti 0.28

# Search the regulatory RAG policy knowledge base
python -m credit_agents.cli rag "What are the adverse action notice requirements under ECOA?"

# Train or retrain the LightGBM credit default model
python -m credit_agents.cli train

5. Run the Test Suite

pytest tests/ -v

Mathematical Foundations

Basel Expected Loss ($EL$)

\(\text{Expected Loss (EL)} = \text{PD} \times \text{EAD} \times \text{LGD}\)

Fair Lending Adverse Impact Ratio ($AIR$)

\(\text{Adverse Impact Ratio (AIR)} = \frac{\text{Approval Rate}_{\text{Protected Cohort}}}{\text{Approval Rate}_{\text{Reference Cohort}}} \ge 0.80\)

Enterprise Highlights for Technical Evaluation

📄 License & Proprietary Copyright

Copyright © 2026 FinRisk AI. All Rights Reserved. This project, software, and codebase is strictly proprietary and confidential. Unauthorized copying, cloning, reverse engineering, redistribution, or modification of this code and platform is strictly prohibited. See the LICENSE file for legal details.

This site is open source. Improve this page.