291 lines
14 KiB
Markdown
291 lines
14 KiB
Markdown
# mindnet v2.4 – Pipeline Playbook
|
||
**Datei:** `docs/mindnet_pipeline_playbook_v2.6.md`
|
||
**Stand:** 2025-12-12
|
||
**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`.
|
||
|
||
---
|
||
<details>
|
||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||
|
||
- [mindnet v2.4 – Pipeline Playbook](#mindnet-v24--pipeline-playbook)
|
||
- [](#)
|
||
- [1. Zweck \& Einordnung](#1-zweck--einordnung)
|
||
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
|
||
- [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.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
|
||
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
|
||
- [3. Chunking \& Payload-Aufbau](#3-chunking--payload-aufbau)
|
||
- [3.1 Chunk-Profile](#31-chunk-profile)
|
||
- [3.2 Payload-Felder](#32-payload-felder)
|
||
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
|
||
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
|
||
- [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.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
|
||
- [5.2 Intent Router (WP06/07)](#52-intent-router-wp0607)
|
||
- [5.3 Context Enrichment](#53-context-enrichment)
|
||
- [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)
|
||
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
|
||
- [7. Quality Gates \& Tests](#7-quality-gates--tests)
|
||
- [7.1 Pflicht-Tests vor Commit](#71-pflicht-tests-vor-commit)
|
||
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
|
||
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
|
||
- [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze)
|
||
- [16. Workpackage Status (v2.6.0)](#16-workpackage-status-v260)
|
||
|
||
</details>
|
||
---
|
||
|
||
## 1. Zweck & Einordnung
|
||
|
||
Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline**. Es beschreibt, wie Daten vom Markdown-Vault in den Wissensgraphen (Qdrant) gelangen, wie der Retriever betrieben wird und wie die **RAG-Generierung** (inkl. Decision Engine & Interviewer) funktioniert.
|
||
|
||
**Zielgruppe:** Dev/Ops, Tech-Leads.
|
||
**Scope:**
|
||
* **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).
|
||
|
||
---
|
||
|
||
## 2. Die Import-Pipeline (Runbook)
|
||
|
||
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 13-Schritte-Prozess (Async + Smart)
|
||
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.
|
||
2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
|
||
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`.
|
||
5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs (z.B. `sliding_smart_edges`).
|
||
6. **Smart Edge Allocation (Neu in WP15):**
|
||
* Wenn in `types.yaml` aktiviert (`enable_smart_edge_allocation`):
|
||
* Der `SemanticAnalyzer` sendet jeden Chunk an das LLM.
|
||
* **Resilienz & Traffic Control:**
|
||
* **Priority:** Der Request nutzt `priority="background"`.
|
||
* **Semaphore:** Eine globale Semaphore (Limit: 2, konfigurierbar) verhindert System-Überlastung.
|
||
* **Retry & Backoff:** Bei Fehlern (Timeouts) wird bis zu 5-mal mit exponentieller Wartezeit wiederholt.
|
||
* **JSON Repair:** Der Analyzer erkennt fehlerhaftes JSON (z.B. Dict statt Liste) und repariert es automatisch.
|
||
* **Safety Fallback:** Schlagen alle Versuche fehl, werden die Kanten *allen* Chunks zugewiesen, um Datenverlust zu vermeiden.
|
||
* Ergebnis: Das LLM filtert irrelevante Links aus dem Chunk ("Broadcasting" verhindern).
|
||
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`, `next`, `prev` (Sequenz).
|
||
11. **Embedding & Upsert (Async):**
|
||
* Generierung der Vektoren via `nomic-embed-text` (768 Dim).
|
||
12. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat.
|
||
13. **Diagnose:** Automatischer Check der Integrität nach dem Lauf.
|
||
|
||
### 2.2 Standard-Betrieb (Inkrementell)
|
||
Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
|
||
|
||
export QDRANT_URL="http://localhost:6333"
|
||
export COLLECTION_PREFIX="mindnet"
|
||
|
||
# Import starten (Apply = Schreiben, Purge = Sauberer Upsert)
|
||
# Nutzt das Venv der Produktionsumgebung
|
||
/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
|
||
--vault ./vault \
|
||
--prefix "$COLLECTION_PREFIX" \
|
||
--apply \
|
||
--purge-before-upsert \
|
||
--sync-deletes
|
||
|
||
* `--apply`: Ohne dieses Flag läuft ein Dry-Run (nur Simulation).
|
||
* `--purge-before-upsert`: Löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Essentiell, um "Geister-Chunks" zu vermeiden, wenn Text gekürzt wurde.
|
||
* `--sync-deletes`: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.
|
||
|
||
### 2.3 Deployment & Restart (Systemd)
|
||
Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden.
|
||
|
||
# Neustart des Produktions-Services (API + UI)
|
||
sudo systemctl restart mindnet-prod
|
||
sudo systemctl restart mindnet-ui-prod
|
||
|
||
# Prüfung
|
||
sudo systemctl status mindnet-prod
|
||
|
||
### 2.4 Full Rebuild (Clean Slate)
|
||
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!
|
||
|
||
# 0. Modell sicherstellen (WICHTIG für v2.4+)
|
||
ollama pull nomic-embed-text
|
||
|
||
# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema 768d)
|
||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||
|
||
# 2. Vollständiger Import aller Dateien
|
||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||
|
||
---
|
||
|
||
## 3. Chunking & Payload-Aufbau
|
||
|
||
Das Chunking ist profilbasiert und typgesteuert.
|
||
|
||
### 3.1 Chunk-Profile
|
||
In `types.yaml` definiert. Standard-Profile (in `chunk_config.py` implementiert):
|
||
* `sliding_short`: Max 128 Tokens (z.B. für Logs, Chats).
|
||
* `sliding_standard`: Max 512 Tokens (Standard für Massendaten).
|
||
* `sliding_smart_edges`: Sliding Window, optimiert für LLM-Analyse (Fließtext).
|
||
* `structured_smart_edges`: Trennt strikt an Überschriften (für strukturierte Daten).
|
||
|
||
### 3.2 Payload-Felder
|
||
Jeder Chunk erhält zwei Text-Felder:
|
||
* `text`: Der reine Inhalt des Chunks (ohne Overlap). Wird dem Nutzer angezeigt.
|
||
* `window`: Der Inhalt plus Overlap zu Vorgänger/Nachfolger. Wird für das Embedding genutzt (besserer Kontext).
|
||
|
||
---
|
||
|
||
## 4. Edge-Erzeugung (Die V2-Logik)
|
||
|
||
In v2.6 entstehen Kanten nach strenger Priorität.
|
||
|
||
### 4.1 Prioritäten & Provenance
|
||
Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch:
|
||
|
||
| Priorität | Quelle | Syntax (Bsp.) | Rule ID | Confidence |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| **1** | Inline | `[[rel:depends_on X]]` | `inline:rel` | ~0.95 |
|
||
| **2** | Callout | `> [!edge] related_to: [[X]]` | `callout:edge` | ~0.90 |
|
||
| **3** | Wikilink | `[[X]]` | `explicit:wikilink` | 1.00 |
|
||
| **4** | Smart | *(via LLM Filter)* | `smart:llm_filter` | 0.90 |
|
||
| **5** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 |
|
||
| **6** | Struktur | *(automatisch)* | `structure:...` | 1.00 |
|
||
|
||
### 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.
|
||
* *Beispiel:* Note Typ `project` verlinkt `[[Tool A]]`.
|
||
* *Ergebnis:* Kante `references` (explizit) UND Kante `depends_on` (Default).
|
||
|
||
---
|
||
|
||
## 5. Retriever, Chat & Generation (RAG Pipeline)
|
||
|
||
Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.
|
||
|
||
### 5.1 Retrieval (Hybrid)
|
||
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)
|
||
Der Request durchläuft den **Hybrid Router v5**:
|
||
1. **Question Detection:** Ist es eine Frage (`?`, W-Wörter)? -> RAG Modus. Interviews werden hier blockiert.
|
||
2. **Keyword Scan:** Enthält es Keywords aus `types.yaml` (Objekt, z.B. "Projekt") oder `decision_engine.yaml` (Action, z.B. "erstellen")? -> INTERVIEW Modus.
|
||
3. **LLM Fallback:** Wenn unklar, entscheidet das LLM.
|
||
|
||
### 5.3 Context Enrichment
|
||
Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an:
|
||
* **Typ-Injection:** `[DECISION]`, `[PROJECT]`.
|
||
* **Reasoning-Infos:** `(Score: 0.75)`.
|
||
|
||
### 5.4 Generation (LLM) mit Traffic Control
|
||
* **Engine:** Ollama (lokal).
|
||
* **Modell:** `phi3:mini` (Standard).
|
||
* **Prompting:** Template wird basierend auf Intent gewählt (`decision_template`, `interview_template` etc.).
|
||
* **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)
|
||
Ein paralleler Datenfluss im Frontend ("Draft Editor") zur Unterstützung des Autors.
|
||
1. **Trigger:** User klickt "Analyse starten" oder tippt.
|
||
2. **Service:** `ingest/analyze` (Backend).
|
||
3. **Discovery:**
|
||
* **Sliding Window:** Zerlegt Text in Abschnitte.
|
||
* **Embedding:** Vektorisiert Abschnitte via Nomic (Async).
|
||
* **Exact Match:** Sucht nach Aliases ("KI-Gedächtnis").
|
||
* **Matrix Logic:** Bestimmt Kanten-Typ (`experience` -> `based_on` -> `value`).
|
||
4. **Feedback:** UI zeigt Vorschläge (`[[rel:...]]`) zum Einfügen an.
|
||
|
||
---
|
||
|
||
## 6. Feedback & Lernen (WP04c)
|
||
|
||
Das System schreibt kontinuierlich Logs ("Data Flywheel"):
|
||
* `data/logs/search_history.jsonl`: Trainingsdaten (Query + Ergebnisse + Breakdown).
|
||
* `data/logs/feedback.jsonl`: Labels (User-Rating zur `query_id`).
|
||
|
||
---
|
||
|
||
## 7. Quality Gates & Tests
|
||
|
||
Diese Tests garantieren die Stabilität der Pipeline.
|
||
|
||
### 7.1 Pflicht-Tests vor Commit
|
||
|
||
1. **Payload Dryrun (Schema-Check):**
|
||
Simuliert Import, prüft JSON-Schema Konformität.
|
||
|
||
python3 -m scripts.payload_dryrun --vault ./test_vault
|
||
|
||
2. **Full Edge Check (Graph-Integrität):**
|
||
Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein).
|
||
|
||
python3 -m scripts.edges_full_check
|
||
|
||
### 7.2 Smoke-Test (E2E)
|
||
Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funktionieren.
|
||
|
||
# Retriever Test
|
||
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5
|
||
|
||
# Intelligence Test (WP11)
|
||
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
|
||
|
||
# Decision Engine Test (WP06)
|
||
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
|
||
|
||
# Feedback Test
|
||
python tests/test_feedback_smoke.py --url http://localhost:8001/query
|
||
|
||
---
|
||
|
||
## 8. Ausblick & Roadmap (Technische Skizzen)
|
||
|
||
Wie entwickeln wir die Pipeline weiter?
|
||
|
||
### 8.1 WP-08: Self-Tuning (Skizze)
|
||
**Ziel:** Die Gewichte in `retriever.yaml` basierend auf `feedback.jsonl` optimieren.
|
||
**Ansatz:** Ein Offline-Learning-Skript `scripts/optimize_weights.py`.
|
||
1. **Load:** Liest `search_history.jsonl` und joint mit `feedback.jsonl` via `query_id`.
|
||
2. **Analyze:** Korrelation Scores vs. User-Rating.
|
||
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
|
||
|
||
---
|
||
|
||
## 16. Workpackage Status (v2.6.0)
|
||
|
||
Aktueller Implementierungsstand der Module.
|
||
|
||
| WP | Titel | Status | Anmerkung |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
|
||
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
|
||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
|
||
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** |
|
||
| **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. | |