Customer Segmentation

Inspiration

Most marketing teams manually segment customers or rely on expensive third-party tools. We wanted to build a lightweight, reproducible ML pipeline that automatically identifies customer personas from behavioral data, enabling data-driven segmentation at scale.

What it does

Clusters customers into 5 distinct personas based on 10 engineered features (spend patterns, purchase frequency, channel preference, tenure, recency). Each cluster is profiled with campaign response and spending metrics, mapped to actionable marketing recommendations. Includes production-ready prediction tools for scoring new customers.

How we built it

Data pipeline: Cleaned raw data, engineered behavioral features (spend ratios, customer tenure, recency), split into leakage-safe train/val/test
Model selection: Evaluated k=2 to k=10 using elbow method + silhouette analysis; chose k=4 for optimal interpretability
Stability validation: Verified cluster assignments and silhouette scores remain consistent across splits (not overfitting artifacts)
Profiling: Analyzed each cluster's campaign response, spending behavior, and demographics to build personas
Inference layer: Built 4 command-line tools (test_single.py, predict_demo.py, loader.py, probe.py) for easy model deployment

Challenges we ran into

Leakage prevention: Ensuring all data-dependent statistics (scaling, imputation, outlier filtering) were computed only on train set and applied to val/test
Feature engineering: Balancing feature count (avoiding curse of dimensionality) while capturing meaningful customer behavior
Model selection: Deciding between high silhouette (k=2) and actionable segmentation (k=5)

Accomplishments that we're proud of

Fully reproducible pipeline—one command generates splits, one notebook retrains the model
Stable, interpretable clusters that generalize across train/val/test
Clean, production-ready prediction interface with multiple access patterns
Comprehensive documentation and profiling output for marketing teams

What we learned

Unsupervised learning requires different validation approaches than supervised tasks (no labels to compare against)
Silhouette scores alone don't guarantee actionable clusters—business context matters
Leakage-safe pipelines are just as critical for clustering as for predictive modeling

What's next

Real-time scoring API: Deploy model as FastAPI endpoint for live customer scoring
Feature importance analysis: Identify which features drive each persona
Automated retraining: Set up pipeline to retrain monthly with new customer data
Extended personas: Expand from 5 to hierarchical clustering for fine-grained segmentation