diff --git a/docs/99_Archive/WP24c_merge_commit.md b/docs/99_Archive/WP24c_merge_commit.md new file mode 100644 index 0000000..471fd8f --- /dev/null +++ b/docs/99_Archive/WP24c_merge_commit.md @@ -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 diff --git a/docs/99_Archive/WP24c_release_notes.md b/docs/99_Archive/WP24c_release_notes.md new file mode 100644 index 0000000..4d73a76 --- /dev/null +++ b/docs/99_Archive/WP24c_release_notes.md @@ -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).