21 Releases 37 Tags

RSS Feed

• v2.9.2 cd5056d4c9

  Compare

  v.2.9.2 Section-basierte Links, Atomic Section Logic & Registry-First Profiling Stable

  Lars released this 2025-12-30 12:27:36 +01:00 | 123 commits to main since this release

  Release Notes: Mindnet v2.9.2 (WP4d)

  🎯 Übersicht

  Diese Version führt Section-basierte Links ein, verbessert das Chunking durch Atomic Section Logic und implementiert Registry-First Profiling für konsistentere Konfigurationsauflösung. Die Änderungen erfordern einen vollständigen Re-Import bestehender Vaults.

  ---

  ✨ Neue Features

  Section-basierte Links (Deep-Links)

  Mindnet unterstützt nun Deep-Links zu spezifischen Abschnitten innerhalb einer Note:

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

  Vorteile:

  • Mehrere Links zur gleichen Note möglich (verschiedene Sections)
  • Präzise Kontext-Ladung (nur relevanter Abschnitt)
  • Keine "Phantom-Knoten" mehr durch korrekte Trennung von Note-Name und Abschnitt

  Technische Details:

  • Links werden in target_id="Note" und target_section="Section" aufgeteilt
  • Edge-ID enthält variant (Section) für Multigraph-Support
  • Semantische Deduplizierung basiert auf src->tgt:kind@sec Key

  Atomic Section Logic (Chunking v3.9.9)

  Das Chunking hält nun Sektions-Überschriften und deren Inhalte atomar zusammen:

  "Pack-and-Carry-Over" Verfahren:

  • Regel 1 & 2: Sektionen werden zusammengepackt, wenn sie in den Token-Limit passen
  • Regel 3: Zu große Sektionen werden intelligent zerlegt, Rest wird zurück in Queue gelegt
  • H1-Context Preservation: Dokumenttitel wird als Breadcrumb in alle Chunks injiziert

  Vorteile:

  • Keine getrennten Überschriften mehr
  • Bessere semantische Kohärenz in Chunks
  • Verbesserte Retrieval-Qualität durch vollständigen Kontext

  Registry-First Profiling (v2.13.12)

  Die Konfigurationsauflösung folgt nun einer klaren Hierarchie:

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

  Impact:

  • Note-Typen wie value erhalten automatisch das korrekte Profil (structured_smart_edges_strict)
  • Keine manuellen Overrides mehr nötig für Standard-Typen
  • Konsistente Metadaten in Qdrant

  ---

  🔧 Verbesserungen

  Extraction & Parsing

  • Multi-line Callout-Blocks: Korrekte Verarbeitung von mehrzeiligen [!edge] Callouts
  • Robuste Fallbacks: "Headless" Blocks werden korrekt behandelt
  • Liberalisierte Regex: Unterstützung für Umlaute und Sonderzeichen in Link-Targets

  Format-agnostische De-Duplizierung

  • Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt
  • Verhindert Dopplungen, wenn Kanten bereits via [!edge] Callout vorhanden sind
  • Ziel-basierte Prüfung statt String-Match

  Deterministic Hashing

  • full-Hash inkludiert strategische Parameter (split_level, strict_heading_split)
  • Konfigurationsänderungen im Frontmatter lösen zwingend Re-Import aus
  • Zuverlässigere Change Detection

  ---

  🐛 Bugfixes

  • ✅ Behoben: Mehrere Links zur gleichen Note in einem Callout-Block wurden zu einer Kante gemergt
  • ✅ Behoben: "Phantom-Knoten" durch Einbeziehung des Anchors in target_id
  • ✅ Behoben: Redundante [[rel:...]] Links in Chunks
  • ✅ Behoben: Inkonsistente Metadaten in Qdrant durch fehlerhafte Profil-Auflösung
  • ✅ Behoben: TypeError durch Parameter-Mismatch zwischen Orchestrator und Strategien

  ---

  ⚠️ Breaking Changes & Migration

  Migration erforderlich

  WICHTIG: Nach dem Update auf v2.9.1 ist ein vollständiger Re-Import erforderlich:

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

  Warum?

  • Behebt "Phantom-Knoten" durch korrekte Aufteilung von [[Note#Section]] Links
  • Konsolidiert Edge-Struktur mit neuem target_section Feld
  • Aktualisiert Chunking basierend auf Atomic Section Logic

  Was passiert beim Re-Import?

  • Alle bestehenden Links werden neu geparst und in target_id + target_section aufgeteilt
  • Chunks werden mit neuer Atomic Section Logic neu generiert
  • Edge-Struktur wird konsolidiert (Multigraph-Support)

  Dauer: Abhängig von Vault-Größe (typischerweise 5-30 Minuten)

  ---

  📚 API-Änderungen

  EdgeDTO erweitert

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

  Impact für API-Consumer:

  • Graph-Endpunkte (/graph/{note_id}) enthalten nun target_section in Edge-Objekten
  • Frontend kann Section-Informationen für präzisere Visualisierung nutzen

  ---

  📖 Dokumentation

  Alle relevanten Dokumente wurden aktualisiert:

  • ✅ 03_tech_data_model.md: Edge Payload Schema mit target_section
  • ✅ 02_concept_graph_logic.md: Section-basierte Links & Multigraph-Support
  • ✅ 03_tech_ingestion_pipeline.md: Chunking-Strategien, Registry-First Profiling
  • ✅ 03_tech_api_reference.md: EdgeDTO mit target_section
  • ✅ 01_knowledge_design.md: Deep-Links dokumentiert
  • ✅ 00_glossary.md: Neue Begriffe ergänzt
  • ✅ 04_admin_operations.md: Migration-Hinweis

  ---

  🔄 Technische Details

  Geänderte Module

  Graph Topology:

  • app/core/graph/graph_utils.py: parse_link_target() für Section-Extraktion
  • app/core/graph/graph_derive_edges.py: target_section in Edge-Payload
  • app/core/graph/graph_extractors.py: Multi-line Callout-Parser

  Chunking:

  • app/core/chunking/chunking_strategies.py: Atomic Section Logic (v3.9.9)
  • app/core/chunking/chunking_propagation.py: Format-agnostische De-Duplizierung

  Ingestion:

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

  Database:

  • app/core/database/qdrant.py: Keyword-Index für target_section
  • app/core/database/qdrant_points.py: Explizites Durchreichen von target_section

  API:

  • app/models/dto.py: EdgeDTO mit target_section Feld (v0.6.7)

  Versionsnummern

  • Graph Topology: v2.9.1
  • Chunking Strategies: v3.9.9
  • Ingestion Processor: v2.13.12
  • API DTO: v0.6.7

  ---

  🚀 Upgrade-Pfad

  Für Administratoren

  1. Backup erstellen:

     docker stop qdrant
     tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_data
     docker start qdrant
     

  2. Code aktualisieren:

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

  3. Re-Import durchführen:

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

  4. Services neu starten:

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

  Für Entwickler

  • Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
  • Frontend kann target_section Feld in Edge-Objekten nutzen (optional)

  ---

  📝 Bekannte Einschränkungen

  • Migration-Dauer: Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen
  • 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:

  • Konsistenz zwischen Code und Dokumentation
  • Vollständige Abdeckung aller Rollen (Entwickler, Administratoren, Anwender, Tester, Deployment)
  • Klare Migration-Pfade

  ---

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

  Downloads

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