# A/B LTV Testing Agent — CDP Edge Quantum Tier

## Identidade

**Agente:** A/B LTV Testing Agent
**Papel:** Otimização Contínua de Precisão do LTV Preditivo
**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 3
**Versão:** 1.0.0 — 9 de Abril de 2026

---

## Missão

Testar variações do prompt do modelo de LTV de forma automática e estatisticamente controlada,
identificando qual formulação do sistema prompt para o Workers AI produz as predições mais
próximas do valor real de compra — **aumentando a precisão do LTV em até +25%**.

---

## Posição no Fluxo do Master Orchestrator

```
Browser /track (Lead Event)
    ↓
LTV Prediction Call (predictLtv)
    ↓ [se teste ativo]
getLtvAbVariation() → sorteia variação ponderada do teste ativo
    ↓
Workers AI com system_prompt da variação sorteada
    ↓
D1: ltv_ab_assignments (registra user_id + variation_id + predicted_ltv)
    ↓
[quando compra chega via webhook]
D1: ltv_ab_assignments.converted = 1 + real_revenue
    ↓
GET /api/ltv/ab-test/results → accuracy_score por variação
    ↓
POST /api/ltv/ab-test/winner → aplica vencedor ao LTV padrão
```

**Upstream (de onde recebe dados):**
- `index.ts → predictLtv()` — ponto de interceptação do teste
- `webhook events` — fonte verdade do revenue real para scoring

**Downstream (quem consome outputs):**
- `ltv-predictor-agent.md` → recebe o prompt vencedor para aplicar como novo default
- `bidding-agent.md` → LTV mais preciso → bids mais precisos
- `dashboard-agent.md` → exibe resultados dos testes no painel

---

## Como o A/B Test Funciona

### 1. Criação do Experimento

```
POST /api/ltv/ab-test/create
{
  "name": "Teste: Foco Engajamento vs Intenção",
  "min_sample": 200,
  "variations": [
    {
      "name": "Controle — Prompt Original",
      "is_control": true,
      "weight": 0.5,
      "system_prompt": "You are a conversion rate expert. Reply ONLY with JSON {\"adjustment\": <-10 to 10>} based on lead data. No explanation."
    },
    {
      "name": "Variação B — Foco em Intenção de Compra",
      "weight": 0.5,
      "system_prompt": "You are a Brazilian digital marketing expert specializing in course sales. Focus on purchase intention signals. Reply ONLY with JSON {\"adjustment\": <-10 to 10>}."
    }
  ]
}
```

### 2. Distribuição Automática

A cada chamada de `predictLtv()` para um evento Lead, o sistema:
1. Busca o teste ativo no D1 (com cache de 5 min no KV para evitar latência)
2. Sorteia uma variação usando distribuição ponderada pelos `weight`
3. Usa o `system_prompt` da variação sorteada no Workers AI
4. Registra o assignment em `ltv_ab_assignments`

### 3. Scoring Automático via Webhook

Quando chega um webhook de compra (`Purchase`), o sistema:
1. Busca o email do comprador em `ltv_ab_assignments` (por hash)
2. Atualiza `converted = 1` e `real_revenue = valor_da_compra`
3. Incrementa `total_purchases` e `sum_real_revenue` na variação

### 4. Cálculo de Accuracy Score

```
accuracy_score =
  1 - (ABS(avg_predicted_ltv - avg_real_revenue) / avg_real_revenue)
  → 1.0 = predição perfeita
  → 0.0 = predição completamente errada
  → Valores negativos = predição muito errada
```

### 5. Declaração de Vencedor

```
POST /api/ltv/ab-test/winner
{ "test_id": 1, "variation_id": 2 }
→ marca variation como winner
→ retorna o system_prompt vencedor para aplicar como novo default
```

---

## Endpoints Expostos

| Método | Rota | Função |
|--------|------|--------|
| `POST` | `/api/ltv/ab-test/create` | Cria novo experimento com variações |
| `GET`  | `/api/ltv/ab-test/list` | Lista todos os experimentos |
| `GET`  | `/api/ltv/ab-test/results` | Resultados de accuracy por variação |
| `POST` | `/api/ltv/ab-test/winner` | Declara vencedor e retorna prompt |

---

## Variações de Prompt Predefinidas (use nos seus testes)

### Variação A — Controle (atual)
```text
You are a conversion rate expert. Reply ONLY with a JSON object
{"adjustment": <number between -10 and 10>} based on the lead data provided.
No explanation.
```

### Variação B — Foco em Intenção
```text
You are a Brazilian infoproduct marketing expert. The lead is likely interested in
online courses or digital products. Focus heavily on purchase_intention and
engagement signals. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
Higher adjustment = higher purchase probability.
```

### Variação C — Foco em Dados Comportamentais
```text
You are a behavioral economics expert. Analyze recency, frequency, and monetary
signals from the lead data. Score based on: (1) engagement quality, (2) time of
conversion, (3) traffic source quality. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
```

### Variação D — Foco em Geo + Canal
```text
You are a CRM specialist for Brazilian digital products. Brazilian leads from paid
social (facebook/instagram) between 18h-23h BRT have highest LTV. Organic traffic
and direct access indicate research phase. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
```

---

## Regras de Negócio

```
✅ SEMPRE manter o controle ativo (is_control = 1) — baseline para comparação
✅ SEMPRE aguardar min_sample assignments antes de recomendar vencedor
✅ SEMPRE registrar assignments mesmo quando Workers AI está indisponível
✅ SEMPRE usar cache KV (5 min TTL) para buscar o teste ativo — evitar latência D1
✅ SEMPRE atualizar assignments quando purchase webhook chegar

❌ NUNCA declarar vencedor com < 50 conversões por variação
❌ NUNCA rodar dois testes simultâneos (status = 'running' deve ser único)
❌ NUNCA alterar o prompt default automaticamente — sempre exigir aprovação manual via POST /winner
```

---

## Schema D1 — Tabelas

```sql
ltv_ab_tests           -- Experimentos (id, name, status, winner_id, min_sample)
ltv_ab_variations      -- Variações de prompt por experimento
ltv_ab_assignments     -- Registro de qual variação foi usada por lead
v_ab_test_performance  -- VIEW: accuracy por variação com métricas consolidadas
```

---

## Variáveis de Ambiente Requeridas

| Variável | Binding | Descrição |
|----------|---------|-----------|
| `DB` | D1 | Tabelas ltv_ab_tests, ltv_ab_variations, ltv_ab_assignments |
| `AI` | Workers AI | Executa as variações de prompt |
| `GEO_CACHE` | KV | Cache do teste ativo (TTL: 5 min) |

*(Nenhum secret externo necessário)*

---

*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*