Compare commits

...
Author SHA1 Message Date
Lars f6f3213b84 WP20final
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-12-25 22:21:41 +01:00
Lars e5db7011f3 WP20 final
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-25 22:17:46 +01:00
Lars b0bc8518ed WP20 final update
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-25 22:16:19 +01:00
Lars 046b648286 docs/03_Technical_References/03_tech_chat_backend.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-12-25 22:05:54 +01:00
Lars e04aecb0c5 docs/03_Technical_References/03_tech_ingestion_pipeline.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-25 22:04:34 +01:00
Lars d64ba06809 docs/00_General/00_glossary.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-12-25 22:02:43 +01:00
Lars b0d73cb053 app/core/ingestion.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-25 21:46:40 +01:00
Lars 5213d262a2 app/core/ingestion.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-25 21:28:54 +01:00
5 changed files with 103 additions and 56 deletions

No files matched your search

+56 -21
View File
@@ -3,8 +3,10 @@ FILE: app/core/ingestion.py
DESCRIPTION: Haupt-Ingestion-Logik. Transformiert Markdown in den Graphen. DESCRIPTION: Haupt-Ingestion-Logik. Transformiert Markdown in den Graphen.
WP-20: Optimiert für OpenRouter (mistralai/mistral-7b-instruct:free). WP-20: Optimiert für OpenRouter (mistralai/mistral-7b-instruct:free).
WP-22: Content Lifecycle, Edge Registry Validation & Multi-Hash. WP-22: Content Lifecycle, Edge Registry Validation & Multi-Hash.
FIX: Finale Mistral-Härtung (<s> & [OUT] Tags), robuste JSON-Recovery & DoD-Sync. FIX: Deep Fallback Logic (v2.11.14). Erkennt Policy Violations auch in validen
VERSION: 2.11.11 JSON-Objekten und erzwingt den lokalen Ollama-Sprung, um Kantenverlust
bei umfangreichen Protokollen zu verhindern.
VERSION: 2.11.14
STATUS: Active STATUS: Active
DEPENDENCIES: app.core.parser, app.core.note_payload, app.core.chunker, app.services.llm_service, app.services.edge_registry DEPENDENCIES: app.core.parser, app.core.note_payload, app.core.chunker, app.services.llm_service, app.services.edge_registry
""" """
@@ -53,7 +55,8 @@ def extract_json_from_response(text: str) -> Any:
Extrahiert JSON-Daten und bereinigt LLM-Steuerzeichen (Mistral/Llama). Extrahiert JSON-Daten und bereinigt LLM-Steuerzeichen (Mistral/Llama).
Entfernt <s>, [OUT], [/OUT] und Markdown-Blöcke für maximale Robustheit. Entfernt <s>, [OUT], [/OUT] und Markdown-Blöcke für maximale Robustheit.
""" """
if not text: return [] if not text or not isinstance(text, str):
return []
# 1. Entferne Mistral/Llama Steuerzeichen und Tags # 1. Entferne Mistral/Llama Steuerzeichen und Tags
clean = text.replace("<s>", "").replace("</s>", "") clean = text.replace("<s>", "").replace("</s>", "")
@@ -137,8 +140,9 @@ class IngestionService:
async def _perform_smart_edge_allocation(self, text: str, note_id: str) -> List[Dict]: async def _perform_smart_edge_allocation(self, text: str, note_id: str) -> List[Dict]:
""" """
WP-20: Nutzt das Hybrid LLM für die semantische Kanten-Extraktion. KI-Extraktion mit Deep-Fallback Logik.
Respektiert die Provider-Einstellung (OpenRouter Primary). Erzwingt den lokalen Ollama-Sprung, wenn die Cloud-Antwort keine verwertbaren
Kanten liefert (häufig bei Policy Violations auf OpenRouter).
""" """
provider = self.settings.MINDNET_LLM_PROVIDER provider = self.settings.MINDNET_LLM_PROVIDER
model = self.settings.OPENROUTER_MODEL if provider == "openrouter" else self.settings.GEMINI_MODEL model = self.settings.OPENROUTER_MODEL if provider == "openrouter" else self.settings.GEMINI_MODEL
@@ -151,9 +155,8 @@ class IngestionService:
template = self.llm.get_prompt("edge_extraction", provider) template = self.llm.get_prompt("edge_extraction", provider)
try: try:
# Sicherheits-Check: Formatierung des Templates gegen KeyError schützen
try: try:
# Nutzt die ersten 6000 Zeichen als Kontext-Fenster # Wir begrenzen den Kontext auf 6000 Zeichen (ca. 1500 Token)
prompt = template.format( prompt = template.format(
text=text[:6000], text=text[:6000],
note_id=note_id, note_id=note_id,
@@ -163,28 +166,57 @@ class IngestionService:
logger.error(f"❌ [Ingestion] Prompt-Template Fehler (Variable {ke} fehlt).") logger.error(f"❌ [Ingestion] Prompt-Template Fehler (Variable {ke} fehlt).")
return [] return []
# 1. Versuch: Anfrage an den primären Cloud-Provider
response_json = await self.llm.generate_raw_response( response_json = await self.llm.generate_raw_response(
prompt=prompt, priority="background", force_json=True, prompt=prompt, priority="background", force_json=True,
provider=provider, model_override=model provider=provider, model_override=model
) )
# Nutzt den verbesserten Mistral-sicheren JSON-Extraktor # Initiales Parsing
raw_data = extract_json_from_response(response_json) raw_data = extract_json_from_response(response_json)
# Recovery: Suche nach Listen in Dictionaries (z.B. {"edges": [...]}) # 2. Dictionary Recovery (Versuche Liste aus Dict zu extrahieren)
if isinstance(raw_data, dict): candidates = []
for k in ["edges", "links", "results", "kanten"]: if isinstance(raw_data, list):
candidates = raw_data
elif isinstance(raw_data, dict):
logger.info(f"ℹ️ [Ingestion] LLM returned dict, checking for embedded lists in {note_id}")
for k in ["edges", "links", "results", "kanten", "matches", "edge_list"]:
if k in raw_data and isinstance(raw_data[k], list): if k in raw_data and isinstance(raw_data[k], list):
raw_data = raw_data[k] candidates = raw_data[k]
break break
# Wenn immer noch keine Liste gefunden, versuche Key-Value Paare (Dict Recovery)
if not isinstance(raw_data, list): if not candidates:
logger.warning(f"⚠️ [Ingestion] LLM lieferte keine Liste für {note_id}") for k, v in raw_data.items():
if isinstance(v, str): candidates.append(f"{k}:{v}")
elif isinstance(v, list): [candidates.append(f"{k}:{i}") for i in v if isinstance(i, str)]
# 3. DEEP FALLBACK: Wenn nach allen Recovery-Versuchen die Liste leer ist UND wir in der Cloud waren
# Triggert den Fallback bei "Data Policy Violations" (leere oder Fehler-JSONs).
if not candidates and provider != "ollama" and self.settings.LLM_FALLBACK_ENABLED:
logger.warning(
f"🛑 [Ingestion] Cloud-Antwort für {note_id} lieferte keine verwertbaren Kanten. "
f"Mögliche Policy Violation oder Refusal. Erzwinge LOKALEN FALLBACK via Ollama..."
)
response_json_local = await self.llm.generate_raw_response(
prompt=prompt, priority="background", force_json=True, provider="ollama"
)
raw_data_local = extract_json_from_response(response_json_local)
# Wiederhole Recovery für lokale Antwort
if isinstance(raw_data_local, list):
candidates = raw_data_local
elif isinstance(raw_data_local, dict):
for k in ["edges", "links", "results"]:
if k in raw_data_local and isinstance(raw_data_local[k], list):
candidates = raw_data_local[k]; break
if not candidates:
logger.warning(f"⚠️ [Ingestion] Auch nach Fallback keine extrahierbaren Kanten für {note_id}")
return [] return []
processed = [] processed = []
for item in raw_data: for item in candidates:
# Fix für 'str' object assignment error: Erkennt sowohl Dict als auch String ["kind:target"]
if isinstance(item, dict) and "to" in item: if isinstance(item, dict) and "to" in item:
item["provenance"] = "semantic_ai" item["provenance"] = "semantic_ai"
item["line"] = f"ai-{provider}" item["line"] = f"ai-{provider}"
@@ -220,6 +252,7 @@ class IngestionService:
except Exception as e: except Exception as e:
return {**result, "error": f"Validation failed: {str(e)}"} return {**result, "error": f"Validation failed: {str(e)}"}
# WP-22: Filter für Systemdateien und Entwürfe
status = fm.get("status", "draft").lower().strip() status = fm.get("status", "draft").lower().strip()
if status in ["system", "template", "archive", "hidden"]: if status in ["system", "template", "archive", "hidden"]:
return {**result, "status": "skipped", "reason": f"lifecycle_{status}"} return {**result, "status": "skipped", "reason": f"lifecycle_{status}"}
@@ -234,7 +267,7 @@ class IngestionService:
except Exception as e: except Exception as e:
return {**result, "error": f"Payload failed: {str(e)}"} return {**result, "error": f"Payload failed: {str(e)}"}
# 3. Change Detection (Strikte DoD Umsetzung: Kein Shortcut) # 3. Change Detection (Strikte DoD Umsetzung)
old_payload = None if force_replace else self._fetch_note_payload(note_id) old_payload = None if force_replace else self._fetch_note_payload(note_id)
check_key = f"{self.active_hash_mode}:{hash_source}:{hash_normalize}" check_key = f"{self.active_hash_mode}:{hash_source}:{hash_normalize}"
old_hash = (old_payload or {}).get("hashes", {}).get(check_key) old_hash = (old_payload or {}).get("hashes", {}).get(check_key)
@@ -272,12 +305,12 @@ class IngestionService:
edges = [] edges = []
context = {"file": file_path, "note_id": note_id} context = {"file": file_path, "note_id": note_id}
# A. Explizite Kanten (User) # A. Explizite Kanten (User / Wikilinks)
for e in extract_edges_with_context(parsed): for e in extract_edges_with_context(parsed):
e["kind"] = edge_registry.resolve(edge_type=e["kind"], provenance="explicit", context={**context, "line": e.get("line")}) e["kind"] = edge_registry.resolve(edge_type=e["kind"], provenance="explicit", context={**context, "line": e.get("line")})
edges.append(e) edges.append(e)
# B. KI Kanten (Turbo) # B. KI Kanten (Turbo Mode mit v2.11.14 Fallback)
ai_edges = await self._perform_smart_edge_allocation(body_text, note_id) ai_edges = await self._perform_smart_edge_allocation(body_text, note_id)
for e in ai_edges: for e in ai_edges:
valid_kind = edge_registry.resolve(edge_type=e.get("kind"), provenance="semantic_ai", context={**context, "line": e.get("line")}) valid_kind = edge_registry.resolve(edge_type=e.get("kind"), provenance="semantic_ai", context={**context, "line": e.get("line")})
@@ -320,6 +353,7 @@ class IngestionService:
return {**result, "error": f"DB Upsert failed: {e}"} return {**result, "error": f"DB Upsert failed: {e}"}
def _fetch_note_payload(self, note_id: str) -> Optional[dict]: def _fetch_note_payload(self, note_id: str) -> Optional[dict]:
"""Holt die Metadaten einer Note aus Qdrant."""
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
try: try:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))]) f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
@@ -328,7 +362,7 @@ class IngestionService:
except: return None except: return None
def _artifacts_missing(self, note_id: str) -> Tuple[bool, bool]: def _artifacts_missing(self, note_id: str) -> Tuple[bool, bool]:
"""Prüft Qdrant aktiv auf vorhandene Chunks und Edges (Kein Shortcut).""" """Prüft Qdrant aktiv auf vorhandene Chunks und Edges."""
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
try: try:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))]) f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
@@ -338,6 +372,7 @@ class IngestionService:
except: return True, True except: return True, True
def _purge_artifacts(self, note_id: str): def _purge_artifacts(self, note_id: str):
"""Löscht verwaiste Chunks/Edges vor einem Re-Import."""
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))]) f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
for suffix in ["chunks", "edges"]: for suffix in ["chunks", "edges"]:
+3 -1
View File
@@ -30,7 +30,9 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
## Konzepte & Features ## Konzepte & Features
* **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). * **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).
* **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. * **Deep Fallback (v2.11.14, WP20):** Ein inhaltsbasierter Rettungsmechanismus in der Ingestion. Im Gegensatz zum technischen Fallback (bei Verbindungsfehlern) wird der Deep Fallback ausgelöst, wenn ein Cloud-Modell zwar technisch erfolgreich antwortet, aber inhaltlich keine verwertbaren Daten liefert (z. B. bei "Data Policy Violations").
* **Silent Refusal (WP20):** Ein Zustand, in dem Cloud-Provider (wie OpenRouter) die Verarbeitung eines Dokuments aufgrund interner Filter ("No data training") verweigern, ohne einen HTTP-Fehler zu senden. Wird durch Deep Fallback abgefangen.
* **Rate-Limit Resilience (WP-20):** 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. * **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`). * **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). * **Intent Boosting:** Dynamische Erhöhung der Kanten-Gewichte basierend auf der Nutzerfrage (z.B. Fokus auf `caused_by` bei "Warum"-Fragen).
+14 -11
View File
@@ -1,15 +1,15 @@
--- ---
doc_type: concept doc_type: concept
audience: architect, product_owner audience: architect, product_owner
scope: ai, router, personas scope: ai, router, personas, resilience
status: active status: active
version: 2.8 version: 2.8.1
context: "Fachkonzept der KI-Persönlichkeit, der Hybrid-Provider-Kaskade und der operationalen Resilienz." context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und der kognitiven Resilienz (Deep Fallback)."
--- ---
# Konzept: KI-Persönlichkeit & Router # Konzept: KI-Persönlichkeit & Router
**Quellen:** `mindnet_functional_architecture.md`, `llm_service.py`, `config.py` **Quellen:** `mindnet_functional_architecture.md`, `llm_service.py`, `config.py`, `ingestion.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“ sowie seine technische Infrastruktur dynamisch 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.
@@ -27,13 +27,16 @@ Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die fachlic
--- ---
## 2. Die Provider-Kaskade (Hybrid-Cloud Resilienz) ## 2. Die hybride LLM-Landschaft (Resilienz-Kaskade)
Ein intelligenter Zwilling muss jederzeit verfügbar sein. Mindnet v2.8.1 nutzt eine **dreistufige Kaskade**, um Intelligenz, Kosten und Verfügbarkeit zu optimieren:
1. **Stufe 1: Cloud-Speed (Turbo-Mode):** Primäre Wahl für komplexe Extraktionsaufgaben und schnelle RAG-Antworten mittels OpenRouter (Mistral-7B) oder Google Gemini (2.5-flash-lite).
2. **Stufe 2: Quoten-Resilienz:** Erkennt das System eine Drosselung durch Cloud-Provider (HTTP 429), pausiert es kontrolliert (`LLM_RATE_LIMIT_WAIT`), führt automatisierte Retries durch und schützt so den laufenden Prozess.
3. **Stufe 3: Deep Fallback & lokale Souveränität (Ollama):** * **Technischer Fallback:** Schlagen alle Cloud-Versuche fehl, übernimmt das lokale Modell (Phi-3).
* **Kognitiver Fallback (v2.11.14):** Liefert die Cloud zwar technisch eine Antwort, verweigert aber inhaltlich die Verarbeitung (Silent Refusal/Policy Violation), wird ein **Deep Fallback** erzwungen, um die Datenintegrität lokal zu retten.
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.
--- ---
@@ -68,7 +71,7 @@ Mindnet wechselt den Hut, je nach Situation.
* **Umsetzung:** Few-Shot Prompting mit eigenen E-Mails/Texten als Stilvorlage. * **Umsetzung:** Few-Shot Prompting mit eigenen E-Mails/Texten als Stilvorlage.
### 4.3 Resilienz als Charakterzug ### 4.3 Resilienz als Charakterzug
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. Durch die **WP-20 Implementierung** zeigt das System „Geduld“: Bei Quoten-Engpässen bricht es nicht ab, sondern wartet auf freie Kapazitäten. Durch das **Deep Fallback (v2.11.14)** besitzt Mindnet eine kognitive Ausdauer, die inhaltliche Zensur oder Blockaden der Cloud erkennt und durch lokale Rechenpower auflöst.
--- ---
@@ -94,6 +97,6 @@ DECISION:
``` ```
**3. Kognitive Ebene (Verständnis)** **3. Kognitive Ebene (Verständnis)**
In `prompts.yaml`: Erkläre dem LLM (provider-spezifisch), was ein Risiko ist. In `prompts.yaml`: Erkläre dem LLM (provider-spezifisch mittels der Prompt-Kaskade), was ein Risiko ist.
**Fazit:** Nur wenn **Daten** (Vault), **Infrastruktur** (Resiliente Kaskade) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling. **Fazit:** Nur wenn **Daten** (Vault), **Infrastruktur** (Resiliente Kaskade) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
@@ -3,8 +3,8 @@ doc_type: technical_reference
audience: developer, architect audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience scope: backend, chat, llm_service, traffic_control, resilience
status: active status: active
version: 2.8 version: 2.8.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService und des WP-76 Resilienz-Systems." context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
--- ---
# Chat Backend & Traffic Control # Chat Backend & Traffic Control
@@ -26,12 +26,13 @@ Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
3. **LLM Fallback (Slow Path):** 3. **LLM Fallback (Slow Path):**
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`. * Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`.
### 1.2 Prompt-Auflösung (WP-20 Fix) ### 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**: 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`). * **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`).
* Existiert dieser nicht, erfolgt ein Fallback auf `gemini` und schließlich auf `ollama`. * **Cloud-Stil Fallback:** Existiert dieser nicht, erfolgt ein Fallback auf das `gemini`-Template.
* Dies garantiert die Rückgabe eines validen Strings und verhindert 500-Fehler bei String-Operationen wie `.replace()`. * **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) ### 1.3 RAG Flow (Technisch)
@@ -48,7 +49,7 @@ Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
--- ---
## 2. LLM Service & Traffic Control (WP-15/WP-20) ## 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. 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.
@@ -63,10 +64,16 @@ Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- un
**Funktionsweise:** **Funktionsweise:**
* Hintergrund-Tasks nutzen ein globales `asyncio.Semaphore`. * 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. * 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. * Chat-Tasks umgehen die Semaphore für minimale Latenz.
### 2.2 Timeout-Konfiguration ### 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: Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhindert:
* **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz. * **Cloud-Calls (OpenRouter/Gemini):** Strikte **45 Sekunden** zur Vermeidung von Blockaden bei Provider-Latenz.
@@ -74,14 +81,15 @@ Deadlocks und "hängende" Importe werden durch differenzierte Timeouts verhinder
--- ---
## 3. Resilience & Quota Management (WP-76) ## 3. Resilience & Quota Management (WP-20)
In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementiert: 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`. 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). 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). 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. **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.
--- ---
@@ -3,17 +3,17 @@ doc_type: technical_reference
audience: developer, devops audience: developer, devops
scope: backend, ingestion, smart_edges, edge_registry scope: backend, ingestion, smart_edges, edge_registry
status: active status: active
version: 2.8.0 version: 2.8.1
context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und WP-76 Resilienz-Logik." context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und Deep Fallback Resilienz."
--- ---
# Ingestion Pipeline & Smart Processing # Ingestion Pipeline & Smart Processing
**Quellen:** `pipeline_playbook.md`, `ingestion.py`, `edge_registry.py`, `01_edge_vocabulary.md`, `llm_service.py` **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.8 integriert dieser Prozess eine **intelligente Quoten-Steuerung** (WP-76) und ein **robustes JSON-Parsing** für Cloud-Modelle (Mistral/Gemini). 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-20) und ein **robustes JSON-Parsing** für Cloud-Modelle (Mistral/Gemini).
## 1. Der Import-Prozess (15-Schritte-Workflow) ## 1. Der Import-Prozess (16-Schritte-Workflow)
Der Prozess ist **asynchron** und **idempotent**. Der Prozess ist **asynchron** und **idempotent**.
@@ -23,7 +23,7 @@ Der Prozess ist **asynchron** und **idempotent**.
2. **Markdown lesen:** Rekursives Scannen des Vaults. 2. **Markdown lesen:** Rekursives Scannen des Vaults.
3. **Frontmatter Check & Hard Skip (WP-22):** 3. **Frontmatter Check & Hard Skip (WP-22):**
* Extraktion von `status` und `type`. * Extraktion von `status` und `type`.
* **Hard Skip Rule:** Wenn `status` in `['system', 'template']` ist, wird die Datei **sofort übersprungen**. Sie wird weder vektorisiert noch in den Graphen aufgenommen. * **Hard Skip Rule:** Wenn `status` in `['system', 'template', 'archive', 'hidden']` ist, wird die Datei **sofort übersprungen**. Sie wird weder vektorisiert noch in den Graphen aufgenommen.
* Validierung der Pflichtfelder (`id`, `title`) für alle anderen Dateien. * Validierung der Pflichtfelder (`id`, `title`) für alle anderen Dateien.
4. **Edge Registry Initialisierung (WP-22):** 4. **Edge Registry Initialisierung (WP-22):**
* Laden der Singleton-Instanz der `EdgeRegistry`. * Laden der Singleton-Instanz der `EdgeRegistry`.
@@ -38,11 +38,12 @@ Der Prozess ist **asynchron** und **idempotent**.
* Vergleich des Hashes mit Qdrant. * Vergleich des Hashes mit Qdrant.
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). * 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). 8. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
9. **Smart Edge Allocation (WP15/WP20):** 9. **Smart Edge Allocation (WP-20):**
* Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM. * Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
* **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last. * **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last.
* **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. * **Resilienz (Quota Handling):** Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via `LLM_RATE_LIMIT_WAIT`), bevor ein Cloud-Retry erfolgt.
* **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (`<s>`) und Framework-Tags (`[OUT]`) zur Sicherstellung validen JSONs. * **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (`<s>`) und Framework-Tags (`[OUT]`) sowie Recovery-Logik für Dictionaries (Suche nach `edges`, `links`, `results`, `kanten`).
* **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals" (Data Policy Violations). Liefert die Cloud trotz erfolgreicher Verbindung keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen, um Kantenverlust zu vermeiden.
10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`. 10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
11. **Alias-Auflösung & Kanonisierung (WP-22):** 11. **Alias-Auflösung & Kanonisierung (WP-22):**
* Jede Kante wird via `edge_registry.resolve()` normalisiert. * Jede Kante wird via `edge_registry.resolve()` normalisiert.
@@ -54,8 +55,6 @@ Der Prozess ist **asynchron** und **idempotent**.
15. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim). 15. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim).
16. **Diagnose:** Integritäts-Check nach dem Lauf. 16. **Diagnose:** Integritäts-Check nach dem Lauf.
--- ---
## 2. Betrieb & CLI Befehle ## 2. Betrieb & CLI Befehle
@@ -120,11 +119,11 @@ Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften).
* **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split). * **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split).
* **Modus "Strict" (`strict_heading_split: true`):** * **Modus "Strict" (`strict_heading_split: true`):**
* Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk. * Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk.
* *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt (verhindert verwaiste Überschriften). * *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt.
* *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt. * *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt.
* **Modus "Soft" (`strict_heading_split: false`):** * **Modus "Soft" (`strict_heading_split: false`):**
* **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split. * **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split.
* **Füll-Logik:** Überschriften *auf* dem Split-Level (z.B. H2) lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat. * **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat.
* *Safety Net:* Auch hier greift das `max` Token Limit. * *Safety Net:* Auch hier greift das `max` Token Limit.
### 3.3 Payload-Felder (Qdrant) ### 3.3 Payload-Felder (Qdrant)