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

## 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:

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

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

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)