cdp-edge 1.2.2 → 1.4.0

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

@@ -0,0 +1,769 @@
+# ML Clustering Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** ML Clustering Agent
+**Papel:** Especialista em Segmentação Dinâmica via Machine Learning
+**Nível:** Deus (Quantum Tier) — Especialista em IA Clustering
+
+---
+
+## Por que isso importa
+
+| Situação Atual | Com Segmentação Dinâmica ML |
+|---|---|
+| Segmentos estáticos (tags manuais) | Grupos automáticos que evoluem com novos dados |
+| Campanhas genéricas para todos | +40% relevância de campanhas por segmento |
+| Insights manuais de comportamento | Clusters ML descobrem padrões ocultos |
+| CTR genérico por vertical | Otimização específica por cluster de comportamento |
+
+---
+
+## O que este agente configura
+
+```
+Segmentação Dinâmica ML
+├── K-means Clustering (Workers AI)
+│   ├── Feature engineering: LTV, behavior, geo, time
+│   ├── N clusters configurável (3-10)
+│   ├── Auto-labeling de segmentos (interpretação ML)
+│   └── Persistência em D1 (tabela ml_segments)
+│
+├── DBSCAN Clustering (anomalias/fraude)
+│   ├── Detecção de leads anômalos (outliers)
+│   ├── Epsilon e MinPts configuráveis
+│   ├── Marcação automática de "suspicious"
+│   └── Integração com Security Agent
+│
+├── Hierarchical Clustering (níveis de segmentos)
+│   ├── Dendrograma de leads (similaridade hierárquica)
+│   ├── Auto-seleção de k (silhouette score)
+│   ├── Níveis de granularidade (macro → micro)
+│   └── Navegação drill-down em clusters
+│
+├── Feature Engineering Pipeline
+│   ├── Normalização (min-max, z-score)
+│   ├── Encoding (one-hot para categoricos)
+│   ├── Feature selection (importância)
+│   └── Time-based features (dias desde lead, hora do dia)
+│
+└── Auto-Interpretation de Segmentos
+    ├── Geração de nomes descritivos (ex: "Alto Valor + Alto Engajamento")
+    ├── Características dominantes (top features por cluster)
+    ├── Distribuição de métricas (avg LTV, std behavior)
+    └── Recomendações de ação por segmento
+```
+
+---
+
+## Pré-requisitos
+
+- **Workers AI**: Binding `env.AI` habilitado no wrangler.toml
+- **D1 Database**: Tabela `leads` com dados históricos (últimos 6 meses)
+- **Server Architect**: Integrar endpoints na rota `/api/segmentation/*`
+- **Feature Engineering**: Pipeline pronta para normalização/encoding
+
+---
+
+## Fase 1 — Feature Engineering Pipeline
+
+### 1.1 Extração de Features do D1
+
+Consultar leads históricos e extrair features numéricas/categóricas:
+
+```sql
+-- Features numéricas
+SELECT 
+  ltv_class AS ltv_numeric,           -- 0=Low, 1=Medium, 2=High
+  behavior_score AS behavior_numeric,        -- 0-100
+  engagement_score AS engagement_numeric,  -- 0-100
+  intention_level AS intention_numeric,      -- 0-100
+  bot_score AS bot_numeric,               -- 0-100 (inverso: 100=humano)
+  value AS purchase_value,                -- valor de compra (null para leads)
+  currency_value AS currency_numeric,       -- 1.0 para BRL
+  
+-- Features de tempo
+FROM leads 
+WHERE created_at >= datetime('now', '-6 months')
+
+-- Features categóricas (para one-hot encoding)
+SELECT DISTINCT 
+  country,           -- BR, US, AR
+  state,            -- SP, RJ, MG
+  geo_timezone,      -- America/Sao_Paulo, America/New_York
+  utm_source,       -- facebook, google, tiktok
+  utm_medium,       -- cpc, organic, social
+FROM leads 
+WHERE created_at >= datetime('now', '-6 months')
+```
+
+### 1.2 Normalização de Features
+
+```python
+# Exemplo de normalização (implementado em Workers AI)
+
+# Min-Max Normalization (0-1 range)
+normalized_value = (value - min) / (max - min)
+
+# Z-Score Normalization (mean=0, std=1)
+normalized_value = (value - mean) / std
+
+# One-Hot Encoding para categóricos
+country_BR = [1, 0, 0, 0, 0]
+country_US = [0, 1, 0, 0, 0]
+country_AR = [0, 0, 1, 0, 0]
+```
+
+### 1.3 Time-Based Features
+
+```python
+# Features temporais para clustering
+
+days_since_lead = (now - created_at).days
+hour_of_day = created_at.hour
+day_of_week = created_at.weekday()  # 0=Segunda, 6=Domingo
+is_weekend = 1 if day_of_week in [5, 6] else 0
+is_business_hours = 1 if 9 <= hour_of_day <= 18 else 0
+```
+
+---
+
+## Fase 2 — K-Means Vetorial Real (embeddinggemma-300m + K-means em JS)
+
+> **Arquitetura atual:** O clustering não usa LLM para fazer os cálculos matemáticos.
+> Em vez disso, usa **embeddings semânticos reais** + **K-means implementado em JavaScript**,
+> com o Granite usado **apenas para nomear** os clusters resultantes.
+
+### 2.1 Pipeline de Clustering
+
+```
+100 leads (sample) → perfil textual → embeddinggemma-300m → vetores 768d
+                                                                   ↓
+                                                    K-means++ (cosine distance, JS puro)
+                                                                   ↓
+                                               silhouette score real calculado em JS
+                                                                   ↓
+                                   Granite 4.0 Micro nomeia cada cluster (1 call de LLM)
+```
+
+### 2.2 Modelos Workers AI utilizados
+
+| Modelo | ID | Uso |
+|---|---|---|
+| **Granite 4.0 Micro** | `@cf/ibm-granite/granite-4.0-h-micro` | LTV Prediction + Naming de clusters |
+| **EmbeddingGemma 300M** | `@cf/baai/bge-m3` | Embeddings semânticos para K-means |
+
+### 2.3 Perfil textual por lead (input para embedding)
+
+```typescript
+function _buildLeadProfile(l) {
+  return [
+    `LTV: ${l.predicted_ltv_class || 'desconhecido'}`,
+    `engajamento: ${Math.round(l.engagement_score || 0)}`,
+    `intenção: ${l.intention_level || 'desconhecida'}`,
+    `origem: ${l.utm_source || 'direto'}`,
+    `canal: ${l.utm_medium || 'desconhecido'}`,
+    `país: ${l.country || 'BR'}`,
+    `hora: ${l.hour_of_day || 12}h`,
+    (l.is_weekend ? 'fim-de-semana' : 'dia-útil'),
+    `recência: ${l.days_since_lead || 0} dias`,
+  ].filter(Boolean).join(', ');
+}
+```
+
+### 2.4 Chamada de embeddings em batch
+
+```typescript
+// Embeds até 100 perfis em uma única chamada
+const embRes = await env.AI.run('@cf/baai/bge-m3', { text: profiles });
+const vectors = embRes.data; // float32[][] — shape [N, 768]
+```
+
+### 2.5 K-means vetorial (cosine distance)
+
+```typescript
+// Inicialização K-means++ → iterações até convergência → assignments finais
+const { assignments } = _kmeansRun(vectors, nClusters); // implementado em index.ts
+const silhouetteScore = _silhouette(vectors, assignments, nClusters); // score real
+```
+
+### 2.6 Naming dos clusters via Granite (único uso de LLM)
+
+```typescript
+// Granite recebe apenas as estatísticas agregadas por cluster
+// Retorna nome descritivo + recomendação de campanha em português
+const nameRes = await env.AI.run('@cf/ibm-granite/granite-4.0-h-micro', {
+  messages: [{ role: 'user', content: namingPrompt }],
+  max_tokens: 800
+});
+```
+
+### 2.2 Features para K-Means
+
+```typescript
+// Features recomendadas para clustering (com base na análise D1)
+
+const RECOMMENDED_FEATURES = [
+  // Financeiro
+  'ltv_class',           // Low/Medium/High (0-1-2)
+  'purchase_value',       // valor de compra (null para leads)
+  
+  // Comportamental
+  'behavior_score',       // 0-100 (engajamento)
+  'engagement_score',     // 0-100 (interações)
+  'intention_level',      // 0-100 (probabilidade de compra)
+  
+  // Temporal
+  'days_since_lead',      // recência (0-180 dias)
+  'hour_of_day',         // 0-23
+  'is_weekend',          // 0/1
+  'is_business_hours',     // 0/1
+  
+  // Geográfico
+  'country',              // one-hot encoding
+  'state',               // one-hot encoding
+  
+  // Origem de tráfego
+  'utm_source',           // one-hot encoding
+  'utm_medium'           // one-hot encoding
+];
+
+const DEFAULT_N_CLUSTERS = 5;  // 5 segmentos (configurável)
+```
+
+---
+
+## Fase 3 — DBSCAN Clustering (Detecção de Anomalias)
+
+### 3.1 Prompt para Workers AI
+
+```python
+PROMPT_DBSCAN = f"""
+You are a Machine Learning expert specializing in anomaly detection.
+
+You will receive {n_leads} customers with {features}.
+Your task: Perform DBSCAN clustering to detect outliers and fraudulent patterns.
+
+INPUTS:
+- leads: JSON array of customer objects
+- features: list of feature names
+- epsilon: distance threshold (default: 0.3)
+- min_samples: minimum points to form cluster (default: 5)
+
+TASK:
+1. For each lead, calculate distance to {min_samples} nearest neighbors
+2. Mark as "core point" if >= min_samples neighbors within epsilon
+3. Mark as "border point" if < min_samples neighbors but reachable from core
+4. Mark as "outlier" if not reachable from any core point
+5. Identify clusters and noise (outliers)
+
+OUTPUT (JSON only):
+{{
+  "total_leads": 500,
+  "n_core_points": 450,
+  "n_border_points": 30,
+  "n_outliers": 20,
+  "outliers": [
+    {{
+      "lead_id": "lead_123",
+      "reason": "behavior_score too high (> 95)",
+      "risk_score": 0.92,
+      "features": {{
+        "behavior_score": 98,
+        "days_since_lead": 0,
+        "unusual_utm_pattern": true
+      }}
+    }},
+    ...
+  ],
+  "clusters": [
+    {{
+      "cluster_id": 0,
+      "size": 235,
+      "density": "high"
+    }},
+    ...
+  ]
+}}
+
+OUTLIER PATTERNS TO DETECT:
+- behavior_score > 95 (bot-like behavior)
+- days_since_lead = 0 AND behavior_score > 80 (instant lead, suspicious)
+- unusual utm_source combination (e.g., unknown_source + high_value)
+- geographic mismatch (high_value + unusual location)
+
+Return ONLY valid JSON, no explanations.
+"""
+```
+
+---
+
+## Fase 4 — Hierarchical Clustering (Drill-Down)
+
+### 4.1 Prompt para Workers AI
+
+```python
+PROMPT_HIERARCHICAL = f"""
+You are a Machine Learning expert specializing in hierarchical clustering.
+
+You will receive {n_leads} customers.
+Your task: Build hierarchical clustering tree from macro to micro segments.
+
+INPUTS:
+- leads: JSON array of customer objects
+- features: list of feature names
+- max_depth: maximum tree depth (default: 3)
+
+TASK:
+1. Build binary hierarchical tree (top-down divisive clustering)
+2. At each level, split cluster into 2 sub-clusters using K-means
+3. Stop when max_depth reached or cluster size < min_points
+4. Calculate Silhouette Score at each split
+5. Prune branches with poor separation (silhouette < 0.3)
+
+OUTPUT (JSON only):
+{{
+  "tree": {{
+    "level_0": {{
+      "name": "Todos os Leads",
+      "size": 500,
+      "children": [
+        {{
+          "name": "Macro Segmento A (Alto Valor)",
+          "size": 180,
+          "children": [
+            {{
+              "name": "Micro Segmento A1 (SP - Alto Valor + Alto Engajamento)",
+              "size": 95
+            }},
+            {{
+              "name": "Micro Segmento A2 (RJ - Alto Valor + Médio Engajamento)",
+              "size": 85
+            }}
+          ]
+        }},
+        {{
+          "name": "Macro Segmento B (Leads Quentes)",
+          "size": 150,
+          "children": [...]
+        }}
+      ]
+    }}
+  }},
+  "statistics": {{
+    "n_levels": 3,
+    "n_leaf_clusters": 6,
+    "avg_leaf_size": 83.3,
+    "best_depth_for_lead": "level_2"
+  }}
+}}
+
+Return ONLY valid JSON, no explanations.
+"""
+```
+
+---
+
+## Fase 5 — Auto-Interpretação de Segmentos
+
+### 5.1 Geração de Nomes Descritivos
+
+```python
+# Prompt para auto-labeling de segmentos
+
+PROMPT_INTERPRETATION = f"""
+You are a marketing intelligence expert.
+
+You will receive cluster centroids and characteristics.
+Your task: Generate descriptive, actionable names for each segment.
+
+INPUT: Cluster characteristics (avg values per feature)
+
+OUTPUT: Descriptive segment name following this pattern:
+"[VALUE_TYPE] [BEHAVIOR_TYPE] [GEO_TYPE]"
+
+VALUE TYPES: "Alto Valor", "Médio Valor", "Baixo Valor", "Lead Quente"
+BEHAVIOR TYPES: "Alto Engajamento", "Médio Engajamento", "Baixo Engajamento", "Alta Intenção"
+GEO TYPES: "[UF]", "Sudeste", "Norte", "Internacional"
+
+EXAMPLES:
+- ltv=0.9, behavior=0.85, geo=SP → "Segmento 0 - Alto Valor + Alto Engajamento (SP)"
+- ltv=0.7, behavior=0.6, geo=RS → "Segmento 1 - Médio Valor + Médio Engajamento (RJ)"
+- ltv=0.2, behavior=0.3, days=0, utm=tiktok → "Segmento 2 - Lead Quente + Baixo Engajamento (TikTok)"
+
+Return ONLY valid JSON with segment names, no explanations.
+"""
+```
+
+---
+
+## Fase 6 — Integração com D1 (Persistência)
+
+### 6.1 Schema da Tabela ml_segments
+
+```sql
+CREATE TABLE IF NOT EXISTS ml_segments (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  cluster_id INTEGER NOT NULL,
+  cluster_name TEXT NOT NULL,
+  clustering_algorithm TEXT NOT NULL,  -- 'kmeans', 'dbscan', 'hierarchical'
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  
+  -- Estatísticas do cluster
+  size INTEGER NOT NULL,
+  percentage REAL NOT NULL,
+  
+  -- Características médias
+  avg_ltv REAL,
+  avg_behavior_score REAL,
+  avg_engagement_score REAL,
+  avg_intention_level REAL,
+  
+  -- Características dominantes
+  dominant_countries TEXT,        -- JSON array: ["BR", "US"]
+  dominant_states TEXT,            -- JSON array: ["SP", "RJ"]
+  dominant_utm_sources TEXT,        -- JSON array: ["facebook", "google"]
+  dominant_features TEXT,            -- JSON array: ["ltv", "behavior_score"]
+  
+  -- Métricas de qualidade
+  silhouette_score REAL,
+  cohesion REAL,
+  separation REAL,
+  
+  -- Recomendações
+  action_recommendations TEXT,        -- JSON array
+  bid_recommendations TEXT,            -- JSON array
+  campaign_recommendations TEXT         -- JSON array
+);
+
+-- Índices para performance
+CREATE INDEX IF NOT EXISTS idx_ml_segments_created ON ml_segments(created_at);
+CREATE INDEX IF NOT EXISTS idx_ml_segments_cluster ON ml_segments(cluster_id);
+CREATE INDEX IF NOT EXISTS idx_ml_segments_algorithm ON ml_segments(clustering_algorithm);
+
+-- Tabela de associação lead ↔ segmento
+CREATE TABLE IF NOT EXISTS ml_segment_members (
+  lead_id TEXT NOT NULL,
+  cluster_id INTEGER NOT NULL,
+  confidence REAL NOT NULL,           -- 0-1 (quanto perto do centroide)
+  updated_at TEXT DEFAULT (datetime('now')),
+  PRIMARY KEY (lead_id, cluster_id, clustering_algorithm)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ml_segment_members_cluster ON ml_segment_members(cluster_id);
+CREATE INDEX IF NOT EXISTS idx_ml_segment_members_lead ON ml_segment_members(lead_id);
+```
+
+---
+
+## Fase 7 — Exposição de API REST
+
+### 7.1 Endpoint de Clustering
+
+```typescript
+// server-edge-tracker/functions/api/segmentation/cluster.ts
+
+export async function onRequestGet(context: EventContext<Env>) {
+  const { searchParams } = new URL(context.request.url);
+  
+  const algorithm = searchParams.get('algorithm') || 'kmeans';
+  const nClusters = parseInt(searchParams.get('n_clusters') || '5');
+  const clientVertical = searchParams.get('vertical') || 'general';
+  
+  // Extrair leads históricos do D1
+  const leads = await context.env.DB.prepare(`
+    SELECT id, ltv_class, behavior_score, engagement_score, intention_level,
+           days_since_lead, hour_of_day, is_weekend, is_business_hours,
+           country, state, utm_source, utm_medium
+    FROM leads 
+    WHERE created_at >= datetime('now', '-6 months')
+    ORDER BY created_at DESC
+  `).bind().all();
+  
+  // Feature Engineering
+  const features = extractFeatures(leads);
+  
+  // 1. Embeddings reais via embeddinggemma-300m
+  const profiles = sample.map(_buildLeadProfile);
+  const embRes   = await context.env.AI.run('@cf/baai/bge-m3', { text: profiles });
+  const vectors  = embRes.data; // vetores 768d
+
+  // 2. K-means vetorial real (JS puro, cosine distance)
+  const { assignments } = _kmeansRun(vectors, nClusters);
+  const silhouetteScore = _silhouette(vectors, assignments, nClusters);
+
+  // 3. Granite apenas para nomear clusters
+  const nameRes  = await context.env.AI.run('@cf/ibm-granite/granite-4.0-h-micro',
+    { messages: [{ role: 'user', content: getNamingPrompt(clusterStats) }], max_tokens: 800 }
+  );
+
+  // 4. Persistir no D1
+  await saveClusters(context.env.DB, clusters, algorithm);
+
+  return Response.json({
+    success: true,
+    algorithm,
+    engine: 'embeddinggemma-300m + kmeans vetorial',
+    n_clusters: nClusters,
+    silhouette_score: silhouetteScore,
+    clusters,
+    generated_at: new Date().toISOString()
+  });
+}
+```
+
+### 7.2 Endpoint de Consulta de Segmentos
+
+```typescript
+// server-edge-tracker/functions/api/segmentation/list.ts
+
+export async function onRequestGet(context: EventContext<Env>) {
+  const clusters = await context.env.DB.prepare(`
+    SELECT id, cluster_id, cluster_name, clustering_algorithm, size, percentage,
+           avg_ltv, avg_behavior_score, avg_engagement_score,
+           dominant_countries, dominant_states, dominant_utm_sources,
+           silhouette_score, action_recommendations
+    FROM ml_segments 
+    ORDER BY created_at DESC 
+    LIMIT 10
+  `).bind().all();
+  
+  return Response.json({
+    success: true,
+    clusters: clusters.map(c => ({
+      ...c,
+      dominant_countries: JSON.parse(c.dominant_countries || '[]'),
+      dominant_states: JSON.parse(c.dominant_states || '[]'),
+      dominant_utm_sources: JSON.parse(c.dominant_utm_sources || '[]'),
+      action_recommendations: JSON.parse(c.action_recommendations || '[]'),
+      bid_recommendations: JSON.parse(c.bid_recommendations || '[]'),
+      campaign_recommendations: JSON.parse(c.campaign_recommendations || '[]')
+    }))
+  });
+}
+```
+
+### 7.3 Endpoint de Anomalias (DBSCAN)
+
+```typescript
+// server-edge-tracker/functions/api/segmentation/outliers.ts
+
+export async function onRequestGet(context: EventContext<Env>) {
+  const outliers = await context.env.DB.prepare(`
+    SELECT l.id, l.email, l.behavior_score, l.days_since_lead,
+           l.country, l.state, l.utm_source, l.utm_medium,
+           sm.risk_score, sm.reason
+    FROM ml_segment_members sm
+    INNER JOIN leads l ON sm.lead_id = l.id
+    WHERE sm.clustering_algorithm = 'dbscan'
+      AND sm.confidence < 0.5  -- low confidence = anomaly
+    ORDER BY sm.updated_at DESC
+    LIMIT 50
+  `).bind().all();
+  
+  return Response.json({
+    success: true,
+    outliers: outliers,
+    total: outliers.length,
+    generated_at: new Date().toISOString()
+  });
+}
+```
+
+---
+
+## Inputs Recebidos do Orquestrador
+
+### Parâmetros de Configuração
+
+```json
+{
+  "client_vertical": "curso-online",
+  "features_to_use": ["ltv", "behavior_score", "engagement_score", "geo", "time"],
+  "clustering_algorithms": ["kmeans", "dbscan", "hierarchical"],
+  "default_n_clusters": 5,
+  "update_frequency": "weekly",  // re-clustering automático
+  "min_data_points": 100,  // mínimo de leads para clustering
+  "max_data_age_months": 6  // usar apenas últimos 6 meses
+}
+```
+
+---
+
+## Outputs para o Server Architect
+
+### Arquivos Criados
+
+```json
+{
+  "endpoints": [
+    "functions/api/segmentation/cluster.ts",
+    "functions/api/segmentation/list.ts", 
+    "functions/api/segmentation/outliers.ts"
+  ],
+  "database": [
+    "server-edge-tracker/schema-segmentation.sql"
+  ],
+  "documentation": [
+    "server-edge-tracker/SEGMENTATION-DOCS.md"
+  ],
+  "integration_points": [
+    "LTV Predictor Agent: enrich predictions with cluster_id",
+    "Dashboard Agent: visualize segments in charts",
+    "Attribution Agent: segment-level attribution"
+  ]
+}
+```
+
+### API Contracts
+
+```typescript
+interface SegmentationAPI {
+  // Criar novos clusters
+  'POST /api/segmentation/cluster': {
+    algorithm: 'kmeans' | 'dbscan' | 'hierarchical';
+    n_clusters?: number;
+    features?: string[];
+    client_vertical?: string;
+  };
+  
+  // Listar clusters existentes
+  'GET /api/segmentation/list': {
+    limit?: number;
+    algorithm?: string;
+  };
+  
+  // Consultar outliers/anomalias
+  'GET /api/segmentation/outliers': {
+    limit?: number;
+    confidence_threshold?: number;  // < 0.5 = high risk
+  };
+  
+  // Atualizar segmentos
+  'PUT /api/segmentation/update': {
+    cluster_id: number;
+    action_recommendations: string[];
+    bid_recommendations: string[];
+  };
+}
+```
+
+---
+
+## Integração com outros agentes
+
+| Quando | Agente |
+|---|---|
+| Após gerar clusters | → **Dashboard Agent** (visualização em gráficos) |
+| Segmentos criados | → **LTV Predictor Agent** (enricher predições com cluster_id) |
+| Outliers detectados | → **Security Enterprise Agent** (bloqueio automático) |
+| Recomendações geradas | → **Attribution Agent** (attribution por segmento) |
+| Clusters atualizados | → **Meta Agent** (campanhas segmentadas) |
+| Re-clustering semanal | → **Intelligence Scheduling** (cron automático) |
+
+---
+
+## Checklist de Conclusão
+
+```
+[ ] Feature Engineering Pipeline implementada
+[ ] K-means Clustering vetorial (embeddinggemma-300m + JS)
+[ ] DBSCAN Clustering para anomalias
+[ ] Hierarchical Clustering (drill-down)
+[ ] Auto-Interpretação de segmentos
+[ ] Schema D1 criado (ml_segments + ml_segment_members)
+[ ] API REST exposta (/api/segmentation/*)
+[ ] Integração com LTV Predictor Agent
+[ ] Integração com Dashboard Agent
+[ ] Integração com Security Enterprise Agent
+[ ] Documentação completa criada
+```
+
+---
+
+## Troubleshooting
+
+| Problema | Causa | Solução |
+|---|---|---|
+| `Clusters vazios` | Menos de `min_data_points` no D1 | Aumentar `max_data_age_months` ou aguardar mais dados |
+| `Silhouette Score < 0.3` | Clusters não são separáveis | Aumentar `n_clusters` ou usar features melhores |
+| `Outliers excessivos` | Epsilon/MinPts muito agressivos no DBSCAN | Ajustar parâmetros de detecção de anomalias |
+| `embeddinggemma timeout` | Batch maior que 100 perfis | Limitar sample a 100 leads (padrão atual) |
+| `vectors insuficientes` | embeddinggemma retornou menos vetores que nClusters | Reduzir nClusters ou verificar resposta da API |
+
+---
+
+## Exemplos de Uso
+
+### Caso 1: Segmentação Básica
+
+```bash
+curl -X POST "https://seudominio.com/api/segmentation/cluster" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "algorithm": "kmeans",
+    "n_clusters": 5,
+    "client_vertical": "curso-online"
+  }'
+
+# Retorna:
+{
+  "clusters": [
+    {
+      "cluster_id": 0,
+      "name": "Segmento 0 - Alto Valor + Alto Engajamento (SP)",
+      "size": 95,
+      "avg_ltv": 497.50,
+      "action_recommendations": [
+        "Priorizar remarketing em 24h",
+        "Criar lookalike audience de alto valor"
+      ]
+    },
+    ...
+  ]
+}
+```
+
+### Caso 2: Detecção de Anomalias
+
+```bash
+curl "https://seudominio.com/api/segmentation/outliers?limit=20"
+
+# Retorna:
+{
+  "outliers": [
+    {
+      "lead_id": "lead_123",
+      "risk_score": 0.92,
+      "reason": "behavior_score too high (> 95), suspicious bot activity"
+    }
+  ]
+}
+```
+
+---
+
+## 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*