21 Releases 37 Tags

RSS Feed

• v2.9.3 67d7154328

  Compare

  Feature Release - Multigraph & Diversity Engine Stable

  Lars released this 2025-12-31 16:57:45 +01:00 | 115 commits to main since this release

  Release Notes: Mindnet v2.9.3 (WP15c)

  Release Date: 2025-12-31
  Type: Feature Release - Multigraph & Diversity Engine
  Branch: WP15c

  ---

  🎯 Übersicht

  Diese Version transformiert den Graphen von einer flachen Struktur zu einem hochpräzisen Multigraphen mit intelligenter Ergebnis-Filterung (Diversity) und gewichtetem Scoring. Die Änderungen verbessern die Retrieval-Qualität durch präzise Sektions-Links, Note-Level Diversity Pooling und mathematische Super-Edge Aggregation.

  ---

  ✨ Neue Features

  Section-Präzision & Multigraph-Modus

  Mindnet erkennt nun präzise Obsidian-Anker ([[Note#Section]]) und Self-Links ([[#Section]]):

  Obsidian-Anker:

  [[rel:based_on Mein Leitbild#P3 – Disziplin]]
  

  Self-Links:

  [[#P3 – Disziplin]]  → Verlinkt innerhalb derselben Note
  

  Technische Details:

  • Links werden in target_id="Note" und target_section="Section" aufgelöst
  • Edge-IDs enthalten variant (Section) für eindeutige Identifikation
  • Multigraph-Modus: Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
  • Verhindert "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt

  Provenance Firewall (Edge Registry v0.8.0)

  Die Edge Registry stellt sicher, dass System-Kanten (next, prev, belongs_to) ausschließlich durch interne Struktur-Prozesse und nicht durch Nutzer oder KI manipuliert werden können:

  Schutz-Mechanismus:

  • System-Kanten dürfen nur mit provenance="structure" gesetzt werden
  • Alle anderen Provenienzen (explicit, semantic_ai, inherited, global_pool, rule) werden blockiert
  • Automatischer Fallback auf related_to bei unerlaubter Verwendung
  • Logging in data/logs/unknown_edges.jsonl für Admin-Review

  Vorteil: Garantiert Graph-Integrität und verhindert Manipulationen an der internen Struktur.

  Note-Level Diversity Pooling

  Um das "Note-Flooding" (Dominanz einer einzigen Notiz durch viele ähnliche Chunks) zu verhindern, wird pro note_id nur noch der relevanteste Treffer im Endergebnis behalten:

  Workflow:

  1. Alle Kandidaten werden nach finalem Score sortiert
  2. Pro note_id wird nur der Hit mit dem höchsten total_score behalten
  3. Begrenzung auf top_k nach dem Diversity-Pooling

  Impact: Verhindert, dass 10 Chunks derselben Note andere KeyNotes verdrängen. Erhöht die Vielfalt der Suchergebnisse.

  Super-Edge Aggregation

  Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer "Super-Edge" aggregiert:

  Aggregations-Logik:

  • Primäre Kante (höchstes Gewicht) zählt voll
  • Jede weitere Kante (z.B. auf eine andere Sektion) wird mit Dämpfungsfaktor 0.1 gewichtet
  • Formel: total_weight = primary_weight + sum(secondary_weights * 0.1)

  Vorteil: Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections derselben Note.

  Metadaten:

  • is_super_edge: Flag für Explanation Layer
  • edge_count: Anzahl der aggregierten Kanten

  ---

  🔧 Verbesserungen

  Mathematisches Scoring (WP-22 Integration)

  Die Engine berechnet den finalen Score basierend auf einer hybriden Multiplikations-Formel:

  Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)
  

  Komponenten:

  • Base Score: Semantic * StatusMult (Lifecycle-Filter)
  • Status-Gatekeeper: stable = 1.2, draft = 0.5, active = 1.0
  • Boosts: TypeBoost + EdgeBonus + CentBonus (additiv, dann multiplikativ auf Base)
  • Graph Boost Factor: Intent-spezifische Verstärkung (1.5x bei aktivem Intent)

  Vorteil: Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt.

  Explanation Layer

  Der Retriever liefert detaillierte Begründungen für jeden Bonus:

  • Sektions-Links (z.B. "Link zu 'Mein Leitbild#P3 – Disziplin'")
  • Hub-Zentralität (z.B. "Note ist zentraler Knoten mit 5 eingehenden Kanten")
  • Super-Edge-Informationen (z.B. "3 parallele Kanten aggregiert")
  • Provenance-Informationen (z.B. "Explizite Kante vom Nutzer")

  Impact: Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen.

  Metadaten-Persistenz

  Der In-Memory Subgraph und der Datenbank-Adapter wurden so erweitert, dass Metadaten durchgängig erhalten bleiben:

  Erhaltene Metadaten:

  • target_section: Abschnitts-Name für präzise Verlinkung
  • provenance: Herkunft der Kante (explicit, smart, rule, structure)
  • confidence: Vertrauenswürdigkeit (0.0 - 1.0)
  • is_super_edge: Flag für aggregierte Kanten

  Vorteil: Ermöglicht präzises Retrieval-Reasoning und Explanation Layer.

  Profil-Synchronisation (Ingestion v2.13.12)

  Der Ingestion-Prozessor löst Chunking-Profile hierarchisch über die types.yaml auf:

  Hierarchie:

  1. Frontmatter (höchste Priorität)
  2. types.yaml Typ-Config
  3. Global Defaults

  Impact: Konsistente Verarbeitung je nach Notiz-Typ. Note-Typen wie value erhalten automatisch das korrekte Profil (structured_smart_edges_strict).

  ---

  🐛 Bugfixes

  • ✅ Behoben: "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section in target_id
  • ✅ Behoben: Score-Explosionen durch multiple Links auf verschiedene Sections
  • ✅ Behoben: "Note-Flooding" durch fehlende Diversity-Filterung
  • ✅ Behoben: Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
  • ✅ Behoben: Manipulation von System-Kanten durch Provenance Firewall

  ---

  ⚠️ Breaking Changes & Migration

  Keine Migration erforderlich

  WICHTIG: Diese Version ist rückwärtskompatibel. Bestehende Vaults funktionieren ohne Re-Import.

  Empfehlung: Optionaler Re-Import für optimale Nutzung der neuen Features:

  python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
  

  Was passiert beim Re-Import?

  • Bestehende Links werden neu geparst und in target_id + target_section aufgeteilt
  • Self-Links ([[#Section]]) werden korrekt aufgelöst
  • Edge-Struktur wird konsolidiert (Multigraph-Support)

  ---

  📚 API-Änderungen

  Keine Breaking Changes

  Die API bleibt vollständig kompatibel. Neue Metadaten werden optional zurückgegeben:

  EdgeDTO (erweitert):

  class EdgeDTO(BaseModel):
      # ... bestehende Felder ...
      target_section: Optional[str] = None  # Neu: Abschnitts-Name
      is_super_edge: Optional[bool] = False    # Neu: Aggregations-Flag
  

  QueryResponse (erweitert):

  • Explanation Layer enthält nun Super-Edge-Informationen
  • Metadaten wie target_section werden in Edge-Objekten zurückgegeben

  ---

  📖 Dokumentation

  Alle relevanten Dokumente wurden aktualisiert:

  • ✅ 02_concept_graph_logic.md: Provenance Firewall, Self-Links, Multigraph-Support
  • ✅ 03_tech_retrieval_scoring.md: Hybrid Scoring Formula, Note-Level Diversity, Super-Edge Aggregation
  • ✅ 03_tech_data_model.md: Section-Support, Metadaten-Persistenz
  • ✅ 03_tech_ingestion_pipeline.md: Registry-First Profiling (bereits dokumentiert)

  ---

  🔄 Technische Details

  Geänderte Module

  Graph Topology:

  • app/services/edge_registry.py: Provenance Firewall (v0.8.0)
  • app/core/graph/graph_utils.py: parse_link_target() für Section-Extraktion & Self-Links (v1.1.2)
  • app/core/graph/graph_derive_edges.py: Multigraph-Support, target_section in Edge-Payload (v1.1.2)
  • app/core/graph/graph_subgraph.py: Metadaten-Persistenz (v1.2.0)
  • app/core/graph/graph_db_adapter.py: Vollständige Metadaten-Durchreichung (v1.1.1)

  Retrieval:

  • app/core/retrieval/retriever.py: Note-Level Diversity Pooling, Super-Edge Aggregation (v0.7.0)
  • app/core/retrieval/retriever_scoring.py: Hybrid Scoring Formula (v1.0.3)

  Ingestion:

  • app/core/ingestion/ingestion_processor.py: Registry-First Profiling (v2.13.12)

  Versionsnummern

  • Edge Registry: v0.8.0
  • Graph Utils / Derive Edges: v1.1.2
  • Graph Subgraph: v1.2.0
  • Graph DB Adapter: v1.1.1
  • Retriever: v0.7.0
  • Retriever Scoring: v1.0.3
  • Ingestion Processor: v2.13.12

  ---

  🚀 Upgrade-Pfad

  Für Administratoren

  1. Code aktualisieren:

     git pull origin main
     source .venv/bin/activate
     pip install -r requirements.txt
     

  2. Services neu starten:

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

  3. Optional: Re-Import für optimale Nutzung:

     python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
     

  Für Entwickler

  • Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
  • Frontend kann neue Metadaten (target_section, is_super_edge) optional nutzen
  • Explanation Layer enthält nun Super-Edge-Informationen

  ---

  📝 Bekannte Einschränkungen

  • Re-Import-Dauer: Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen (optional)
  • Temporärer Speicher: Während des Re-Imports kann Qdrant-Speicher temporär ansteigen

  ---

  🙏 Danksagungen

  Diese Version wurde durch umfangreiche Code-Analyse und Dokumentationsprüfung ermöglicht. Besonderer Fokus lag auf:

  • Transformation zu einem hochpräzisen Multigraphen
  • Intelligente Ergebnis-Filterung (Diversity Engine)
  • Mathematisches Scoring mit gewichteten Boni
  • Graph-Integrität durch Provenance Firewall

  ---

  Vollständige Changelog: Siehe Git-Commits für detaillierte Änderungen
  Support: Bei Fragen siehe Admin Operations Guide

  Downloads

  • Source Code (ZIP)
  • Source Code (TAR.GZ)