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

7.3 KiB
Raw Permalink Blame History

Release Notes: Mindnet v2.9.1 (WP4d)

Release Date: 2025-01-XX
Type: Feature Release mit Breaking Changes
Branch: 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