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

dokumentation WP15

Browse Source
This commit is contained in:
Lars 2025-12-12 22:54:59 +01:00
parent 70ffa5cd4e
commit faaa3ef55f
11 changed files with 452 additions and 314 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
Programmmanagement/Programmplan_V2.2.md
View File

@ -1,5 +1,5 @@
# mindnet v2.4 — Programmplan # mindnet v2.4 — Programmplan
**Version:** 2.5.0 (Inkl. WP-15 Smart Edge Allocation) **Version:** 2.6.0 (Inkl. WP-15 Smart Edge Allocation)
**Stand:** 2025-12-12 **Stand:** 2025-12-12
**Status:** Aktiv **Status:** Aktiv
@ -35,6 +35,7 @@
- [WP-14 – Review / Refactoring / Dokumentation (geplant)](#wp-14--review--refactoring--dokumentation-geplant) - [WP-14 – Review / Refactoring / Dokumentation (geplant)](#wp-14--review--refactoring--dokumentation-geplant)
- [WP-15 – Smart Edge Allocation \& Chunking Strategies (abgeschlossen)](#wp-15--smart-edge-allocation--chunking-strategies-abgeschlossen) - [WP-15 – Smart Edge Allocation \& Chunking Strategies (abgeschlossen)](#wp-15--smart-edge-allocation--chunking-strategies-abgeschlossen)
- [WP-16 – Auto-Discovery \& Enrichment (geplant)](#wp-16--auto-discovery--enrichment-geplant) - [WP-16 – Auto-Discovery \& Enrichment (geplant)](#wp-16--auto-discovery--enrichment-geplant)
- [WP-17 – Conversational Memory (Dialog-Gedächtnis) (geplant)](#wp-17--conversational-memory-dialog-gedächtnis-geplant)
- [7. Abhängigkeiten (vereinfacht, aktualisiert)](#7-abhängigkeiten-vereinfacht-aktualisiert) - [7. Abhängigkeiten (vereinfacht, aktualisiert)](#7-abhängigkeiten-vereinfacht-aktualisiert)
- [8. Laufzeit- \& Komplexitätsindikatoren (aktualisiert)](#8-laufzeit---komplexitätsindikatoren-aktualisiert) - [8. Laufzeit- \& Komplexitätsindikatoren (aktualisiert)](#8-laufzeit---komplexitätsindikatoren-aktualisiert)
- [9. Programmfortschritt (Ampel, aktualisiert)](#9-programmfortschritt-ampel-aktualisiert) - [9. Programmfortschritt (Ampel, aktualisiert)](#9-programmfortschritt-ampel-aktualisiert)
@ -555,7 +556,24 @@ Automatisches Erkennen und Vorschlagen von fehlenden Kanten in "dummem" Text (oh
- Komplexität: Hoch - Komplexität: Hoch
--- ---
### WP-17 – Conversational Memory (Dialog-Gedächtnis) (geplant)
**Phase:** D
**Status:** 🟡 geplant
**Ziel:**
Erweiterung des Chat-Backends von einem statischen Request-Response-Modell zu einem zustandsbehafteten Dialogsystem ("Multi-Turn Conversation"). Das System soll sich an vorherige Aussagen im aktuellen Gesprächsverlauf erinnern, um Rückfragen ("Was meinst du damit?") korrekt zu interpretieren.
**Umfang:**
- **API-Erweiterung:** `ChatRequest` DTO erhält ein `history`-Feld (Liste von Nachrichten).
- **Context Management:** Implementierung einer Token-Budget-Logik, die dynamisch zwischen RAG-Kontext (Dokumente) und Dialog-Verlauf (History) balanciert, um das Kontextfenster (8k) optimal zu nutzen.
- **Prompt Engineering:** Integration eines `{chat_history}` Platzhalters in den System-Prompt.
- **Frontend-Update:** Die `ui.py` muss die letzten N Nachrichtenpaare (User/AI) bei jedem Request mitsenden.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
---
## 7. Abhängigkeiten (vereinfacht, aktualisiert) ## 7. Abhängigkeiten (vereinfacht, aktualisiert)
WP01 → WP02 → WP03 → WP04a WP01 → WP02 → WP03 → WP04a
@ -564,6 +582,7 @@ Automatisches Erkennen und Vorschlagen von fehlenden Kanten in "dummem" Text (oh
WP07 → WP10a WP07 → WP10a
WP03 → WP09 WP03 → WP09
WP01/WP03 → WP10 → WP11 → WP12 WP01/WP03 → WP10 → WP11 → WP12
WP10 → WP17
WP11 → WP15 → WP16 WP11 → WP15 → WP16
WP03/WP04 → WP13 WP03/WP04 → WP13
Alles → WP14 Alles → WP14
@ -589,6 +608,7 @@ Automatisches Erkennen und Vorschlagen von fehlenden Kanten in "dummem" Text (oh
| WP14 | Mittel | Niedrig/Mittel | | WP14 | Mittel | Niedrig/Mittel |
| WP15 | Mittel | Hoch | | WP15 | Mittel | Hoch |
| WP16 | Mittel | Hoch | | WP16 | Mittel | Hoch |
| WP17 | Mittel | Mittel |
--- ---
@ -616,6 +636,7 @@ Automatisches Erkennen und Vorschlagen von fehlenden Kanten in "dummem" Text (oh
| WP14 | 🟡 | | WP14 | 🟡 |
| WP15 | 🟢 | | WP15 | 🟢 |
| WP16 | 🟡 | | WP16 | 🟡 |
| WP17 | 🟡 |
--- ---

28
docs/Knowledge_Design_Manual.md
View File

@ -1,7 +1,7 @@
# mindnet v2.4 – Knowledge Design Manual # mindnet v2.4 – Knowledge Design Manual
**Datei:** `docs/mindnet_knowledge_design_manual_v2.4.md` **Datei:** `docs/mindnet_knowledge_design_manual_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Integrierter Stand WP01–WP11) **Status:** **FINAL** (Integrierter Stand WP01–WP15)
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`. **Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
--- ---
@ -24,9 +24,9 @@ Dieses Handbuch ist die **primäre Arbeitsanweisung** für dich als Mindmaster (
### 1.1 Zielsetzung ### 1.1 Zielsetzung
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet. Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet.
Seit Version 2.4 verfügt Mindnet über: Seit Version 2.6 verfügt Mindnet über:
* **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst. * **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
* **Context Intelligence:** Das System lädt je nach Situation unterschiedliche Notiz-Typen (z.B. Werte bei Entscheidungen). * **Smart Edge Allocation:** Das System prüft deine Links intelligent und bindet sie nur an die Textabschnitte (Chunks), wo sie wirklich relevant sind.
* **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden. * **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden.
* **Active Intelligence (WP11):** Das System hilft dir beim Schreiben und Vernetzen (Link-Vorschläge). * **Active Intelligence (WP11):** Das System hilft dir beim Schreiben und Vernetzen (Link-Vorschläge).
@ -69,7 +69,7 @@ Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:
**Die ID (Identifikator):** **Die ID (Identifikator):**
* Muss global eindeutig und **stabil** sein. * Muss global eindeutig und **stabil** sein.
* Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird. * Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
* **Empfehlung:** `YYYYMMDD-slug-hash` (z. B. `20231027-vektor-db-a1b2`). Dies garantiert Eindeutigkeit und Chronologie. * **Empfehlung:** `YYYYMMDD-slug` (z. B. `20231027-vektor-db`). Dies garantiert Eindeutigkeit und Chronologie.
**Dateinamen & Pfade:** **Dateinamen & Pfade:**
* Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär. * Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
@ -80,7 +80,7 @@ Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:
## 3. Note-Typen & Typ-Registry ## 3. Note-Typen & Typ-Registry
Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, **wann** eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval") und **welche Felder** im Interview abgefragt werden. Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, **wann** eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval") und seit WP-15, **ob Smart Edges aktiviert sind**.
### 3.1 Übersicht der Kern-Typen ### 3.1 Übersicht der Kern-Typen
@ -95,8 +95,8 @@ Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die **Rolle
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel | Ziel für `based_on` | | **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel | Ziel für `based_on` |
| **`principle`** | Handlungsleitlinie. | **DECISION** | Regel, Ausnahme | Quelle für `derived_from` | | **`principle`** | Handlungsleitlinie. | **DECISION** | Regel, Ausnahme | Quelle für `derived_from` |
| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte | Ziel für `related_to` | | **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte | Ziel für `related_to` |
| **`risk`** | **NEU:** Ein identifiziertes Risiko oder eine Gefahr. | **DECISION** | Auswirkung, Wahrscheinlichkeit | Quelle für `blocks` | | **`risk`** | Ein identifiziertes Risiko oder eine Gefahr. | **DECISION** | Auswirkung, Wahrscheinlichkeit | Quelle für `blocks` |
| **`belief`** | **NEU:** Glaubenssatz / Überzeugung. | **EMPATHY** | Ursprung, Mantra | - | | **`belief`** | Glaubenssatz / Überzeugung. | **EMPATHY** | Ursprung, Mantra | - |
| **`person`** | Eine reale Person (Netzwerk, Autor). | **FACT** | Rolle, Kontext | - | | **`person`** | Eine reale Person (Netzwerk, Autor). | **FACT** | Rolle, Kontext | - |
| **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | **FACT** | Datum, Tags | - | | **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | **FACT** | Datum, Tags | - |
| **`source`** | Externe Quelle (Buch, PDF, Artikel). | **FACT** | Autor, URL | - | | **`source`** | Externe Quelle (Buch, PDF, Artikel). | **FACT** | Autor, URL | - |
@ -107,13 +107,11 @@ Der `type` steuert im Hintergrund drei technische Mechanismen:
1. **`retriever_weight` (Wichtigkeit):** 1. **`retriever_weight` (Wichtigkeit):**
* Ein `concept` (0.6) wiegt weniger als ein `project` (0.97) oder eine `decision` (1.0). * Ein `concept` (0.6) wiegt weniger als ein `project` (0.97) oder eine `decision` (1.0).
* **Warum?** Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine *Entscheidung* ("Warum wir X nutzen") anzeigen.
2. **`chunk_profile` (Textzerlegung):** 2. **`chunk_profile` (Textzerlegung):**
* `journal` (short): Wird fein zerlegt. * `journal` (short): Wird fein zerlegt.
* `project` (long): Längere Kontext-Fenster. * `experience` (sliding_smart_edges): Wird intelligent analysiert.
3. **`edge_defaults` (Automatische Vernetzung):** 3. **`enable_smart_edge_allocation` (WP15):**
* Mindnet ergänzt automatisch Kanten. * Wenn `true`: Das System analysiert jeden Abschnitt mit KI, um zu prüfen, ob verlinkte Themen dort wirklich relevant sind. Das erhöht die Präzision massiv.
* Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert.
--- ---
@ -291,4 +289,4 @@ Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.
### 7.2 Was bedeutet das für dich? ### 7.2 Was bedeutet das für dich?
* Du kannst dich auf den Inhalt konzentrieren. * Du kannst dich auf den Inhalt konzentrieren.
* Wenn wir in Zukunft (WP08) basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an. * Wenn wir in Zukunft basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.

46
docs/Overview.md
View File

@ -1,8 +1,8 @@
# Mindnet v2.4 – Overview & Einstieg # Mindnet v2.4 – Overview & Einstieg
**Datei:** `docs/mindnet_overview_v2.4.md` **Datei:** `docs/mindnet_overview_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Inkl. Async Intelligence & Editor) **Status:** **FINAL** (Inkl. Smart Edges, Traffic Control & Healing UI)
**Version:** 2.4.0 **Version:** 2.6.0
--- ---
@ -28,14 +28,14 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
### Ebene 1: Content (Das Gedächtnis) ### Ebene 1: Content (Das Gedächtnis)
* **Quelle:** Dein lokaler Obsidian-Vault (Markdown). * **Quelle:** Dein lokaler Obsidian-Vault (Markdown).
* **Funktion:** Speicherung von Fakten, Projekten und Logs. * **Funktion:** Speicherung von Fakten, Projekten und Logs.
* **Technik:** Async Import-Pipeline, Chunking, Vektor-Datenbank (Qdrant). * **Technik:** Async Import-Pipeline, Smart Chunking (LLM-gestützte Kantenzuweisung), Vektor-Datenbank (Qdrant).
* **Status:** 🟢 Live (WP01–WP03, WP11). * **Status:** 🟢 Live (WP01–WP03, WP11, WP15).
### Ebene 2: Semantik (Das Verstehen) ### Ebene 2: Semantik (Das Verstehen)
* **Funktion:** Verknüpfung von isolierten Notizen zu einem Netzwerk. * **Funktion:** Verknüpfung von isolierten Notizen zu einem Netzwerk.
* **Logik:** "Projekt A *hängt ab von* Entscheidung B". * **Logik:** "Projekt A *hängt ab von* Entscheidung B".
* **Technik:** Hybrider Retriever (Graph + Nomic Embeddings), Explanation Engine. * **Technik:** Hybrider Retriever (Graph + Nomic Embeddings), Explanation Engine.
* **Status:** 🟢 Live (WP04, WP11). * **Status:** 🟢 Live (WP04, WP11, WP15).
### Ebene 3: Identität & Interaktion (Die Persönlichkeit) ### Ebene 3: Identität & Interaktion (Die Persönlichkeit)
* **Funktion:** Interaktion, Bewertung und Co-Creation. * **Funktion:** Interaktion, Bewertung und Co-Creation.
@ -43,11 +43,11 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
* "Ich empfehle Lösung X, weil sie unserem Wert 'Datensparsamkeit' entspricht." * "Ich empfehle Lösung X, weil sie unserem Wert 'Datensparsamkeit' entspricht."
* "Ich sehe, du willst ein Projekt starten. Lass uns die Eckdaten erfassen." * "Ich sehe, du willst ein Projekt starten. Lass uns die Eckdaten erfassen."
* **Technik:** * **Technik:**
* **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung vs. Interview). * **Hybrid Router v5:** Erkennt Absichten (Frage vs. Befehl) und unterscheidet Objekte (`types.yaml`) von Handlungen (`decision_engine.yaml`).
* **Strategic Retrieval:** Lädt gezielt Werte oder Erfahrungen nach. * **Traffic Control:** Priorisiert Chat-Anfragen ("Realtime") vor Hintergrund-Jobs ("Background").
* **One-Shot Extraction:** Generiert Entwürfe für neue Notizen. * **One-Shot Extraction:** Generiert Entwürfe für neue Notizen.
* **Active Intelligence:** Schlägt Links während des Schreibens vor. * **Active Intelligence:** Schlägt Links während des Schreibens vor.
* **Status:** 🟢 Live (WP05–WP07, WP10). * **Status:** 🟢 Live (WP05–WP07, WP10, WP15).
--- ---
@ -57,8 +57,9 @@ Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
1. **Input:** Du schreibst Notizen in Obsidian **ODER** lässt sie von Mindnet im Chat entwerfen. 1. **Input:** Du schreibst Notizen in Obsidian **ODER** lässt sie von Mindnet im Chat entwerfen.
2. **Intelligence (Live):** Während du schreibst, analysiert Mindnet den Text und schlägt Verknüpfungen vor (Sliding Window Analyse). 2. **Intelligence (Live):** Während du schreibst, analysiert Mindnet den Text und schlägt Verknüpfungen vor (Sliding Window Analyse).
3. **Ingest:** Ein asynchrones Python-Skript importiert, zerlegt (Chunking) und vernetzt (Edges) die Daten in Qdrant. 3. **Ingest:** Ein asynchrones Python-Skript importiert und zerlegt die Daten.
4. **Intent Recognition:** Der Router analysiert deine Frage: Willst du Fakten, Code, Empathie oder etwas dokumentieren? * **Neu (Smart Edges):** Ein LLM analysiert jeden Textabschnitt und entscheidet, welche Kanten relevant sind.
4. **Intent Recognition:** Der Router analysiert deine Eingabe: Ist es eine Frage (RAG) oder ein Befehl (Interview)?
5. **Retrieval / Action:** 5. **Retrieval / Action:**
* Bei Fragen: Das System sucht Inhalte passend zum Intent. * Bei Fragen: Das System sucht Inhalte passend zum Intent.
* Bei Interviews: Das System wählt das passende Schema (z.B. Projekt-Vorlage). * Bei Interviews: Das System wählt das passende Schema (z.B. Projekt-Vorlage).
@ -69,7 +70,8 @@ Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
* **Backend:** Python 3.10+, FastAPI (Async). * **Backend:** Python 3.10+, FastAPI (Async).
* **Datenbank:** Qdrant (Vektor & Graph, 768 Dim). * **Datenbank:** Qdrant (Vektor & Graph, 768 Dim).
* **KI:** Ollama (Phi-3 Mini für Chat, Nomic für Embeddings) – 100% lokal. * **KI:** Ollama (Phi-3 Mini für Chat, Nomic für Embeddings) – 100% lokal.
* **Frontend:** Streamlit Web-UI (v2.4). * **Traffic Control:** Semaphore-Logik zur Lastverteilung zwischen Chat und Import.
* **Frontend:** Streamlit Web-UI (v2.5) mit Healing Parser.
--- ---
@ -79,13 +81,13 @@ Wo findest du was?
| Wenn du... | ...lies dieses Dokument | | Wenn du... | ...lies dieses Dokument |
| :--- | :--- | | :--- | :--- |
| **...wissen willst, wie man Notizen schreibt.** | `mindnet_knowledge_design_manual_v2.4.md` | | **...wissen willst, wie man Notizen schreibt.** | `mindnet_knowledge_design_manual_v2.6.md` |
| **...das System installieren oder betreiben musst.** | `mindnet_admin_guide_v2.4.md` | | **...das System installieren oder betreiben musst.** | `mindnet_admin_guide_v2.6.md` |
| **...am Python-Code entwickeln willst.** | `mindnet_developer_guide_v2.4.md` | | **...am Python-Code entwickeln willst.** | `mindnet_developer_guide_v2.6.md` |
| **...die Pipeline (Import -> RAG) verstehen willst.** | `mindnet_pipeline_playbook_v2.4.md` | | **...die Pipeline (Import -> RAG) verstehen willst.** | `mindnet_pipeline_playbook_v2.6.md` |
| **...die genaue JSON-Struktur oder APIs suchst.** | `mindnet_technical_architecture.md` | | **...die genaue JSON-Struktur oder APIs suchst.** | `mindnet_technical_architecture_v2.6.md` |
| **...verstehen willst, was fachlich passiert.** | `mindnet_functional_architecture.md` | | **...verstehen willst, was fachlich passiert.** | `mindnet_functional_architecture_v2.6.md` |
| **...den aktuellen Projektstatus suchst.** | `mindnet_appendices_v2.4.md` | | **...den aktuellen Projektstatus suchst.** | `mindnet_appendices_v2.6.md` |
--- ---
@ -99,5 +101,5 @@ Wo findest du was?
## 6. Aktueller Fokus ## 6. Aktueller Fokus
Wir haben den **Interview-Assistenten (WP07)** und die **Backend Intelligence (WP11)** erfolgreich integriert. Wir haben die **Smart Edge Allocation (WP15)** und die **System-Stabilisierung (Traffic Control)** erfolgreich abgeschlossen.
Das System kann nun aktiv helfen, Wissen zu strukturieren und zu vernetzen. Der Fokus verschiebt sich nun in Richtung **Self-Tuning (WP08)**, um aus dem gesammelten Feedback automatisch zu lernen. Das System kann nun aktiv helfen, Wissen zu strukturieren, ohne dabei unter Last zusammenzubrechen. Der Fokus verschiebt sich nun in Richtung **Conversational Memory (WP17)** und **MCP Integration (WP13)**.

47
docs/admin_guide.md
View File

@ -1,8 +1,8 @@
# Mindnet v2.4 – Admin Guide # Mindnet v2.4 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.4.md` **Datei:** `docs/mindnet_admin_guide_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Inkl. Async Architecture & Nomic Model) **Status:** **FINAL** (Inkl. Traffic Control & Smart Edge Config)
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.4.md`. **Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.6.md`.
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB). > Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB).
@ -55,7 +55,7 @@ Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
### 2.4 Ollama Setup (LLM & Embeddings) ### 2.4 Ollama Setup (LLM & Embeddings)
Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings. Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings.
**WICHTIG (Update v2.3.10):** Es muss zwingend `nomic-embed-text` installiert sein, sonst startet der Import nicht. **WICHTIG (Update v2.4):** Es muss zwingend `nomic-embed-text` installiert sein, sonst startet der Import nicht.
# 1. Installieren (Linux Script) # 1. Installieren (Linux Script)
curl -fsSL https://ollama.com/install.sh | sh curl -fsSL https://ollama.com/install.sh | sh
@ -68,7 +68,7 @@ Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings.
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}' curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
### 2.5 Konfiguration (ENV) ### 2.5 Konfiguration (ENV)
Erstelle eine `.env` Datei im Root-Verzeichnis. Achte besonders auf `VECTOR_DIM` und `MINDNET_EMBEDDING_MODEL`. Erstelle eine `.env` Datei im Root-Verzeichnis. Achte besonders auf `VECTOR_DIM` und das neue `MINDNET_LLM_BACKGROUND_LIMIT`.
# Server Config # Server Config
UVICORN_HOST=0.0.0.0 UVICORN_HOST=0.0.0.0
@ -87,11 +87,15 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Achte besonders auf `VECTOR_DIM`
# AI Modelle (Ollama) # AI Modelle (Ollama)
MINDNET_OLLAMA_URL="http://127.0.0.1:11434" MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
MINDNET_LLM_MODEL="phi3:mini" MINDNET_LLM_MODEL="phi3:mini"
MINDNET_EMBEDDING_MODEL="nomic-embed-text" # NEU MINDNET_EMBEDDING_MODEL="nomic-embed-text"
# Timeouts (Erhöht für Async/Nomic) # Timeouts (Erhöht für Async/Nomic/Smart Edges)
MINDNET_LLM_TIMEOUT=300.0 MINDNET_LLM_TIMEOUT=300.0
MINDNET_API_TIMEOUT=60.0 MINDNET_API_TIMEOUT=300.0 # Wichtig: Frontend muss warten können
# Traffic Control (Neu in v2.6)
# Begrenzt parallele LLM-Calls im Import, um Chat stabil zu halten.
MINDNET_LLM_BACKGROUND_LIMIT=2
# Configs # Configs
MINDNET_PROMPTS_PATH="./config/prompts.yaml" MINDNET_PROMPTS_PATH="./config/prompts.yaml"
@ -155,12 +159,15 @@ Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit).
## 3. Betrieb im Alltag ## 3. Betrieb im Alltag
### 3.1 Regelmäßige Importe ### 3.1 Regelmäßige Importe
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden. Das Skript nutzt nun **AsyncIO** und eine Semaphore, um Ollama nicht zu überlasten. Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden. Das Skript nutzt nun **AsyncIO**, **Smart Edges** und **Traffic Control**.
**Cronjob-Beispiel (stündlich):** **Cronjob-Beispiel (stündlich):**
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1 0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
**Hinweis zu Smart Edges:**
Der Import dauert nun länger (ca. 2-3 Min pro Datei), da das LLM intensiv genutzt wird. Dank `MINDNET_LLM_BACKGROUND_LIMIT=2` bleibt der Server dabei aber für den Chat responsive.
### 3.2 Health-Checks ### 3.2 Health-Checks
Prüfe regelmäßig, ob alle Komponenten laufen. Prüfe regelmäßig, ob alle Komponenten laufen.
@ -176,7 +183,7 @@ Prüfe regelmäßig, ob alle Komponenten laufen.
--- ---
## 4. Troubleshooting (Update v2.4) ## 4. Troubleshooting (Update v2.6)
### "Vector dimension error: expected dim: 768, got 384" ### "Vector dimension error: expected dim: 768, got 384"
* **Ursache:** Du versuchst, in eine alte Qdrant-Collection (mit 384 Dim aus v2.2) neue Embeddings (mit 768 Dim von Nomic) zu schreiben. * **Ursache:** Du versuchst, in eine alte Qdrant-Collection (mit 384 Dim aus v2.2) neue Embeddings (mit 768 Dim von Nomic) zu schreiben.
@ -184,15 +191,17 @@ Prüfe regelmäßig, ob alle Komponenten laufen.
1. `python -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes` (Löscht DB). 1. `python -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes` (Löscht DB).
2. `python -m scripts.import_markdown ...` (Baut neu auf). 2. `python -m scripts.import_markdown ...` (Baut neu auf).
### "500 Internal Server Error" beim Speichern ### "500 Internal Server Error" beim Speichern/Chatten
* **Ursache:** Oft Timeout bei Ollama, wenn `nomic-embed-text` noch nicht im RAM geladen ist ("Cold Start"). * **Ursache:** Oft Timeout bei Ollama, wenn `nomic-embed-text` noch nicht im RAM geladen ist ("Cold Start") oder der Import die GPU blockiert.
* **Lösung:** * **Lösung:**
1. Sicherstellen, dass Modell existiert: `ollama list`. 1. `MINDNET_LLM_TIMEOUT` in `.env` auf `300.0` setzen.
2. API neustarten (re-initialisiert Async Clients). 2. `MINDNET_LLM_BACKGROUND_LIMIT` auf `1` reduzieren (falls Hardware schwach).
### "NameError: name 'os' is not defined" ### Import ist sehr langsam
* **Ursache:** Fehlender Import in Skripten nach Updates. * **Ursache:** Smart Edges sind aktiv (`types.yaml`) und analysieren jeden Chunk.
* **Lösung:** `git pull` (Fix wurde in v2.3.10 deployed). * **Lösung:**
* Akzeptieren (für bessere Qualität).
* Oder für Massen-Initial-Import in `types.yaml` temporär `enable_smart_edge_allocation: false` setzen.
--- ---
@ -215,7 +224,7 @@ Wenn die Datenbank korrupt ist oder Modelle gewechselt werden:
# 1. DB komplett leeren (Wipe) # 1. DB komplett leeren (Wipe)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# 2. Alles neu importieren # 2. Alles neu importieren (Force re-calculates Hashes)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
--- ---

57
docs/appendix.md
View File

@ -1,7 +1,7 @@
# Mindnet v2.4 – Appendices & Referenzen # Mindnet v2.4 – Appendices & Referenzen
**Datei:** `docs/mindnet_appendices_v2.4.md` **Datei:** `docs/mindnet_appendices_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Integrierter Stand WP01–WP11) **Status:** **FINAL** (Integrierter Stand WP01–WP15)
**Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`. **Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`.
> Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden. > Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden.
@ -10,22 +10,23 @@
## Anhang A: Typ-Registry Referenz (Default-Werte) ## Anhang A: Typ-Registry Referenz (Default-Werte)
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.4). Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.6).
| Typ (`type`) | Chunk Profile | Retriever Weight | Edge Defaults (Auto-Kanten) | Beschreibung | | Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung |
| :--- | :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- | :--- |
| **concept** | `medium` | 0.60 | `references`, `related_to` | Abstrakte Begriffe, Theorien. | | **concept** | `medium` | 0.60 | Nein | Abstrakte Begriffe, Theorien. |
| **project** | `long` | 0.97 | `references`, `depends_on` | Aktive Vorhaben. Hohe Priorität. | | **project** | `long` | 0.97 | Ja | Aktive Vorhaben. Hohe Priorität. |
| **decision** | `long` | 1.00 | `caused_by`, `references` | Entscheidungen (ADRs). Höchste Prio. | | **decision** | `long` | 1.00 | Ja | Entscheidungen (ADRs). Höchste Prio. |
| **experience** | `medium` | 0.90 | `derived_from`, `inspired_by` | Persönliche Learnings. | | **experience** | `sliding_smart_edges` | 0.90 | **Ja** | Persönliche Learnings. Intensiv analysiert. |
| **journal** | `short` | 0.80 | `related_to` | Zeitgebundene Logs. Fein granular. | | **journal** | `short` | 0.80 | Nein | Zeitgebundene Logs. Fein granular. |
| **person** | `short` | 0.50 | `related_to` | Personen-Profile. | | **person** | `short` | 0.50 | Nein | Personen-Profile. |
| **source** | `long` | 0.50 | *(keine)* | Externe Quellen (Bücher, PDFs). | | **source** | `long` | 0.50 | Nein | Externe Quellen (Bücher, PDFs). |
| **event** | `short` | 0.60 | `related_to` | Meetings, Konferenzen. | | **event** | `short` | 0.60 | Nein | Meetings, Konferenzen. |
| **value** | `medium` | 1.00 | `related_to` | Persönliche Werte/Prinzipien. | | **value** | `medium` | 1.00 | Ja | Persönliche Werte/Prinzipien. |
| **goal** | `medium` | 0.95 | `depends_on` | Strategische Ziele. | | **goal** | `medium` | 0.95 | Ja | Strategische Ziele. |
| **belief** | `medium` | 0.90 | `related_to` | Glaubenssätze. | | **belief** | `medium` | 0.90 | Ja | Glaubenssätze. |
| **default** | `medium` | 1.00 | `references` | Fallback, wenn Typ unbekannt. | | **risk** | `short` | 0.90 | Ja | **NEU:** Risiken & Gefahren. |
| **default** | `medium` | 1.00 | Nein | Fallback, wenn Typ unbekannt. |
--- ---
@ -43,6 +44,7 @@ Referenz aller implementierten Kantenarten (`kind`).
| `similar_to` | Inline | Ja | Inhaltliche Ähnlichkeit. "Ist wie X". | | `similar_to` | Inline | Ja | Inhaltliche Ähnlichkeit. "Ist wie X". |
| `caused_by` | Inline | Nein | Kausalität. "X ist der Grund für Y". | | `caused_by` | Inline | Nein | Kausalität. "X ist der Grund für Y". |
| `solves` | Inline | Nein | Lösung. "Tool X löst Problem Y". | | `solves` | Inline | Nein | Lösung. "Tool X löst Problem Y". |
| `blocks` | Inline | Nein | **NEU:** Blockade. "Risiko X blockiert Projekt Y". |
| `derived_from` | Matrix / Default | Nein | Herkunft. "Erkenntnis stammt aus Prinzip X". | | `derived_from` | Matrix / Default | Nein | Herkunft. "Erkenntnis stammt aus Prinzip X". |
| `based_on` | Matrix | Nein | Fundament. "Erfahrung basiert auf Wert Y". | | `based_on` | Matrix | Nein | Fundament. "Erfahrung basiert auf Wert Y". |
| `uses` | Matrix | Nein | Nutzung. "Projekt nutzt Konzept Z". | | `uses` | Matrix | Nein | Nutzung. "Projekt nutzt Konzept Z". |
@ -78,6 +80,7 @@ Diese sind die Felder, die effektiv in Qdrant gespeichert werden.
"window": "string (text)", // Text + Overlap (für Embedding) "window": "string (text)", // Text + Overlap (für Embedding)
"ord": "integer", // Laufende Nummer (1..N) "ord": "integer", // Laufende Nummer (1..N)
"retriever_weight": "float", // Kopie aus Note (für Query-Speed) "retriever_weight": "float", // Kopie aus Note (für Query-Speed)
"chunk_profile": "string", // Vererbt von Note
"neighbors_prev": ["string"], // ID des Vorgängers "neighbors_prev": ["string"], // ID des Vorgängers
"neighbors_next": ["string"] // ID des Nachfolgers "neighbors_next": ["string"] // ID des Nachfolgers
} }
@ -92,7 +95,8 @@ Diese sind die Felder, die effektiv in Qdrant gespeichert werden.
"scope": "string (keyword)", // Immer 'chunk' "scope": "string (keyword)", // Immer 'chunk'
"rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink' "rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink'
"confidence": "float", // 0.0 - 1.0 "confidence": "float", // 0.0 - 1.0
"note_id": "string (keyword)" // Owner Note ID "note_id": "string (keyword)", // Owner Note ID
"provenance": "keyword" // 'explicit', 'rule', 'smart' (NEU)
} }
--- ---
@ -115,7 +119,8 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | **NEU:** Name des Vektor-Modells. | | `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | **NEU:** Name des Vektor-Modells. |
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server (Neu in v2.2). | | `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server (Neu in v2.2). |
| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout für Ollama (Erhöht für CPU-Inference). | | `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout für Ollama (Erhöht für CPU-Inference). |
| `MINDNET_API_TIMEOUT` | `60.0` | **NEU:** Frontend Timeout (Streamlit). | | `MINDNET_API_TIMEOUT` | `300.0` | **NEU:** Frontend Timeout (Erhöht für Smart Edges). |
| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **NEU:** Max. parallele Import-Tasks (Traffic Control). |
| `MINDNET_VAULT_ROOT` | `./vault` | **NEU:** Pfad für Write-Back Operationen. | | `MINDNET_VAULT_ROOT` | `./vault` | **NEU:** Pfad für Write-Back Operationen. |
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). | | `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). | | `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). |
@ -129,16 +134,19 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
* **Decision Engine:** Komponente, die den Intent prüft und Strategien wählt (WP06). * **Decision Engine:** Komponente, die den Intent prüft und Strategien wählt (WP06).
* **Draft Editor:** Web-Komponente zur Bearbeitung generierter Notizen (WP10a). * **Draft Editor:** Web-Komponente zur Bearbeitung generierter Notizen (WP10a).
* **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert. * **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
* **Healing Parser:** UI-Funktion, die defektes YAML von LLMs repariert (v2.5).
* **Hybrid Router:** Kombination aus Keyword-Matching und LLM-Klassifizierung für Intents. * **Hybrid Router:** Kombination aus Keyword-Matching und LLM-Klassifizierung für Intents.
* **Matrix Logic:** Regelwerk, das Kanten-Typen basierend auf Quell- und Ziel-Typ bestimmt. * **Matrix Logic:** Regelwerk, das Kanten-Typen basierend auf Quell- und Ziel-Typ bestimmt.
* **Nomic:** Das neue, hochpräzise Embedding-Modell (768 Dim). * **Nomic:** Das neue, hochpräzise Embedding-Modell (768 Dim).
* **One-Shot Extractor:** LLM-Strategie zur sofortigen Generierung von Drafts ohne Rückfragen (WP07). * **One-Shot Extractor:** LLM-Strategie zur sofortigen Generierung von Drafts ohne Rückfragen (WP07).
* **RAG (Retrieval Augmented Generation):** Kombination aus Suche und Text-Generierung. * **RAG (Retrieval Augmented Generation):** Kombination aus Suche und Text-Generierung.
* **Resurrection Pattern:** UI-Technik, um Eingaben bei Tab-Wechseln zu erhalten. * **Resurrection Pattern:** UI-Technik, um Eingaben bei Tab-Wechseln zu erhalten.
* **Smart Edge Allocation:** LLM-basierte Prüfung, ob ein Link zu einem Chunk passt (WP15).
* **Traffic Control:** Priorisierung von Chat-Anfragen ("Realtime") vor Import-Last ("Background") im LLM-Service (v2.6).
--- ---
## Anhang F: Workpackage Status (v2.4.0) ## Anhang F: Workpackage Status (v2.6.0)
Aktueller Implementierungsstand der Module. Aktueller Implementierungsstand der Module.
@ -151,9 +159,12 @@ Aktueller Implementierungsstand der Module.
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. | | **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. | | **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. | | **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. | | **WP06** | Decision Engine | 🟢 Live | Hybrid Router v5, Strategic Retrieval. |
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** | | **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). | | **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | | **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Core, Nomic, Matrix.** | | **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic, Matrix.** |
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control.** |
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |

62
docs/dev_workflow.md
View File

@ -1,6 +1,6 @@
# Mindnet v2.4 – Entwickler-Workflow # Mindnet v2.4 – Entwickler-Workflow
**Datei:** `docs/DEV_WORKFLOW.md` **Datei:** `docs/DEV_WORKFLOW.md`
**Stand:** 2025-12-11 (Aktualisiert: Inkl. Async Intelligence & Nomic) **Stand:** 2025-12-12 (Aktualisiert: v2.6 mit Traffic Control)
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server). Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
@ -35,14 +35,14 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung.
2. **Branch erstellen:** 2. **Branch erstellen:**
* Klicke wieder unten links auf `main`. * Klicke wieder unten links auf `main`.
* Wähle `+ Create new branch...`. * Wähle `+ Create new branch...`.
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp11-async-fix`). * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp15-traffic-control`).
* Drücke **Enter**. * Drücke **Enter**.
3. **Sicherheits-Check:** 3. **Sicherheits-Check:**
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!** * Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
4. **Coden:** 4. **Coden:**
* Nimm deine Änderungen vor (z.B. neue Schemas in `decision_engine.yaml` oder Async-Logik in `ingestion.py`). * Nimm deine Änderungen vor (z.B. neue Schemas in `types.yaml` oder Async-Logik in `ingestion.py`).
5. **Sichern & Hochladen:** 5. **Sichern & Hochladen:**
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**. * **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
@ -64,15 +64,27 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
```bash ```bash
git fetch git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an # Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp11-async-fix git checkout feature/wp15-traffic-control
git pull git pull
``` ```
4. **Umgebung vorbereiten (WICHTIG für v2.4):** 4. **Umgebung vorbereiten (WICHTIG für v2.6):**
Prüfe deine `.env` Datei. Sie benötigt jetzt Einträge für die Traffic Control.
```bash
nano .env
```
**Ergänze/Prüfe:**
```ini
# Traffic Control (Neu in v2.6)
MINDNET_LLM_BACKGROUND_LIMIT=2 # Max. parallele Import-Tasks
MINDNET_API_TIMEOUT=300.0 # Frontend wartet länger
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
```
**Dependencies aktualisieren:**
```bash ```bash
source .venv/bin/activate source .venv/bin/activate
pip install -r requirements.txt # HTTPX usw. pip install -r requirements.txt
# Sicherstellen, dass das neue Embedding-Modell da ist:
ollama pull nomic-embed-text ollama pull nomic-embed-text
``` ```
@ -102,18 +114,15 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
``` ```
6. **Validieren (Smoke Tests):** 6. **Validieren (Smoke Tests v2.6):**
* **Browser:** Öffne `http://<IP>:8502` um die UI zu testen (Intent Badge prüfen!). * **Test A: Last-Test (Traffic Control):**
* **CLI:** Führe Testskripte in einem **zweiten Terminal** aus: 1. Starte einen Import im Terminal: `python3 -m scripts.import_markdown ...`
2. Öffne **gleichzeitig** `http://<IP>:8502` im Browser.
3. Stelle eine Chat-Frage ("Was ist Mindnet?").
4. **Erwartung:** Der Chat antwortet sofort (Realtime Lane), während der Import im Hintergrund weiterläuft (Background Lane).
**Test A: Intelligence / Aliases (Neu in WP11)** * **Test B: API Check**
```bash
python debug_analysis.py
# Erwartung: "✅ ALIAS GEFUNDEN"
```
**Test B: API Check**
```bash ```bash
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}' curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
``` ```
@ -147,6 +156,9 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).
pip install -r requirements.txt pip install -r requirements.txt
ollama pull nomic-embed-text ollama pull nomic-embed-text
# .env prüfen (Traffic Control)
# Ggf. MINDNET_LLM_BACKGROUND_LIMIT=2 hinzufügen
# Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade): # Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade):
# python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes # python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force # python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
@ -168,7 +180,7 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
cd ~/mindnet_dev cd ~/mindnet_dev
git checkout main git checkout main
git pull git pull
git branch -d feature/wp11-async-fix git branch -d feature/wp15-traffic-control
``` ```
3. **VS Code:** 3. **VS Code:**
* Auf `main` wechseln. * Auf `main` wechseln.
@ -190,15 +202,15 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
## 4. Troubleshooting ## 4. Troubleshooting
**"Vector dimension error: expected 768, got 384"** **"Read timed out" im Frontend**
* **Ursache:** Du hast `nomic-embed-text` (768) aktiviert, aber die DB ist noch alt (384). * **Ursache:** Backend braucht für Smart Edges länger als 60s.
* **Lösung:** `scripts.reset_qdrant` ausführen und neu importieren. * **Lösung:** `MINDNET_API_TIMEOUT=300.0` in `.env` setzen und Services neustarten.
**"Read timed out (300s)" / 500 Error beim Interview** **Import ist extrem langsam**
* **Ursache:** Das LLM (Ollama) braucht für den One-Shot Draft länger als das Timeout erlaubt. * **Ursache:** Smart Edges analysieren jeden Chunk mit LLM.
* **Lösung:** * **Lösung:**
1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0`. * Akzeptieren (Qualität vor Speed).
2. Starte die Server neu. * Oder temporär in `config/types.yaml`: `enable_smart_edge_allocation: false`.
**"UnicodeDecodeError in .env"** **"UnicodeDecodeError in .env"**
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei. * **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.

66
docs/developer_guide.md
View File

@ -1,7 +1,7 @@
# Mindnet v2.4 – Developer Guide # Mindnet v2.4 – Developer Guide
**Datei:** `docs/mindnet_developer_guide_v2.4.md` **Datei:** `docs/mindnet_developer_guide_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Inkl. Async Core, Nomic & Frontend State) **Status:** **FINAL** (Inkl. Async Core, Nomic, Traffic Control & Frontend State)
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`. **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
> **Zielgruppe:** Entwickler:innen. > **Zielgruppe:** Entwickler:innen.
@ -9,7 +9,7 @@
--- ---
- [Mindnet v2.4 – Developer Guide](#mindnet-v24--developer-guide) - [Mindnet v2.4 – Developer Guide](#mindnet-v24--developer-guide)
- [1. Projektstruktur (Post-WP10)](#1-projektstruktur-post-wp10) - [1. Projektstruktur (Post-WP15)](#1-projektstruktur-post-wp15)
- [2. Lokales Setup (Development)](#2-lokales-setup-development) - [2. Lokales Setup (Development)](#2-lokales-setup-development)
- [2.1 Voraussetzungen](#21-voraussetzungen) - [2.1 Voraussetzungen](#21-voraussetzungen)
- [2.2 Installation](#22-installation) - [2.2 Installation](#22-installation)
@ -21,6 +21,7 @@
- [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever) - [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever)
- [3.4 Das Frontend (`app.frontend.ui`)](#34-das-frontend-appfrontendui) - [3.4 Das Frontend (`app.frontend.ui`)](#34-das-frontend-appfrontendui)
- [3.5 Embedding Service (`app.services.embeddings_client`)](#35-embedding-service-appservicesembeddings_client) - [3.5 Embedding Service (`app.services.embeddings_client`)](#35-embedding-service-appservicesembeddings_client)
- [3.6 Traffic Control (`app.services.llm_service`)](#36-traffic-control-appservicesllm_service)
- [4. Tests \& Debugging](#4-tests--debugging) - [4. Tests \& Debugging](#4-tests--debugging)
- [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest) - [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest)
- [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests) - [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests)
@ -34,15 +35,15 @@
--- ---
## 1. Projektstruktur (Post-WP10) ## 1. Projektstruktur (Post-WP15)
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt. Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
mindnet/ mindnet/
├── app/ ├── app/
│ ├── core/ # Kernlogik │ ├── core/ # Kernlogik
│ │ ├── ingestion.py # NEU: Async Ingestion Service (WP11) │ │ ├── ingestion.py # NEU: Async Ingestion Service mit Change Detection
│ │ ├── chunker.py # Text-Zerlegung │ │ ├── chunker.py # Smart Chunker Orchestrator
│ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik) │ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik)
│ │ ├── retriever.py # Scoring & Hybrid Search │ │ ├── retriever.py # Scoring & Hybrid Search
│ │ ├── qdrant.py # DB-Verbindung │ │ ├── qdrant.py # DB-Verbindung
@ -52,21 +53,22 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
│ ├── routers/ # FastAPI Endpoints │ ├── routers/ # FastAPI Endpoints
│ │ ├── query.py # Suche │ │ ├── query.py # Suche
│ │ ├── ingest.py # NEU: Save/Analyze (WP11) │ │ ├── ingest.py # NEU: Save/Analyze (WP11)
│ │ ├── chat.py # Hybrid Router & Interview Logic (WP06/WP07) │ │ ├── chat.py # Hybrid Router v5 & Interview Logic
│ │ ├── feedback.py # Feedback (WP04c) │ │ ├── feedback.py # Feedback (WP04c)
│ │ └── ... │ │ └── ...
│ ├── services/ # Interne & Externe Dienste │ ├── services/ # Interne & Externe Dienste
│ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode) │ │ ├── llm_service.py # Ollama Client mit Traffic Control
│ │ ├── embeddings_client.py# NEU: Async Embeddings (HTTPX) │ │ ├── semantic_analyzer.py# NEU: LLM-Filter für Edges (WP15)
│ │ ├── embeddings_client.py# Async Embeddings (HTTPX)
│ │ ├── feedback_service.py # Logging (JSONL Writer) │ │ ├── feedback_service.py # Logging (JSONL Writer)
│ │ └── discovery.py # NEU: Intelligence Logic (WP11) │ │ └── discovery.py # NEU: Intelligence Logic (WP11)
│ ├── frontend/ # NEU (WP10) │ ├── frontend/ # NEU (WP10)
│ │ └── ui.py # Streamlit Application inkl. Draft-Editor │ │ └── ui.py # Streamlit Application inkl. Healing Parser
│ └── main.py # Entrypoint der API │ └── main.py # Entrypoint der API
├── config/ # YAML-Konfigurationen (Single Source of Truth) ├── config/ # YAML-Konfigurationen (Single Source of Truth)
│ ├── types.yaml # Import-Regeln │ ├── types.yaml # Import-Regeln & Smart-Edge Config
│ ├── prompts.yaml # LLM Prompts & Interview Templates (WP06/07) │ ├── prompts.yaml # LLM Prompts & Interview Templates
│ ├── decision_engine.yaml # Router-Strategien & Schemas (WP06/07) │ ├── decision_engine.yaml # Router-Strategien (Actions only)
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte │ └── retriever.yaml # Scoring-Regeln & Kantengewichte
├── data/ ├── data/
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl) │ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
@ -121,12 +123,13 @@ Erstelle eine `.env` Datei im Root-Verzeichnis.
MINDNET_LLM_MODEL="phi3:mini" MINDNET_LLM_MODEL="phi3:mini"
MINDNET_EMBEDDING_MODEL="nomic-embed-text" # NEU MINDNET_EMBEDDING_MODEL="nomic-embed-text" # NEU
MINDNET_OLLAMA_URL="http://127.0.0.1:11434" MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
MINDNET_LLM_TIMEOUT=300.0 MINDNET_LLM_TIMEOUT=300.0 # Timeout für CPU-Inference Cold-Starts
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
MINDNET_LLM_BACKGROUND_LIMIT=2 # NEU: Limit für parallele Import-Tasks
# Frontend Settings (WP10) # Frontend Settings (WP10)
MINDNET_API_URL="http://localhost:8002" MINDNET_API_URL="http://localhost:8002"
MINDNET_API_TIMEOUT=60.0 MINDNET_API_TIMEOUT=300.0 # Erhöht wegen Smart Edge Berechnung
# Import-Strategie # Import-Strategie
MINDNET_HASH_COMPARE="Body" MINDNET_HASH_COMPARE="Body"
@ -154,15 +157,15 @@ Wir entwickeln mit zwei Services. Du kannst sie manuell in zwei Terminals starte
### 3.1 Der Importer (`scripts.import_markdown`) ### 3.1 Der Importer (`scripts.import_markdown`)
Dies ist das komplexeste Modul. Dies ist das komplexeste Modul.
* **Einstieg:** `scripts/import_markdown.py` -> `main_async()`. * **Einstieg:** `scripts/import_markdown.py` -> `main_async()`.
* **Async & Semaphore:** Das Skript nutzt nun `asyncio` und eine Semaphore (Limit: 5), um parallele Embeddings zu erzeugen, ohne Ollama zu überlasten. * **Smart Edges:** Nutzt `app.core.chunker` und `app.services.semantic_analyzer` zur Kanten-Filterung.
* **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5). * **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5).
* **Debugging:** Nutze `--dry-run` oder `scripts/payload_dryrun.py`. * **Robustheit:** In `ingestion.py` sind Mechanismen wie Change Detection und Robust File I/O (fsync) implementiert.
### 3.2 Der Hybrid Router (`app.routers.chat`) ### 3.2 Der Hybrid Router (`app.routers.chat`)
Hier liegt die Logik für Intent Detection (WP06) und Interview-Modus (WP07). Hier liegt die Logik für Intent Detection (WP06) und Interview-Modus (WP07).
* **Logic:** `_classify_intent` prüft zuerst Keywords (Fast Path) und fällt auf `llm_service.generate_raw_response` zurück (Slow Path), wenn konfiguriert. * **Question Detection:** Prüft zuerst, ob der Input eine Frage ist. Falls ja -> RAG.
* **One-Shot:** Wenn Intent `INTERVIEW` erkannt wird, wird **kein Retrieval** ausgeführt. Stattdessen wird ein Draft generiert. * **Keyword Match:** Prüft Keywords in `decision_engine.yaml` und `types.yaml`.
* **Erweiterung:** Um neue Intents hinzuzufügen, editiere nur die YAML, nicht den Python-Code (Late Binding). * **Priority:** Ruft `llm_service` mit `priority="realtime"` auf.
### 3.3 Der Retriever (`app.core.retriever`) ### 3.3 Der Retriever (`app.core.retriever`)
Hier passiert das Scoring. Hier passiert das Scoring.
@ -172,14 +175,19 @@ Hier passiert das Scoring.
### 3.4 Das Frontend (`app.frontend.ui`) ### 3.4 Das Frontend (`app.frontend.ui`)
Eine Streamlit-App (WP10). Eine Streamlit-App (WP10).
* **Resurrection Pattern:** Das UI nutzt ein spezielles State-Management, um Eingaben bei Tab-Wechseln (Chat <-> Editor) zu erhalten. Widgets synchronisieren sich mit `st.session_state`. * **Resurrection Pattern:** Das UI nutzt ein spezielles State-Management, um Eingaben bei Tab-Wechseln (Chat <-> Editor) zu erhalten. Widgets synchronisieren sich mit `st.session_state`.
* **Draft Editor:** Enthält einen YAML-Sanitizer (`normalize_meta_and_body`), der sicherstellt, dass LLM-Halluzinationen im Frontmatter nicht das File zerstören. * **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter (fehlendes `---`) automatisch.
* **Logik:** Ruft `/chat` und `/feedback` und `/ingest/analyze` Endpoints der API auf. * **Logik:** Ruft `/chat`, `/feedback` und `/ingest/analyze` Endpoints der API auf.
### 3.5 Embedding Service (`app.services.embeddings_client`) ### 3.5 Embedding Service (`app.services.embeddings_client`)
**Neu in v2.4:** **Neu in v2.4:**
* Nutzt `httpx.AsyncClient` für non-blocking Calls an Ollama. * Nutzt `httpx.AsyncClient` für non-blocking Calls an Ollama.
* Unterstützt dediziertes Embedding-Modell (`nomic-embed-text`) getrennt vom Chat-Modell. * Unterstützt dediziertes Embedding-Modell (`nomic-embed-text`) getrennt vom Chat-Modell.
* Enthält Legacy-Funktion `embed_text` für synchrone Skripte.
### 3.6 Traffic Control (`app.services.llm_service`)
**Neu in v2.6:**
* Stellt sicher, dass Batch-Prozesse (Import) den Live-Chat nicht ausbremsen.
* **Methode:** `generate_raw_response(..., priority="background")` aktiviert eine Semaphore (Limit default 2).
* **Config:** `MINDNET_LLM_BACKGROUND_LIMIT` in `.env`.
--- ---
@ -235,6 +243,7 @@ Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
chunk_profile: short # Risiken sind oft kurze Statements chunk_profile: short # Risiken sind oft kurze Statements
retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
detection_keywords: ["risiko", "gefahr"] # Für Router
**2. Strategie-Ebene (`config/decision_engine.yaml`)** **2. Strategie-Ebene (`config/decision_engine.yaml`)**
Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen. Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen.
@ -262,14 +271,17 @@ Konfiguriere `edge_weights`, wenn Kausalität wichtiger ist als Ähnlichkeit.
Wenn Mindnet neue Fragen stellen soll: Wenn Mindnet neue Fragen stellen soll:
**1. Schema erweitern (`config/decision_engine.yaml`)** **1. Schema erweitern (`config/types.yaml`)**
Füge das Feld in die Liste ein. Füge das Feld in die Liste ein.
project: project:
fields: ["Titel", "Ziel", "Budget"] # <--- Budget neu schema:
- "Titel"
- "Ziel"
- "Budget (Neu)"
**2. Keine Code-Änderung nötig** **2. Keine Code-Änderung nötig**
Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch und weist das LLM an, das Budget zu extrahieren oder `[TODO]` zu setzen. Der `One-Shot Extractor` liest diese Liste dynamisch.
### Fazit ### Fazit
* **Vault:** Liefert das Wissen. * **Vault:** Liefert das Wissen.

134
docs/mindnet_functional_architecture.md
View File

@ -1,9 +1,9 @@
# Mindnet v2.4 – Fachliche Architektur # Mindnet v2.4 – Fachliche Architektur
**Datei:** `docs/mindnet_functional_architecture_v2.4.md` **Datei:** `docs/mindnet_functional_architecture_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Integrierter Stand WP01–WP11: Async Intelligence) **Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control)
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit). > Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Smart Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit).
--- ---
<details> <details>
@ -19,7 +19,8 @@
- [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett) - [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
- [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit) - [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
- [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert) - [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
- [2.4 Matrix-Logik (Kontextsensitive Kanten) – Neu in v2.4](#24-matrix-logik-kontextsensitive-kanten--neu-in-v24) - [2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6](#24-smart-edge-allocation-llm-gefiltert--neu-in-v26)
- [2.5 Matrix-Logik (Kontextsensitive Kanten)](#25-matrix-logik-kontextsensitive-kanten)
- [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik) - [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
- [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml) - [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
- [4.1 Zweck](#41-zweck) - [4.1 Zweck](#41-zweck)
@ -27,13 +28,15 @@
- [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer) - [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
- [5.1 Scoring-Modell](#51-scoring-modell) - [5.1 Scoring-Modell](#51-scoring-modell)
- [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b) - [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
- [6) Context Intelligence \& Intent Router (WP06–WP11)](#6-context-intelligence--intent-router-wp06wp11) - [5.3 Graph-Expansion](#53-graph-expansion)
- [6) Context Intelligence \& Intent Router (WP06–WP15)](#6-context-intelligence--intent-router-wp06wp15)
- [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten) - [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten)
- [6.2 Der Intent-Router (Keyword \& Semantik)](#62-der-intent-router-keyword--semantik) - [6.2 Der Hybrid Router v5 (Action vs. Question)](#62-der-hybrid-router-v5-action-vs-question)
- [6.3 Strategic Retrieval (Injektion von Werten)](#63-strategic-retrieval-injektion-von-werten) - [6.3 Traffic Control (Realtime vs. Background)](#63-traffic-control-realtime-vs-background)
- [6.4 Reasoning (Das Gewissen)](#64-reasoning-das-gewissen) - [6.4 Strategic Retrieval (Injektion von Werten)](#64-strategic-retrieval-injektion-von-werten)
- [6.5 Der Interview-Modus (One-Shot Extraction)](#65-der-interview-modus-one-shot-extraction) - [6.5 Reasoning (Das Gewissen)](#65-reasoning-das-gewissen)
- [6.6 Active Intelligence (Link Suggestions) – Neu in v2.4](#66-active-intelligence-link-suggestions--neu-in-v24) - [6.6 Der Interview-Modus (One-Shot Extraction)](#66-der-interview-modus-one-shot-extraction)
- [6.7 Active Intelligence (Link Suggestions)](#67-active-intelligence-link-suggestions)
- [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick) - [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick)
- [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung) - [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung)
- [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus) - [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus)
@ -49,7 +52,7 @@
- [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz) - [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz)
- [14) Beispiel – Von Markdown zu Kanten](#14-beispiel--von-markdown-zu-kanten) - [14) Beispiel – Von Markdown zu Kanten](#14-beispiel--von-markdown-zu-kanten)
- [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien) - [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
- [16) Workpackage Status (v2.4.0)](#16-workpackage-status-v240) - [16) Workpackage Status (v2.6.0)](#16-workpackage-status-v260)
</details> </details>
--- ---
@ -63,7 +66,7 @@ Die drei zentralen Artefakt-Sammlungen lauten:
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“) - `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes) - `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
Die Import-Pipeline (seit v2.3.10 asynchron) erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → embed → edge → upsert*. Die Import-Pipeline (seit v2.6 mit **Traffic Control** und **Smart Edges**) erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → embed → smart-edge-allocation → upsert*.
--- ---
@ -80,9 +83,9 @@ Die Import-Pipeline (seit v2.3.10 asynchron) erzeugt diese Artefakte **determini
- Jeder Chunk gehört **genau einer** Note. - Jeder Chunk gehört **genau einer** Note.
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*. - Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
- **Update v2.4:** Chunks werden jetzt durch das Modell `nomic-embed-text` in **768-dimensionale Vektoren** umgewandelt. Dies erlaubt eine deutlich höhere semantische Auflösung als frühere Modelle (384 Dim). - **Update v2.4:** Chunks werden jetzt durch das Modell `nomic-embed-text` in **768-dimensionale Vektoren** umgewandelt. Dies erlaubt eine deutlich höhere semantische Auflösung als frühere Modelle (384 Dim).
- **Neu in v2.2:** Alle Kanten entstehen ausschließlich zwischen Chunks (Scope="chunk"), nie zwischen Notes direkt. Notes dienen nur noch als Metadatencontainer. - **Update v2.6 (Smart Chunking):** Ein Chunk ist nicht mehr nur ein dummer Textblock, der alle Links der Mutter-Notiz erbt. Durch die **Smart Edge Allocation (WP15)** "weiß" jeder Chunk genau, welche Kanten inhaltlich zu ihm gehören (siehe 2.4).
> **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt. > **Wichtig:** Chunking-Profile (short/medium/long/sliding_smart_edges) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt.
--- ---
@ -97,7 +100,7 @@ Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges`
Diese Kanten entstehen immer, unabhängig von Inhalten. Diese Kanten entstehen immer, unabhängig von Inhalten.
### 2.2 Inhalts-Kanten (explizit) ### 2.2 Inhalts-Kanten (explizit)
Hier unterscheidet v2.2 präzise zwischen verschiedenen Quellen der Evidenz: Hier unterscheidet v2.6 präzise zwischen verschiedenen Quellen der Evidenz:
1. **Explizite Inline-Relationen (Höchste Priorität):** 1. **Explizite Inline-Relationen (Höchste Priorität):**
Im Fließtext notierte, semantisch qualifizierte Relationen. Im Fließtext notierte, semantisch qualifizierte Relationen.
@ -131,7 +134,19 @@ Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche*
Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante. Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7). Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7).
### 2.4 Matrix-Logik (Kontextsensitive Kanten) – Neu in v2.4 ### 2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6
Mit **WP15** wurde ein intelligenter Filter eingeführt, um das Problem des "Broadcasting" zu lösen. Früher erbte jeder Chunk einer Notiz *alle* Links der Notiz, was zu unpräzisem Retrieval führte.
**Der neue Prozess:**
1. **Scan:** Das System sammelt alle expliziten Links der gesamten Notiz.
2. **Chunking:** Der Text wird in Abschnitte zerlegt.
3. **Analyse (LLM):** Ein lokales LLM (Semantic Analyzer) liest jeden Chunk einzeln.
4. **Entscheidung:** Das LLM entscheidet für jeden Link aus Schritt 1: *"Ist dieser Link im Kontext dieses spezifischen Textabschnitts relevant?"*
5. **Zuweisung:** Nur wenn das LLM zustimmt, wird die Kante am Chunk erstellt.
*Steuerung:* Dies ist pro Typ in der `types.yaml` konfigurierbar (`enable_smart_edge_allocation: true`).
### 2.5 Matrix-Logik (Kontextsensitive Kanten)
Mit WP-11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix"). Mit WP-11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").
**Beispiel für `Source Type: experience`:** **Beispiel für `Source Type: experience`:**
@ -154,7 +169,7 @@ Jede Kante hat mindestens:
Erweiterte/abgeleitete Felder (WP03 Superset): Erweiterte/abgeleitete Felder (WP03 Superset):
- `provenance` – `"explicit"` (Wikilink/Inline/Callout) oder `"rule"` (Typ-Defaults) - `provenance` – `"explicit"` (Wikilink/Inline/Callout), `"rule"` (Typ-Defaults) oder neu `"smart"` (vom LLM validiert).
- `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`) - `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`)
- `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring. - `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring.
@ -168,20 +183,24 @@ Erweiterte/abgeleitete Felder (WP03 Superset):
- Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ** - Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ**
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ** - Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
- Definiert **edge_defaults** je Typ (s. o.) - Definiert **edge_defaults** je Typ (s. o.)
- **Neu in v2.6:** Steuert `enable_smart_edge_allocation` (LLM-Filter) und `detection_keywords` für den Hybrid Router.
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei. Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei.
### 4.2 Beispiel (auslieferungsnah) ### 4.2 Beispiel (auslieferungsnah)
version: 1.0 version: 2.6.0
types: types:
concept: concept:
chunk_profile: medium chunk_profile: medium
edge_defaults: ["references", "related_to"] edge_defaults: ["references", "related_to"]
retriever_weight: 0.60 retriever_weight: 0.60
project: experience:
chunk_profile: long chunk_profile: sliding_smart_edges
edge_defaults: ["references", "depends_on"] enable_smart_edge_allocation: true # WP15: LLM prüft Kanten
retriever_weight: 0.97 detection_keywords: ["passiert", "erlebt", "situation"] # WP06: Router-Trigger
schema: # WP07: Interview-Struktur
- "Situation (Was ist passiert?)"
- "Meine Reaktion (Was habe ich getan?)"
**Auflösung im Importer** **Auflösung im Importer**
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None` - `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
@ -220,9 +239,12 @@ Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) ei
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück. Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
### 5.3 Graph-Expansion
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden.
--- ---
## 6) Context Intelligence & Intent Router (WP06–WP11) ## 6) Context Intelligence & Intent Router (WP06–WP15)
Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Partner. Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Partner.
@ -230,40 +252,51 @@ Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie
* **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval. * **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval.
* **Heute (WP06):** Das System erkennt, *was* der User will (Rat, Fakten oder Datenerfassung) und wechselt den Modus. * **Heute (WP06):** Das System erkennt, *was* der User will (Rat, Fakten oder Datenerfassung) und wechselt den Modus.
### 6.2 Der Intent-Router (Keyword & Semantik) ### 6.2 Der Hybrid Router v5 (Action vs. Question)
Der Router prüft vor jeder Antwort die Absicht über konfigurierbare Strategien (`config/decision_engine.yaml`): Der Router wurde in v2.6 (WP15) weiterentwickelt, um Fehlalarme zu vermeiden.
1. **FACT:** Reine Wissensfrage ("Was ist Qdrant?"). → Standard RAG. 1. **Frage-Erkennung:**
2. **DECISION:** Frage nach Rat oder Strategie ("Soll ich Qdrant nutzen?"). → Aktiviert die Decision Engine. * Das System prüft zuerst: Enthält der Satz ein `?` oder typische W-Wörter (Wer, Wie, Was)?
3. **EMPATHY:** Emotionale Zustände ("Ich bin gestresst"). → Aktiviert den empathischen Modus. * Wenn **JA** -> Gehe in den **RAG Modus** (Intent `FACT` oder `DECISION`). Interviews werden hier blockiert.
4. **INTERVIEW (WP07):** Wunsch, Wissen zu erfassen ("Neues Projekt anlegen"). → Aktiviert den Draft-Generator.
5. **CODING:** Technische Anfragen.
### 6.3 Strategic Retrieval (Injektion von Werten) 2. **Befehls-Erkennung (Fast Path):**
* Wenn **NEIN** (keine Frage), prüft das System auf Keywords in `types.yaml` ("Projekt", "Erfahrung").
* Treffer -> **INTERVIEW Modus** (Erfassen). Das Schema wird aus `types.yaml` geladen.
3. **LLM Fallback (Slow Path):**
* Wenn beides fehlschlägt, entscheidet das LLM über den Intent.
### 6.3 Traffic Control (Realtime vs. Background)
Um den Live-Betrieb (Chat) nicht durch den ressourcenintensiven Smart-Import (LLM-Analyse) zu gefährden, implementiert v2.6 ein **Traffic Control System** im `LLMService`.
* **Realtime Lane (Chat):** Anfragen aus dem Chat erhalten `priority="realtime"`. Sie umgehen alle Warteschlangen und werden sofort bearbeitet.
* **Background Lane (Import):** Anfragen zur Kantenanalyse erhalten `priority="background"`. Sie werden durch eine **Semaphore** gedrosselt (Standard: max 2 parallel), um die Hardware nicht zu überlasten.
### 6.4 Strategic Retrieval (Injektion von Werten)
Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie: Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie:
* **Values (`type: value`):** Moralische Werte (z.B. "Privacy First"). * **Values (`type: value`):** Moralische Werte (z.B. "Privacy First").
* **Principles (`type: principle`):** Handlungsanweisungen. * **Principles (`type: principle`):** Handlungsanweisungen.
* **Goals (`type: goal`):** Strategische Ziele. * **Goals (`type: goal`):** Strategische Ziele.
### 6.4 Reasoning (Das Gewissen) ### 6.5 Reasoning (Das Gewissen)
Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."* Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."*
Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z"). Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z").
### 6.5 Der Interview-Modus (One-Shot Extraction) ### 6.6 Der Interview-Modus (One-Shot Extraction)
Wenn der User Wissen erfassen will ("Ich möchte ein neues Projekt anlegen"), wechselt Mindnet in den **Interview-Modus**. Wenn der User Wissen erfassen will ("Ich möchte ein neues Projekt anlegen"), wechselt Mindnet in den **Interview-Modus**.
* **Late Binding Schema:** Das System lädt ein konfiguriertes Schema für den Ziel-Typ (z.B. `project`: Pflichtfelder sind Titel, Ziel, Status). * **Late Binding Schema:** Das System lädt ein konfiguriertes Schema für den Ziel-Typ (z.B. `project`: Pflichtfelder sind Titel, Ziel, Status).
* **One-Shot Extraction:** Statt eines langen Dialogs extrahiert das LLM **sofort** alle verfügbaren Infos aus dem Prompt und generiert einen validen Markdown-Draft mit Frontmatter. * **One-Shot Extraction:** Statt eines langen Dialogs extrahiert das LLM **sofort** alle verfügbaren Infos aus dem Prompt und generiert einen validen Markdown-Draft mit Frontmatter.
* **Draft-Status:** Fehlende Pflichtfelder werden mit `[TODO]` markiert. * **Healing Parser (v2.5):** Falls das LLM die YAML-Syntax beschädigt (z.B. fehlendes Ende), repariert das Frontend den Entwurf automatisch.
* **UI-Integration:** Das Frontend rendert statt einer Chat-Antwort einen **interaktiven Editor** (WP10), in dem der Entwurf finalisiert werden kann. * **UI-Integration:** Das Frontend rendert statt einer Chat-Antwort einen **interaktiven Editor** (WP10), in dem der Entwurf finalisiert werden kann.
### 6.6 Active Intelligence (Link Suggestions) – Neu in v2.4 ### 6.7 Active Intelligence (Link Suggestions)
Im **Draft Editor** (Frontend) unterstützt das System den Autor aktiv. Im **Draft Editor** (Frontend) unterstützt das System den Autor aktiv.
* **Analyse:** Ein "Sliding Window" scannt den Text im Hintergrund (auch lange Entwürfe). * **Analyse:** Ein "Sliding Window" scannt den Text im Hintergrund (auch lange Entwürfe).
* **Erkennung:** Es findet Begriffe ("Mindnet") und semantische Konzepte ("Autofahrt in Italien"). * **Erkennung:** Es findet Begriffe ("Mindnet") und semantische Konzepte ("Autofahrt in Italien").
* **Matching:** Es prüft gegen den Index (Aliases und Vektoren). * **Matching:** Es prüft gegen den Index (Aliases und Vektoren).
* **Vorschlag:** Es bietet fertige Markdown-Links an (z.B. `[[rel:related_to ...]]`), die per Klick eingefügt werden. * **Vorschlag:** Es bietet fertige Markdown-Links an (z.B. `[[rel:related_to ...]]`), die per Klick eingefügt werden.
* **Logik:** Dabei kommt die in 2.4 beschriebene **Matrix-Logik** zum Einsatz, um den korrekten Kanten-Typ vorzuschlagen. * **Logik:** Dabei kommt die in 2.5 beschriebene **Matrix-Logik** zum Einsatz, um den korrekten Kanten-Typ vorzuschlagen.
--- ---
@ -301,8 +334,9 @@ Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Ko
chunk_profile: short # Risiken sind oft kurze Statements chunk_profile: short # Risiken sind oft kurze Statements
retriever_weight: 0.90 # Hohe Priorität im Ranking retriever_weight: 0.90 # Hohe Priorität im Ranking
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
detection_keywords: ["gefahr", "risiko"] # Für den Hybrid Router
``` ```
*Effekt:* Der Retriever spült diese Notizen bei relevanten Anfragen nach oben. *Effekt:* Der Router erkennt das Wort "Risiko" und bietet ein Interview an. Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.
2. **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)** 2. **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)**
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird. Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird.
@ -359,12 +393,12 @@ Die Interaktion erfolgt primär über das **Web-Interface (WP10)**.
## 10) Confidence & Provenance – wozu? ## 10) Confidence & Provenance – wozu?
Der Retriever kann Edges gewichten: Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *rule* - **provenance**: *explicit* > *smart* (Neu) > *rule*
- **confidence**: numerische Feinsteuerung - **confidence**: numerische Feinsteuerung
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens - **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist: Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
`explicit: 1.0`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen. `explicit: 1.0`, `smart: 0.9`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen.
--- ---
@ -413,11 +447,11 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
> [!edge] related_to: [[Vector DB Basics]] > [!edge] related_to: [[Vector DB Basics]]
**Ergebnis (fachlich)** **Ergebnis (fachlich - Smart Edges)**
1. `depends_on(Chunk→Qdrant)` mit `rule_id=inline:rel`, `confidence≈0.95`. Das LLM analysiert jeden Chunk.
2. `references(Chunk→Embeddings 101)` mit `rule_id=explicit:wikilink`, `confidence=1.0`. 1. Chunk 1 ("Wir nutzen..."): Enthält `depends_on(Chunk→Qdrant)`. Das LLM bestätigt: Relevant. -> Kante wird erstellt.
3. `related_to(Chunk→Vector DB Basics)` via Callout; `rule_id=callout:edge`, `confidence≈0.90`. 2. Chunk 2 ("Siehe auch..."): Enthält `references(Chunk→Embeddings)`. Das LLM bestätigt.
4. **Typ-Defaults:** Falls die Note vom Typ `project` ist, entstehen zusätzlich `depends_on`-Kanten zu den Zielen aus (2) und (3). 3. **Wichtig:** Ein Chunk 3 ("Die Benutzeroberfläche ist blau..."), der keine Erwähnung von Qdrant hat, bekommt **keine** `depends_on` Kante zu Qdrant, auch wenn die Note global verlinkt ist. Das ist der Gewinn von WP15.
--- ---
@ -425,6 +459,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`. - Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`. - Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
- Smart Chunking & Traffic Control: `app/core/chunker.py` & `app/services/llm_service.py`.
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`. - Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
- Retriever-Scoring & Explanation: `app/core/retriever.py`. - Retriever-Scoring & Explanation: `app/core/retriever.py`.
- Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`. - Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`.
@ -435,7 +470,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 16) Workpackage Status (v2.4.0) ## 16) Workpackage Status (v2.6.0)
Aktueller Implementierungsstand der Module. Aktueller Implementierungsstand der Module.
@ -448,9 +483,12 @@ Aktueller Implementierungsstand der Module.
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. | | **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. | | **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. | | **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. | | **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** | | **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). | | **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | | **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** | | **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** |
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |

175
docs/mindnet_technical_architecture.md
View File

@ -1,7 +1,7 @@
# Mindnet v2.4 – Technische Architektur # Mindnet v2.4 – Technische Architektur
**Datei:** `docs/mindnet_technical_architecture_v2.4.md` **Datei:** `docs/mindnet_technical_architecture_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Integrierter Stand WP01–WP11: Async Intelligence) **Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control)
**Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`. **Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`.
> **Ziel dieses Dokuments:** > **Ziel dieses Dokuments:**
@ -15,7 +15,7 @@
- [](#) - [](#)
- [1. Systemüberblick](#1-systemüberblick) - [1. Systemüberblick](#1-systemüberblick)
- [1.1 Architektur-Zielbild](#11-architektur-zielbild) - [1.1 Architektur-Zielbild](#11-architektur-zielbild)
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP10)](#12-verzeichnisstruktur--komponenten-post-wp10) - [1.2 Verzeichnisstruktur \& Komponenten (Post-WP15)](#12-verzeichnisstruktur--komponenten-post-wp15)
- [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant) - [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant)
- [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes) - [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes)
- [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks) - [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks)
@ -27,22 +27,23 @@
- [3.4 Prompts (`config/prompts.yaml`)](#34-prompts-configpromptsyaml) - [3.4 Prompts (`config/prompts.yaml`)](#34-prompts-configpromptsyaml)
- [3.5 Environment (`.env`)](#35-environment-env) - [3.5 Environment (`.env`)](#35-environment-env)
- [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant) - [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant)
- [4.1 Verarbeitungsschritte (Async)](#41-verarbeitungsschritte-async) - [4.1 Verarbeitungsschritte (Async + Smart)](#41-verarbeitungsschritte-async--smart)
- [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring) - [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring)
- [5.1 Betriebsmodi](#51-betriebsmodi) - [5.1 Betriebsmodi](#51-betriebsmodi)
- [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a) - [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a)
- [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b) - [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b)
- [5.4 Graph-Expansion](#54-graph-expansion) - [5.4 Graph-Expansion](#54-graph-expansion)
- [6. RAG \& Chat Architektur (WP06 Hybrid Router + WP07 Interview)](#6-rag--chat-architektur-wp06-hybrid-router--wp07-interview) - [6. RAG \& Chat Architektur (WP06 Hybrid Router + WP07 Interview)](#6-rag--chat-architektur-wp06-hybrid-router--wp07-interview)
- [6.1 Architektur-Pattern: Intent Router](#61-architektur-pattern-intent-router) - [6.1 Architektur-Pattern: Intent Router v5](#61-architektur-pattern-intent-router-v5)
- [6.2 Schritt 1: Intent Detection (Hybrid)](#62-schritt-1-intent-detection-hybrid) - [6.2 Traffic Control (Priorisierung)](#62-traffic-control-priorisierung)
- [6.3 Schritt 2: Strategy Resolution (Late Binding)](#63-schritt-2-strategy-resolution-late-binding) - [6.3 Schritt 1: Intent Detection (Question vs. Action)](#63-schritt-1-intent-detection-question-vs-action)
- [6.4 Schritt 3: Retrieval vs. Extraction](#64-schritt-3-retrieval-vs-extraction) - [6.4 Schritt 2: Strategy Resolution](#64-schritt-2-strategy-resolution)
- [6.5 Schritt 4: Generation \& Response](#65-schritt-4-generation--response) - [6.5 Schritt 3: Retrieval vs. Extraction](#65-schritt-3-retrieval-vs-extraction)
- [6.6 Schritt 4: Generation \& Response](#66-schritt-4-generation--response)
- [7. Frontend Architektur (WP10)](#7-frontend-architektur-wp10) - [7. Frontend Architektur (WP10)](#7-frontend-architektur-wp10)
- [7.1 Kommunikation](#71-kommunikation) - [7.1 Kommunikation](#71-kommunikation)
- [7.2 Features \& UI-Logik](#72-features--ui-logik) - [7.2 Features \& UI-Logik](#72-features--ui-logik)
- [7.3 Draft-Editor \& Sanitizer (Neu in WP10a)](#73-draft-editor--sanitizer-neu-in-wp10a) - [7.3 Draft-Editor \& Healing Parser (Neu in WP10a/v2.5)](#73-draft-editor--healing-parser-neu-in-wp10av25)
- [7.4 State Management (Resurrection Pattern)](#74-state-management-resurrection-pattern) - [7.4 State Management (Resurrection Pattern)](#74-state-management-resurrection-pattern)
- [7.5 Deployment Ports](#75-deployment-ports) - [7.5 Deployment Ports](#75-deployment-ports)
- [8. Feedback \& Logging Architektur (WP04c)](#8-feedback--logging-architektur-wp04c) - [8. Feedback \& Logging Architektur (WP04c)](#8-feedback--logging-architektur-wp04c)
@ -62,57 +63,63 @@
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface. Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface.
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel). 1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**. 2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
* **Neu in v2.6:** Intelligente Kanten-Zuweisung durch lokale LLMs (Smart Edges).
3. **Storage:** 3. **Storage:**
* **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges). * **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges).
* **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel). * **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel).
4. **Backend:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit. 4. **Backend:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
* **Update v2.3.10:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)**, um Blockaden bei Embedding-Requests zu vermeiden. * **Update v2.6:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)** mit **Traffic Control** (Semaphore), um Blockaden bei parallelem Import und Chat zu vermeiden.
5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor** und **Intelligence-Features**. 5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor**, **Active Intelligence** und **Healing Parser**.
6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung. Embedding via `nomic-embed-text`. 6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung. Embedding via `nomic-embed-text`.
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`). Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`).
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP10) ### 1.2 Verzeichnisstruktur & Komponenten (Post-WP15)
/mindnet/ /mindnet/
├── app/ ├── app/
│ ├── main.py # FastAPI Einstiegspunkt │ ├── main.py # FastAPI Einstiegspunkt
│ ├── core/ │ ├── core/
│ │ ├── ingestion.py # NEU: Async Ingestion Service (WP11) │ │ ├── ingestion.py # NEU: Async Ingestion mit Change Detection
│ │ ├── qdrant.py # Client-Factory & Connection │ │ ├── qdrant.py # Client-Factory & Connection
│ │ ├── qdrant_points.py # Low-Level Point Operations (Upsert/Delete) │ │ ├── qdrant_points.py # Low-Level Point Operations (Upsert/Delete)
│ │ ├── note_payload.py # Bau der Note-Objekte │ │ ├── note_payload.py # Bau der Note-Objekte
│ │ ├── chunk_payload.py # Bau der Chunk-Objekte │ │ ├── chunk_payload.py # Bau der Chunk-Objekte
│ │ ├── chunker.py # Text-Zerlegung (Profiling) │ │ ├── chunker.py # Smart Chunker Orchestrator (WP15)
│ │ ├── edges.py # Edge-Datenstrukturen │ │ ├── edges.py # Edge-Datenstrukturen
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03) │ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
│ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b) │ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
│ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b) │ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
│ ├── models/ # Pydantic DTOs │ ├── models/ # Pydantic DTOs
│ │ └── dto.py # Zentrale DTO-Definition
│ ├── routers/ │ ├── routers/
│ │ ├── query.py # Such-Endpunkt │ │ ├── query.py # Such-Endpunkt
│ │ ├── ingest.py # NEU: API für Save & Analyze (WP11) │ │ ├── ingest.py # NEU: API für Save & Analyze (WP11)
│ │ ├── chat.py # Hybrid Router & Interview Logic (WP06/07) │ │ ├── chat.py # Hybrid Router v5 & Interview Logic (WP06/07)
│ │ ├── feedback.py # Feedback-Endpunkt (WP04c) │ │ ├── feedback.py # Feedback-Endpunkt (WP04c)
│ │ └── ... │ │ └── ...
│ ├── services/ │ ├── services/
│ │ ├── llm_service.py # Ollama Chat Client │ │ ├── llm_service.py # Ollama Chat Client mit Traffic Control
│ │ ├── embeddings_client.py# NEU: Async Embedding Client (HTTPX) │ │ ├── semantic_analyzer.py# NEU: LLM-Filter für Edges (WP15)
│ │ └── feedback_service.py # JSONL Logging (WP04c) │ │ ├── embeddings_client.py# NEU: Async Embeddings (HTTPX)
│ │ ├── feedback_service.py # Logging (JSONL Writer)
│ │ └── discovery.py # NEU: Intelligence Logic (WP11)
│ ├── frontend/ # NEU (WP10) │ ├── frontend/ # NEU (WP10)
│ └── ui.py # Streamlit Application inkl. Sanitizer │ │ └── ui.py # Streamlit Application inkl. Healing Parser
├── config/ │ └── main.py # Entrypoint der API
│ ├── types.yaml # Typ-Definitionen (Import-Zeit) ├── config/ # YAML-Konfigurationen (Single Source of Truth)
│ ├── retriever.yaml # Scoring-Gewichte (Laufzeit) │ ├── types.yaml # Import-Regeln & Smart-Edge Config
│ ├── decision_engine.yaml # Strategien & Schemas (WP06/WP07) │ ├── prompts.yaml # LLM Prompts & Interview Templates (WP06/07)
│ └── prompts.yaml # LLM System-Prompts & Templates (WP06) │ ├── decision_engine.yaml # Router-Strategien (Actions only)
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte
├── data/ ├── data/
│ └── logs/ # Lokale JSONL-Logs (WP04c) │ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
├── scripts/ ├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
│ ├── import_markdown.py # Haupt-Importer CLI (Async) │ ├── import_markdown.py # Haupt-Importer CLI (Async)
│ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB │ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB
│ └── edges_full_check.py # Diagnose: Graph-Integrität │ └── edges_full_check.py # Diagnose: Graph-Integrität
└── tests/ # Pytest Suite ├── tests/ # Pytest Suite & Smoke Scripts
└── vault/ # Dein lokaler Markdown-Content (Git-ignored)
--- ---
@ -171,6 +178,7 @@ Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
| `scope` | Keyword | Geltungsbereich. | Immer `"chunk"` (v2.2). | | `scope` | Keyword | Geltungsbereich. | Immer `"chunk"` (v2.2). |
| `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` | | `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` |
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 | | `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
| `provenance` | Keyword | Quelle der Kante. | `explicit`, `rule`, **`smart`** (Neu v2.6). |
--- ---
@ -181,6 +189,9 @@ Die Logik ist ausgelagert in YAML-Dateien.
### 3.1 Typ-Registry (`config/types.yaml`) ### 3.1 Typ-Registry (`config/types.yaml`)
Steuert den Import-Prozess. Steuert den Import-Prozess.
* **Priorität:** Frontmatter > Pfad > Default. * **Priorität:** Frontmatter > Pfad > Default.
* **Neu in v2.6:**
* `enable_smart_edge_allocation`: (Bool) Aktiviert den LLM-Filter für diesen Typ.
* `detection_keywords`: (List) Keywords für den Hybrid Router ("Objekterkennung").
* **Inhalt (Beispiel):** * **Inhalt (Beispiel):**
types: types:
@ -188,6 +199,10 @@ Steuert den Import-Prozess.
chunk_profile: medium chunk_profile: medium
edge_defaults: ["references", "related_to"] edge_defaults: ["references", "related_to"]
retriever_weight: 0.60 retriever_weight: 0.60
experience:
chunk_profile: sliding_smart_edges
enable_smart_edge_allocation: true
detection_keywords: ["erfahrung", "erlebt"]
### 3.2 Retriever-Config (`config/retriever.yaml`) ### 3.2 Retriever-Config (`config/retriever.yaml`)
Steuert das Scoring zur Laufzeit (WP04a). Steuert das Scoring zur Laufzeit (WP04a).
@ -199,14 +214,14 @@ Steuert das Scoring zur Laufzeit (WP04a).
centrality_weight: 0.5 centrality_weight: 0.5
### 3.3 Decision Engine (`config/decision_engine.yaml`) ### 3.3 Decision Engine (`config/decision_engine.yaml`)
**Neu in WP06/07:** Steuert den Intent-Router und die Interview-Schemas. **Neu in WP06/07:** Steuert den Intent-Router.
* Definiert Strategien (`DECISION`, `INTERVIEW`, etc.). * Definiert Strategien (`DECISION`, `INTERVIEW`, etc.).
* Definiert `schemas` für den Interview-Modus (Pflichtfelder pro Typ). * **Update v2.6:** Enthält nur noch **Handlungs-Keywords** (Verben wie "neu", "erstellen"). Objektnamen ("Projekt") werden nun über `types.yaml` aufgelöst.
* Definiert LLM-Router-Settings (`llm_fallback_enabled`). * Definiert LLM-Router-Settings (`llm_fallback_enabled`).
### 3.4 Prompts (`config/prompts.yaml`) ### 3.4 Prompts (`config/prompts.yaml`)
Steuert die LLM-Persönlichkeit und Templates. Steuert die LLM-Persönlichkeit und Templates.
* Enthält Templates für alle Strategien inkl. `interview_template` mit One-Shot Logik. * Enthält Templates für alle Strategien inkl. `interview_template` und neu `router_prompt`.
### 3.5 Environment (`.env`) ### 3.5 Environment (`.env`)
Erweiterung für LLM-Steuerung und Embedding-Modell: Erweiterung für LLM-Steuerung und Embedding-Modell:
@ -215,32 +230,36 @@ Erweiterung für LLM-Steuerung und Embedding-Modell:
MINDNET_EMBEDDING_MODEL=nomic-embed-text # NEU in v2.3.10 MINDNET_EMBEDDING_MODEL=nomic-embed-text # NEU in v2.3.10
MINDNET_OLLAMA_URL=http://127.0.0.1:11434 MINDNET_OLLAMA_URL=http://127.0.0.1:11434
MINDNET_LLM_TIMEOUT=300.0 # Neu: Erhöht für CPU-Inference Cold-Starts MINDNET_LLM_TIMEOUT=300.0 # Neu: Erhöht für CPU-Inference Cold-Starts
MINDNET_API_TIMEOUT=60.0 # Neu: Timeout für Frontend-API Calls MINDNET_API_TIMEOUT=300.0 # Neu: Timeout für Frontend-API (Smart Edges brauchen Zeit)
MINDNET_DECISION_CONFIG="config/decision_engine.yaml" MINDNET_DECISION_CONFIG="config/decision_engine.yaml"
MINDNET_VAULT_ROOT="./vault" # Neu: Pfad für Write-Back MINDNET_VAULT_ROOT="./vault" # Neu: Pfad für Write-Back
MINDNET_LLM_BACKGROUND_LIMIT=2 # Neu: Limit für parallele Import-Tasks
--- ---
## 4. Import-Pipeline (Markdown → Qdrant) ## 4. Import-Pipeline (Markdown → Qdrant)
Das Skript `scripts/import_markdown.py` orchestriert den Prozess. Das Skript `scripts/import_markdown.py` orchestriert den Prozess.
**Neu in v2.3.10:** Der Import nutzt `asyncio` und eine **Semaphore**, um Ollama nicht zu überlasten. **Neu in v2.6:** Der Import nutzt `asyncio` und **Traffic Control**, um Ollama nicht zu überlasten.
### 4.1 Verarbeitungsschritte (Async) ### 4.1 Verarbeitungsschritte (Async + Smart)
1. **Discovery & Parsing:** 1. **Discovery & Parsing:**
* Einlesen der `.md` Dateien. Hash-Vergleich (Body/Frontmatter) zur Erkennung von Änderungen. * Einlesen der `.md` Dateien. Hash-Vergleich (Body/Frontmatter) zur Erkennung von Änderungen.
2. **Typauflösung:** 2. **Typauflösung:**
* Bestimmung des `type` via `types.yaml`. * Bestimmung des `type` via `types.yaml`.
3. **Chunking:** 3. **Config Check:**
* Zerlegung via `chunker.py` basierend auf `chunk_profile`. * Prüft `enable_smart_edge_allocation` in der `types.yaml`.
4. **Embedding (Async):** 4. **Chunking & Smart Edges (WP15):**
* Der `EmbeddingsClient` (`app/services/embeddings_client.py`) sendet Text-Chunks asynchron an Ollama. * Zerlegung des Textes via `chunker.py`.
* Modell: `nomic-embed-text` (768d). * Wenn Smart Edges aktiv: Der `SemanticAnalyzer` sendet Chunks an das LLM.
* Semaphore: Max. 5 gleichzeitige Files, um OOM (Out-of-Memory) zu verhindern. * **Traffic Control:** Der Request nutzt `priority="background"`. Die Semaphore (default: 2) drosselt die Parallelität.
5. **Kantenableitung (Edge Derivation):** 5. **Kantenableitung (Edge Derivation):**
* `derive_edges.py` erzeugt Inline-, Callout- und Default-Edges. * `derive_edges.py` erzeugt Inline-, Callout- und Default-Edges.
6. **Upsert:** 6. **Embedding (Async):**
* Der `EmbeddingsClient` (`app/services/embeddings_client.py`) sendet Text-Chunks asynchron an Ollama.
* Modell: `nomic-embed-text` (768d).
7. **Upsert:**
* Schreiben in Qdrant. Nutzung von `--purge-before-upsert`. * Schreiben in Qdrant. Nutzung von `--purge-before-upsert`.
* **Strict Mode:** Der Prozess bricht ab, wenn Embeddings leer sind oder Dimension `0` haben. * **Strict Mode:** Der Prozess bricht ab, wenn Embeddings leer sind oder Dimension `0` haben.
@ -269,49 +288,55 @@ $$
* **Gewichte ($W$):** Stammen aus `retriever.yaml`. * **Gewichte ($W$):** Stammen aus `retriever.yaml`.
### 5.3 Explanation Layer (WP04b) ### 5.3 Explanation Layer (WP04b)
Der Retriever kann Ergebnisse erklären (`explain=True`). Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
* **Logik:**
* Berechnung des `ScoreBreakdown` (Anteile von Semantik, Graph, Typ). **Die "Warum"-Logik:**
* Analyse des lokalen Subgraphen mittels `graph_adapter.py`. 1. **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
* **Incoming Edges (Authority):** Wer zeigt auf diesen Treffer? (z.B. "Referenziert von...") 2. **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
* **Outgoing Edges (Hub):** Worauf zeigt dieser Treffer? (z.B. "Verweist auf...") 3. **Graph (Kontext):**
* **Output:** `QueryHit` enthält ein `explanation` Objekt mit menschenlesbaren `reasons` und `related_edges`. * **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
* **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
### 5.4 Graph-Expansion ### 5.4 Graph-Expansion
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden. Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden.
--- ---
## 6. RAG \& Chat Architektur (WP06 Hybrid Router + WP07 Interview) ## 6. RAG & Chat Architektur (WP06 Hybrid Router + WP07 Interview)
Der Flow für eine Chat-Anfrage (`/chat`) wurde in WP06 auf eine **Configuration-Driven Architecture** umgestellt. Der `ChatRouter` (`app/routers/chat.py`) fungiert als zentraler Dispatcher. Der Flow für eine Chat-Anfrage (`/chat`) wurde in WP06 auf eine **Configuration-Driven Architecture** umgestellt und in WP15 (v2.6) verfeinert.
### 6.1 Architektur-Pattern: Intent Router ### 6.1 Architektur-Pattern: Intent Router v5
Die Behandlung einer Anfrage ist nicht mehr hartkodiert, sondern wird dynamisch zur Laufzeit entschieden. Die Behandlung einer Anfrage ist nicht mehr hartkodiert, sondern wird dynamisch zur Laufzeit entschieden.
* **Input:** User Message. * **Input:** User Message.
* **Config:** `config/decision_engine.yaml` (Strategien & Keywords). * **Config:** `decision_engine.yaml` (Strategien) + `types.yaml` (Objekte).
* **Komponenten:** * **Komponenten:**
* **Fast Path:** Keyword Matching (CPU-schonend). * **Traffic Control:** `LLMService` priorisiert Chat-Anfragen.
* **Slow Path:** LLM-basierter Semantic Router (für subtile Intents). * **Question Detection:** Unterscheidung Frage vs. Befehl.
### 6.2 Schritt 1: Intent Detection (Hybrid) ### 6.2 Traffic Control (Priorisierung)
Um den Chat-Betrieb auch bei laufendem Import stabil zu halten, implementiert der `LLMService` Prioritäts-Warteschlangen:
* **Priority "realtime" (Chat):** Anfragen gehen sofort an Ollama. Keine Semaphore.
* **Priority "background" (Import):** Anfragen warten in einer Semaphore (Limit konfiguriert via `MINDNET_LLM_BACKGROUND_LIMIT`).
### 6.3 Schritt 1: Intent Detection (Question vs. Action)
Der Router ermittelt die Absicht (`Intent`) des Nutzers. Der Router ermittelt die Absicht (`Intent`) des Nutzers.
1. **Keyword Scan (Fast Path):** 1. **Frage-Check:** Wenn der Input ein `?` enthält oder mit W-Wörtern beginnt, wird der **RAG-Modus** erzwungen (oder LLM-Entscheidung). Interviews werden hier unterdrückt.
* Iteration über alle Strategien in `decision_engine.yaml`. 2. **Keyword Scan (Fast Path):**
* Prüfung auf `trigger_keywords`. * Prüfung auf `trigger_keywords` (Handlung) in `decision_engine.yaml`.
* **Best Match:** Bei mehreren Treffern gewinnt das längste/spezifischste Keyword (Robustheit gegen Shadowing). * Prüfung auf `detection_keywords` (Objekt) in `types.yaml`.
2. **LLM Fallback (Slow Path):** * Treffer -> **INTERVIEW Modus** (Erfassen).
* Nur aktiv, wenn `llm_fallback_enabled: true`. 3. **LLM Fallback (Slow Path):**
* Greift, wenn keine Keywords gefunden wurden. * Greift, wenn keine Keywords passen. Sendet Query an LLM Router.
* Sendet die Query an das LLM mit einem Klassifizierungs-Prompt (`llm_router_prompt`).
* Ergebnis: `EMPATHY`, `DECISION`, `INTERVIEW`, `CODING` oder `FACT`.
### 6.3 Schritt 2: Strategy Resolution (Late Binding) ### 6.4 Schritt 2: Strategy Resolution
Basierend auf dem Intent lädt der Router die Parameter: Basierend auf dem Intent lädt der Router die Parameter:
* **Bei RAG (FACT/DECISION):** `inject_types` für Strategic Retrieval. * **Bei RAG (FACT/DECISION):** `inject_types` für Strategic Retrieval.
* **Bei INTERVIEW (WP07):** `schemas` (Pflichtfelder) basierend auf der erkannten Ziel-Entität (`_detect_target_type`). * **Bei INTERVIEW (WP07):** `schemas` (Pflichtfelder) basierend auf der erkannten Ziel-Entität (`_detect_target_type`).
### 6.4 Schritt 3: Retrieval vs. Extraction ### 6.5 Schritt 3: Retrieval vs. Extraction
Der Router verzweigt hier: Der Router verzweigt hier:
**A) RAG Modus (FACT, DECISION, EMPATHY):** **A) RAG Modus (FACT, DECISION, EMPATHY):**
@ -324,9 +349,9 @@ Der Router verzweigt hier:
2. **Schema Injection:** Das Schema für den erkannten Typ (z.B. "Project") wird geladen. 2. **Schema Injection:** Das Schema für den erkannten Typ (z.B. "Project") wird geladen.
3. **Prompt Assembly:** Der `interview_template` Prompt wird mit der Schema-Definition ("Ziel", "Status") gefüllt. 3. **Prompt Assembly:** Der `interview_template` Prompt wird mit der Schema-Definition ("Ziel", "Status") gefüllt.
### 6.5 Schritt 4: Generation & Response ### 6.6 Schritt 4: Generation & Response
* **Templating:** Das LLM erhält den Prompt basierend auf dem gewählten Template. * **Templating:** Das LLM erhält den Prompt basierend auf dem gewählten Template.
* **Execution:** Der `LLMService` führt den Call aus. Ein konfigurierbarer Timeout (`MINDNET_LLM_TIMEOUT`) fängt Cold-Start-Verzögerungen auf CPU-Hardware ab. * **Execution:** Der `LLMService` führt den Call mit `priority="realtime"` aus.
* **Response:** Rückgabe enthält Antworttext (im Interview-Modus: Markdown Codeblock), Quellenliste und den erkannten `intent`. * **Response:** Rückgabe enthält Antworttext (im Interview-Modus: Markdown Codeblock), Quellenliste und den erkannten `intent`.
--- ---
@ -338,7 +363,7 @@ Das Frontend ist eine **Streamlit-Anwendung** (`app/frontend/ui.py`), die als se
### 7.1 Kommunikation ### 7.1 Kommunikation
* **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`). * **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`).
* **Endpoints:** Nutzt `/chat` für Interaktion, `/feedback` für Bewertungen und `/ingest/analyze` für Intelligence. * **Endpoints:** Nutzt `/chat` für Interaktion, `/feedback` für Bewertungen und `/ingest/analyze` für Intelligence.
* **Resilienz:** Das Frontend implementiert eigene Timeouts (`MINDNET_API_TIMEOUT`, Default 300s). * **Resilienz:** Das Frontend nutzt `MINDNET_API_TIMEOUT` (Default 300s), um auch bei langsamen Smart-Edge-Berechnungen im Backend nicht abzubrechen.
### 7.2 Features & UI-Logik ### 7.2 Features & UI-Logik
* **State Management:** Session-State speichert Chat-Verlauf und `query_id`. * **State Management:** Session-State speichert Chat-Verlauf und `query_id`.
@ -347,16 +372,16 @@ Das Frontend ist eine **Streamlit-Anwendung** (`app/frontend/ui.py`), die als se
* **Source Expanders:** Zeigt verwendete Chunks inkl. Score und "Why"-Explanation. * **Source Expanders:** Zeigt verwendete Chunks inkl. Score und "Why"-Explanation.
* **Sidebar:** Zeigt Suchhistorie (Log-basiert) und Konfiguration. * **Sidebar:** Zeigt Suchhistorie (Log-basiert) und Konfiguration.
### 7.3 Draft-Editor & Sanitizer (Neu in WP10a) ### 7.3 Draft-Editor & Healing Parser (Neu in WP10a/v2.5)
Wenn der Intent `INTERVIEW` ist, rendert die UI statt einer Textblase den **Draft-Editor**. Wenn der Intent `INTERVIEW` ist, rendert die UI statt einer Textblase den **Draft-Editor**.
1. **Parsing:** Die Funktion `parse_markdown_draft` extrahiert den Codeblock aus der LLM-Antwort. 1. **Parsing:** Die Funktion `parse_markdown_draft` extrahiert den Codeblock aus der LLM-Antwort.
* **Healing:** Erkennt und repariert defekte YAML-Frontmatter (z.B. fehlendes schließendes `---`), falls das LLM unter Last Fehler macht.
2. **Sanitization (`normalize_meta_and_body`):** 2. **Sanitization (`normalize_meta_and_body`):**
* Prüft den YAML-Frontmatter auf unerlaubte Felder (Halluzinationen des LLMs). * Prüft den YAML-Frontmatter auf unerlaubte Felder (Halluzinationen des LLMs).
* Verschiebt ungültige Felder (z.B. "Situation") in den Body der Notiz. * Verschiebt ungültige Felder (z.B. "Situation") in den Body der Notiz.
* Stellt sicher, dass das Markdown valide bleibt.
3. **Editor Widget:** `st.text_area` erlaubt das Bearbeiten des Inhalts vor dem Speichern. 3. **Editor Widget:** `st.text_area` erlaubt das Bearbeiten des Inhalts vor dem Speichern.
4. **Action:** Buttons zum Download oder Kopieren des fertigen Markdowns. 4. **Save Action:** Speichert über `/ingest/save` atomar in Vault und DB. Erzeugt intelligente Dateinamen via `slugify`.
### 7.4 State Management (Resurrection Pattern) ### 7.4 State Management (Resurrection Pattern)
Um Datenverlust bei Tab-Wechseln (Chat <-> Editor) zu verhindern, nutzt `ui.py` ein Persistenz-Muster: Um Datenverlust bei Tab-Wechseln (Chat <-> Editor) zu verhindern, nutzt `ui.py` ein Persistenz-Muster:
@ -420,5 +445,5 @@ Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
2. **Unresolved Targets:** 2. **Unresolved Targets:**
* Kanten zu Notizen, die noch nicht existieren, werden mit `target_id="Titel"` angelegt. * Kanten zu Notizen, die noch nicht existieren, werden mit `target_id="Titel"` angelegt.
* Heilung durch `scripts/resolve_unresolved_references.py` möglich. * Heilung durch `scripts/resolve_unresolved_references.py` möglich.
3. **Vektor-Konfiguration für Edges:** 3. **Hardware-Last bei Smart Import:**
* `mindnet_edges` hat aktuell keine Vektoren (`vectors = null`). Eine semantische Suche *auf Kanten* ist noch nicht möglich. * Der "Smart Edge" Import ist rechenintensiv. Trotz Traffic Control kann die Antwortzeit im Chat leicht steigen, wenn die GPU am VRAM-Limit arbeitet.

86
docs/pipeline_playbook.md
View File

@ -1,7 +1,7 @@
# mindnet v2.4 – Pipeline Playbook # mindnet v2.4 – Pipeline Playbook
**Datei:** `docs/mindnet_pipeline_playbook_v2.4.md` **Datei:** `docs/mindnet_pipeline_playbook_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Inkl. Async Ingestion & Active Intelligence) **Status:** **FINAL** (Inkl. Smart Edges & Traffic Control)
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.4.md`. **Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.4.md`.
--- ---
@ -12,7 +12,7 @@
- [](#) - [](#)
- [1. Zweck \& Einordnung](#1-zweck--einordnung) - [1. Zweck \& Einordnung](#1-zweck--einordnung)
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook) - [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
- [2.1 Der 12-Schritte-Prozess (Async)](#21-der-12-schritte-prozess-async) - [2.1 Der 13-Schritte-Prozess (Async + Smart)](#21-der-13-schritte-prozess-async--smart)
- [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell) - [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell)
- [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd) - [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate) - [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
@ -21,12 +21,13 @@
- [3.2 Payload-Felder](#32-payload-felder) - [3.2 Payload-Felder](#32-payload-felder)
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik) - [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance) - [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
- [4.2 Typ-Defaults](#42-typ-defaults) - [4.2 Smart Edge Allocation (WP15)](#42-smart-edge-allocation-wp15)
- [4.3 Typ-Defaults](#43-typ-defaults)
- [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline) - [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline)
- [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid) - [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
- [5.2 Intent Router (WP06/07)](#52-intent-router-wp0607) - [5.2 Intent Router (WP06/07)](#52-intent-router-wp0607)
- [5.3 Context Enrichment](#53-context-enrichment) - [5.3 Context Enrichment](#53-context-enrichment)
- [5.4 Generation (LLM)](#54-generation-llm) - [5.4 Generation (LLM) mit Traffic Control](#54-generation-llm-mit-traffic-control)
- [5.5 Active Intelligence Pipeline (Neu in v2.4)](#55-active-intelligence-pipeline-neu-in-v24) - [5.5 Active Intelligence Pipeline (Neu in v2.4)](#55-active-intelligence-pipeline-neu-in-v24)
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c) - [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
- [7. Quality Gates \& Tests](#7-quality-gates--tests) - [7. Quality Gates \& Tests](#7-quality-gates--tests)
@ -34,7 +35,7 @@
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e) - [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen) - [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
- [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze) - [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze)
- [16. Workpackage Status (v2.4.0)](#16-workpackage-status-v240) - [16. Workpackage Status (v2.6.0)](#16-workpackage-status-v260)
</details> </details>
--- ---
@ -45,7 +46,7 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline*
**Zielgruppe:** Dev/Ops, Tech-Leads. **Zielgruppe:** Dev/Ops, Tech-Leads.
**Scope:** **Scope:**
* **Ist-Stand (WP01–WP11):** Async Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor, Active Intelligence. * **Ist-Stand (WP01–WP15):** Async Import, Smart Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor, Active Intelligence.
* **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08). * **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08).
--- ---
@ -54,23 +55,27 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline*
Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss **deterministisch** und **idempotent** sein. Wir nutzen `scripts/import_markdown.py` als zentralen Entrypoint. Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss **deterministisch** und **idempotent** sein. Wir nutzen `scripts/import_markdown.py` als zentralen Entrypoint.
### 2.1 Der 12-Schritte-Prozess (Async) ### 2.1 Der 13-Schritte-Prozess (Async + Smart)
Seit v2.3.10 läuft der Import **asynchron**, um Netzwerk-Blockaden bei der Embedding-Generierung zu vermeiden. Seit v2.6 läuft der Import vollständig asynchron, nutzt intelligente Kantenvalidierung (Smart Edges) und drosselt sich selbst ("Traffic Control").
1. **Markdown lesen:** Rekursives Scannen des Vaults. 1. **Markdown lesen:** Rekursives Scannen des Vaults.
2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`). 2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
3. **Typauflösung:** Bestimmung des `type` via `types.yaml` (Prio: Frontmatter > Pfad > Default). 3. **Typauflösung:** Bestimmung des `type` via `types.yaml` (Prio: Frontmatter > Pfad > Default).
4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`. 4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`.
5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs. 5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs (z.B. `sliding_smart_edges`).
6. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext. 6. **Smart Edge Allocation (Neu in WP15):**
7. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken. * Prüfung: Ist für den Typ `enable_smart_edge_allocation: true` konfiguriert?
8. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry. * Falls Ja: Der `SemanticAnalyzer` sendet jeden Chunk an das LLM (Ollama).
9. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz). * **Traffic Control:** Der Request nutzt `priority="background"`. Die globale Semaphore (Limit: 2, konfigurierbar) verhindert Überlastung des Systems.
10. **Embedding & Upsert (Async):** * Ergebnis: Das LLM filtert irrelevante Links aus dem Chunk ("Broadcasting" verhindern).
* Das System nutzt eine **Semaphore** (Limit: 5 Files concurrent), um Ollama nicht zu überlasten. 7. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext.
8. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken.
9. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry.
10. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz).
11. **Embedding & Upsert (Async):**
* Generierung der Vektoren via `nomic-embed-text` (768 Dim). * Generierung der Vektoren via `nomic-embed-text` (768 Dim).
11. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat. 12. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat.
12. **Diagnose:** Automatischer Check der Integrität nach dem Lauf. 13. **Diagnose:** Automatischer Check der Integrität nach dem Lauf.
### 2.2 Standard-Betrieb (Inkrementell) ### 2.2 Standard-Betrieb (Inkrementell)
Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash. Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
@ -102,7 +107,7 @@ Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden
sudo systemctl status mindnet-prod sudo systemctl status mindnet-prod
### 2.4 Full Rebuild (Clean Slate) ### 2.4 Full Rebuild (Clean Slate)
Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunk-Größen) oder beim Wechsel des Embedding-Modells (z.B. Update auf `nomic-embed-text`). Notwendig bei Änderungen an `types.yaml` (z.B. Smart Edges an/aus) oder beim Wechsel des Embedding-Modells.
**WICHTIG:** Vorher das Modell pullen, sonst schlägt der Import fehl! **WICHTIG:** Vorher das Modell pullen, sonst schlägt der Import fehl!
@ -127,6 +132,7 @@ In `types.yaml` definiert. Standard-Profile (in `chunk_config.py` implementiert)
* `medium`: Max 256 Tokens (z.B. für Konzepte). * `medium`: Max 256 Tokens (z.B. für Konzepte).
* `long`: Max 512 Tokens (z.B. für Essays, Projekte). * `long`: Max 512 Tokens (z.B. für Essays, Projekte).
* `by_heading`: Trennt strikt an Überschriften. * `by_heading`: Trennt strikt an Überschriften.
* `sliding_smart_edges`: Sliding Window, das speziell für die nachgelagerte LLM-Analyse optimiert ist.
### 3.2 Payload-Felder ### 3.2 Payload-Felder
Jeder Chunk erhält zwei Text-Felder: Jeder Chunk erhält zwei Text-Felder:
@ -137,7 +143,7 @@ Jeder Chunk erhält zwei Text-Felder:
## 4. Edge-Erzeugung (Die V2-Logik) ## 4. Edge-Erzeugung (Die V2-Logik)
In v2.2 entstehen Kanten nach strenger Priorität. In v2.6 entstehen Kanten nach strenger Priorität.
### 4.1 Prioritäten & Provenance ### 4.1 Prioritäten & Provenance
Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch: Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch:
@ -147,10 +153,17 @@ Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch:
| **1** | Inline | `[[rel:depends_on X]]` | `inline:rel` | ~0.95 | | **1** | Inline | `[[rel:depends_on X]]` | `inline:rel` | ~0.95 |
| **2** | Callout | `> [!edge] related_to: [[X]]` | `callout:edge` | ~0.90 | | **2** | Callout | `> [!edge] related_to: [[X]]` | `callout:edge` | ~0.90 |
| **3** | Wikilink | `[[X]]` | `explicit:wikilink` | 1.00 | | **3** | Wikilink | `[[X]]` | `explicit:wikilink` | 1.00 |
| **4** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 | | **4** | Smart | *(via LLM Filter)* | `smart:llm_filter` | 0.90 |
| **5** | Struktur | *(automatisch)* | `structure:...` | 1.00 | | **5** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 |
| **6** | Struktur | *(automatisch)* | `structure:...` | 1.00 |
### 4.2 Typ-Defaults ### 4.2 Smart Edge Allocation (WP15)
Dieser Mechanismus löst das Problem, dass Chunks sonst alle Links der Note erben.
* **Prozess:** Der `SemanticAnalyzer` prüft jeden Chunk: "Ist Link X im Kontext von Chunk Y relevant?"
* **Ergebnis:** Kanten werden präzise an den Chunk gebunden, nicht global an die Note.
* **Steuerung:** Das Feature wird in `types.yaml` per Typ aktiviert (`enable_smart_edge_allocation: true`).
### 4.3 Typ-Defaults
Wenn in `types.yaml` für einen Typ `edge_defaults` definiert sind, werden diese **additiv** zu expliziten Links erzeugt. Wenn in `types.yaml` für einen Typ `edge_defaults` definiert sind, werden diese **additiv** zu expliziten Links erzeugt.
* *Beispiel:* Note Typ `project` verlinkt `[[Tool A]]`. * *Beispiel:* Note Typ `project` verlinkt `[[Tool A]]`.
* *Ergebnis:* Kante `references` (explizit) UND Kante `depends_on` (Default). * *Ergebnis:* Kante `references` (explizit) UND Kante `depends_on` (Default).
@ -165,25 +178,23 @@ Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.
Der `/chat` Endpunkt nutzt **Hybrid Retrieval** (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt). Der `/chat` Endpunkt nutzt **Hybrid Retrieval** (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt).
### 5.2 Intent Router (WP06/07) ### 5.2 Intent Router (WP06/07)
Der Request durchläuft den **Hybrid Router**: Der Request durchläuft den **Hybrid Router v5**:
1. **Fast Path:** Prüfung auf `trigger_keywords` aus `decision_engine.yaml`. 1. **Question Detection:** Ist es eine Frage (`?`, W-Wörter)? -> RAG Modus. Interviews werden hier blockiert.
2. **Slow Path:** Falls kein Keyword matched und `llm_fallback_enabled=true`, klassifiziert das LLM den Intent. 2. **Keyword Scan:** Enthält es Keywords aus `types.yaml` (Objekt, z.B. "Projekt") oder `decision_engine.yaml` (Action, z.B. "erstellen")? -> INTERVIEW Modus.
* `FACT`: Wissen abfragen. 3. **LLM Fallback:** Wenn unklar, entscheidet das LLM.
* `DECISION`: Rat suchen.
* `EMPATHY`: Trost suchen.
* `INTERVIEW`: Wissen eingeben (Neu in WP07).
3. **Result:** Auswahl der Strategie und der `inject_types` oder `schemas`.
### 5.3 Context Enrichment ### 5.3 Context Enrichment
Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an: Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an:
* **Typ-Injection:** `[DECISION]`, `[PROJECT]`. * **Typ-Injection:** `[DECISION]`, `[PROJECT]`.
* **Reasoning-Infos:** `(Score: 0.75)`. * **Reasoning-Infos:** `(Score: 0.75)`.
### 5.4 Generation (LLM) ### 5.4 Generation (LLM) mit Traffic Control
* **Engine:** Ollama (lokal). * **Engine:** Ollama (lokal).
* **Modell:** `phi3:mini` (Standard). * **Modell:** `phi3:mini` (Standard).
* **Prompting:** Template wird basierend auf Intent gewählt (`decision_template`, `interview_template` etc.). * **Prompting:** Template wird basierend auf Intent gewählt (`decision_template`, `interview_template` etc.).
* **One-Shot (WP07):** Im Interview-Modus generiert das LLM direkt einen Markdown-Block ohne Rückfragen. * **Traffic Control:** Der `LLMService` unterscheidet:
* **Chat-Requests** (`priority="realtime"`) -> Sofortige Ausführung.
* **Import-Requests** (`priority="background"`) -> Gedrosselt durch Semaphore (Standard: 2).
### 5.5 Active Intelligence Pipeline (Neu in v2.4) ### 5.5 Active Intelligence Pipeline (Neu in v2.4)
Ein paralleler Datenfluss im Frontend ("Draft Editor") zur Unterstützung des Autors. Ein paralleler Datenfluss im Frontend ("Draft Editor") zur Unterstützung des Autors.
@ -252,7 +263,7 @@ Wie entwickeln wir die Pipeline weiter?
--- ---
## 16. Workpackage Status (v2.4.0) ## 16. Workpackage Status (v2.6.0)
Aktueller Implementierungsstand der Module. Aktueller Implementierungsstand der Module.
@ -269,5 +280,8 @@ Aktueller Implementierungsstand der Module.
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** | | **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). | | **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | | **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** | | **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** |
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |

38
docs/user_guide.md
View File

@ -1,7 +1,7 @@
# Mindnet v2.4 – User Guide # Mindnet v2.4 – User Guide
**Datei:** `docs/mindnet_user_guide_v2.4.md` **Datei:** `docs/mindnet_user_guide_v2.6.md`
**Stand:** 2025-12-11 **Stand:** 2025-12-12
**Status:** **FINAL** (Inkl. RAG, Web-Interface & Interview-Assistent & Intelligence) **Status:** **FINAL** (Inkl. Smart Edges, Hybrid Router v5 & Healing UI)
**Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`. **Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`.
> **Willkommen bei Mindnet.** > **Willkommen bei Mindnet.**
@ -18,6 +18,7 @@ Wenn du nach "Projekt Alpha" suchst, findet Mindnet nicht nur das Dokument. Es f
* **Abhängigkeiten:** "Technologie X wird benötigt". * **Abhängigkeiten:** "Technologie X wird benötigt".
* **Entscheidungen:** "Warum nutzen wir X?". * **Entscheidungen:** "Warum nutzen wir X?".
* **Ähnliches:** "Projekt Beta war ähnlich". * **Ähnliches:** "Projekt Beta war ähnlich".
* **Neu in v2.6 (Smart Edges):** Mindnet zeigt dir präzise Verknüpfungen an, die für den spezifischen Textabschnitt relevant sind, statt pauschal alle Links der Notiz anzuzeigen.
### 1.2 Der Zwilling (Die Personas) ### 1.2 Der Zwilling (Die Personas)
Mindnet passt seinen Charakter dynamisch an deine Frage an: Mindnet passt seinen Charakter dynamisch an deine Frage an:
@ -52,28 +53,22 @@ Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Brows
## 3. Den Chat steuern (Intents) ## 3. Den Chat steuern (Intents)
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Das System nutzt einen **Hybrid Router**, der sowohl auf Schlüsselwörter als auch auf die Bedeutung achtet. Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Das System nutzt einen **Hybrid Router v5**, der intelligent zwischen Frage und Befehl unterscheidet.
### 3.1 Modus: Entscheidung ("Der Berater") ### 3.1 Frage-Modus (Wissen abrufen)
Wenn du vor einer Wahl stehst, hilft Mindnet dir, konform zu deinen Prinzipien zu bleiben. Sobald du ein Fragezeichen `?` benutzt oder Wörter wie "Wer", "Wie", "Was", "Soll ich" verwendest, sucht Mindnet nach Antworten (**RAG**).
* **Auslöser (Keywords):** "Soll ich...", "Was ist deine Meinung?", "Strategie für...", "Vor- und Nachteile". * **Entscheidung ("Soll ich?"):** Mindnet lädt deine **Werte** (`type: value`) und **Ziele** (`type: goal`) in den Kontext und prüft die Fakten dagegen.
* **Was passiert:** Mindnet lädt deine **Werte** (`type: value`) und **Ziele** (`type: goal`) in den Kontext und prüft die Fakten dagegen. * *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First' und dein Ziel 'Digitale Autarkie'."
* **Beispiel-Dialog:** * **Empathie ("Ich fühle..."):** Mindnet lädt deine **Erfahrungen** (`type: experience`) und **Glaubenssätze** (`type: belief`). Es antwortet verständnisvoll und zitiert deine eigenen Lektionen.
* *Du:* "Soll ich Tool X nutzen?" * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
* *Mindnet:* "Nein. Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First' und dein Ziel 'Digitale Autarkie'."
### 3.2 Modus: Empathie ("Der Spiegel") ### 3.2 Befehls-Modus (Wissen erfassen / Interview)
Wenn du frustriert bist oder reflektieren willst, wechselt Mindnet in den "Ich"-Modus. Wenn du keine Frage stellst, sondern eine Absicht äußerst, wechselt Mindnet in den **Interview-Modus**.
* **Auslöser (Keywords & Semantik):** "Ich fühle mich...", "Traurig", "Gestresst", "Alles ist sinnlos", "Ich bin überfordert".
* **Was passiert:** Mindnet lädt deine **Erfahrungen** (`type: experience`) und **Glaubenssätze** (`type: belief`). Es antwortet verständnisvoll und zitiert deine eigenen Lektionen.
### 3.3 Modus: Interview ("Der Analyst")
Wenn du Wissen festhalten willst, statt zu suchen.
* **Auslöser:** "Neues Projekt", "Notiz erstellen", "Ich will etwas festhalten", "Neue Entscheidung dokumentieren". * **Auslöser:** "Neues Projekt", "Notiz erstellen", "Ich will etwas festhalten", "Neue Entscheidung dokumentieren".
* **Was passiert:** Siehe Kapitel 6.3. * **Was passiert:** Mindnet sucht nicht im Archiv, sondern öffnet den **Draft-Editor**.
* **Beispiel:** "Neue Erfahrung: Streit am Recyclinghof." -> Das System erstellt sofort eine strukturierte Notiz mit den Feldern "Situation", "Reaktion" und "Learning".
--- ---
@ -127,9 +122,10 @@ Mindnet kann dir helfen, Markdown-Notizen zu schreiben.
2. **Generierung:** Mindnet erkennt den Wunsch (`INTERVIEW`), analysiert den Satz und erstellt **sofort** einen Entwurf. 2. **Generierung:** Mindnet erkennt den Wunsch (`INTERVIEW`), analysiert den Satz und erstellt **sofort** einen Entwurf.
3. **Editor:** Die UI wechselt von der Chat-Blase zu einem **Draft-Editor**. 3. **Editor:** Die UI wechselt von der Chat-Blase zu einem **Draft-Editor**.
* Du siehst das generierte Frontmatter (`type: project`, `status: draft`). * Du siehst das generierte Frontmatter (`type: project`, `status: draft`).
* **Healing UI (v2.5):** Falls das LLM Syntax-Fehler gemacht hat (z.B. fehlendes `---`), hat der Editor das bereits automatisch repariert.
* Du siehst den Body-Text mit Platzhaltern (`[TODO]`), wo Infos fehlten (z.B. Stakeholder). * Du siehst den Body-Text mit Platzhaltern (`[TODO]`), wo Infos fehlten (z.B. Stakeholder).
4. **Finalisierung:** Ergänze die fehlenden Infos direkt im Editor und klicke auf **Download** oder **Kopieren**. 4. **Finalisierung:** Ergänze die fehlenden Infos direkt im Editor und klicke auf **Download** oder **Kopieren**.
5. **Speichern:** Speichere die Datei in deinen Obsidian Vault. Beim nächsten Import ist sie im System. 5. **Speichern:** Klicke auf "💾 Speichern". Die Notiz landet sofort im Vault und im Index.
### 6.4 Der Intelligence-Workflow (Neu in v2.4) ### 6.4 Der Intelligence-Workflow (Neu in v2.4)
Wenn du Texte im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei der Vernetzung: Wenn du Texte im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei der Vernetzung: