mindnet/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md

LLM-Validierung von Links in Notizen (Phase 3 Agentic Edge Validation)

Version: v4.5.8
Status: Aktiv
Aktualisiert: WP-24c Phase 3 Agentic Edge Validation mit Kontext-Optimierung

Ü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.

Validierte Links (Phase 3 - candidate: Präfix) - WP-24c v4.5.8

Links, die vom LLM validiert werden sollen, müssen in einer speziellen Sektion am Ende der Notiz definiert werden. Diese Links erhalten das candidate: Präfix und durchlaufen Phase 3 Agentic Edge Validation.

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

Phase 3 Validierungsprozess (WP-24c v4.5.8)

1. Extraktion: Links aus der "Unzugeordnete Kanten" Sektion werden extrahiert
2. candidate: Präfix: Erhalten candidate: Präfix in rule_id oder provenance
3. Kontext-Optimierung:
   • Note-Scope (scope: note): LLM nutzt note_summary (Top 5 Chunks) oder note_text (aggregierter Gesamttext)
   • Chunk-Scope (scope: chunk): LLM nutzt spezifischen Chunk-Text, falls verfügbar, sonst Note-Text
4. Validierung: LLM prüft semantisch (via ingest_validator Profil, Temperature 0.0):
   • Ist der Link semantisch relevant für den Kontext?
   • Passt die Relation (kind) zum Ziel?
5. Ergebnis:
   • ✅ VERIFIED: candidate: Präfix wird entfernt, Kante wird in den Graph übernommen
   • 🚫 REJECTED: Kante wird nicht in die Datenbank geschrieben (verhindert "Geister-Verknüpfungen")

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 (Phase 3)

Während der Ingestion sehen Sie im Log:

🚀 [PHASE 3] Validierung: Note-A -> Ziel-Notiz (related_to) | Scope: chunk | Kontext: Chunk-Scope (c00)
⚖️ [VALIDATING] Relation 'related_to' -> 'Ziel-Notiz' (Profile: ingest_validator)...
✅ [PHASE 3] VERIFIED: Note-A -> Ziel-Notiz (related_to) | rule_id: explicit

oder

🚀 [PHASE 3] Validierung: Note-A -> Ziel-Notiz (related_to) | Scope: note | Kontext: Note-Scope (aggregiert)
⚖️ [VALIDATING] Relation 'related_to' -> 'Ziel-Notiz' (Profile: ingest_validator)...
🚫 [PHASE 3] REJECTED: Note-A -> Ziel-Notiz (related_to)

Hinweis: Phase 3 Logs zeigen auch die Kontext-Optimierung (Note-Scope vs. Chunk-Scope) und den finalen Status (VERIFIED/REJECTED).

Technische Details

Provenance-System (WP-24c v4.5.8)

• explicit: Explizite Links (keine Validierung, höchste Priorität)
• explicit:note_zone: Note-Scope Links aus ## Smart Edges (keine Validierung)
• candidate:: Links aus ### Unzugeordnete Kanten (Phase 3 Validierung erforderlich)
• semantic_ai: KI-generierte Links
• rule: Regel-basierte Links (z.B. aus types.yaml)
• structure: System-generierte Spiegelkanten (automatische Invers-Logik)

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: Das System unterscheidet zwischen:

• Transienten Fehlern (Netzwerk, Timeout): Kante wird erlaubt (Integrität vor Präzision - verhindert Datenverlust)
• Permanenten Fehlern (Config, Validation): Kante wird abgelehnt (Graph-Qualität schützen)

Q: Was ist der Unterschied zwischen expliziten und validierten Links?
A:

• Explizite Links: Sofortige Übernahme, höchste Priorität, keine Validierung, confidence: 1.0
• Validierte Links: Phase 3 Prüfung, candidate: Präfix, können abgelehnt werden, höhere Graph-Qualität

Q: Warum sollte ich explizite Links nutzen statt validierte?
A: Explizite Links haben:

• ✅ Sofortige Übernahme (keine Wartezeit)
• ✅ Höchste Priorität (werden immer beibehalten)
• ✅ Keine Validierungs-Kosten (keine LLM-Aufrufe)
• ✅ Höhere Confidence-Werte

Nutze validierte Links nur, wenn du unsicher bist, ob die Verbindung wirklich passt.

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

Zusammenfassung (WP-24c v4.5.8)

• ✅ Explizite Links: [[rel:kind|target]], > [!edge] oder ## Smart Edges → Keine Validierung, höchste Priorität
• ✅ Validierte Links: Sektion ### Unzugeordnete Kanten → Phase 3 Validierung mit candidate: Präfix
• ✅ Phase 3 Validierung: LLM prüft semantisch mit Kontext-Optimierung (Note-Scope vs. Chunk-Scope)
• ✅ Ergebnis: VERIFIED (Präfix entfernt, persistiert) oder REJECTED (nicht in DB geschrieben)
• ✅ Format: kind:target (eine pro Zeile in ### Unzugeordnete Kanten)
• ✅ Automatische Spiegelkanten: Explizite Kanten erzeugen automatisch Invers-Kanten (beide Richtungen durchsuchbar)