cdp-edge 1.3.0 → 1.4.0

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

@@ -202,6 +202,15 @@ Cobertura:
 3. `wrangler secret put` os 4 obrigatórios
 4. Disparar lead via `/track` ou webhook → conferir contato + conversa + nota no painel EVO
 
+## 🔑 ONDE ENCONTRAR AS 4 CREDENCIAIS (UI GUIDE)
+
+Para orientar o usuário, siga este roteiro:
+
+1. **`EVO_CRM_BASE_URL`**: A URL de acesso ao painel (ex: `https://api.seucrm.com`).
+2. **`EVO_CRM_CLIENT_ID`**: Gerado em Administrador → Configurações → Aplicações → "Nova Aplicação".
+3. **`EVO_CRM_CLIENT_SECRET`**: Gerado junto com o ID acima. *Atenção: Só aparece uma vez!*
+4. **`EVO_CRM_INBOX_ID`**: Clique na Caixa de Entrada desejada e pegue o número final na URL do navegador (ex: `/inboxes/5`).
+
 ---
 
 ## 🔧 INTEGRAÇÃO COM OUTROS AGENTES

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

@@ -57,3 +57,22 @@ Sempre que o Orquestrador invocar a Otimização de Baleias (LTV Prediction):
   "limite_diario": 10000
 }
 ```
+
+---
+
+## COMANDO *new-ai-module — Ativação por módulo genérico
+
+Este agente também é invocado pelo Master Orchestrator quando recebe o comando `*new-ai-module` com descrição do tipo:
+**classificar, score, pontuar, prever, predizer, detectar, identificar, intenção, distribuir, rotear, priorizar, ranking**
+
+### Responsabilidade no PASSO 1 do pipeline *new-ai-module
+
+Entregar obrigatoriamente ao Master Orchestrator:
+
+1. **Modelo escolhido** — justificado pelo caso de uso descrito
+2. **System prompt calibrado** — instrução para o modelo retornar JSON puro com os campos: `class`, `confidence`, `score`, `reasoning`
+3. **Contrato de features** — quais campos do payload `/track` alimentam o modelo como input
+4. **TTL de cache KV recomendado** — padrão 3600s, ajustar se o módulo for sensível a tempo real
+5. **Posição no pipeline `/track`** — se Modo A ou C, indicar após qual módulo existente este deve ser inserido
+
+> **Regra:** Responder com o pacote completo em uma única mensagem. Sem perguntas de volta ao Orchestrator.

package/extracted-skill/tracking-events-generator/agents/master-orchestrator.md

@@ -916,6 +916,277 @@ FASE 6 (Enterprise Features — ordem de configuração):
 
 ---
 
+## COMANDO *new-ai-module — Criar novo módulo Workers AI
+
+### TRIGGERS (qualquer uma das formas abaixo ativa este comando)
+
+| Forma | Exemplo |
+|---|---|
+| `*new-ai-module [descrição]` | `*new-ai-module classifica leads por score do quiz` |
+| `crie um worker ai para [descrição]` | `crie um worker ai para distribuir leads por pontuação` |
+| `quero um módulo de IA que [descrição]` | `quero um módulo de IA que detecta intenção de compra` |
+
+**REGRA:** O Master Orchestrator NÃO pede mais informações antes de agir. Infere tudo a partir da descrição e executa imediatamente.
+
+---
+
+### DECISÃO INICIAL — Tipo de módulo
+
+Antes de spawnar agentes, classificar automaticamente:
+
+| Descrição contém | Tipo | Agente primário |
+|---|---|---|
+| classificar, score, pontuar, prever, predizer, LTV, valor | **Scoring/Prediction** | LTV Predictor Agent |
+| segmentar, agrupar, cluster, similaridade, perfil | **Clustering/Embedding** | ML Clustering Agent |
+| detectar, identificar, intenção, comportamento, padrão | **Classification** | LTV Predictor Agent |
+| distribuir, rotear, priorizar, fila, ranking | **Routing/Ranking** | LTV Predictor Agent |
+
+---
+
+### PERGUNTA OBRIGATÓRIA — Modo de execução
+
+Antes de iniciar o pipeline, fazer UMA pergunta:
+
+> **"Este módulo deve rodar:"**
+> - **[A] Dentro do pipeline `/track`** — executa automaticamente a cada evento capturado
+> - **[B] Sob demanda via API** — chamado explicitamente por outro sistema ou cron
+> - **[C] Ambos** — rota API + integrado ao `/track`
+
+A resposta define como o PASSO 3 (Server Tracking Agent) conecta o módulo.
+
+---
+
+### PIPELINE DE EXECUÇÃO (sempre nesta ordem, sem pular passos)
+
+---
+
+**PASSO 1 — Agente de IA (LTV Predictor Agent ou ML Clustering Agent)**
+
+Responsabilidade: especificar o cérebro do módulo.
+
+Entregar obrigatoriamente:
+
+1. **Modelo escolhido** com justificativa:
+
+| Caso de uso | Modelo |
+|---|---|
+| Classificação / scoring / raciocínio leve | `@cf/ibm-granite/granite-4.0-h-micro` |
+| Embeddings / similaridade / clustering semântico | `@cf/baai/bge-m3` |
+| Análise rica / respostas longas / contexto amplo | `@cf/meta/llama-3.1-8b-instruct` |
+| Sentimento / classificação binária (rápido) | `@cf/huggingface/distilbert-sst-2-int8` |
+
+2. **Contrato de input/output tipado:**
+```typescript
+// Exemplo para módulo de scoring de leads
+interface AIModuleInput {
+  lead_id: string;
+  features: Record<string, string | number | boolean>;
+  context?: string; // contexto extra opcional
+}
+
+interface AIModuleOutput {
+  lead_id: string;
+  result_class: string;        // ex: 'High' | 'Medium' | 'Low'
+  confidence: number;          // 0.0 – 1.0
+  score: number;               // 0 – 100
+  reasoning: string;           // explicação do modelo (1 linha)
+  model: string;               // @cf/modelo-usado
+  latency_ms: number;
+  cached: boolean;
+}
+```
+
+3. **System prompt do modelo** — calibrado ao caso de uso específico, com instrução de retornar JSON puro.
+
+4. **Estratégia de cache** — resultado deve ser cacheado no KV (`GEO_CACHE`) por TTL definido pelo agente (padrão: 1h), usando `input_hash` como chave, para evitar rechamadas desnecessárias ao modelo.
+
+---
+
+**PASSO 2 — Database Agent**
+
+Responsabilidade: criar schema D1 tipado e com índices corretos.
+
+Schema obrigatório — **sem campos genéricos**:
+```sql
+-- Nomenclatura: schema-ai-[nome-do-módulo].sql
+CREATE TABLE IF NOT EXISTS ai_[nome] (
+  id           TEXT    PRIMARY KEY,               -- UUID v4
+  lead_id      TEXT    NOT NULL,
+  input_hash   TEXT    NOT NULL,                  -- SHA256 do input (usado como cache key)
+  result_class TEXT    NOT NULL,                  -- saída classificada do modelo
+  confidence   REAL    NOT NULL DEFAULT 0,        -- 0.0 – 1.0
+  score        INTEGER NOT NULL DEFAULT 0,        -- 0 – 100
+  reasoning    TEXT,                              -- explicação do modelo
+  model        TEXT    NOT NULL,                  -- @cf/modelo-usado
+  latency_ms   INTEGER,                           -- tempo de inferência
+  cached       INTEGER NOT NULL DEFAULT 0,        -- 0 = fresh, 1 = from KV cache
+  pipeline     TEXT    NOT NULL DEFAULT 'api',    -- 'track' | 'api' | 'cron'
+  created_at   INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_ai_[nome]_lead    ON ai_[nome](lead_id);
+CREATE INDEX IF NOT EXISTS idx_ai_[nome]_class   ON ai_[nome](result_class);
+CREATE INDEX IF NOT EXISTS idx_ai_[nome]_created ON ai_[nome](created_at DESC);
+```
+
+Após gerar o schema, o Database Agent passa o arquivo para o DevOps Agent aplicar — **não aplica diretamente**.
+
+---
+
+**PASSO 3 — Server Tracking Agent**
+
+Responsabilidade: criar o módulo TypeScript + rotas REST + integração ao pipeline conforme resposta da PERGUNTA OBRIGATÓRIA.
+
+**Estrutura do módulo gerado:**
+```typescript
+// server-edge-tracker/modules/ml/[nome].ts
+
+export async function run[Nome](
+  env: Env,
+  input: AIModuleInput
+): Promise<AIModuleOutput> {
+
+  // 1. Verificar cache KV antes de chamar o modelo
+  const cacheKey = `ai:[nome]:${input.input_hash}`;
+  const cached = await env.GEO_CACHE.get(cacheKey, 'json');
+  if (cached) return { ...cached, cached: true };
+
+  // 2. Chamar Workers AI
+  const aiRes = await env.AI.run('[modelo-escolhido]', {
+    messages: [
+      { role: 'system', content: '[system-prompt-gerado-no-passo-1]' },
+      { role: 'user',   content: JSON.stringify(input.features) }
+    ],
+    max_tokens: 64
+  });
+
+  // 3. Parsear output do modelo (sempre JSON puro)
+  const parsed = JSON.parse(aiRes.response);
+  const output: AIModuleOutput = {
+    lead_id:      input.lead_id,
+    result_class: parsed.class,
+    confidence:   parsed.confidence ?? 0,
+    score:        parsed.score ?? 0,
+    reasoning:    parsed.reasoning ?? '',
+    model:        '[modelo-escolhido]',
+    latency_ms:   0, // preenchido pelo caller
+    cached:       false
+  };
+
+  // 4. Salvar no KV (cache) e no D1 (persistência)
+  await env.GEO_CACHE.put(cacheKey, JSON.stringify(output), { expirationTtl: 3600 });
+  await env.DB.prepare(`
+    INSERT INTO ai_[nome] (id, lead_id, input_hash, result_class, confidence, score, reasoning, model, pipeline)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(crypto.randomUUID(), input.lead_id, input.input_hash, output.result_class,
+          output.confidence, output.score, output.reasoning, output.model, input.pipeline ?? 'api')
+    .run();
+
+  return output;
+}
+```
+
+**Rotas REST criadas (sempre, independente do modo):**
+```
+POST /api/ai/[nome]            → executa inferência ad-hoc
+GET  /api/ai/[nome]/:lead_id   → retorna último resultado salvo para o lead
+GET  /api/ai/[nome]/stats      → distribuição de classes + taxa de cache hit
+```
+
+**Integração ao pipeline `/track` (somente se Modo A ou C):**
+```typescript
+// Em index.ts — dentro do handler POST /track, após Quiz Scoring e antes do CAPI Dispatch
+// Ordem runtime atualizada:
+// [1] Fraud Gate → [2] Quiz Scoring → [3] LTV → [3.x] [NOME] → [4] D1 → [5] CAPI
+
+const [nomeResult] = await run[Nome](env, {
+  lead_id:    payload.userId,
+  input_hash: await sha256(JSON.stringify(relevantFeatures)),
+  features:   relevantFeatures,
+  pipeline:   'track'
+});
+
+// Resultado disponível para enriquecer o CAPI dispatch
+payload.ai_[nome]_class = [nomeResult].result_class;
+payload.ai_[nome]_score = [nomeResult].score;
+```
+
+---
+
+**PASSO 4 — DevOps Agent**
+
+Sequência de execução obrigatória:
+
+```bash
+# 1. Verificar se binding [ai] já existe (não duplicar)
+! grep -c '\[ai\]' server-edge-tracker/wrangler.toml
+# Se retornar 0 → adicionar bloco [ai] binding = "AI"
+# Se retornar ≥1 → pular, já existe
+
+# 2. Aplicar schema D1
+! wrangler d1 execute cdp-edge-db --file=server-edge-tracker/schema-ai-[nome].sql --remote
+
+# 3. Deploy
+! wrangler deploy
+```
+
+**Em caso de falha no deploy:** o DevOps Agent captura o erro, passa para o Debug Agent e tenta correção automática antes de escalar para o usuário.
+
+---
+
+**PASSO 5 — Validator Agent**
+
+Smoke tests obrigatórios em sequência:
+
+```bash
+# Test 1 — Inferência ad-hoc
+POST /api/ai/[nome]
+Body: { "lead_id": "smoke-test-001", "features": { [campo-principal]: [valor-teste] } }
+Esperado: 200 + { result_class, confidence, score, cached: false }
+
+# Test 2 — Cache hit
+POST /api/ai/[nome]  (mesmo payload)
+Esperado: 200 + { cached: true, latency_ms < 10 }
+
+# Test 3 — Leitura do resultado
+GET /api/ai/[nome]/smoke-test-001
+Esperado: 200 + registro da tabela D1
+
+# Test 4 — Stats
+GET /api/ai/[nome]/stats
+Esperado: 200 + { total, by_class: { ... }, cache_hit_rate }
+
+# Test 5 — Pipeline /track (somente se Modo A ou C)
+POST /track com payload real
+Esperado: response contém ai_[nome]_class no resultado
+```
+
+Se qualquer teste falhar: **bloquear** e escalar para Debug Agent antes de entregar ao usuário.
+
+---
+
+### SAÍDA FINAL AO USUÁRIO
+
+```
+⚡ Módulo AI criado: [nome-do-módulo]
+
+Modelo:     @cf/[modelo]
+Tabela D1:  ai_[nome]  ([N] colunas tipadas + 3 índices)
+Cache KV:   ai:[nome]:{hash}  (TTL: 1h)
+
+Rotas:
+  POST /api/ai/[nome]           → inferência
+  GET  /api/ai/[nome]/:lead_id  → histórico
+  GET  /api/ai/[nome]/stats     → métricas
+
+Pipeline /track: [INTEGRADO na posição [3.x] | NÃO INTEGRADO]
+
+Smoke tests:  5/5 ✅
+Deploy:       OK — [worker-url]
+```
+
+---
+
 ## COMANDO /setup — Fluxo principal de configuração
 
 ### MENSAGEM DE BOAS-VINDAS (disparar na ativação do agente)
@@ -1082,9 +1353,9 @@ Exibir:
 
 **Bloco EVO CRM (OAuth2)** (incluir se CRM selecionado):
 > - `EVO_CRM_BASE_URL` — URL base (ex: https://api-evocrm.dominio.com)
-> - `EVO_CRM_CLIENT_ID` — OAuth client_id
-> - `EVO_CRM_CLIENT_SECRET` — OAuth client_secret
-> - `EVO_CRM_INBOX_ID` — ID do inbox no CRM
+> - `EVO_CRM_CLIENT_ID` — OAuth client_id (Configurações -> Aplicações)
+> - `EVO_CRM_CLIENT_SECRET` — OAuth client_secret (O segredo do app)
+> - `EVO_CRM_INBOX_ID` — ID numérico do inbox (final da URL da caixa)
 > - `EVO_CRM_DEFAULT_COUNTRY` — Dial code default (ex: 55)
 > - `EVO_CRM_LOCALE` — Locale das notas (pt-BR | en-US | es-ES)
 
@@ -1956,6 +2227,10 @@ Apresentar o resultado organizado com resumo de eventos e próximos passos.
    wrangler secret put META_ACCESS_TOKEN
    wrangler secret put GA4_API_SECRET
    wrangler secret put TIKTOK_ACCESS_TOKEN
+   wrangler secret put EVO_CRM_BASE_URL
+   wrangler secret put EVO_CRM_CLIENT_ID
+   wrangler secret put EVO_CRM_CLIENT_SECRET
+   wrangler secret put EVO_CRM_INBOX_ID
    ```
 
 3. **Testar Eventos:**

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

@@ -744,6 +744,26 @@ curl "https://seudominio.com/api/segmentation/outliers?limit=20"
 
 ---
 
+## COMANDO *new-ai-module — Ativação por módulo genérico
+
+Este agente também é invocado pelo Master Orchestrator quando recebe o comando `*new-ai-module` com descrição do tipo:
+**segmentar, agrupar, cluster, similaridade, perfil, embedding, distribuição**
+
+### Responsabilidade no PASSO 1 do pipeline *new-ai-module
+
+Entregar obrigatoriamente ao Master Orchestrator:
+
+1. **Modelo escolhido** — para clustering semântico: `@cf/baai/bge-m3`; para auto-labeling de segmentos: `@cf/ibm-granite/granite-4.0-h-micro`
+2. **Estratégia de clustering** — K-means (grupos fixos) ou DBSCAN (anomalias/fraude), com `n_clusters` recomendado
+3. **Pipeline de features** — quais campos do payload ou da tabela D1 alimentam o vetor de embedding
+4. **Contrato de output** — `{ segment_id, segment_label, similarity_score, cluster_method }`
+5. **TTL de cache KV recomendado** — padrão 3600s; para segmentos comportamentais usar 1800s
+6. **Posição no pipeline `/track`** — se Modo A ou C, este módulo entra após LTV Prediction
+
+> **Regra:** Responder com o pacote completo em uma única mensagem. Sem perguntas de volta ao Orchestrator.
+
+---
+
 *ML Clustering Agent v1.0 — Segmentação Dinâmica ML*
 *Versão: 1.0 — Criado em: 9 de Abril de 2026*
 *Status: Ready para implementação*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-edge",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",