# 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

```typescript
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*