feat(customer-analytics): synthetic causal telco data model

[ronaldmego]

What

The foundation of the customer-analytics/ track (issue: ronaldmego/site-ronaldmego#64): one synthetic, causal, reproducible telco data model that all five cases — segmentation, churn, next-best-offer, ARPU, incrementality — will read from. No case notebooks yet; this is the shared dataset they stand on.

Why it's built this way

• Standard library only. The generator has zero third-party deps, so it stays auditable (plain CSV, git diff-able) and CI validates it with uvx pytest without installing anything.
• Explicit causal structure, so the cases are real and not circular:
  • churn is caused by observable trajectories (usage decline, payment problems, unresolved escalations, weak engagement, early life, plan misfit) plus unobserved satisfaction + noise → a model recovers signal but never fits perfectly;
  • retention campaigns carry a true uplift but are targeted at high-risk customers (selection bias) with a held-out control → incrementality is non-trivial to estimate correctly.
• No leakage by construction. Every fact stops at the observation cutoff; the churn outcome lives in the next 90 days. There is nothing post-outcome to leak. A test enforces it.

Tables

12 related tables — reference dims (plans, offers, campaigns), entity (customers, subscriptions), monthly facts (usage_monthly, billing, digital_monthly), events (support_interactions, campaign_exposures), policy (consent) and the target (churn_labels). Full schema, grains and keys in data-model/README.md.

Tests (the repo's first suite)

tracks/customer-analytics/telco-customer-intelligence/tests/ — stdlib only, so CI runs them. They assert schema + referential integrity, the no-leakage property, that causal signal is actually present (churn rises with unresolved escalations; a control group exists), and determinism. Locally: 10 passed, ruff check . clean.

Reference signals (default run, seed 42 — re-derive, don't quote)

• 90-day churn base rate ≈ 13% (realistic for telco)
• churn with an unresolved escalation ≈ 28% vs ≈ 10% without
• retention responders ≈ 20% vs held-out control ≈ 31% (both above base → the confounding the incrementality case must untangle)

Notes

• Generated data/ is git-ignored — reproduce from the seed (byte-for-byte).
• usage_daily in the issue body is intentionally modelled at monthly grain (documented) — churn/ARPU/RFM are monthly; daily would bloat CSVs ~30× with no analytical gain.
• Refs, not Closes — this is the foundation; the five cases are the rest of #64.
• Distribution (LinkedIn/video) is downstream and out of scope here — that's Hermes (ronaldmego/site-ronaldmego#65). This PR produces the reproducible artifact + write-up only.

🤖 Generated with Claude Code