237 lines
7.3 KiB
Markdown
237 lines
7.3 KiB
Markdown
# 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:
|
||
|
||
```markdown
|
||
[[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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```python
|
||
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:**
|
||
```bash
|
||
docker stop qdrant
|
||
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_data
|
||
docker start qdrant
|
||
```
|
||
|
||
2. **Code aktualisieren:**
|
||
```bash
|
||
git pull origin main
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
3. **Re-Import durchführen:**
|
||
```bash
|
||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||
```
|
||
|
||
4. **Services neu starten:**
|
||
```bash
|
||
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](../04_Operations/04_admin_operations.md)
|
||
|