279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
---
|
||
stepsCompleted:
|
||
- step-v-01-discovery
|
||
- step-v-02-structure
|
||
- step-v-03-goals
|
||
- step-v-04-requirements
|
||
- step-v-05-measurability-validation
|
||
- step-v-06-traceability-validation
|
||
- step-v-10-smart-validation
|
||
- step-v-11-holistic-quality-validation
|
||
- step-v-12-completeness-validation
|
||
inputDocuments:
|
||
- README.md
|
||
- CLAUDE.md
|
||
- _bmad-output/planning-artifacts/product-brief.md
|
||
workflowType: 'prd'
|
||
bmadSkill: 'PM Agent (John) — /bmad-agent-bmm-pm → [CP] Create PRD'
|
||
bmadWorkflow: '_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md'
|
||
---
|
||
|
||
<!-- 📋 Generated by BMAD PM Skill — Agent: John (Product Manager) -->
|
||
<!-- Skill Command: /bmad-agent-bmm-pm → [CP] Create PRD -->
|
||
<!-- Workflow: _bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md -->
|
||
|
||
# Product Requirements Document — CouncilOS (KI-Rat Baukasten)
|
||
|
||
**Autor:** John (📋 BMAD PM Agent)
|
||
**Datum:** 2026-03-12
|
||
**Version:** 1.0.0
|
||
**Status:** Genehmigt — Bereit für Architektur
|
||
|
||
---
|
||
|
||
## 1. Projekt-Überblick
|
||
|
||
### 1.1 Problemstellung
|
||
|
||
Aktuelle KI-Tools (wie ChatGPT) arbeiten linear. Wenn ein Nutzer ein komplexes Ergebnis will — z. B. einen perfekten Blogartikel, rechtssichere PR-Texte oder lauffähigen Code — muss er den Output ständig manuell lesen, Fehler finden und die KI in endlosen Chat-Verläufen korrigieren. Das kostet Zeit und erfordert extrem gutes „Prompting".
|
||
|
||
### 1.2 Lösung
|
||
|
||
**CouncilOS** ist eine visuelle No-Code-Plattform. Anstatt selbst mit der KI zu chatten, baut der Nutzer sich einen eigenen **„KI-Rat" (Multi-Agenten-System)**. Der Nutzer definiert verschiedene KI-Experten, gibt ihnen Werkzeuge (Internet, PDF-Reader) und legt per Drag & Drop fest, in welcher Reihenfolge sie Dokumente bearbeiten, kritisieren und überarbeiten.
|
||
|
||
### 1.3 Alleinstellungsmerkmal (USP)
|
||
|
||
Im Gegensatz zu bestehenden Tools arbeiten die KIs in **Endlosschleifen (Zyklen)**. Eine Kritiker-KI kann ein Dokument so lange an die Master-KI zurückweisen, bis es perfekt ist, ohne dass der Mensch eingreifen muss. Wahlweise kann der Mensch als „Vorsitzender des Rates" jeden Schritt abnicken (God-Mode / Human-in-the-Loop).
|
||
|
||
---
|
||
|
||
## 2. Ziele und Erfolgsmetriken
|
||
|
||
### 2.1 Geschäftsziele
|
||
|
||
| Ziel | Messgröße | Zielwert |
|
||
|------|-----------|---------- |
|
||
| Nutzer können komplexe KI-Pipelines ohne Code aufbauen | Anzahl erfolgreich abgeschlossener Council-Runs | ≥ 100 Runs/Woche (Phase 3 Launch) |
|
||
| Qualitätsverbesserung durch iterative Schleifen | Durchschnittlicher Critic-Score bei Abschluss | ≥ 8/10 |
|
||
| Transparente KI-Nutzung | Anteil der Nutzer, die God-Mode verwenden | ≥ 20 % aller Runs |
|
||
|
||
### 2.2 Nutzerziele
|
||
|
||
- Nutzer können in < 5 Minuten einen KI-Rat aus Standard-Agents zusammenstellen und ausführen.
|
||
- Nutzer sehen in Echtzeit, welcher Agent gerade arbeitet.
|
||
- Im God Mode können Nutzer an jedem Entscheidungspunkt eingreifen.
|
||
|
||
### 2.3 Technische Ziele
|
||
|
||
- Backend-Latenz für einen einzelnen Agent-Node < 30 Sekunden (bei normalen LLM-Antwortzeiten).
|
||
- WebSocket-Events werden innerhalb von 500 ms nach Node-Eintritt gesendet.
|
||
- Das System unterstützt bis zu 10 gleichzeitige Council-Runs.
|
||
|
||
---
|
||
|
||
## 3. Zielgruppen
|
||
|
||
### 3.1 Primäre Nutzer
|
||
|
||
**Content-Ersteller und Marketing-Teams**
|
||
- Erstellen Rohtexte, die von KI-Experten (SEO, Faktenprüfung, Lektor) in Schleifen verfeinert werden.
|
||
- Technisches Know-how: gering bis mittel.
|
||
- Kernbedürfnis: Qualitätssteigerung ohne manuelles Nacharbeiten.
|
||
|
||
**Software-Entwickler und Architekten**
|
||
- Lassen Code durch Architekten-KI, Tester-KI und Doku-KI überprüfen.
|
||
- Technisches Know-how: hoch.
|
||
- Kernbedürfnis: Automatisierte Code-Review-Schleifen.
|
||
|
||
### 3.2 Sekundäre Nutzer
|
||
|
||
**Analysten und Researcher**
|
||
- Lassen 100-seitige PDFs durch KI-Ketten zusammenfassen und analysieren.
|
||
- Kernbedürfnis: Informationsextraktion aus langen Dokumenten.
|
||
|
||
---
|
||
|
||
## 4. Funktionale Anforderungen
|
||
|
||
### FR-01: Visueller Canvas (Rat-Architekt)
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-01.1 | Der Nutzer kann Agent-Nodes per Drag & Drop auf den Canvas ziehen. | MUSS |
|
||
| FR-01.2 | Ein Klick auf einen Node öffnet ein Einstellungs-Panel (Name, System-Prompt, LLM-Modell, Tools). | MUSS |
|
||
| FR-01.3 | Der Nutzer kann lineare Edges (Pfeile) zwischen Nodes ziehen. | MUSS |
|
||
| FR-01.4 | Der Nutzer kann bedingte Edges erstellen (mit Routing-Label). | MUSS |
|
||
| FR-01.5 | Der Nutzer kann den Council unter einem Namen speichern. | MUSS |
|
||
| FR-01.6 | Der Nutzer kann einen gespeicherten Council laden und bearbeiten. | SOLL |
|
||
| FR-01.7 | Der Canvas unterstützt Export des Blueprints als JSON-Datei. | SOLL |
|
||
|
||
### FR-02: Council-Ausführung (Konferenzzimmer)
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-02.1 | Der Nutzer kann einen Prompt-Text als Eingabe für den Council angeben. | MUSS |
|
||
| FR-02.2 | Der Nutzer kann ein PDF hochladen, dessen Inhalt als Eingabe dient. | SOLL |
|
||
| FR-02.3 | Der Nutzer kann zwischen Auto-Pilot und God Mode wählen. | MUSS |
|
||
| FR-02.4 | Im Auto-Pilot läuft der Council autonom bis zum Abschluss. | MUSS |
|
||
| FR-02.5 | Im God Mode pausiert der Council vor jedem Agent und wartet auf Genehmigung. | MUSS |
|
||
| FR-02.6 | Der Nutzer sieht das fertige Dokument nach Abschluss des Councils. | MUSS |
|
||
| FR-02.7 | Der Nutzer kann vergangene Council-Runs in einem Verlauf einsehen. | SOLL |
|
||
|
||
### FR-03: Echtzeit-Updates (WebSocket)
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-03.1 | Der aktive Agent-Node leuchtet/pulsiert im Canvas (live). | MUSS |
|
||
| FR-03.2 | WebSocket-Events enthalten: `node_name`, `status` (`running`/`completed`/`done`). | MUSS |
|
||
| FR-03.3 | Bei Abschluss eines Runs wird ein `done`-Event gesendet. | MUSS |
|
||
|
||
### FR-04: God Mode / Human-in-the-Loop
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-04.1 | Im God Mode erscheint ein Popup mit dem Agent-Namen, Grund und Approve/Reject/Modify-Buttons. | MUSS |
|
||
| FR-04.2 | „Approve" setzt die Ausführung am nächsten Node fort. | MUSS |
|
||
| FR-04.3 | „Reject" bricht den Run ab und markiert ihn als fehlgeschlagen. | MUSS |
|
||
| FR-04.4 | „Modify" erlaubt die Bearbeitung des aktuellen Drafts vor Fortsetzung. | SOLL |
|
||
|
||
### FR-05: Agent-Konfiguration
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-05.1 | Jeder Agent kann ein individuelles LLM-Modell zugewiesen bekommen (Claude 3.5 Sonnet, GPT-4o, lokal). | MUSS |
|
||
| FR-05.2 | Jeder Agent kann optional Web-Suche aktiviert bekommen (Tavily). | SOLL |
|
||
| FR-05.3 | Jeder Agent kann optional PDF-Reader aktiviert bekommen (ChromaDB). | SOLL |
|
||
| FR-05.4 | Agent-Konfigurationen können gespeichert und wiederverwendet werden. | SOLL |
|
||
|
||
### FR-06: Blueprint-Verwaltung (CRUD)
|
||
|
||
| ID | Anforderung | Priorität |
|
||
|----|-------------|-----------|
|
||
| FR-06.1 | Blueprints können erstellt, gelesen, aktualisiert und gelöscht werden (REST API). | MUSS |
|
||
| FR-06.2 | Blueprints werden in PostgreSQL als JSONB gespeichert. | MUSS |
|
||
| FR-06.3 | Jeder Blueprint hat ein `version`-Feld. | MUSS |
|
||
|
||
---
|
||
|
||
## 5. Nicht-funktionale Anforderungen
|
||
|
||
### NFR-01: Performance
|
||
|
||
| ID | Anforderung |
|
||
|----|-------------|
|
||
| NFR-01.1 | WebSocket-Events werden innerhalb von 500 ms nach Node-Eintritt gesendet. |
|
||
| NFR-01.2 | Blueprint-CRUD-Endpunkte antworten in < 200 ms (P95). |
|
||
| NFR-01.3 | Das System unterstützt ≥ 10 parallele Council-Runs. |
|
||
|
||
### NFR-02: Sicherheit
|
||
|
||
| ID | Anforderung |
|
||
|----|-------------|
|
||
| NFR-02.1 | API-Keys (Anthropic, OpenAI, Tavily) werden ausschließlich in Umgebungsvariablen gespeichert, nie im Code. |
|
||
| NFR-02.2 | Keine echten LLM-API-Aufrufe in CI/CD-Tests. |
|
||
| NFR-02.3 | CORS ist auf bekannte Origins beschränkt (in Produktion). |
|
||
|
||
### NFR-03: Wartbarkeit
|
||
|
||
| ID | Anforderung |
|
||
|----|-------------|
|
||
| NFR-03.1 | Backend-Testabdeckung: ≥ 80 % für `agents/`, ≥ 90 % für `state.py` und `services/graph_builder.py`. |
|
||
| NFR-03.2 | Datenbankmigrationen werden mit Alembic verwaltet. |
|
||
| NFR-03.3 | Der LangGraph-Graph wird ab Phase 3 dynamisch aus Blueprint-JSON gebaut (kein hartcodierter Graph in Produktion). |
|
||
|
||
### NFR-04: Skalierbarkeit
|
||
|
||
| ID | Anforderung |
|
||
|----|-------------|
|
||
| NFR-04.1 | LangGraph-Runs werden in asyncio-Thread-Pools ausgeführt, um den FastAPI Event Loop nicht zu blockieren. |
|
||
| NFR-04.2 | WebSocket-Sessions sind pro `run_id` isoliert — keine Event-Übertragung zwischen Sessions. |
|
||
|
||
---
|
||
|
||
## 6. Technische Abhängigkeiten
|
||
|
||
| Komponente | Technologie | Version |
|
||
|------------|-------------|---------|
|
||
| KI-Orchestrierung | LangGraph (Python) | ≥ 0.2.x |
|
||
| Backend-API | FastAPI | ≥ 0.110 |
|
||
| Frontend-Framework | Next.js + React Flow | Next.js 14+, React Flow 12+ |
|
||
| Datenbank | PostgreSQL | 16 |
|
||
| Vektor-DB | ChromaDB (lokal) | ≥ 0.5 |
|
||
| LLMs | Anthropic Claude 3.5 Sonnet, OpenAI GPT-4o | via API |
|
||
| Web-Suche | Tavily Search API | — |
|
||
| PDF-Verarbeitung | PyPDF + LangChain Text Splitter | — |
|
||
|
||
---
|
||
|
||
## 7. Annahmen und Einschränkungen
|
||
|
||
### Annahmen
|
||
|
||
- Nutzer haben gültige API-Keys für Anthropic und/oder OpenAI.
|
||
- Die Anwendung wird zunächst lokal (Docker Compose) und später in der Cloud betrieben.
|
||
- Ein PDF-Upload ist auf ≤ 50 MB begrenzt.
|
||
|
||
### Einschränkungen
|
||
|
||
- Zyklen sind First-Class — der Graph darf nicht zu einem DAG vereinfacht werden.
|
||
- State ist die einzige Quelle der Wahrheit — Agents speichern keinen internen Zustand.
|
||
- Human-in-the-Loop erfolgt ausschließlich über LangGraphs `interrupt_before` — kein eigener Pause-Mechanismus.
|
||
- WebSocket für Echtzeit-Updates ist Pflicht — Polling ist nicht akzeptabel.
|
||
|
||
---
|
||
|
||
## 8. Entwicklungs-Roadmap (Phasen)
|
||
|
||
| Phase | Ziel | Status |
|
||
|-------|------|--------|
|
||
| Phase 1 — LangGraph Engine (Backend MVP) | Hartcodierter Testgraph, CouncilState, Routing-Logik | ✅ Abgeschlossen |
|
||
| Phase 2 — Visueller Baukasten (Frontend MVP) | React Flow Canvas, Custom Nodes/Edges, Blueprint-Parser, PostgreSQL-Speicherung | ✅ Abgeschlossen |
|
||
| Phase 3 — Integration (Frontend ↔ Backend) | Dynamischer Graph aus JSON-Blueprint, WebSocket-Events, Frontend-Ausgabe | ✅ Abgeschlossen |
|
||
| Phase 4 — Tools & God Mode (Enterprise) | Tavily Search, PyPDF + ChromaDB, Human-in-the-Loop UI | ✅ Abgeschlossen |
|
||
|
||
---
|
||
|
||
## 9. Typische Use-Cases
|
||
|
||
### Use-Case 1: Content-Rat
|
||
|
||
```
|
||
User Input → Master-KI (schreibt Rohfassung)
|
||
→ Kritiker-KI (prüft Fakten & SEO)
|
||
→ [Wenn Note < 8: zurück zu Master-KI]
|
||
→ Lektor-KI (formatiert für Social Media)
|
||
```
|
||
|
||
### Use-Case 2: Programmier-Rat
|
||
|
||
```
|
||
User Input → Architekt-KI (schreibt Code)
|
||
→ Tester-KI (sucht Bugs)
|
||
→ [Wenn Bugs: zurück zum Architekten]
|
||
→ Doku-KI (schreibt das README)
|
||
```
|
||
|
||
### Use-Case 3: Analyse-Rat
|
||
|
||
```
|
||
PDF-Upload → Researcher-KI (liest 100-seitiges PDF)
|
||
→ Analyst-KI (extrahiert Kerndaten)
|
||
→ Strategie-KI (schreibt Zusammenfassung)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Glossar
|
||
|
||
| Begriff | Definition |
|
||
|---------|------------|
|
||
| Council | Eine konfigurierte Gruppe von KI-Agents, die zusammenarbeiten |
|
||
| Blueprint | Die gespeicherte JSON-Konfiguration eines Councils |
|
||
| Council Run | Eine einzelne Ausführung eines Councils |
|
||
| CouncilState | Das zentrale TypedDict, das zwischen allen Agents weitergegeben wird |
|
||
| God Mode | Ausführungsmodus mit menschlicher Genehmigung an jedem Entscheidungspunkt |
|
||
| Auto-Pilot | Ausführungsmodus ohne menschlichen Eingriff |
|
||
| Node | Ein einzelner KI-Agent im Graph |
|
||
| Edge | Eine Verbindung zwischen zwei Agents (linear oder bedingt) |
|
||
| Critic Score | Die numerische Bewertung (0–10) des Kritiker-Agents |
|
||
| Route Decision | Das Routing-Signal (`rework`\|`approve`\|benutzerdefiniert) |
|