From 27b404560c60debaf1a4958a77b6022c8c9cd8cf Mon Sep 17 00:00:00 2001 From: Lars Date: Thu, 25 Dec 2025 19:39:16 +0100 Subject: [PATCH] Dokumentation WP20 --- config/prod.env | 48 +++++++++++++ docs/00_General/00_glossary.md | 21 +++--- docs/02_concepts/02_concept_ai_personality.md | 71 ++++++++++--------- .../03_tech_chat_backend.md | 60 ++++++++++------ .../03_tech_configuration.md | 58 ++++++++------- .../03_tech_ingestion_pipeline.md | 23 +++--- docs/06_Roadmap/06_active_roadmap.md | 25 ++++--- 7 files changed, 193 insertions(+), 113 deletions(-) create mode 100644 config/prod.env diff --git a/config/prod.env b/config/prod.env new file mode 100644 index 0000000..ae3f569 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index 7c65dad..a3ee1f4 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,13 +2,13 @@ doc_type: glossary audience: all status: active -version: 2.7.0 -context: "Zentrales Glossar für Mindnet v2.7. Definitionen von Entitäten, WP-22 Scoring-Konzepten und der Edge Registry." +version: 2.8.0 +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. -* **Alias (Edge):** Ein nutzerfreundliches Synonym (z.B. `basiert_auf`), das während der Ingestion automatisch zum Canonical Type aufgelöst 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). +* **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 (``, `[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). - * `rule`: Durch System-Regeln/Matrix erzeugt (Prio 3). + * `semantic_ai`: Von der KI im Turbo-Mode extrahiert und validiert (Prio 2). + * `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`). \ No newline at end of file diff --git a/docs/02_concepts/02_concept_ai_personality.md b/docs/02_concepts/02_concept_ai_personality.md index 4f2afe6..4f37053 100644 --- a/docs/02_concepts/02_concept_ai_personality.md +++ b/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 -context: "Fachkonzept der KI-Persönlichkeit, der Decision Engine und Erweiterungsstrategien." +version: 2.8 +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`). -* *Aktion:* Das System sucht im Gedächtnis und generiert eine Antwort. +* **Intent:** Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`). +* **Aktion:** Das System sucht im Gedächtnis und generiert eine Antwort. ### Modus B: Interview (Knowledge Capture) -* *Intent:* Der Nutzer will Wissen speichern (`INTERVIEW`). -* *Aktion:* Das System sucht **nicht**, sondern fragt ab und erstellt einen Draft. +* **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`). +* **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) -* **Auslöser:** Fragen wie "Soll ich...?", "Was ist besser?". +### 3.1 Der Berater (Strategy: DECISION) +* **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) -* **Auslöser:** Emotionale Aussagen ("Ich bin frustriert"). +### 3.2 Der Spiegel (Strategy: EMPATHY) +* **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) -* **Auslöser:** Sachfragen ("Was ist Qdrant?"). +### 3.3 Der Bibliothekar (Strategy: FACT) +* **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 -* **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 +### 4.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 -* **Konzept:** Berücksichtigung weicher Faktoren. -* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft. +### 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. --- -## 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. \ No newline at end of file +**Fazit:** Nur wenn **Daten** (Vault), **Infrastruktur** (Resiliente Kaskade) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md index c32f2d1..d1bf0b1 100644 --- a/docs/03_Technical_References/03_tech_chat_backend.md +++ b/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 -context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control Systems." +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, 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. - -**Prioritäten-Levels:** +Jeder LLM-Request steuert über ein `priority`-Flag den Zugriff auf Hardware- und API-Ressourcen: | Priority | Verwendung | Limitierung | | :--- | :--- | :--- | -| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) | -| **background** | Smart Edge Allocation, Drafts | `MINDNET_LLM_BACKGROUND_LIMIT` | +| **realtime** | Chat-Anfragen, Intent-Routing | Keine (Hardware-Limit) | +| **background** | Smart Edge Allocation, Import-Tasks | `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. +* 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 werden durch strikte Timeouts verhindert, die in der `.env` definiert sind. - -* **Chat:** `MINDNET_LLM_TIMEOUT` (Default: 300s). -* **Frontend:** `MINDNET_API_TIMEOUT` (Default: 300s). +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. 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). diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index db92177..3ee257e 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/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 -context: "Umfassende Referenztabellen für Umgebungsvariablen, YAML-Konfigurationen und die Edge Registry Struktur." +version: 2.8.0 +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_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). | -| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). | -| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). | +| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum lokalen LLM-Server. | +| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden für LLM-Anfragen. | +| `MINDNET_API_TIMEOUT` | `300.0` | Globales API-Timeout für das Frontend. | +| `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). | | `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). | --- @@ -199,21 +207,21 @@ Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wir | System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung | | :--------------------- | :--------------------------------------------------- | :-------------------------------------- | -| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. | -| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. | -| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. | -| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. | -| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. | -| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. | -| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. | -| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. | -| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. | -| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. | -| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. | -| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. | -| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. | -| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). | -| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B | +| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. | +| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. | +| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. | +| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. | +| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. | +| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. | +| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. | +| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. | +| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. | +| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. | +| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. | +| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. | +| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. | +| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). | +| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B | **ACHTUNG!** Die Kantentypen **belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index 3acbad3..9ca4efc 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/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 -context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle." +version: 2.8.0 +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. - * **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks). + * **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. + * **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (``) 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. diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 55f9440..755f66e 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/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) -**Fokus:** Visualisierung, Exploration & Intelligent Ingestion. +**Aktueller Stand:** v2.8.0 (Post-WP20/WP76) +**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`.
**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.
**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 (``, `[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?"). @@ -254,4 +252,5 @@ graph TD WP21 --> WP22(Lifecycle & Registry) WP22 --> WP14 WP15(Smart Edges) --> WP21 - WP20(Cloud Hybrid) --> WP15b \ No newline at end of file + WP20(Cloud Hybrid) --> WP15b +``` \ No newline at end of file