From 603bba533b8a6fa3a842ef1910bc4d048ebfcca4 Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 7 Dec 2025 12:07:03 +0100 Subject: [PATCH] =?UTF-8?q?docs/pipeline=5Fplaybook.md=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/pipeline_playbook.md | 191 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 docs/pipeline_playbook.md diff --git a/docs/pipeline_playbook.md b/docs/pipeline_playbook.md new file mode 100644 index 0000000..9f16c6d --- /dev/null +++ b/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"). \ No newline at end of file