# MATRIX_PARAMS.md

# Retrieval-Matrix: alle relevanten Parameter und ihr realer Einfluss

## Zweck dieser Datei

Diese Datei beschreibt die **realen Retrieval-Parameter im aktuellen Code-Stand** von RetrieX auf Basis der aktuellen `rag.zip`.

Wichtig:

- Die Datei beschreibt **Code-Defaults, Hard Limits und effektive Laufzeitlogik**
- Die **aktiven DB-Werte** der `ModelGenerationConfig` sind aus dem Repository allein **nicht sicher ableitbar**
- Wo kein aktiver DB-Wert aus dem ZIP belegbar ist, wird zwischen **Code-Default**, **Admin-Default** und **effektivem Clamp** unterschieden

---

# 1. Die wichtigsten Hebel in Kurzform

Die Retrieval-Qualität wird im aktuellen Stand vor allem durch diese Hebel bestimmt:

1. **`retrievalMaxChunks`**  
   bestimmt, wie viele finale Chunks maximal ans LLM gehen

2. **`retrievalVectorTopK`**  
   bestimmt, wie breit die initiale Vektorsuche sucht

3. **effektiver Score-Threshold im Retriever**  
   bestimmt, welche Vector-Hits überhaupt in die Fusion gelangen

4. **Tag-Routing**  
   bestimmt, ob zusätzlich eine dokumentgescopte Suche ausgeführt wird

5. **List-Intent / Sales-Intent**  
   verändert TopK, Auswahlmodus und Scoping-Verhalten

6. **Selektionsregeln pro Dokument**  
   begrenzen Redundanz und Nachbarschaft ähnlicher Chunks

---

# 2. Matrix der Retrieval-Parameter

| Ebene | Ort | Parameter / Konstante | Aktueller Wert | Effektiver Einfluss |
|---|---|---:|---:|---|
| **DB / Config** | `ModelGenerationConfig` | `retrievalMaxChunks` | Constructor-Default: `25` | Maximalzahl finaler Chunks vor Retriever-internem Clamp |
| **DB / Config** | `ModelGenerationConfig` | `retrievalVectorTopK` | Constructor-Default: `25` | Basisbreite der initialen Vektorsuche vor Retriever-internem Clamp |
| **DB / Guardrail** | `ModelGenerationConfig` | `MAX_RETRIEVAL_CHUNKS` | `200` | Harte Obergrenze beim Setzen des DB-Werts |
| **DB / Guardrail** | `ModelGenerationConfig` | `MAX_VECTOR_TOPK` | `200` | Harte Obergrenze beim Setzen des DB-Werts |
| **Admin-Erzeugung** | `ModelGenerationConfigAdminService` | `retrieval_max_chunks` | Fallback: `25` | Standardwert beim Anlegen neuer Configs im Admin |
| **Admin-Erzeugung** | `ModelGenerationConfigAdminService` | `retrieval_vector_top_k` | Fallback: `25` | Standardwert beim Anlegen neuer Configs im Admin |
| **Fallback ohne aktive DB-Config** | `ModelGenerationConfigProvider` | `retrievalMaxChunks` | implizit `25` | Greift nur, wenn keine aktive Config existiert |
| **Fallback ohne aktive DB-Config** | `ModelGenerationConfigProvider` | `retrievalVectorTopK` | implizit `25` | Greift nur, wenn keine aktive Config existiert |
| **Retriever** | `NdjsonHybridRetriever` | `HARD_MAX_CHUNKS` | `90` | Zusätzlicher harter Retriever-Clamp für finale Chunk-Zahl |
| **Retriever** | `NdjsonHybridRetriever` | `HARD_MAX_VECTORK` | `250` | Zusätzlicher harter Retriever-Clamp für TopK; effektiv meist unter DB-Clamp |
| **Retriever** | `NdjsonHybridRetriever` | `VECTOR_SCORE_THRESHOLD` | `0.75` | Formale Basisschwelle vor zusätzlichem Floor/Ceil |
| **Retriever** | `NdjsonHybridRetriever` | `THRESHOLD_FLOOR` | `0.83` | Effektive Mindestschwelle; dominiert aktuell den Basisschwellenwert |
| **Retriever** | `NdjsonHybridRetriever` | `THRESHOLD_CEIL` | `0.92` | Effektive Maximalschwelle |
| **Retriever** | `NdjsonHybridRetriever` | `LIST_BONUS` | `1.25` | Erhöht `topK` bei Listenfragen auf `round(base * 1.25)` |
| **Retriever** | `NdjsonHybridRetriever` | `MAX_CHUNKS_PER_DOC` | `2` | Maximal zwei finale Chunks pro Dokument im Sales-Modus |
| **Retriever** | `NdjsonHybridRetriever` | `MIN_CHUNK_DISTANCE` | `2.5` | Verhindert zu nahe Chunk-Nachbarn aus demselben Dokument |
| **Retriever** | `NdjsonHybridRetriever` | `RRF_K` | `60` | Steuert die Reciprocal-Rank-Fusion |
| **Retriever** | `NdjsonHybridRetriever` | Scoped RRF Boost | `1.2` | Scoped Hits werden nur in bestimmten Fällen stärker gewichtet |
| **Retriever** | `NdjsonHybridRetriever` | `EMPTY_RRF_FALLBACK_TOPN` | `1` | Falls Fusion leer bleibt, wird maximal ein Top-Hit in Fallback-RRF überführt |
| **Intent** | `IntentLite` | `LIST_THRESHOLD` | `4` | Ab Score 4 wird Listenmodus aktiviert |
| **Intent** | `SalesIntentLite` | `MIN_SCORE_THRESHOLD` | `3` | Mindestscore, damit ein Nicht-Discovery-Intent akzeptiert wird |
| **Intent** | `SalesIntentLite` | `DOMINANCE_DELTA` | `2` | Top-Intent muss den zweiten Intent um mindestens 2 Punkte schlagen |
| **Vector Client** | `VectorSearchClient` | `MIN_SCORE` | `0.30` | Vorfilter im PHP-Client für Chunk-Vektortreffer |
| **Vector Client** | `VectorSearchClient` | `MAX_LIMIT` | `200` | Hard Clamp für Anfragen an den Chunk-Vector-Service |
| **Tag Vector Client** | `TagVectorSearchClient` | `MIN_SCORE` | `0.72` | Vorfilter für Tag-Vektortreffer |
| **Tag Vector Client** | `TagVectorSearchClient` | `MAX_LIMIT` | `50` | Hard Clamp für Anfragen an den Tag-Vector-Service |
| **Tag Routing** | `TagRoutingService` | `DEFAULT_TOPK` | `8` | Anzahl der Tag-Treffer, die initial geprüft werden |
| **Tag Routing** | `TagRoutingService` | `MIN_BEST_SCORE` | `0.25` | Zusätzliche Gate-Schwelle nach Tag-Search; aktuell praktisch nicht limitierend |
| **Tag Routing** | `TagRoutingService` | `MAX_CANDIDATE_DOCS` | `200` | Maximalzahl an Dokumenten, die aus Tags als Kandidatenmenge entstehen dürfen |
| **Query-Aufbereitung** | `QueryCleaner` | Stopword-Filter | aktiv | Entfernt Stopwörter vor der Suche |
| **Query-Aufbereitung** | `QueryCleaner` | Zahlen bleiben erhalten | aktiv | Zahlen werden nicht entfernt |
| **Query-Aufbereitung** | `QueryCleaner` | Bindestrich/Slash-Splitting | aktiv | `-` und `/` werden als Worttrenner behandelt |
| **Query-Aufbereitung** | `QueryEnricher` | Synonym-/Pseudonym-Anreicherung | Mapping-basiert | Hängt erkannte Pseudonyme als Zusatz an die Query |
| **Auswahlmodus** | `NdjsonHybridRetriever` | `selectListChunkIds()` | dedup-basiert | Listenmodus dedupliziert Textfragmente statt hart pro Dokument zu begrenzen |
| **Auswahlmodus** | `NdjsonHybridRetriever` | `selectSalesChunkIds()` | dokumentbegrenzt | Sales-/Normalmodus begrenzt pro Dokument und nach Chunk-Abstand |

---

# 3. Effektive Laufzeitlogik der wichtigsten Parameter

## 3.1 `retrievalMaxChunks`

Effektive Formel:
```
limit = min(activeConfig.retrievalMaxChunks, HARD_MAX_CHUNKS)
```
---

# 4. Parameteränderungen und ihre typische Wirkung

| Parameter | Wenn erhöht | Wenn gesenkt | Typischer Effekt / Risiko |
|---|---|---|---|
| `retrievalMaxChunks` | mehr finaler Kontext | kompakterer Kontext | zu hoch: mehr Noise und Tokenverbrauch |
| `retrievalVectorTopK` | breitere Kandidatenbasis | engere Kandidatenbasis | zu hoch: mehr Streuung, zu niedrig: Recall-Verlust |
| effektiver Threshold | präzisere Treffer | mehr schwache Treffer | zu niedrig: Rauschen, zu hoch: Leertreffer |
| `LIST_BONUS` | stärkere Listenabdeckung | schmalere Listenabdeckung | zu hoch: unnötig breite Listen-Suche |
| `MAX_CHUNKS_PER_DOC` | mehr Tiefe je Dokument | mehr Diversität zwischen Dokumenten | zu hoch: Dominanz einzelner Dokumente |
| `MIN_CHUNK_DISTANCE` | weniger Nachbarschaftsduplikate | mehr lokale Ballung | zu hoch: zusammenhängende Argumente können verloren gehen |
| `RRF_K` | flachere Rangunterschiede | stärkere Dominanz der Top-Ränge | beeinflusst Fusionscharakter |
| Scoped Boost `1.2` | stärkt Routing-Dokumente | schwächt Routing-Dokumente | zu hoch: Routing dominiert globale Suche |
| Tag `DEFAULT_TOPK` | mehr Tag-Kandidaten | weniger Tag-Kandidaten | zu hoch: größere Kandidatenmengen |
| `MAX_CANDIDATE_DOCS` | breiteres Tag-Scoping | engeres Tag-Scoping | zu hoch: Scoping verliert Fokus |
| VectorClient `MIN_SCORE` | präzisere Rohhits | mehr Rohrauschen | Vorfilter vor Retriever-Fusion |
| TagVectorClient `MIN_SCORE` | strengere Tag-Erkennung | großzügigere Tag-Erkennung | sehr sensibel für Routing-Verhalten |
| `LIST_THRESHOLD` | Listenmodus seltener | Listenmodus häufiger | Fehlklassifikation möglich |
| `MIN_SCORE_THRESHOLD` (`SalesIntent`) | Discovery häufiger | Spezial-Intents häufiger | beeinflusst Objection/Pricing-Steuerung |
| `DOMINANCE_DELTA` | Intent muss klarer dominieren | Intent springt leichter um | beeinflusst Spezialisierung der Retrieval-Logik |

# 5. Praktische Lesart für Tuning

Wenn man im aktuellen Stand Retrieval-Tuning betreiben will, sind diese Hebel am wichtigsten:

## Für mehr Recall

- `retrievalVectorTopK` erhöhen
- `QueryEnrichment` gezielt erweitern
- Tag-Routing nicht zu streng machen
- effektiven Threshold bewusst überprüfen

## Für mehr Präzision

- effektiven Threshold sauber justieren
- `retrievalMaxChunks` nicht unnötig hoch setzen
- `MAX_CHUNKS_PER_DOC` niedrig halten
- Tag-Kandidatenmenge fokussiert halten

## Für bessere Listenantworten

- `LIST_THRESHOLD` und Listenheuristik prüfen
- `LIST_BONUS` gezielt feinjustieren
- dedup-basierte List-Auswahl beobachten

## Für bessere Sales-/Beratungsantworten

- `MAX_CHUNKS_PER_DOC`
- `MIN_CHUNK_DISTANCE`
- SalesIntent-Erkennung
- Scoped-Boost-Logik