mindnet/docs/03_Technical_References/03_tech_chat_backend.md

doc_type	audience	scope	status	version	context
technical_reference	developer, architect	backend, chat, llm_service, traffic_control, resilience	active	2.8.1	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.