From 71fc5a25016bb81404c0346eaef80d4d157c1fe7 Mon Sep 17 00:00:00 2001 From: team 1 Date: Thu, 7 May 2026 20:04:02 +0200 Subject: [PATCH] p62 new --- docs/retriex/shop-query-guardrails.md | 295 ++++++++++++++++++ ...P_QUERY_GUARDRAILS_DOCUMENTATION_README.md | 73 +++++ 2 files changed, 368 insertions(+) create mode 100644 docs/retriex/shop-query-guardrails.md create mode 100644 patch_history/RETRIEX_PATCH_62_SHOP_QUERY_GUARDRAILS_DOCUMENTATION_README.md diff --git a/docs/retriex/shop-query-guardrails.md b/docs/retriex/shop-query-guardrails.md new file mode 100644 index 0000000..7da96b9 --- /dev/null +++ b/docs/retriex/shop-query-guardrails.md @@ -0,0 +1,295 @@ +# RetrieX Shopquery Guardrails + +Diese Checkliste schuetzt den bestaetigten p60/p61C-Flow vor Regressionen. +Sie gilt fuer Aenderungen an Shop-Follow-ups, Shopquery-Cleanup, +History-/RAG-Ankerung, Produktrollen, positiven Token-Filtern und +Shop-Antwortlogik. + +## Zielbild + +Eine Shopquery soll nur Tokens enthalten, die Shopware sinnvoll fuer eine +Produktsuche verwenden kann: + +- konkrete Geraete-, Produkt-, Zubehoer- oder Verbrauchsmaterialbegriffe +- konkrete Modell-, Typ-, Code-, Artikel- oder Gebindetokens +- geschuetzte fachliche Kurzbegriffe wie `pH`, `RX`, `TH`, `TC`, `TP`, `TM` +- shoprelevante Mess- oder Anwendungsterme wie `redox`, `chlor`, `wasserhaerte` + +Nicht in die finale Shopquery gehoeren reine Satz-, Relations-, Bedien-, +Antwort- oder RAG-Erklaerwoerter, z. B. `gemessen`, `beim`, `welchem`, +`wert`, `wurde`, `gut`, `passend`, `suche`, `zeige`. + +## Harte Qualitaetsregel + +Wenn ein Verlauf bereits einen konkreten Geraeteanker enthaelt und die +Folgefrage referenziell nach Preis, Shop, Kosten oder Verfuegbarkeit eines +Zubehoers fragt, muss der konkrete Geraeteanker in der Shopquery erhalten +bleiben. + +Beispiel: + +```text +Was ist der niedrigste Grenzwert fuer die Wasserhaerte, welcher mit einem Testomaten ueberwacht werden kann? +mit welchem indikator wird der wert gemessen +was kostet der indikator +``` + +Die letzte Shopquery muss produktnah bleiben, z. B.: + +```text +testomat 808 300 indikator +``` + +Sie darf nicht auf eine breite Typquery zurueckfallen: + +```text +indikatortyp 300 indikator +``` + +Sie darf auch nicht durch Cleanup zu kurz werden: + +```text +300 indikator +``` + +## Warum das wichtig ist + +Shopware kann bei einer breiten Query wie `indikatortyp 300 indikator` +falsche Treffer liefern, z. B. ein anderes Hauptgeraet. Wenn im Verlauf aber +der konkrete Zielkontext `Testomat 808` belegt ist, darf ein Treffer zu einem +anderen Modell nicht als Preisbasis fuer das referenzierte Zubehoer verwendet +werden. + +## Wichtige Konfigurationsstellen + +### 1. History-/RAG-Ankerung + +Pfad: + +```yaml +config/retriex/genre.yaml +parameters: + retriex.genre.config: + configuration_values: + context_resolution: + history_anchor_enrichment: +``` + +Wirkung: + +- erkennt referenzielle Zubehoer-/Verbrauchsmaterialanker aus dem Verlauf +- bewahrt konkrete Modell-/Geraeteanker aus dem Verlauf +- haelt Typ-/Codetokens wie `300` fest +- verhindert, dass RAG-nahe Typwoerter wie `indikatortyp` die Shopquery dominieren + +Wichtige Felder: + +- `trigger_terms`: Woerter, die History-Ankerung aktivieren duerfen. +- `query_terms`: Woerter, die als shopfaehige Produktbegriffe in die Query duerfen. +- `query_noise_terms`: RAG-/Relationsterme, die nicht dominant in die Shopquery sollen. +- `anchor_patterns`: Patterns fuer Typ-/Code-/Zubehoeranker im Verlauf. +- `template`: Zusammensetzung aus Anker und aktueller Query. + +Pflegehinweis: + +- `indikatortyp` kann ein guter Trigger sein, ist aber oft ein schlechter Shopterm. +- konkrete Werte/Codes wie `300` duerfen nicht entfernt werden. +- konkrete Modellanker wie `Testomat 808` duerfen nicht entfernt werden. + +### 2. Positive Shopquery-Filterung + +Pfad: + +```yaml +config/retriex/genre.yaml +parameters: + retriex.genre.config: + configuration_values: + shop_query_runtime: + positive_token_filter: +``` + +Wirkung: + +- filtert die finale Plain-Text-Shopquery auf produktrelevante Tokens +- entfernt Satz- und Relationswoerter wie `gemessen` oder `beim` +- bewahrt Modell-/Typ-/Gebindecodes ueber `code_patterns` +- kann geschuetzte Kurzbegriffe und Produktrollen aus bestehenden Genre-Werten einbeziehen + +Wichtige Felder: + +- `enabled`: aktiviert den Filter. +- `min_query_tokens_after_filter`: sollte `1` bleiben, damit kurze valide Produktqueries moeglich sind. +- `include_current_input_preservation_terms`: bezieht geschuetzte Kurzbegriffe ein. +- `include_semantic_shop_search_tokens`: bezieht shoprelevante Produktbegriffe ein. +- `include_product_role_terms`: bezieht Geraete-/Zubehoerrollen ein. +- `allowed_terms`: kleine genre-spezifische Positivliste. +- `blocked_terms`: Woerter, die trotz Kontext nicht als Shopterm taugen. +- `code_patterns`: Regex fuer Modell-, Typ-, Artikel- und Gebindetokens. + +Pflegehinweis: + +- Neue Produkt-/Zubehoerwoerter gehoeren bevorzugt in zentrale Genre-Werte, + nicht als harte PHP-Liste. +- Neue Rauschwoerter gehoeren in `blocked_terms`, wenn sie nur fuer Shopqueries + stoeren, aber in RAG-Fragen fachlich relevant sein koennen. +- Keine konkreten Einzelfallregeln fuer `Testomat 808` oder `Indikator 300` + einfuehren. + +### 3. Current input preservation + +Pfad: + +```yaml +config/retriex/genre.yaml +parameters: + retriex.genre.config: + configuration_values: + shop_query_runtime: + current_input_preservation_terms: +``` + +Wirkung: + +- schuetzt kurze technische Tokens aus der aktuellen User-Eingabe +- wichtig fuer `pH`, `RX`, `TH`, `TC`, `redox`, `orp`, `0,02` + +Pflegehinweis: + +- Fachkuerzel nie als normale Stopwoerter behandeln. +- Geschuetzte Begriffe duerfen nicht durch Cleanup-Profile entfernt werden. + +### 4. Stopword cleanup + +Pfad: + +```yaml +config/retriex/genre.yaml +parameters: + retriex.genre.config: + configuration_values: + shop_query_runtime: + stopword_cleanup: +``` + +Wirkung: + +- entfernt Bedien-, UI- und Praesentationswoerter aus Shopqueries +- arbeitet vor bzw. neben dem positiven Tokenfilter + +Pflegehinweis: + +- Nur generische Shopquery-Rauschwoerter eintragen. +- Fachlich relevante RAG-Woerter wie `gemessen` nicht global in Language-Stopwords + verschieben, wenn sie nur im Shopkontext stoeren. + +### 5. Shop-Treffer-Identitaet und Antwortregel + +Relevante Wirkung aus p60: + +- Wenn die Shopquery einen konkreten Modell-/Geraeteanker enthaelt, duerfen + Shop-Treffer zu anderen konkreten Modellen nicht als Preisbasis verwendet werden. +- Wenn nach der Filterung kein passender Shop-Treffer bleibt, soll die Antwort + klar sagen, dass der Preis aus den bereitgestellten Shopdaten nicht ermittelt + werden konnte. +- Die Antwort darf dann keine fremden RAG-/Shop-Produkte als Ersatzpreis nennen. + +## Regressionstest-Checkliste fuer Shopquery-Aenderungen + +Nach jeder Aenderung an den oben genannten Bereichen muessen diese Faelle +manuell geprueft werden. + +### A. Referenzieller Indikator-Preisflow + +Promptfolge: + +```text +Was ist der niedrigste Grenzwert fuer die Wasserhaerte, welcher mit einem Testomaten ueberwacht werden kann? +mit welchem indikator wird der wert gemessen +was kostet der indikator +``` + +Erwartung: + +- erster Turn: `0,02 dH` und `Testomat 808` +- zweiter Turn: `Indikatortyp 300` fuer `Testomat 808` +- dritter Turn: Shopquery enthaelt den konkreten Geraeteanker und den Typcode +- gute Queryform: `testomat 808 300 indikator` +- unerwuenscht: `indikatortyp 300 indikator` +- unerwuenscht: `300 indikator` +- unerwuenscht: Woerter wie `gemessen` oder `beim` +- wenn kein passender Shop-Treffer existiert: keine fremden Geraete oder TH/TP-Indikatoren als Preisersatz nennen + +### B. Direkte Zubehoer-/Attributsuche + +Prompt: + +```text +zeige mir Anschlusskabel fuer pH/Redox laenger 20m +``` + +Erwartung: + +- Shopquery bleibt bei Zubehoer und Anwendung +- keine Testomat-/Indikator-/Hauptgeraete-Ersetzung +- `pH` und `redox` bleiben erhalten, soweit fuer Shopware sinnvoll +- Laengenfilter/Sortierung darf separat wirken, aber nicht die Produktart verdraengen + +### C. Redox Pockettester Follow-up + +Promptfolge: + +```text +welcher pockettester ist fuer Redox messung gut +suche im shop +``` + +Erwartung: + +- Follow-up erkennt den Verlaufskontext +- Shopquery enthaelt produktnahe Begriffe wie `pockettester redox` +- Rauschterme wie `messung` oder `gut` dominieren nicht + +### D. Kurze Produktfrage ohne Verlauf + +Prompt: + +```text +was kostet indikator +``` + +Erwartung: + +- eine kurze valide Query wie `indikator` darf erhalten bleiben +- positive Filterung darf nicht auf leer kuerzen +- wenn mehrere unqualifizierte Treffer kommen, muss die Antwort vorsichtig bleiben + +## Do / Don't + +Do: + +- Produkt- und Geraetebegriffe zentral in `genre.yaml` pflegen. +- Fachkuerzel schuetzen, statt sie als Stopwoerter zu behandeln. +- Query-Rauschen shopkontextspezifisch entfernen. +- Bei referenziellen Preisfragen konkrete Verlaufanker erhalten. +- Falsche Shop-Treffer lieber verwerfen als als Preisbasis verwenden. + +Don't: + +- keine neuen harten Produktlisten im PHP-Core einfuehren +- keine Sonderlogik fuer einzelne Produktfaelle wie `Testomat 808` oder `Indikator 300` +- keine globalen Language-Stopwords fuer fachlich relevante RAG-Woerter erzwingen +- keine fremden Shop-Treffer als Preisersatz ausgeben +- keine Query auf reine Typcodes kuerzen, wenn ein konkreter Geraeteanker vorhanden ist + +## Pflichtchecks + +```bash +bin/console mto:agent:config:validate +bin/console mto:agent:regression:test +bin/console mto:agent:config:audit-source --details +bin/console mto:agent:config:audit-patterns --details +``` + +Zusaetzlich muss mindestens der referenzielle Indikator-Preisflow aus Abschnitt A +manuell getestet werden. diff --git a/patch_history/RETRIEX_PATCH_62_SHOP_QUERY_GUARDRAILS_DOCUMENTATION_README.md b/patch_history/RETRIEX_PATCH_62_SHOP_QUERY_GUARDRAILS_DOCUMENTATION_README.md new file mode 100644 index 0000000..bf0e476 --- /dev/null +++ b/patch_history/RETRIEX_PATCH_62_SHOP_QUERY_GUARDRAILS_DOCUMENTATION_README.md @@ -0,0 +1,73 @@ +# RetrieX Patch p62 - Shopquery Guardrails Documentation + +## Ziel + +p62 dokumentiert die bestaetigten p60/p61C-Guardrails fuer referenzielle +Shop-Follow-ups und positive Shopquery-Filterung. + +Der Patch aendert keine Runtime-Logik und keine YAML-Werte. Er fuegt nur eine +Projekt-Checkliste hinzu, damit kuenftige Shopquery-Aenderungen den Flow +`0,02 dH -> Indikatortyp 300 -> was kostet der indikator` nicht regressieren. + +## Neue Dokumentation + +- `docs/retriex/shop-query-guardrails.md` + +Die Dokumentation beschreibt: + +- Zielbild fuer finale Plain-Text-Shopqueries +- relevante `genre.yaml`-Pflegepunkte +- Unterschied zwischen History-Ankerung, Stopword-Cleanup und positivem Tokenfilter +- Regeln fuer konkrete Verlauf-Geraeteanker +- Verhalten bei unpassenden Shop-Treffern +- manuelle Regressionstest-Checkliste +- Do/Don't-Regeln fuer zukuenftige Patches + +## Wichtige geschuetzte Regression + +Promptfolge: + +```text +Was ist der niedrigste Grenzwert fuer die Wasserhaerte, welcher mit einem Testomaten ueberwacht werden kann? +mit welchem indikator wird der wert gemessen +was kostet der indikator +``` + +Erwartung fuer die letzte Shopquery: + +```text +testomat 808 300 indikator +``` + +Nicht akzeptabel: + +```text +indikatortyp 300 indikator +300 indikator +testomat 808 gemessen 300 beim indikator +``` + +## Scope + +Keine Aenderungen an: + +- Runtime-Verhalten +- Retrieval +- Prompting +- Shop-Query-Code +- Shop-Scoring +- SearchRepair +- Intent-Routing +- YAML-Konfigurationswerten + +## Validierung + +Da p62 nur Markdown-Dateien hinzufuegt, reichen lokale Datei-/Diff-Pruefungen. +Im Projekt sollten dennoch die Standardchecks laufen: + +```bash +bin/console mto:agent:config:validate +bin/console mto:agent:regression:test +bin/console mto:agent:config:audit-source --details +bin/console mto:agent:config:audit-patterns --details +```