100 lines
5.4 KiB
Markdown
100 lines
5.4 KiB
Markdown
# Retrospektive — Epic 5: Tools & God Mode (Phase 4)
|
|
|
|
<!-- 🏃 Facilitiert von BMAD SM Skill — Agent: Bob (Scrum Master) -->
|
|
<!-- Skill Command: /bmad-agent-bmm-sm → [ER] Epic Retrospective -->
|
|
<!-- Workflow: _bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml -->
|
|
|
|
**Datum:** 2026-03-12
|
|
**Epic:** Epic 5 — Tools & God Mode (Phase 4)
|
|
**Status:** Abgeschlossen — 4/4 Stories erledigt
|
|
**Facilitiert von:** Bob (🏃 Scrum Master)
|
|
|
|
---
|
|
|
|
## 1. Epic-Zusammenfassung
|
|
|
|
**Ziel:** Tavily-Web-Suche, PDF-Reader mit ChromaDB, und Human-in-the-Loop via `interrupt_before`.
|
|
|
|
**Stories abgeschlossen:**
|
|
- ✅ 5.1: Tavily Web-Suche als Agent-Tool
|
|
- ✅ 5.2: PDF-Upload & ChromaDB-Ingestion
|
|
- ✅ 5.3: God Mode — Human-in-the-Loop
|
|
- ✅ 5.4: Run-Verlauf (History)
|
|
|
|
---
|
|
|
|
## 2. Was lief gut? (Keep)
|
|
|
|
**Technische Entscheidungen:**
|
|
- **LangChain `@tool`-Decorator** macht Tool-Implementierungen direkt LLM-kompatibel — kein Adapter-Boilerplate nötig
|
|
- **Lazy Imports** in `web_search.py` und `pdf_reader.py` verhindern `ImportError` wenn Pakete fehlen oder API-Keys nicht gesetzt sind
|
|
- **`create_web_search_tool()` / `create_pdf_search_tool()` Factory-Pattern** ermöglicht bedingtes Tool-Binding — Tools werden nur gebunden wenn die Voraussetzungen erfüllt sind
|
|
- **LangGraph `interrupt_before`** — God Mode funktioniert ohne eigenes Pause-Protokoll; der LangGraph-Mechanismus übernimmt das gesamte State-Handling
|
|
- **ChromaDB `_collection_cache`** verhindert mehrfache Client-Initialisierungen pro Request
|
|
- **`council_runs`-PostgreSQL-Tabelle** mit `status`, `final_draft`, `critic_score` ermöglicht vollständigen Run-Verlauf ohne In-Memory-Abhängigkeit
|
|
|
|
**Prozess:**
|
|
- Story 5.4 (History) konnte parallel zu 5.3 (God Mode) entwickelt werden — keine Abhängigkeit
|
|
- Alle Tool-Tests sind vollständig gemockt — kein Tavily-/ChromaDB-Aufruf in CI nötig
|
|
- God-Mode-Tests mit LangGraph-Checkpointer komplett gemockt — stabile Tests
|
|
|
|
---
|
|
|
|
## 3. Was lief nicht gut? (Drop / Improve)
|
|
|
|
**Technisch:**
|
|
- `_collection_cache` in `pdf_reader.py` ist ein Modul-Level-Dict — bei hoher Last und vielen Collections könnte Speicher wachsen; TTL fehlt
|
|
- `god_mode_states`-Dict in `dynamic_graph_builder.py` ist In-Memory — bei Server-Neustart gehen alle pausierten God-Mode-Runs verloren
|
|
- PDF-Chunks mit `words`-basiertem Split beachtet keine semantischen Grenzen (Sätze, Absätze) — könnte zu abgeschnittenen Kontexten führen
|
|
- `POST /api/councils/upload-pdf` speichert keine Referenz auf die Collection-Zuordnung zu einem Blueprint
|
|
|
|
**Prozess:**
|
|
- Story 5.3 (God Mode) war die komplexeste Story des gesamten Projekts — hätte in zwei Sub-Stories aufgeteilt werden können (Backend God Mode / Frontend Overlay)
|
|
|
|
---
|
|
|
|
## 4. Lernerkenntnisse
|
|
|
|
| Erkenntnis | Anwendung / Empfehlung |
|
|
|------------|----------------------|
|
|
| LangGraph's `interrupt_before` ist sehr einfach zu aktivieren — aber die State-Persistenz (Checkpointer) ist der eigentliche Komplexitätspunkt | Für Produktions-God-Mode: `PostgresSaver`-Checkpointer statt In-Memory verwenden |
|
|
| Tool-Factory-Pattern trennt Konfiguration (API-Key prüfen) von Ausführung (Tool aufrufen) | Für zukünftige Tools immer Factory-Funktion + @tool-Funktion getrennt implementieren |
|
|
| ChromaDB-Collections sollten an einen Blueprint-Run gebunden sein | `collection_name = f"run_{run_id}"` wäre eine sauberere Isolation |
|
|
| `UploadFile.content_type` ist browser-abhängig | Immer auch Dateiendung prüfen als Fallback (`filename.endswith(".pdf")`) |
|
|
|
|
---
|
|
|
|
## 5. Post-MVP Backlog
|
|
|
|
| Priorität | Verbesserung | Kategorie |
|
|
|-----------|-------------|-----------|
|
|
| Hoch | `PostgresSaver`-Checkpointer für God Mode (Persistenz über Neustarts) | Tech Debt |
|
|
| Hoch | PDF-Collection pro Blueprint-Run isolieren | Feature |
|
|
| Mittel | Sentence-basierter Text-Splitter statt Word-basiertem | Quality |
|
|
| Mittel | `god_mode_states`-Dict durch Redis oder DB ersetzen | Scalability |
|
|
| Niedrig | CORS `allow_origins` via `ALLOWED_ORIGINS`-Env konfigurierbar machen | Security |
|
|
| Niedrig | `_collection_cache` TTL / maximale Collection-Anzahl | Stability |
|
|
|
|
---
|
|
|
|
## 6. Projekt-Abschluss-Retrospektive
|
|
|
|
**Alle 5 Epics abgeschlossen. Das MVP von CouncilOS ist implementiert.**
|
|
|
|
### Was das Projekt gelehrt hat:
|
|
|
|
1. **LangGraph's Zyklus-Unterstützung** ist der Kern des Mehrwerts — kein anderes Framework ermöglicht so einfach echte Feedback-Schleifen
|
|
2. **BMAD-Method** hat die Planung strukturiert und sichergestellt, dass Backend-First-Reihenfolge eingehalten wurde
|
|
3. **TypedDict + `operator.add`-Reducer** ist ein elegantes Muster für akkumulativen State — keine Race Conditions möglich
|
|
4. **Factory-Pattern für Tools** und **`@tool`-Decorator** von LangChain ermöglichen saubere, testbare Tool-Integration
|
|
5. **WebSockets + `interrupt_before`** sind das Fundament für eine responsive, interaktive AI-Erfahrung
|
|
|
|
### Quantitative Zusammenfassung:
|
|
- **5 Epics, 18 Stories** — alle `done`
|
|
- **125 Backend-Tests** (pytest, alle grün, LLMs vollständig gemockt)
|
|
- **26 Frontend-Tests** (vitest, alle grün)
|
|
- **0 echte API-Calls in Tests**
|
|
|
|
---
|
|
|
|
*Bob (Scrum Master): "Epic 5 schließt das MVP ab. Besonders beeindruckend: God Mode mit LangGraph's `interrupt_before` war konzeptuell elegant und in der Praxis überraschend einfach zu implementieren. Das BMAD-Method-Vorgehen — Zyklen über Story→Dev→Review — hat die Codequalität nachhaltig verbessert. Herzlichen Glückwunsch zum CouncilOS-MVP!"*
|