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
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService und des WP-76 Resilienz-Systems."
---

# 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 (WP-20 Fix)

Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**:
* Das System sucht zuerst nach einem Prompt für den aktiven Provider (z.B. `openrouter`).
* Existiert dieser nicht, erfolgt ein Fallback auf `gemini` und schließlich auf `ollama`.
* Dies garantiert die Rückgabe eines validen Strings und verhindert 500-Fehler bei String-Operationen wie `.replace()`.

### 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-15/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.

### 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 (Default: 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 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-76)

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` (Default: 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").

---

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