mindnet/docs/03_Technical_References/03_tech_ingestion_pipeline.md

doc_type	audience	scope	status	version	context
technical_reference	developer, devops	backend, ingestion, smart_edges	active	2.6.0	Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle.

Ingestion Pipeline & Smart Processing

Quellen: pipeline_playbook.md, Handbuch.md

Die Ingestion transformiert Markdown in den Graphen. Entrypoint: scripts/import_markdown.py.

1. Der Import-Prozess (13-Schritte-Workflow)

Der Prozess ist asynchron und idempotent.

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.
4. Note-Payload generieren: Erstellen des JSON-Objekts für mindnet_notes.
5. Chunking anwenden: Zerlegung des Textes basierend auf dem chunk_profile (siehe Kap. 3).
6. Smart Edge Allocation (WP15):
   • Wenn enable_smart_edge_allocation: true: Der SemanticAnalyzer sendet Chunks an das LLM.
   • Traffic Control: Request nutzt priority="background". Semaphore (Limit via .env) drosselt die Last.
   • Resilienz: Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks).
7. Inline-Kanten finden: Parsing von [[rel:...]].
8. Callout-Kanten finden: Parsing von > [!edge].
9. Default-Edges erzeugen: Anwendung der edge_defaults aus Registry.
10. Strukturkanten erzeugen: belongs_to, next, prev.
11. Embedding (Async): Generierung via nomic-embed-text (768 Dim).
12. Strict Mode: Abbruch bei leeren Embeddings oder Dimension 0.
13. Diagnose: Integritäts-Check nach dem Lauf.

---

2. Betrieb & CLI Befehle

2.1 Standard-Betrieb (Inkrementell)

Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.

export QDRANT_URL="http://localhost:6333"
export COLLECTION_PREFIX="mindnet"

# 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

[!WARNING] Purge-Before-Upsert Das Flag --purge-before-upsert ist kritisch. Es löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Ohne dieses Flag entstehen "Geister-Chunks" (alte Textabschnitte, die im Markdown gelöscht wurden, aber im Index verbleiben).

2.2 Full Rebuild (Clean Slate)

Notwendig bei Änderungen an types.yaml (z.B. neue Chunking-Profile) oder Modell-Wechsel.

# 0. Modell sicherstellen
ollama pull nomic-embed-text

# 1. Qdrant Collections löschen (Wipe)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Vollständiger Import (Force)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

---

3. Chunking & Payload

Das Chunking ist profilbasiert und in types.yaml konfiguriert. Seit v2.6 unterscheiden wir zwischen Sliding Window und Heading Split.

3.1 Profile und Strategien

Profil	Strategie	Parameter	Einsatzgebiet
sliding_short	sliding_window	Max: 350, Target: 200	Kurze Logs, Chats, Risiken.
sliding_standard	sliding_window	Max: 650, Target: 450	Massendaten (Journal, Quellen).
sliding_smart_edges	sliding_window	Max: 600, Target: 400	Fließtexte mit hohem Wert (Projekte, Erfahrungen).
structured_smart_edges	by_heading	strict: false (Soft)	Strukturierte Texte, wo kleine Abschnitte gemergt werden dürfen.
structured_smart_edges_strict	by_heading	strict: true (Hard)	Atomare Einheiten: Entscheidungen, Werte, Profile.

3.2 Die by_heading Logik (Neu in v2.6)

Die Strategie by_heading zerlegt Texte anhand ihrer Struktur (Überschriften).

• Split Level: Definiert die Tiefe (z.B. 2 = H1 & H2 triggern Split).
• Modus "Strict" (strict_heading_split: true):
  • Jede Überschrift (<= split_level) erzwingt einen neuen Chunk.
  • Ausnahme: Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt (Context-Aware Merge).
  • Safety: Wird ein Abschnitt zu lang (> max), wird trotzdem getrennt (Hybrid-Fallback).
• Modus "Soft" (strict_heading_split: false):
  • Überschriften auf dem Split-Level (z.B. H2) lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die target-Größe erreicht hat.
  • Überschriften oberhalb (z.B. H1) erzwingen immer einen Split (Hierarchie-Reset).

3.3 Payload-Felder (Qdrant)

• text: Der reine Inhalt (Anzeige im UI).
• window: Inhalt plus Overlap (für Embedding). Bei by_heading enthält dies oft den Kontext der Eltern-Überschrift.

---

4. Edge-Erzeugung & Prioritäten

Kanten werden nach Vertrauenswürdigkeit (provenance) priorisiert. Die höhere Prio gewinnt.

Prio	Quelle	Rule ID	Confidence
1	Inline	inline:rel	0.95
2	Callout	callout:edge	0.90
3	Wikilink	explicit:wikilink	1.00
4	Smart Edge	smart:llm_filter	0.90
5	Type Default	edge_defaults	0.70
6	Struktur	structure	1.00

---

5. Quality Gates & Tests

Diese Tests garantieren die Stabilität der Pipeline.

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