MtoRagSystem/RETRIEX_PATCH_38_YAML_EXTERNALIZATION_HARDENING_README.md

RetrieX Patch p38 - YAML Externalization Hardening

Ziel

Dieser Patch schliesst die nach p37 verbliebenen sinnvollen YAML-Externalization-Luecken im PHP-Core. Fokus ist nicht technische Infrastruktur, sondern fachliche, sprachliche und UI-nahe Listen, Tokens, Vergleichswerte, Prompt-Regeln und Normalisierungsregeln.

Die Leitlinie bleibt:

• keine neuen Token-/Stringlisten im PHP-Core
• fachliche, sprachliche und UI-nahe Werte ueber YAML
• bestehende 1.5.3-Logik nicht fachlich veraendern
• keine neuen Spezialfaelle fuer konkrete Produkte

Geaenderte Dateien

• config/retriex/agent.yaml
• config/retriex/language.yaml
• config/retriex/prompt.yaml
• src/Config/AgentRunnerConfig.php
• src/Config/LanguageCleanupConfig.php
• src/Config/PromptBuilderConfig.php
• src/Agent/AgentRunner.php
• src/Agent/PromptBuilder.php
• src/Knowledge/Retrieval/QueryCleaner.php
• src/Knowledge/Retrieval/NdjsonLexicalIndexBuilder.php
• src/Knowledge/Retrieval/NdjsonKeywordRetriever.php
• src/Knowledge/Retrieval/NdjsonChunkLookup.php
• src/Knowledge/Retrieval/NdjsonHybridRetriever.php

Inhalt

AgentRunner

Externalisiert wurden insbesondere:

• Placeholder-Ausgaben der Query-/Input-Normalisierung
• Shop-Repair-/Shop-Query-Heartbeat-Meldungen
• No-LLM-Produktfeldtexte und Produktzeilen-Templates
• Follow-up-Kontextlabels
• Production-UI-Stage-Labels
• Production-UI-Confidence-Labels
• Production-UI-Texte, Templates und Shop-Meta-Labels
• Follow-up-Action-Chips fuer Commerce und Knowledge

Zusaetzlich nutzt der Runner vorhandene Language-Cleanup-Konfiguration fuer ASCII-Transliteration, Separator-Normalisierung und Dash-Normalisierung.

Language Cleanup

language.yaml enthaelt nun zusaetzlich zentrale Normalisierungsregeln fuer:

• Wortseparatoren (-, /, _)
• Unicode-Dash-Aequivalente

LanguageCleanupConfig stellt dafuer zentrale Methoden bereit:

• replaceWordSeparatorsWithSpace()
• normalizeDashEquivalents()

PromptBuilder

Externalisiert wurden verbliebene Prompt-/Policy-Regeln rund um:

• Fallback-Escalation bei vorhandenen Shop-Ergebnissen
• Measurement-Evidence-Guard-Templates
• finale Measurement-Evidence-Regeln
• Parameter-Split-Pattern
• Parameter-Trim-Zeichen

Die Unicode-Dash-Normalisierung nutzt nun ebenfalls LanguageCleanupConfig.

Retrieval-Normalisierung

Wiederholte Separatorlisten in Retrieval-Klassen wurden durch die zentrale Language-Cleanup-Methode ersetzt.

Betroffen:

• QueryCleaner
• NdjsonLexicalIndexBuilder
• NdjsonKeywordRetriever
• NdjsonChunkLookup
• NdjsonHybridRetriever

Bewusst nicht externalisiert

Nicht Ziel dieses Patches waren rein technische Infrastrukturwerte, z. B.:

• Boolean-Parser-Werte wie true, false, yes, no, on, off
• technische Statuscodes und interne State-Keys
• DTO-/Array-Schluessel
• Log-/HTTP-/Encoding-Infrastruktur
• Zeilenumbruch-Normalisierung

Diese Werte sind keine fachlichen oder sprachlichen Matching-/Prompt-/UI-Listen.

Lokale Validierung

Da im ZIP kein vendor/ enthalten ist, konnten Symfony-Console-Checks nicht direkt ausgefuehrt werden.

Durchgefuehrt wurden:

• php -l fuer alle geaenderten PHP-Dateien: OK
• YAML-Parse fuer geaenderte YAML-Dateien: OK
• statische Greps auf die zuvor identifizierten Reststellen: OK

Gepruefte ehemalige Problemklassen:

• keine PHP-Funde mehr fuer normalized user input / corrected user input
• keine PHP-Funde mehr fuer die harten Measurement-Evidence-Regeltexte
• keine PHP-Funde mehr fuer die alten Separatorlisten ['-', '/', '_']
• keine PHP-Funde mehr fuer die alten Unicode-Dash-Listen
• keine PHP-Funde mehr fuer die AgentRunner-UI-Labels wie RetrieX-Status, Datenbasis, Folgeaktionen, Artikelnummer, Preis, Verfuegbarkeit, Relevanz

Empfohlene Checks nach Einspielen

Bitte im echten Projekt mit installiertem vendor/ ausfuehren:

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