mindnet/docs/pipeline_playbook.md

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").