patch 19

RETRIEX_PATCH_18_EVIDENCE_STATE_AGGREGATE_CONSISTENCY_README.md

@@ -0,0 +1,112 @@
+# RetrieX Patch 18 – Evidence State / Aggregate Consistency Fix
+
+## Zweck
+
+Dieser Patch behebt die Status-/Antwort-Konsistenz für Aggregat- und Zählfragen wie:
+
+`wieviele testomat geräte haben wir`
+
+Bisher konnte RetrieX bei solchen Fragen semantisch passende RAG-Treffer finden und die Beleglage trotzdem als `fachlich belegt` anzeigen, obwohl die Antwort selbst keine belastbare Zählinformation nennen konnte.
+
+## Fachliche Entscheidung
+
+`fachlich belegt` wird nicht pauschal abgewertet. Stattdessen wird ein eigener Zwischenzustand eingeführt:
+
+`aggregate_missing`
+
+Dieser Zustand bedeutet:
+
+- Es wurden Quellen geprüft.
+- Es gibt semantisch passende Quellen.
+- Die Quellen enthalten aber keine explizite Aggregat-/Zählinformation für die angefragte Anzahl.
+
+Die Nutzeranzeige wird dadurch präziser:
+
+`Beleglage: geprüfte Quellen, keine passende Zählinformation`
+
+## Änderungen
+
+### `src/Agent/AgentRunner.php`
+
+- Erkennt Aggregatfragen weiterhin über YAML-konfigurierte Patterns.
+- Prüft bei Aggregatfragen zusätzlich auf explizite Aggregat-Antwortbelege.
+- Gibt bei fehlender Zählinformation den neuen Evidence-State `aggregate_missing` zurück.
+- Zeigt für diesen Zustand eine präzisere Beleglage an.
+- Übergibt den Evidence-State auch an die finale Production-UI-Confidence-Logik.
+
+### `src/Agent/PromptBuilder.php`
+
+- Behandelt `aggregate_missing` als eigenen Reliability-State.
+- Gibt dem LLM explizite Regeln, keine Produktfamilien-/Portfolio-Nennungen als konkrete Anzahl zu verkaufen.
+
+### `src/Config/AgentRunnerConfig.php`
+
+- Neuer YAML-backed Getter:
+
+`getRagEvidenceAggregateAnswerEvidencePatterns()`
+
+### `src/Config/RetriexEffectiveConfigProvider.php`
+
+- Neuer Config-Pfad wird im Effective Config Output sichtbar.
+- Neuer Config-Pfad wird als Regex-Liste validiert.
+
+### `config/retriex/agent.yaml`
+
+- Neuer YAML-Pfad:
+
+`rag_evidence_guard.aggregate_answer_evidence_patterns`
+
+Diese Patterns beschreiben explizite Zähl-/Aggregatbelege, z. B. `Anzahl ... 12`, `insgesamt ... 12`, oder `Sortiment umfasst ... 12`.
+
+### `config/retriex/prompt.yaml`
+
+- Neuer Reliability-State:
+
+`aggregatfrage_keine_belastbare_zaehlinformation`
+
+## Nicht geändert
+
+- Keine Shop-Follow-up-Logik.
+- Keine Produktrollen-Logik.
+- Kein allgemeines Retrieval-/Scoring-Tuning.
+- Keine harte neue PHP-Keywordliste im Core.
+- Keine Strict-YAML-Validation.
+
+## Lokale Prüfung in dieser Umgebung
+
+Durchgeführt:
+
+```bash
+php -l src/Agent/AgentRunner.php
+php -l src/Agent/PromptBuilder.php
+php -l src/Config/AgentRunnerConfig.php
+php -l src/Config/RetriexEffectiveConfigProvider.php
+```
+
+Zusätzlich:
+
+- YAML-Parse für `config/retriex/agent.yaml` erfolgreich.
+- YAML-Parse für `config/retriex/prompt.yaml` erfolgreich.
+- Regex-Smoke-Test für die neuen Aggregat-Antwortpatterns erfolgreich.
+
+Nicht vollständig ausführbar in dieser Umgebung:
+
+```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
+```
+
+Grund: Die ZIP enthält keine installierten Composer-Dependencies; `composer install` kann hier wegen fehlender PHP-Extensions und fehlendem Netzwerkzugriff nicht vollständig abgeschlossen werden.
+
+## Pflichtprüfung nach Einspielen
+
+Bitte nach dem Einspielen im Projekt ausführen:
+
+```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
+```