README.md

metadata

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

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

pip install -r requirements.txt

2. Generate Dataset & Train Models

python scripts/generate_dataset.py
python ml/train.py

3. Evaluate Accuracy & Classification Metrics

python scripts/evaluate_models.py

4. Run Inference on a Sample Customer

python predict.py

---

💡 Example Model Inference Usage

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)