BugPilot

KI-gestützter Engineering-Bug-Intelligence-Agent

Kernarchitektur: BugPilot läuft auf einer sauberen, durchgängig entkoppelten Pipeline: React / Vite → FastAPI Backend → ReAct Orchestrator → Spezialisten-Agents → MCP Client → MCP Server → 10 schreibgeschützte Tools → SQLite-Datenbank (synthetische Jira-Daten).

1. Systemarchitektur

┌─────────────────────────────────────────────────────────────────────────────┐
│                       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    │
└─────────────────────────────────────────────────────────────────────────────┘

Strenger Datenzugriffsvertrag

✅ 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)

Agents interagieren ausschließlich über dynamisch entdeckte MCP-Tools, was Sandboxing und vollständige Testbarkeit gewährleistet.

Related MCP server: mcp-sqlite-manager

2. Referenz der 10 MCP-Tools

Alle 10 Tools sind streng schreibgeschützt, auf Mandantenebene begrenzt (org_id) und werden dynamisch über das MCP-Protokoll entdeckt:

3. Dynamische ReAct-Orchestrierung & vergleichende Analyse

Der Orchestrator-Agent arbeitet mit einer echten Reasoning + Action (ReAct)-Schleife:

1. Absichts- & Bereichsfremd-Schutz — Frühe Prüfungen filtern nicht-technische Anfragen, ohne LLM-/Tool-Aufrufe zu verschwenden.

2. Dynamische Tool-Auswahl — Das LLM entscheidet über jede Aktion (CALL_TOOL, DELEGATE oder FINISH) basierend auf der Anfrage, dynamisch entdeckten Tools und gesammelten Beobachtungen.

3. Iterative Mehrfachkandidaten-Prüfung — Bei vergleichenden und bewertenden Anfragen („Analysiere Authentifizierungsfehler und identifiziere das Issue mit dem höchsten Risiko") entdeckt search_bugs Kandidaten, und der Orchestrator ruft iterativ get_bug für jeden Kandidatenfehler auf, bevor FINISH erlaubt wird, um sicherzustellen, dass vollständige technische Nachweise (Ursache, Schadensradius, Reproduktionsschritte) gesammelt werden.

4. Differenzierte, nachweisgestützte Risikobewertung — Bewertet Schweregrad, Priorität, Status, Produktionsumgebung, Sicherheitsauswirkungen (z. B. SOC2/Session-Hijacking) und technische Ursachen (z. B. Race Condition, Absturz). Erzeugt nicht-sättigende Bewertungen (0.0–99.5), um künstliche 100/100-Gleichstände zu vermeiden.

5. Qualitätsbewertung durch Reflexions-Agent — Validiert generierte Berichte anhand der Ground-Truth-MCP-Daten, um Halluzinationen zu verhindern und eine korrekte Berichterstattung zu bestätigen.

4. Multi-Tenancy & RBAC-Sicherheit

• Mandantenisolierung — Jeder Datenbankeintrag (issues, sprints, users, audit_logs) ist streng durch organization_id (z. B. org-acme) begrenzt. Datenzugriff über Organisationsgrenzen hinweg wird auf Repository- und MCP-Ebene blockiert.

• Rollenbasierte Zugriffskontrolle (RBAC):

  • Admin — Vollzugriff, Benutzerverwaltung und Issue-Administration.

  • Ingenieur / Entwickler — Erstellen, Aktualisieren, Überführen und Analysieren von Issues.

  • Betrachter — Schreibgeschützter Zugriff auf Issues, Analysen und Berichte.

• Geheimnisverwaltung — Keine geheimen Schlüssel oder Anmeldeinformationen sind fest codiert. JWT-Geheimnisse, API-Schlüssel und Umgebungsvariablen werden strikt aus .env geladen und von der Versionskontrolle ausgeschlossen.

5. Technologie-Stack

6. Einrichtungs- & Ausführungsanleitung

Voraussetzungen

• Python 3.12+

• Node.js 18+ (für das Frontend)

• Ein Groq-API-Schlüssel (optional — die App läuft auch ohne, mit Fallback auf lokales Ollama oder deterministischen Modus)

1. Backend-Einrichtung

# 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. Eigenständigen MCP-Server ausführen

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

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

3. FastAPI-Backend ausführen

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

Die Datenbank wird beim ersten Start automatisch erstellt und befüllt — kein Migrationsschritt erforderlich. Überprüfen Sie die Funktionsfähigkeit unter http://127.0.0.1:8000/api/v1/health und http://127.0.0.1:8000/docs.

4. Frontend erstellen & ausführen

cd frontend
npm install
npm run dev

Der Vite-Entwicklungsserver leitet /api-Anfragen an das FastAPI-Backend auf Port 8000 weiter (siehe vite.config.ts), daher müssen beide Dienste gleichzeitig laufen.

5. Testsuite ausführen

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

LLM-Aufrufe werden während der Tests simuliert (siehe tests/conftest.py), sodass die Suite deterministisch ohne Groq-/Ollama-Verbindung läuft. Da mehrere Tests einen neuen MCP-Server-Subprozess starten, dauert die gesamte Suite einige Minuten — dies ist erwartet und kein Hängenbleiben.

7. Evaluierung & Qualitätsergebnisse

BugPilot wird mit einem automatisierten Evaluierungs-Framework (evaluation/) ausgeliefert, das den Agenten anhand eines goldenen Datensatzes mit 23 Abfragen in 11 Dimensionen bewertet — Absichtsgenauigkeit, Tool-Auswahl, Grounding, Halluzinationsrate, Trajektorien-Gültigkeit, Befolgungsgenauigkeit, Sicherheit und Latenz — ohne manuelle Bewertung. Führen Sie es selbst aus mit:

python -m evaluation.run_eval

Letzte festgeschriebene Ergebnisse (evaluation_report.json):

Die beiden nicht bestandenen Abfragen waren Grenzfälle der Absichtsweiterleitung (z. B. eine als COMPONENT_ANALYSIS statt METRIC klassifizierte Abfrage), keine Halluzinationen oder Fehler — der Agent hat in keinem der 23 Testfälle Informationen erfunden.

Ein Parallelitäts-/Lasttest (1–50 gleichzeitige Benutzer) ist ebenfalls über evaluation/load_tester.py enthalten. Bei bis zu 25 gleichzeitigen Benutzern hält das System eine Fehlerrate von 0%; bei 50 gleichzeitigen Benutzern steigt die Fehlerrate auf ~66%, was darauf hindeutet, dass die aktuelle Einzelinstanz-Einrichtung noch nicht für hohen Produktionsdatenverkehr optimiert ist. Siehe Bekannte Einschränkungen unten.

Hinweis zu Kosten/Token-Zahlen: Die Werte estimated_total_cost_usd und average_tokens_per_query in evaluation_report.json sind wortzählbasierte Schätzungen, keine tatsächlichen Groq-API-Nutzungsdaten. Behandeln Sie sie als grobe Indikatoren, nicht als Abrechnungszahlen.

8. Bekannte Einschränkungen

Im Interesse der Transparenz für Prüfer:

• Parallelitätsobergrenze — Lasttests zeigen einen starken Anstieg der Fehlerrate bei 50 gleichzeitigen Benutzern (siehe oben). Für Demo-/Kleinteam-Nutzung geeignet; für größeren Produktionsdatenverkehr wären Connection-Pooling/Async-Optimierungen erforderlich.

• Geschätztes (nicht gemessenes) Token-/Kosten-Tracking — Die Kostenangaben im Evaluierungsbericht sind heuristische Schätzungen basierend auf Wortzahlen, keine tatsächliche API-Nutzungsabrechnung.

• Kleiner goldener Evaluierungsdatensatz — Die automatisierte Evaluierung deckt 23 repräsentative Abfragen ab; eine breitere Abdeckung (mehr adversarial-/Prompt-Injection-Fälle, mehr Grenzfälle) würde das Vertrauen weiter stärken.

• generate_pdf.py ist ein eigenständiges Dokumentationsexport-Dienstprogramm mit einem Windows-spezifischen Standardausgabepfad; übergeben Sie unter macOS/Linux ein explizites Dateinamenargument.

---.