mindnet/docs/03_Technical_References/03_tech_chat_backend.md

---
doc_type: technical_reference
audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience
status: active
version: 2.8.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
---

# Chat Backend & Traffic Control

## 1. Hybrid Router (Decision Engine)

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.

### 1.1 Intent-Erkennung (Logik)

Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):

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.2 Prompt-Auflösung (Bulletproof Resolution)

Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**:
* **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`).
* **Cloud-Stil Fallback:** Existiert dieser nicht, erfolgt ein Fallback auf das `gemini`-Template.
* **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)

Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:

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.

---

## 2. LLM Service & Traffic Control (WP-20)

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.

Mit Version 2.8.1 wurde die Architektur der Antwort-Generierung grundlegend gehärtet:

A. Fail-Fast Prinzip (No-Retry Chat)
Im Gegensatz zur Ingestion-Pipeline nutzt das Chat-Backend für Echtzeit-Anfragen keine internen Retries (max_retries=0).

Scheitert ein Provider (Timeout/Fehler), wird sofort die Fallback-Kaskade eingeleitet oder der Deep Fallback zu Ollama getriggert.

Dies verhindert die kumulative Wartezeit von mehreren Minuten bei Provider-Störungen.

B. Context-Throttling & Memory Guard
Drosselung: Vor der Übergabe an Ollama prüft die chat.py, ob der Kontext (RAG-Hits) die Grenze von MAX_OLLAMA_CHARS überschreitet und kürzt diesen ggf..

Modell-Lock: Der LLMService erzwingt im Ollama-Payload den Parameter num_ctx: 8192. Dies stabilisiert den VRAM-Verbrauch und verhindert, dass das Modell versucht, speicherintensive 128k-Kontexte zu reservieren.

### 2.1 Prioritäts-Semaphor

Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- und API-Ressourcen:

| Priority | Verwendung | Limitierung |
| :--- | :--- | :--- |
| **realtime** | Chat-Anfragen, Intent-Routing | Keine (Hardware-Limit) |
| **background** | Smart Edge Allocation, Import-Tasks | `MINDNET_LLM_BACKGROUND_LIMIT` |

**Funktionsweise:**
* Hintergrund-Tasks nutzen ein globales `asyncio.Semaphore`.
* Das Limit (Standard: 2) verhindert, dass parallele Import-Vorgänge die API-Quoten oder die lokale CPU erschöpfen.
* Chat-Tasks umgehen die Semaphore für minimale Latenz.

### 2.2 Task-Mapping & Model Selection

Die Konfiguration ermöglicht eine spezialisierte Modell-Auswahl je nach Anwendungsfall:
* **Semantische Extraktion (Turbo):** Nutzt bevorzugt `OPENROUTER_MODEL` (Mistral-7B) für schnelles und präzises JSON-Parsing.
* **RAG-Chat:** Nutzt bevorzugt `GEMINI_MODEL` (2.5 flash-lite) für hohe Kapazität und Stabilität mittels erzwungener **v1-API Version**.

### 2.3 Timeout-Konfiguration

Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhindert:
* **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz.
* **Lokales LLM (Ollama):** Konfigurierbar via `MINDNET_LLM_TIMEOUT` (Default: 300s).

---

## 3. Resilience & Quota Management (WP-20)

In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementiert:

1.  **Rate-Limit Erkennung:** Der Service erkennt HTTP 429 Fehler sowie provider-spezifische Meldungen wie `RESOURCE_EXHAUSTED`.
2.  **Intelligenter Backoff:** Statt sofort auf das langsame lokale Modell zu wechseln, pausiert das System für die Dauer von `LLM_RATE_LIMIT_WAIT` (Standard: 60s).
3.  **Cloud-Retry:** Nach der Pause erfolgt ein erneuter Versuch (bis zu `LLM_RATE_LIMIT_RETRIES` Mal).
4.  **Ollama Fallback:** Erst nach Erschöpfung der Retries schaltet das System auf den lokalen Ollama um, um die Betriebssicherheit zu gewährleisten ("Quoten-Schutz").
5.  **Deep Fallback Support:** Der Service stellt die Infrastruktur für den inhaltsbasierten Fallback (v2.11.14) bereit, falls die Cloud zwar technisch antwortet, aber inhaltlich (z.B. wegen Policy-Filtern oder Silent Refusal) keine validen Daten liefert.

---

## 4. Feedback Traceability

Unterstützt das geplante Self-Tuning (WP08).

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`.