# mindnet Retriever (WP-04 / Step 4a) – Kurz-Dokumentation

## 1. Überblick

Der Retriever besteht aus:

- **Semantic Retriever** (`semantic_retrieve`)
- **Hybrid Retriever** (`hybrid_retrieve`)
- Qdrant-Backend (`*_chunks`, `*_edges`)
- optionaler Edge-Expansion über `graph_adapter.expand`

Die API nutzt das bestehende `/query`-Endpoint (FastAPI), das `QueryRequest` und `QueryResponse` aus `app.models.dto` verwendet.

## 2. Scoring-Formel

Pro Treffer werden folgende Komponenten geführt:

- `semantic_score` – direkt aus Qdrant (Cosine/Euclidean, je nach Collection)
- `retriever_weight` – aus Chunk-Payload (`types.yaml` / Frontmatter)
- `edge_bonus` – Bonus aus dem Subgraph (z. B. Zahl der eingehenden/ausgehenden Edges, Beziehungstypen)
- `centrality_bonus` – Bonus aus einer einfachen Zentralitäts-Heuristik im Subgraph

Aktuelle Formel (Step 4a):

```text
total_score = semantic_score * max(retriever_weight, 0.0)
              + edge_bonus
              + centrality_bonus
```

Die Sortierung der Ergebnisse erfolgt absteigend nach `total_score`.

## 3. Modi

### 3.1 Semantic Mode

- Funktion: `semantic_retrieve`
- Request-Feld `mode = "semantic"`
- Keine Edge-Expansion, kein Graph-Call.
- Kandidaten nur aus Vektorsuche in `<prefix>_chunks`.

### 3.2 Hybrid Mode

- Funktion: `hybrid_retrieve`
- Request-Feld `mode = "hybrid"`
- Schritte:
  1. Semantische Chunk-Suche wie im Semantic Mode
  2. Falls `expand.depth > 0` gesetzt ist:
     - Seeds = `chunk_id` (Fallback: `note_id`) der Treffer
     - Aufruf `graph_adapter.expand(client, prefix, seed_ids, depth, edge_types)`
     - Ergebnis-Subgraph liefert `edge_bonus` und `centrality_bonus` pro Node
  3. Scores werden nach obiger Formel kombiniert.

## 4. Request-Struktur (JSON)

Beispiel-Hybrid-Request:

```json
{
  "mode": "hybrid",
  "query": "embeddings und qdrant",
  "top_k": 10,
  "expand": {
    "depth": 1,
    "edge_types": ["references", "depends_on"]
  }
}
```

Minimaler Semantic-Request:

```json
{
  "mode": "semantic",
  "query": "karate trainingsplan",
  "top_k": 5
}
```

## 5. Smoke-Test

Für einen schnellen End-to-End-Test kann folgendes Skript verwendet werden:

```bash
python scripts/test_retriever_smoke.py --query "karate" --mode hybrid --expand-depth 1 --top-k 5
```

Das Skript ruft `/query` auf, wertet Statuscode und JSON-Antwort aus und zeigt die Scores der Top-K-Treffer an.

## 6. Tests

Die wichtigsten Tests für den Retriever sind:

- `tests/test_retriever_basic.py` – Basisfunktion (Semantic + Hybrid)
- `tests/test_retriever_weight.py` – Einfluss von `retriever_weight` auf das Ranking
- `tests/test_retriever_edges.py` – Einfluss von Edge-/Centrality-Boni im Hybrid-Modus