Autonomous-Bug-Explorer/.ralph/specs/legacy/ai-enrichment.md

ABE — AI Bug Report Enrichment Specification

Concepto

Este es el diferenciador más importante de ABE frente a cualquier competidor. Después de detectar una anomalía, ABE puede usar una LLM para enriquecer el bug report con un análisis inteligente: causa probable, impacto, sugerencia de fix, y prompt listo para usar con Claude/GPT.

IMPORTANTE: esto es una capa OPCIONAL sobre el core determinista.

El core engine nunca llama a LLMs. El enriquecimiento es post-procesado, ejecutado solo si el usuario lo configura.

Qué genera la IA

1. Root Cause Analysis

A partir del action trace, HTTP log, console errors y DOM snapshot, la IA propone la causa más probable del bug. Ejemplo: "The 500 error is likely caused by missing server-side validation of the email field. The server crashes when receiving an empty string where a valid email is expected."

2. User Impact Assessment

La IA evalúa el impacto del bug en términos de negocio: "This bug blocks users from completing registration. Any user who submits an empty email will encounter an unhandled server error, preventing account creation."

3. Suggested Fix

La IA propone un fix concreto: "Add server-side validation: check if email is present and valid before processing. Return a 422 with a descriptive error message instead of propagating the exception."

4. AI-Ready Debug Prompt

Un prompt completo listo para copiar y pegar en Claude/ChatGPT:

Bug Report Context:
- Type: HTTP 500 on form submission
- Steps to reproduce: [exact action trace]
- Error: [exact error message]
- Request: POST /api/register with body {"email": ""}
- Response: 500 Internal Server Error

Please analyze this bug and provide:
1. Root cause
2. Code fix
3. Test case to prevent regression

Implementación

Provider abstraction

interface IAIProvider {
  name: string;
  enrich(anomaly: IAnomaly, context: IEnrichmentContext): Promise<IAIEnrichment>;
}

interface IEnrichmentContext {
  domSnapshot: string;
  httpLog: IHttpResponse[];
  consoleErrors: string[];
  actionTrace: IAction[];
  pageTitle: string;
  url: string;
}

interface IAIEnrichment {
  rootCause: string;
  userImpact: string;
  suggestedFix: string;
  debugPrompt: string;
  confidence: 'low' | 'medium' | 'high';
  generatedAt: number;
  provider: string;
  model: string;
}

Providers implementados

• ClaudeProvider — usa Anthropic API (claude-3-5-haiku — rápido y barato)
• OpenAIProvider — usa OpenAI API (gpt-4o-mini)
• OllamaProvider — usa Ollama local (llama3.2 — sin API key, offline)

Cuándo se ejecuta

• Automático: si aiEnrichment.autoEnrich: true, se ejecuta tras cada anomalía high/critical
• Manual: botón "Enrich with AI" en AnomalyDetail page
• No bloquea: el bug report se guarda sin enriquecimiento, la IA lo añade async

Configuración en .env

ABE_AI_PROVIDER=claude         # claude | openai | ollama | none
ABE_AI_API_KEY=sk-ant-xxx      # Anthropic key (si provider=claude)
ABE_OPENAI_API_KEY=sk-xxx      # OpenAI key (si provider=openai)
ABE_OLLAMA_URL=http://localhost:11434  # (si provider=ollama)
ABE_AI_MODEL=claude-haiku-4-5  # modelo específico (opcional)
ABE_AI_AUTO_ENRICH=false       # default false para no incurrir en costes
ABE_AI_MIN_SEVERITY=high       # solo enriquecer high/critical automáticamente

Modelo de datos — añadir a SQLite

Añadir columna a anomalies

ALTER TABLE anomalies ADD COLUMN ai_enrichment_json TEXT;
ALTER TABLE anomalies ADD COLUMN ai_enriched_at INTEGER;

Frontend — AI panel en AnomalyDetail

Si la anomalía tiene ai_enrichment_json, mostrar panel "AI Analysis" con:

• 🔍 Root Cause (texto con ícono)
• 👥 User Impact (texto con ícono)
• 🔧 Suggested Fix (bloque de código si contiene código)
• 📋 "Copy debug prompt" button (copia el debugPrompt al clipboard)
• Badge: "Analyzed by Claude" / "Analyzed by GPT-4o-mini" / "Analyzed by Llama 3.2"
• Timestamp de cuándo se generó

Si no tiene enriquecimiento, mostrar botón "✨ Analyze with AI" que llama a: POST /api/anomalies/:id/enrich

Endpoint nuevo

POST /api/anomalies/:anomalyId/enrich

Dispara el enriquecimiento de una anomalía concreta (async). Response inmediata: { status: 'enriching' } Cuando termina, emite WebSocket event: anomaly:enriched { anomalyId, enrichment }

GET /api/anomalies/:anomalyId — actualizado

Incluye ai_enrichment si está disponible.