Customer Segmentation Data Science Project

"""Reproducible RFM customer segmentation with K-means."""

from __future__ import annotations

import numpy as np
import pandas as pd
from sklearn.cluster import KMeans
from sklearn.metrics import silhouette_score
from sklearn.preprocessing import StandardScaler


def make_demo_customers(n: int = 500, seed: int = 42) -> pd.DataFrame:
    rng = np.random.default_rng(seed)
    return pd.DataFrame({
        "customer_id": [f"C{i:04d}" for i in range(1, n + 1)],
        "recency_days": rng.integers(1, 365, n),
        "orders": np.maximum(1, rng.negative_binomial(3, 0.35, n)),
        "revenue": np.round(rng.lognormal(7.3, 0.8, n), 2),
    })


def segment_customers(data: pd.DataFrame, clusters: int = 4, seed: int = 42) -> tuple[pd.DataFrame, pd.DataFrame, float]:
    features = ["recency_days", "orders", "revenue"]
    if len(data) <= clusters:
        raise ValueError("Number of rows must exceed the number of clusters")
    scaled = StandardScaler().fit_transform(data[features])
    labels = KMeans(n_clusters=clusters, random_state=seed, n_init=20).fit_predict(scaled)
    result = data.copy()
    result["segment"] = labels
    profile = result.groupby("segment").agg(customers=("customer_id", "size"), median_recency=("recency_days", "median"), median_orders=("orders", "median"), median_revenue=("revenue", "median")).reset_index()
    return result, profile, float(silhouette_score(scaled, labels))


def main() -> None:
    _, profile, score = segment_customers(make_demo_customers())
    print(f"Silhouette score: {score:.3f}")
    print(profile.round(2).to_string(index=False))
    print("Segments describe patterns; they do not explain causes or individual intent.")


if __name__ == "__main__":
    main()