Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity

21 Releases 37 Tags

RSS Feed
  • v3.2.0 d0012355b9
    Compare

    Mindnet v3.2.0 - Feature Release - Phase 3 Agentic Edge Validation & Chunk-Aware Multigraph-System
    All checks were successful
    Deploy mindnet to llm-node / deploy (push) Successful in 4s
    Details
    Stable

    Lars released this 2026-01-12 10:55:12 +01:00 | 13 commits to main since this release

    🎯 Ü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:

    # --- 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):

      Diese Entscheidung [[rel:depends_on Performance-Analyse]] wurde getroffen.
      • Sofortige Übernahme, höchste Priorität, keine Validierung

    2. Validierte Links (für explorative Verbindungen):

      ### 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):

      ## 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:

    # --- 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:

    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:

    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:

    git pull origin main
# oder
git checkout WP24c
git merge main

    2. Dependencies aktualisieren:

    source .venv/bin/activate
pip install -r requirements.txt

    3. ENV-Variablen konfigurieren (optional):

    # Fügen Sie die neuen Variablen zu .env hinzu
nano .env
# oder
nano config/prod.env

    4. Services neu starten:

    systemctl restart mindnet-prod
systemctl restart mindnet-ui-prod

    5. Health Check:

    curl http://localhost:8001/healthz
curl http://localhost:8501/healthz

    6. Logs prüfen:

    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:

    ---
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:

    ---
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:

    [[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).

    Downloads