mindnet/docs/wp04_retriever_scoring.md

# WP-04 / Step 4a – Retriever Scoring & Konfiguration

Dieses Dokument beschreibt den aktuellen Stand (2025-11-30) der Scoring-Logik des mindnet-Retrievers in WP-04 / Step 4a.  
Es dient als Referenz für:

- Nachvollziehbarkeit des Rankings
- Konfiguration und Feintuning (ohne Codeänderungen)
- spätere Automatisierung / „Selbstjustierung“ des Retrievers

---

## 1. Überblick

Der Retriever kombiniert drei Signalquellen zu einem einheitlichen Score:

1. **Semantik** – Vektorsuche über `mindnet_chunks`
2. **Typ-Gewichtung** – `retriever_weight` pro Note/Chunk (aus `types.yaml`)
3. **Graph-Boni** – `edge_bonus` und `centrality_bonus` aus dem Subgraph (Edges)

Die Berechnung erfolgt in `app/core/retriever.py` und ist über `config/retriever.yaml` konfigurierbar.  
Die API stellt die Funktionalität über den `/query`-Endpoint (FastAPI) bereit.

---

## 2. Datenbasis (Kurzüberblick)

### 2.1 Notes (`<prefix>_notes`)

Relevante Felder:

    - note_id: keyword
    - title: text
    - type: keyword
    - retriever_weight: float
    - chunk_profile: keyword
    - edge_defaults: keyword[]
    - tags: keyword[]
    - path: text
    - fulltext: text

### 2.2 Chunks (`<prefix>_chunks`)

Relevante Felder:

    - note_id: keyword
    - chunk_id: keyword
    - text: text
    - window: text
    - retriever_weight: float
    - type: keyword
    - path: text
    - section: text
    - neighbors_prev / neighbors_next
    - chunk_profile: keyword

### 2.3 Edges (`<prefix>_edges`)

Relevante Felder:

    - kind: keyword
    - source_id: keyword
    - target_id: keyword
    - note_id: keyword
    - confidence: float
    - rule_id, provenance, edge_id, scope, relation, ref_text

Edges stammen stets aus der Import-/Edge-Pipeline (WP-03) und bilden die graphbasierte Grundlage des Retrievers.

---

## 3. Scoring-Formel (Retriever)

### 3.1 Eingangsgrößen

Für jeden Treffer gelten:

    semantic_score     – aus der Vektorsuche (Qdrant)
    retriever_weight   – typabhängiges Gewicht (aus types.yaml)
    edge_bonus         – aggregierter Graph-Bonus
    centrality_bonus   – Zentralitätsbonus aus dem Subgraph

### 3.2 Globale Gewichte (aus retriever.yaml)

Datei: `config/retriever.yaml`  
Beispiel:

    version: 1.0

    scoring:
      semantic_weight:   1.0    # W_sem
      edge_weight:       0.7    # W_edge
      centrality_weight: 0.5    # W_cent

Falls diese Datei fehlt, greifen ENV-basierte Defaults (`RETRIEVER_W_*`).

### 3.3 Formel

    total_score =
        W_sem * semantic_score * max(retriever_weight, 0.0)
        + W_edge * edge_bonus
        + W_cent * centrality_bonus

Bemerkungen:

- Negative `retriever_weight` werden abgefangen.
- Die rohen `edge_bonus` und `centrality_bonus` werden im API-/Smoke-Output angezeigt.
- Die Gewichte aus `retriever.yaml` beeinflussen **nur den total_score**, nicht die Anzeige.

---

## 4. Konfigurationsdateien

### 4.1 Typen-Registry (`types.yaml`)

Beispielauszug:

    defaults:
      retriever_weight: 1.0
      chunk_profile: default

    types:
      types:
        concept:
          retriever_weight: 0.60
          edge_defaults: ["references", "related_to"]

        project:
          retriever_weight: 0.97
          edge_defaults: ["references", "depends_on"]

        journal:
          retriever_weight: 0.80
          edge_defaults: ["references", "related_to"]

        source:
          retriever_weight: 0.50
          edge_defaults: []

Diese Werte bestimmen, wie wichtig eine Note/Chunk **prinzipiell** für den Retriever ist.

### 4.2 Retriever-Konfiguration (`retriever.yaml`)

Beispiel:

    version: 1.0

    scoring:
      semantic_weight:   1.0
      edge_weight:       0.7
      centrality_weight: 0.5

    # Blueprint für spätere Edge-Feinsteuerung:
    edge_types:
      references: 0.20
      depends_on: 0.18
      related_to: 0.15
      similar_to: 0.12
      belongs_to: 0.10
      next: 0.06
      prev: 0.06

Die Datei befindet sich standardmäßig unter `config/retriever.yaml`.  
Override per ENV:

    MINDNET_RETRIEVER_CONFIG=/pfad/zur/datei.yaml

### 4.3 Aktive Gewichte auslesen

    python - << 'PY'
    from app.core.retriever import _get_scoring_weights
    print(_get_scoring_weights())
    PY

Beispielausgabe:

    (1.0, 0.7, 0.5)

---

## 5. Betriebsmodi

### 5.1 Semantikmodus (semantic)

Ablauf:

    - Query-Vektor über embed_text()
    - Qdrant-Suche über mindnet_chunks
    - kein Subgraph → edge_bonus = centrality = 0
    - total_score = W_sem * semantic_score * retriever_weight

### 5.2 Hybridmodus (hybrid)

Ablauf:

    - Semantik wie oben
    - falls expand.depth > 0:
        - Subgraph-Berechnung über ga.expand()
        - Ermittlung von edge_bonus und centrality_bonus
    - total_score = kombinierte Formel aus Semantik + Graph

---

## 6. Tests

### Ausführung (Unit & Integration)

    pytest tests/test_retriever_basic.py \
           tests/test_retriever_weight.py \
           tests/test_retriever_edges.py

    pytest tests/test_query_unit.py \
           tests/test_query_text_embed_unit.py

Tests decken ab:

    - Semantiktreffer
    - Typ-Gewichte
    - Edge-Boni
    - Hybridmodus / FastAPI-Endpunkt

### Smoke-Test

    python tests/test_retriever_smoke.py \
      --url "http://127.0.0.1:8001/query" \
      --query "embeddings" \
      --mode hybrid \
      --expand-depth 1 \
      --top-k 5

Beispielausgabe:

    [1] note_id=...retriever-design
         total=1.5054 (semantic=0.4038 edge=1.5910 centrality=0.0000)

Interpretation:

- `semantic`, `edge`, `centrality` = Rohwerte
- `total` = skaliert mit `retriever.yaml`

---

## 7. Betriebs-Hinweise

### 7.1 Änderung der Gewichte

    - retriever.yaml anpassen
    - FastAPI/uvicorn neu starten
    - Smoke-Test prüfen

### 7.2 Zielbild WP-04

Der jetzige Stand ermöglicht:

    - transparente, konfigurierbare Score-Berechnung
    - Kombination aus Semantik, Typwissen und Graphstruktur
    - spätere agentenbasierte Selbstjustierung
    - alternative Profile (z. B. „mehr Semantik“, „mehr Graph“)

Dieses Dokument dient als stabile Referenz für Entwickler, Tests und spätere Automatisierungsschritte.