p62 new
This commit is contained in:
team 1
295
docs/retriex/shop-query-guardrails.md
Normal file
295
docs/retriex/shop-query-guardrails.md
Normal file
@@ -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.
|
||||||
@@ -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
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user