Tosa9/customer-segmentation-app

🛍️ Customer Segmentation — K-Means Clustering

Group 9 | TechCrush AI/ML Programme

A deployed machine learning web app that segments mall customers into 5 distinct groups using K-Means clustering, built on the Mall Customer Segmentation dataset from Kaggle.

🚀 Live App

Deployed on Streamlit Cloud — [Add your link here after deployment]

📁 Repository Structure

customer-segmentation-app/
│
├── app.py                      ← Streamlit web application
├── kmeans_primary_model.pkl    ← Trained K-Means model (from notebook Section 11)
├── scaler_2d.pkl               ← Fitted StandardScaler (from notebook Section 11)
├── Mall_Customers.csv          ← Source dataset (from Kaggle)
├── requirements.txt            ← Python dependencies for Streamlit Cloud
└── README.md                   ← This file

🧠 What the App Does

The app has two tabs:

Tab 1 — Segment Predictor Enter a customer's Annual Income and Spending Score using sliders. The trained K-Means model instantly classifies them into one of 5 segments with a profile description and a recommended business action.

Tab 2 — Cluster Visualisations Displays all major plots from the project notebook:

• —Hero cluster scatter plot (Income vs Spending Score)
• —Elbow method and Silhouette Score (how we chose k=5)
• —Per-sample silhouette coefficients
• —Cluster size distribution
• —Feature box plots per cluster
• —Radar chart (multi-feature cluster comparison)
• —Segment profile table with business actions
• —PCA projection of the extended 4-feature model
• —Correlation heatmap (EDA)

🏷️ The 5 Customer Segments

🛠️ Local Setup

# Clone the repo
git clone https://github.com/Tosa9/customer-segmentation-app.git
cd customer-segmentation-app

# Install dependencies
pip install -r requirements.txt

# Run the app
streamlit run app.py

📦 Generating the Model Files

The .pkl files are generated by running the full project notebook:

1. 1.Open Group_9_Customer_Segmentation_Project.ipynb in Google Colab
2. 2.Upload Mall_Customers.csv when prompted in Section 0
3. 3.Run all cells through to Section 11
4. 4.Download kmeans_primary_model.pkl and scaler_2d.pkl from the Colab file browser
5. 5.Place them in this repo directory

📊 Dataset

Mall Customer Segmentation Dataset Source: Kaggle — vjchoudhary7 Records: 200 customers | Features: CustomerID, Gender, Age, Annual Income (k$), Spending Score (1-100)

🔬 Tech Stack

• —Python 3.10+
• —scikit-learn — KMeans, StandardScaler, PCA, metrics
• —Streamlit — Web app framework
• —pandas / numpy — Data manipulation
• —matplotlib / seaborn — Visualisations
• —scipy — Hierarchical clustering (dendrogram)
• —joblib — Model persistence

Group 9 | TechCrush AI/ML Programme