p69

patch_history/RETRIEX_PATCH_69_CONTEXT_AWARE_FOLLOWUP_ACTIONS_README.md

@@ -0,0 +1,68 @@
+# RetrieX Patch p69 - Context-aware Follow-up Actions
+
+## Ziel
+
+Dieser Patch härtet die in p67/p68 eingeführten Folgeaktionen: Actions werden nicht mehr nur anhand von `hasShopResults` statisch angezeigt, sondern nach aktuellem Antwort-/Shopkontext gefiltert.
+
+## Problem
+
+Bei einer Anfrage wie `testomat 808 indikatoren` wurden nach einer Zubehör-/Indikatorliste trotzdem generische Rollenfilter wie `Nur Geräte anzeigen` angeboten. Beim Klick ging der Produktkontext verloren und die Folgeanfrage konnte zu einer generischen Shopquery wie `geräte` degenerieren.
+
+## Lösung
+
+- Follow-up-Actions erhalten optionale Metadaten in `config/retriex/chat-messages.yaml`:
+  - `action_type: shop_search`
+  - `action_type: price_details`
+  - `action_type: role_filter`
+  - `target_role: accessory_or_consumable|main_device`
+- `AgentRunner` baut vor dem Rendern einen Action-Kontext auf:
+  - aktuelle Shopquery
+  - ob die finale Antwort bereits Preise enthält
+  - Rollenverteilung der aktuellen Shop-Treffer
+- Rollenfilter werden nur angezeigt, wenn sie wirklich verengen:
+  - Zielrolle muss in den Ergebnissen vorkommen
+  - Zielrolle darf nicht bereits die komplette Ergebnismenge sein
+  - Kontextquery muss vorhanden sein
+- Preis-Actions werden ausgeblendet, wenn die Antwort bereits Preise enthält.
+- Action-Prompts werden mit `{shop_query}` verankert, damit Klicks nicht mehr zu isolierten Queries wie `geräte` führen.
+- Wenn nach der Kontextfilterung keine sinnvolle Action übrig bleibt, wird keine Follow-up-Action-Karte gerendert.
+
+## Bewusst nicht geändert
+
+- Kein Eingriff in Retrieval, Scoring, Ranking, PromptBuilder oder Shop-Matching.
+- Keine neuen fachlichen Keywordlisten im PHP-Core.
+- Produktrollen-Erkennung nutzt bestehende YAML-gepflegte No-LLM-Rollenterms.
+- `buildShopProductCardsMessage()` bleibt weiterhin nicht eingehängt.
+
+## Geänderte Dateien
+
+- `src/Agent/AgentRunner.php`
+- `src/Config/AgentRunnerConfig.php`
+- `src/Config/ChatMessagesConfig.php`
+- `config/retriex/chat-messages.yaml`
+
+## Lokale Checks
+
+- `php -l src/Agent/AgentRunner.php`
+- `php -l src/Config/AgentRunnerConfig.php`
+- `php -l src/Config/ChatMessagesConfig.php`
+- YAML-Parsing von `config/retriex/chat-messages.yaml`
+- `ChatMessagesConfig::validate()`
+- `AgentRunnerConfig::getProductionUiFollowUpActions('shop_results')`
+
+## Empfohlene Regressionstests
+
+1. `testomat 808 indikatoren`
+   - Erwartung: keine Action `Nur Geräte anzeigen`.
+   - Erwartung: `Preis anzeigen` nur, wenn die Antwort noch keine Preise enthält.
+   - Erwartung: keine Action-Karte, falls nur redundante oder nicht sinnvolle Actions übrig wären.
+
+2. Nach einer gemischten Shop-Trefferliste mit Geräten und Zubehör:
+   - Erwartung: Rollenfilter erscheinen nur, wenn sie die aktuelle Liste sinnvoll verengen.
+   - Erwartung: Klick-Prompt enthält den aktuellen Shopkontext, z. B. `Suche im Shop nach <shop_query> und zeige daraus nur Geräte.`
+
+3. Smalltalk / No-Evidence:
+   - Erwartung: keine Follow-up-Actions.
+
+4. Technische RAG-Antwort mit belastbarer Evidenz:
+   - Erwartung: `Technische Details anzeigen` kann weiterhin erscheinen.