Update documentation to version 2.9.1, incorporating WP-15c enhancements including section-based links, multigraph support, and improved scoring logic. Add details on Super-Edge aggregation and Note-Level Diversity Pooling for better retrieval accuracy. Enhance context descriptions and clarify provenance handling in technical references.

This commit is contained in:
Lars committed 2025-12-31 16:55:12 +01:00
1 parent d35bdc64b9
commit 4de9a4f649
5 files changed
+448 -21

No files matched your search

+123
View File
@@ -0,0 +1,123 @@
# Branch Merge Commit Message: WP15c
```
feat: Multigraph-Support, Diversity Engine & Provenance Firewall (v2.9.1)
## Graph Topology & Edge Management (WP-15c)
### Section-Präzision & Multigraph-Modus
- Präzise Erkennung von Obsidian-Ankern (`[[Note#Section]]`) und Self-Links (`[[#Section]]`)
- Links werden in `target_id="Note"` und `target_section="Section"` aufgelöst
- Edge-ID enthält `variant` (Section) für eindeutige Identifikation
- Multigraph-Modus: Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
- 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 & 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)
### Provenance Firewall (Edge Registry v0.8.0)
- System-Kanten (`next`, `prev`, `belongs_to`) 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
**Geänderte Dateien:**
- `app/services/edge_registry.py`: Provenance Firewall (v0.8.0)
## Retrieval-Intelligenz (The Diversity Engine)
### Note-Level Diversity Pooling
- Pro `note_id` wird nur der relevanteste Treffer im Endergebnis behalten
- Verhindert "Note-Flooding" (Dominanz einer einzigen Notiz durch viele ähnliche Chunks)
- Workflow: Sortierung nach finalem Score → Diversity-Pooling → Begrenzung auf `top_k`
**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Note-Level Diversity Pooling (v0.7.0)
### Super-Edge Aggregation
- Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer "Super-Edge" aggregiert
- Primäre Kante zählt voll, weitere Kanten werden mit Dämpfungsfaktor **0.1** gewichtet
- Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections
- Metadaten: `is_super_edge` Flag und `edge_count` für Explanation Layer
**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Super-Edge Aggregation (v0.7.0)
### Metadaten-Persistenz
- In-Memory Subgraph und Datenbank-Adapter erweitert für durchgängige Metadaten-Erhaltung
- `target_section`, `provenance` und `confidence` werden vollständig erhalten
- Ermöglicht präzises Retrieval-Reasoning und Explanation Layer
**Geänderte Dateien:**
- `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)
## Mathematisches Scoring (WP-22 Integration)
### Hybrid Scoring Formula (v1.0.3)
- Neue Formel: `Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)`
- Status-Gatekeeper: `stable` = 1.2, `draft` = 0.5, `active` = 1.0
- Graph Boost Factor: Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
- Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt
**Geänderte Dateien:**
- `app/core/retrieval/retriever_scoring.py`: Hybrid Scoring Formula (v1.0.3)
### Explanation Layer
- Detaillierte Begründungen für jeden Bonus (Sektions-Links, Hub-Zentralität, Super-Edge-Informationen)
- Provenance-Informationen für erhöhte Transparenz
- Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen
**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Explanation Layer (v0.7.0)
## Ingestion & Profil-Synchronisation
### Registry-First Profiling (v2.13.12)
- Hierarchische Auflösung: Frontmatter > types.yaml Typ-Config > Global Defaults
- Konsistente Verarbeitung je nach Notiz-Typ
- Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`)
**Geänderte Dateien:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12)
## Impact & Breaking Changes
### 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
```
### Fixes
- ✅ Resolves: "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section
- ✅ Resolves: Score-Explosionen durch multiple Links auf verschiedene Sections
- ✅ Resolves: "Note-Flooding" durch fehlende Diversity-Filterung
- ✅ Resolves: Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
- ✅ Resolves: Manipulation von System-Kanten durch Provenance Firewall
## Dokumentation
Alle relevanten Dokumente 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)
## Versionen
- 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
Closes #[issue-number]
```
+267
View File
@@ -0,0 +1,267 @@
# 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)