p98

patch_history/RETRIEX_PATCH_98_RETRIEVAL_EVAL_GREEN_BASELINE_README.md

@@ -0,0 +1,79 @@
+# RetrieX Patch p98 - Retrieval Eval Green Baseline
+
+## Ziel
+
+p98 schärft die Retrieval-Baseline für die vier zuletzt roten Eval-Fälle, ohne neue produkt- oder testfallspezifische PHP-Sonderlogik einzuführen.
+
+Abgedeckte rote Fälle aus `tests/evals/cases/retrieval.ndjson`:
+
+- `welcher testomat ist ein verschneideregler`
+- `welches geraet ist fuer chlorueberwachung gedacht`
+- `lieferbedingungen versand testomat`
+- `testomat 2000 th 2005 sicherheitsdatenblatt`
+
+## Änderungen
+
+### 1. YAML-konfigurierbares Retrieval-Query-Cleanup
+
+`QueryCleaner` nutzt zusätzlich zum bestehenden Legacy-Stopword-Set ein YAML-Cleanup-Profil aus `retrieval.yaml`:
+
+```yaml
+query_cleanup_profile: retrieval_reference_cleanup
+```
+
+Dadurch werden generische Fragewörter wie `welcher` und `welches` über das bestehende Cleanup-Profil entfernt, ohne sie wieder in alte Legacy-Listen zurückzuschreiben.
+
+### 2. ASCII-/Umlaut- und Bedeutungsbrücken im Genre-Enrichment
+
+`genre.yaml` ergänzt konservative Query-Enrichment-Regeln für häufige ASCII-Schreibweisen und zusammengesetzte Suchbegriffe:
+
+- `geraet` -> `gerät analysegerät`
+- `chlorueberwachung` -> `chlor überwachung chlorüberwachung`
+- `haerteueberwachungsgeraet` -> `härteüberwachungsgerät härteüberwachung analysegerät`
+- `lieferbedingungen` -> `lieferung versand verkaufsbedingungen allgemeine lieferbedingungen`
+
+Die Regeln bleiben im genre-spezifischen Konfigurationsbereich `brands_and_canonical_terms.query_enrichment_rules`.
+
+### 3. Strengerer Exact-Title-Fallback für kurze Modellvarianten
+
+Kurze Modell-/Variantentokens aus der Retrieval-Vocabulary-View können nun bei Exact-Title-Tokenmatches signifikant sein.
+
+Damit gilt z. B. bei `Testomat 2000 V` auch `v` als relevanter Titelbestandteil. Eine Anfrage wie `testomat 2000 th 2005 sicherheitsdatenblatt` fällt dadurch nicht mehr fälschlich auf `Testomat 2000 V`, sondern kann in die normale Retrieval-Fusion laufen und dort die TH-2005-Sicherheitsdatenblätter treffen.
+
+### 4. Config-Validierung und Doku
+
+- `NdjsonHybridRetrieverConfig` exportiert `query_cleanup_profile`.
+- `RetriexEffectiveConfigProvider` validiert, dass das Profil existiert.
+- `CONFIG_PARAMS.md` dokumentiert den neuen Parameter.
+
+## Nicht geändert
+
+- Keine Shopquery-Logik geändert.
+- Keine Follow-up-Actions geändert.
+- Keine Agent-/Prompt-Antwortregeln geändert.
+- Keine Testomat-spezifische PHP-Sonderlogik ergänzt.
+- Keine Retrieval-Parameter wie Schwellenwerte, RRF-Gewichte oder Top-K verändert.
+
+## Validierung im Patch-Build
+
+Da die lokale Ausführungsumgebung keine vollständigen PHP-Erweiterungen/Vendor-Abhängigkeiten bereitstellt, konnte der Symfony-Eval-Command hier nicht ausgeführt werden. Stattdessen wurden folgende Checks ausgeführt:
+
+- YAML-Parsing für `retrieval.yaml`, `genre.yaml`, `language.yaml`
+- PHP-Syntaxprüfung für alle geänderten PHP-Dateien
+- lokale NDJSON-/Lexical-Index-Simulation gegen die bereitgestellte `knowledge.zip`
+
+Die Simulation zeigt für die vier roten Baseline-Fälle den erwarteten Zieltreffer in den Top-Ergebnissen:
+
+- Verschneideregler -> `Testomat 2000 V`
+- Chlorüberwachung -> `Testomat 2000 THCL`
+- Lieferbedingungen/Versand -> `Lieferung und Versand`
+- TH 2005 Sicherheitsdatenblatt -> `Testomat 2000 Indikator TH 2005`
+
+## Empfohlener Regressionstest nach Einspielen
+
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:eval:run retrieval
+```
+
+Erwartung: Die Retrieval-Baseline sollte von `15/19` auf `19/19` gehen. Falls nach produktiver Vector-/Lexical-Index-Lage noch ein einzelner semantischer Fall hängt, sollte zuerst der Knowledge-Index neu aufgebaut werden, bevor Retrieval-Parameter verändert werden.