diff --git a/docs/99_Archive/WP4d_merge_commit.md b/docs/99_Archive/WP4d_merge_commit.md new file mode 100644 index 0000000..298c055 --- /dev/null +++ b/docs/99_Archive/WP4d_merge_commit.md @@ -0,0 +1,99 @@ +# Branch Merge Commit Message: WP4d + +``` +feat: Section-basierte Links, Atomic Section Chunking & Registry-First Profiling (v2.9.1) + +## Graph Topology & Edge Management + +### Section-basierte Links (Multigraph-Support) +- Split `[[Note#Section]]` Links in `target_id="Note"` und `target_section="Section"` +- Edge-ID enthält nun `variant` (Section), ermöglicht mehrere Kanten zwischen denselben Knoten +- Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key +- Behebt "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt + +**Geänderte Dateien:** +- `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/database/qdrant.py`: Keyword-Index für `target_section` +- `app/core/database/qdrant_points.py`: Explizites Durchreichen von `target_section` +- `app/models/dto.py`: `EdgeDTO` mit `target_section` Feld + +### Extraction & Parsing Verbesserungen +- Multi-line Callout-Blocks korrekt verarbeitet (stop-check logic) +- Robuster Fallback für "headless" Blocks (split chunks) +- Liberalisierte Regex für Umlaute und Sonderzeichen in Targets + +**Geänderte Dateien:** +- `app/core/graph/graph_extractors.py`: Multi-line Callout-Parser, erweiterte Regex + +## Chunking & Ingestion (v3.9.9 / v2.13.12) + +### Atomic Section Logic (v3.9.9) +- Vollständige Implementierung des "Pack-and-Carry-Over" Verfahrens (Regel 1-3) +- Sektions-Überschriften und Inhalte bleiben atomar in Chunks +- H1-Context Preservation: Dokumenttitel als Breadcrumb in Embedding-Fenster +- Signature Alignment: Parameter-Synchronisierung (`context_prefix` statt `doc_title`) + +**Geänderte Dateien:** +- `app/core/chunking/chunking_strategies.py`: Atomic Section Logic implementiert + +### Format-agnostische De-Duplizierung +- Prüfung auf vorhandene Kanten basiert auf Ziel (`target`), nicht String-Match +- Verhindert Dopplung von Kanten, die bereits via `[!edge]` Callout vorhanden sind +- Global Pool Integration für unzugeordnete Kanten + +**Geänderte Dateien:** +- `app/core/chunking/chunking_propagation.py`: Ziel-basierte Prüfung + +### Registry-First Profiling (v2.13.12) +- Korrekte Hierarchie: Frontmatter > types.yaml Typ-Config > Global Defaults +- Hard-Fallback auf `sliding_standard` nur wenn keine Konfiguration existiert +- Automatische Anwendung korrekter Profile basierend auf Note-Typ + +### Deterministic Hashing +- `full`-Hash inkludiert strategische Parameter (`split_level`, `strict_heading_split`) +- Konfigurationsänderungen im Frontmatter lösen zwingend Re-Import aus + +**Geänderte Dateien:** +- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling, Deterministic Hashing + +## Impact & Breaking Changes + +### Migration erforderlich +**WICHTIG:** Vollständiger Re-Import erforderlich für bestehende Vaults: +```bash +python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force +``` + +**Grund:** +- Behebt "Phantom-Knoten" durch korrekte Aufteilung von `[[Note#Section]]` Links +- Konsolidiert Edge-Struktur mit `target_section` Feld +- Aktualisiert Chunking basierend auf neuen Strategien + +### Fixes +- ✅ Resolves: Mehrere Links zur gleichen Note in einem Callout-Block wurden zu einer Kante gemergt +- ✅ Resolves: "Phantom-Knoten" durch Einbeziehung des Anchors in `target_id` +- ✅ Resolves: Redundante `[[rel:...]]` Links in Chunks +- ✅ Resolves: Inkonsistente Metadaten in Qdrant durch Registry-First Profiling + +## Dokumentation + +Alle relevanten Dokumente 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 + +## Versionen + +- Graph Topology: v2.9.1 +- Chunking Strategies: v3.9.9 +- Ingestion Processor: v2.13.12 +- API DTO: v0.6.7 + +Closes #[issue-number] +``` + diff --git a/docs/99_Archive/WP4d_release_notes.md b/docs/99_Archive/WP4d_release_notes.md new file mode 100644 index 0000000..4653ceb --- /dev/null +++ b/docs/99_Archive/WP4d_release_notes.md @@ -0,0 +1,236 @@ +# 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) +