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

+123 -5
View File
@@ -1,10 +1,10 @@
---
doc_type: concept
audience: architect, product_owner
scope: graph, logic, provenance
scope: graph, logic, provenance, agentic_validation, note_scope
status: active
version: 2.9.1
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support und WP-22 Scoring-Prinzipien."
version: 4.5.8
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support, WP-22 Scoring-Prinzipien, WP-24c Phase 3 Agentic Edge Validation und automatische Spiegelkanten."
---
# Konzept: Die Graph-Logik
@@ -156,9 +156,127 @@ Die Deduplizierung basiert auf dem `src->tgt:kind@sec` Key, um sicherzustellen,
---
## 7. Idempotenz & Konsistenz
## 7. Automatische Spiegelkanten (Invers-Logik) - WP-24c v4.5.8
Das System erzeugt automatisch **Spiegelkanten** (Invers-Kanten) für explizite Verbindungen, um die Auffindbarkeit von Informationen zu verdoppeln.
### 7.1 Funktionsweise
**Beispiel:**
- **Explizite Kante:** Note A `depends_on: Note B`
- **Automatische Spiegelkante:** Note B `enforced_by: Note A`
**Vorteil:** Beide Richtungen sind durchsuchbar. Wenn du nach "Note B" suchst, findest du auch alle Notizen, die von "Note B" abhängen (via `enforced_by`).
### 7.2 Invers-Mapping
Die Edge Registry definiert für jeden Kanten-Typ das symmetrische Gegenstück:
- `depends_on` ↔ `enforced_by`
- `derived_from` ↔ `resulted_in`
- `impacts` ↔ `impacted_by`
- `blocks` ↔ `blocked_by`
- `next` ↔ `prev`
- `related_to` ↔ `related_to` (symmetrisch)
### 7.3 Priorität & Schutz
* **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 Confidence-Werte (`confidence: 1.0`) als automatisch generierte Spiegelkanten (`confidence: 0.9 * original`)
* **Provenance Firewall:** System-Kanten (`belongs_to`, `next`, `prev`) können nicht manuell überschrieben werden
### 7.4 Phase 2 Symmetrie-Injektion
Spiegelkanten werden am Ende des gesamten Imports (Phase 2) in einem Batch-Prozess injiziert:
- **Authority-Check:** Nur wenn keine explizite Kante existiert, wird die Spiegelkante erzeugt
- **ID-Konsistenz:** Verwendet exakt dieselbe ID-Generierung wie Phase 1 (inkl. `target_section`)
- **Logging:** `🔄 [SYMMETRY]` zeigt die erzeugten Spiegelkanten
---
## 8. Phase 3 Agentic Edge Validation - WP-24c v4.5.8
Das System implementiert ein finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix, um "Geister-Verknüpfungen" zu verhindern und die Graph-Qualität zu sichern.
### 8.1 Trigger-Kriterium
Kanten erhalten `candidate:` Präfix, wenn sie:
- In `### Unzugeordnete Kanten` Sektionen stehen
- Von der Smart Edge Allocation als Kandidaten vorgeschlagen wurden
- Explizit als `candidate:` markiert wurden
### 8.2 Validierungsprozess
1. **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
2. **LLM-Validierung:**
- Nutzt `ingest_validator` Profil (Temperature 0.0 für Determinismus)
- Prüft semantisch: "Passt diese Verbindung zum Kontext?"
- Binäre Entscheidung: YES (VERIFIED) oder NO (REJECTED)
3. **Ergebnis:**
- **VERIFIED:** `candidate:` Präfix wird entfernt, Kante wird persistiert
- **REJECTED:** Kante wird **nicht** in die Datenbank geschrieben (verhindert persistente "Geister-Verknüpfungen")
### 8.3 Fehlertoleranz
Das System unterscheidet zwischen:
- **Transienten Fehlern (Netzwerk, Timeout):** Kante wird erlaubt (Integrität vor Präzision)
- **Permanenten Fehlern (Config, Validation):** Kante wird abgelehnt (Graph-Qualität schützen)
### 8.4 Provenance nach Validierung
- **Vor Validierung:** `provenance: "candidate:global_pool"` oder `rule_id: "candidate:..."`
- **Nach VERIFIED:** `provenance: "global_pool"` oder `rule_id: "explicit"` (Präfix entfernt)
- **Nach REJECTED:** Kante existiert nicht im Graph (wird nicht persistiert)
---
## 9. Note-Scope vs. Chunk-Scope - WP-24c v4.2.0
Das System unterscheidet zwischen **Note-Scope** (globale Verbindungen) und **Chunk-Scope** (lokale Referenzen).
### 9.1 Chunk-Scope (Standard)
- **Quelle:** `source_id = chunk_id` (z.B. `note-id#c00`)
- **Kontext:** Spezifischer Textabschnitt (Chunk)
- **Verwendung:** Lokale Referenzen innerhalb eines Abschnitts
- **Phase 3 Validierung:** Nutzt spezifischen Chunk-Text
**Beispiel:**
```markdown
In diesem Abschnitt nutzen wir [[rel:uses|Technologie X]].
```
### 9.2 Note-Scope
- **Quelle:** `source_id = note_id` (nicht `chunk_id`)
- **Kontext:** Gesamte Note (Note-Summary oder Note-Text)
- **Verwendung:** Globale Verbindungen, die für die ganze Note gelten
- **Phase 3 Validierung:** Nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext)
**Beispiel:**
```markdown
## Smart Edges
[[rel:depends_on|Projekt-Übersicht]]
[[rel:part_of|Größeres System]]
```
### 9.3 Priorität
Bei Duplikaten (gleiche Kante in Chunk-Scope und Note-Scope):
1. **Note-Scope Links** haben **höchste Priorität**
2. Dann Confidence-Wert
3. Dann Provenance-Priority
---
## 10. Idempotenz & Konsistenz
Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports.
* **Deduplizierung:** Kanten werden anhand ihrer Identität (inkl. Section) erkannt. Die "stärkere" Provenance gewinnt.
* **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden.
* **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden.
* **Phase 3 Validierung:** Verhindert persistente "Geister-Verknüpfungen" durch Ablehnung irrelevanter Kanten.