mindnet/docs/03_Technical_References/03_tech_chat_backend.md

doc_type	audience	scope	status	version	context
technical_reference	developer, architect	backend, chat, ollama, traffic_control	active	2.6	Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control 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, welche Strategie gewählt wird, basierend auf dem User-Input.

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, z.B. "Projekt") und decision_engine.yaml (Handlungen, z.B. "neu").
   • Wenn Match (z.B. "Projekt" + "neu"): INTERVIEW Modus.
3. LLM Fallback (Slow Path):
   • Wenn unklar: Anfrage an LLM zur Klassifizierung.

1.2 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).
   • 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. Traffic Control (WP-15)

Das Traffic Control System (app/core/llm_service.py) schützt das System vor Überlastung, wenn rechenintensive Hintergrundprozesse (Smart Edge Import) und Latenz-kritische Chat-Anfragen gleichzeitig laufen.

2.1 Prioritäts-Semaphor

Jeder LLM-Request muss ein priority-Flag setzen.

Prioritäten-Levels:

Priority	Verwendung	Limitierung
realtime	Chat-Anfragen	Keine (Hardware-Limit)
background	Smart Edge Allocation, Drafts	MINDNET_LLM_BACKGROUND_LIMIT

Funktionsweise:

• Hintergrund-Tasks nutzen asyncio.Semaphore.
• Wenn das Limit (Default: 2) erreicht ist, warten weitere Import-Tasks.
• Chat-Tasks umgehen die Semaphore und werden sofort bearbeitet.

2.2 Timeout-Konfiguration

Deadlocks werden durch strikte Timeouts verhindert, die in der .env definiert sind.

• Chat: MINDNET_LLM_TIMEOUT (Default: 300s).
• Frontend: MINDNET_API_TIMEOUT (Default: 300s).

---

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