# 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
```typescript
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
```sql
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.