Dokumentation WP20

config/prod.env

@@ -0,0 +1,48 @@
+# --- FastAPI Server (Produktion) ---
+UVICORN_HOST=0.0.0.0
+UVICORN_PORT=8000
+DEBUG=false
+
+# --- Qdrant Vektor-Datenbank ---
+# Trennung der Daten durch eigenes Prefix
+QDRANT_URL=http://127.0.0.1:6333
+QDRANT_API_KEY=
+COLLECTION_PREFIX=mindnet
+
+# --- Vektoren-Konfiguration ---
+# Muss 768 für 'nomic-embed-text' sein
+VECTOR_DIM=768
+
+# --- AI Modelle (Lokal/Fallback) ---
+MINDNET_LLM_MODEL=phi3:mini
+MINDNET_OLLAMA_URL=http://127.0.0.1:11434
+MINDNET_LLM_TIMEOUT=300.0
+MINDNET_LLM_BACKGROUND_LIMIT=2
+
+# Vektor-Modell für semantische Suche
+MINDNET_EMBEDDING_MODEL=nomic-embed-text
+
+# --- WP-20/WP-76: Hybrid-Cloud & Resilienz ---
+# Primärer Provider für höchste Qualität
+MINDNET_LLM_PROVIDER=openrouter
+MINDNET_LLM_FALLBACK=true
+
+# Intelligente Rate-Limit Steuerung (Sekunden/Versuche)
+MINDNET_LLM_RATE_LIMIT_WAIT=60.0
+MINDNET_LLM_RATE_LIMIT_RETRIES=3
+
+# --- Cloud Provider Keys (Hier Prod-Keys einsetzen) ---
+GOOGLE_API_KEY=AIzaSy... (Dein Prod-Key)
+MINDNET_GEMINI_MODEL=gemini-2.5-flash-lite
+
+OPENROUTER_API_KEY=sk-or-v1-... (Dein Prod-Key)
+# Stabilstes Free-Modell für strukturierte Extraktion
+OPENROUTER_MODEL=mistralai/mistral-7b-instruct:free
+
+# --- Pfade & System (Produktions-Vault) ---
+MINDNET_TYPES_FILE=./config/types.yaml
+MINDNET_VAULT_ROOT=./vault_prod
+MINDNET_VOCAB_PATH=/mindnet/vault/mindnet/_system/dictionary/edge_vocabulary.md
+
+# Change Detection für effiziente Re-Imports
+MINDNET_CHANGE_DETECTION_MODE=full

docs/00_General/00_glossary.md

@@ -2,13 +2,13 @@
 doc_type: glossary
 audience: all
 status: active
-version: 2.7.0
+version: 2.8.0
-context: "Zentrales Glossar für Mindnet v2.7. Definitionen von Entitäten, WP-22 Scoring-Konzepten und der Edge Registry."
+context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-76 Quoten-Steuerung und Mistral-safe Parsing."
 ---
 
 # Mindnet Glossar
 
-**Quellen:** `01_edge_vocabulary.md`, `retriever_scoring.py`, `edge_registry.py`
+**Quellen:** `01_edge_vocabulary.md`, `llm_service.py`, `ingestion.py`, `edge_registry.py`
 
 ## Kern-Entitäten
 
@@ -21,21 +21,22 @@ context: "Zentrales Glossar für Mindnet v2.7. Definitionen von Entitäten, WP-2
 ## Komponenten
 
 * **Edge Registry:** Der zentrale Dienst (SSOT), der Kanten-Typen validiert und Aliase in kanonische Typen auflöst. Nutzt `01_edge_vocabulary.md` als Basis.
-* **Retriever:** Besteht in v2.7 aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`).
+* **LLM Service:** Der Hybrid-Client (v3.3.6), der Anfragen zwischen OpenRouter, Google Gemini und lokalem Ollama routet. Verwaltet Cloud-Timeouts und Quoten-Management.
+* **Retriever:** Besteht in v2.7+ aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`).
 * **Decision Engine:** Teil des Routers, der Intents erkennt und entsprechende **Boost-Faktoren** für das Retrieval injiziert.
-* **Traffic Control:** Verwaltet Prioritäten und drosselt Hintergrund-Tasks (z.B. Smart Edges) mittels Semaphoren.
+* **Traffic Control:** Verwaltet Prioritäten und drosselt Hintergrund-Tasks (z.B. Smart Edges) mittels Semaphoren und Timeouts (45s) zur Vermeidung von System-Hangs.
 * **Unknown Edges Log:** Die Datei `unknown_edges.jsonl`, in der das System Kanten-Typen protokolliert, die nicht im Dictionary gefunden wurden.
 
 ## Konzepte & Features
 
-* **Canonical Type:** Der standardisierte System-Name einer Kante (z.B. `based_on`), der in der Datenbank gespeichert wird.
+* **Hybrid Provider Cascade:** Die intelligente Reihenfolge der Modell-Ansprache. Schlägt die Cloud (OpenRouter/Gemini) fehl, erfolgt nach Retries ein Fallback auf den lokalen Ollama (Quoten-Schutz).
-* **Alias (Edge):** Ein nutzerfreundliches Synonym (z.B. `basiert_auf`), das während der Ingestion automatisch zum Canonical Type aufgelöst wird.
+* **Rate-Limit Resilience (WP-76):** Automatisierte Erkennung von HTTP 429 Fehlern. Das System pausiert (konfigurierbar via `LLM_RATE_LIMIT_WAIT`) und wiederholt den Cloud-Call, bevor der langsame Fallback ausgelöst wird.
+* **Mistral-safe Parsing:** Robuste Extraktions-Logik in Ingestion und Analyzer, die technische Steuerzeichen (`<s>`, `[OUT]`) und Framework-Tags erkennt und entfernt, um valides JSON aus Free-Modellen zu gewinnen.
 * **Lifecycle Scoring (WP-22):** Ein Mechanismus, der die Relevanz einer Notiz basierend auf ihrem Status gewichtet (z.B. Bonus für `stable`, Malus für `draft`).
 * **Intent Boosting:** Dynamische Erhöhung der Kanten-Gewichte basierend auf der Nutzerfrage (z.B. Fokus auf `caused_by` bei "Warum"-Fragen).
 * **Provenance Weighting:** Gewichtung einer Kante nach ihrer Herkunft:
     * `explicit`: Vom Mensch gesetzt (Prio 1).
-    * `smart`: Von der KI validiert (Prio 2).
+    * `semantic_ai`: Von der KI im Turbo-Mode extrahiert und validiert (Prio 2).
-    * `rule`: Durch System-Regeln/Matrix erzeugt (Prio 3).
+    * `structure`: Durch System-Regeln/Matrix erzeugt (Prio 3).
 * **Smart Edge Allocation:** KI-Verfahren zur Relevanzprüfung von Links für spezifische Textabschnitte.
-* **Strict Heading Split:** Chunking-Strategie mit harten Grenzen an Überschriften und integriertem "Safety Net" gegen zu große Chunks.
 * **Matrix Logic:** Bestimmung des Kanten-Typs basierend auf Quell- und Ziel-Entität (z.B. Erfahrung -> Wert = `based_on`).

docs/02_concepts/02_concept_ai_personality.md

@@ -3,71 +3,78 @@ doc_type: concept
 audience: architect, product_owner
 scope: ai, router, personas
 status: active
-version: 2.6
+version: 2.8
-context: "Fachkonzept der KI-Persönlichkeit, der Decision Engine und Erweiterungsstrategien."
+context: "Fachkonzept der KI-Persönlichkeit, der Hybrid-Provider-Kaskade und der operationalen Resilienz."
 ---
 
 # Konzept: KI-Persönlichkeit & Router
 
-**Quellen:** `mindnet_functional_architecture.md`, `Programmplan_V2.2.md`
+**Quellen:** `mindnet_functional_architecture.md`, `llm_service.py`, `config.py`
 
-Mindnet soll nicht wie eine Suchmaschine wirken, sondern wie ein **Digitaler Zwilling**. Dazu muss das System erkennen, **was** der Nutzer will, und seine "Persönlichkeit" anpassen.
+Mindnet soll nicht wie eine Suchmaschine wirken, sondern wie ein **Digitaler Zwilling**. Dazu muss das System erkennen, **was** der Nutzer will, und seine „Persönlichkeit“ sowie seine technische Infrastruktur dynamisch anpassen.
 
 ## 1. Der Hybrid Router (Das Gehirn)
 
-Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die Strategie.
+Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die fachliche Strategie und die technische Ausführung.
 
 ### Modus A: RAG (Retrieval Augmented Generation)
-* *Intent:* Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
+* **Intent:** Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
-* *Aktion:* Das System sucht im Gedächtnis und generiert eine Antwort.
+* **Aktion:** Das System sucht im Gedächtnis und generiert eine Antwort.
 
 ### Modus B: Interview (Knowledge Capture)
-* *Intent:* Der Nutzer will Wissen speichern (`INTERVIEW`).
+* **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`).
-* *Aktion:* Das System sucht **nicht**, sondern fragt ab und erstellt einen Draft.
+* **Aktion:** Das System sucht **nicht**, sondern fragt ab und erstellt einen Draft.
 
 ---
 
-## 2. Die Personas (Strategien)
+## 2. Die Provider-Kaskade (Hybrid-Cloud Resilienz)
+
+Ein intelligenter Zwilling muss jederzeit verfügbar sein. Mindnet v2.8 nutzt eine **dreistufige Kaskade**, um Intelligenz, Kosten und Verfügbarkeit zu optimieren:
+
+1.  **Stufe 1: High-Performance Cloud (OpenRouter/Gemini):** Primäre Wahl für komplexe Schlussfolgerungen und semantische Extraktion (Mistral-7B / Gemini-2.5-Lite).
+2.  **Stufe 2: Resilienz-Pause (Quota-Handling):** Bei Erreichen von Provider-Limits (HTTP 429) pausiert das System intelligent (konfigurierbar via `LLM_RATE_LIMIT_WAIT`), anstatt den Dienst abzubrechen.
+3.  **Stufe 3: Local-Only Fallback (Ollama):** Schlagen alle Cloud-Retries fehl, übernimmt das lokale Modell (Phi-3), um die Betriebssicherheit ohne Datenabfluss zu garantieren.
+
+---
+
+## 3. Die Personas (Strategien)
 
 Mindnet wechselt den Hut, je nach Situation.
 
-### 2.1 Der Berater (Strategy: DECISION)
+### 3.1 Der Berater (Strategy: DECISION)
-* **Auslöser:** Fragen wie "Soll ich...?", "Was ist besser?".
+* **Auslöser:** Fragen wie „Soll ich...?“, „Was ist besser?“.
 * **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen.
-* **Reasoning:** *"Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken."*
+* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken.“*
 
-### 2.2 Der Spiegel (Strategy: EMPATHY)
+### 3.2 Der Spiegel (Strategy: EMPATHY)
-* **Auslöser:** Emotionale Aussagen ("Ich bin frustriert").
+* **Auslöser:** Emotionale Aussagen („Ich bin frustriert“).
 * **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze).
-* **Reasoning:** *"Nutze meine eigenen Erfahrungen, um die Situation einzuordnen."*
+* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen.“*
 
-### 2.3 Der Bibliothekar (Strategy: FACT)
+### 3.3 Der Bibliothekar (Strategy: FACT)
-* **Auslöser:** Sachfragen ("Was ist Qdrant?").
+* **Auslöser:** Sachfragen („Was ist Qdrant?“).
 * **Behavior:** Präzise, neutral, kurz.
 
 ---
 
-## 3. Future Concepts: The Empathic Digital Twin
+## 4. Future Concepts: The Empathic Digital Twin
 
-Um Mindnet von einer Maschine zu einem echten Spiegel der Persönlichkeit zu entwickeln, sind folgende Konzepte in der Architektur angelegt:
+### 4.1 Antizipation durch Erfahrung
+* **Konzept:** Das System soll Konsequenzen vorhersagen („Was passiert, wenn...?“).
+* **Logik:** *„In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt.“* (Analogie-Schluss).
 
-### 3.1 Antizipation durch Erfahrung
+### 4.2 Empathie & „Ich“-Modus
-* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
-* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."* (Analogie-Schluss).
-
-### 3.2 Empathie & "Ich"-Modus
 * **Konzept:** Das System antwortet im Tonfall des Nutzers.
 * **Umsetzung:** Few-Shot Prompting mit eigenen E-Mails/Texten als Stilvorlage.
 
-### 3.3 Glaubenssätze & Rituale
+### 4.3 Resilienz als Charakterzug
-* **Konzept:** Berücksichtigung weicher Faktoren.
+Durch das **WP-76 Handling** zeigt das System „Geduld“: Bei Überlastung der Cloud-Dienste bricht es nicht panisch ab, sondern wartet auf die nächste freie Kapazität, um die Qualität der Antwort zu sichern.
-* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.
 
 ---
 
-## 4. Erweiterbarkeit: Das "Teach-the-AI" Paradigma
+## 5. Erweiterbarkeit: Das „Teach-the-AI“ Paradigma
 
-Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**. Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
+Mindnet lernt durch **Konfiguration** und **Vernetzung**.
 
 **Beispiel: Du willst den Typ `risk` einführen.**
 
@@ -87,6 +94,6 @@ DECISION:
 ```
 
 **3. Kognitive Ebene (Verständnis)**
-In `prompts.yaml`: Erkläre dem LLM, was ein Risiko ist.
+In `prompts.yaml`: Erkläre dem LLM (provider-spezifisch), was ein Risiko ist.
 
-**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
+**Fazit:** Nur wenn **Daten** (Vault), **Infrastruktur** (Resiliente Kaskade) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.

docs/03_Technical_References/03_tech_chat_backend.md

@@ -1,17 +1,17 @@
 ---
 doc_type: technical_reference
 audience: developer, architect
-scope: backend, chat, ollama, traffic_control
+scope: backend, chat, llm_service, traffic_control, resilience
 status: active
-version: 2.6
+version: 2.8
-context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control Systems."
+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, welche Strategie gewählt wird, basierend auf dem User-Input.
+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)
 
@@ -21,18 +21,26 @@ Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
     * 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").
+    * 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.
+    * Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`.
 
-### 1.2 RAG Flow (Technisch)
+### 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.
@@ -40,36 +48,44 @@ Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
 
 ---
 
-## 2. Traffic Control (WP-15)
+## 2. LLM Service & Traffic Control (WP-15/WP-20)
 
-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.
+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 muss ein `priority`-Flag setzen.
+Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- und API-Ressourcen:
-
-**Prioritäten-Levels:**
 
 | Priority | Verwendung | Limitierung |
 | :--- | :--- | :--- |
-| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) |
+| **realtime** | Chat-Anfragen, Intent-Routing | Keine (Hardware-Limit) |
-| **background** | Smart Edge Allocation, Drafts | `MINDNET_LLM_BACKGROUND_LIMIT` |
+| **background** | Smart Edge Allocation, Import-Tasks | `MINDNET_LLM_BACKGROUND_LIMIT` |
 
 **Funktionsweise:**
-* Hintergrund-Tasks nutzen `asyncio.Semaphore`.
+* Hintergrund-Tasks nutzen ein globales `asyncio.Semaphore`.
-* Wenn das Limit (Default: 2) erreicht ist, warten weitere Import-Tasks.
+* Das Limit (Default: 2) verhindert, dass parallele Import-Vorgänge die API-Quoten oder die lokale CPU erschöpfen.
-* Chat-Tasks umgehen die Semaphore und werden sofort bearbeitet.
+* Chat-Tasks umgehen die Semaphore für minimale Latenz.
 
 ### 2.2 Timeout-Konfiguration
 
-Deadlocks werden durch strikte Timeouts verhindert, die in der `.env` definiert sind.
+Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhindert:
-
+* **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz.
-* **Chat:** `MINDNET_LLM_TIMEOUT` (Default: 300s).
+* **Lokales LLM (Ollama):** Konfigurierbar via `MINDNET_LLM_TIMEOUT` (Default: 300s).
-* **Frontend:** `MINDNET_API_TIMEOUT` (Default: 300s).
 
 ---
 
-## 3. Feedback Traceability
+## 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).
 

docs/03_Technical_References/03_tech_configuration.md

@@ -1,15 +1,15 @@
 ---
 doc_type: technical_reference
 audience: developer, admin
-scope: configuration, env, registry, scoring
+scope: configuration, env, registry, scoring, resilience
 status: active
-version: 2.7.2
+version: 2.8.0
-context: "Umfassende Referenztabellen für Umgebungsvariablen, YAML-Konfigurationen und die Edge Registry Struktur."
+context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur."
 ---
 
 # Konfigurations-Referenz
 
-Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.7 wurde die Konfiguration professionalisiert, um die Edge Registry und dynamische Scoring-Parameter (Lifecycle & Intent) zu unterstützen.
+Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.8 wurde die Konfiguration professionalisiert, um die Edge Registry, dynamische Scoring-Parameter (Lifecycle & Intent) sowie die neue Hybrid-Cloud-Resilienz zu unterstützen.
 
 ## 1. Environment Variablen (`.env`)
 
@@ -22,17 +22,25 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts.
 | `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
 | `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
 | `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. |
-| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. Dient als Fallback-Basis, falls `MINDNET_VOCAB_PATH` nicht gesetzt ist. |
+| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
 | `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
 | `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
 | `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
 | `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM Prompts. |
-| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Chat-Modells (Ollama). |
+| `MINDNET_LLM_PROVIDER` | `openrouter` | **Neu (WP-20):** Aktiver Provider (`openrouter`, `gemini`, `ollama`). |
+| `MINDNET_LLM_FALLBACK` | `true` | **Neu (WP-20):** Aktiviert automatischen Ollama-Fallback bei Cloud-Fehlern. |
+| `MINDNET_LLM_RATE_LIMIT_WAIT`| `60.0` | **Neu (WP-76):** Wartezeit in Sekunden bei HTTP 429 (Rate Limit). |
+| `MINDNET_LLM_RATE_LIMIT_RETRIES`| `3` | **Neu (WP-76):** Anzahl Cloud-Retries vor lokalem Fallback. |
+| `GOOGLE_API_KEY` | *(Key)* | API Key für Google AI Studio. |
+| `MINDNET_GEMINI_MODEL` | `gemini-2.5-flash-lite` | **Update 2025:** Optimiertes Lite-Modell für hohe Quoten. |
+| `OPENROUTER_API_KEY` | *(Key)* | API Key für OpenRouter Integration. |
+| `OPENROUTER_MODEL` | `mistralai/mistral-7b-instruct:free` | **Update 2025:** Verifiziertes Free-Modell für strukturierte Extraktion. |
+| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des lokalen Chat-Modells (Ollama). |
 | `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-Modells (Ollama). |
-| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server. |
+| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum lokalen LLM-Server. |
-| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). |
+| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden für LLM-Anfragen. |
-| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). |
+| `MINDNET_API_TIMEOUT` | `300.0` | Globales API-Timeout für das Frontend. |
-| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
+| `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
 | `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). |
 
 ---

docs/03_Technical_References/03_tech_ingestion_pipeline.md

@@ -3,15 +3,15 @@ doc_type: technical_reference
 audience: developer, devops
 scope: backend, ingestion, smart_edges, edge_registry
 status: active
-version: 2.7.1
+version: 2.8.0
-context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle."
+context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und WP-76 Resilienz-Logik."
 ---
 
 # Ingestion Pipeline & Smart Processing
 
-**Quellen:** `pipeline_playbook.md`, `Handbuch.md`, `edge_registry.py`, `01_edge_vocabulary.md`, `06_active_roadmap.md`
+**Quellen:** `pipeline_playbook.md`, `ingestion.py`, `edge_registry.py`, `01_edge_vocabulary.md`, `llm_service.py`
 
-Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.7 integriert dieser Prozess die **Edge Registry** zur Normalisierung des Vokabulars und beachtet den **Content Lifecycle**.
+Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.8 integriert dieser Prozess eine **intelligente Quoten-Steuerung** (WP-76) und ein **robustes JSON-Parsing** für Cloud-Modelle (Mistral/Gemini).
 
 ## 1. Der Import-Prozess (15-Schritte-Workflow)
 
@@ -38,10 +38,11 @@ Der Prozess ist **asynchron** und **idempotent**.
     * Vergleich des Hashes mit Qdrant.
     * Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`).
 8.  **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
-9.  **Smart Edge Allocation (WP15):**
+9.  **Smart Edge Allocation (WP15/WP20):**
     * Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
-    * **Traffic Control:** Request nutzt `priority="background"`. Semaphore (Limit via `.env`) drosselt die Last.
+    * **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last.
-    * **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
+    * **Resilienz (WP-76):** Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via `LLM_RATE_LIMIT_WAIT`), bevor ein Cloud-Retry oder der lokale Fallback erfolgt.
+    * **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (`<s>`) und Framework-Tags (`[OUT]`) zur Sicherstellung validen JSONs.
 10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
 11. **Alias-Auflösung & Kanonisierung (WP-22):**
     * Jede Kante wird via `edge_registry.resolve()` normalisiert.
@@ -138,20 +139,20 @@ Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften).
 
 Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt.
 
-| Prio | Quelle | Rule ID | Confidence | Erläuterung |
+| Prio | Quelle | Rule ID / Provenance | Confidence | Erläuterung |
 | :--- | :--- | :--- | :--- | :--- |
 | **1** | Wikilink | `explicit:wikilink` | **1.00** | Harte menschliche Setzung. |
 | **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. |
 | **3** | Callout | `callout:edge` | **0.90** | Explizite Meta-Information. |
-| **4** | Smart Edge | `smart:llm_filter` | **0.90** | KI-validierte Verbindung. |
+| **4** | Semantic AI | `semantic_ai` | **0.90** | KI-extrahierte Verbindung (Mistral-safe). |
 | **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. |
-| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung. |
+| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung (`belongs_to`). |
 
 ---
 
 ## 5. Quality Gates & Monitoring
 
-In v2.7 wurden Tools zur Überwachung der Datenqualität integriert:
+In v2.7+ wurden Tools zur Überwachung der Datenqualität integriert:
 
 **1. Registry Review:** Prüfung der `data/logs/unknown_edges.jsonl`. Administratoren sollten hier gelistete Begriffe als Aliase in die `01_edge_vocabulary.md` aufnehmen.
 

docs/06_Roadmap/06_active_roadmap.md

@@ -2,18 +2,18 @@
 doc_type: roadmap
 audience: product_owner, developer
 status: active
-version: 2.7
+version: 2.8.0
 context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs."
 ---
 
 # Mindnet Active Roadmap
 
-**Aktueller Stand:** v2.6.0 (Post-WP15/WP19)
+**Aktueller Stand:** v2.8.0 (Post-WP20/WP76)
-**Fokus:** Visualisierung, Exploration & Intelligent Ingestion.
+**Fokus:** Visualisierung, Exploration & Cloud-Resilienz.
 
 ## 1. Programmstatus
 
-Wir haben mit der Implementierung des Graph Explorers (WP19) und der Smart Edge Allocation (WP15) die Basis für ein intelligentes, robustes System gelegt. Der nächste Schritt (WP19a) vertieft die Analyse, während WP16 die "Eingangs-Intelligenz" erhöht.
+Wir haben mit der Implementierung des Graph Explorers (WP19), der Smart Edge Allocation (WP15) und der hybriden Cloud-Resilienz (WP20) die Basis für ein intelligentes, robustes System gelegt. Der nächste Schritt (WP19a) vertieft die Analyse, während WP16 die "Eingangs-Intelligenz" erhöht.
 
 | Phase | Fokus | Status |
 | :--- | :--- | :--- |
@@ -47,7 +47,7 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
 | **WP-11** | Backend Intelligence | `nomic-embed-text` (768d) und Matrix-Logik für Kanten-Typisierung. |
 | **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore) + Strict Chunking. |
 | **WP-19** | Graph Visualisierung | **Frontend Modularisierung:** Umbau auf `ui_*.py`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**Tools:** "Single Source of Truth" Editor, Persistenz via URL. |
-| **WP-20** | Cloud Hybrid Mode | Nutzung von Public LLM für schnellere Verarbeitung und bestimmte Aufgaben |
+| **WP-20** | **Cloud Hybrid Mode & Resilienz** | **Ergebnis:** Integration von OpenRouter (Mistral 7B) & Gemini 2.5 Lite. Implementierung von WP-76 (Rate-Limit Wait) & Mistral-safe JSON Parsing. |
 | **WP-21** | Semantic Graph Routing & Canonical Edges | Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?"). |
 | **WP-22** | **Content Lifecycle & Registry** | **Ergebnis:** SSOT via `01_edge_vocabulary.md`, Alias-Mapping, Status-Scoring (`stable`/`draft`) und Modularisierung der Scoring-Engine. |
 
@@ -55,6 +55,9 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
 * **Architektur:** Die Trennung von `retriever.py` und `retriever_scoring.py` war notwendig, um LLM-Context-Limits zu wahren und die Testbarkeit der mathematischen Formeln zu erhöhen.
 * **Kanten-Validierung:** Die Edge Registry muss beim Start explizit initialisiert werden (Singleton), um "Lazy Loading" Probleme in der API zu vermeiden.
 
+### 2.2 WP-20 Lessons Learned (Resilienz)
+* **Quoten-Management:** Die Nutzung von Free-Tier Modellen (Mistral/OpenRouter) erfordert zwingend eine intelligente Rate-Limit-Erkennung (HTTP 429) mit automatisierten Wartezyklen, um Batch-Prozesse stabil zu halten.
+* **Parser-Robustheit:** Cloud-Modelle betten JSON oft in technische Steuerzeichen (`<s>`, `[OUT]`) ein. Ein robuster Extraktor mit Recovery-Logik ist essentiell zur Vermeidung von Datenverlust.
 
 ---
 
@@ -80,7 +83,7 @@ Diese Features stehen als nächstes an oder befinden sich in der Umsetzung.
 **Phase:** B
 **Status:** 🟡 geplant
 
-**Ziel:** Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
+**Ziel:** Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet installiert werden können – ohne Massenumbau.
 
 **Umfang:**
 - Tools zur Analyse des Vault-Status.
@@ -122,7 +125,7 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h
 **Ziel:** Technische Schulden abbauen, die durch schnelle Feature-Entwicklung (WP15/WP19) entstanden sind.
 * **Refactoring `chunker.py`:** Die Datei ist monolithisch geworden (Parsing, Strategien, LLM-Orchestrierung).
     * *Lösung:* Aufteilung in ein Package `app/core/chunking/` mit Modulen (`strategies.py`, `orchestration.py`, `utils.py`).
-* **Dokumentation:** Kontinuierliche Synchronisation von Code und Docs (v2.6 Stand).
+* **Dokumentation:** Kontinuierliche Synchronisation von Code und Docs (v2.8 Stand).
 
 ### WP-16 – Auto-Discovery & Intelligent Ingestion
 **Status:** 🟡 Geplant
@@ -155,11 +158,6 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h
 **Ziel:** mindnet als MCP-Server bereitstellen, damit Agenten (Claude Desktop, OpenAI) standardisierte Tools nutzen können.
 * **Umfang:** MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).
 
-### WP-20 – Cloud Hybrid Mode (Optional)
-**Status:** ⚪ Optional
-**Ziel:** "Turbo-Modus" für Massen-Imports.
-* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten.
-
 ### WP-21 – Semantic Graph Routing & Canonical Edges
 **Status:** 🟡 Geplant
 **Ziel:** Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?").
@@ -255,3 +253,4 @@ graph TD
     WP22 --> WP14
     WP15(Smart Edges) --> WP21
     WP20(Cloud Hybrid) --> WP15b
+```