# 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
```markdown
[[rel:mastered_by|Klaus]]
[[rel:depends_on|Projekt Alpha]]
```

### 2. Standard Wikilinks
```markdown
[[Klaus]]
[[Projekt Alpha]]
```

### 3. Callouts
```markdown
> [!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:

```markdown
---
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

```markdown
---
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`:**

```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:**
   ```markdown
   Diese Entscheidung [[rel:depends_on|Performance-Analyse]] wurde getroffen.
   ```

2. **Global Pool für unsichere/explorative Links:**
   ```markdown
   ### Unzugeordnete Kanten
   related_to:Mögliche Verbindung
   ```

3. **Kombination beider Ansätze:**
   ```markdown
   # 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`:

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

### Schritt 2: Notiz erstellen

```markdown
---
type: your_type
title: Meine Notiz
---

# Inhalt

### Unzugeordnete Kanten

related_to:Ziel-Notiz
```

### Schritt 3: Import ausführen

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