---
name: customer-lifetime-value
description: >
  Estimates total net profit from a customer over the entire relationship horizon using
  descriptive, Markov chain, survival regression, and Monte Carlo models. Use when asked to:
  calculate LTV or CLV or CLTV, determine acquisition spend limits, estimate customer equity,
  segment customers by long-term profitability, model retention impact on revenue, or size
  a retention campaign by expected LTV saved. Also trigger when someone says "how much is
  a customer worth?", "what can we spend to acquire?", "customer equity", "LTV model",
  "CLV calculation", "lifetime value", "retention impact on revenue", "LTV by segment",
  "model customer profitability", "predict LTV", "LTV × savability", or provides transaction
  history data and asks for long-term revenue projections. Always render an inline HTML
  dashboard as primary output — never just a text table.
metadata:
  author: Axiom Nexar / Polanyi
  version: 1.0.0
  reference: Katsov, Introduction to Algorithmic Marketing, Ch. 3 §3.5.7; Berger & Nasr (1998)
---

# Customer Lifetime Value (LTV)

Four modeling tiers from descriptive to Monte Carlo simulation. Always outputs an inline
HTML dashboard + exec recommendation. Reference book: Katsov §3.5.7 (pp. 113–120).

---

## Core LTV Formula (Berger & Nasr, 1998 — Katsov eq. 3.23)

```
LTV(u) = Σ_{t=1}^{T}  (R − C) · r^(t−1) / (1 + d)^(t−1)
```

Parameters:
- **R** — average revenue per customer per period
- **C** — average cost per customer per period  
- **r** — retention rate (probability of staying one more period)
- **d** — discount rate (cost of capital per period)
- **T** — projection horizon (periods)

**Key insight:** LTV is the upper bound on acquisition spend. Customer equity = Σ LTV(u) across all customers.

---

## Model Selection

| Scenario | Model | Script |
|---|---|---|
| Quick estimate, segment-level | Descriptive (eq. 3.23–3.24) | `ltv_descriptive.py` |
| Multi-state customer journey (recency/frequency states) | Markov Chain (eq. 3.25–3.28) | `ltv_markov_chain.py` |
| Individual-level with churn survival function | Regression + Survival (eq. 3.30–3.31) | `ltv_survival.py` |
| Confidence intervals + uncertainty quantification | Monte Carlo on Markov | `monte_carlo_ltv.py` |
| Portfolio-level metric | Customer Equity | `customer_equity.py` |

→ Read `references/model_selection_ltv.md` for deeper guidance.

---

## Workflow

### Step 1 — Gather Parameters
Minimum viable inputs:
- Net margin per period `m₀` = R − C
- Retention rate `r` (historical cohort analysis or survival model output)
- Discount rate `d` (WACC or cost of capital; 8–15% annually typical)
- Horizon `T` (typically 24–60 months)

For Markov: define states (recency buckets), transition matrix P, gain vector G.  
For Survival: requires transaction history with churn events or heuristic lapse rule.

### Step 2 — Run Model
```bash
# Descriptive
python scripts/ltv_descriptive.py --m0 100 --mM 150 --tau 3 --r 0.9 --d 0.1 --T 5

# Markov chain
python scripts/ltv_markov_chain.py --transitions data/transitions.csv \
       --gains "75,-5,-5,0" --discount 0.001 --horizon 24

# Survival regression
python scripts/ltv_survival.py --transactions data/txns.csv --horizon 36

# Monte Carlo
python scripts/monte_carlo_ltv.py --transitions data/transitions.csv \
       --gains "75,-5,-5,0" --n-sims 10000 --horizon 36
```

### Step 3 — Export Dashboard JSON
```bash
python scripts/export_ltv_dashboard_json.py --results results/ltv_output.csv \
       --model-type descriptive --output dashboard_data.json
```

### Step 4 — Render Inline Dashboard
Load `references/ltv_dashboard_template.html`, inject JSON, call `show_widget`.

**Output sequence:**
```
1. [bash_tool] Run model script → capture output
2. [bash_tool] export_ltv_dashboard_json.py → JSON
3. [show_widget] Render HTML dashboard
4. [text] 3–5 line exec recommendation
5. [text] Model caveats / sensitivity notes
```

---

## Scripts Reference

| Script | Key Inputs | Key Outputs |
|---|---|---|
| `ltv_descriptive.py` | m0, mM, tau, r, d, T | LTV table + LTV curve JSON |
| `ltv_markov_chain.py` | transitions CSV, gains, d, T | LTV vector per initial state |
| `ltv_survival.py` | transaction history CSV | Per-customer LTV with survival function |
| `monte_carlo_ltv.py` | transitions CSV, gains, n_sims, T | LTV distribution: mean, p10, p50, p90 |
| `customer_equity.py` | scored customers CSV | Total customer equity + segment breakdown |
| `export_ltv_dashboard_json.py` | any LTV output CSV | JSON for HTML dashboard |

---

## Output Format — Visualization First

**Primary output: inline HTML dashboard (show_widget). Always render before text.**

Dashboard panels (see `references/ltv_dashboard_template.html`):
1. **KPI bar** — LTV (base state), customer equity, payback period, breakeven retention rate
2. **LTV curve over time** — discounted cumulative LTV vs. horizon (shows saturation)
3. **Retention sensitivity** — LTV as function of r from 0.5→0.99
4. **Discount rate sensitivity** — LTV as function of d from 0→0.3
5. **Monte Carlo distribution** — histogram with p10/p50/p90 bands (if MC model)
6. **Segment comparison table** — LTV by customer state / segment

**Fallback** (if show_widget unavailable): Katsov Table 3.6 format — year | net_profit | retention_rate | expected_profit | discount_multiplier | discounted_profit | cumulative_ltv

---

## Key Equations Reference

```
# Descriptive with growing net profit (eq. 3.24):
m_t = m0 + (mM − m0)(1 − e^{−kt})    where k = ln(2)/τ

# Regression/Survival LTV (eq. 3.30–3.31):
LTV(u) = Σ_t p(u,t) · m(u,t)
LTV(u) = Σ_t S_u(t) · m(u,t)         [survival function replaces retention]

# Markov LTV (eq. 3.28):
V = Σ_{t=1}^{T} [1/(1+d)^{t−1}] P^t G

# Customer equity:
CE = Σ_u LTV(u)

# Retention budget optimization (eq. 3.49–3.52):
r = r_max(1 − e^{−k_r R})            [retention as function of spend R]
argmax_{A,R} N_p(a·LTV(r) − c) + N_c·LTV(r)   s.t. A + R ≤ budget
```

---

## Key Caveats

- **Retention rate is the dominant driver.** A 5pp improvement in r has larger LTV impact than a 10% increase in margin. Always run sensitivity.
- **Discount rate encodes risk.** Higher d → lower LTV → lower acquisition bid ceiling. Use WACC or sector-appropriate rate.
- **Descriptive model ≠ causal model.** Changing a marketing action changes r, which changes LTV — the feedback loop requires eq. 3.49.
- **Survival model requires lapse definition.** Must define churn event heuristically (e.g., 5 months without purchase = lapsed). Results are sensitive to this.
- **Monte Carlo provides variance, not bias correction.** Use MC to communicate uncertainty to CMO/CFO, not to correct model specification.

---

## Integration with Agency Growth OS

| Skill | Handoff |
|---|---|
| `response-uplift-modeling` | Savability × LTV → retention targeting score (eq. 3.40) |
| `audience-segmentation-brief` | Segment-level LTV inputs (R, C, r per persona) |
| `crm-journey-architect` | LTV payback period → journey trigger timing |
| `margin-simulation` | Customer equity → business valuation input |
| `measurement-incrementality` | LTV uplift as campaign success metric |

---

## Reference Files

- `references/model_selection_ltv.md` — Descriptive vs Markov vs Survival decision guide
- `references/katsov_ltv_excerpts.md` — Key equations, Table 3.6, and Markov example
- `references/ltv_dashboard_template.html` — Reusable HTML dashboard. Inject `SKILL_DATA_JSON`