Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
78fbc9b31b
mindnet/docs/99_Archive/WP15c_release_notes.md

9.3 KiB
Raw Blame History

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