docs/pipeline_playbook.md hinzugefügt

docs/pipeline_playbook.md

@@ -0,0 +1,191 @@
+# mindnet v2.2 – Pipeline Playbook
+**Datei:** `docs/mindnet_pipeline_playbook_v2.2.md`
+**Stand:** 2025-12-07
+**Status:** **FINAL** (Konsolidiert aus WP02, WP03, WP04a)
+**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `wp04_retriever_scoring.md`.
+
+---
+
+## 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 und wie der Retriever konfiguriert und betrieben wird.
+
+**Zielgruppe:** Dev/Ops, Tech-Leads.
+**Scope:**
+* **Ist-Stand (WP01–WP04a):** Markdown-Import, Chunking, Edge-Erzeugung, Hybrider Retriever.
+* **Roadmap (Ausblick):** Self-Healing (WP06), Feedback-Loops (WP08).
+
+---
+
+## 2. Die Import-Pipeline (Runbook)
+
+Der Import ist der kritischste Prozess. 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)
+    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 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
+
+### 2.4 Baseline-Builds & Hashing
+Um unnötige Updates zu vermeiden, nutzt der Importer Hashes.
+* **ENV `MINDNET_HASH_COMPARE`:** Steuert, was verglichen wird.
+    * `Body`: Nur Textänderungen triggern Update (Standard).
+    * `Full`: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update.
+* **Flag `--baseline-modes`:** Berechnet Hashes für alle Modi vor, um spätere Wechsel der Strategie ohne Massen-Update zu ermöglichen.
+
+---
+
+## 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 & Scoring
+
+Der Retriever (`app/core/retriever.py`) kombiniert Signale zur Laufzeit.
+
+### 5.1 Konfiguration (`retriever.yaml`)
+Diese Datei steuert das Ranking. Änderungen wirken sofort (API-Neustart).
+
+    scoring:
+      semantic_weight:   1.0    # Vektor-Ähnlichkeit
+      edge_weight:       0.7    # Graph-Dichte Bonus
+      centrality_weight: 0.5    # Zentralitäts-Bonus
+
+### 5.2 Scoring-Formel
+    total_score =
+        semantic_weight   * semantic_score
+      + edge_weight       * edge_bonus
+      + centrality_weight * centrality_bonus
+      + type_weight       * retriever_weight
+
+* `retriever_weight`: Kommt aus dem Note-Payload (via `types.yaml`).
+* `edge_bonus`: Summe der `confidence` aller relevanten Kanten im Subgraph.
+
+### 5.3 Hybrider Modus
+Der Request muss `mode="hybrid"` und `expand.depth > 0` setzen, damit der Graph genutzt wird.
+* **Expand:** Lädt Nachbarn der Vektor-Treffer.
+* **Re-Rank:** Berechnet Boni auf diesem lokalen Graphen.
+
+---
+
+## 6. Quality Gates & Tests
+
+Diese Tests garantieren die Stabilität der Pipeline.
+
+### 6.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; keine verwaisten Kanten).
+    
+        python3 -m scripts.edges_full_check
+
+3.  **Unit Tests:**
+    
+        pytest tests/test_retriever_basic.py tests/test_retriever_edges.py
+
+### 6.2 Smoke-Test (E2E)
+Prüft am laufenden System, ob Semantik und Graph funktionieren.
+
+    python scripts/test_retriever_smoke.py \
+        --query "mindnet" \
+        --mode hybrid \
+        --expand-depth 1 \
+        --top-k 5
+
+### 6.3 Roundtrip-Test (Datenverlust-Check)
+Exportiert Qdrant zurück nach Markdown und vergleicht mit Original.
+
+    python3 -m scripts.export_markdown --out ./_export
+    python3 tests/compare_vaults.py --src ./vault --dst ./_export --focus body
+
+---
+
+## 7. Ausblick & Roadmap
+
+### 7.1 Self-Healing (WP06)
+Geplant: Automatisierte Jobs, die `unresolved` Referenzen periodisch prüfen und heilen, wenn die Ziel-Note erstellt wurde. Aktuell manuell via `scripts/resolve_unresolved_references.py`.
+
+### 7.2 Feedback-Logging (WP04c/WP08)
+Geplant: Speicherung von User-Feedback zu Suchergebnissen, um `retriever.yaml` Gewichte mittelfristig automatisch zu justieren ("Self-Tuning").