Customer Segmentation Studio
A train-to-service clustering workflow that turns customer inputs into named segments, with shared preprocessing, saved model artifacts, input warnings, and a browser demo.
What it is
The goal is to make a clustering result readable to someone who does not work in cluster IDs. The service pairs an assignment with a name, description, key drivers, and suggested actions, while surfacing unusual inputs.
The browser demo makes it possible to inspect the same catalog and model metadata served by the API rather than maintaining a separate presentation-only set of labels.
The loop it has to make believable
- 01
Train on a validated dataset, compare candidate clusterings, and inspect the selected segment catalog and saved artifacts.
- 02
Submit a customer or a bounded batch and inspect the assigned segment, explanatory drivers, and input warnings in the demo flow.
How it’s built
The training path validates data, engineers features, scales them, and compares candidate clusterings using several internal signals. The saved bundle includes the exact preprocessing objects and catalog needed to reproduce inference.
FastAPI validates single and batch inputs, caps a batch at 250 customers, and loads the artifact bundle at startup. Confidence is computed from transformed distance to the assigned centroid; it is not calibrated against a labeled correctness outcome.
Architecture
- Data contract
- Required numeric inputs, value bounds, dataset validation, and deterministic engineered features
- Selection
- K-Means candidates ranked using separation, compactness, balance, confidence heuristics, and stability signals
- Bundle
- Model, scaler, feature engineer, catalog, and metadata loaded together for inference
- API
- Validated single and bounded batch requests return segment labels, descriptions, drivers, and input flags
- Explanation
- Business-facing catalog gives human-readable names and suggested actions to numerical cluster IDs
What has to hold up
- Reuse the persisted feature engineer and scaler at inference so the API applies the training transformation.
- Distinguish a distance-to-centroid confidence heuristic from a probability of correctness or a demonstrated business outcome.
Interpretation and version limits
Internal clustering scores measure properties of this dataset and representation. Segment names and recommended actions are interpretations; they do not demonstrate increased retention or revenue.
The local measurement notes flag a customer_id mismatch in the separate v2 training path. This case study describes the baseline artifact-to-service workflow and makes no v2 improvement or measured latency claim.
Proof
VerifyRepository, checks, stack, status
- 01
Follow the baseline training and API instructions in the README before exploring train_v2.py.
- 02
Inspect the candidate leaderboard, model metadata, catalog, and saved preprocessing artifacts.
- 03
Compare api/main.py with the shared feature implementation and inspect single/batch validation and input flags.
- 04
Read MEASUREMENTS.md for the v2 schema issue and collect fresh runtime evidence before publishing performance numbers.
- Role
- Feature engineering, model selection, segment interpretation, serving, and demo integration
- Scope
- Local clustering training pipeline, artifact bundle, inference API, and static demo UI
- Proof
- train.py; src/features.py and src/evaluation.py; api/main.py; artifacts/model_metadata.json and candidate_leaderboard.json; MEASUREMENTS.md
- Stack
- Python, Pandas, scikit-learn, FastAPI, Pydantic, HTML, JavaScript
- Inputs
- Age, income, spending score
- Selection
- Multiple clustering signals
- Serving
- Shared saved artifacts
- Batch API
- Up to 250 customers