From 0d2469f8fab1905522a28bb58e41e02095ab56cf Mon Sep 17 00:00:00 2001 From: Lars Date: Thu, 1 Jan 2026 20:24:09 +0100 Subject: [PATCH] WP25-v3.0.0-Dokumentation --- docs/00_General/00_documentation_map.md | 4 +- docs/00_General/00_glossary.md | 10 +- docs/01_User_Manual/01_chat_usage_guide.md | 54 +++- docs/02_concepts/02_concept_ai_personality.md | 70 +++-- .../03_tech_api_reference.md | 40 ++- .../03_tech_chat_backend.md | 131 ++++++--- .../03_tech_configuration.md | 97 +++++-- docs/05_Development/05_developer_guide.md | 15 +- docs/05_Development/05_testing_guide.md | 28 +- docs/06_Roadmap/06_active_roadmap.md | 72 ++--- docs/99_Archive/WP25_merge_commit.md | 138 +++++++++ docs/99_Archive/WP25_release_notes.md | 268 ++++++++++++++++++ docs/README.md | 4 +- 13 files changed, 767 insertions(+), 164 deletions(-) create mode 100644 docs/99_Archive/WP25_merge_commit.md create mode 100644 docs/99_Archive/WP25_release_notes.md diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md index fef368d..97d9265 100644 --- a/docs/00_General/00_documentation_map.md +++ b/docs/00_General/00_documentation_map.md @@ -151,8 +151,8 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten ## 6. Dokumentations-Status -**Aktuelle Version:** 2.9.1 -**Letzte Aktualisierung:** 2025-01-XX +**Aktuelle Version:** 2.9.3 +**Letzte Aktualisierung:** 2025-12-31 **Status:** ✅ Vollständig und aktiv gepflegt **Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden. \ No newline at end of file diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index 3ff270b..ae2a13e 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,8 +2,8 @@ doc_type: glossary audience: all status: active -version: 2.9.1 -context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion und Mistral-safe Parsing." +version: 2.9.3 +context: "Zentrales Glossar für Mindnet v2.9.3. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG und Mistral-safe Parsing." --- # Mindnet Glossar @@ -23,7 +23,11 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C * **Edge Registry:** Der zentrale Dienst (SSOT), der Kanten-Typen validiert und Aliase in kanonische Typen auflöst. Nutzt `01_edge_vocabulary.md` als Basis. * **LLM Service:** Der Hybrid-Client (v3.3.6), der Anfragen zwischen OpenRouter, Google Gemini und lokalem Ollama routet. Verwaltet Cloud-Timeouts und Quoten-Management. Nutzt zur Text-Bereinigung nun die neutrale `registry.py`, um Circular Imports zu vermeiden. * **Retriever:** Besteht in v2.7+ aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`). Seit WP-14 im Paket `app.core.retrieval` gekapselt. -* **Decision Engine:** Teil des Routers, der Intents erkennt und entsprechende **Boost-Faktoren** für das Retrieval injiziert. +* **Decision Engine (WP-25):** Der zentrale **Agentic Orchestrator**, der Intents erkennt, parallele Wissens-Streams orchestriert und die Ergebnisse synthetisiert. Implementiert Multi-Stream Retrieval und Intent-basiertes Routing. +* **Agentic Multi-Stream RAG (WP-25):** Architektur-Paradigma, bei dem Nutzeranfragen in parallele, spezialisierte Wissens-Streams aufgeteilt werden (Values, Facts, Biography, Risk, Tech), die gleichzeitig abgefragt und zu einer kontextreichen Antwort synthetisiert werden. +* **Stream-Tracing (WP-25):** Kennzeichnung jedes Treffers mit seinem Ursprungs-Stream (`stream_origin`), um Feedback-Optimierung pro Wissensbereich zu ermöglichen. +* **Intent-basiertes Routing (WP-25):** Hybrid-Modus zur Intent-Erkennung mit Keyword Fast-Path (sofortige Erkennung von Triggern) und LLM Slow-Path (semantische Analyse für unklare Anfragen). +* **Wissens-Synthese (WP-25):** Template-basierte Zusammenführung der Ergebnisse aus parallelen Streams mit expliziten Stream-Variablen (z.B. `{values_stream}`, `{risk_stream}`), um dem LLM eine differenzierte Abwägung zu ermöglichen. * **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. * **Database Package (WP-14):** Zentralisiertes Infrastruktur-Paket (`app.core.database`), das den Qdrant-Client (`qdrant.py`) und das Point-Mapping (`qdrant_points.py`) verwaltet. diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md index c560530..eeb1f5b 100644 --- a/docs/01_User_Manual/01_chat_usage_guide.md +++ b/docs/01_User_Manual/01_chat_usage_guide.md @@ -3,8 +3,8 @@ doc_type: user_manual audience: user, mindmaster scope: chat, ui, feedback, graph status: active -version: 2.6 -context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Graph Explorers." +version: 2.9.3 +context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers." --- # Chat & Graph Usage Guide @@ -60,21 +60,49 @@ Ein Editor mit **"File System First"** Garantie. --- -## 3. Den Chat steuern (Intents) +## 3. Den Chat steuern (Intents & Multi-Stream RAG) -Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Der **Hybrid Router v5** unterscheidet intelligent: +Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Seit WP-25 nutzt Mindnet **Agentic Multi-Stream RAG**, das deine Anfrage in parallele Wissens-Streams aufteilt: -### 3.1 Frage-Modus (Wissen abrufen) -Ausgelöst durch `?` oder W-Wörter. +### 3.1 Intent-Erkennung (Hybrid-Router) + +Der Router erkennt deine Absicht auf zwei Wegen: + +**Schnelle Erkennung (Keyword Fast-Path):** +* **"Soll ich..."** → Sofortige Erkennung als `DECISION` (Berater) +* **"Wann..."** → Sofortige Erkennung als `FACT_WHEN` (Zeitpunkte) +* **"Was ist..."** → Sofortige Erkennung als `FACT_WHAT` (Wissen) +* **"Ich fühle..."** → Sofortige Erkennung als `EMPATHY` (Spiegel) + +**Intelligente Analyse (LLM Slow-Path):** +* Bei unklaren Anfragen analysiert die KI semantisch deine Absicht + +### 3.2 Multi-Stream Retrieval (WP-25) + +Anstelle einer einzelnen Suche führt Mindnet nun **parallele Abfragen** in spezialisierten Wissens-Streams aus: + +**Die Streams:** +* **Values Stream:** Deine Identität, Ethik und Prinzipien (`value`, `principle`, `belief`) +* **Facts Stream:** Operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`) +* **Biography Stream:** Persönliche Erfahrungen und Journal-Einträge (`experience`, `journal`) +* **Risk Stream:** Hindernisse und potenzielle Gefahren (`risk`, `obstacle`) +* **Tech Stream:** Technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`) + +**Vorteil:** Jeder Stream fokussiert auf spezifische Wissensbereiche, was zu präziseren und kontextreicheren Antworten führt. + +### 3.3 Frage-Modi (Strategien) * **Entscheidung ("Soll ich?"):** Der **Berater**. - * Mindnet lädt deine Werte (`type: value`) und Ziele (`type: goal`). + * Nutzt: Values Stream, Facts Stream, Risk Stream + * Wägt Fakten gegen deine Werte ab und evaluiert Risiken * *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First'." * **Empathie ("Ich fühle..."):** Der **Spiegel**. - * Mindnet lädt deine Erfahrungen (`type: experience`). + * Nutzt: Biography Stream, Values Stream + * Greift auf deine Erfahrungen und Werte zurück * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..." -* **Fakten ("Was ist?"):** Der **Bibliothekar**. - * Liefert präzise Definitionen. +* **Fakten ("Was ist?", "Wann..."):** Der **Bibliothekar**. + * Nutzt: Facts Stream, Tech Stream, Biography Stream + * Liefert präzise Definitionen und zeitliche Informationen ### 3.2 Befehls-Modus (Interview) Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten". @@ -84,13 +112,17 @@ Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten". --- -## 4. Ergebnisse interpretieren (Explanation Layer) +## 4. Ergebnisse interpretieren (Explanation Layer & Stream-Tracing) Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat. Öffne eine Quellen-Karte, um zu sehen: * *"Hohe textuelle Übereinstimmung."* (Semantik) * *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit) * *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext) +* *"Quelle: Values Stream"* (Stream-Tracing - WP-25) + +**Stream-Tracing (WP-25):** +Jede Quelle wird mit ihrem Ursprungs-Stream markiert (z.B. "Values Stream", "Facts Stream"). Dies hilft dir zu verstehen, aus welchem Wissensbereich die Information stammt. --- diff --git a/docs/02_concepts/02_concept_ai_personality.md b/docs/02_concepts/02_concept_ai_personality.md index 403e2ef..633f443 100644 --- a/docs/02_concepts/02_concept_ai_personality.md +++ b/docs/02_concepts/02_concept_ai_personality.md @@ -1,10 +1,10 @@ --- doc_type: concept audience: architect, product_owner -scope: ai, router, personas, resilience +scope: ai, router, personas, resilience, agentic_rag status: active -version: 2.8.1 -context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und der kognitiven Resilienz (Deep Fallback)." +version: 2.9.3 +context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, Provider-Kaskade und kognitiven Resilienz (Deep Fallback)." --- # Konzept: KI-Persönlichkeit & Router @@ -13,13 +13,45 @@ context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und 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) +## 1. Der Hybrid Router & Agentic Multi-Stream RAG (Das Gehirn) -Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die fachliche Strategie und die technische Ausführung. +Jede Eingabe durchläuft den **Hybrid Router**. Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert. -### 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-basiertes Routing (WP-25) + +Der Router nutzt einen **Hybrid-Modus** mit Keyword Fast-Path und LLM Slow-Path: + +**Keyword Fast-Path:** +* Sofortige Erkennung von Triggern wie "Soll ich", "Wann", "Was ist" +* Reduziert Latenz durch schnelle Keyword-Erkennung ohne LLM-Call + +**LLM Slow-Path:** +* Komplexe semantische Analyse für unklare Anfragen +* Nutzt `intent_router_v1` Prompt zur Klassifizierung + +**Strategien:** +* **FACT_WHAT/FACT_WHEN:** Wissensabfrage (Wissen/Listen, Zeitpunkte) +* **DECISION:** Beratung (Rat, Strategie, Abwägung) +* **EMPATHY:** Reflexion (Emotionale Resonanz) +* **CODING:** Technik (Programmierung, Syntax) +* **INTERVIEW:** Datenerfassung (Wissen speichern) + +### Modus A: Agentic Multi-Stream RAG (WP-25) + +Anstelle einer einzelnen Suche führt das System **parallele Abfragen** in spezialisierten Wissens-Streams aus: + +**Stream-Library:** +* **Values Stream:** Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`) +* **Facts Stream:** Operative Daten (`project`, `decision`, `task`, `goal`, `event`, `state`) +* **Biography Stream:** Persönliche Erfahrungen (`experience`, `journal`, `profile`, `person`) +* **Risk Stream:** Hindernisse und Gefahren (`risk`, `obstacle`, `bias`) +* **Tech Stream:** Technisches Wissen (`concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`) + +**Wissens-Synthese:** +Die Zusammenführung erfolgt über spezialisierte Templates mit expliziten Stream-Variablen (z.B. `{values_stream}`, `{risk_stream}`). Dies ermöglicht dem LLM eine differenzierte Abwägung zwischen Fakten und persönlichen Werten. + +**Stream-Tracing:** +Jeder Treffer wird mit `stream_origin` markiert, um Feedback-Optimierung pro Wissensbereich zu ermöglichen. ### Modus B: Interview (Knowledge Capture) * **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`). @@ -45,18 +77,22 @@ Ein intelligenter Zwilling muss jederzeit verfügbar sein. Mindnet v2.8.1 nutzt Mindnet wechselt den Hut, je nach Situation. ### 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.“* +* **Auslöser:** Fragen wie „Soll ich...?", „Was ist besser?", „Empfehlung...". +* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Values Stream, Facts Stream und Risk Stream aus. +* **Wissens-Synthese:** Wägt Fakten gegen Werte ab, evaluiert Risiken und prüft Kompatibilität mit langfristiger Identität. +* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken."* ### 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.“* +* **Auslöser:** Emotionale Aussagen („Ich bin frustriert", „Ich fühle...", „Stress..."). +* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Biography Stream und Values Stream aus. +* **Wissens-Synthese:** Greift auf persönliche Erfahrungen und Werte zurück, um emotionale Resonanz zu schaffen. +* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen."* -### 3.3 Der Bibliothekar (Strategy: FACT) -* **Auslöser:** Sachfragen („Was ist Qdrant?“). -* **Behavior:** Präzise, neutral, kurz. +### 3.3 Der Bibliothekar (Strategy: FACT_WHAT / FACT_WHEN) +* **Auslöser:** Sachfragen („Was ist...?", „Welche sind...?", „Wann...?", „Datum..."). +* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Facts Stream, Tech Stream und Biography Stream aus. +* **Wissens-Synthese:** Kombiniert harte Fakten mit persönlichen Erfahrungen, falls vorhanden. +* **Behavior:** Präzise, neutral, strukturiert. --- diff --git a/docs/03_Technical_References/03_tech_api_reference.md b/docs/03_Technical_References/03_tech_api_reference.md index 6e1d856..05c60a1 100644 --- a/docs/03_Technical_References/03_tech_api_reference.md +++ b/docs/03_Technical_References/03_tech_api_reference.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, integrator -scope: api, endpoints, integration +scope: api, endpoints, integration, agentic_rag status: active -version: 2.9.1 -context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung." +version: 2.9.3 +context: "Vollständige API-Referenz für alle Mindnet-Endpunkte inklusive WP-25 Agentic Multi-Stream RAG. Basis für Integration und Entwicklung." --- # API Reference @@ -96,21 +96,37 @@ Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming. **Response (Non-Streaming):** ```json { - "intent": "FACT", - "response": "Mindnet ist ein persönliches KI-Gedächtnis...", - "sources": [...], - "query_id": "uuid" + "query_id": "uuid", + "answer": "Mindnet ist ein persönliches KI-Gedächtnis...", + "sources": [ + { + "node_id": "uuid", + "note_id": "uuid", + "semantic_score": 0.85, + "total_score": 0.92, + "stream_origin": "values_stream", // WP-25: Ursprungs-Stream + "explanation": {...} + } + ], + "latency_ms": 450, + "intent": "DECISION", // WP-25: Gewählte Strategie + "intent_source": "Keyword (FastPath)" // WP-25: Quelle der Intent-Erkennung } ``` **Response (Streaming):** Server-Sent Events (SSE) mit Chunks der Antwort. -**Intent-Typen:** -- `FACT`: Wissensabfrage -- `DECISION`: Entscheidungsfrage -- `EMPATHY`: Emotionale Anfrage -- `INTERVIEW`: Wissen erfassen +**Intent-Typen (WP-25):** +- `FACT_WHAT`: Wissensabfrage (Wissen/Listen) +- `FACT_WHEN`: Zeitpunkte (Termine, Daten) +- `DECISION`: Entscheidungsfrage (Beratung, Strategie) +- `EMPATHY`: Emotionale Anfrage (Reflexion) +- `CODING`: Technische Anfrage (Programmierung) +- `INTERVIEW`: Wissen erfassen (Datenerfassung) + +**Stream-Tracing (WP-25):** +Jeder Treffer in `sources` enthält `stream_origin`, um die Zuordnung zum Quell-Stream zu ermöglichen (z.B. "values_stream", "facts_stream", "risk_stream"). --- diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md index bb20742..7c865af 100644 --- a/docs/03_Technical_References/03_tech_chat_backend.md +++ b/docs/03_Technical_References/03_tech_chat_backend.md @@ -1,30 +1,32 @@ --- doc_type: technical_reference audience: developer, architect -scope: backend, chat, llm_service, traffic_control, resilience +scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag status: active -version: 2.9.1 -context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik." +version: 2.9.3 +context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.4.2), WP-25 Agentic Multi-Stream RAG und WP-20 Resilienz-Logik." --- -# Chat Backend & Traffic Control +# Chat Backend & Agentic Multi-Stream RAG -## 1. Hybrid Router (Decision Engine) +## 1. Hybrid Router & Intent-basiertes Routing (WP-25) -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. +Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert. -### 1.1 Intent-Erkennung (Logik) +### 1.1 Intent-Erkennung (Hybrid-Modus) -Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip): +Der Router nutzt einen **Hybrid-Modus** mit Keyword-Fast-Path und LLM-Slow-Path: -1. **Question Detection (Regelbasiert):** - * Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich). - * Wenn positiv: **RAG Modus** (Interview wird blockiert). -2. **Keyword Scan (Fast Path):** - * Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen). - * Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**. -3. **LLM Fallback (Slow Path):** - * Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`. +1. **Keyword Fast-Path (Sofortige Erkennung):** + * Prüft `trigger_keywords` aus `decision_engine.yaml` (z.B. "Soll ich", "Wann", "Was ist"). + * Wenn Match: Sofortige Intent-Zuordnung ohne LLM-Call. + * **Strategien:** FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW. +2. **Type Keywords (Interview-Modus):** + * Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung. + * Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung). +3. **LLM Slow-Path (Semantische Analyse):** + * Wenn unklar: Anfrage an `DecisionEngine._determine_strategy()` zur LLM-basierten Klassifizierung. + * Nutzt `intent_router_v1` Prompt aus `prompts.yaml`. ### 1.2 Prompt-Auflösung (Bulletproof Resolution) @@ -34,24 +36,70 @@ Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt * **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.2 Multi-Stream Retrieval (WP-25) -Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt: +Anstelle einer einzelnen Suche führt die `DecisionEngine` nun **parallele Abfragen** in spezialisierten Streams aus: -1. **Pre-Processing:** Query Rewriting (optional). -2. **Context Enrichment:** - * Abruf via `retriever.py` (Hybrid Search). - * Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung. - * Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt. -3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query. -4. **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt. -5. **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams. +**Stream-Library (definiert in `decision_engine.yaml`):** +* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, etc.). +* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, etc.). +* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`). +* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`). +* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, etc.). + +**Stream-Konfiguration:** +* Jeder Stream nutzt individuelle **Edge-Boosts** (z.B. `guides: 3.0` für Values Stream). +* **Filter-Types** sind strikt mit `types.yaml` (v2.7.0) synchronisiert. +* **Query-Templates** transformieren die ursprüngliche Anfrage für spezialisierte Suche. + +**Parallele Ausführung:** +* `asyncio.gather()` führt alle aktiven Streams gleichzeitig aus. +* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung. +* **Fehlerbehandlung:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage. + +### 1.3 Wissens-Synthese (WP-25) + +Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`: + +**Template-Struktur:** +* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`). +* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors). +* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter. + +**Synthese-Strategien:** +* **FACT_WHAT/FACT_WHEN:** Kombiniert Fakten, Biographie und Technik. +* **DECISION:** Wägt Fakten gegen Werte ab, evaluiert Risiken. +* **EMPATHY:** Fokus auf Biographie und Werte. +* **CODING:** Technik und Fakten. + +### 1.4 RAG Flow (Technisch) + +Wenn der Intent nicht `INTERVIEW` ist, wird folgender Flow ausgeführt: + +1. **Intent Detection:** Hybrid Router klassifiziert die Anfrage. +2. **Multi-Stream Retrieval:** + * Parallele Abfragen in spezialisierten Streams via `DecisionEngine._execute_parallel_streams()`. + * Jeder Stream nutzt individuelle Filter, Edge-Boosts und Query-Templates. +3. **Context Formatting:** + * Stream-Ergebnisse werden in formatierte Kontext-Strings umgewandelt. + * **Ollama Context-Throttling:** Kontext wird auf `MAX_OLLAMA_CHARS` begrenzt (Standard: 10.000). +4. **Synthese:** + * `DecisionEngine._generate_final_answer()` kombiniert alle Streams. + * Template-basierte Prompt-Konstruktion mit Stream-Variablen. +5. **Response:** + * LLM-Antwort wird generiert (provider-spezifisch). + * **Sources:** Alle Treffer aus allen Streams werden dedupliziert und zurückgegeben. --- -## 2. LLM Service & Traffic Control (WP-20) +## 2. LLM Service & Traffic Control (WP-20 / WP-25) -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`, v3.4.2) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten. + +**WP-25 Integration:** +* **Lazy Initialization:** `DecisionEngine` wird erst bei Bedarf initialisiert (verhindert Circular Imports). +* **Ingest-Stability Patch:** Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen beim Vault-Import. +* **Empty Response Guard:** Sicherung gegen leere `choices` Arrays bei OpenRouter (verhindert JSON-Errors). Mit Version 2.8.1 wurde die Architektur der Antwort-Generierung grundlegend gehärtet: @@ -107,10 +155,27 @@ In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementier --- -## 4. Feedback Traceability +## 4. Feedback Traceability & Stream-Tracing (WP-25) -Unterstützt das geplante Self-Tuning (WP08). +Unterstützt das geplante Self-Tuning (WP08) und ermöglicht Stream-spezifische Optimierung. -1. **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`. -2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context). -3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`. \ No newline at end of file +1. **Query ID:** Generiert bei jedem `/chat` Call eine `UUIDv4`. +2. **Stream-Tracing:** Jeder Treffer enthält `stream_origin` für Zuordnung zum Quell-Stream. +3. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context + Intent). +4. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id` und `stream_origin`. + +## 5. Lifespan Management (WP-25) + +Die FastAPI-Anwendung (`app/main.py`, v1.0.0) implementiert **Lifespan-Management** für sauberen Startup und Shutdown: + +**Startup:** +* Integritäts-Check der WP-25 Konfiguration (`decision_engine.yaml`, `prompts.yaml`). +* Validierung kritischer Dateien vor dem Start. + +**Shutdown:** +* Ressourcen-Cleanup (LLMService-Connections schließen). +* Graceful Shutdown für asynchrone Prozesse. + +**Globale Fehlerbehandlung:** +* Fängt unerwartete Fehler in der Multi-Stream Kette ab. +* Strukturierte JSON-Responses bei Engine-Fehlern. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index 8553f00..1951594 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, admin -scope: configuration, env, registry, scoring, resilience, modularization +scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag status: active -version: 2.9.1 -context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur unter Berücksichtigung von WP-14." +version: 2.9.3 +context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur und WP-25 Multi-Stream RAG unter Berücksichtigung von WP-14." --- # Konfigurations-Referenz @@ -224,15 +224,16 @@ Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wir --- -## 5. Decision Engine (`decision_engine.yaml`) +## 5. Decision Engine (`decision_engine.yaml` v3.1.6) -Die Decision Engine fungiert als zentraler Orchestrator für die Intent-Erkennung und das dynamische Retrieval-Routing. Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Informationstypen bevorzugt werden und wie der Wissensgraph für die spezifische Situation verformt wird. +Die Decision Engine fungiert als zentraler **Agentic Orchestrator** für die Intent-Erkennung und das dynamische Multi-Stream Retrieval-Routing (WP-25). Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Wissens-Streams aktiviert werden und wie die Ergebnisse synthetisiert werden. -### 5.1 Intent Recognition: Dual-Path Routing -Das System nutzt ein zweistufiges Verfahren, um die Absicht des Nutzers zu identifizieren: +### 5.1 Intent Recognition: Hybrid-Routing (WP-25) +Das System nutzt einen **Hybrid-Modus** mit Keyword Fast-Path und LLM Slow-Path: -1. **Fast Path (Keyword Trigger):** Das System scannt die Anfrage nach definierten `trigger_keywords`. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt. -2. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting. +1. **Fast Path (Keyword Trigger):** Das System scannt die Anfrage nach definierten `trigger_keywords`. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt (z.B. "Soll ich" → `DECISION`). +2. **Type Keywords:** Prüft `detection_keywords` aus `types.yaml` für Interview-Modus (z.B. "Projekt" + "neu" → `INTERVIEW`). +3. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting (`intent_router_v1`). #### LLM Router Konfiguration Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Strategien (`FACT`, `DECISION`, `EMPATHY`, `CODING`, `INTERVIEW`) zu klassifizieren. @@ -244,36 +245,90 @@ Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Str --- -### 5.2 Strategie-Mechaniken (Graph Shaping) -Jede Strategie definiert drei Hebel, um das Ergebnis des Retrievers zu beeinflussen: +### 5.2 Multi-Stream Konfiguration (WP-25) -* **`inject_types`:** Erzwingt die Einbindung bestimmter Notiz-Typen (z. B. `value` bei Entscheidungen), auch wenn diese semantisch eine geringere Ähnlichkeit aufweisen. +Seit WP-25 nutzt die Decision Engine eine **Stream-Library** mit spezialisierten Wissens-Streams: + +**Stream-Library (`streams_library`):** +* **`values_stream`:** Identität, Ethik und Prinzipien (filter_types: `value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`) +* **`facts_stream`:** Operative Daten (filter_types: `project`, `decision`, `task`, `goal`, `event`, `state`) +* **`biography_stream`:** Persönliche Erfahrungen (filter_types: `experience`, `journal`, `profile`, `person`) +* **`risk_stream`:** Hindernisse und Gefahren (filter_types: `risk`, `obstacle`, `bias`) +* **`tech_stream`:** Technisches Wissen (filter_types: `concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`) + +**Stream-Parameter:** +* **`query_template`:** Transformiert die ursprüngliche Anfrage für spezialisierte Suche (z.B. "Welche meiner Werte und Prinzipien betreffen: {query}") +* **`filter_types`:** Strikte Synchronisation mit `types.yaml` (v2.7.0) +* **`top_k`:** Anzahl der Treffer pro Stream (z.B. 5 für Values, 3 für Risk) +* **`edge_boosts`:** Individuelle Edge-Gewichtung pro Stream (z.B. `guides: 3.0` für Values Stream) + +**Strategie-Komposition (`strategies`):** +Jede Strategie definiert, welche Streams aktiviert werden: + +* **`use_streams`:** Liste der Stream-Keys, die parallel abgefragt werden (z.B. `["values_stream", "facts_stream", "risk_stream"]` für `DECISION`) +* **`prompt_template`:** Template-Key aus `prompts.yaml` für die Wissens-Synthese (z.B. `decision_synthesis_v1`) +* **`prepend_instruction`:** Optional: Zusätzliche Anweisung für das LLM (z.B. "Analysiere die Fakten vor dem Hintergrund meiner Werte") +* **`preferred_provider`:** Optional: Provider-Präferenz für diese Strategie (z.B. `gemini` für DECISION) + +### 5.3 Strategie-Mechaniken (Graph Shaping) +Jede Strategie definiert mehrere Hebel, um das Ergebnis zu beeinflussen: + +* **`use_streams`:** Aktiviert parallele Wissens-Streams (WP-25). * **`edge_boosts`:** Erhöht die Gewichtung spezifischer Kanten-Typen in der Scoring-Formel. Dies ermöglicht es dem Graphen, die Textsuche situativ zu "überstimmen". * **`prepend_instruction`:** Injiziert eine spezifische Systemanweisung in das LLM-Prompt, um den Antwortstil anzupassen (z. B. "Wäge Fakten gegen Werte ab"). --- -### 5.3 Übersicht der Strategien +### 5.4 Übersicht der Strategien (WP-25) -| Strategie | Fokus | Bevorzugte Kanten (`edge_boosts`) | Injektionstypen | +| Strategie | Fokus | Aktive Streams | Bevorzugte Kanten (`edge_boosts`) | | :--- | :--- | :--- | :--- | -| **FACT** | Wissensabfrage & Definitionen | `part_of` (2.0), `composed_of` (2.0), `similar_to` (1.5) | *(Keine)* | -| **DECISION** | Rat, Strategie & Abwägung | `blocks` (2.5), `solves` (2.0), `risk_of` (2.5) | `value`, `principle`, `goal`, `risk` | -| **EMPATHY** | Emotionale Resonanz | `based_on` (2.0), `experienced_in` (2.5), `related_to` (2.0) | `experience`, `belief`, `profile` | -| **CODING** | Programmierung & Syntax | `implemented_in` (3.0), `uses` (2.5), `depends_on` (2.0) | `snippet`, `reference`, `source` | -| **INTERVIEW** | Erfassung neuer Daten | *(Keine)* | *(Keine)* | +| **FACT_WHAT** | Wissensabfrage & Listen | `facts_stream`, `tech_stream`, `biography_stream` | `part_of` (2.0), `depends_on` (1.5), `implemented_in` (1.5) | +| **FACT_WHEN** | Zeitpunkte & Termine | `facts_stream`, `biography_stream`, `tech_stream` | `part_of` (2.0), `depends_on` (1.5) | +| **DECISION** | Rat, Strategie & Abwägung | `values_stream`, `facts_stream`, `risk_stream` | `blocks` (2.5), `impacts` (2.0), `risk_of` (2.5) | +| **EMPATHY** | Emotionale Resonanz | `biography_stream`, `values_stream` | `related_to` (1.5), `experienced_in` (2.0) | +| **CODING** | Programmierung & Syntax | `tech_stream`, `facts_stream` | `uses` (2.5), `implemented_in` (3.0) | +| **INTERVIEW** | Erfassung neuer Daten | *(Keine Streams)* | *(Keine)* | --- -### 5.4 Der Interview-Modus & Schemas +### 5.5 Der Interview-Modus & Schemas Die Strategie `INTERVIEW` dient der strukturierten Datenerfassung. -* **Trigger:** Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren". +* **Trigger:** Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren" (Type Keywords aus `types.yaml`). * **Schema-Logik:** Nutzt das `default`-Schema mit den Feldern `Titel`, `Thema/Inhalt` und `Tags`, sofern kein spezifisches Typ-Schema aus der `types.yaml` greift. * **Dynamik:** In diesem Modus wird der Fokus vom Retrieval (Wissen finden) auf die Extraktion (Wissen speichern) verschoben. +* **Streams:** Keine Streams aktiviert (leere `use_streams` Liste). > **Hinweis:** Da spezifische Schemas für Projekte oder Erfahrungen direkt in der `types.yaml` definiert werden, dient die `decision_engine.yaml` hier primär als Fallback für generische Datenaufnahmen. +### 5.6 Prompts-Konfiguration (`prompts.yaml` v3.1.2) + +Seit WP-25 nutzen die Synthese-Templates explizite Stream-Variablen: + +**Template-Struktur:** +```yaml +decision_synthesis_v1: + ollama: | + WERTE & PRINZIPIEN (Identität): + {values_stream} + + OPERATIVE FAKTEN (Realität): + {facts_stream} + + RISIKO-RADAR (Konsequenzen): + {risk_stream} + + ENTSCHEIDUNGSFRAGE: + {query} +``` + +**Pre-Initialization:** +Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen). + +**Provider-spezifische Templates:** +Separate Versionen für Ollama, Gemini und OpenRouter. + Auszug aus der decision_engine.yaml ```yaml diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 427d163..0f8e5a2 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -1,10 +1,10 @@ --- doc_type: developer_guide audience: developer -scope: workflow, testing, architecture, modules, modularization +scope: workflow, testing, architecture, modules, modularization, agentic_rag status: active -version: 2.9.1 -context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), Modul-Interna, Setup und Git-Workflow." +version: 2.9.3 +context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, Modul-Interna, Setup und Git-Workflow." --- # Mindnet Developer Guide & Workflow @@ -236,7 +236,7 @@ Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit. | :--- | :--- | :--- | :--- | | **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. | | **Config** | `app/config.py` | 🟢 **Core** | **Settings.** Zentrale Konfiguration (Pydantic). Lädt Env-Vars für Qdrant, LLM und Pfade. | -| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API.** Haupt-Endpunkt für Chat. Entscheidet zwischen Interview- und RAG-Modus. | +| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API (WP-25).** Haupt-Endpunkt für Chat. Hybrid Router mit Intent-Erkennung, Multi-Stream Orchestration und Wissens-Synthese. | | | `app/routers/ingest.py` | 🟢 **API** | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. | | | `app/routers/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. | | | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). | @@ -393,12 +393,13 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration* edge_defaults: ["blocks"] # Automatische Kante detection_keywords: ["gefahr", "risiko"] ``` -2. **Strategie (`config/decision_engine.yaml`):** +2. **Strategie (`config/decision_engine.yaml` v3.1.6, WP-25):** ```yaml DECISION: - inject_types: ["value", "risk"] # <--- "risk" hinzufügen + use_streams: ["values_stream", "facts_stream", "risk_stream"] # WP-25: Multi-Stream + inject_types: ["value", "risk"] # Legacy: Fallback für nicht-Stream-Typen ``` - *Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken. + *Ergebnis (WP-25):* Wenn der Intent `DECISION` erkannt wird, führt das System parallele Abfragen in Values, Facts und Risk Streams aus und synthetisiert die Ergebnisse. ### Workflow B: Graph-Farben ändern 1. Öffne `app/frontend/ui_config.py`. diff --git a/docs/05_Development/05_testing_guide.md b/docs/05_Development/05_testing_guide.md index 3310877..445b0de 100644 --- a/docs/05_Development/05_testing_guide.md +++ b/docs/05_Development/05_testing_guide.md @@ -3,8 +3,8 @@ doc_type: developer_guide audience: developer, tester scope: testing, quality_assurance, test_strategies status: active -version: 2.9.1 -context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices." +version: 2.9.3 +context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG." --- # Testing Guide @@ -245,19 +245,29 @@ class TestIngest(unittest.IsolatedAsyncioTestCase): - `tests/test_edges_defaults_smoke.py` - `scripts/edges_full_check.py` -### 4.4 Chat & Intent-Tests +### 4.4 Chat & Intent-Tests (WP-25) **Was wird getestet:** -- Intent-Erkennung (FACT, DECISION, EMPATHY, INTERVIEW) -- Decision Engine +- Intent-Erkennung (FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW) +- Hybrid Router (Keyword Fast-Path + LLM Slow-Path) +- Decision Engine (Multi-Stream Orchestration) +- Parallele Stream-Abfragen (Values, Facts, Biography, Risk, Tech) +- Stream-Tracing (`stream_origin` Markierung) +- Wissens-Synthese (Template-basierte Zusammenführung) - Interview-Modus - Feedback-Loop **Tests:** -- `tests/test_wp06_decision.py` -- `tests/test_interview_intent.py` -- `tests/test_chat_wp05.py` -- `tests/test_feedback_smoke.py` +- `tests/test_wp06_decision.py` - Decision Engine (Legacy) +- `tests/test_interview_intent.py` - Interview-Modus +- `tests/test_chat_wp05.py` - Chat-Backend (Legacy) +- `tests/test_feedback_smoke.py` - Feedback-Loop + +**WP-25 Spezifische Tests (geplant):** +- Multi-Stream Retrieval (parallele Abfragen) +- Stream-Tracing (stream_origin Zuordnung) +- Template-Robustheit (Pre-Initialization) +- Intent-Kollision (Keyword-Fast-Path Präzision) ### 4.5 Ingestion-Tests diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 7b9be49..cb61b71 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -2,14 +2,14 @@ doc_type: roadmap audience: product_owner, developer status: active -version: 2.9.1 -context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b." +version: 2.9.3 +context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25." --- # Mindnet Active Roadmap -**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b) -**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence. +**Aktueller Stand:** v2.9.3 (Post-WP25: Agentic Multi-Stream RAG) +**Fokus:** Agentic Orchestration, Multi-Stream Retrieval & Wissens-Synthese. | Phase | Fokus | Status | | :--- | :--- | :--- | @@ -48,6 +48,8 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio | **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. | +| **WP-15c** | **Multigraph-Support & Diversity Engine** | **Ergebnis:** Section-basierte Links, Note-Level Diversity Pooling, Super-Edge Aggregation, Provenance Firewall. Transformation zu einem hochpräzisen Multigraphen. | +| **WP-25** | **Agentic Multi-Stream RAG Orchestration** | **Ergebnis:** Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine. Intent-basiertes Routing (Hybrid Fast/Slow-Path), parallele Wissens-Streams (Values, Facts, Biography, Risk, Tech), Stream-Tracing und Template-basierte Wissens-Synthese. | ### 2.1 WP-22 Lessons Learned * **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. @@ -191,53 +193,29 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h 2. **Single Source of Truth (SSOT):** Die Registry nutzt `01_edge_vocabulary.md` als führende Konfiguration. 3. **Self-Learning Loop:** Protokollierung unbekannter Kanten in `unknown_edges.jsonl`. -### WP-23: Agentic Multi-Stream Reasoning (Mindnet 2025) +### WP-25: Agentic Multi-Stream RAG Orchestration +**Status:** ✅ Fertig (v2.9.3) -#### 1. Zielsetzung & Problemstellung -Das bisherige System basiert auf einem globalen Scoring-Modell, bei dem Notizen unterschiedlicher Typen (z. B. `insight` vs. `belief`) in einem einzigen Retrieval-Topf konkurrieren. Dies führt dazu, dass leiser gewichtete, aber fundamentale Identitätsmerkmale oft durch hochgewichtete aktuelle Erkenntnisse verdrängt werden. Ziel dieses Pakets ist die Einführung einer parallelen **Stream-Architektur**, um die Vielschichtigkeit menschlicher Entscheidungsprozesse (Werte + Erfahrung + Absicht) im LLM-Kontext zu garantieren. +**Ergebnis:** Transformation von Mindnet von einer klassischen, linearen RAG-Architektur zu einer **Agentic Multi-Stream Engine**. Das System agiert nun als intelligenter Orchestrator, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert. -#### 2. Funktionsbeschreibung: Die Streams -Die Daten aus der `types.yaml` werden in drei logische Verarbeitungseinheiten unterteilt: +**Kern-Features:** +1. **Intent-basiertes Routing:** Hybrid-Modus mit Keyword Fast-Path und LLM Slow-Path +2. **Multi-Stream Retrieval:** Parallele Abfragen in spezialisierten Streams (Values, Facts, Biography, Risk, Tech) +3. **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert +4. **Wissens-Synthese:** Template-basierte Zusammenführung mit expliziten Stream-Variablen +5. **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage -##### A. Identity Stream (Die Wahrheitsebene) -* **Inhalt:** `value`, `belief`, `trait`, `principle`, `need`, `boundary`, `bias`. -* **Zweck:** Definition des moralischen Kompasses, der psychologischen Grundbedürfnisse und kognitiven Muster. -* **Wirkung:** Liefert das "Warum" hinter jeder Handlung. +**Technische Details:** +- Decision Engine v1.0.3: Multi-Stream Orchestrator +- Chat Router v3.0.2: Hybrid Router Integration +- LLM Service v3.4.2: Ingest-Stability Patch +- decision_engine.yaml v3.1.6: Multi-Stream Konfiguration +- prompts.yaml v3.1.2: Stream-Templates -##### B. History Stream (Die Evidenzebene) -* **Inhalt:** `experience`, `event`, `source`, `journal`, `person`. -* **Zweck:** Bereitstellung empirischer Belege aus der Vergangenheit und sozialer Kontexte. -* **Wirkung:** Verankert die Antwort in real erlebten Mustern und Fakten. - -##### C. Action Stream (Die Dynamikebene) -* **Inhalt:** `project`, `decision`, `goal`, `task`, `risk`, `motivation`, `habit`, `state`. -* **Zweck:** Analyse der aktuellen Richtung, geplanter Vorhaben und des gegenwärtigen Zustands. -* **Wirkung:** Liefert den Kontext für die Umsetzung und zukünftige Ziele. - - -#### 3. Technische Wirkungsweise (Solution Sketch) - -##### Schritt 1: Query-Decomposition -Ein initialer Klassifizierungs-Agent analysiert die Nutzeranfrage und bestimmt, welcher Stream primär angesprochen werden muss (z. B. "Wie soll ich mich entscheiden?" boostet den Identity Stream). - -##### Schritt 2: Parallel Stream Retrieval -Anstelle einer Suche werden drei unabhängige Vektor-Suchen mit Typ-Filtern durchgeführt: -* **Search_A (Identity):** Top-5 Ergebnisse aus Identitäts-Notizen. -* **Search_B (History):** Top-5 Ergebnisse aus biografischen/externen Notizen. -* **Search_C (Action):** Top-5 Ergebnisse aus operativen/strategischen Notizen. - -##### Schritt 3: Agentic Synthesis (The Reasoning) -Ein Synthese-Agent (LLM) erhält die aggregierten Ergebnisse in getrennten Sektionen. Die Anweisung lautet: -1. **Prüfung:** Steht das aktuelle Vorhaben (Action) im Einklang mit den Werten (Identity)? -2. **Abgleich:** Welche vergangenen Erfahrungen (History) stützen oder widersprechen diesem Weg? -3. **Korrektur:** Identifiziere mögliche Biases oder Grenzüberschreitungen (Boundary). - - - -#### 4. Erwartete Ergebnisse -* **Höhere Resonanz:** Antworten wirken authentischer, da sie explizit auf das Wertesystem des Nutzers Bezug nehmen. -* **Widerspruchs-Erkennung:** Das System kann den Nutzer aktiv warnen, wenn ein Projekt gegen seine `principles` oder `needs` verstößt. -* **Robustes Retrieval:** Wichtige Identitäts-Informationen gehen nicht mehr im "Rauschen" von hunderten Journal-Einträgen verloren. +**Ausblick (WP-25a):** +- Pre-Synthesis: LLM-basierte Komprimierung überlanger Streams +- Kontext-Budgeting: Intelligente Token-Verteilung +- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich --- ### WP-24 – Proactive Discovery & Agentic Knowledge Mining diff --git a/docs/99_Archive/WP25_merge_commit.md b/docs/99_Archive/WP25_merge_commit.md new file mode 100644 index 0000000..66acec9 --- /dev/null +++ b/docs/99_Archive/WP25_merge_commit.md @@ -0,0 +1,138 @@ +# Branch Merge Commit Message: WP25 + +``` +feat: Agentic Multi-Stream RAG Orchestration (v3.0) + +## Architektur-Transformation (WP-25) + +### Agentic Multi-Stream RAG Orchestration +- Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine +- Parallele Abfragen in spezialisierten Wissens-Streams (Values, Facts, Biography, Risk, Tech) +- Stream-Tracing: Jeder Treffer wird mit `stream_origin` markiert +- Fehler-Resilienz: Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage + +**Geänderte Dateien:** +- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3) +- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2) +- `app/models/dto.py`: Stream-Tracing Support (v0.7.1) + +### Intent-basiertes Routing ("The Brain") +- Hybrid-Modus: Keyword Fast-Path + LLM Slow-Path +- Strategien: FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW +- Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call +- Komplexe semantische Analyse für unklare Anfragen + +**Geänderte Dateien:** +- `app/routers/chat.py`: Hybrid Router mit Keyword-Fast-Path (v3.0.2) +- `app/core/retrieval/decision_engine.py`: LLM-basiertes Routing (v1.0.3) + +### Wissens-Synthese +- Spezialisierte Templates in `prompts.yaml` mit expliziten Stream-Variablen +- Pre-Initialization aller Stream-Variablen (verhindert KeyErrors) +- Provider-spezifische Templates für Ollama, Gemini und OpenRouter +- Differenzierte Abwägung zwischen Fakten und persönlichen Werten + +**Geänderte Dateien:** +- `config/prompts.yaml`: Stream-Templates (v3.1.2) +- `app/core/retrieval/decision_engine.py`: Synthese-Logik (v1.0.3) + +## Stream-Konfiguration & Typ-Synchronisation + +### Stream-Library (decision_engine.yaml v3.1.6) +- **Values Stream:** Identität, Ethik und Prinzipien (filter_types: value, principle, belief, etc.) +- **Facts Stream:** Operative Daten (filter_types: project, decision, task, etc.) +- **Biography Stream:** Persönliche Erfahrungen (filter_types: experience, journal, profile) +- **Risk Stream:** Hindernisse und Gefahren (filter_types: risk, obstacle, bias) +- **Tech Stream:** Technisches Wissen (filter_types: concept, source, glossary, etc.) + +**Edge-Boosts pro Stream:** +- Values: `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0` +- Facts: `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5` +- Risk: `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5` + +**Geänderte Dateien:** +- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6) + +## Bugfixes & Optimierungen + +### Vault-Import Performance +- "Empty Response Guard" korrigiert: Kurze Ingest-Antworten (YES/NO) lösen nicht mehr fälschlicherweise langsame Fallbacks aus +- Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen + +**Geänderte Dateien:** +- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2) + +### Cloud-Resilienz +- Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert +- Verhindert JSON-Errors bei überlasteten APIs + +**Geänderte Dateien:** +- `app/services/llm_service.py`: Empty Response Guard (v3.4.2) + +### Template-Robustheit +- Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine` +- Verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen +- Fallback-Mechanismus bei Template-Fehlern + +**Geänderte Dateien:** +- `app/core/retrieval/decision_engine.py`: Pre-Initialization (v1.0.3) + +### Intent-Kollision +- Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt +- Sicherstellt, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden + +**Geänderte Dateien:** +- `config/decision_engine.yaml`: Keyword-Fix (v3.1.6) + +## Ollama Context-Throttling + +- Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000) +- Automatische Kürzung bei großen Kontexten + +**Geänderte Dateien:** +- `app/routers/chat.py`: Context-Throttling (v3.0.2) + +## Lifespan Management + +- FastAPI-Anwendung implementiert Lifespan-Management für sauberen Startup und Shutdown +- Integritäts-Check der WP-25 Konfiguration beim Startup +- Ressourcen-Cleanup beim Shutdown +- Globale Fehlerbehandlung für asynchrone Prozesse + +**Geänderte Dateien:** +- `app/main.py`: Lifespan Management (v1.0.0) + +## Impact & Breaking Changes + +### Keine Migration erforderlich +**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import. + +**Konfigurations-Updates:** +- `decision_engine.yaml` wurde auf v3.1.6 aktualisiert (Multi-Stream Struktur) +- `prompts.yaml` wurde auf v3.1.2 aktualisiert (Stream-Templates) +- **Empfehlung:** Backup der alten Konfigurationsdateien vor dem Update + +### API-Erweiterungen +- `QueryHit.stream_origin`: Name des Ursprungs-Streams (optional) +- `ChatResponse.intent`: Die gewählte WP-25 Strategie (optional) +- `ChatResponse.intent_source`: Quelle der Intent-Erkennung (optional) + +## Dokumentation + +Alle relevanten Dokumente aktualisiert: +- `03_tech_chat_backend.md`: Agentic Multi-Stream RAG, Intent-basiertes Routing, Wissens-Synthese +- `03_tech_configuration.md`: decision_engine.yaml, prompts.yaml (Stream-Struktur) +- `03_tech_api_reference.md`: Erweiterte DTOs (stream_origin, intent) + +## Versionen + +- Decision Engine: v1.0.3 +- Chat Router: v3.0.2 +- LLM Service: v3.4.2 +- DTOs: v0.7.1 +- Main: v1.0.0 +- decision_engine.yaml: v3.1.6 +- prompts.yaml: v3.1.2 + +Closes #[issue-number] +``` diff --git a/docs/99_Archive/WP25_release_notes.md b/docs/99_Archive/WP25_release_notes.md new file mode 100644 index 0000000..e7acffe --- /dev/null +++ b/docs/99_Archive/WP25_release_notes.md @@ -0,0 +1,268 @@ +# Release Notes: Mindnet v3.0.0 (WP25) + +**Release Date:** 2026-01-01 +**Type:** Feature Release - Agentic Multi-Stream RAG Orchestration +**Branch:** WP25 + +--- + +## 🎯 Übersicht + +Diese Version markiert den Übergang von Mindnet von einer klassischen, linearen RAG-Architektur zu einer **Agentic Multi-Stream Engine**. Das System agiert nun als intelligenter Orchestrator, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert. + +--- + +## ✨ Neue Features + +### Agentic Multi-Stream RAG Orchestration + +Mindnet führt nun **parallele Abfragen** in spezialisierten Wissens-Streams aus, anstatt einer einzelnen Suche: + +**Stream-Library:** +* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`). +* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, `goal`, `event`, `state`). +* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`, `person`). +* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`). +* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`). + +**Vorteile:** +* **Präzise Kontext-Ladung:** Jeder Stream fokussiert auf spezifische Wissensbereiche. +* **Parallele Ausführung:** Alle Streams werden gleichzeitig abgefragt (asyncio.gather). +* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung. +* **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage. + +### Intent-basiertes Routing ("The Brain") + +Der Router wurde zu einem **hybriden System** erweitert, das Anfragen klassifiziert, bevor die Suche beginnt: + +**Strategien:** +* **FACT_WHAT:** Wissen/Listen (z.B. "Was ist...", "Welche sind..."). +* **FACT_WHEN:** Zeitpunkte (z.B. "Wann...", "Datum..."). +* **DECISION:** Beratung (z.B. "Soll ich...", "Sollte ich...", "Empfehlung..."). +* **EMPATHY:** Reflexion (z.B. "Fühle...", "Stress...", "Angst..."). +* **CODING:** Technik (z.B. "Code...", "Python...", "Bug..."). +* **INTERVIEW:** Datenerfassung (z.B. "Neues Projekt...", "Erfahrung..."). + +**Hybrid-Modus:** +* **Keyword Fast-Path:** Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call. +* **LLM Slow-Path:** Komplexe semantische Analyse für unklare Anfragen. +* **Type Keywords:** Automatische Erkennung von Objekt-Typen für Interview-Modus. + +**Vorteil:** Reduziert Latenz durch schnelle Keyword-Erkennung, nutzt LLM nur bei Bedarf. + +### Wissens-Synthese + +Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`: + +**Template-Struktur:** +* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`). +* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors). +* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter. + +**Synthese-Strategien:** +* **FACT_WHAT/FACT_WHEN:** Kombiniert Fakten, Biographie und Technik. +* **DECISION:** Wägt Fakten gegen Werte ab, evaluiert Risiken. +* **EMPATHY:** Fokus auf Biographie und Werte. +* **CODING:** Technik und Fakten. + +**Vorteil:** Ermöglicht dem LLM eine differenzierte Abwägung zwischen Fakten und persönlichen Werten. + +--- + +## 🔧 Verbesserungen + +### Stream-Konfiguration & Typ-Synchronisation + +Jeder Stream nutzt individuelle **Edge-Boosts** und **Filter-Types**, die strikt mit der `types.yaml` (v2.7.0) synchronisiert sind: + +**Beispiele:** +* **Values Stream:** `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0`. +* **Facts Stream:** `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5`. +* **Risk Stream:** `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5`. + +**Vorteil:** Präzise Gewichtung der Graph-Kanten je nach Wissensbereich. + +### Template-Robustheit + +**Pre-Initialization:** Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine` verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen. + +**Fallback-Mechanismus:** Bei Template-Fehlern wird ein vereinfachter Prompt mit allen verfügbaren Stream-Ergebnissen verwendet. + +### Ollama Context-Throttling + +Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext (RAG-Hits) die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000) und kürzt diesen ggf. + +**Vorteil:** Verhindert VRAM-Überlastung bei großen Kontexten. + +--- + +## 🐛 Bugfixes + +- ✅ **Behoben:** Vault-Import Performance - "Empty Response Guard" korrigiert, damit kurze Ingest-Antworten (YES/NO) nicht mehr fälschlicherweise langsame Fallbacks auslösen. +- ✅ **Behoben:** Cloud-Resilienz - Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert, um JSON-Errors bei überlasteten APIs zu verhindern. +- ✅ **Behoben:** Template-Robustheit - Automatische Vor-Initialisierung aller Stream-Variablen verhindert `KeyError`-Abstürze. +- ✅ **Behoben:** Intent-Kollision - Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt, um sicherzustellen, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden. + +--- + +## ⚠️ Breaking Changes & Migration + +### Keine Migration erforderlich + +**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import. + +**Konfigurations-Updates:** +* `decision_engine.yaml` wurde auf v3.1.6 aktualisiert (Multi-Stream Struktur). +* `prompts.yaml` wurde auf v3.1.2 aktualisiert (Stream-Templates). +* **Empfehlung:** Backup der alten Konfigurationsdateien vor dem Update. + +--- + +## 📚 API-Änderungen + +### Erweiterte DTOs + +**QueryHit (erweitert):** +```python +class QueryHit(BaseModel): + # ... bestehende Felder ... + stream_origin: Optional[str] = None # Neu: Name des Ursprungs-Streams +``` + +**ChatResponse (erweitert):** +```python +class ChatResponse(BaseModel): + # ... bestehende Felder ... + intent: Optional[str] = "FACT" # Neu: Die gewählte WP-25 Strategie + intent_source: Optional[str] = "LLM_Router" # Neu: Quelle der Intent-Erkennung +``` + +**Impact für API-Consumer:** +* Frontend kann `stream_origin` für visuelle Kennzeichnung der Quellen nutzen. +* `intent` und `intent_source` ermöglichen Debugging und Analytics. + +--- + +## 📖 Dokumentation + +Alle relevanten Dokumente wurden aktualisiert: + +- ✅ `03_tech_chat_backend.md`: Agentic Multi-Stream RAG, Intent-basiertes Routing, Wissens-Synthese +- ✅ `03_tech_configuration.md`: decision_engine.yaml, prompts.yaml (Stream-Struktur) +- ✅ `03_tech_api_reference.md`: Erweiterte DTOs (stream_origin, intent) + +--- + +## 🔄 Technische Details + +### Geänderte Module + +**Decision Engine:** +- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3) + - Paralleles Retrieval via `_execute_parallel_streams()` + - Stream-Tracing mit `stream_origin` + - Pre-Initialization der Stream-Variablen + +**Chat Router:** +- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2) + - Keyword Fast-Path + LLM Slow-Path + - Multi-Stream Orchestrierung + - Ollama Context-Throttling + +**LLM Service:** +- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2) + - Entfernung des <5-Zeichen Guards + - Empty Response Guard für OpenRouter + - Lazy Initialization der DecisionEngine + +**DTOs:** +- `app/models/dto.py`: Stream-Tracing Support (v0.7.1) + - `stream_origin` in `QueryHit` + - `intent` und `intent_source` in `ChatResponse` + +**Main:** +- `app/main.py`: Lifespan Management (v1.0.0) + - Startup-Integritäts-Check + - Ressourcen-Cleanup beim Shutdown + - Globale Fehlerbehandlung + +**Konfiguration:** +- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6) +- `config/prompts.yaml`: Stream-Templates (v3.1.2) + +### Versionsnummern + +- Decision Engine: **v1.0.3** +- Chat Router: **v3.0.2** +- LLM Service: **v3.4.2** +- DTOs: **v0.7.1** +- Main: **v1.0.0** +- decision_engine.yaml: **v3.1.6** +- prompts.yaml: **v3.1.2** + +--- + +## 🚀 Upgrade-Pfad + +### Für Administratoren + +1. **Code aktualisieren:** + ```bash + git pull origin main + source .venv/bin/activate + pip install -r requirements.txt + ``` + +2. **Konfiguration prüfen:** + ```bash + # Backup der alten Konfigurationen + cp config/decision_engine.yaml config/decision_engine.yaml.backup + cp config/prompts.yaml config/prompts.yaml.backup + + # Prüfen, ob neue Konfigurationen vorhanden sind + ls -la config/decision_engine.yaml config/prompts.yaml + ``` + +3. **Services neu starten:** + ```bash + sudo systemctl restart mindnet-prod + sudo systemctl restart mindnet-ui-prod + ``` + +### Für Entwickler + +- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird +- Frontend kann neue Felder (`stream_origin`, `intent`, `intent_source`) optional nutzen +- Stream-Tracing ermöglicht Feedback-Optimierung pro Wissensbereich + +--- + +## 📝 Bekannte Einschränkungen + +- **Stream-Parallelität:** Maximale Anzahl paralleler Streams ist durch asyncio-Limits begrenzt (typischerweise 5-10 Streams). +- **Kontext-Größe:** Große Kontexte (>10.000 Zeichen) werden bei Ollama automatisch gekürzt. + +--- + +## 🔮 Ausblick (WP-25a: Agentic Refinement) + +Auf Basis des stabilen WP-25 Fundaments sind folgende Erweiterungen geplant: + +* **Pre-Synthesis:** LLM-basierte Komprimierung überlanger Streams vor der finalen Antwortgenerierung. +* **Kontext-Budgeting:** Intelligente Verteilung der verfügbaren Token auf die aktivierten Streams. +* **Stream-specific Provider:** Zuweisung unterschiedlicher KI-Modelle pro Wissensbereich (z.B. lokales Ollama für Identitäts-Werte, Gemini für technische Fakten). + +--- + +## 🙏 Danksagungen + +Diese Version wurde durch umfangreiche Architektur-Überarbeitung ermöglicht. Besonderer Fokus lag auf: +- Transformation zu einer Agentic Multi-Stream Engine +- Intelligente Intent-Erkennung mit Hybrid-Routing +- Parallele Wissens-Synthese mit wertebasierter Abwägung +- Robustheit und Fehler-Resilienz + +--- + +**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen +**Support:** Bei Fragen siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md) diff --git a/docs/README.md b/docs/README.md index b9d04f4..a4de11d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ doc_type: documentation_index audience: all status: active -version: 2.9.1 +version: 2.9.3 context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" --- # Mindnet Dokumentation -Willkommen in der Dokumentation von Mindnet v2.9.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. +Willkommen in der Dokumentation von Mindnet v2.9.3! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. ## 🚀 Schnellstart