WP25-v3.0.0-Dokumentation
This commit is contained in:
1 parent
124849c580
commit
0d2469f8fa
13 files changed
+767
-164
No files matched your search
@@ -1,30 +1,32 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, architect
|
||||
scope: backend, chat, llm_service, traffic_control, resilience
|
||||
scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag
|
||||
status: active
|
||||
version: 2.9.1
|
||||
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
|
||||
version: 2.9.3
|
||||
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.4.2), WP-25 Agentic Multi-Stream RAG und WP-20 Resilienz-Logik."
|
||||
---
|
||||
|
||||
# Chat Backend & Traffic Control
|
||||
# Chat Backend & Agentic Multi-Stream RAG
|
||||
|
||||
## 1. Hybrid Router (Decision Engine)
|
||||
## 1. Hybrid Router & Intent-basiertes Routing (WP-25)
|
||||
|
||||
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch über die Strategie und nutzt den `LLMService` zur provider-agnostischen Generierung.
|
||||
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert.
|
||||
|
||||
### 1.1 Intent-Erkennung (Logik)
|
||||
### 1.1 Intent-Erkennung (Hybrid-Modus)
|
||||
|
||||
Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
|
||||
Der Router nutzt einen **Hybrid-Modus** mit Keyword-Fast-Path und LLM-Slow-Path:
|
||||
|
||||
1. **Question Detection (Regelbasiert):**
|
||||
* Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich).
|
||||
* Wenn positiv: **RAG Modus** (Interview wird blockiert).
|
||||
2. **Keyword Scan (Fast Path):**
|
||||
* Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen).
|
||||
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**.
|
||||
3. **LLM Fallback (Slow Path):**
|
||||
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`.
|
||||
1. **Keyword Fast-Path (Sofortige Erkennung):**
|
||||
* Prüft `trigger_keywords` aus `decision_engine.yaml` (z.B. "Soll ich", "Wann", "Was ist").
|
||||
* Wenn Match: Sofortige Intent-Zuordnung ohne LLM-Call.
|
||||
* **Strategien:** FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW.
|
||||
2. **Type Keywords (Interview-Modus):**
|
||||
* Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung.
|
||||
* Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung).
|
||||
3. **LLM Slow-Path (Semantische Analyse):**
|
||||
* Wenn unklar: Anfrage an `DecisionEngine._determine_strategy()` zur LLM-basierten Klassifizierung.
|
||||
* Nutzt `intent_router_v1` Prompt aus `prompts.yaml`.
|
||||
|
||||
### 1.2 Prompt-Auflösung (Bulletproof Resolution)
|
||||
|
||||
@@ -34,24 +36,70 @@ Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt
|
||||
* **Basis-Fallback:** Als letzte Instanz wird das `ollama`-Template geladen.
|
||||
* **String-Garantie:** Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert.
|
||||
|
||||
### 1.3 RAG Flow (Technisch)
|
||||
### 1.2 Multi-Stream Retrieval (WP-25)
|
||||
|
||||
Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
|
||||
Anstelle einer einzelnen Suche führt die `DecisionEngine` nun **parallele Abfragen** in spezialisierten Streams aus:
|
||||
|
||||
1. **Pre-Processing:** Query Rewriting (optional).
|
||||
2. **Context Enrichment:**
|
||||
* Abruf via `retriever.py` (Hybrid Search).
|
||||
* Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung.
|
||||
* Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt.
|
||||
3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query.
|
||||
4. **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt.
|
||||
5. **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams.
|
||||
**Stream-Library (definiert in `decision_engine.yaml`):**
|
||||
* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, etc.).
|
||||
* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, etc.).
|
||||
* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`).
|
||||
* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
|
||||
* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, etc.).
|
||||
|
||||
**Stream-Konfiguration:**
|
||||
* Jeder Stream nutzt individuelle **Edge-Boosts** (z.B. `guides: 3.0` für Values Stream).
|
||||
* **Filter-Types** sind strikt mit `types.yaml` (v2.7.0) synchronisiert.
|
||||
* **Query-Templates** transformieren die ursprüngliche Anfrage für spezialisierte Suche.
|
||||
|
||||
**Parallele Ausführung:**
|
||||
* `asyncio.gather()` führt alle aktiven Streams gleichzeitig aus.
|
||||
* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung.
|
||||
* **Fehlerbehandlung:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage.
|
||||
|
||||
### 1.3 Wissens-Synthese (WP-25)
|
||||
|
||||
Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`:
|
||||
|
||||
**Template-Struktur:**
|
||||
* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`).
|
||||
* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors).
|
||||
* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter.
|
||||
|
||||
**Synthese-Strategien:**
|
||||
* **FACT_WHAT/FACT_WHEN:** Kombiniert Fakten, Biographie und Technik.
|
||||
* **DECISION:** Wägt Fakten gegen Werte ab, evaluiert Risiken.
|
||||
* **EMPATHY:** Fokus auf Biographie und Werte.
|
||||
* **CODING:** Technik und Fakten.
|
||||
|
||||
### 1.4 RAG Flow (Technisch)
|
||||
|
||||
Wenn der Intent nicht `INTERVIEW` ist, wird folgender Flow ausgeführt:
|
||||
|
||||
1. **Intent Detection:** Hybrid Router klassifiziert die Anfrage.
|
||||
2. **Multi-Stream Retrieval:**
|
||||
* Parallele Abfragen in spezialisierten Streams via `DecisionEngine._execute_parallel_streams()`.
|
||||
* Jeder Stream nutzt individuelle Filter, Edge-Boosts und Query-Templates.
|
||||
3. **Context Formatting:**
|
||||
* Stream-Ergebnisse werden in formatierte Kontext-Strings umgewandelt.
|
||||
* **Ollama Context-Throttling:** Kontext wird auf `MAX_OLLAMA_CHARS` begrenzt (Standard: 10.000).
|
||||
4. **Synthese:**
|
||||
* `DecisionEngine._generate_final_answer()` kombiniert alle Streams.
|
||||
* Template-basierte Prompt-Konstruktion mit Stream-Variablen.
|
||||
5. **Response:**
|
||||
* LLM-Antwort wird generiert (provider-spezifisch).
|
||||
* **Sources:** Alle Treffer aus allen Streams werden dedupliziert und zurückgegeben.
|
||||
|
||||
---
|
||||
|
||||
## 2. LLM Service & Traffic Control (WP-20)
|
||||
## 2. LLM Service & Traffic Control (WP-20 / WP-25)
|
||||
|
||||
Der `LLMService` (`app/services/llm_service.py`) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten.
|
||||
Der `LLMService` (`app/services/llm_service.py`, v3.4.2) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten.
|
||||
|
||||
**WP-25 Integration:**
|
||||
* **Lazy Initialization:** `DecisionEngine` wird erst bei Bedarf initialisiert (verhindert Circular Imports).
|
||||
* **Ingest-Stability Patch:** Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen beim Vault-Import.
|
||||
* **Empty Response Guard:** Sicherung gegen leere `choices` Arrays bei OpenRouter (verhindert JSON-Errors).
|
||||
|
||||
Mit Version 2.8.1 wurde die Architektur der Antwort-Generierung grundlegend gehärtet:
|
||||
|
||||
@@ -107,10 +155,27 @@ In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementier
|
||||
|
||||
---
|
||||
|
||||
## 4. Feedback Traceability
|
||||
## 4. Feedback Traceability & Stream-Tracing (WP-25)
|
||||
|
||||
Unterstützt das geplante Self-Tuning (WP08).
|
||||
Unterstützt das geplante Self-Tuning (WP08) und ermöglicht Stream-spezifische Optimierung.
|
||||
|
||||
1. **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`.
|
||||
2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context).
|
||||
3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`.
|
||||
1. **Query ID:** Generiert bei jedem `/chat` Call eine `UUIDv4`.
|
||||
2. **Stream-Tracing:** Jeder Treffer enthält `stream_origin` für Zuordnung zum Quell-Stream.
|
||||
3. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context + Intent).
|
||||
4. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id` und `stream_origin`.
|
||||
|
||||
## 5. Lifespan Management (WP-25)
|
||||
|
||||
Die FastAPI-Anwendung (`app/main.py`, v1.0.0) implementiert **Lifespan-Management** für sauberen Startup und Shutdown:
|
||||
|
||||
**Startup:**
|
||||
* Integritäts-Check der WP-25 Konfiguration (`decision_engine.yaml`, `prompts.yaml`).
|
||||
* Validierung kritischer Dateien vor dem Start.
|
||||
|
||||
**Shutdown:**
|
||||
* Ressourcen-Cleanup (LLMService-Connections schließen).
|
||||
* Graceful Shutdown für asynchrone Prozesse.
|
||||
|
||||
**Globale Fehlerbehandlung:**
|
||||
* Fängt unerwartete Fehler in der Multi-Stream Kette ab.
|
||||
* Strukturierte JSON-Responses bei Engine-Fehlern.
|
||||
Reference in new issue
Block a user