WP24c - Agentic Edge Validation & Chunk-Aware Multigraph-System (v4.5.8) #22

Merged
Lars merged 71 commits from WP24c into main 2026-01-12 10:53:20 +01:00
2 changed files with 520 additions and 0 deletions
Showing only changes of commit 1056078e6a - Show all commits

View File

@ -0,0 +1,113 @@
# Branch Merge Commit: WP-24c
**Branch:** `WP24c`
**Target:** `main`
**Version:** v4.5.8
**Date:** 2026-01-XX
---
## Commit Message
```
feat: Phase 3 Agentic Edge Validation & Chunk-Aware Multigraph-System (v4.5.8)
### Phase 3 Agentic Edge Validation
- Finales Validierungs-Gate für Kanten mit candidate: Präfix
- LLM-basierte semantische Prüfung gegen Kontext (Note-Scope vs. Chunk-Scope)
- Differenzierte Fehlerbehandlung: Transiente Fehler erlauben Kante, permanente Fehler lehnen ab
- Kontext-Optimierung: Note-Scope nutzt Note-Summary/Text, Chunk-Scope nutzt spezifischen Chunk-Text
- Implementierung in app/core/ingestion/ingestion_validation.py (v2.14.0)
### Automatische Spiegelkanten (Invers-Logik)
- Automatische Erzeugung von Spiegelkanten für explizite Verbindungen
- Phase 2 Batch-Injektion am Ende des Imports
- Authority-Check: Explizite Kanten haben Vorrang (keine Duplikate)
- Provenance Firewall: System-Kanten können nicht manuell überschrieben werden
- Implementierung in app/core/ingestion/ingestion_processor.py (v2.13.12)
### Note-Scope Zonen (v4.2.0)
- Globale Verbindungen für ganze Notizen (scope: note)
- Konfigurierbare Header-Namen via ENV-Variablen
- Höchste Priorität bei Duplikaten
- Phase 3 Validierung nutzt Note-Summary/Text für bessere Präzision
- Implementierung in app/core/graph/graph_derive_edges.py (v1.1.2)
### Chunk-Aware Multigraph-System
- Section-basierte Links: [[Note#Section]] wird präzise in target_id und target_section aufgeteilt
- Multigraph-Support: Mehrere Kanten zwischen denselben Knoten möglich (verschiedene Sections)
- Semantische Deduplizierung basierend auf src->tgt:kind@sec Key
- Metadaten-Persistenz: target_section, provenance, confidence bleiben erhalten
### Code-Komponenten
- app/core/ingestion/ingestion_validation.py: v2.14.0 (Phase 3 Validierung, Kontext-Optimierung)
- app/core/ingestion/ingestion_processor.py: v2.13.12 (Automatische Spiegelkanten, Authority-Check)
- app/core/graph/graph_derive_edges.py: v1.1.2 (Note-Scope Zonen, LLM-Validierung Zonen)
- app/core/chunking/chunking_processor.py: v2.13.0 (LLM-Validierung Zonen Erkennung)
- app/core/chunking/chunking_parser.py: v2.12.0 (Header-Level Erkennung, Zonen-Extraktion)
### Konfiguration
- Neue ENV-Variablen für konfigurierbare Header:
- MINDNET_LLM_VALIDATION_HEADERS (Default: "Unzugeordnete Kanten,Edge Pool,Candidates")
- MINDNET_LLM_VALIDATION_HEADER_LEVEL (Default: 3)
- MINDNET_NOTE_SCOPE_ZONE_HEADERS (Default: "Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen")
- MINDNET_NOTE_SCOPE_HEADER_LEVEL (Default: 2)
- config/llm_profiles.yaml: ingest_validator Profil für Phase 3 Validierung (Temperature 0.0)
- config/prompts.yaml: edge_validation Prompt für Phase 3 Validierung
### Dokumentation
- 01_knowledge_design.md: Automatische Spiegelkanten, Phase 3 Validierung, Note-Scope Zonen
- NOTE_SCOPE_ZONEN.md: Phase 3 Validierung integriert
- LLM_VALIDIERUNG_VON_LINKS.md: Phase 3 statt global_pool, Kontext-Optimierung
- 02_concept_graph_logic.md: Phase 3 Validierung, automatische Spiegelkanten, Note-Scope vs. Chunk-Scope
- 03_tech_data_model.md: candidate: Präfix, verified Status, virtual Flag, scope Feld
- 03_tech_configuration.md: Neue ENV-Variablen dokumentiert
- 04_admin_operations.md: Troubleshooting für Phase 3 Validierung und Note-Scope Links
- 05_testing_guide.md: WP-24c Test-Szenarien hinzugefügt
- 00_quality_checklist.md: WP-24c Features in Checkliste aufgenommen
- README.md: Version auf v4.5.8 aktualisiert, WP-24c Features verlinkt
### Breaking Changes
- Keine Breaking Changes für Endbenutzer
- Vollständige Rückwärtskompatibilität
- Bestehende Notizen funktionieren ohne Änderungen
### Migration
- Keine Migration erforderlich
- System funktioniert ohne Änderungen
- Optional: ENV-Variablen können für Custom-Header konfiguriert werden
---
**Status:** ✅ WP-24c ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).
```
---
## Zusammenfassung
Dieser Merge führt die **Phase 3 Agentic Edge Validation** und das **Chunk-Aware Multigraph-System** in MindNet ein. Das System validiert nun automatisch Kanten mit `candidate:` Präfix, erzeugt automatisch Spiegelkanten für explizite Verbindungen und unterstützt Note-Scope Zonen für globale Verbindungen.
**Kern-Features:**
- Phase 3 Agentic Edge Validation (finales Validierungs-Gate)
- Automatische Spiegelkanten (Invers-Logik)
- Note-Scope Zonen (globale Verbindungen)
- Chunk-Aware Multigraph-System (Section-basierte Links)
**Technische Integrität:**
- Alle Kanten durchlaufen Phase 3 Validierung (falls candidate: Präfix)
- Spiegelkanten werden automatisch erzeugt (Phase 2)
- Note-Scope Links haben höchste Priorität
- Kontext-Optimierung für bessere Validierungs-Genauigkeit
**Dokumentation:**
- Vollständige Aktualisierung aller relevanten Dokumente
- Neue ENV-Variablen dokumentiert
- Troubleshooting-Guide erweitert
- Test-Szenarien hinzugefügt
**Deployment:**
- Keine Breaking Changes
- Optional: ENV-Variablen für Custom-Header konfigurieren
- System funktioniert ohne Änderungen

View File

@ -0,0 +1,407 @@
# MindNet v4.5.8 - Release Notes: WP-24c
**Release Date:** 2026-01-XX
**Type:** Feature Release - Phase 3 Agentic Edge Validation & Chunk-Aware Multigraph-System
**Version:** 4.5.8 (WP-24c)
---
## 🎯 Überblick
Mit WP-24c wurde MindNet um ein **finales Validierungs-Gate (Phase 3 Agentic Edge Validation)** erweitert, das "Geister-Verknüpfungen" verhindert und die Graph-Qualität sichert. Zusätzlich wurde das System um **automatische Spiegelkanten (Invers-Logik)** und **Note-Scope Zonen** erweitert, die es ermöglichen, globale Verbindungen für ganze Notizen zu definieren.
Diese Version markiert einen wichtigen Schritt zur **Graph-Integrität**: Von manueller Kanten-Pflege hin zu automatischer Validierung und bidirektionaler Durchsuchbarkeit.
---
## ✨ Neue Features
### 1. Phase 3 Agentic Edge Validation
**Implementierung (`app/core/ingestion/ingestion_validation.py` v2.14.0):**
Finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix:
* **Trigger-Kriterium:** Kanten in `### Unzugeordnete Kanten` Sektionen erhalten `candidate:` Präfix
* **Validierungsprozess:** LLM prüft semantisch, ob die Verbindung zum Kontext passt
* **Ergebnis:** VERIFIED (Präfix entfernt, persistiert) oder REJECTED (nicht in DB geschrieben)
* **Kontext-Optimierung:** Note-Scope nutzt Note-Summary/Text, Chunk-Scope nutzt spezifischen Chunk-Text
**Vorteile:**
* **Graph-Qualität:** Verhindert persistente "Geister-Verknüpfungen"
* **Präzision:** Höhere Validierungs-Genauigkeit durch Kontext-Optimierung
* **Fehlertoleranz:** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern
### 2. Automatische Spiegelkanten (Invers-Logik)
**Implementierung (`app/core/ingestion/ingestion_processor.py` v2.13.12):**
Automatische Erzeugung von Spiegelkanten für explizite Verbindungen:
* **Funktionsweise:** Explizite Kante `A depends_on: B` erzeugt automatisch `B enforced_by: A`
* **Priorität:** Explizite Kanten haben Vorrang (keine Duplikate)
* **Schutz:** System-Kanten (`belongs_to`, `next`, `prev`) können nicht manuell überschrieben werden
* **Phase 2 Injektion:** Spiegelkanten werden am Ende des Imports in einem Batch-Prozess injiziert
**Vorteile:**
* **Bidirektionale Durchsuchbarkeit:** Beide Richtungen sind durchsuchbar ohne manuelle Pflege
* **Konsistenz:** Volle Graph-Konsistenz ohne "Link-Nightmare"
* **Höhere Wirksamkeit:** Explizite Kanten haben höhere Confidence-Werte als automatisch generierte
### 3. Note-Scope Zonen (v4.2.0)
**Implementierung (`app/core/graph/graph_derive_edges.py` v1.1.2):**
Globale Verbindungen für ganze Notizen:
* **Format:** Links in `## Smart Edges` Zonen werden als `scope: note` behandelt
* **Priorität:** Höchste Priorität bei Duplikaten
* **Phase 3 Validierung:** Nutzt Note-Summary (Top 5 Chunks) oder Note-Text für bessere Validierung
* **Konfigurierbar:** Header-Namen und -Ebene via ENV-Variablen
**Vorteile:**
* **Globale Verbindungen:** Links gelten für die gesamte Note, nicht nur einen Abschnitt
* **Bessere Validierung:** Note-Kontext ermöglicht präzisere LLM-Validierung
* **Flexibilität:** Konfigurierbare Header-Namen für verschiedene Workflows
### 4. Chunk-Aware Multigraph-System
**Erweiterung des bestehenden Multigraph-Systems:**
* **Section-basierte Links:** `[[Note#Section]]` wird präzise in `target_id` und `target_section` aufgeteilt
* **Multigraph-Support:** Mehrere Kanten zwischen denselben Knoten möglich, wenn sie auf verschiedene Sections zeigen
* **Semantische Deduplizierung:** Basierend auf `src->tgt:kind@sec` Key
**Vorteile:**
* **Präzision:** Präzise Verlinkung innerhalb langer Dokumente
* **Flexibilität:** Mehrere Verbindungen zur gleichen Note möglich
* **Konsistenz:** Verhindert "Phantom-Knoten"
---
## 🔧 Technische Änderungen
### Konfigurationsdateien
**`config/llm_profiles.yaml` (v1.3.0):**
* **Keine Änderungen:** Bestehende Profile bleiben unverändert
* **`ingest_validator` Profil:** Wird für Phase 3 Validierung genutzt (Temperature 0.0 für Determinismus)
**`config/prompts.yaml` (v3.2.2):**
* **Keine Änderungen:** Bestehende Prompts bleiben unverändert
* **`edge_validation` Prompt:** Wird für Phase 3 Validierung genutzt
### Environment Variablen (`.env`)
**Neue Variablen für WP-24c:**
```env
# --- WP-24c v4.2.0: Konfigurierbare Markdown-Header für Edge-Zonen ---
# Komma-separierte Liste von Headern für LLM-Validierung
# Format: Header1,Header2,Header3
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
# Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###)
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
# Komma-separierte Liste von Headern für Note-Scope Zonen
# Format: Header1,Header2,Header3
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
# Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##)
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
```
**Default-Werte:**
* `MINDNET_LLM_VALIDATION_HEADERS`: `Unzugeordnete Kanten,Edge Pool,Candidates`
* `MINDNET_LLM_VALIDATION_HEADER_LEVEL`: `3` (für `###`)
* `MINDNET_NOTE_SCOPE_ZONE_HEADERS`: `Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen`
* `MINDNET_NOTE_SCOPE_HEADER_LEVEL`: `2` (für `##`)
**Hinweis:** Falls diese Variablen nicht gesetzt sind, werden die Default-Werte verwendet. Das System funktioniert ohne explizite Konfiguration.
### Code-Komponenten
**Neue/Erweiterte Module:**
* `app/core/ingestion/ingestion_validation.py`: v2.14.0
* Phase 3 Validierung mit Kontext-Optimierung
* Differenzierte Fehlerbehandlung (transient vs. permanent)
* Lazy-Prompt-Orchestration Integration
* `app/core/ingestion/ingestion_processor.py`: v2.13.12
* Automatische Spiegelkanten-Generierung (Phase 2)
* Authority-Check für explizite Kanten
* ID-Konsistenz mit Phase 1
* `app/core/graph/graph_derive_edges.py`: v1.1.2
* Note-Scope Zonen Extraktion
* LLM-Validierung Zonen Extraktion
* Konfigurierbare Header-Erkennung
* `app/core/chunking/chunking_processor.py`: v2.13.0
* LLM-Validierung Zonen Erkennung
* candidate: Präfix-Setzung
* `app/core/chunking/chunking_parser.py`: v2.12.0
* Header-Level Erkennung
* Zonen-Extraktion
---
## 📋 Migration Guide
### Für Endbenutzer
**Keine Migration erforderlich!** Das System funktioniert ohne Änderungen.
**Optionale Nutzung neuer Features:**
1. **Explizite Links (empfohlen):**
```markdown
Diese Entscheidung [[rel:depends_on Performance-Analyse]] wurde getroffen.
```
* Sofortige Übernahme, höchste Priorität, keine Validierung
2. **Validierte Links (für explorative Verbindungen):**
```markdown
### Unzugeordnete Kanten
related_to:Mögliche Verbindung
depends_on:Unsicherer Link
```
* Phase 3 Validierung, kann abgelehnt werden
3. **Note-Scope Links (für globale Verbindungen):**
```markdown
## Smart Edges
[[rel:depends_on|Projekt-Übersicht]]
[[rel:part_of|Größeres System]]
```
* Globale Verbindung für ganze Note, höchste Priorität
### Für Administratoren
**1. Environment Variablen hinzufügen (optional):**
Fügen Sie die folgenden Zeilen zu Ihrer `.env` oder `config/prod.env` hinzu:
```env
# --- WP-24c v4.2.0: Konfigurierbare Markdown-Header für Edge-Zonen ---
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
```
**Hinweis:** Falls diese Variablen nicht gesetzt sind, werden die Default-Werte verwendet. Das System funktioniert ohne explizite Konfiguration.
**2. LLM-Profil prüfen:**
Stellen Sie sicher, dass das `ingest_validator` Profil in `config/llm_profiles.yaml` existiert:
```yaml
ingest_validator:
provider: ollama
model: phi3:mini
temperature: 0.0
fallback_profile: null
```
**3. Prompt prüfen:**
Stellen Sie sicher, dass der `edge_validation` Prompt in `config/prompts.yaml` existiert.
**4. System neu starten:**
Nach dem Hinzufügen der ENV-Variablen:
```bash
systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod
```
### Für Entwickler
**Keine Code-Änderungen erforderlich!** Die neuen Features sind vollständig rückwärtskompatibel.
**Optionale Integration:**
* **Phase 3 Validierung:** Nutzen Sie `validate_edge_candidate()` aus `ingestion_validation.py`
* **Note-Scope Zonen:** Nutzen Sie `extract_note_scope_zones()` aus `graph_derive_edges.py`
* **Spiegelkanten:** Werden automatisch erzeugt, keine manuelle Integration erforderlich
---
## 🚀 Deployment-Anweisungen
### Pre-Deployment Checkliste
- [ ] **Backup:** Vollständiges Backup von Qdrant und Vault durchführen
- [ ] **ENV-Variablen:** Neue ENV-Variablen zu `.env` hinzufügen (optional)
- [ ] **LLM-Profil:** `ingest_validator` Profil in `llm_profiles.yaml` prüfen
- [ ] **Prompt:** `edge_validation` Prompt in `prompts.yaml` prüfen
- [ ] **Dependencies:** `requirements.txt` aktualisieren (falls neue Abhängigkeiten)
- [ ] **Tests:** Unit Tests und Integration Tests ausführen
### Deployment-Schritte
**1. Code aktualisieren:**
```bash
git pull origin main
# oder
git checkout WP24c
git merge main
```
**2. Dependencies aktualisieren:**
```bash
source .venv/bin/activate
pip install -r requirements.txt
```
**3. ENV-Variablen konfigurieren (optional):**
```bash
# Fügen Sie die neuen Variablen zu .env hinzu
nano .env
# oder
nano config/prod.env
```
**4. Services neu starten:**
```bash
systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod
```
**5. Health Check:**
```bash
curl http://localhost:8001/healthz
curl http://localhost:8501/healthz
```
**6. Logs prüfen:**
```bash
journalctl -u mindnet-prod -n 50 --no-pager
journalctl -u mindnet-ui-prod -n 50 --no-pager
```
### Post-Deployment Validierung
**1. Phase 3 Validierung testen:**
Erstellen Sie eine Test-Notiz mit `### Unzugeordnete Kanten`:
```markdown
---
type: concept
title: Test-Notiz
---
# Test-Notiz
Hier ist der Inhalt...
### Unzugeordnete Kanten
related_to:Test-Ziel
```
**Erwartetes Verhalten:**
* Log zeigt `🚀 [PHASE 3] Validierung: ...`
* Log zeigt `✅ [PHASE 3] VERIFIED:` oder `🚫 [PHASE 3] REJECTED:`
* Kante wird nur bei VERIFIED persistiert
**2. Note-Scope Zonen testen:**
Erstellen Sie eine Test-Notiz mit `## Smart Edges`:
```markdown
---
type: decision
title: Test-Entscheidung
---
# Test-Entscheidung
Hier ist der Inhalt...
## Smart Edges
[[rel:depends_on|Test-Projekt]]
```
**Erwartetes Verhalten:**
* Link wird als `scope: note` behandelt
* `provenance: explicit:note_zone`
* Höchste Priorität bei Duplikaten
**3. Automatische Spiegelkanten testen:**
Erstellen Sie eine explizite Kante:
```markdown
[[rel:depends_on Projekt Alpha]]
```
**Erwartetes Verhalten:**
* Log zeigt `🔄 [SYMMETRY] Add inverse: ...`
* Beide Richtungen sind durchsuchbar
* Explizite Kante hat höhere Priorität
---
## 🐛 Bekannte Probleme & Einschränkungen
**Keine bekannten Probleme.**
**Hinweise:**
* **Phase 3 Validierung:** Erfordert LLM-Verfügbarkeit. Bei transienten Fehlern wird die Kante erlaubt (Datenintegrität vor Präzision).
* **Spiegelkanten:** Werden nur für explizite Kanten erzeugt. Validierte Kanten erhalten keine Spiegelkanten, bis sie VERIFIED sind.
* **Note-Scope:** Header-Namen müssen exakt (case-insensitive) übereinstimmen.
---
## 📚 Dokumentation
**Aktualisierte Dokumente:**
* `docs/01_User_Manual/01_knowledge_design.md` - Automatische Spiegelkanten, Phase 3 Validierung, Note-Scope Zonen
* `docs/01_User_Manual/NOTE_SCOPE_ZONEN.md` - Phase 3 Validierung integriert
* `docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md` - Phase 3 statt global_pool
* `docs/02_concepts/02_concept_graph_logic.md` - Phase 3 Validierung, automatische Spiegelkanten, Note-Scope vs. Chunk-Scope
* `docs/03_Technical_References/03_tech_data_model.md` - candidate: Präfix, verified Status, virtual Flag
* `docs/03_Technical_References/03_tech_configuration.md` - Neue ENV-Variablen dokumentiert
* `docs/04_Operations/04_admin_operations.md` - Troubleshooting für Phase 3 Validierung
* `docs/05_Development/05_testing_guide.md` - WP-24c Test-Szenarien
**Neue Dokumente:**
* Keine neuen Dokumente (alle Features in bestehenden Dokumenten integriert)
---
## ✅ Breaking Changes
**Keine Breaking Changes!**
Das System ist vollständig rückwärtskompatibel. Bestehende Notizen funktionieren ohne Änderungen.
---
## 🎉 Danksagungen
Diese Version wurde entwickelt, um die Graph-Integrität zu sichern und die Benutzerfreundlichkeit durch automatische Spiegelkanten zu verbessern.
---
**Status:** ✅ WP-24c ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).