mindnet/docs/03_Technical_References/03_tech_ingestion_pipeline.md

---
doc_type: technical_reference
audience: developer, devops
scope: backend, ingestion, smart_edges
status: active
version: 2.6.0
context: "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.

```bash
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.

```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)
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.
```bash
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).
```bash
python3 -m scripts.edges_full_check
```