--- doc_type: technical_reference audience: developer, devops scope: backend, ingestion, smart_edges, edge_registry status: active version: 2.7.1 context: "Detaillierte technische Beschreibung der Import-Pipeline, Chunking-Strategien und CLI-Befehle." --- # Ingestion Pipeline & Smart Processing **Quellen:** `pipeline_playbook.md`, `Handbuch.md`, `edge_registry.py`, `01_edge_vocabulary.md`, `06_active_roadmap.md` Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.7 integriert dieser Prozess die **Edge Registry** zur Normalisierung des Vokabulars und beachtet den **Content Lifecycle**. ## 1. Der Import-Prozess (15-Schritte-Workflow) Der Prozess ist **asynchron** und **idempotent**. 1. **Trigger & Async Dispatch:** * **API (`/save`):** Nimmt Request entgegen, validiert und startet Background-Task ("Fire & Forget"). Antwortet sofort mit `202/Queued`. * **CLI:** Iteriert über Dateien und nutzt `asyncio.Semaphore` zur Drosselung. 2. **Markdown lesen:** Rekursives Scannen des Vaults. 3. **Frontmatter Check & Hard Skip (WP-22):** * Extraktion von `status` und `type`. * **Hard Skip Rule:** Wenn `status` in `['system', 'template']` ist, wird die Datei **sofort übersprungen**. Sie wird weder vektorisiert noch in den Graphen aufgenommen. * Validierung der Pflichtfelder (`id`, `title`) für alle anderen Dateien. 4. **Edge Registry Initialisierung (WP-22):** * Laden der Singleton-Instanz der `EdgeRegistry`. * Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`. 5. **Config Resolution:** * Bestimmung von `chunking_profile` und `retriever_weight`. * **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default. 6. **Note-Payload generieren:** * Erstellen des JSON-Objekts inklusive `status` (für Scoring). * **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten). 7. **Change Detection:** * Vergleich des Hashes mit Qdrant. * Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). 8. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). 9. **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). 10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`. 11. **Alias-Auflösung & Kanonisierung (WP-22):** * Jede Kante wird via `edge_registry.resolve()` normalisiert. * Aliase (z.B. `basiert_auf`) werden zu kanonischen Typen (z.B. `based_on`) aufgelöst. * Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert. 12. **Callout-Kanten finden:** Parsing von `> [!edge]`. 13. **Default- & Matrix-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry und Matrix-Logik. 14. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`. 15. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim). 16. **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. ```bash export QDRANT_URL="http://localhost:6333" export COLLECTION_PREFIX="mindnet" # Steuert, wann eine Datei als "geändert" gilt export MINDNET_CHANGE_DETECTION_MODE="full" # 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), der Registry oder Modell-Wechsel. ```bash # 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) # --force ignoriert alle Hashes und schreibt alles neu python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force ``` --- ## 3. Chunking & Payload Das Chunking ist profilbasiert und in `types.yaml` konfiguriert. ### 3.1 Profile und Strategien (Vollständige Referenz) | 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). | | `structured_smart_edges` | `by_heading` | `strict: false` (Soft) | Strukturierte Texte, Merging erlaubt. | | `structured_smart_edges_strict` | `by_heading` | `strict: true` (Hard) | **Atomare Einheiten**: Entscheidungen, Werte. | | `structured_smart_edges_strict_L3`| `by_heading` | `strict: true`, `level: 3` | Tief geschachtelte Prinzipien (Tier 2/MP1). | ### 3.2 Die `by_heading` Logik (v2.9 Hybrid) Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt seit v2.9 ein "Safety Net" gegen zu große Chunks. * **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. * *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt (verhindert verwaiste Überschriften). * *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt. * **Modus "Soft" (`strict_heading_split: false`):** * **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split. * **Füll-Logik:** Ü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. * *Safety Net:* Auch hier greift das `max` Token Limit. ### 3.3 Payload-Felder (Qdrant) * `text`: Der reine Inhalt (Anzeige im UI). * `window`: Inhalt plus Overlap (für Embedding). * `chunk_profile`: Das effektiv genutzte Profil (zur Nachverfolgung). --- ## 4. Edge-Erzeugung & Prioritäten (Provenance) Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt. | Prio | Quelle | Rule ID | Confidence | Erläuterung | | :--- | :--- | :--- | :--- | :--- | | **1** | Wikilink | `explicit:wikilink` | **1.00** | Harte menschliche Setzung. | | **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. | | **3** | Callout | `callout:edge` | **0.90** | Explizite Meta-Information. | | **4** | Smart Edge | `smart:llm_filter` | **0.90** | KI-validierte Verbindung. | | **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. | | **6** | Struktur | `structure` | **1.00** | System-interne Verkettung. | --- ## 5. Quality Gates & Monitoring In v2.7 wurden Tools zur Überwachung der Datenqualität integriert: **1. Registry Review:** Prüfung der `data/logs/unknown_edges.jsonl`. Administratoren sollten hier gelistete Begriffe als Aliase in die `01_edge_vocabulary.md` aufnehmen. **2. Payload Dryrun (Schema-Check):** Simuliert Import, prüft JSON-Schema Konformität. ```bash python3 -m scripts.payload_dryrun --vault ./test_vault ``` **3. Full Edge Check (Graph-Integrität):** Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein). ```bash python3 -m scripts.edges_full_check ```