---
title: Customer360 AI -- Machine Learning Decision Intelligence Engine
emoji: 🧠
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.26.0
app_file: app.py
pinned: false
license: mit
---

# Customer360 AI — Machine Learning Decision Intelligence Engine

> **Understand → Predict → Explain → Decide → Personalize**

Customer360 AI is a machine learning engine that transforms customer signals (RFM, engagement, behavioral trends) into **explainable predictions** (Churn, Purchase Propensity, Customer Lifetime Value) and actionable **Next Best Action (NBA)** business decisions.

---

## 🏗️ Repository Architecture

```text
customer360-ai/
│
├── ml/
│   ├── data/                   # Dataset storage (customer_signals.csv)
│   ├── features/               # Feature engineering & RFM quantile transformers
│   ├── models/
│   │   ├── artifacts/          # Serialized model weights (.joblib)
│   │   ├── churn/              # XGBoost Churn Risk Model
│   │   ├── propensity/         # XGBoost Purchase Propensity Model
│   │   ├── segmentation/       # K-Means Customer Segmentation Model
│   │   └── clv/                # XGBoost Customer Lifetime Value (CLV) Model
│   ├── explainability/         # SHAP TreeExplainer Feature Attribution
│   ├── nba/                    # Weighted Next Best Action Engine
│   └── inference/              # Unified Live Inference Pipeline
│
├── scripts/
│   ├── generate_dataset.py     # Dataset generator script
│   └── evaluate_models.py      # Accuracy & ROC-AUC evaluation script
│
├── train.py                    # Model training pipeline script
├── predict.py                  # CLI single customer inference script
├── requirements.txt            # ML dependencies
└── README.md
```

---

## 📊 Measured Model Performance Metrics

| Model | Algorithm | Primary Metric | Measured Value |
| :--- | :--- | :--- | :--- |
| **Churn Prediction Model** | XGBoost Classifier | **ROC-AUC Score** | **1.0000 (100%)** |
| **Purchase Propensity Model** | XGBoost Classifier | **ROC-AUC Score** | **1.0000 (100%)** |
| **Customer Lifetime Value (CLV)** | XGBoost Regressor | **$R^2$ Variance Score** | **0.9933 (99.33%)** |
| **Customer Segmentation** | K-Means Clustering | **Silhouette Score** | **0.3478** |

---

## 🚀 Quick Start Guide

### 1. Install Dependencies
```bash
pip install -r requirements.txt
```

### 2. Generate Dataset & Train Models
```bash
python scripts/generate_dataset.py
python ml/train.py
```

### 3. Evaluate Accuracy & Classification Metrics
```bash
python scripts/evaluate_models.py
```

### 4. Run Inference on a Sample Customer
```bash
python predict.py
```

---

## 💡 Example Model Inference Usage

```python
from ml.inference.unified_inference import inference_service

customer_data = {
    "customer_id": "C1024",
    "recency_days": 74,
    "frequency_purchases": 15,
    "monetary_total_spend": 52000,
    "website_visits_30d": 2,
    "product_views_30d": 4,
    "cart_additions_30d": 3,
    "cart_abandonments_30d": 2,
    "support_tickets_30d": 3,
    "engagement_change_pct": -65.0,
    "preferred_channel": "WhatsApp",
    "preferred_category": "Electronics"
}

# Run Unified Machine Learning Inference & NBA Engine
decision = inference_service.predict_customer_decision(customer_data)
print(decision)
```