mindnet/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md

LLM-Validierung von Links in Notizen

Version: v4.1.0
Status: Aktiv

Übersicht

Das Mindnet-System unterstützt zwei Arten von Links:

1. Explizite Links - Werden direkt übernommen (keine Validierung)
2. Global Pool Links - Werden vom LLM validiert (wenn aktiviert)

Explizite Links (keine Validierung)

Diese Links werden sofort in den Graph übernommen, ohne LLM-Validierung:

1. Typed Relations

[[rel:mastered_by|Klaus]]
[[rel:depends_on|Projekt Alpha]]

2. Standard Wikilinks

[[Klaus]]
[[Projekt Alpha]]

3. Callouts

> [!edge] mastered_by:Klaus
> [!edge] depends_on:Projekt Alpha

Hinweis: Explizite Links haben immer Vorrang und werden nicht validiert.

Global Pool Links (mit LLM-Validierung)

Links, die vom LLM validiert werden sollen, müssen in einer speziellen Sektion am Ende der Notiz definiert werden.

Format

Erstellen Sie eine Sektion mit einem der folgenden Titel:

• ### Unzugeordnete Kanten
• ### Edge Pool
• ### Candidates

In dieser Sektion listen Sie Links im Format kind:target auf:

---
type: concept
title: Meine Notiz
---

# Inhalt der Notiz

Hier ist der normale Inhalt...

### Unzugeordnete Kanten

related_to:Klaus
mastered_by:Projekt Alpha
depends_on:Andere Notiz

Beispiel

---
type: decision
title: Entscheidung über Technologie-Stack
---

# Entscheidung über Technologie-Stack

Wir haben uns für React entschieden, weil...

## Begründung

React bietet bessere Performance...

### Unzugeordnete Kanten

related_to:React-Dokumentation
depends_on:Performance-Analyse
uses:TypeScript

Validierung

Wichtig: Global Pool Links werden nur validiert, wenn:

1. Die Chunk-Konfiguration enable_smart_edge_allocation: true enthält
2. Dies wird normalerweise in config/types.yaml pro Note-Typ konfiguriert

Beispiel-Konfiguration in types.yaml:

types:
  decision:
    chunking_profile: sliding_smart_edges
    chunking:
      sliding_smart_edges:
        enable_smart_edge_allocation: true  # ← Aktiviert LLM-Validierung

Validierungsprozess

1. Extraktion: Links aus der "Unzugeordnete Kanten" Sektion werden extrahiert
2. Provenance: Erhalten provenance: "global_pool"
3. Validierung: Für jeden Link wird geprüft:
   • Ist der Link semantisch relevant für den Chunk-Kontext?
   • Passt die Relation (kind) zum Ziel?
4. Ergebnis:
   • ✅ YES → Link wird in den Graph übernommen
   • ❌ NO → Link wird verworfen

Validierungs-Prompt

Das System verwendet den Prompt edge_validation aus config/prompts.yaml:

Verify relation '{edge_kind}' for graph integrity.
Chunk: "{chunk_text}"
Target: "{target_title}" ({target_summary})
Respond ONLY with 'YES' or 'NO'.

Best Practices

✅ Empfohlen

1. Explizite Links für sichere Verbindungen:

   Diese Entscheidung [[rel:depends_on|Performance-Analyse]] wurde getroffen.
   

2. Global Pool für unsichere/explorative Links:

   ### Unzugeordnete Kanten
   related_to:Mögliche Verbindung
   

3. Kombination beider Ansätze:

   # Hauptinhalt
   
   Explizite Verbindung: [[rel:depends_on|Sichere Notiz]]
   
   ## Weitere Überlegungen
   
   ### Unzugeordnete Kanten
   related_to:Unsichere Verbindung
   explored_in:Experimentelle Notiz
   

❌ Vermeiden

1. Nicht zu viele Global Pool Links:

   • Jeder Link erfordert einen LLM-Aufruf
   • Kann die Ingestion verlangsamen

2. Nicht für offensichtliche Links:

   • Nutzen Sie explizite Links für klare Verbindungen
   • Global Pool ist für explorative/unsichere Links gedacht

Aktivierung der Validierung

Schritt 1: Chunk-Profile konfigurieren

In config/types.yaml:

types:
  your_type:
    chunking_profile: sliding_smart_edges
    chunking:
      sliding_smart_edges:
        enable_smart_edge_allocation: true

Schritt 2: Notiz erstellen

---
type: your_type
title: Meine Notiz
---

# Inhalt

### Unzugeordnete Kanten

related_to:Ziel-Notiz

Schritt 3: Import ausführen

python3 -m scripts.import_markdown --vault ./vault --apply

Logging & Debugging

Während der Ingestion sehen Sie im Log:

⚖️ [VALIDATING] Relation 'related_to' -> 'Ziel-Notiz' (Profile: ingest_validator)...
✅ [VALIDATED] Relation to 'Ziel-Notiz' confirmed.

oder

🚫 [REJECTED] Relation to 'Ziel-Notiz' irrelevant for this chunk.

Technische Details

Provenance-System

• explicit: Explizite Links (keine Validierung)
• global_pool: Global Pool Links (mit Validierung)
• semantic_ai: KI-generierte Links
• rule: Regel-basierte Links (z.B. aus types.yaml)

Code-Referenzen

• Extraktion: app/core/chunking/chunking_processor.py (Zeile 66-81)
• Validierung: app/core/ingestion/ingestion_validation.py
• Integration: app/core/ingestion/ingestion_processor.py (Zeile 237-239)

FAQ

Q: Werden explizite Links auch validiert?
A: Nein, explizite Links werden direkt übernommen.

Q: Kann ich die Validierung für bestimmte Links überspringen?
A: Ja, nutzen Sie explizite Links ([[rel:kind|target]] oder > [!edge]).

Q: Was passiert, wenn das LLM nicht verfügbar ist?
A: Bei transienten Fehlern (Netzwerk) werden Links erlaubt. Bei permanenten Fehlern werden sie verworfen.

Q: Kann ich mehrere Links in einer Zeile angeben?
A: Nein, jeder Link muss in einer eigenen Zeile stehen: kind:target.

Zusammenfassung

• ✅ Explizite Links: [[rel:kind|target]] oder > [!edge] → Keine Validierung
• ✅ Global Pool Links: Sektion ### Unzugeordnete Kanten → Mit LLM-Validierung
• ✅ Aktivierung: enable_smart_edge_allocation: true in Chunk-Config
• ✅ Format: kind:target (eine pro Zeile)