BugPilot

Agente de Inteligencia de Errores de Ingeniería Impulsado por IA

Arquitectura Central: BugPilot se ejecuta en un pipeline limpio y desacoplado de extremo a extremo: React / Vite → FastAPI Backend → ReAct Orchestrator → Specialist Agents → MCP Client → MCP Server → 10 Read-Only Tools → SQLite Database (Synthetic Jira Data).

1. Arquitectura del Sistema

┌─────────────────────────────────────────────────────────────────────────────┐
│                       React / Vite Frontend (TypeScript)                     │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ HTTP REST API (JWT + RBAC + Tenant Isolation)
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          FastAPI Backend (Port 8000)                         │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        ReAct Orchestrator Agent                              │
│         Dynamic reasoning loop: Goal → LLM Decision → Tool Call →            │
│                    Observation → Next Decision → FINISH                     │
│               [Groq Primary API + Local Ollama Fallback]                    │
└───────────┬──────────────────────────┼──────────────────────────┬───────────┘
            │                          │                          │
            ▼                          ▼                          ▼
┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
│  Bug Analyst Agent   │   │ Trend Analyst Agent  │   │ Risk Analyst Agent   │
└───────────┬──────────┘   └──────────┬───────────┘   └──────────┬───────────┘
            │                          │                          │
            └──────────────────────────┼──────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                 MCP Client                                   │
│                 Dynamic tool discovery, timeout & sandboxing                 │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │ stdio JSON-RPC Transport
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          MCP Server (mcp_server)                            │
│                  Exposes 10 Strict READ-ONLY Tools                          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              AnalyticsService                                │
│              Deterministic metric calculation & statistical trends          │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 DataProvider Interface (SQLDataProvider / SQLite)            │
│                 Multi-tenant tenant isolation (`organization_id`)           │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    SQLite Database (`sqlite:///./bugpilot.db`)              │
│       Realistic Jira-style Defect Catalog, Sprints, Users & Audit Trails    │
└─────────────────────────────────────────────────────────────────────────────┘

Contrato Estricto de Acceso a Datos

✅ Agent → MCP Client → MCP Server → AnalyticsService → DataProvider → SQLite Data
❌ Agent → Direct Database Access (FORBIDDEN)
❌ Agent → Direct Data File Reading (FORBIDDEN)
❌ External Vector Database / RAG dependencies (FORBIDDEN)

Los agentes interactúan exclusivamente a través de herramientas MCP descubiertas dinámicamente, preservando el aislamiento (sandboxing) y la total capacidad de prueba.

Related MCP server: mcp-sqlite-manager

2. Referencia de las 10 Herramientas MCP

Las 10 herramientas son estrictamente de solo lectura, con alcance por inquilino (org_id), y se descubren dinámicamente mediante el protocolo MCP:

3. Orquestación ReAct Dinámica y Análisis Comparativo

El Agente Orquestador opera en un bucle genuino de Razonamiento + Acción (ReAct):

1. Guardrail de Intención y Fuera de Dominio — Las comprobaciones tempranas filtran consultas no técnicas sin desperdiciar invocaciones de LLM/herramientas.

2. Selección Dinámica de Herramientas — El LLM decide cada acción (CALL_TOOL, DELEGATE o FINISH) basándose en la consulta, las herramientas descubiertas dinámicamente y las observaciones acumuladas.

3. Inspección Iterativa de Múltiples Candidatos — Para consultas comparativas y de clasificación ("analizar errores de autenticación e identificar el issue de mayor riesgo"), search_bugs descubre candidatos, y el Orquestador invoca iterativamente get_bug en cada defecto candidato antes de permitir FINISH, asegurando que se recopile toda la evidencia técnica (causa raíz, radio de explosión, pasos de reproducción).

4. Puntuación de Riesgo Diferenciada Basada en Evidencia — Evalúa gravedad, prioridad, estado, entorno de producción, impacto de seguridad (por ejemplo, SOC2/secuestro de sesión) y causas raíz técnicas (por ejemplo, condición de carrera, caída). Genera puntuaciones no saturadas (0.0–99.5) para evitar empates artificiales 100/100.

5. Evaluación de Calidad del Agente de Reflexión — Valida los informes generados contra los datos MCP de referencia para prevenir alucinaciones y confirmar informes precisos.

4. Seguridad de Multiinquilino y RBAC

• Aislamiento de Inquilinos — Cada registro de base de datos (issues, sprints, users, audit_logs) está estrictamente limitado por organization_id (por ejemplo, org-acme). El acceso a datos entre organizaciones está bloqueado en las capas de repositorio y MCP.

• Control de Acceso Basado en Roles (RBAC):

  • Admin — Acceso completo, gestión de usuarios y administración de issues.

  • Ingeniero / Desarrollador — Crear, actualizar, transicionar y analizar issues.

  • Visor — Acceso de solo lectura a issues, análisis e informes.

• Gestión de Secretos — No hay claves secretas ni credenciales codificadas. Los secretos JWT, claves API y variables de entorno se cargan estrictamente desde .env y se excluyen del control de versiones.

5. Pila Tecnológica

6. Guía de Configuración y Ejecución

Requisitos Previos

• Python 3.12+

• Node.js 18+ (para el frontend)

• Una clave de API de Groq (opcional — la aplicación funciona sin ella, recurriendo a Ollama local o modo determinista)

1. Configuración del Backend

# Clone and enter project
git clone <repo-url> bugpilot
cd bugpilot

# Create and activate virtual environment
python -m venv .venv
# Windows: .\.venv\Scripts\activate | macOS/Linux: source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment (defaults to SQLite with zero setup)
cp .env.example .env
# Optional: add your GROQ_API_KEY to .env for live LLM responses

2. Ejecutar el Servidor MCP Independiente

# Windows
.\.venv\Scripts\python -m mcp_server.server

# macOS / Linux
.venv/bin/python -m mcp_server.server

3. Ejecutar el Backend FastAPI

uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

La base de datos se crea y se siembra automáticamente en el primer inicio — no se requiere paso de migración. Verifique que está saludable en http://127.0.0.1:8000/api/v1/health y http://127.0.0.1:8000/docs.

4. Construir y Ejecutar el Frontend

cd frontend
npm install
npm run dev

El servidor de desarrollo de Vite redirige las solicitudes /api al backend FastAPI en el puerto 8000 (ver vite.config.ts), por lo que ambos servicios deben ejecutarse juntos.

5. Ejecutar el Conjunto de Pruebas

# Run all unit and integration tests (329 tests)
pytest tests/unit tests/integration -q

Las llamadas al LLM se simulan durante las pruebas (ver tests/conftest.py), por lo que el conjunto se ejecuta de forma determinista sin una conexión a Groq/Ollama. Debido a que varias pruebas inician un subproceso nuevo del servidor MCP, el conjunto completo tarda unos minutos — esto es esperado, no un bloqueo.

7. Evaluación y Resultados de Calidad

BugPilot incluye un arnés de evaluación automatizado (evaluation/) que puntúa al agente frente a un conjunto de datos dorado de 23 consultas en 11 dimensiones — precisión de intención, selección de herramientas, fundamentación, tasa de alucinación, validez de trayectoria, seguimiento de instrucciones, seguridad y latencia — sin depender de calificación manual. Ejecútelo usted mismo con:

python -m evaluation.run_eval

Últimos resultados confirmados (evaluation_report.json):

Las dos consultas no superadas fueron casos límite de enrutamiento de intención (por ejemplo, una consulta clasificada como COMPONENT_ANALYSIS en lugar de METRIC), no alucinaciones o fallos — el agente nunca inventó información en ninguno de los 23 casos de prueba.

También se incluye una prueba de concurrencia/carga (1–50 usuarios simultáneos) a través de evaluation/load_tester.py. Con hasta 25 usuarios concurrentes, el sistema mantiene una tasa de error del 0%; con 50 usuarios concurrentes, la tasa de error aumenta a ~66%, lo que indica que la configuración actual de instancia única aún no está optimizada para tráfico de producción de alta concurrencia. Consulte Limitaciones Conocidas a continuación.

Nota sobre cifras de costo/tokens: los valores estimated_total_cost_usd y average_tokens_per_query en evaluation_report.json son estimaciones basadas en el recuento de palabras, no datos reales de uso de la API de Groq. Trátelos como indicadores aproximados, no como cifras de facturación.

8. Limitaciones Conocidas

En aras de la transparencia para los revisores:

• Límite de concurrencia — las pruebas de carga muestran un aumento pronunciado en la tasa de error con 50 usuarios simultáneos (ver arriba). Adecuado para uso en demostraciones/equipos pequeños tal como está; necesitaría agrupación de conexiones / ajuste asíncrono para tráfico de producción más grande.

• Seguimiento de tokens/costos estimado (no medido) — las cifras de costos del informe de evaluación son estimaciones heurísticas basadas en recuentos de palabras, no una contabilidad real de uso de API.

• Conjunto de evaluación dorado pequeño — la evaluación automatizada cubre 23 consultas representativas; una cobertura más amplia (más casos adversariales/de inyección de prompts, más casos extremos) fortalecería aún más la confianza.

• generate_pdf.py es una utilidad independiente de exportación de documentación con una ruta de salida predeterminada específica de Windows; pase un argumento de nombre de archivo explícito en macOS/Linux.