Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity

WP4d #16

Merged
Lars merged 33 commits from WP4d into main 2025-12-30 12:25:33 +01:00
Conversation 0 Commits 33 Files Changed 23 +335
2 changed files with 335 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 39fb821481 - Show all commits

99
docs/99_Archive/WP4d_merge_commit.md Normal file
View File

@ -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]
```

236
docs/99_Archive/WP4d_release_notes.md Normal file
View File

@ -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)