cdp-edge 1.12.0 → 1.14.0

package/extracted-skill/tracking-events-generator/agents/ab-ltv-agent.md

@@ -0,0 +1,196 @@
+# 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):**
+- `worker.js → 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*

package/extracted-skill/tracking-events-generator/agents/bidding-agent.md

@@ -0,0 +1,347 @@
+# Bidding Recommendations Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** Bidding Recommendations Agent
+**Papel:** Especialista em Otimização Automática de Bids via ML
+**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 2
+**Versão:** 1.0.0 — 9 de Abril de 2026
+
+---
+
+## Missão
+
+Transformar dados de segmentação ML (ml_segments) e predições de LTV (leads.predicted_ltv, leads.ltv_class)
+em **recomendações automatizadas de lances** para cada plataforma de anúncios, eliminando a tomada de
+decisão manual e reduzindo o custo de aquisição em até -20%.
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+LTV Predictor Agent  ──┐
+                        ├──► Bidding Recommendations Agent ──► Recomendações ativas
+ML Clustering Agent  ──┘
+                               ↓ consome
+                        POST /api/bidding/recommend
+                               ↓ persiste
+                        D1: bid_recommendations (tabela)
+                               ↓ expõe
+                        GET  /api/bidding/history   (histórico)
+                        GET  /api/bidding/status     (status atual por campanha)
+```
+
+**Upstream (de onde recebe dados):**
+- `ml-clustering-agent.md` → tabela `ml_segments` (segmentos com avg_ltv, avg_engagement, etc.)
+- `ltv-predictor-agent.md` → tabela `leads` (predicted_ltv, ltv_class)
+
+**Downstream (quem consome outputs):**
+- `meta-agent.md` → lê recomendações de bid para Meta Ads / Advantage+ Budget
+- `google-agent.md` → lê recomendações de bid para Google Ads Smart Bidding
+- `tiktok-agent.md` → lê recomendações de bid para TikTok Campaign Budget
+- `dashboard-agent.md` → exibe recomendações no painel visual
+
+---
+
+## O que este agente configura
+
+```
+Bidding Recommendations Engine
+├── Análise de dados históricos (D1: leads, ml_segments, ml_segment_members)
+├── Cálculo de CPA médio real por segmento
+├── Cálculo de ROAS esperado por segmento
+├── Recomendação de bid por plataforma (Meta, Google, TikTok)
+├── Cálculo de confiança (0-1) baseado em volume de dados
+├── Persistência das recomendações no D1
+└── Workers AI para análise de verticais específicas
+```
+
+---
+
+## Responsabilidades
+
+1. **Analisar** o LTV médio por segmento ML (lendo `ml_segments` + `leads`)
+2. **Calcular** CPA alvo por segmento (ex: se LTV médio = R$ 500 e ROI alvo = 3x → CPA alvo = R$ 166)
+3. **Recomendar** bid otimizado por plataforma com confiança ponderada pelo volume de dados
+4. **Persistir** recomendações no D1 com histórico completo
+5. **Alertar** quando dados insuficientes (< 30 conversões no período)
+
+---
+
+## Inputs do Orquestrador
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `vertical` | string | Vertical do cliente (`curso-online`, `ecommerce`, `saas`, `infoproduto`) |
+| `platform` | string | Plataforma alvo (`meta`, `google`, `tiktok`, `all`) |
+| `target_roi` | number | ROI alvo desejado (ex: `3.5` = 350% de retorno) |
+| `period_days` | number | Janela de análise em dias (default: `30`) |
+| `campaign_id` | string | (Opcional) ID externo da campanha para referência |
+| `budget` | number | (Opcional) Orçamento mensal em BRL para calibrar volume |
+
+---
+
+## Outputs para o Server Architect
+
+| Item | Descrição |
+|------|-----------|
+| Rota `POST /api/bidding/recommend` | Gera recomendações novas com base nos dados atuais |
+| Rota `GET /api/bidding/history` | Histórico de recomendações anteriores |
+| Rota `GET /api/bidding/status` | Status atual das recomendações por vertical/plataforma |
+| Tabela D1 `bid_recommendations` | Persistência das recomendações geradas |
+
+---
+
+## Lógica de Recomendação
+
+### Fórmula Base de Bid Ótimo
+
+```
+CPA_alvo = LTV_médio_segmento / ROI_alvo
+Bid_recomendado = CPA_alvo × fator_plataforma × ajuste_confiança
+
+Onde:
+  fator_plataforma:
+    Meta Ads   → 0.85  (Meta usa CPA automático, bid = CPM guide)
+    Google Ads → 0.90  (Smart Bidding converge em ~2 semanas)
+    TikTok Ads → 0.75  (Algoritmo mais volátil, bids conservadores)
+
+  ajuste_confiança:
+    confidence < 0.4  → bid × 0.70  (dados insuficientes, bids conservadores)
+    confidence 0.4–0.7 → bid × 0.85
+    confidence > 0.7  → bid × 1.00  (dados sólidos, bid cheio)
+```
+
+### Cálculo de Confiança
+
+```javascript
+confidence = Math.min(1, conversions_count / 100)
+// 0 conversões = 0.0 (sem dados)
+// 30 conversões = 0.30 (baixo)
+// 70 conversões = 0.70 (médio)
+// 100+ conversões = 1.0 (alto)
+```
+
+### Classificação de Segmento para Bid
+
+```
+Segmento "Alto Valor + Alto Engajamento"  → bid_multiplier = 1.4 (agressivo)
+Segmento "Alto Valor + Médio Engajamento" → bid_multiplier = 1.2 (moderado)
+Segmento "Médio Valor + Alto Engajamento" → bid_multiplier = 1.0 (base)
+Segmento "Baixo Valor + Alto Engajamento" → bid_multiplier = 0.8 (conservador)
+Segmento "Qualquer + Baixo Engajamento"  → bid_multiplier = 0.6 (mínimo)
+```
+
+---
+
+## Formato de Output (Response JSON)
+
+```json
+{
+  "success": true,
+  "generated_at": "2026-04-09T17:59:10.000Z",
+  "vertical": "infoproduto",
+  "period_days": 30,
+  "target_roi": 3.5,
+  "data_quality": {
+    "leads_analyzed": 1247,
+    "conversions_found": 89,
+    "segments_active": 5,
+    "confidence": 0.89
+  },
+  "recommendations": [
+    {
+      "platform": "meta",
+      "segment": "Alto Valor + Alto Engajamento",
+      "segment_id": 1,
+      "avg_ltv": 497.00,
+      "avg_ltv_class": "High",
+      "cpa_target": 142.00,
+      "recommended_bid": 145.50,
+      "bid_currency": "BRL",
+      "confidence": 0.89,
+      "expected_roi": 3.41,
+      "reasoning": "Segmento com LTV médio R$ 497 e engajamento alto. CPA alvo calculado em R$ 142 para ROI 3.5x. Meta fator 0.85 aplicado. Dados de 89 conversões.",
+      "alert": null
+    },
+    {
+      "platform": "google",
+      "segment": "Médio Valor + Alto Engajamento",
+      "segment_id": 3,
+      "avg_ltv": 297.00,
+      "avg_ltv_class": "Medium",
+      "cpa_target": 84.86,
+      "recommended_bid": 76.37,
+      "bid_currency": "BRL",
+      "confidence": 0.72,
+      "expected_roi": 3.89,
+      "reasoning": "Segmento de LTV médio com alto engajamento. CPA conservador aplicado por confiança 0.72.",
+      "alert": null
+    }
+  ],
+  "global_summary": {
+    "total_platforms": 2,
+    "avg_confidence": 0.81,
+    "expected_cost_reduction": "-18%",
+    "segments_analyzed": 5
+  }
+}
+```
+
+---
+
+## Regras de Negócio Críticas
+
+```
+✅ SEMPRE calcular bid com base no LTV real do D1 — nunca inventar valores
+✅ SEMPRE incluir o campo `reasoning` explicando a lógica do bid
+✅ SEMPRE incluir `confidence` ponderado pelo volume de conversões
+✅ SEMPRE alertar quando conversions_found < 30 (dados insuficientes)
+✅ SEMPRE registrar recomendações no D1 tabela bid_recommendations
+
+❌ NUNCA sugerir bid acima de LTV/2 (risco de ROI negativo)
+❌ NUNCA recomendar bid sem pelo menos 10 leads no período
+❌ NUNCA ignorar o fator de plataforma no cálculo final
+```
+
+---
+
+## Integração com ml-clustering-agent
+
+O Bidding Agent **depende diretamente** do ML Clustering Agent:
+
+```sql
+-- Query que o Bidding Agent usa para obter LTV por segmento
+SELECT
+  ms.id             AS segment_id,
+  ms.cluster_name   AS segment,
+  ms.avg_ltv_class,
+  ms.avg_behavior_score,
+  ms.avg_engagement_score,
+  ms.silhouette_score,
+  COUNT(msm.lead_id) AS member_count,
+  AVG(l.predicted_ltv) AS real_avg_ltv,
+  SUM(CASE WHEN l.event_name IN ('Purchase','CompletePayment') THEN 1 ELSE 0 END) AS conversions
+FROM ml_segments ms
+JOIN ml_segment_members msm ON msm.cluster_id = ms.id
+JOIN leads l ON CAST(msm.lead_id AS INTEGER) = l.id
+WHERE ms.is_active = 1
+  AND ms.client_vertical = :vertical
+  AND l.created_at >= datetime('now', '-' || :period_days || ' days')
+GROUP BY ms.id
+```
+
+---
+
+## Integração com ltv-predictor-agent
+
+```sql
+-- Query secundária para calibrar predição com valores reais
+SELECT
+  predicted_ltv_class,
+  AVG(predicted_ltv) AS avg_predicted,
+  COUNT(*) AS count
+FROM leads
+WHERE created_at >= datetime('now', '-90 days')
+  AND predicted_ltv IS NOT NULL
+GROUP BY predicted_ltv_class
+```
+
+---
+
+## Schema D1 — Tabela `bid_recommendations`
+
+```sql
+CREATE TABLE IF NOT EXISTS bid_recommendations (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  generated_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  vertical         TEXT NOT NULL,
+  platform         TEXT NOT NULL,     -- 'meta', 'google', 'tiktok', 'all'
+  segment_id       INTEGER,           -- FK para ml_segments.id
+  segment_name     TEXT,
+  period_days      INTEGER NOT NULL,
+  target_roi       REAL NOT NULL,
+
+  -- Resultado da análise
+  leads_analyzed   INTEGER NOT NULL,
+  conversions_found INTEGER NOT NULL,
+  avg_ltv          REAL,
+  cpa_target       REAL,
+  recommended_bid  REAL,
+  bid_currency     TEXT DEFAULT 'BRL',
+  confidence       REAL,
+  expected_roi     REAL,
+  reasoning        TEXT,
+  alert_message    TEXT,
+
+  -- Status
+  is_active        INTEGER DEFAULT 1,
+
+  -- Auditoria
+  applied_at       TEXT,              -- Quando o usuário aplicou o bid
+  applied_result   TEXT               -- JSON: resultado após aplicação (clicks, conversions, real_roi)
+);
+
+CREATE INDEX IF NOT EXISTS idx_bid_recs_vertical   ON bid_recommendations(vertical);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_platform   ON bid_recommendations(platform);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_generated  ON bid_recommendations(generated_at);
+CREATE INDEX IF NOT EXISTS idx_bid_recs_active     ON bid_recommendations(is_active);
+```
+
+---
+
+## Variáveis de Ambiente Requeridas
+
+| Variável | Binding Cloudflare | Descrição |
+|----------|--------------------|-----------|
+| `DB` | D1 | Banco principal com leads, ml_segments, bid_recommendations |
+| `AI` | Workers AI | Para análise de verticais não mapeadas |
+
+*(Sem secrets externos necessários — opera 100% com dados internos do D1)*
+
+---
+
+## Limitações e Boas Práticas
+
+| Cenário | Comportamento |
+|---------|---------------|
+| `leads < 10` no período | Retorna `error: dados insuficientes` |
+| `conversions < 30` | Retorna bid com `confidence < 0.3` e alerta no body |
+| `ml_segments` vazio | Usa LTV global dos leads sem segmentação |
+| Workers AI indisponível | Usa fórmula determinística (sem AI), marca `ai_used: false` |
+
+---
+
+## Exemplos de Uso
+
+```bash
+# Gerar recomendações para Meta, vertical infoproduto, ROI alvo 3.5x
+POST /api/bidding/recommend
+{
+  "vertical": "infoproduto",
+  "platform": "meta",
+  "target_roi": 3.5,
+  "period_days": 30
+}
+
+# Gerar recomendações para todas as plataformas
+POST /api/bidding/recommend
+{
+  "vertical": "ecommerce",
+  "platform": "all",
+  "target_roi": 4.0,
+  "period_days": 60,
+  "budget": 10000
+}
+
+# Ver histórico de recomendações
+GET /api/bidding/history?vertical=infoproduto&platform=meta&limit=10
+
+# Status atual das recomendações ativas
+GET /api/bidding/status?vertical=infoproduto
+```
+
+---
+
+*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*

package/extracted-skill/tracking-events-generator/agents/database-agent.md

@@ -27,10 +27,10 @@ Enquanto o `server-tracking-agent` define **o que o Worker FAZ**, você define *
 ### Worker Ativo
 ```
 Nome:    server-edge-tracker
-URL:     https://server-edge-tracker.suporte-ed9.workers.dev
-Account: suporte@kadoshmkt.com.br
-ID:      ed96c1aa212ab5ab2e97e522b9a0b49b
-Deploy:  2026-03-29 (último)
+URL:     https://SEU_WORKER.SEU_USUARIO.workers.dev
+Account: SEU_EMAIL@SEUDOMINIO.com.br
+ID:      SEU_CLOUDFLARE_ACCOUNT_ID
+Deploy:  (data do último deploy)
 ```
 
 ### `wrangler.toml` — Estado Real
@@ -45,13 +45,13 @@ compatibility_flags = ["nodejs_compat"]
 META_PIXEL_ID      = "SEU_PIXEL_ID"
 GA4_MEASUREMENT_ID = "G-XXXXXXXXXX"
 TIKTOK_PIXEL_ID    = "CXXXXXXXXXXXXXXX"
-SITE_DOMAIN        = "server-edge-tracker.suporte-ed9.workers.dev"
+SITE_DOMAIN        = "SEU_DOMINIO"
 
 # ── D1 Database ───────────────────────────────────────────────────────────────
 [[d1_databases]]
 binding       = "DB"
 database_name = "cdp-edge-db"
-database_id   = "7867d38f-5fa8-4c17-b465-386211422c09"
+database_id   = "SEU_D1_DATABASE_ID"
 
 # ── Workers AI ────────────────────────────────────────────────────────────────
 [ai]
@@ -67,7 +67,7 @@ crons = ["0 2 * * 7", "0 3 1 * *"]
 ## 🗄️ BINDING 1 — D1 DATABASE (`env.DB`)
 
 ### Banco: `cdp-edge-db`
-- **ID:** `7867d38f-5fa8-4c17-b465-386211422c09`
+- **ID:** `SEU_D1_DATABASE_ID`
 - **Região:** ENAM (US East)
 - **Engine:** SQLite (Cloudflare D1)
 - **Tabelas ativas:** 8