# 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.