p99

patch_history/RETRIEX_PATCH_99_EVAL_SUITE_EXPANSION_README.md

@@ -0,0 +1,157 @@
+# RetrieX Patch p99 - Eval Suite Expansion
+
+## Ziel
+
+p99 erweitert die bisher reine Retrieval-Eval-Baseline um zusätzliche, manuell bekannte Regressionstypen aus v1.6.2:
+
+- Shopquery-Erzeugung
+- Follow-up-Auflösung mit Chatverlauf
+- Antwort-/Halluzinations-Guardrails auf Retrieval-Evidenzebene
+
+Der Patch ändert bewusst keine produktive RAG-, Retrieval-, Shop-, Prompt- oder Antwortlogik. Er ergänzt nur Eval-Infrastruktur und Eval-Cases.
+
+## Neue Eval-Typen
+
+### `shop_query`
+
+Prüft die von `AgentRunner` vorbereitete Shop-Suchquery anhand der Shop-Meta-Ausgabe. Der Runner stoppt, sobald die erste Shop-Such-Meta-Card erzeugt wurde. Dadurch werden die Query-Guards, die Routing-/History-Logik und die finalen Shopquery-Filter geprüft, ohne von der Live-Shopware-Suche abhängig zu sein.
+
+Beispiel:
+
+```bash
+php bin/console mto:agent:eval:run shop_query
+```
+
+Cases liegen in:
+
+```text
+tests/evals/cases/shop_query.ndjson
+```
+
+Abgedeckt werden unter anderem:
+
+- exakter Indikatorcode `Testomat 808 Indikator 300`
+- Brauerei-/Brauwasser-Query-Cleanup
+- Schwimmbad-Tippfehlerkorrektur
+- LAB-CL-Kürzelerhalt
+- SIO2-Geräteanker für Silikatüberwachung
+
+### `followup`
+
+Prüft referenzielle Shop-Folgefragen mit vorbereiteten History-Turns. Die History wird pro Eval-Case in einen isolierten temporären Eval-User geschrieben und danach wieder gelöscht.
+
+Beispiel:
+
+```bash
+php bin/console mto:agent:eval:run followup
+```
+
+Cases liegen in:
+
+```text
+tests/evals/cases/followup.ndjson
+```
+
+Abgedeckt werden unter anderem:
+
+- `0,02 °dH -> Testomat 808 -> Indikatortyp 300 -> was kostet der indikator`
+- Wechsel vom Indikatorpreis zurück zum Hauptgerätpreis
+- schwache Shop-Folgefrage `suche im shop nach der information` mit THCL-Historyanker
+- Produktlink-Follow-up mit Einzelqueries statt kombinierter Multi-Produkt-Query
+
+### `answer_guard`
+
+Prüft Antwort-Guardrails vor der finalen LLM-Antwort auf Basis der Retrieval-Evidenz. Das ist absichtlich kein generativer LLM-Antworttest, sondern ein stabiler Pre-Answer-Guard gegen falsche Evidenz oder Halluzinationsrisiken.
+
+Beispiel:
+
+```bash
+php bin/console mto:agent:eval:run answer_guard
+```
+
+Cases liegen in:
+
+```text
+tests/evals/cases/answer_guard.ndjson
+```
+
+Abgedeckt werden unter anderem:
+
+- Noise-Prompt ohne Evidenz
+- Fantasie-Medien wie Drachenblut / Mondwasser
+- Lieferbedingungen dürfen nicht auf Sicherheitsdatenblätter kippen
+
+## Neue Assertion-Felder
+
+### Für `shop_query` und `followup`
+
+```json
+{
+  "expected_query": "testomat 808 300 indikator",
+  "must_include_terms": ["testomat", "808", "300", "indikator"],
+  "must_not_include_terms": ["300 s", "301", "302"],
+  "must_not_equal_query": "information"
+}
+```
+
+Für Multi-Produkt-Follow-ups:
+
+```json
+{
+  "expected_individual_queries": [
+    "testomat 2000 self clean",
+    "testomat 2000 cal",
+    "testomat 808"
+  ],
+  "expected_individual_queries_exact": true,
+  "min_individual_queries": 3,
+  "max_individual_queries": 3
+}
+```
+
+### Für `retrieval` und `answer_guard`
+
+`RetrievalDebugRunner` unterstützt zusätzlich:
+
+```json
+{
+  "must_not_include_terms": ["sicherheitsdatenblatt"],
+  "must_not_match_patterns": ["/forbidden/u"]
+}
+```
+
+## Geänderte Dateien
+
+```text
+src/Command/AgentEvalRunCommand.php
+src/Eval/AgentEvalRunner.php
+src/Eval/AnswerGuardEvalRunner.php
+src/Eval/Dto/EvalCase.php
+src/Eval/RetrievalDebugRunner.php
+src/Eval/ShopQueryEvalRunner.php
+tests/evals/cases/answer_guard.ndjson
+tests/evals/cases/followup.ndjson
+tests/evals/cases/shop_query.ndjson
+patch_history/RETRIEX_PATCH_99_EVAL_SUITE_EXPANSION_README.md
+```
+
+## Nicht geändert
+
+- Keine Retrieval-Gewichte geändert.
+- Keine Shopquery-Produktivlogik geändert.
+- Keine Prompt-Regeln geändert.
+- Keine YAML-Vokabularregeln geändert.
+- Keine LLM-/Modellparameter geändert.
+- Keine Admin-/Frontend-Logik geändert.
+
+## Empfohlene Validierung nach Einspielen
+
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:eval:run retrieval
+php bin/console mto:agent:eval:run shop_query
+php bin/console mto:agent:eval:run followup
+php bin/console mto:agent:eval:run answer_guard
+```
+
+Wichtig: `shop_query` und `followup` laufen über den `AgentRunner` bis zur Shop-Meta-Card. Sie stoppen vor der Live-Shop-Suche, können aber je nach aktiver Konfiguration weiterhin Input-Normalisierung oder Shopquery-Optimierung über das konfigurierte LLM versuchen. Wenn das LLM nicht erreichbar ist, greift die bestehende Fallback-Logik des Agenten.