Add comprehensive AI Explainability features for customer churn prediction hackathon

[Copilot]

Overview

This PR transforms the ChubbChurns repository into a complete AI Explainability hackathon project focused on customer churn prediction in the insurance industry. The implementation demonstrates state-of-the-art explainability techniques using SHAP and LIME to make machine learning predictions interpretable and actionable.

What is AI Explainability?

AI Explainability (XAI) makes machine learning model decisions understandable to humans. This is crucial for:

• Building Trust: Understanding why a model predicts a customer will churn
• Regulatory Compliance: Providing transparent explanations for business decisions
• Model Validation: Ensuring models use appropriate features and logic
• Business Insights: Discovering actionable patterns in customer behavior

Key Features Added

🤖 Machine Learning Models

• Multiple Model Types: Random Forest, Gradient Boosting, and Logistic Regression classifiers
• Comprehensive Evaluation: Accuracy, precision, recall, F1-score, and ROC-AUC metrics
• Model Persistence: Save and load trained models for reuse
• Feature Importance: Extract and visualize feature importance scores

🔍 AI Explainability Implementations

SHAP (SHapley Additive exPlanations)

• Tree, Kernel, and Linear explainer support for different model types
• Global feature importance via summary plots
• Individual prediction explanations with waterfall plots
• Force plots showing feature contribution dynamics

LIME (Local Interpretable Model-agnostic Explanations)

• Instance-level prediction explanations
• Local surrogate model approximations
• Feature contribution analysis
• Easy-to-understand visualizations for stakeholders

📊 Data Processing Pipeline

• Synthetic customer churn data generation with realistic features:
  • Demographics (age, tenure)
  • Account information (monthly charges, total charges)
  • Service features (products, online service, tech support)
  • Interaction metrics (customer service calls, claims)
• Automated preprocessing with feature scaling
• Stratified train/test splitting

📚 Documentation & Examples

Documentation Files

• README.md: Comprehensive project overview and concepts
• QUICKSTART.md: Installation and usage guide for immediate hands-on
• CONTRIBUTING.md: Guidelines for hackathon participants
• LICENSE: MIT License for open collaboration

Interactive Examples

• example.py: Complete end-to-end demonstration script
• notebooks/AI_Explainability_Demo.ipynb: Interactive Jupyter notebook with detailed explanations and visualizations

Project Structure

ChubbChurns/
├── src/
│   ├── data_processing.py    # Data generation and preprocessing utilities
│   ├── model.py              # Churn prediction models with evaluation
│   ├── explainability.py     # SHAP and LIME implementations
│   └── __init__.py           # Package initialization
├── notebooks/
│   └── AI_Explainability_Demo.ipynb  # Interactive tutorial
├── data/                     # Dataset directory with documentation
├── models/                   # Trained models directory
├── visualizations/           # Generated explanation plots
├── example.py                # Quick start demo script
├── requirements.txt          # Python dependencies
└── [documentation files]

Quick Start

# Install dependencies
pip install -r requirements.txt

# Run the demo
python example.py

This will:

1. Generate synthetic customer data (1000 samples)
2. Train a Random Forest churn prediction model
3. Generate SHAP explanations showing global feature importance
4. Create LIME explanations for individual predictions
5. Save visualizations to the visualizations/ directory

Use Cases Demonstrated

• Customer Retention: Identify at-risk customers and understand the drivers of churn
• Model Debugging: Validate that models use appropriate features aligned with business logic
• Stakeholder Communication: Present clear, visual explanations of predictions to non-technical teams
• Compliance: Provide auditable, transparent explanations for regulatory requirements

Technical Highlights

• ~1,000 lines of production-quality Python code
• Modular architecture enabling easy extension and customization
• Multiple visualization types for different explanation needs
• Comprehensive error handling and input validation
• Professional documentation suitable for hackathon presentation

This implementation provides everything needed for a successful AI Explainability hackathon demonstration, combining technical depth with practical business value.

Original prompt

This is a repository for hackathon which is based on AI Explainability .

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.