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

@@ -120,10 +120,12 @@ Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Track
}
```
**Section-Support:**
**Section-Support (WP-15c):**
* Links wie `[[Note#Section]]` werden in `target_id="Note"` und `target_section="Section"` aufgeteilt.
* Die Edge-ID enthält die Section als `variant`, sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen.
* **Self-Links:** `[[#Section]]` wird zu `target_id="current_note_id"` und `target_section="Section"` aufgelöst.
* Die Edge-ID enthält die Section als `variant`, sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen (Multigraph-Modus).
* Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key, um "Phantom-Knoten" zu vermeiden.
* **Metadaten-Persistenz:** `target_section`, `provenance` und `confidence` werden durchgängig im In-Memory Subgraph und Datenbank-Adapter erhalten.
**Erforderliche Indizes:**
Es müssen Payload-Indizes für folgende Felder existieren:
@@ -3,22 +3,29 @@ doc_type: technical_reference
audience: developer, data_scientist
scope: backend, retrieval, scoring, modularization
status: active
version: 2.9.0
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und WP-14 Modularisierung."
version: 2.9.1
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting, WP-15c Diversity Engine und WP-14 Modularisierung."
---
# Retrieval & Scoring Algorithmen
Der Retriever unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert. Mit Version 2.7 (WP-22) wurde dieses Modell um **Lifecycle-Faktoren** und **Intent-Boosting** erweitert sowie die Architektur modularisiert (WP-14).
## 1. Scoring Formel (v2.7.0)
## 1. Scoring Formel (WP-15c / v1.0.3)
Der Gesamtscore eines Treffers berechnet sich als gewichtete Summe. Alle Gewichte ($W$) und Modifier ($M$) sind in `retriever.yaml` und `decision_engine.yaml` konfigurierbar.
Seit WP-15c nutzt Mindnet eine **hybride Multiplikations-Formel** für präziseres Scoring. Alle Gewichte ($W$) und Modifier ($M$) sind in `retriever.yaml` und `decision_engine.yaml` konfigurierbar.
$$
TotalScore = (W_{sem} \cdot S_{sem} \cdot W_{type} \cdot M_{status}) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent}) + B_{intent}
Final = (Semantic \cdot StatusMult) \cdot (1 + TypeBoost + EdgeBonus + CentBonus)
$$
**Komponenten:**
* **Base Score:** `Semantic * StatusMult` (Lifecycle-Filter)
* **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.
### Die Komponenten (Klassisch v2.4)
**1. Semantic Score ($S_{sem}$):**
@@ -43,13 +50,15 @@ $$
### Die WP-22 Erweiterungen (v2.7.0)
**5. Status Modifier ($M_{status}$):**
**5. Status Modifier ($M_{status}$) - Status-Gatekeeper:**
* **Herkunft:** Feld `status` aus dem Frontmatter (verarbeitet in `retriever_scoring.get_status_multiplier`).
* **Zweck:** Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Belohnung für verifiziertes Wissen).
* `active`: **1.0** (Standard-Gewichtung).
* `draft`: **0.5** (Malus für unfertige Fragmente).
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter).
* **Zweck:** Wirkt als **Multiplikator** auf die Basis-Semantik. Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
* **Werte (WP-15c):**
* `stable`: **1.2** (Belohnung für verifiziertes Wissen)
* `active`: **1.0** (Standard-Gewichtung)
* `draft`: **0.5** (Malus für unfertige Fragmente)
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter)
* **Impact:** Der Status wirkt direkt auf die semantische Ähnlichkeit, bevor Graph-Boni berechnet werden.
**6. Intent Boost ($B_{intent}$):**
* **Herkunft:** Dynamische Injektion durch die Decision Engine basierend auf der Nutzerfrage.
@@ -70,16 +79,25 @@ Seit v2.9 ist die Retrieval-Engine im spezialisierten Paket `app.core.retrieval`
* Diese delegiert an `app.core.graph.graph_subgraph`, um direkte Nachbarn aus der `_edges` Collection zu laden.
* Konstruktion eines in-memory Graphen zur Berechnung topologischer Boni.
**Phase 3: Re-Ranking (Modular)**
**Phase 3: Graph-Intelligenz & Super-Edge Aggregation (WP-15c)**
* **Super-Edge Aggregation:** Parallele Kanten zwischen zwei Notizen (z.B. auf verschiedene Sections) werden mathematisch zu einer "Super-Edge" aggregiert:
* Primäre Kante zählt voll (höchstes Gewicht)
* Weitere Kanten werden mit Dämpfungsfaktor **0.1** gewichtet
* Verhindert Score-Explosionen durch multiple Links
* **Provenance Weighting:** Kanten werden nach Provenance gewichtet (`explicit`=1.0, `smart`=0.9, `rule`=0.7)
* **Intent Boost:** Dynamische Multiplikatoren für spezifische Kanten-Typen (z.B. `caused_by` bei "Warum"-Fragen)
**Phase 4: Re-Ranking & Diversity Pooling (WP-15c)**
* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine` (`retriever_scoring.py`).
* Berechnung der finalen Scores unter Berücksichtigung von $B_{edge}$, $B_{cent}$ sowie der Lifecycle- und Intent-Modifier.
* **Note-Level Diversity Pooling:** Pro `note_id` wird nur der relevanteste Treffer behalten (verhindert "Note-Flooding").
* Sortierung absteigend nach `TotalScore` und Limitierung auf die angeforderten Top-Resultate.
---
## 3. Explanation Layer (WP-22 Update)
## 3. Explanation Layer (WP-15c)
Bei `explain=True` generiert das System eine detaillierte Begründung inklusive Provenienz-Informationen.
Bei `explain=True` generiert das System eine detaillierte Begründung inklusive Provenienz-Informationen. Der Explanation Layer liefert detaillierte Begründungen für jeden Bonus (z.B. Sektions-Links oder Hub-Zentralität), was die Transparenz massiv erhöht.
**Erweiterte JSON-Struktur:**