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	Detaillierte technische Beschreibung der Import-Pipeline, Quality Gates 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 unten).
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: 2) 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 (768d).
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 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.

Profil	Max Token	Overlap	Einsatz
sliding_short	128	20	Logs, Chats.
sliding_standard	512	50	Massendaten.
sliding_smart_edges	512	50	Wichtige Inhalte (Experience, Project).
structured_smart	n/a	n/a	Trennt strikt an Headings (für ADRs).

Payload-Felder:

• text: Der reine Inhalt (Anzeige).
• window: Inhalt plus Overlap (für Embedding).

---

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