Skip to content

ImdataScientistSachin/Bias-Drift-Detector

BranchesTags

Repository files navigation

🛡️ Bias Drift Guardian

Real-time AI Fairness & Data Drift Monitoring System

Python Streamlit FastAPI License: MIT Code style: black Last Commit Maintained GitHub stars GitHub forks

🚀 Live Demo • 📚 Documentation • 🌐 API Docs • 💼 LinkedIn • 🐛 Report Bug

Status Updated

🎯 Detect bias before it becomes a lawsuit. Monitor drift before it breaks your model.

📋 Executive Summary

Bias Drift Guardian is a production-ready dashboard and API for real-time bias and drift detection in machine learning models. Built with Streamlit + FastAPI, it ensures compliance with EEOC/EU AI Act regulations and explains root causes with SHAP.

Key Highlights:

  • ⚡ Deploy in 30 seconds - Standalone Streamlit dashboard with pre-loaded demo
  • 📚 Multi-Dataset Support - Switch instantly between German Credit, Adult Census, and COMPAS Recidivism
  • 🎯 Unique Feature - Intersectional bias detection (not available in standard tools)
  • 📊 Comprehensive Monitoring - Drift detection (PSI, KS, Chi-square) + Fairness metrics
  • 🔍 Root Cause Analysis - SHAP-based explanations for model behavior changes
  • 🚀 Production-Ready - FastAPI backend with persistence, Docker support, live deployment
  • 🛡️ Robust Safety Net - Auto-fallback mock data generation (never crashes on missing files)
  • 📚 Actively Maintained - 2,800+ lines of documentation, open-source (MIT), updated December 2025

🎯 Perfect for: ML Engineers • Data Scientists • Compliance Teams • AI Ethics Researchers

📸 Dashboard Preview

Bias Drift Guardian Dashboard

Interactive dashboard showing drift alerts, fairness metrics, and intersectional bias analysis

📖 Table of Contents

🌟 Why Bias Drift Guardian?

The Problem:

  • 🚨 80% of AI models experience performance degradation in production due to data drift
  • ⚖️ $1M+ lawsuits from algorithmic discrimination are becoming common
  • 🔍 Hidden bias in intersectional groups (e.g., "Female employees 50+") goes undetected by standard tools

The Solution: Bias Drift Guardian is a production-ready monitoring system that combines:

  • ✅ Data Drift Detection - Catch distribution shifts before they break your model
  • ✅ Fairness Analysis - Ensure compliance with EEOC and EU AI Act
  • ✅ Intersectional Bias Detection - Unique feature that catches compound discrimination
  • ✅ Root Cause Analysis - SHAP-based explanations for why drift is happening
  • ✅ Counterfactual "What-If" Analysis - Generate actionable, minimal changes to flip model predictions (e.g., "Increase income by $5k to get approved")

✨ Key Features

🎯 Intersectional Fairness Analysis ⭐ UNIQUE

What makes us different: Most fairness tools only check one attribute at a time (gender OR age). We detect compound bias affecting specific subgroups.

Example:

Standard Analysis: "No gender bias" ✅ (Male: 70%, Female: 68%)
Our Analysis: "Female employees aged 50+ have only 38% approval rate!" ❌

Why it matters:

  • 📋 EEOC compliance requirement
  • 💼 Prevents discrimination lawsuits
  • 🎓 Not available in standard Fairlearn

📊 Comprehensive Drift Detection

  • PSI (Population Stability Index) - Industry standard for numerical features
  • KS Test - Statistical distribution comparison
  • Chi-square Test - Categorical feature drift

Thresholds:

  • PSI < 0.1: ✅ No drift
  • PSI 0.1-0.25: ⚠️ Monitor closely
  • PSI > 0.25: ❌ Action required

🔍 Root Cause Analysis

SHAP-based feature importance drift detection:

Root Cause Analysis:
- age: Importance increased by 0.0847 (0.1234 → 0.2081)
- credit_amount: Decreased by 0.0423
Recommendation: Investigate data distribution changes

🔮 Counterfactual Explanations ("What-If" Analysis)

Go beyond "Why?" to "How to fix it?"

  • Actionable Insights: "If this applicant increases savings by 10%, they would be approved."
  • Constraint-Aware: Respects real-world constraints (e.g., Age cannot decrease, Race is immutable).
  • L0/L1 Optimization: Suggests the fewest possible changes to achieve the desired outcome.
  • EEOC Compliance: Includes a sticky disclaimer and "Rejected Plans" toggle for full auditability.

🌊 Interactive Drift Simulation

Educational tool to visualize how distribution shifts affect model performance in real-time.

📈 Model Performance Monitoring

  • Confusion Matrix visualization
  • Accuracy, Precision, Recall, F1-Score
  • Error breakdown and actionable insights

📚 Dynamic Data Hub (New!)

  • Multi-Dataset Selector: Switch context instantly regardless of current state.
    • 💳 German Credit: Financial compliance demo
    • 👔 Adult Income: Census-based hiring fairness
    • ⚖️ COMPAS: Criminal justice recidivism (with audit logging)
  • Robust Loader: "Missing File" protection with auto-generated mock data for rock-solid demos.
  • Promise-First Onboarding: "Bias Gap in 15s" frictionless startup flow.

🚀 Quick Start

Option 1: Standalone Dashboard (30 seconds)

Perfect for demos and portfolio showcases.

# Clone repository
git clone https://github.com/ImdataScientistSachin/Bias-Drift-Detector.git
cd Bias-Drift-Detector

# Install dependencies
pip install -r requirements.txt

# Run dashboard
streamlit run dashboard/app.py

Access: http://localhost:8501

Option 2: Full Stack (5 minutes)

For production deployment with API backend.

# Install all dependencies
pip install -r requirements-full.txt

# Terminal 1: Start API
uvicorn api.main:app --reload

# Terminal 2: Start Dashboard
streamlit run dashboard/app.py

Access:

Option 3: Docker (Production)

docker-compose up -d

📊 Demo & Screenshots

🎬 Live Demo

Try it now: https://bias-drift-guardian.streamlit.app/

📸 Screenshots

📊 Dashboard Overview

Top Metrics Cards

  • Total Predictions: 150
  • Fairness Score: 60/100
  • Drift Alerts: 4
  • Average Drift Score: 0.18
🌊 Interactive Drift Simulation

Visualize how data distribution changes affect your model with real-time KS-test calculations.

🎯 Intersectional Bias Analysis

Worst-Performing Groups:

  1. Female_50+ → 38% approval (Disparity: 0.48 ❌)
  2. Female_40-50 → 52% approval (Disparity: 0.65 ⚠️)
  3. Male_50+ → 58% approval (Disparity: 0.73 ⚠️)

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    BIAS DRIFT GUARDIAN                      │
└─────────────────────────────────────────────────────────────┘

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   STREAMLIT      │     │   FASTAPI        │     │   CORE ENGINE    │
│   DASHBOARD      │────▶│   API            │────▶│   (Analytics)    │
│                  │     │                  │     │                  │
│ • Visualizations │     │ • REST Endpoints │     │ • Drift Detector │
│ • Metrics Cards  │     │ • Persistence    │     │ • Bias Analyzer  │
│ • Simulations    │     │ • Background     │     │ • Intersectional │
│                  │     │   Tasks          │     │ • Root Cause     │
└──────────────────┘     └──────────────────┘     └──────────────────┘

Tech Stack

Layer Technology Purpose
Frontend Streamlit Interactive dashboard
Backend FastAPI REST API with async support
Analytics Fairlearn, SHAP Fairness metrics & explainability
Data Pandas, NumPy Data processing
Visualization Plotly, Seaborn Interactive charts
Statistics SciPy, Scikit-learn Statistical tests

💼 Use Cases

🏦 Financial Services

Scenario: Credit scoring model monitoring

  • Monitor for age/gender bias in loan approvals
  • Detect drift in applicant demographics
  • EEOC compliance reporting
  • Prevent discrimination lawsuits

👔 HR & Recruiting

Scenario: Hiring algorithm fairness

  • Intersectional bias detection (race × gender × age)
  • Resume screening fairness analysis
  • Legal risk mitigation
  • Diversity & inclusion metrics

🏥 Healthcare

Scenario: Treatment recommendation systems

  • Ensure equal treatment across demographics
  • Monitor for patient population changes
  • Regulatory compliance (HIPAA, GDPR)
  • Ethical AI deployment

🛒 E-commerce

Scenario: Recommendation systems

  • Prevent filter bubbles
  • Ensure fair product exposure
  • Monitor for seasonal drift
  • A/B testing fairness

📚 Documentation

📖 Core Documentation

🎓 Guides

📊 Project Info

🛠️ Installation

Prerequisites

  • Python 3.9 or higher
  • pip package manager
  • Git

Dependencies

Dashboard Only (~30MB):

pip install -r requirements.txt

Full Stack (~150MB):

pip install -r requirements-full.txt

Key Packages:

  • streamlit - Dashboard framework
  • fastapi - API framework (full stack only)
  • fairlearn - Fairness metrics (full stack only)
  • shap - Explainability (full stack only)
  • pandas, numpy - Data processing
  • plotly, seaborn - Visualizations
  • scipy, scikit-learn - Statistical tests

🎓 Usage Examples

Example 1: Drift Detection

from core.drift_detector import DriftDetector
import pandas as pd

# Initialize detector with baseline data
detector = DriftDetector(
    baseline_data=train_df,
    numerical_features=['age', 'credit_amount', 'duration'],
    categorical_features=['job', 'housing', 'purpose']
)

# Detect drift in production data
drift_results = detector.detect_feature_drift(production_df)

# Check for alerts
alerts = drift_results[drift_results['alert'] == True]
print(f"Drift detected in {len(alerts)} features:")
for _, row in alerts.iterrows():
    print(f"  - {row['feature']}: PSI={row['psi']:.3f}")

Example 2: Bias Analysis

from core.bias_analyzer import BiasAnalyzer

# Initialize analyzer
analyzer = BiasAnalyzer(sensitive_attrs=['Sex', 'Age_Group'])

# Calculate fairness metrics
metrics = analyzer.calculate_bias_metrics(
    y_true=true_labels,
    y_pred=predictions,
    sensitive_features=sensitive_df
)

# Check fairness score
print(f"Fairness Score: {metrics['fairness_score']}/100")

# Check disparate impact
for attr in ['Sex', 'Age_Group']:
    di = metrics[attr]['disparate_impact']
    status = "✅ PASS" if di >= 0.8 else "❌ FAIL"
    print(f"{attr} Disparate Impact: {di:.3f} {status}")

Example 3: Intersectional Analysis

from core.intersectional_analyzer import IntersectionalAnalyzer

# Initialize analyzer
analyzer = IntersectionalAnalyzer(
    sensitive_attrs=['Sex', 'Age_Group', 'Race']
)

# Analyze intersectional bias
results = analyzer.analyze_intersectional_bias(
    y_pred=predictions,
    sensitive_features=sensitive_df,
    min_group_size=10
)

# Get worst-performing groups
leaderboard = analyzer.get_intersectional_leaderboard(
    y_pred=predictions,
    sensitive_features=sensitive_df
)

print("Worst-Performing Groups:")
for group in leaderboard[:5]:
    print(f"  {group['group']}: {group['selection_rate']:.1%} "
          f"(Disparity: {group['disparity_ratio']:.2f})")

Example 4: API Integration

import requests

# Register model
response = requests.post("http://localhost:8000/api/v1/models/register", json={
    "model_id": "credit_model_v1",
    "numerical_features": ["age", "credit_amount"],
    "categorical_features": ["job", "housing"],
    "sensitive_attributes": ["Sex", "Age_Group"],
    "baseline_data": baseline_records
})

# Log prediction
requests.post("http://localhost:8000/api/v1/predictions/log", json={
    "model_id": "credit_model_v1",
    "features": {"age": 35, "credit_amount": 5000, "job": "skilled"},
    "prediction": 1,
    "sensitive_features": {"Sex": "Female", "Age_Group": "30-40"}
})

# Get metrics
metrics = requests.get("http://localhost:8000/api/v1/metrics/credit_model_v1").json()
print(f"Drift Alerts: {len([d for d in metrics['drift_analysis'] if d['alert']])}")
print(f"Fairness Score: {metrics['bias_analysis']['fairness_score']}")

Example 5: Run Complete Demos

We provide 3 ready-to-run examples demonstrating real-world use cases:

📊 German Credit Demo

Use Case: Credit risk analysis with fairness monitoring

python examples/german_credit_demo.py

What it does:

  • Loads German Credit dataset (1,000 samples)
  • Trains RandomForest classifier
  • Registers model with API
  • Simulates drift by shifting age distribution
  • Logs 150 predictions
  • Analyzes drift and bias

Expected Output:

Drift Alerts: 2 (age, savings_status)
Fairness Score: 60/100
Sex Disparate Impact: 0.75 ❌ FAIL

File: examples/german_credit_demo.py

👥 Adult Census Demo

Use Case: Income prediction fairness analysis

python examples/adult_demo.py

What it does:

  • Analyzes Adult Census dataset
  • Detects intersectional bias (race × gender × age)
  • Monitors for demographic drift

File: examples/adult_demo.py

🌐 Live API Client

Use Case: API integration example

python examples/live_demo_client.py

What it does:

  • Demonstrates API endpoints
  • Shows model registration
  • Logs predictions
  • Retrieves metrics

File: examples/live_demo_client.py

💡 Tip: Start with german_credit_demo.py for a complete end-to-end example!

🌐 API Reference

Endpoints

1. Register Model

POST /api/v1/models/register

Request Body:

{
  "model_id": "my_model_v1",
  "numerical_features": ["age", "income"],
  "categorical_features": ["job", "education"],
  "sensitive_attributes": ["Sex", "Race"],
  "baseline_data": [...]
}

2. Log Prediction

POST /api/v1/predictions/log

Request Body:

{
  "model_id": "my_model_v1",
  "features": {"age": 35, "income": 50000},
  "prediction": 1,
  "true_label": 1,
  "sensitive_features": {"Sex": "Female", "Race": "Asian"}
}

3. Get Metrics

GET /api/v1/metrics/{model_id}

Response:

{
  "model_id": "my_model_v1",
  "total_predictions": 150,
  "drift_analysis": [...],
  "bias_analysis": {...},
  "root_cause_report": "..."
}

4. List Models

GET /api/v1/models

5. Health Check

GET /api/v1/health

Full API Documentation: http://localhost:8000/docs (when API is running)

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch 
    git checkout -b feature/AmazingFeature
  3. Commit your changes 
    git commit -m 'Add AmazingFeature'
  4. Push to the branch 
    git push origin feature/AmazingFeature
  5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/Bias-Drift-Detector.git
cd Bias-Drift-Detector

# Install dev dependencies
pip install -r requirements-full.txt
pip install pytest pytest-asyncio black flake8

# Run tests (when available)
pytest tests/

# Format code
black .

# Lint code
flake8 .

Code Style

  • Follow PEP 8
  • Use Black for formatting
  • Add docstrings to all functions
  • Include type hints where possible

🗺️ Roadmap

✅ Completed Features

Click to see all 9 completed features
  • ✅ Core drift detection (PSI, KS, Chi-square)
  • ✅ Fairness analysis (Disparate Impact, Demographic Parity, Equalized Odds)
  • ✅ Intersectional bias detection ⭐ Unique feature
  • ✅ Root cause analysis (SHAP-based explanations)
  • ✅ Standalone Streamlit demo (works without backend)
  • ✅ FastAPI backend with persistence layer
  • ✅ Comprehensive documentation (2,800+ lines)
  • ✅ Docker support (docker-compose ready)
  • ✅ Streamlit Cloud deployment (live demo available)

🚧 In Progress

  • ⏳ Unit tests (target: 80% coverage)
  • ⏳ CI/CD pipeline (GitHub Actions)
  • ⏳ Performance optimizations

📋 Planned Features

  • 📅 Time-series drift tracking
  • 📧 Automated alerting (email/Slack)
  • 📊 Model comparison features
  • 🗄️ PostgreSQL integration
  • ⚡ Redis caching
  • ☸️ Kubernetes deployment guide
  • 🌍 Multi-language support
  • 🔌 Custom metric plugins

❓ FAQ

Can I deploy this commercially?

Yes! This project is MIT licensed. You can use it commercially with attribution. Perfect for:

  • Enterprise ML monitoring
  • SaaS products
  • Consulting projects
  • Internal tools
Is this GDPR compliant?

The system doesn't store sensitive data by default. For GDPR compliance:

  • ✅ Data is processed in-memory
  • ✅ No PII stored without configuration
  • ⚠️ Implement data anonymization for production
  • ⚠️ Configure retention policies as needed
Can I use this with my own dataset?

Yes! The system is model-agnostic. Just register your model with baseline data and start logging predictions.

What models are supported?

Any scikit-learn compatible model. For SHAP analysis: RandomForest, XGBoost, LightGBM, and Linear models work best.

How much data do I need?

Minimum 500 samples for baseline. For production monitoring, analyze every 100-1000 predictions depending on risk level.

How does intersectional analysis differ from standard bias analysis?

Standard analysis checks one attribute at a time (e.g., gender OR age). Intersectional analysis checks combinations (e.g., "Female employees aged 50+"), catching compound discrimination that single-attribute analysis misses.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use this project in your research or work, please cite:

@software{bias_drift_guardian,
  author = {Sachin Paunikar},
  title = {Bias Drift Guardian: Real-time AI Fairness and Data Drift Monitoring},
  year = {2025},
  url = {https://github.com/ImdataScientistSachin/Bias-Drift-Detector}
}

🙏 Acknowledgments

  • Fairlearn - Microsoft's fairness toolkit
  • DiCE - Diverse Counterfactual Explanations
  • SHAP - Lundberg & Lee's explainability framework
  • Streamlit - Amazing dashboard framework
  • FastAPI - Modern Python web framework
  • UCI ML Repository - German Credit & Adult Census datasets

Inspiration

This project was inspired by the need for accessible, production-ready fairness monitoring tools in the ML community and the growing importance of ethical AI deployment.

📞 Contact

Sachin Paunikar

⭐ Star History

If you find this project useful, please consider giving it a star! It helps others discover the project.

Star History Chart

Made with ❤️ for Ethical AI

⬆ Back to Top

About

No description or website provided.

Topics

data-science responsible-ai streamlit ethical-ai ml-fairness

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages