Implement Phase 3 Agentic Edge Validation in ingestion_processor.py and related documentation updates

Introduce a new method for persisting rejected edges for audit purposes, enhancing traceability and validation logic. Update the decision engine to utilize a generic fallback template for improved error handling during LLM validation. Revise documentation across multiple files to reflect the new versioning, context, and features related to Phase 3 validation, including automatic mirror edges and note-scope zones. This update ensures better graph integrity and validation accuracy in the ingestion process.
This commit is contained in:
Lars committed 2026-01-12 07:45:54 +01:00
1 parent b19f91c3ee
commit 742792770c
18 files changed
+1110 -119

No files matched your search

+6 -4
View File
@@ -1,10 +1,10 @@
---
doc_type: user_manual
audience: user, mindmaster
scope: chat, ui, feedback, graph
scope: chat, ui, feedback, graph, agentic_validation
status: active
version: 2.9.3
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers."
version: 4.5.8
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers. Inkludiert WP-24c Chunk-Aware Multigraph-System und automatische Spiegelkanten."
---
# Chat & Graph Usage Guide
@@ -17,11 +17,13 @@ context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-St
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert.
**Das Gedächtnis (Der Graph):**
**Das Gedächtnis (Der Graph - Chunk-Aware Multigraph):**
Wenn du nach "Projekt Alpha" suchst, findet Mindnet auch:
* **Abhängigkeiten:** "Technologie X wird benötigt".
* **Entscheidungen:** "Warum nutzen wir X?".
* **Ähnliches:** "Projekt Beta war ähnlich".
* **Beide Richtungen:** Dank automatischer Spiegelkanten findest du auch Notizen, die auf "Projekt Alpha" verweisen (z.B. "Projekt Beta enforced_by: Projekt Alpha").
* **Präzise Abschnitte:** Deep-Links zu spezifischen Abschnitten (`[[Note#Section]]`) ermöglichen präzise Verknüpfungen innerhalb langer Dokumente.
**Der Zwilling (Die Personas):**
Mindnet passt seinen Charakter an: Mal ist es der neutrale Bibliothekar, mal der strategische Berater, mal der empathische Spiegel.
+116 -8
View File
@@ -1,10 +1,10 @@
---
doc_type: user_manual
audience: user, author
scope: vault, markdown, schema
scope: vault, markdown, schema, agentic_validation, note_scope
status: active
version: 2.9.1
context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren."
version: 4.5.8
context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren. Inkludiert WP-24c Phase 3 Agentic Edge Validation, automatische Spiegelkanten und Note-Scope Zonen."
---
# Knowledge Design Manual
@@ -238,8 +238,14 @@ Callout-Blocks mit mehreren Zeilen werden korrekt verarbeitet. Das System erkenn
**Format-agnostische De-Duplizierung:**
Wenn Kanten bereits via `[!edge]` Callout vorhanden sind, werden sie nicht mehrfach injiziert. Das System erkennt vorhandene Kanten unabhängig vom Format (Inline, Callout, Wikilink).
### 4.3 Implizite Bidirektionalität (Edger-Logik) [NEU] [PRÜFEN!]
In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Der **Edger** übernimmt die Paarbildung automatisch im Hintergrund.
### 4.3 Automatische Spiegelkanten (Invers-Logik) - WP-24c v4.5.8
In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Das System erzeugt automatisch **Spiegelkanten** (Invers-Kanten) im Hintergrund.
**Wie es funktioniert:**
1. **Du setzt eine explizite Kante:** Z.B. `[[rel:depends_on Projekt Alpha]]` in Note A
2. **System erzeugt automatisch die Spiegelkante:** Note "Projekt Alpha" erhält automatisch `enforced_by: Note A`
3. **Vorteil:** Beide Richtungen sind durchsuchbar, ohne dass du beide manuell setzen musst
**Deine Aufgabe:** Setze die Kante in der Datei, die du gerade bearbeitest, so wie es der **logische Fluss** vorgibt.
@@ -247,10 +253,112 @@ In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Der **
* **Blick nach vorn (Vorwärtslink):** Wenn du einen Plan oder ein Protokoll schreibst, nutze `resulted_in`, `supports` oder `next`.
**System-Logik (Beispiele):**
- Schreibst du in Note A: `next: [[B]]`, weiß das System automatisch: `B prev A`.
- Schreibst du in Note B: `derived_from: [[A]]`, weiß das System automatisch: `A resulted_in B`.
- Schreibst du in Note A: `[[rel:next Projekt B]]`, erzeugt das System automatisch: `Projekt B prev: Note A`
- Schreibst du in Note B: `[[rel:derived_from Note A]]`, erzeugt das System automatisch: `Note A resulted_in: Note B`
- Schreibst du in Note A: `[[rel:impacts Projekt B]]`, erzeugt das System automatisch: `Projekt B impacted_by: Note A`
**Vorteil:** Keine redundante Datenpflege, kein "Link-Nightmare", volle Konsistenz im Graphen.
**Wichtig:**
- **Explizite Kanten haben Vorrang:** Wenn du bereits beide Richtungen explizit gesetzt hast, wird keine automatische Spiegelkante erzeugt (keine Duplikate)
- **Höhere Wirksamkeit expliziter Kanten:** Explizit gesetzte Kanten haben höhere Priorität und Confidence-Werte als automatisch generierte Spiegelkanten
- **Schutz vor Manipulation:** System-Kanten (`belongs_to`, `next`, `prev`) können nicht manuell überschrieben werden (Provenance Firewall)
**Vorteil:** Keine redundante Datenpflege, kein "Link-Nightmare", volle Konsistenz im Graphen. Beide Richtungen sind durchsuchbar, was die Auffindbarkeit von Informationen verdoppelt.
### 4.4 Explizite vs. Validierte Kanten (Phase 3 Validierung) - WP-24c v4.5.8
Mindnet unterscheidet zwischen **expliziten Kanten** (sofort übernommen) und **validierten Kanten** (Phase 3 LLM-Prüfung).
#### Explizite Kanten (Höchste Priorität)
Diese Kanten werden **sofort** in den Graph übernommen, ohne LLM-Validierung:
1. **Typed Relations im Text:**
```markdown
Diese Entscheidung [[rel:depends_on Performance-Analyse]] wurde getroffen.
```
2. **Callout-Edges:**
```markdown
> [!edge] depends_on
> [[Performance-Analyse]]
> [[Projekt Alpha]]
```
3. **Note-Scope Zonen:**
```markdown
## Smart Edges
[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
```
*(Siehe auch: [Note-Scope Zonen](NOTE_SCOPE_ZONEN.md))*
**Vorteil expliziter Kanten:**
- ✅ **Sofortige Übernahme:** Keine Wartezeit auf LLM-Validierung
- ✅ **Höchste Priorität:** Werden immer beibehalten, auch bei Duplikaten
- ✅ **Höhere Confidence:** Explizite Kanten haben `confidence: 1.0` (maximal)
- ✅ **Keine Validierungs-Kosten:** Keine LLM-Aufrufe erforderlich
#### Validierte Kanten (Phase 3 - candidate: Präfix)
Kanten, die in speziellen Validierungs-Zonen stehen, erhalten das `candidate:` Präfix und werden in **Phase 3** durch ein LLM semantisch geprüft:
**Format:**
```markdown
### Unzugeordnete Kanten
related_to:Mögliche Verbindung
depends_on:Unsicherer Link
uses:Experimentelle Technologie
```
**Validierungsprozess:**
1. **Extraktion:** Links aus `### Unzugeordnete Kanten` erhalten `candidate:` Präfix
2. **Phase 3 Validierung:** LLM prüft semantisch: "Passt diese Verbindung zum Kontext?"
3. **Erfolg (VERIFIED):** `candidate:` Präfix wird entfernt, Kante wird persistiert
4. **Ablehnung (REJECTED):** Kante wird **nicht** in die Datenbank geschrieben
**Kontext-Optimierung:**
- **Note-Scope Kanten:** LLM nutzt Note-Summary oder gesamten Note-Text (besser für globale Verbindungen)
- **Chunk-Scope Kanten:** LLM nutzt spezifischen Chunk-Text (besser für lokale Referenzen)
**Wann nutze ich validierte Kanten?**
- ✅ **Explorative Verbindungen:** Du bist unsicher, ob die Verbindung wirklich passt
- ✅ **Experimentelle Links:** Du willst testen, ob eine Verbindung semantisch Sinn macht
- ✅ **Automatische Vorschläge:** Das System hat Links vorgeschlagen, die du prüfen lassen willst
**Wann nutze ich explizite Kanten?**
- ✅ **Sichere Verbindungen:** Du bist dir sicher, dass die Verbindung korrekt ist
- ✅ **Schnelle Übernahme:** Du willst keine Wartezeit auf Validierung
- ✅ **Höchste Priorität:** Die Verbindung soll definitiv im Graph sein
*(Siehe auch: [LLM-Validierung von Links](LLM_VALIDIERUNG_VON_LINKS.md))*
### 4.5 Note-Scope Zonen (Globale Verbindungen) - WP-24c v4.2.0
Für Verbindungen, die der **gesamten Note** zugeordnet werden sollen (nicht nur einem spezifischen Chunk), nutze **Note-Scope Zonen**:
```markdown
## Smart Edges
[[rel:depends_on|Projekt-Übersicht]]
[[rel:part_of|Größeres System]]
```
**Vorteile:**
- ✅ **Globale Verbindungen:** Links gelten für die gesamte Note, nicht nur einen Abschnitt
- ✅ **Höchste Priorität:** Note-Scope Links haben Vorrang bei Duplikaten
- ✅ **Bessere Validierung:** In Phase 3 nutzt das LLM den gesamten Note-Kontext (Note-Summary/Text)
**Wann nutze ich Note-Scope?**
- ✅ **Projekt-Abhängigkeiten:** "Dieses Projekt hängt von X ab" (gilt für die ganze Note)
- ✅ **System-Zugehörigkeit:** "Dieses Konzept ist Teil von Y" (gilt für die ganze Note)
- ✅ **Globale Prinzipien:** "Diese Entscheidung basiert auf Prinzip Z" (gilt für die ganze Note)
**Wann nutze ich Chunk-Scope (Standard)?**
- ✅ **Lokale Referenzen:** "In diesem Abschnitt nutzen wir Technologie X" (nur für diesen Abschnitt)
- ✅ **Spezifische Kontexte:** Links, die nur in einem bestimmten Textabschnitt relevant sind
*(Siehe auch: [Note-Scope Zonen - Detaillierte Anleitung](NOTE_SCOPE_ZONEN.md))*
---
@@ -1,7 +1,8 @@
# LLM-Validierung von Links in Notizen
# LLM-Validierung von Links in Notizen (Phase 3 Agentic Edge Validation)
**Version:** v4.1.0
**Status:** Aktiv
**Version:** v4.5.8
**Status:** Aktiv
**Aktualisiert:** WP-24c Phase 3 Agentic Edge Validation mit Kontext-Optimierung
## Übersicht
@@ -34,9 +35,9 @@ Diese Links werden **sofort** in den Graph übernommen, ohne LLM-Validierung:
**Hinweis:** Explizite Links haben immer Vorrang und werden nicht validiert.
## Global Pool Links (mit LLM-Validierung)
## 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.
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
@@ -105,16 +106,19 @@ types:
enable_smart_edge_allocation: true # ← Aktiviert LLM-Validierung
```
### Validierungsprozess
### Phase 3 Validierungsprozess (WP-24c v4.5.8)
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?
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?
4. **Ergebnis:**
- ✅ **YES** → Link wird in den Graph übernommen
- ❌ **NO** → Link wird verworfen
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
@@ -201,29 +205,36 @@ related_to:Ziel-Notiz
python3 -m scripts.import_markdown --vault ./vault --apply
```
## Logging & Debugging
## 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)...
✅ [VALIDATED] Relation to 'Ziel-Notiz' confirmed.
✅ [PHASE 3] VERIFIED: Note-A -> Ziel-Notiz (related_to) | rule_id: explicit
```
oder
```
🚫 [REJECTED] Relation to 'Ziel-Notiz' irrelevant for this chunk.
🚀 [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
### Provenance-System (WP-24c v4.5.8)
- `explicit`: Explizite Links (keine Validierung)
- `global_pool`: Global Pool Links (mit Validierung)
- `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
@@ -240,14 +251,32 @@ A: Nein, explizite Links werden direkt übernommen.
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.
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
## Zusammenfassung (WP-24c v4.5.8)
- ✅ **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)
- ✅ **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)
+42 -7
View File
@@ -1,7 +1,8 @@
# Note-Scope Extraktions-Zonen (v4.2.0)
# Note-Scope Extraktions-Zonen (v4.5.8)
**Version:** v4.2.0
**Status:** Aktiv
**Version:** v4.5.8
**Status:** Aktiv
**Aktualisiert:** WP-24c Phase 3 Agentic Edge Validation
## Übersicht
@@ -159,17 +160,44 @@ Bei Duplikaten (gleiche ID):
- Beschränken Sie sich auf wirklich Note-weite Verbindungen
- Zu viele Note-Scope Links können die Graph-Struktur verwässern
## Integration mit LLM-Validierung
## Integration mit Phase 3 Validierung (WP-24c v4.5.8)
Note-Scope Links können auch **LLM-validiert** werden, wenn sie in der Sektion `### Unzugeordnete Kanten` stehen:
Note-Scope Links können **zwei verschiedene Provenance** haben:
### Explizite Note-Scope Links (Keine Validierung)
Links in `## Smart Edges` Zonen werden als `explicit:note_zone` markiert und **direkt übernommen** (keine Phase 3 Validierung):
```markdown
## Smart Edges
[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
```
**Vorteil:** Sofortige Übernahme, höchste Priorität, keine Validierungs-Kosten.
### Validierte Note-Scope Links (Phase 3 Validierung)
Links in `### Unzugeordnete Kanten` erhalten `candidate:` Präfix und werden in **Phase 3** validiert:
```markdown
### Unzugeordnete Kanten
related_to:Mögliche Verbindung
depends_on:Unsicherer Link
```
**Wichtig:** Links in `### Unzugeordnete Kanten` werden als `global_pool` markiert und validiert. Links in `## Smart Edges` werden als `explicit:note_zone` markiert und **nicht** validiert (direkt übernommen).
**Validierungsprozess:**
1. Links erhalten `candidate:` Präfix
2. **Phase 3 Validierung:** LLM prüft semantisch gegen Note-Summary oder Note-Text (Note-Scope Kontext-Optimierung)
3. **Erfolg (VERIFIED):** `candidate:` Präfix wird entfernt, Kante wird persistiert
4. **Ablehnung (REJECTED):** Kante wird **nicht** in die Datenbank geschrieben
**Wichtig:**
- Links in `### Unzugeordnete Kanten` werden als `candidate:` markiert und durchlaufen Phase 3
- Links in `## Smart Edges` werden als `explicit:note_zone` markiert und **nicht** validiert (direkt übernommen)
- **Note-Scope Kontext-Optimierung:** Bei Note-Scope Kanten nutzt Phase 3 `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) für bessere Validierungs-Genauigkeit
## Beispiel: Vollständige Notiz
@@ -226,7 +254,14 @@ A: Ja, `[[rel:kind|Target#Section]]` wird unterstützt. `target_section` fließt
A: Der Note-Scope Link hat Vorrang und wird beibehalten.
**Q: Werden Note-Scope Links validiert?**
A: Nein, sie werden direkt übernommen (wie explizite Links). Für Validierung nutzen Sie `### Unzugeordnete Kanten`.
A: Das hängt von der Zone ab:
- **`## Smart Edges`:** Nein, werden direkt übernommen (explizite Links, keine Validierung)
- **`### Unzugeordnete Kanten`:** Ja, durchlaufen Phase 3 Validierung (candidate: Präfix)
**Q: Was ist der Unterschied zwischen Note-Scope in Smart Edges vs. Unzugeordnete Kanten?**
A:
- **Smart Edges:** Explizite Links, sofortige Übernahme, höchste Priorität
- **Unzugeordnete Kanten:** Validierte Links, Phase 3 Prüfung, candidate: Präfix
**Q: Kann ich eigene Header-Namen verwenden?**
A: Aktuell nur die vordefinierten Header. Erweiterung möglich durch Anpassung von `NOTE_SCOPE_ZONE_HEADERS`.