MtoRagSystem/docs/retriex/shop-query-guardrails.md

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:

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

testomat 808 300 indikator

Sie darf nicht auf eine breite Typquery zurueckfallen:

indikatortyp 300 indikator

Sie darf auch nicht durch Cleanup zu kurz werden:

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:

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:

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:

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:

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:

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:

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:

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:

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

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.