# mindnet v2.2 – Pipeline Playbook **Datei:** `docs/mindnet_pipeline_playbook_v2.2.md` **Stand:** 2025-12-08 **Status:** **FINAL** (Inkl. WP05 RAG Pipeline) **Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`. ---
📖 Inhaltsverzeichnis (Klicken zum Öffnen) - [mindnet v2.2 – Pipeline Playbook](#mindnet-v22--pipeline-playbook) - [1. Zweck \& Einordnung](#1-zweck--einordnung) - [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook) - [2.1 Der 12-Schritte-Prozess](#21-der-12-schritte-prozess) - [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 Typ-Defaults](#42-typ-defaults) - [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline) - [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid) - [5.2 Context Enrichment (Das "Context Intelligence" Pattern)](#52-context-enrichment-das-context-intelligence-pattern) - [5.3 Generation (LLM)](#53-generation-llm) - [5.4 Explanation Mode (WP04b)](#54-explanation-mode-wp04b) - [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-06: Decision Engine (Skizze)](#81-wp-06-decision-engine-skizze) - [8.2 WP-08: Self-Tuning (Skizze)](#82-wp-08-self-tuning-skizze)
--- ## 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** funktioniert. **Zielgruppe:** Dev/Ops, Tech-Leads. **Scope:** * **Ist-Stand (WP01–WP05):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat, Feedback Loop. * **Roadmap (Ausblick):** Technische Skizzen für Self-Healing (WP06) und 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 12-Schritte-Prozess Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab: 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. 6. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext. 7. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken. 8. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry. 9. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz). 10. **Chunks upserten:** Schreiben in Qdrant (`mindnet_chunks`). 11. **Edges upserten:** Schreiben in Qdrant (`mindnet_edges`). 12. **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 muss der API-Prozess neu gestartet werden. # Neustart des Produktions-Services sudo systemctl restart mindnet-prod # Prüfung sudo systemctl status mindnet-prod ### 2.4 Full Rebuild (Clean Slate) Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunk-Größen) oder Embedding-Modellen. # 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema) 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 --- ## 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): * `short`: Max 128 Tokens (z.B. für Logs, Chats). * `medium`: Max 256 Tokens (z.B. für Konzepte). * `long`: Max 512 Tokens (z.B. für Essays, Projekte). * `by_heading`: Trennt strikt an Überschriften. ### 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.2 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** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 | | **5** | Struktur | *(automatisch)* | `structure:...` | 1.00 | ### 4.2 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) total_score = semantic_weight * semantic_score + edge_weight * edge_bonus + centrality_weight * centrality_bonus + type_weight * retriever_weight 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 Context Enrichment (Das "Context Intelligence" Pattern) Bevor der Text an das LLM geht, reichert der Router (`chat.py`) ihn an. * **Metadaten-Injection:** `[DECISION]`, `[PROJECT]`, `[SCORE: 0.9]`. * **Zweck:** Ermöglicht kleinen Modellen (Phi-3) das Erkennen von logischen Rollen ("Warum?" vs "Was?"). ### 5.3 Generation (LLM) * **Engine:** Ollama (lokal). * **Modell:** `phi3:mini` (Standard). * **Prompting:** Gesteuert über `config/prompts.yaml`. ### 5.4 Explanation Mode (WP04b) Wird `/query` mit `explain=True` aufgerufen, führt der Retriever eine Post-Processing-Analyse durch und liefert `reasons` ("Verweist auf...", "Hoher Typ-Bonus"). --- ## 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 # Chat Test (Neu WP05) python tests/test_chat_wp05.py # 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-06: Decision Engine (Skizze) **Ziel:** Aktive Entscheidungsberatung. **Erweiterung:** Der Chat-Router lädt bei Entscheidungfragen gezielt `type: value` Notizen nach, um Optionen gegen Werte abzuwägen. ### 8.2 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`.