268 lines
9.3 KiB
Markdown
268 lines
9.3 KiB
Markdown
# Release Notes: Mindnet v2.9.1 (WP15c)
|
||
|
||
**Release Date:** 2025-12-31
|
||
**Type:** Feature Release - Multigraph & Diversity Engine
|
||
**Branch:** WP15c
|
||
|
||
---
|
||
|
||
## 🎯 Übersicht
|
||
|
||
Diese Version transformiert den Graphen von einer flachen Struktur zu einem **hochpräzisen Multigraphen** mit intelligenter Ergebnis-Filterung (Diversity) und gewichtetem Scoring. Die Änderungen verbessern die Retrieval-Qualität durch präzise Sektions-Links, Note-Level Diversity Pooling und mathematische Super-Edge Aggregation.
|
||
|
||
---
|
||
|
||
## ✨ Neue Features
|
||
|
||
### Section-Präzision & Multigraph-Modus
|
||
|
||
Mindnet erkennt nun präzise **Obsidian-Anker** (`[[Note#Section]]`) und **Self-Links** (`[[#Section]]`):
|
||
|
||
**Obsidian-Anker:**
|
||
```markdown
|
||
[[rel:based_on Mein Leitbild#P3 – Disziplin]]
|
||
```
|
||
|
||
**Self-Links:**
|
||
```markdown
|
||
[[#P3 – Disziplin]] → Verlinkt innerhalb derselben Note
|
||
```
|
||
|
||
**Technische Details:**
|
||
- Links werden in `target_id="Note"` und `target_section="Section"` aufgelöst
|
||
- Edge-IDs enthalten `variant` (Section) für eindeutige Identifikation
|
||
- **Multigraph-Modus:** Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
|
||
- Verhindert "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt
|
||
|
||
### Provenance Firewall (Edge Registry v0.8.0)
|
||
|
||
Die **Edge Registry** stellt sicher, dass System-Kanten (`next`, `prev`, `belongs_to`) ausschließlich durch interne Struktur-Prozesse und nicht durch Nutzer oder KI manipuliert werden können:
|
||
|
||
**Schutz-Mechanismus:**
|
||
- System-Kanten dürfen nur mit `provenance="structure"` gesetzt werden
|
||
- Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden blockiert
|
||
- Automatischer Fallback auf `related_to` bei unerlaubter Verwendung
|
||
- Logging in `data/logs/unknown_edges.jsonl` für Admin-Review
|
||
|
||
**Vorteil:** Garantiert Graph-Integrität und verhindert Manipulationen an der internen Struktur.
|
||
|
||
### Note-Level Diversity Pooling
|
||
|
||
Um das **"Note-Flooding"** (Dominanz einer einzigen Notiz durch viele ähnliche Chunks) zu verhindern, wird pro `note_id` nur noch der relevanteste Treffer im Endergebnis behalten:
|
||
|
||
**Workflow:**
|
||
1. Alle Kandidaten werden nach finalem Score sortiert
|
||
2. Pro `note_id` wird nur der Hit mit dem höchsten `total_score` behalten
|
||
3. Begrenzung auf `top_k` nach dem Diversity-Pooling
|
||
|
||
**Impact:** Verhindert, dass 10 Chunks derselben Note andere KeyNotes verdrängen. Erhöht die Vielfalt der Suchergebnisse.
|
||
|
||
### Super-Edge Aggregation
|
||
|
||
Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer **"Super-Edge"** aggregiert:
|
||
|
||
**Aggregations-Logik:**
|
||
- Primäre Kante (höchstes Gewicht) zählt voll
|
||
- Jede weitere Kante (z.B. auf eine andere Sektion) wird mit Dämpfungsfaktor **0.1** gewichtet
|
||
- Formel: `total_weight = primary_weight + sum(secondary_weights * 0.1)`
|
||
|
||
**Vorteil:** Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections derselben Note.
|
||
|
||
**Metadaten:**
|
||
- `is_super_edge`: Flag für Explanation Layer
|
||
- `edge_count`: Anzahl der aggregierten Kanten
|
||
|
||
---
|
||
|
||
## 🔧 Verbesserungen
|
||
|
||
### Mathematisches Scoring (WP-22 Integration)
|
||
|
||
Die Engine berechnet den finalen Score basierend auf einer **hybriden Multiplikations-Formel**:
|
||
|
||
```
|
||
Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)
|
||
```
|
||
|
||
**Komponenten:**
|
||
- **Base Score:** `Semantic * StatusMult` (Lifecycle-Filter)
|
||
- **Status-Gatekeeper:** `stable` = 1.2, `draft` = 0.5, `active` = 1.0
|
||
- **Boosts:** `TypeBoost + EdgeBonus + CentBonus` (additiv, dann multiplikativ auf Base)
|
||
- **Graph Boost Factor:** Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
|
||
|
||
**Vorteil:** Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt.
|
||
|
||
### Explanation Layer
|
||
|
||
Der Retriever liefert detaillierte Begründungen für jeden Bonus:
|
||
- Sektions-Links (z.B. "Link zu 'Mein Leitbild#P3 – Disziplin'")
|
||
- Hub-Zentralität (z.B. "Note ist zentraler Knoten mit 5 eingehenden Kanten")
|
||
- Super-Edge-Informationen (z.B. "3 parallele Kanten aggregiert")
|
||
- Provenance-Informationen (z.B. "Explizite Kante vom Nutzer")
|
||
|
||
**Impact:** Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen.
|
||
|
||
### Metadaten-Persistenz
|
||
|
||
Der In-Memory Subgraph und der Datenbank-Adapter wurden so erweitert, dass Metadaten durchgängig erhalten bleiben:
|
||
|
||
**Erhaltene Metadaten:**
|
||
- `target_section`: Abschnitts-Name für präzise Verlinkung
|
||
- `provenance`: Herkunft der Kante (explicit, smart, rule, structure)
|
||
- `confidence`: Vertrauenswürdigkeit (0.0 - 1.0)
|
||
- `is_super_edge`: Flag für aggregierte Kanten
|
||
|
||
**Vorteil:** Ermöglicht präzises Retrieval-Reasoning und Explanation Layer.
|
||
|
||
### Profil-Synchronisation (Ingestion v2.13.12)
|
||
|
||
Der Ingestion-Prozessor löst Chunking-Profile hierarchisch über die `types.yaml` auf:
|
||
|
||
**Hierarchie:**
|
||
1. **Frontmatter** (höchste Priorität)
|
||
2. **types.yaml Typ-Config**
|
||
3. **Global Defaults**
|
||
|
||
**Impact:** Konsistente Verarbeitung je nach Notiz-Typ. Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`).
|
||
|
||
---
|
||
|
||
## 🐛 Bugfixes
|
||
|
||
- ✅ **Behoben:** "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section in `target_id`
|
||
- ✅ **Behoben:** Score-Explosionen durch multiple Links auf verschiedene Sections
|
||
- ✅ **Behoben:** "Note-Flooding" durch fehlende Diversity-Filterung
|
||
- ✅ **Behoben:** Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
|
||
- ✅ **Behoben:** Manipulation von System-Kanten durch Provenance Firewall
|
||
|
||
---
|
||
|
||
## ⚠️ Breaking Changes & Migration
|
||
|
||
### Keine Migration erforderlich
|
||
|
||
**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.
|
||
|
||
**Empfehlung:** Optionaler Re-Import für optimale Nutzung der neuen Features:
|
||
```bash
|
||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||
```
|
||
|
||
**Was passiert beim Re-Import?**
|
||
- Bestehende Links werden neu geparst und in `target_id` + `target_section` aufgeteilt
|
||
- Self-Links (`[[#Section]]`) werden korrekt aufgelöst
|
||
- Edge-Struktur wird konsolidiert (Multigraph-Support)
|
||
|
||
---
|
||
|
||
## 📚 API-Änderungen
|
||
|
||
### Keine Breaking Changes
|
||
|
||
Die API bleibt vollständig kompatibel. Neue Metadaten werden optional zurückgegeben:
|
||
|
||
**EdgeDTO (erweitert):**
|
||
```python
|
||
class EdgeDTO(BaseModel):
|
||
# ... bestehende Felder ...
|
||
target_section: Optional[str] = None # Neu: Abschnitts-Name
|
||
is_super_edge: Optional[bool] = False # Neu: Aggregations-Flag
|
||
```
|
||
|
||
**QueryResponse (erweitert):**
|
||
- Explanation Layer enthält nun Super-Edge-Informationen
|
||
- Metadaten wie `target_section` werden in Edge-Objekten zurückgegeben
|
||
|
||
---
|
||
|
||
## 📖 Dokumentation
|
||
|
||
Alle relevanten Dokumente wurden aktualisiert:
|
||
|
||
- ✅ `02_concept_graph_logic.md`: Provenance Firewall, Self-Links, Multigraph-Support
|
||
- ✅ `03_tech_retrieval_scoring.md`: Hybrid Scoring Formula, Note-Level Diversity, Super-Edge Aggregation
|
||
- ✅ `03_tech_data_model.md`: Section-Support, Metadaten-Persistenz
|
||
- ✅ `03_tech_ingestion_pipeline.md`: Registry-First Profiling (bereits dokumentiert)
|
||
|
||
---
|
||
|
||
## 🔄 Technische Details
|
||
|
||
### Geänderte Module
|
||
|
||
**Graph Topology:**
|
||
- `app/services/edge_registry.py`: Provenance Firewall (v0.8.0)
|
||
- `app/core/graph/graph_utils.py`: `parse_link_target()` für Section-Extraktion & Self-Links (v1.1.2)
|
||
- `app/core/graph/graph_derive_edges.py`: Multigraph-Support, `target_section` in Edge-Payload (v1.1.2)
|
||
- `app/core/graph/graph_subgraph.py`: Metadaten-Persistenz (v1.2.0)
|
||
- `app/core/graph/graph_db_adapter.py`: Vollständige Metadaten-Durchreichung (v1.1.1)
|
||
|
||
**Retrieval:**
|
||
- `app/core/retrieval/retriever.py`: Note-Level Diversity Pooling, Super-Edge Aggregation (v0.7.0)
|
||
- `app/core/retrieval/retriever_scoring.py`: Hybrid Scoring Formula (v1.0.3)
|
||
|
||
**Ingestion:**
|
||
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12)
|
||
|
||
### Versionsnummern
|
||
|
||
- Edge Registry: **v0.8.0**
|
||
- Graph Utils / Derive Edges: **v1.1.2**
|
||
- Graph Subgraph: **v1.2.0**
|
||
- Graph DB Adapter: **v1.1.1**
|
||
- Retriever: **v0.7.0**
|
||
- Retriever Scoring: **v1.0.3**
|
||
- Ingestion Processor: **v2.13.12**
|
||
|
||
---
|
||
|
||
## 🚀 Upgrade-Pfad
|
||
|
||
### Für Administratoren
|
||
|
||
1. **Code aktualisieren:**
|
||
```bash
|
||
git pull origin main
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. **Services neu starten:**
|
||
```bash
|
||
sudo systemctl restart mindnet-prod
|
||
sudo systemctl restart mindnet-ui-prod
|
||
```
|
||
|
||
3. **Optional: Re-Import für optimale Nutzung:**
|
||
```bash
|
||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||
```
|
||
|
||
### Für Entwickler
|
||
|
||
- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
|
||
- Frontend kann neue Metadaten (`target_section`, `is_super_edge`) optional nutzen
|
||
- Explanation Layer enthält nun Super-Edge-Informationen
|
||
|
||
---
|
||
|
||
## 📝 Bekannte Einschränkungen
|
||
|
||
- **Re-Import-Dauer:** Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen (optional)
|
||
- **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:
|
||
- Transformation zu einem hochpräzisen Multigraphen
|
||
- Intelligente Ergebnis-Filterung (Diversity Engine)
|
||
- Mathematisches Scoring mit gewichteten Boni
|
||
- Graph-Integrität durch Provenance Firewall
|
||
|
||
---
|
||
|
||
**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen
|
||
**Support:** Bei Fragen siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)
|