docs: enterprise refactor plan with ralph specs
This commit is contained in:
debian
130
.ralph/specs/legacy/ai-enrichment.md
Normal file
130
.ralph/specs/legacy/ai-enrichment.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user