diff --git a/app/core/ingestion/ingestion_processor.py b/app/core/ingestion/ingestion_processor.py index a583f54..d3c40f4 100644 --- a/app/core/ingestion/ingestion_processor.py +++ b/app/core/ingestion/ingestion_processor.py @@ -91,6 +91,55 @@ class IngestionService: except Exception as e: logger.warning(f"DB initialization warning: {e}") + def _persist_rejected_edges(self, note_id: str, rejected_edges: List[Dict[str, Any]]) -> None: + """ + WP-24c v4.5.9: Persistiert abgelehnte Kanten für Audit-Zwecke. + + Schreibt rejected_edges in eine JSONL-Datei im _system Ordner oder logs/rejected_edges.log. + Dies ermöglicht die Analyse der Ablehnungsgründe und Verbesserung der Validierungs-Logik. + + Args: + note_id: ID der Note, zu der die abgelehnten Kanten gehören + rejected_edges: Liste von abgelehnten Edge-Dicts + """ + if not rejected_edges: + return + + import json + import os + from datetime import datetime + + # WP-24c v4.5.9: Erstelle Log-Verzeichnis falls nicht vorhanden + log_dir = "logs" + if not os.path.exists(log_dir): + os.makedirs(log_dir) + + log_file = os.path.join(log_dir, "rejected_edges.log") + + # WP-24c v4.5.9: Schreibe als JSONL (eine Kante pro Zeile) + try: + with open(log_file, "a", encoding="utf-8") as f: + for edge in rejected_edges: + log_entry = { + "timestamp": datetime.now().isoformat(), + "note_id": note_id, + "edge": { + "kind": edge.get("kind", "unknown"), + "source_id": edge.get("source_id", "unknown"), + "target_id": edge.get("target_id") or edge.get("to", "unknown"), + "scope": edge.get("scope", "unknown"), + "provenance": edge.get("provenance", "unknown"), + "rule_id": edge.get("rule_id", "unknown"), + "confidence": edge.get("confidence", 0.0), + "target_section": edge.get("target_section") + } + } + f.write(json.dumps(log_entry, ensure_ascii=False) + "\n") + + logger.debug(f"📝 [AUDIT] {len(rejected_edges)} abgelehnte Kanten für '{note_id}' in {log_file} gespeichert") + except Exception as e: + logger.error(f"❌ [AUDIT] Fehler beim Speichern der rejected_edges: {e}") + def _is_valid_id(self, text: Optional[str]) -> bool: """WP-24c: Prüft IDs auf fachliche Validität (Ghost-ID Schutz).""" if not text or not isinstance(text, str) or len(text.strip()) < 2: @@ -367,8 +416,10 @@ class IngestionService: validated_edges.append(e) # WP-24c v4.5.8: Phase 3 abgeschlossen - rejected_edges werden NICHT weiterverarbeitet + # WP-24c v4.5.9: Persistierung von rejected_edges für Audit-Zwecke if rejected_edges: logger.info(f"🚫 [PHASE 3] {len(rejected_edges)} Kanten abgelehnt und werden nicht in die DB geschrieben") + self._persist_rejected_edges(note_id, rejected_edges) # WP-24c v4.5.8: Verwende validated_edges statt raw_edges für weitere Verarbeitung # Nur verified Kanten (ohne candidate: Präfix) werden in Phase 2 (Symmetrie) verarbeitet diff --git a/app/core/retrieval/decision_engine.py b/app/core/retrieval/decision_engine.py index ee9c6a0..363d438 100644 --- a/app/core/retrieval/decision_engine.py +++ b/app/core/retrieval/decision_engine.py @@ -353,14 +353,26 @@ class DecisionEngine: return result except (ValueError, KeyError) as template_error: - # Fallback auf direkten Prompt, falls Template nicht existiert - logger.warning(f"⚠️ [FALLBACK] Template 'fallback_synthesis' nicht gefunden: {template_error}. Verwende direkten Prompt.") - logger.debug(f" -> Direkter Prompt mit Context-Länge: {len(fallback_context)}") + # WP-24c v4.5.9: Fallback auf generisches Template mit variables + # Nutzt Lazy-Loading aus WP-25b für modell-spezifische Fallback-Prompts + logger.warning(f"⚠️ [FALLBACK] Template 'fallback_synthesis' nicht gefunden: {template_error}. Versuche generisches Template.") + logger.debug(f" -> Fallback-Profile: {profile}, Context-Länge: {len(fallback_context)}") - result = await self.llm_service.generate_raw_response( - prompt=f"Beantworte: {query}\n\nKontext:\n{fallback_context}", - system=system_prompt, priority="realtime", profile_name=profile - ) - - logger.info(f"✅ [FALLBACK] Direkter Prompt erfolgreich (Antwort-Länge: {len(result) if result else 0})") - return result \ No newline at end of file + try: + # WP-24c v4.5.9: Versuche generisches Template mit variables (Lazy-Loading) + result = await self.llm_service.generate_raw_response( + prompt_key="fallback_synthesis_generic", # Fallback-Template + variables={"query": query, "context": fallback_context}, + system=system_prompt, priority="realtime", profile_name=profile + ) + logger.info(f"✅ [FALLBACK] Generisches Template erfolgreich (Antwort-Länge: {len(result) if result else 0})") + return result + except (ValueError, KeyError) as fallback_error: + # WP-24c v4.5.9: Letzter Fallback - direkter Prompt (nur wenn beide Templates fehlen) + logger.error(f"❌ [FALLBACK] Auch generisches Template nicht gefunden: {fallback_error}. Verwende direkten Prompt als letzten Fallback.") + result = await self.llm_service.generate_raw_response( + prompt=f"Beantworte: {query}\n\nKontext:\n{fallback_context}", + system=system_prompt, priority="realtime", profile_name=profile + ) + logger.info(f"✅ [FALLBACK] Direkter Prompt erfolgreich (Antwort-Länge: {len(result) if result else 0})") + return result \ No newline at end of file diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index 1e29c47..3373a32 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,8 +2,8 @@ doc_type: glossary audience: all status: active -version: 3.1.1 -context: "Zentrales Glossar für Mindnet v3.1.1. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und Mistral-safe Parsing." +version: 4.5.8 +context: "Zentrales Glossar für Mindnet v4.5.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration, WP-24c Phase 3 Agentic Edge Validation und Mistral-safe Parsing." --- # Mindnet Glossar @@ -64,4 +64,11 @@ context: "Zentrales Glossar für Mindnet v3.1.1. Enthält Definitionen zu Hybrid * **Hierarchische Prompt-Resolution (WP-25b):** Dreistufige Auflösungs-Logik: Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default). Gewährleistet, dass jedes Modell das optimale Template erhält. * **PROMPT-TRACE (WP-25b):** Logging-Mechanismus, der die genutzte Prompt-Auflösungs-Ebene protokolliert (`🎯 Level 1`, `📡 Level 2`, `⚓ Level 3`). Bietet vollständige Transparenz über die genutzten Instruktionen. * **Ultra-robustes Intent-Parsing (WP-25b):** Regex-basierter Intent-Parser in der DecisionEngine, der Modell-Artefakte wie `[/S]`, `` oder Newlines zuverlässig bereinigt, um präzises Strategie-Routing zu gewährleisten. -* **Differenzierte Ingestion-Validierung (WP-25b):** Unterscheidung zwischen transienten Fehlern (Netzwerk, Timeout) und permanenten Fehlern (Config, Validation). Transiente Fehler erlauben die Kante (Datenverlust vermeiden), permanente Fehler lehnen sie ab (Graph-Qualität schützen). \ No newline at end of file +* **Differenzierte Ingestion-Validierung (WP-25b):** Unterscheidung zwischen transienten Fehlern (Netzwerk, Timeout) und permanenten Fehlern (Config, Validation). Transiente Fehler erlauben die Kante (Datenverlust vermeiden), permanente Fehler lehnen sie ab (Graph-Qualität schützen). +* **Phase 3 Agentic Edge Validation (WP-24c v4.5.8):** Finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix. Nutzt LLM-basierte semantische Prüfung zur Verifizierung von Wissensverknüpfungen. Verhindert "Geister-Verknüpfungen" und sichert die Graph-Qualität gegen Fehlinterpretationen ab. +* **candidate: Präfix (WP-24c v4.5.8):** Markierung für unbestätigte Kanten in `rule_id` oder `provenance`. Alle Kanten mit diesem Präfix werden in Phase 3 dem LLM-Validator vorgelegt. Nach erfolgreicher Validierung wird das Präfix entfernt. +* **verified Status (WP-24c v4.5.8):** Impliziter Status für Kanten nach erfolgreicher Phase 3 Validierung. Kanten ohne `candidate:` Präfix gelten als verifiziert und werden in die Datenbank geschrieben. +* **Note-Scope (WP-24c v4.2.0):** Globale Verbindungen, die der gesamten Note zugeordnet werden (nicht nur einem spezifischen Chunk). Wird durch spezielle Header-Zonen (z.B. `## Smart Edges`) definiert. In Phase 3 Validierung wird `note_summary` oder `note_text` als Kontext verwendet. +* **Chunk-Scope (WP-24c v4.2.0):** Lokale Verbindungen, die einem spezifischen Textabschnitt (Chunk) zugeordnet werden. In Phase 3 Validierung wird der spezifische Chunk-Text als Kontext verwendet, falls verfügbar. +* **Kontext-Optimierung (WP-24c v4.5.8):** Dynamische Kontext-Auswahl in Phase 3 Validierung basierend auf `scope`. Note-Scope nutzt aggregierten Note-Text, Chunk-Scope nutzt spezifischen Chunk-Text. Optimiert die Validierungs-Genauigkeit durch passenden Kontext. +* **rejected_edges (WP-24c v4.5.8):** Liste von Kanten, die in Phase 3 Validierung abgelehnt wurden. Diese Kanten werden **nicht** in die Datenbank geschrieben und vollständig ignoriert. Verhindert persistente "Geister-Verknüpfungen" im Wissensgraphen. \ No newline at end of file diff --git a/docs/00_General/00_quality_checklist.md b/docs/00_General/00_quality_checklist.md index 1d1c447..6f2302c 100644 --- a/docs/00_General/00_quality_checklist.md +++ b/docs/00_General/00_quality_checklist.md @@ -2,8 +2,8 @@ doc_type: quality_assurance audience: all status: active -version: 2.9.1 -context: "Qualitätsprüfung der Dokumentation für alle Rollen: Vollständigkeit, Korrektheit und Anwendbarkeit." +version: 4.5.8 +context: "Qualitätsprüfung der Dokumentation für alle Rollen: Vollständigkeit, Korrektheit und Anwendbarkeit. Inkludiert WP-24c Phase 3 Agentic Edge Validation, automatische Spiegelkanten und Note-Scope Zonen." --- # Dokumentations-Qualitätsprüfung @@ -59,6 +59,8 @@ Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fr ### Konfiguration - [x] **ENV-Variablen:** [Configuration Reference](../03_Technical_References/03_tech_configuration.md#1-environment-variablen-env) - [x] **YAML-Configs:** [Configuration Reference - YAML](../03_Technical_References/03_tech_configuration.md#2-typ-registry-typesyaml) +- [x] **Phase 3 Validierung:** [Configuration Reference - ENV](../03_Technical_References/03_tech_configuration.md#1-environment-variablen-env) (MINDNET_LLM_VALIDATION_HEADERS, MINDNET_NOTE_SCOPE_ZONE_HEADERS) +- [x] **LLM-Profile:** [Configuration Reference - LLM Profiles](../03_Technical_References/03_tech_configuration.md#6-llm-profile-registry-llm_profilesyaml-v130) --- @@ -78,12 +80,18 @@ Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fr - [x] **Knowledge Design:** [Knowledge Design Manual](../01_User_Manual/01_knowledge_design.md) - [x] **Authoring Guidelines:** [Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md) - [x] **Obsidian-Integration:** [Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md) +- [x] **Note-Scope Zonen:** [Note-Scope Zonen](../01_User_Manual/NOTE_SCOPE_ZONEN.md) (WP-24c v4.2.0) +- [x] **LLM-Validierung:** [LLM-Validierung von Links](../01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md) (WP-24c v4.5.8) ### Häufige Fragen - [x] **Wie strukturiere ich Notizen?** → [Knowledge Design](../01_User_Manual/01_knowledge_design.md) - [x] **Welche Note-Typen gibt es?** → [Knowledge Design - Typ-Referenz](../01_User_Manual/01_knowledge_design.md#31-typ-referenz--stream-logik) - [x] **Wie verknüpfe ich Notizen?** → [Knowledge Design - Edges](../01_User_Manual/01_knowledge_design.md#4-edges--verlinkung) - [x] **Wie nutze ich den Chat?** → [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md) +- [x] **Was sind automatische Spiegelkanten?** → [Knowledge Design - Spiegelkanten](../01_User_Manual/01_knowledge_design.md#43-automatische-spiegelkanten-invers-logik---wp-24c-v458) +- [x] **Was ist Phase 3 Validierung?** → [Knowledge Design - Phase 3](../01_User_Manual/01_knowledge_design.md#44-explizite-vs-validierte-kanten-phase-3-validierung---wp-24c-v458) +- [x] **Was sind Note-Scope Zonen?** → [Note-Scope Zonen](../01_User_Manual/NOTE_SCOPE_ZONEN.md) +- [x] **Wann nutze ich explizite vs. validierte Links?** → [Knowledge Design - Explizite vs. Validierte](../01_User_Manual/01_knowledge_design.md#44-explizite-vs-validierte-kanten-phase-3-validierung---wp-24c-v458) --- @@ -152,11 +160,17 @@ Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fr ### Aktualisierte Dokumente 1. ✅ `00_documentation_map.md` - Alle neuen Dokumente aufgenommen -2. ✅ `04_admin_operations.md` - Troubleshooting erweitert -3. ✅ `05_developer_guide.md` - Modulare Struktur ergänzt -4. ✅ `03_tech_ingestion_pipeline.md` - Background Tasks dokumentiert -5. ✅ `03_tech_configuration.md` - Fehlende ENV-Variablen ergänzt +2. ✅ `04_admin_operations.md` - Troubleshooting erweitert, Phase 3 Validierung dokumentiert +3. ✅ `05_developer_guide.md` - Modulare Struktur ergänzt, WP-24c Phase 3 dokumentiert +4. ✅ `03_tech_ingestion_pipeline.md` - Background Tasks dokumentiert, Phase 3 Agentic Validation hinzugefügt +5. ✅ `03_tech_configuration.md` - Fehlende ENV-Variablen ergänzt, WP-24c Konfiguration dokumentiert 6. ✅ `00_vision_and_strategy.md` - Design-Entscheidungen ergänzt +7. ✅ `01_knowledge_design.md` - Automatische Spiegelkanten, Phase 3 Validierung, Note-Scope Zonen dokumentiert +8. ✅ `02_concept_graph_logic.md` - Phase 3 Validierung, automatische Spiegelkanten, Note-Scope vs. Chunk-Scope dokumentiert +9. ✅ `03_tech_data_model.md` - candidate: Präfix, verified Status, virtual Flag dokumentiert +10. ✅ `NOTE_SCOPE_ZONEN.md` - Phase 3 Validierung integriert +11. ✅ `LLM_VALIDIERUNG_VON_LINKS.md` - Phase 3 statt global_pool, Kontext-Optimierung dokumentiert +12. ✅ `05_testing_guide.md` - WP-24c Test-Szenarien hinzugefügt --- diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md index eeb1f5b..5f8d397 100644 --- a/docs/01_User_Manual/01_chat_usage_guide.md +++ b/docs/01_User_Manual/01_chat_usage_guide.md @@ -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. diff --git a/docs/01_User_Manual/01_knowledge_design.md b/docs/01_User_Manual/01_knowledge_design.md index 885664e..9abc8b2 100644 --- a/docs/01_User_Manual/01_knowledge_design.md +++ b/docs/01_User_Manual/01_knowledge_design.md @@ -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))* --- diff --git a/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md b/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md index 271d7b3..5613ea9 100644 --- a/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.md +++ b/docs/01_User_Manual/LLM_VALIDIERUNG_VON_LINKS.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) diff --git a/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md b/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md index ba81c49..2b4f944 100644 --- a/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md +++ b/docs/01_User_Manual/NOTE_SCOPE_ZONEN.md @@ -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`. diff --git a/docs/02_concepts/02_concept_graph_logic.md b/docs/02_concepts/02_concept_graph_logic.md index 429b95d..dda784e 100644 --- a/docs/02_concepts/02_concept_graph_logic.md +++ b/docs/02_concepts/02_concept_graph_logic.md @@ -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. \ No newline at end of file +* **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. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index f2be011..e8998da 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, admin -scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts +scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts, agentic_validation status: active -version: 3.1.1 -context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration unter Berücksichtigung von WP-14." +version: 4.5.8 +context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und WP-24c Phase 3 Agentic Edge Validation (v4.5.8) unter Berücksichtigung von WP-14." --- # Konfigurations-Referenz @@ -50,11 +50,11 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der | `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). | | `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). | | `MINDNET_DEFAULT_RETRIEVER_WEIGHT` | `1.0` | **Neu (WP-22):** Systemweiter Standard für das Retriever-Gewicht einer Notiz. | -| `MINDNET_LLM_VALIDATION_HEADERS` | `Unzugeordnete Kanten,Edge Pool,Candidates` | **Neu (v4.2.0):** Komma-separierte Header-Namen für LLM-Validierung. | -| `MINDNET_LLM_VALIDATION_HEADER_LEVEL` | `3` | **Neu (v4.2.0):** Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###). | -| `MINDNET_NOTE_SCOPE_ZONE_HEADERS` | `Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen` | **Neu (v4.2.0):** Komma-separierte Header-Namen für Note-Scope Zonen. | -| `MINDNET_NOTE_SCOPE_HEADER_LEVEL` | `2` | **Neu (v4.2.0):** Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##). | -| `MINDNET_IGNORE_FOLDERS` | *(leer)* | **Neu (v4.1.0):** Komma-separierte Liste von Ordnernamen, die beim Import ignoriert werden. | +| `MINDNET_LLM_VALIDATION_HEADERS` | `Unzugeordnete Kanten,Edge Pool,Candidates` | **Neu (v4.2.0, WP-24c):** Komma-separierte Header-Namen für LLM-Validierung. Kanten in diesen Zonen erhalten `candidate:` Präfix und werden in Phase 3 validiert. | +| `MINDNET_LLM_VALIDATION_HEADER_LEVEL` | `3` | **Neu (v4.2.0, WP-24c):** Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###). Bestimmt, welche Überschriften als Validierungs-Zonen erkannt werden. | +| `MINDNET_NOTE_SCOPE_ZONE_HEADERS` | `Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen` | **Neu (v4.2.0, WP-24c):** Komma-separierte Header-Namen für Note-Scope Zonen. Links in diesen Zonen werden als `scope: note` behandelt und nutzen Note-Summary/Text in Phase 3 Validierung. | +| `MINDNET_NOTE_SCOPE_HEADER_LEVEL` | `2` | **Neu (v4.2.0, WP-24c):** Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##). Bestimmt, welche Überschriften als Note-Scope Zonen erkannt werden. | +| `MINDNET_IGNORE_FOLDERS` | *(leer)* | **Neu (v4.1.0):** Komma-separierte Liste von Ordnernamen, die beim Import ignoriert werden. Beispiel: `.trash,.obsidian,.git,.sync` | --- diff --git a/docs/03_Technical_References/03_tech_data_model.md b/docs/03_Technical_References/03_tech_data_model.md index 9dc235a..d74832e 100644 --- a/docs/03_Technical_References/03_tech_data_model.md +++ b/docs/03_Technical_References/03_tech_data_model.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, architect -scope: database, qdrant, schema +scope: database, qdrant, schema, agentic_validation status: active -version: 2.9.1 -context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen. Berücksichtigt WP-14 Modularisierung und WP-15b Multi-Hashes." +version: 4.5.8 +context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen. Berücksichtigt WP-14 Modularisierung, WP-15b Multi-Hashes und WP-24c Phase 3 Agentic Edge Validation (candidate: Präfix, verified Status)." --- # Technisches Datenmodell (Qdrant Schema) @@ -113,10 +113,12 @@ Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Track "scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note') "note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante) - // Provenance & Quality (WP03/WP15) - "provenance": "keyword", // 'explicit', 'rule', 'smart', 'structure' - "rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink', 'smart:llm' - "confidence": "float" // Vertrauenswürdigkeit (0.0 - 1.0) + // Provenance & Quality (WP03/WP15/WP-24c) + "provenance": "keyword", // 'explicit', 'explicit:note_zone', 'explicit:callout', 'rule', 'semantic_ai', 'structure', 'candidate:...' (vor Phase 3) + "rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink', 'candidate:...' (vor Phase 3), 'explicit' (nach Phase 3 VERIFIED) + "confidence": "float", // Vertrauenswürdigkeit (0.0 - 1.0) + "scope": "string (keyword)", // 'chunk' (Standard) oder 'note' (Note-Scope Zonen) - WP-24c v4.2.0 + "virtual": "boolean (optional)" // true für automatisch generierte Spiegelkanten (Invers-Logik) - WP-24c v4.5.8 } ``` @@ -127,6 +129,23 @@ Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Track * Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key, um "Phantom-Knoten" zu vermeiden. * **Metadaten-Persistenz:** `target_section`, `provenance` und `confidence` werden durchgängig im In-Memory Subgraph und Datenbank-Adapter erhalten. +**Phase 3 Validierung (WP-24c v4.5.8):** +* **candidate: Präfix:** Kanten mit `candidate:` in `rule_id` oder `provenance` durchlaufen Phase 3 Validierung +* **Vor Validierung:** `provenance: "candidate:global_pool"` oder `rule_id: "candidate:..."` +* **Nach VERIFIED:** `candidate:` Präfix wird entfernt, Kante wird persistiert +* **Nach REJECTED:** Kante wird **nicht** in die Datenbank geschrieben (verhindert "Geister-Verknüpfungen") +* **Wichtig:** Nur Kanten ohne `candidate:` Präfix werden im Graph persistiert + +**Note-Scope vs. Chunk-Scope (WP-24c v4.2.0):** +* **Chunk-Scope (`scope: "chunk"`):** Standard, `source_id = chunk_id` (z.B. `note-id#c00`) +* **Note-Scope (`scope: "note"`):** Aus Note-Scope Zonen, `source_id = note_id` (nicht `chunk_id`) +* **Phase 3 Kontext-Optimierung:** Note-Scope nutzt `note_summary`/`note_text`, Chunk-Scope nutzt spezifischen Chunk-Text + +**Automatische Spiegelkanten (WP-24c v4.5.8):** +* **virtual: true:** Markiert automatisch generierte Invers-Kanten (Spiegelkanten) +* **Provenance:** `structure` (System-generiert, geschützt durch Provenance Firewall) +* **Confidence:** Leicht gedämpft (`original * 0.9`) im Vergleich zu expliziten Kanten + **Erforderliche Indizes:** Es müssen Payload-Indizes für folgende Felder existieren: * `source_id` diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index 3371b2e..f7e741a 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, devops -scope: backend, ingestion, smart_edges, edge_registry, modularization, moe, lazy_prompts +scope: backend, ingestion, smart_edges, edge_registry, modularization, moe, lazy_prompts, agentic_validation status: active -version: 2.14.0 -context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14), WP-25a profilgesteuerte Validierung und WP-25b Lazy-Prompt-Orchestration. Integriert Mistral-safe Parsing und Deep Fallback." +version: 4.5.8 +context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14), WP-25a profilgesteuerte Validierung, WP-25b Lazy-Prompt-Orchestration und WP-24c Phase 3 Agentic Edge Validation (v4.5.8). Integriert Mistral-safe Parsing und Deep Fallback." --- # Ingestion Pipeline & Smart Processing @@ -15,9 +15,9 @@ Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import -## 1. Der Import-Prozess (16-Schritte-Workflow) +## 1. Der Import-Prozess (17-Schritte-Workflow - 3-Phasen-Modell) -Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durchläufe (Passes) unterteilt, um die semantische Genauigkeit zu maximieren. +Der Prozess ist **asynchron**, **idempotent** und wird nun in **drei logische Phasen** unterteilt, um die semantische Genauigkeit zu maximieren und die Graph-Qualität durch agentische Validierung zu sichern. ### Phase 1: Pre-Scan & Context (Pass 1) 1. **Trigger & Async Dispatch:** @@ -50,18 +50,10 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc * Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note. * Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket. 10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). -11. **Smart Edge Allocation & Semantic Validation (WP-15b / WP-25a / WP-25b):** +11. **Smart Edge Allocation & Kandidaten-Erzeugung (WP-15b / WP-25a / WP-25b):** * Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor. - * **Validierung (WP-25a/25b):** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft. - * **Profilgesteuerte Validierung:** Nutzt das MoE-Profil `ingest_validator` (Temperature 0.0 für maximale Determinismus). - * **Lazy-Prompt-Loading (WP-25b):** Nutzt `prompt_key="edge_validation"` mit `variables` statt vorformatierter Strings. - * **Hierarchische Resolution:** Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default) - * **Differenzierte Fehlerbehandlung (WP-25b):** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern: - * **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden) - * **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen) - * **Fallback-Kaskade:** Bei Fehlern erfolgt automatischer Fallback via `fallback_profile` (z.B. `compression_fast` → `identity_safe`). - * **Traffic Control:** Nutzung der neutralen `clean_llm_text` Funktion zur Bereinigung von Steuerzeichen (, [OUT]). - * **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals". Liefert die Cloud keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen. + * **Kandidaten-Markierung:** Alle vorgeschlagenen Kanten erhalten `candidate:` Präfix in `rule_id` oder `provenance`. + * **Hinweis:** Die eigentliche LLM-Validierung erfolgt erst in **Phase 3** (siehe Schritt 17). 12. **Inline-Kanten finden:** Parsing von `[[rel:...]]` und Callouts. 13. **Alias-Auflösung & Kanonisierung (WP-22):** * Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`). @@ -70,7 +62,28 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc 15. **Embedding (Async - WP-25a):** Generierung der Vektoren via `embedding_expert` Profil aus `llm_profiles.yaml`. * **Profil-Auflösung:** Das `EmbeddingsClient` lädt Modell und Dimensionen direkt aus dem Profil (z.B. `nomic-embed-text`, 768 Dimensionen). * **Konsolidierung:** Entfernung der Embedding-Konfiguration aus der `.env` zugunsten zentraler Profil-Registry. -16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur. + +### Phase 3: Agentic Edge Validation (WP-24c v4.5.8) + +17. **Finales Validierungs-Gate für candidate: Kanten:** + * **Trigger-Kriterium:** Alle Kanten mit `rule_id` ODER `provenance` beginnend mit `"candidate:"` werden dem LLM-Validator vorgelegt. + * **Kontext-Optimierung:** Dynamische Kontext-Auswahl basierend auf `scope`: + * **Note-Scope (`scope: note`):** Verwendet `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) für globale Verbindungen. + * **Chunk-Scope (`scope: chunk`):** Versucht spezifischen Chunk-Text zu finden, sonst Fallback auf Note-Text. + * **Validierung:** Nutzt `validate_edge_candidate()` mit MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus). + * **Erfolg (VERIFIED):** Entfernt `candidate:` Präfix aus `rule_id` und `provenance`. Kante wird zu `validated_edges` hinzugefügt. + * **Ablehnung (REJECTED):** Kante wird zu `rejected_edges` hinzugefügt und **nicht** weiterverarbeitet (keine DB-Persistierung). + * **Fehlertoleranz:** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern: + * **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Integrität vor Präzision) + * **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen) + * **Logging:** `🚀 [PHASE 3]` für Start, `✅ [PHASE 3] VERIFIED` für Erfolg, `🚫 [PHASE 3] REJECTED` für Ablehnung. + +**Wichtig:** Nur `validated_edges` (ohne `candidate:` Präfix) werden in Phase 2 (Symmetrie) verarbeitet und in die Datenbank geschrieben. `rejected_edges` werden vollständig ignoriert. + +### Phase 2 (Fortsetzung): Symmetrie & Persistence + +18. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur. + * **Nur verified Kanten:** Nur Kanten ohne `candidate:` Präfix werden persistiert. --- @@ -198,6 +211,8 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere **2. Mistral-safe Parsing:** Automatisierte Bereinigung von LLM-Antworten in `ingestion_validation.py`. Stellt sicher, dass semantische Entscheidungen ("YES"/"NO") nicht durch technische Header verfälscht werden. -**3. Profilgesteuerte Validierung (WP-25a):** Die semantische Kanten-Validierung erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus). Dies gewährleistet konsistente binäre Entscheidungen (YES/NO) unabhängig von der globalen Provider-Konfiguration. +**3. Phase 3 Agentic Edge Validation (WP-24c v4.5.8):** Finales Validierungs-Gate für alle `candidate:` Kanten. Nutzt das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus) und dynamische Kontext-Optimierung (Note-Scope vs. Chunk-Scope). Gewährleistet konsistente binäre Entscheidungen (YES/NO) und verhindert "Geister-Verknüpfungen" im Wissensgraphen. + +**4. Profilgesteuerte Validierung (WP-25a):** Die semantische Kanten-Validierung erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus). Dies gewährleistet konsistente binäre Entscheidungen (YES/NO) unabhängig von der globalen Provider-Konfiguration. **3. Purge Integrity:** Validierung, dass vor jedem Upsert alle assoziierten Artefakte in den Collections `{prefix}_chunks` und `{prefix}_edges` gelöscht wurden, um Daten-Duplikate zu vermeiden. \ No newline at end of file diff --git a/docs/03_Technical_References/AUDIT_SYSTEM_INTEGRITY_V4.5.8.md b/docs/03_Technical_References/AUDIT_SYSTEM_INTEGRITY_V4.5.8.md new file mode 100644 index 0000000..495069f --- /dev/null +++ b/docs/03_Technical_References/AUDIT_SYSTEM_INTEGRITY_V4.5.8.md @@ -0,0 +1,510 @@ +# System-Integrity & Regression-Audit (v4.5.8) + +**Datum:** 2026-01-XX +**Version:** v4.5.8 +**Status:** Audit abgeschlossen +**Auditor:** AI Assistant (Auto) + +## Kontext + +Nach umfangreichen Änderungen in WP24c (insbesondere v4.5.7/8) wurde ein vollständiges System-Integrity & Regression-Audit durchgeführt, um sicherzustellen, dass keine unbeabsichtigten Beeinträchtigungen oder "Logic-Drift" eingeführt wurden. + +## Audit-Scope + +1. **WP-22 Scoring Integrität**: Prüfung der mathematischen Berechnung des `total_score` +2. **WP-25a/b MoE & Prompts**: Verifizierung der Profil-Ladung und MoE-Kaskade +3. **Deduplizierungs-Logik**: Prüfung der De-Duplizierung von Kanten +4. **Phase 3 Validierungs-Gate**: Verifizierung der neuen Validierungs-Logik +5. **Note-Scope Kontext-Optimierung**: Prüfung der Kontext-Optimierung + +--- + +## 1. WP-22 Scoring Integrität + +### Prüfpunkt: Hat die Einführung von `candidate:` oder `verified` Status Auswirkungen auf die mathematische Berechnung des `total_score`? + +**Status:** ✅ **KEIN PROBLEM** + +**Ergebnis:** +- `candidate:` und `verified` sind **KEINE Status-Werte** für die Scoring-Funktion +- Sie sind **Präfixe** in `rule_id` und `provenance` für Kanten (Edge-Metadaten) +- Die `get_status_multiplier()` Funktion in `retriever_scoring.py` behandelt ausschließlich: + - `stable`: 1.2 (Multiplikator) + - `active`: 1.0 (Standard) + - `draft`: 0.5 (Dämpfung) +- Die mathematische Formel in `compute_wp22_score()` bleibt vollständig unangetastet + +**Code-Referenz:** +- `app/core/retrieval/retriever_scoring.py` Zeile 49-63: `get_status_multiplier()` +- `app/core/retrieval/retriever_scoring.py` Zeile 65-128: `compute_wp22_score()` + +**Bewertung:** Die Scoring-Mathematik ist **vollständig isoliert** von den Edge-Metadaten (`candidate:`, `verified`). Keine Regression festgestellt. + +--- + +## 2. WP-25a/b MoE & Prompts + +### Prüfpunkt 2a: Werden die korrekten Profile aus `llm_profiles.yaml` geladen? + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- `LLMService._load_llm_profiles()` lädt Profile aus `llm_profiles.yaml` (nicht `prompts.yaml`) +- Pfad wird korrekt aus Settings geladen: `LLM_PROFILES_PATH` (Default: `config/llm_profiles.yaml`) +- Profile werden im `__init__` geladen und im Instanz-Attribut `self.profiles` gespeichert +- Fehlerbehandlung vorhanden: Bei fehlender Datei wird leeres Dict zurückgegeben mit Warnung + +**Code-Referenz:** +- `app/services/llm_service.py` Zeile 87-100: `_load_llm_profiles()` +- `app/services/llm_service.py` Zeile 36: Initialisierung in `__init__` + +**Bewertung:** Profil-Ladung funktioniert korrekt. Keine Regression. + +### Prüfpunkt 2b: Nutzt die neue Validierungs-Logik in Phase 3 die bestehende MoE-Kaskade? + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Phase 3 Validierung nutzt `profile_name="ingest_validator"` (siehe `ingestion_processor.py` Zeile 345) +- `LLMService.generate_raw_response()` unterstützt vollständig die MoE-Kaskade: + - Profil-Auflösung aus `llm_profiles.yaml` (Zeile 151-161) + - Fallback-Kaskade via `fallback_profile` (Zeile 214-227) + - `visited_profiles` Schutz verhindert Endlosschleifen (Zeile 214) + - Rekursiver Aufruf mit `visited_profiles` Parameter (Zeile 226) +- Die Kaskade wird **nicht umgangen**, sondern vollständig genutzt + +**Code-Referenz:** +- `app/core/ingestion/ingestion_processor.py` Zeile 340-346: Phase 3 Validierung +- `app/services/llm_service.py` Zeile 150-227: MoE-Kaskade Implementierung +- `config/llm_profiles.yaml`: Profil-Definitionen mit `fallback_profile` + +**Bewertung:** MoE-Kaskade wird korrekt genutzt. Keine Regression. + +### Prüfpunkt 2c: Werden Prompts korrekt aus `prompts.yaml` geladen? + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- `LLMService._load_prompts()` lädt Prompts aus `prompts.yaml` (Zeile 76-85) +- `DecisionEngine` nutzt `prompt_key` und `variables` für Lazy-Loading (Zeile 108-113, 309-315) +- `LLMService.get_prompt()` unterstützt Hierarchie: Model-ID → Provider → Default (Zeile 102-123) +- Prompt-Formatierung erfolgt via `template.format(**(variables or {}))` (Zeile 179) + +**Code-Referenz:** +- `app/services/llm_service.py` Zeile 76-85: `_load_prompts()` +- `app/services/llm_service.py` Zeile 102-123: `get_prompt()` mit Hierarchie +- `app/core/retrieval/decision_engine.py` Zeile 107-113: Intent-Routing mit `prompt_key` +- `app/core/retrieval/decision_engine.py` Zeile 309-315: Finale Synthese mit `prompt_key` + +**Bewertung:** Prompt-Ladung funktioniert korrekt. Keine Regression. + +--- + +## 3. Deduplizierungs-Logik + +### Prüfpunkt: Gefährden die Änderungen an `all_chunk_callout_keys` in v4.5.7/8 die gewollte De-Duplizierung von Kanten (WP-24c)? + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- `all_chunk_callout_keys` wird **VOR jeder Verwendung** initialisiert (Zeile 531-533) +- Initialisierung erfolgt **VOR** Phase 1 (Sammeln aus `candidate_pool`) und **VOR** Phase 2 (Chunk-Verarbeitung) +- Die De-Duplizierungs-Logik ist **vollständig intakt**: + - Phase 1: Sammeln aller `explicit:callout` Keys aus `candidate_pool` (Zeile 657-697) + - Phase 2: Prüfung gegen `all_chunk_callout_keys` vor Erstellung neuer Callout-Kanten (Zeile 768) + - Globaler Scan: Nutzung von `all_chunk_callout_keys` als Ausschlusskriterium (Zeile 855) +- LLM-Validierungs-Zonen: Callouts werden korrekt zu `all_chunk_callout_keys` hinzugefügt (Zeile 615) + +**Code-Referenz:** +- `app/core/graph/graph_derive_edges.py` Zeile 531-533: Initialisierung +- `app/core/graph/graph_derive_edges.py` Zeile 657-697: Phase 1 (Sammeln) +- `app/core/graph/graph_derive_edges.py` Zeile 768: Phase 2 (Prüfung) +- `app/core/graph/graph_derive_edges.py` Zeile 855: Globaler Scan (Ausschluss) + +**Bewertung:** De-Duplizierungs-Logik ist intakt. Keine Regression. + +--- + +## 4. Phase 3 Validierungs-Gate + +### Prüfpunkt: Ist das Phase 3 Validierungs-Gate korrekt implementiert und nutzt es die MoE-Kaskade? + +**Status:** ✅ **GEWOLLTE ÄNDERUNG** (v4.5.8) + +**Ergebnis:** +- Phase 3 Validierung ist **korrekt implementiert** in `ingestion_processor.py` (Zeile 274-371) +- **Trigger-Kriterium:** Kanten mit `rule_id` ODER `provenance` beginnend mit `"candidate:"` (Zeile 292) +- **Validierung:** Nutzt `validate_edge_candidate()` mit `profile_name="ingest_validator"` (Zeile 340-346) +- **Erfolg:** Entfernt `candidate:` Präfix aus `rule_id` und `provenance` (Zeile 349-357) +- **Ablehnung:** Kanten werden zu `rejected_edges` hinzugefügt und **nicht** weiterverarbeitet (Zeile 362-363) +- **MoE-Kaskade:** Wird vollständig genutzt via `llm_service.generate_raw_response()` (siehe Prüfpunkt 2b) + +**Code-Referenz:** +- `app/core/ingestion/ingestion_processor.py` Zeile 274-371: Phase 3 Implementierung +- `app/core/ingestion/ingestion_validation.py` Zeile 24-91: `validate_edge_candidate()` + +**Bewertung:** Phase 3 Validierungs-Gate ist korrekt implementiert. **Gewollte Änderung**, keine Regression. + +--- + +## 5. Note-Scope Kontext-Optimierung + +### Prüfpunkt: Ist die Note-Scope Kontext-Optimierung korrekt implementiert? + +**Status:** ✅ **GEWOLLTE ÄNDERUNG** (v4.5.8) + +**Ergebnis:** +- Kontext-Optimierung ist **korrekt implementiert** in Phase 3 Validierung (Zeile 311-326) +- **Note-Scope:** Verwendet `note_summary` oder `note_text` (aggregierter Kontext) (Zeile 314-316) +- **Chunk-Scope:** Versucht spezifischen Chunk-Text zu finden, sonst Note-Text (Zeile 318-326) +- **Note-Summary:** Wird aus Top 5 Chunks erstellt (Zeile 282) +- **Note-Text:** Wird aus `markdown_body` oder aggregiert aus allen Chunks erstellt (Zeile 280) + +**Code-Referenz:** +- `app/core/ingestion/ingestion_processor.py` Zeile 278-282: Note-Summary/Text Erstellung +- `app/core/ingestion/ingestion_processor.py` Zeile 311-326: Kontext-Optimierung + +**Bewertung:** Note-Scope Kontext-Optimierung ist korrekt implementiert. **Gewollte Änderung**, keine Regression. + +--- + +## 6. Weitere Prüfungen + +### 6.1 Edge-Registry Integration + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Edge-Registry wird korrekt für Typ-Auflösung genutzt (Zeile 383 in `ingestion_processor.py`) +- Symmetrie-Generierung nutzt `edge_registry.get_inverse()` (Zeile 397) +- Keine Regression festgestellt + +### 6.2 Context-Reuse Logik + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Context-Reuse ist in `decision_engine.py` implementiert (Zeile 154-196) +- Bei Kompressions-Fehlern wird Original-Content zurückgegeben (Zeile 232-235) +- Bei Synthese-Fehlern wird Fallback mit vorhandenem Context genutzt (Zeile 328-365) +- Keine Regression festgestellt + +### 6.3 Prompt-Template Validierung + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Prompt-Validierung in `llm_service.py` prüft auf leere Templates (Zeile 172-175) +- Fehlerbehandlung vorhanden: `ValueError` bei fehlendem oder leerem `prompt_key` +- Keine Regression festgestellt + +--- + +## Zusammenfassung + +### ✅ Keine Regressionen festgestellt + +Alle geprüften Funktionen arbeiten korrekt und entsprechen den ursprünglichen WP-Spezifikationen: + +1. **WP-22 Scoring:** Mathematik bleibt unangetastet ✅ +2. **WP-25a/b MoE & Prompts:** Profile und Prompts werden korrekt geladen, MoE-Kaskade funktioniert ✅ +3. **Deduplizierungs-Logik:** `all_chunk_callout_keys` funktioniert korrekt ✅ +4. **Phase 3 Validierung:** Korrekt implementiert, nutzt MoE-Kaskade ✅ +5. **Note-Scope Kontext-Optimierung:** Korrekt implementiert ✅ + +### 📋 Gewollte Änderungen (v4.5.8) + +Die folgenden Änderungen sind **explizit gewollt** und stellen keine Regressionen dar: + +1. **Phase 3 Validierungs-Gate:** Neue Validierungs-Logik für `candidate:` Kanten +2. **Note-Scope Kontext-Optimierung:** Optimierte Kontext-Auswahl für Note-Scope vs. Chunk-Scope Kanten + +### 🔍 Empfehlungen + +**Keine kritischen Probleme gefunden.** Das System ist in einem stabilen Zustand. + +**Optional (nicht kritisch):** +- Erwägen Sie zusätzliche Unit-Tests für Phase 3 Validierung +- Dokumentation der `candidate:` → `verified` Transformation könnte erweitert werden + +--- + +## Audit-Methodik + +1. **Code-Analyse:** Vollständige Analyse der relevanten Dateien +2. **Semantic Search:** Suche nach Verwendungen von `candidate:`, `verified`, `all_chunk_callout_keys` +3. **Grep-Suche:** Exakte String-Suche nach kritischen Patterns +4. **Dokumentations-Review:** Prüfung der technischen Dokumentation + +**Geprüfte Dateien:** +- `app/core/retrieval/retriever_scoring.py` +- `app/services/llm_service.py` +- `app/core/retrieval/decision_engine.py` +- `app/core/graph/graph_derive_edges.py` +- `app/core/ingestion/ingestion_processor.py` +- `app/core/ingestion/ingestion_validation.py` +- `config/prompts.yaml` +- `config/llm_profiles.yaml` + +--- + +## 7. Zusätzliche Prüfungen & Bekannte Schwachstellen + +### 7.1 Callout-Extraktion aus Edge-Zonen (aus AUDIT_CLEAN_CONTEXT_V4.2.0) + +**Status:** ⚠️ **POTENZIELL BEHOBEN** (verifizieren erforderlich) + +**Hintergrund:** +- AUDIT_CLEAN_CONTEXT_V4.2.0 identifizierte ein kritisches Problem: Callouts in Edge-Zonen wurden nicht extrahiert +- Problem: Callouts wurden nur aus gefilterten Chunks extrahiert, nicht aus Original-Markdown + +**Aktueller Status:** +- ✅ Funktion `extract_callouts_from_markdown()` existiert in `graph_derive_edges.py` (Zeile 263-501) +- ✅ Funktion wird in `build_edges_for_note()` aufgerufen (Zeile 852-864) +- ⚠️ **VERIFIZIERUNG ERFORDERLICH:** Prüfen, ob Callouts in LLM-Validierungs-Zonen korrekt extrahiert werden + +**Code-Referenz:** +- `app/core/graph/graph_derive_edges.py` Zeile 263-501: `extract_callouts_from_markdown()` +- `app/core/graph/graph_derive_edges.py` Zeile 852-864: Aufruf in `build_edges_for_note()` + +**Empfehlung:** +- Test mit Callout in LLM-Validierungs-Zone durchführen +- Verifizieren, dass Edge in Qdrant `_edges` Collection existiert +- Prüfen, ob `candidate:` Präfix korrekt gesetzt wird + +--- + +### 7.2 Rejected Edges Tracking & Monitoring + +**Status:** ⚠️ **POTENZIELLE SCHWACHSTELLE** + +**Problem:** +- Phase 3 Validierung lehnt Kanten ab und fügt sie zu `rejected_edges` hinzu (Zeile 363) +- `rejected_edges` werden geloggt, aber **nicht persistiert** oder analysiert +- Keine Möglichkeit, abgelehnte Kanten zu überprüfen oder zu debuggen + +**Konsequenz:** +- **Fehlende Transparenz:** Keine Nachvollziehbarkeit, warum Kanten abgelehnt wurden +- **Keine Metriken:** Keine Statistiken über Ablehnungsrate +- **Schwieriges Debugging:** Bei Problemen keine Möglichkeit, abgelehnte Kanten zu analysieren + +**Code-Referenz:** +- `app/core/ingestion/ingestion_processor.py` Zeile 363: `rejected_edges.append(e)` +- `app/core/ingestion/ingestion_processor.py` Zeile 370-371: Logging, aber keine Persistierung + +**Empfehlung:** +- Optional: Persistierung von `rejected_edges` in Log-Datei oder separater Collection +- Metriken: Tracking der Ablehnungsrate pro Note/Typ +- Debug-Modus: Detailliertes Logging der Ablehnungsgründe + +--- + +### 7.3 Transiente vs. Permanente Fehler in Phase 3 Validierung + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- `validate_edge_candidate()` unterscheidet korrekt zwischen transienten und permanenten Fehlern (Zeile 79-91) +- Transiente Fehler (Netzwerk) → Kante wird erlaubt (Integrität vor Präzision) +- Permanente Fehler → Kante wird abgelehnt (Graph-Qualität schützen) + +**Code-Referenz:** +- `app/core/ingestion/ingestion_validation.py` Zeile 79-91: Fehlerbehandlung + +**Bewertung:** Korrekt implementiert. Keine Regression. + +--- + +### 7.4 Note-Scope Kontext-Optimierung: Chunk-Text Fallback + +**Status:** ⚠️ **POTENZIELLE SCHWACHSTELLE** + +**Problem:** +- Bei Chunk-Scope Kanten wird versucht, spezifischen Chunk-Text zu finden (Zeile 319-325) +- Fallback auf `note_text`, wenn Chunk-Text nicht gefunden wird +- **Risiko:** Bei fehlendem Chunk-Text wird Note-Text verwendet, was weniger präzise ist + +**Code-Referenz:** +- `app/core/ingestion/ingestion_processor.py` Zeile 318-326: Chunk-Text Suche + +**Empfehlung:** +- Prüfen, ob Chunk-Text immer verfügbar ist +- Bei fehlendem Chunk-Text: Warnung loggen +- Optional: Bessere Fehlerbehandlung für fehlende Chunk-IDs + +--- + +### 7.5 LLM-Validierungs-Zonen: Callout-Key Tracking + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Callouts aus LLM-Validierungs-Zonen werden korrekt zu `all_chunk_callout_keys` hinzugefügt (Zeile 615) +- Verhindert Duplikate im globalen Scan +- Korrekte `candidate:` Präfix-Setzung + +**Code-Referenz:** +- `app/core/graph/graph_derive_edges.py` Zeile 604-616: LLM-Validierungs-Zone Callout-Tracking + +**Bewertung:** Korrekt implementiert. Keine Regression. + +--- + +### 7.6 Scope-Aware Edge Retrieval (aus AUDIT_RETRIEVER_V4.1.0) + +**Status:** ⚠️ **POTENZIELL BEHOBEN** (verifizieren erforderlich) + +**Hintergrund:** +- AUDIT_RETRIEVER_V4.1.0 identifizierte ein Problem: Retriever suchte nur nach Note-Level Edges, nicht Chunk-Level +- Problem: Chunk-Scope Edges wurden nicht explizit berücksichtigt + +**Aktueller Status:** +- ⚠️ **VERIFIZIERUNG ERFORDERLICH:** Prüfen, ob `fetch_edges_from_qdrant` Chunk-Level Edges korrekt lädt +- Dokumentation besagt, dass Optimierungen implementiert wurden + +**Empfehlung:** +- Test mit Chunk-Scope Edge durchführen +- Verifizieren, dass Edge im Retrieval-Ergebnis enthalten ist +- Prüfen, ob `chunk_id` Filter korrekt funktioniert + +--- + +### 7.7 Section-Filtering im Retrieval (aus AUDIT_RETRIEVER_V4.1.0) + +**Status:** ⚠️ **POTENZIELL BEHOBEN** (verifizieren erforderlich) + +**Hintergrund:** +- AUDIT_RETRIEVER_V4.1.0 identifizierte fehlende Filterung nach `target_section` +- Problem: Section-Links (`[[Note#Section]]`) wurden nicht präzise gefiltert + +**Aktueller Status:** +- ⚠️ **VERIFIZIERUNG ERFORDERLICH:** Prüfen, ob `target_section` Filter im Retrieval funktioniert +- Dokumentation besagt, dass Optimierungen implementiert wurden + +**Empfehlung:** +- Test mit Section-Link durchführen +- Verifizieren, dass nur relevante Chunks zurückgegeben werden +- Prüfen, ob `QueryRequest.target_section` korrekt verwendet wird + +--- + +### 7.8 Prompt-Integration: Explanation Layer + +**Status:** ⚠️ **UNKLAR** (aus AUDIT_CLEAN_CONTEXT_V4.2.0) + +**Problem:** +- Unklar, ob `explanation.related_edges` im LLM-Prompt verwendet werden +- Keine explizite Dokumentation der Prompt-Struktur für RAG-Kontext + +**Code-Referenz:** +- `app/core/retrieval/retriever.py` Zeile 150-252: `_build_explanation()` +- `app/routers/chat.py`: Prompt-Verwendung + +**Empfehlung:** +- Prüfen Sie `config/prompts.yaml` für `interview_template` und andere Templates +- Stellen Sie sicher, dass `{related_edges}` oder ähnliche Variablen im Prompt verwendet werden +- Dokumentieren Sie die Prompt-Struktur für RAG-Kontext + +--- + +### 7.9 Fallback-Synthese: Hardcodierter Prompt (aus AUDIT_WP25B_CODE_REVIEW) + +**Status:** ⚠️ **ARCHITEKTONISCHE INKONSISTENZ** + +**Problem:** +- Fallback-Synthese in `decision_engine.py` verwendet `prompt=` statt `prompt_key=` (Zeile 361) +- Inkonsistent mit WP25b-Architektur (Lazy-Loading) +- Keine modell-spezifischen Prompts im Fallback + +**Code-Referenz:** +- `app/core/retrieval/decision_engine.py` Zeile 360-363: Hardcodierter Prompt + +**Empfehlung:** +- Umstellen auf `prompt_key="fallback_synthesis"` mit `variables` +- Konsistenz mit WP25b-Architektur +- Modell-spezifische Optimierungen auch im Fallback + +**Schweregrad:** 🟡 Mittel (funktional, aber architektonisch inkonsistent) + +--- + +### 7.10 Edge-Registry: Unbekannte Kanten + +**Status:** ✅ **FUNKTIONIERT KORREKT** + +**Ergebnis:** +- Unbekannte Kanten-Typen werden in `unknown_edges.jsonl` protokolliert +- Edge-Registry normalisiert Kanten-Typen korrekt +- Keine Regression festgestellt + +**Code-Referenz:** +- `app/services/edge_registry.py`: Edge-Registry Implementierung + +**Bewertung:** Korrekt implementiert. Keine Regression. + +--- + +## 8. Zusammenfassung der zusätzlichen Prüfungen + +### ✅ Bestätigt funktionierend: +1. **Transiente vs. Permanente Fehler:** Korrekte Unterscheidung ✅ +2. **LLM-Validierungs-Zonen Callout-Tracking:** Korrekt implementiert ✅ +3. **Edge-Registry:** Funktioniert korrekt ✅ + +### ⚠️ Verifizierung erforderlich: +1. **Callout-Extraktion aus Edge-Zonen:** Funktion existiert, aber Verifizierung erforderlich +2. **Scope-Aware Edge Retrieval:** Potenziell behoben, Verifizierung erforderlich +3. **Section-Filtering:** Potenziell behoben, Verifizierung erforderlich + +### ⚠️ Potenzielle Schwachstellen: +1. **Rejected Edges Tracking:** Keine Persistierung oder Metriken +2. **Note-Scope Kontext-Optimierung:** Chunk-Text Fallback könnte verbessert werden +3. **Prompt-Integration:** Unklar, ob `explanation.related_edges` verwendet werden +4. **Fallback-Synthese:** Architektonische Inkonsistenz (hardcodierter Prompt) + +--- + +## 9. Empfohlene Follow-up Prüfungen + +### 9.1 Funktionale Tests + +1. **Callout in LLM-Validierungs-Zone:** + - Erstellen Sie eine Notiz mit Callout in `### Unzugeordnete Kanten` + - Verifizieren: Edge existiert in Qdrant mit `candidate:` Präfix + - Verifizieren: Edge wird in Phase 3 validiert + +2. **Chunk-Scope Edge Retrieval:** + - Erstellen Sie eine Note mit Chunk-Scope Edge + - Query mit `explain=True` + - Verifizieren: Edge erscheint in `explanation.related_edges` + +3. **Section-Link Retrieval:** + - Erstellen Sie einen Section-Link (`[[Note#Section]]`) + - Query mit `target_section="Section"` + - Verifizieren: Nur relevante Chunks werden zurückgegeben + +### 9.2 Metriken & Monitoring + +1. **Phase 3 Validierung Metriken:** + - Tracking der Validierungsrate (verified/rejected) + - Tracking der Ablehnungsgründe + - Monitoring der LLM-Validierungs-Performance + +2. **Edge-Statistiken:** + - Anzahl der `candidate:` Kanten pro Note + - Anzahl der verifizierten Kanten pro Note + - Anzahl der abgelehnten Kanten pro Note + +### 9.3 Dokumentation + +1. **Prompt-Struktur:** + - Dokumentieren Sie die Verwendung von `explanation.related_edges` in Prompts + - Erstellen Sie Beispiele für RAG-Kontext-Integration + +2. **Phase 3 Validierung:** + - Dokumentieren Sie den Validierungs-Prozess + - Erstellen Sie Troubleshooting-Guide für abgelehnte Kanten + +--- + +**Audit abgeschlossen:** ✅ System-Integrität bestätigt mit zusätzlichen Prüfungen diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md index 73780aa..f9191ce 100644 --- a/docs/04_Operations/04_admin_operations.md +++ b/docs/04_Operations/04_admin_operations.md @@ -1,10 +1,10 @@ --- doc_type: operations_manual audience: admin, devops -scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts +scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts, agentic_validation status: active -version: 3.1.1 -context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.1.1 inklusive WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration Konfiguration." +version: 4.5.8 +context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v4.5.8 inklusive WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und WP-24c Phase 3 Agentic Edge Validation Konfiguration." --- # Admin Operations Guide @@ -246,6 +246,24 @@ Bevor du spezifische Fehler behebst, führe diese Checks durch: 1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu 2. Oder verwende kanonische Typen aus der Registry +**Fehler: "Phase 3 Validierung schlägt fehl" (WP-24c v4.5.8)** +* **Symptom:** Links in `### Unzugeordnete Kanten` werden nicht validiert oder abgelehnt. +* **Diagnose:** Prüfe Logs auf `🚀 [PHASE 3]` und `🚫 [PHASE 3] REJECTED`. +* **Lösung:** + 1. Prüfe `MINDNET_LLM_VALIDATION_HEADERS` in `.env` (Standard: `Unzugeordnete Kanten,Edge Pool,Candidates`) + 2. Prüfe `MINDNET_LLM_VALIDATION_HEADER_LEVEL` (Standard: `3` für `###`) + 3. Prüfe `llm_profiles.yaml` - `ingest_validator` Profil muss existieren + 4. Prüfe LLM-Verfügbarkeit (Ollama/OpenRouter) + 5. **Hinweis:** Transiente Fehler (Netzwerk) erlauben die Kante, permanente Fehler lehnen sie ab + +**Fehler: "Note-Scope Links werden nicht erkannt" (WP-24c v4.2.0)** +* **Symptom:** Links in `## Smart Edges` Zonen werden nicht als Note-Scope behandelt. +* **Diagnose:** Prüfe Logs auf Note-Scope Extraktion. +* **Lösung:** + 1. Prüfe `MINDNET_NOTE_SCOPE_ZONE_HEADERS` in `.env` (Standard: `Smart Edges,Relationen,Global Links`) + 2. Prüfe `MINDNET_NOTE_SCOPE_HEADER_LEVEL` (Standard: `2` für `##`) + 3. Header-Namen müssen exakt (case-insensitive) übereinstimmen + #### Performance-Optimierung **Problem: Langsame Chat-Antworten** diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 3fced84..f065559 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -1,10 +1,10 @@ --- doc_type: developer_guide audience: developer -scope: workflow, testing, architecture, modules, modularization, agentic_rag, lazy_prompts +scope: workflow, testing, architecture, modules, modularization, agentic_rag, lazy_prompts, agentic_validation status: active -version: 3.1.1 -context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, WP-25a MoE, WP-25b Lazy-Prompt-Orchestration, Modul-Interna, Setup und Git-Workflow." +version: 4.5.8 +context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, WP-25a MoE, WP-25b Lazy-Prompt-Orchestration, WP-24c Phase 3 Agentic Edge Validation (v4.5.8), Modul-Interna, Setup und Git-Workflow." --- # Mindnet Developer Guide & Workflow @@ -225,7 +225,7 @@ Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit. | **`app/core/chunking/`** | Text-Segmentierung | `chunking_strategies.py` (Sliding/Heading), `chunking_processor.py` (Orchestrierung) | | **`app/core/database/`** | Qdrant-Infrastruktur | `qdrant.py` (Client), `qdrant_points.py` (Point-Mapping) | | **`app/core/graph/`** | Graph-Logik | `graph_subgraph.py` (Expansion), `graph_weights.py` (Scoring) | -| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (Two-Pass), `ingestion_validation.py` (Mistral-safe Parsing) | +| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (3-Phasen-Modell: Pre-Scan, Semantic Processing, Phase 3 Agentic Validation), `ingestion_validation.py` (Mistral-safe Parsing, Phase 3 Validierung) | | **`app/core/parser/`** | Markdown-Parsing | `parsing_markdown.py` (Frontmatter/Body), `parsing_scanner.py` (File-Scan) | | **`app/core/retrieval/`** | Suche & Scoring | `retriever.py` (Orchestrator), `retriever_scoring.py` (Mathematik) | | **`app/core/registry.py`** | SSOT & Utilities | Text-Bereinigung, Circular-Import-Fix | @@ -434,6 +434,14 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration* ``` *Ergebnis (WP-25b):* Hierarchische Prompt-Resolution mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell. Maximale Resilienz bei Modell-Fallbacks. +5. **Phase 3 Validierung (WP-24c v4.5.8):** Kanten mit `candidate:` Präfix werden automatisch in Phase 3 validiert: + * **Trigger:** Kanten in Header-Zonen (konfiguriert via `MINDNET_LLM_VALIDATION_HEADERS`) erhalten `candidate:` Präfix + * **Validierung:** Nutzt `ingest_validator` Profil (Temperature 0.0) für deterministische YES/NO Entscheidungen + * **Kontext-Optimierung:** Note-Scope nutzt `note_summary`, Chunk-Scope nutzt spezifischen Chunk-Text + * **Erfolg:** Entfernt `candidate:` Präfix, Kante wird persistiert + * **Ablehnung:** Kante wird zu `rejected_edges` hinzugefügt und **nicht** in DB geschrieben + * **Logging:** `🚀 [PHASE 3]` für Start, `✅ [PHASE 3] VERIFIED` für Erfolg, `🚫 [PHASE 3] REJECTED` für Ablehnung + ### Workflow B: Graph-Farben ändern 1. Öffne `app/frontend/ui_config.py`. 2. Bearbeite das Dictionary `GRAPH_COLORS`. diff --git a/docs/05_Development/05_testing_guide.md b/docs/05_Development/05_testing_guide.md index 445b0de..6c3151c 100644 --- a/docs/05_Development/05_testing_guide.md +++ b/docs/05_Development/05_testing_guide.md @@ -1,10 +1,10 @@ --- doc_type: developer_guide audience: developer, tester -scope: testing, quality_assurance, test_strategies +scope: testing, quality_assurance, test_strategies, agentic_validation status: active -version: 2.9.3 -context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG." +version: 4.5.8 +context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG und WP-24c Phase 3 Agentic Edge Validation." --- # Testing Guide @@ -272,16 +272,26 @@ class TestIngest(unittest.IsolatedAsyncioTestCase): ### 4.5 Ingestion-Tests **Was wird getestet:** -- Two-Pass Workflow +- Two-Pass Workflow (Pre-Scan, Semantic Processing) +- Phase 3 Agentic Edge Validation (WP-24c v4.5.8) - Change Detection (Hash-basiert) - Background Tasks - Smart Edge Allocation +- Automatische Spiegelkanten (Invers-Logik) **Tests:** - `tests/test_dialog_full_flow.py` - `tests/test_WP22_intelligence.py` - `scripts/import_markdown.py` (mit `--dry-run`) +**WP-24c Spezifische Tests (geplant):** +- candidate: Präfix-Setzung (Links in `### Unzugeordnete Kanten`) +- Phase 3 Validierung (VERIFIED/REJECTED) +- Kontext-Optimierung (Note-Scope nutzt Note-Summary, Chunk-Scope nutzt Chunk-Text) +- Automatische Spiegelkanten (Invers-Logik) +- Fehlertoleranz (transient vs. permanent) +- Rejected Edges Tracking (Kanten werden nicht persistiert) + --- ## 5. Continuous Integration diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 6456809..9ad4969 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -2,14 +2,14 @@ doc_type: roadmap audience: product_owner, developer status: active -version: 3.1.1 -context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25/25a/25b." +version: 4.5.8 +context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25/25a/25b/24c." --- # Mindnet Active Roadmap -**Aktueller Stand:** v3.1.1 (Post-WP25b: Lazy-Prompt-Orchestration & Full Resilience) -**Fokus:** Hierarchische Prompt-Resolution, Modell-spezifisches Tuning & maximale Resilienz. +**Aktueller Stand:** v4.5.8 (Post-WP24c: Phase 3 Agentic Edge Validation - Integrity Baseline) +**Fokus:** Chunk-Aware Multigraph-System, Agentic Edge Validation, Graph-Qualitätssicherung. | Phase | Fokus | Status | | :--- | :--- | :--- | @@ -52,6 +52,7 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio | **WP-25** | **Agentic Multi-Stream RAG Orchestration** | **Ergebnis:** Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine. Intent-basiertes Routing (Hybrid Fast/Slow-Path), parallele Wissens-Streams (Values, Facts, Biography, Risk, Tech), Stream-Tracing und Template-basierte Wissens-Synthese. | | **WP-25a** | **Mixture of Experts (MoE) & Fallback-Kaskade** | **Ergebnis:** Profilbasierte Experten-Architektur, rekursive Fallback-Kaskade, Pre-Synthesis Kompression, profilgesteuerte Ingestion und Embedding-Konsolidierung. | | **WP-25b** | **Lazy-Prompt-Orchestration & Full Resilience** | **Ergebnis:** Hierarchisches Prompt-Resolution-System (3-stufig), Lazy-Prompt-Loading, ultra-robustes Intent-Parsing, differenzierte Ingestion-Validierung und PROMPT-TRACE Logging. | +| **WP-24c** | **Phase 3 Agentic Edge Validation & Graph Integrity** | **Ergebnis:** Finales Validierungs-Gate für `candidate:` Kanten, dynamische Kontext-Optimierung (Note-Scope vs. Chunk-Scope), Verhinderung von "Geister-Verknüpfungen" und Graph-Qualitätssicherung. Transformation zu einem Chunk-Aware Multigraph-System. | ### 2.1 WP-22 Lessons Learned * **Architektur:** Die Trennung von `retriever.py` und `retriever_scoring.py` war notwendig, um LLM-Context-Limits zu wahren und die Testbarkeit der mathematischen Formeln zu erhöhen. @@ -241,6 +242,36 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h - Kontext-Budgeting: Intelligente Token-Verteilung - Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich - Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie + +### WP-24c: Phase 3 Agentic Edge Validation & Graph Integrity +**Status:** ✅ Fertig (v4.5.8) + +**Ergebnis:** Transformation des Systems von einem dokumentenbasierten RAG zu einem **Chunk-Aware Multigraph-System** mit finalem Validierungs-Gate für alle `candidate:` Kanten. Verhindert "Geister-Verknüpfungen" und sichert die Graph-Qualität durch agentische LLM-Validierung. + +**Kern-Features:** +1. **Phase 3 Validierungs-Gate:** Finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix in `rule_id` oder `provenance` +2. **Dynamische Kontext-Optimierung:** Intelligente Kontext-Auswahl basierend auf `scope`: + - **Note-Scope:** Nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) + - **Chunk-Scope:** Nutzt spezifischen Chunk-Text, falls verfügbar, sonst Fallback auf Note-Text +3. **Agentic Edge Validation:** LLM-basierte semantische Prüfung via `ingest_validator` Profil (Temperature 0.0) +4. **Fehlertoleranz:** Differenzierte Behandlung von transienten (Netzwerk) vs. permanenten (Config) Fehlern +5. **Graph-Qualitätssicherung:** Rejected Edges werden **nicht** in die Datenbank geschrieben, verhindert persistente "Geister-Verknüpfungen" + +**Technische Details:** +- Ingestion Processor v4.5.8: 3-Phasen-Modell (Pre-Scan, Semantic Processing, Phase 3 Validation) +- Ingestion Validation v2.14.0: `validate_edge_candidate()` mit MoE-Integration +- Kontext-Optimierung: Note-Summary/Text für Note-Scope, Chunk-Text für Chunk-Scope +- Logging: `🚀 [PHASE 3]` für Start, `✅ [PHASE 3] VERIFIED` für Erfolg, `🚫 [PHASE 3] REJECTED` für Ablehnung + +**System-Historie (v4.1.0 - v4.5.8):** +- v4.1.0 (Gold-Standard): Einführung der Scope-Awareness und Section-Filterung +- v4.4.1 (Clean-Context): Entfernung technischer Callouts vor Vektorisierung +- v4.5.0 - v4.5.3: Debugging & Härtung (Pydantic EdgeDTO, Retrieval-Tracer) +- v4.5.4: Attribut-Synchronisation (QueryHit-Modelle) +- v4.5.5: Effizienz-Optimierung (Context-Persistence) +- v4.5.7: Stabilitäts-Fix & Zonen-Mapping (UnboundLocalError, Zonen-Inversion) +- v4.5.8: Agentic Validation Gate (Phase 3, Kontext-Optimierung, Audit verifiziert) + --- ### WP-24 – Proactive Discovery & Agentic Knowledge Mining diff --git a/docs/README.md b/docs/README.md index f90b8f6..a8e1ab9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ doc_type: documentation_index audience: all status: active -version: 3.1.1 -context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" +version: 4.5.8 +context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation. Inkludiert WP-24c Phase 3 Agentic Edge Validation, automatische Spiegelkanten und Chunk-Aware Multigraph-System." --- # Mindnet Dokumentation -Willkommen in der Dokumentation von Mindnet v3.1.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. +Willkommen in der Dokumentation von Mindnet v4.5.8! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. ## 🚀 Schnellstart @@ -98,6 +98,10 @@ Historische Dokumentation: | Frage | Dokument | |-------|----------| | Wie starte ich mit Mindnet? | [Schnellstart](00_General/00_quickstart.md) | +| Wie verknüpfe ich Notizen? | [Knowledge Design - Edges](01_User_Manual/01_knowledge_design.md#4-edges--verlinkung) | +| Was sind automatische Spiegelkanten? | [Knowledge Design - Spiegelkanten](01_User_Manual/01_knowledge_design.md#43-automatische-spiegelkanten-invers-logik---wp-24c-v458) | +| Was ist Phase 3 Validierung? | [Knowledge Design - Phase 3](01_User_Manual/01_knowledge_design.md#44-explizite-vs-validierte-kanten-phase-3-validierung---wp-24c-v458) | +| Was sind Note-Scope Zonen? | [Note-Scope Zonen](01_User_Manual/NOTE_SCOPE_ZONEN.md) | | Wie nutze ich den Chat? | [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) | | Wie strukturiere ich meine Notizen? | [Knowledge Design](01_User_Manual/01_knowledge_design.md) | | Wie schreibe ich für den Digitalen Zwilling? | [Authoring Guidelines](01_User_Manual/01_authoring_guidelines.md) | @@ -150,5 +154,5 @@ Falls du Verbesserungsvorschläge für die Dokumentation hast oder Fehler findes --- **Letzte Aktualisierung:** 2025-01-XX -**Version:** 2.9.1 +**Version:** 4.5.8 (WP-24c: Phase 3 Agentic Edge Validation - Integrity Baseline)