Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity

WP25-v3.0.0-Dokumentation

Browse Source
This commit is contained in:
Lars 2026-01-01 20:24:09 +01:00
parent 124849c580
commit 0d2469f8fa
13 changed files with 767 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/00_General/00_documentation_map.md
View File

@ -151,8 +151,8 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten
## 6. Dokumentations-Status ## 6. Dokumentations-Status
**Aktuelle Version:** 2.9.1 **Aktuelle Version:** 2.9.3
**Letzte Aktualisierung:** 2025-01-XX **Letzte Aktualisierung:** 2025-12-31
**Status:** ✅ Vollständig und aktiv gepflegt **Status:** ✅ Vollständig und aktiv gepflegt
**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden. **Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.

10
docs/00_General/00_glossary.md
View File

@ -2,8 +2,8 @@
doc_type: glossary doc_type: glossary
audience: all audience: all
status: active status: active
version: 2.9.1 version: 2.9.3
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." 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 # 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. * **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. * **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. * **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. * **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. * **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. * **Database Package (WP-14):** Zentralisiertes Infrastruktur-Paket (`app.core.database`), das den Qdrant-Client (`qdrant.py`) und das Point-Mapping (`qdrant_points.py`) verwaltet.

54
docs/01_User_Manual/01_chat_usage_guide.md
View File

@ -3,8 +3,8 @@ doc_type: user_manual
audience: user, mindmaster audience: user, mindmaster
scope: chat, ui, feedback, graph scope: chat, ui, feedback, graph
status: active status: active
version: 2.6 version: 2.9.3
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Graph Explorers." context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers."
--- ---
# Chat & Graph Usage Guide # 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) ### 3.1 Intent-Erkennung (Hybrid-Router)
Ausgelöst durch `?` oder W-Wörter.
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**. * **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'." * *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**. * **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..." * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
* **Fakten ("Was ist?"):** Der **Bibliothekar**. * **Fakten ("Was ist?", "Wann..."):** Der **Bibliothekar**.
* Liefert präzise Definitionen. * Nutzt: Facts Stream, Tech Stream, Biography Stream
* Liefert präzise Definitionen und zeitliche Informationen
### 3.2 Befehls-Modus (Interview) ### 3.2 Befehls-Modus (Interview)
Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten". 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. Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat.
Öffne eine Quellen-Karte, um zu sehen: Öffne eine Quellen-Karte, um zu sehen:
* *"Hohe textuelle Übereinstimmung."* (Semantik) * *"Hohe textuelle Übereinstimmung."* (Semantik)
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit) * *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext) * *"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.
--- ---

70
docs/02_concepts/02_concept_ai_personality.md
View File

@ -1,10 +1,10 @@
--- ---
doc_type: concept doc_type: concept
audience: architect, product_owner audience: architect, product_owner
scope: ai, router, personas, resilience scope: ai, router, personas, resilience, agentic_rag
status: active status: active
version: 2.8.1 version: 2.9.3
context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und der kognitiven Resilienz (Deep Fallback)." context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, Provider-Kaskade und kognitiven Resilienz (Deep Fallback)."
--- ---
# Konzept: KI-Persönlichkeit & Router # 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. 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-basiertes Routing (WP-25)
* **Intent:** Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
* **Aktion:** Das System sucht im Gedächtnis und generiert eine Antwort. 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) ### Modus B: Interview (Knowledge Capture)
* **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`). * **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. Mindnet wechselt den Hut, je nach Situation.
### 3.1 Der Berater (Strategy: DECISION) ### 3.1 Der Berater (Strategy: DECISION)
* **Auslöser:** Fragen wie „Soll ich...?“, „Was ist besser?“. * **Auslöser:** Fragen wie „Soll ich...?", „Was ist besser?", „Empfehlung...".
* **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen. * **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Values Stream, Facts Stream und Risk Stream aus.
* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken.“* * **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) ### 3.2 Der Spiegel (Strategy: EMPATHY)
* **Auslöser:** Emotionale Aussagen („Ich bin frustriert“). * **Auslöser:** Emotionale Aussagen („Ich bin frustriert", „Ich fühle...", „Stress...").
* **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze). * **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Biography Stream und Values Stream aus.
* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen.“* * **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) ### 3.3 Der Bibliothekar (Strategy: FACT_WHAT / FACT_WHEN)
* **Auslöser:** Sachfragen („Was ist Qdrant?“). * **Auslöser:** Sachfragen („Was ist...?", „Welche sind...?", „Wann...?", „Datum...").
* **Behavior:** Präzise, neutral, kurz. * **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.
--- ---

40
docs/03_Technical_References/03_tech_api_reference.md
View File

@ -1,10 +1,10 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, integrator audience: developer, integrator
scope: api, endpoints, integration scope: api, endpoints, integration, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung." 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 # API Reference
@ -96,21 +96,37 @@ Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.
**Response (Non-Streaming):** **Response (Non-Streaming):**
```json ```json
{ {
"intent": "FACT", "query_id": "uuid",
"response": "Mindnet ist ein persönliches KI-Gedächtnis...", "answer": "Mindnet ist ein persönliches KI-Gedächtnis...",
"sources": [...], "sources": [
"query_id": "uuid" {
"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):** **Response (Streaming):**
Server-Sent Events (SSE) mit Chunks der Antwort. Server-Sent Events (SSE) mit Chunks der Antwort.
**Intent-Typen:** **Intent-Typen (WP-25):**
- `FACT`: Wissensabfrage - `FACT_WHAT`: Wissensabfrage (Wissen/Listen)
- `DECISION`: Entscheidungsfrage - `FACT_WHEN`: Zeitpunkte (Termine, Daten)
- `EMPATHY`: Emotionale Anfrage - `DECISION`: Entscheidungsfrage (Beratung, Strategie)
- `INTERVIEW`: Wissen erfassen - `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").
--- ---

131
docs/03_Technical_References/03_tech_chat_backend.md
View File

@ -1,30 +1,32 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, architect audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik." 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):** 1. **Keyword Fast-Path (Sofortige Erkennung):**
* Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich). * Prüft `trigger_keywords` aus `decision_engine.yaml` (z.B. "Soll ich", "Wann", "Was ist").
* Wenn positiv: **RAG Modus** (Interview wird blockiert). * Wenn Match: Sofortige Intent-Zuordnung ohne LLM-Call.
2. **Keyword Scan (Fast Path):** * **Strategien:** FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW.
* Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen). 2. **Type Keywords (Interview-Modus):**
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**. * Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung.
3. **LLM Fallback (Slow Path):** * Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung).
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`. 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) ### 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. * **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. * **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). **Stream-Library (definiert in `decision_engine.yaml`):**
2. **Context Enrichment:** * **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, etc.).
* Abruf via `retriever.py` (Hybrid Search). * **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, etc.).
* Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung. * **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`).
* Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt. * **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query. * **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, etc.).
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-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: 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`. 1. **Query ID:** Generiert bei jedem `/chat` Call eine `UUIDv4`.
2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context). 2. **Stream-Tracing:** Jeder Treffer enthält `stream_origin` für Zuordnung zum Quell-Stream.
3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`. 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.

97
docs/03_Technical_References/03_tech_configuration.md
View File

@ -1,10 +1,10 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, admin audience: developer, admin
scope: configuration, env, registry, scoring, resilience, modularization scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur unter Berücksichtigung von WP-14." 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 # 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 ### 5.1 Intent Recognition: Hybrid-Routing (WP-25)
Das System nutzt ein zweistufiges Verfahren, um die Absicht des Nutzers zu identifizieren: 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. 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. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting. 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 #### 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. 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) ### 5.2 Multi-Stream Konfiguration (WP-25)
Jede Strategie definiert drei Hebel, um das Ergebnis des Retrievers zu beeinflussen:
* **`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". * **`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"). * **`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)* | | **FACT_WHAT** | Wissensabfrage & Listen | `facts_stream`, `tech_stream`, `biography_stream` | `part_of` (2.0), `depends_on` (1.5), `implemented_in` (1.5) |
| **DECISION** | Rat, Strategie & Abwägung | `blocks` (2.5), `solves` (2.0), `risk_of` (2.5) | `value`, `principle`, `goal`, `risk` | | **FACT_WHEN** | Zeitpunkte & Termine | `facts_stream`, `biography_stream`, `tech_stream` | `part_of` (2.0), `depends_on` (1.5) |
| **EMPATHY** | Emotionale Resonanz | `based_on` (2.0), `experienced_in` (2.5), `related_to` (2.0) | `experience`, `belief`, `profile` | | **DECISION** | Rat, Strategie & Abwägung | `values_stream`, `facts_stream`, `risk_stream` | `blocks` (2.5), `impacts` (2.0), `risk_of` (2.5) |
| **CODING** | Programmierung & Syntax | `implemented_in` (3.0), `uses` (2.5), `depends_on` (2.0) | `snippet`, `reference`, `source` | | **EMPATHY** | Emotionale Resonanz | `biography_stream`, `values_stream` | `related_to` (1.5), `experienced_in` (2.0) |
| **INTERVIEW** | Erfassung neuer Daten | *(Keine)* | *(Keine)* | | **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. 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. * **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. * **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. > **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 Auszug aus der decision_engine.yaml
```yaml ```yaml

15
docs/05_Development/05_developer_guide.md
View File

@ -1,10 +1,10 @@
--- ---
doc_type: developer_guide doc_type: developer_guide
audience: developer audience: developer
scope: workflow, testing, architecture, modules, modularization scope: workflow, testing, architecture, modules, modularization, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), Modul-Interna, Setup und Git-Workflow." 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 # 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. | | **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. | | **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/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/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
| | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). | | | `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 edge_defaults: ["blocks"] # Automatische Kante
detection_keywords: ["gefahr", "risiko"] detection_keywords: ["gefahr", "risiko"]
``` ```
2. **Strategie (`config/decision_engine.yaml`):** 2. **Strategie (`config/decision_engine.yaml` v3.1.6, WP-25):**
```yaml ```yaml
DECISION: 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 ### Workflow B: Graph-Farben ändern
1. Öffne `app/frontend/ui_config.py`. 1. Öffne `app/frontend/ui_config.py`.

28
docs/05_Development/05_testing_guide.md
View File

@ -3,8 +3,8 @@ doc_type: developer_guide
audience: developer, tester audience: developer, tester
scope: testing, quality_assurance, test_strategies scope: testing, quality_assurance, test_strategies
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices." context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG."
--- ---
# Testing Guide # Testing Guide
@ -245,19 +245,29 @@ class TestIngest(unittest.IsolatedAsyncioTestCase):
- `tests/test_edges_defaults_smoke.py` - `tests/test_edges_defaults_smoke.py`
- `scripts/edges_full_check.py` - `scripts/edges_full_check.py`
### 4.4 Chat & Intent-Tests ### 4.4 Chat & Intent-Tests (WP-25)
**Was wird getestet:** **Was wird getestet:**
- Intent-Erkennung (FACT, DECISION, EMPATHY, INTERVIEW) - Intent-Erkennung (FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW)
- Decision Engine - 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 - Interview-Modus
- Feedback-Loop - Feedback-Loop
**Tests:** **Tests:**
- `tests/test_wp06_decision.py` - `tests/test_wp06_decision.py` - Decision Engine (Legacy)
- `tests/test_interview_intent.py` - `tests/test_interview_intent.py` - Interview-Modus
- `tests/test_chat_wp05.py` - `tests/test_chat_wp05.py` - Chat-Backend (Legacy)
- `tests/test_feedback_smoke.py` - `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 ### 4.5 Ingestion-Tests

72
docs/06_Roadmap/06_active_roadmap.md
View File

@ -2,14 +2,14 @@
doc_type: roadmap doc_type: roadmap
audience: product_owner, developer audience: product_owner, developer
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b." 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 # Mindnet Active Roadmap
**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b) **Aktueller Stand:** v2.9.3 (Post-WP25: Agentic Multi-Stream RAG)
**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence. **Fokus:** Agentic Orchestration, Multi-Stream Retrieval & Wissens-Synthese.
| Phase | Fokus | Status | | 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-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-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-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 ### 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. * **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. 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`. 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 **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.
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.
#### 2. Funktionsbeschreibung: Die Streams **Kern-Features:**
Die Daten aus der `types.yaml` werden in drei logische Verarbeitungseinheiten unterteilt: 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) **Technische Details:**
* **Inhalt:** `value`, `belief`, `trait`, `principle`, `need`, `boundary`, `bias`. - Decision Engine v1.0.3: Multi-Stream Orchestrator
* **Zweck:** Definition des moralischen Kompasses, der psychologischen Grundbedürfnisse und kognitiven Muster. - Chat Router v3.0.2: Hybrid Router Integration
* **Wirkung:** Liefert das "Warum" hinter jeder Handlung. - 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) **Ausblick (WP-25a):**
* **Inhalt:** `experience`, `event`, `source`, `journal`, `person`. - Pre-Synthesis: LLM-basierte Komprimierung überlanger Streams
* **Zweck:** Bereitstellung empirischer Belege aus der Vergangenheit und sozialer Kontexte. - Kontext-Budgeting: Intelligente Token-Verteilung
* **Wirkung:** Verankert die Antwort in real erlebten Mustern und Fakten. - Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
##### 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.
--- ---
### WP-24 – Proactive Discovery & Agentic Knowledge Mining ### WP-24 – Proactive Discovery & Agentic Knowledge Mining

138
docs/99_Archive/WP25_merge_commit.md Normal file
View File

@ -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]
```

268
docs/99_Archive/WP25_release_notes.md Normal file
View File

@ -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)

4
docs/README.md
View File

@ -2,13 +2,13 @@
doc_type: documentation_index doc_type: documentation_index
audience: all audience: all
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation"
--- ---
# 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 ## 🚀 Schnellstart