Customer Lifetime Value Analysis Project

"""Estimate historical customer value from synthetic completed orders."""

from __future__ import annotations

import numpy as np
import pandas as pd


def make_demo_orders(n: int = 2_000, seed: int = 42) -> pd.DataFrame:
    rng = np.random.default_rng(seed)
    customer = rng.integers(1, 401, n)
    revenue = rng.lognormal(6.5, 0.65, n)
    gross_margin_rate = rng.uniform(0.28, 0.58, n)
    return pd.DataFrame({"order_id": range(1, n + 1), "customer_id": customer,
                         "order_date": pd.Timestamp("2024-01-01") + pd.to_timedelta(rng.integers(0, 730, n), unit="D"),
                         "revenue": revenue.round(2), "gross_margin": (revenue * gross_margin_rate).round(2)})


def historical_clv(orders: pd.DataFrame, as_of: str = "2026-01-01") -> pd.DataFrame:
    data = orders.copy()
    data["order_date"] = pd.to_datetime(data["order_date"])
    cutoff = pd.Timestamp(as_of)
    data = data[data["order_date"] < cutoff]
    result = data.groupby("customer_id", as_index=False).agg(
        first_order=("order_date", "min"), last_order=("order_date", "max"),
        orders=("order_id", "nunique"), revenue=("revenue", "sum"),
        historical_gross_profit=("gross_margin", "sum"))
    result["active_months"] = ((cutoff - result["first_order"]).dt.days / 30.4375).clip(lower=1)
    result["monthly_gross_profit"] = result["historical_gross_profit"] / result["active_months"]
    result["days_since_last_order"] = (cutoff - result["last_order"]).dt.days
    return result.sort_values("historical_gross_profit", ascending=False).reset_index(drop=True)


def main() -> None:
    clv = historical_clv(make_demo_orders())
    print(clv.head(10).round(2).to_string(index=False))
    print(f"Customers: {len(clv)} | Historical gross profit: {clv['historical_gross_profit'].sum():,.0f}")
    print("This is observed historical value, not a prediction of future lifetime value.")


if __name__ == "__main__":
    main()