A professional-grade Machine Learning application that segments retail customers based on their purchasing behavior. By analyzing transaction history, this tool identifies distinct customer groups—from high-value VIPs to at-risk churners—enabling businesses to launch targeted marketing campaigns with precision.
- RFM Analysis: Automatically calculates Recency, Frequency, and Monetary value for every customer.
- Smart Clustering: Uses K-Means clustering to group customers with similar behaviors.
- Dynamic Labeling: Intelligently labels clusters (e.g., "💎 Loyal", "
⚠️ At-Risk") based on their statistical profiles, solving the common "label switching" problem in ML. - Interactive Dashboard: A beautiful Streamlit interface to visualize segments, explore data, and export results.
- Business-Ready: Handles real-world retail data issues like cancellations, missing IDs, and returns.
This project is organized for scalability and clarity. Here's a look under the hood:
customer_segmentation/
├── app.py # 🚀 The main Streamlit application entry point
├── requirements.txt # 📦 List of python dependencies
├── data/ # 💾 Folder for storing raw CSV/Excel data
│ └── customer_segmentation.csv (Example data)
├── pipeline/ # ⚙️ The Engine Room: Training & Processing
│ ├── train_model.py # Script to retrain the ML model
│ └── feature_engineering.py # Logic for cleaning & RFM calculation
├── inference/ # 🔮 Prediction Logic
│ └── batch_predictor.py # Class to load model & predict on new data
├── utils/ # 🛠️ Helper Utilities
│ └── io.py # Robust file loading (CSV/Excel)
├── artifacts/ # 🏺 Saved Models (Created after training)
│ ├── kmeans.pkl # Trained K-Means model
│ ├── scaler.pkl # Standard Scaler for normalization
│ └── feature_schema.json # Ensures data consistency
└── notebooks/ # 📓 Jupyter Notebooks for experimentation
Follow these steps to get the project running on your local machine.
Ensure you have Python 3.8+ installed.
Clone the repository and install the required packages:
# Install dependencies
pip install -r requirements.txtThe project comes with a pre-trained model structure, but if you want to retrain it on your own data:
- Place your training data in
data/customer_segmentation.csv. - Run the training pipeline:
python pipeline/train_model.pyThis will generate new model files in the artifacts/ directory.
Launch the interactive dashboard:
streamlit run app.pyThe app will open in your browser at http://localhost:8501.
- Data Ingestion: You upload a transaction file (CSV/Excel) containing
InvoiceNo,StockCode,Quantity,InvoiceDate,UnitPrice, andCustomerID. - Preprocessing: The app cleans the data (removing returns, null IDs) and aggregates it to the customer level.
- Feature Engineering: We calculate 5 core metrics for each customer:
- Recency: Days since last purchase.
- Frequency: Number of unique purchases.
- Monetary: Total money spent.
- Total Quantity: Total items bought.
- Unique Products: Variety of products purchased.
- AI Segmentation: The pre-trained K-Means model groups customers into 4 clusters based on these metrics.
- Insight Generation: The system analyzes the clusters and assigns human-readable labels (e.g., "Recent Low Spenders" vs "High-Value Loyal") so you can take action immediately.
Your input file needs to look something like this:
| InvoiceNo | StockCode | Description | Quantity | InvoiceDate | UnitPrice | CustomerID |
|---|---|---|---|---|---|---|
| 536365 | 85123A | HEART LIGHT HOLDER | 6 | 12/1/2010 8:26 | 2.55 | 17850 |
| 536365 | 71053 | WHITE METAL LANTERN | 6 | 12/1/2010 8:26 | 3.39 | 17850 |
Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.
Built with ❤️ for intelligent retail analytics.