README.md

Explainable Customer Segmentation (GMM + SHAP) — Streamlit App

Pages

• Overview: Explains clustering, GMM, and SHAP and shows cluster profiles (mean luxury/fresh/dry sales per cluster).
  

• Customer Explorer: Select an existing customer or enter spending values to predict the customer’s cluster and view cluster probabilities.
  

• Why This Customer is in This Cluster (XAI): Displays a SHAP waterfall plot and a contributions table explaining which features pushed the customer toward the predicted cluster, plus a simple-language summary.
  

• Global Insights: Shows global SHAP feature importance and a scatter plot (luxury_sales vs dry_sales) colored by cluster.
  

• City Prediction (Probabilistic): Predicts the top 5 most likely outlet cities for a spending pattern and shows a probability bar chart + explanation text.
  

• Customer Anomaly Detection: Checks whether a customer’s spending is anomalous for a selected city using z-scores and explains which features are outside the normal range.
  

Run locally (Windows / PowerShell)

From this folder (/app):

.\run_app.ps1

This will:

1. Create a .venv (if missing)
2. Install dependencies from requirements.txt
3. Launch Streamlit in a browser window

Run manually (alternative)

py -3 -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
.\.venv\Scripts\streamlit run app.py

Notes

• Models are loaded from artifacts/ and data from data/dataset.csv.
• If port 8501 is busy, stop the other Streamlit process or change the port in run_app.ps1.