MtoRagSystem/genre_yaml_konfigurationsanleitung.md

Konfigurationsanleitung config/retriex/genre.yaml

Stand: aktueller Arbeitsstand aus rag-inprogress.zip.

Diese Anleitung beschreibt, welche Bereiche in genre.yaml gepflegt werden, welche Auswirkungen Änderungen haben und wie eine Anpassung sicher durchgeführt wird.

---

1. Zweck der Datei

config/retriex/genre.yaml ist die zentrale fachliche Konfigurationsfläche für eine RetrieX-Installation mit genau einem aktiven Genre.

Aktuell ist das Genre:

id: water_analysis
label: Water analysis / measurement devices
mode: single_installation_single_genre

Wichtig:

• Eine Installation steht für ein Genre.
• Es gibt keine Multi-Tenant-, Multi-Shop-, Host-, API-Key- oder Request-basierte Genre-Umschaltung.
• Fachliche Listen, Begriffe, Muster, Produktrollen, Antwortregeln und genreabhängige Guardrails gehören in genre.yaml.
• Technische Einstellungen wie Modell, Vector-Index, Chunking, Cache, LLM-Parameter, Store-API-Credentials oder allgemeine Infrastruktur bleiben außerhalb von genre.yaml.
• Die alten YAML-Dateien bleiben als technische Verarbeitungsschicht, leere Fallbacks oder eingefrorene Legacy-Pfade erhalten. Neue fachliche Werte sollen dort nicht wieder eingeführt werden.

---

2. Grundstruktur

Die Datei hängt am Symfony-Parameter:

parameters:
  retriex.genre.config:
    id: water_analysis
    label: Water analysis / measurement devices
    mode: single_installation_single_genre
    description: ...
    adaptation_surface: ...
    configuration_values: ...

2.1 id, label, mode, description

Feld	Bedeutung	Auswirkung	Anpassung
id	Technischer Genre-Identifier	Metadaten, Diagnose, zukünftige Dokumentation	Bei Umwidmung ändern, z. B. fashion, spare_parts, electronics
label	Lesbarer Name	Audit-/Debug-/Dokumentationswert	Frei sprechend halten
mode	Betriebsmodell	Beschreibt bewusst single_installation_single_genre	Nicht auf Multi-Genre ändern, solange keine Architektur dafür existiert
description	Kurzbeschreibung	Dokumentation	An neues Genre anpassen

2.2 adaptation_surface

adaptation_surface ist die Landkarte. Sie gruppiert alle Konfigurationsbereiche, die bei einer Umwidmung des Systems überprüft werden müssen.

Sie enthält Beschreibungen und paths auf alte/effective Runtime-Konfigurationspfade.

Auswirkung:

• Ändert normalerweise nicht direkt das Antwort- oder Suchverhalten.
• Wird für Validierung, Audit und Nachvollziehbarkeit genutzt.
• Muss synchron zu configuration_values bleiben.
• Jede Gruppe in adaptation_surface braucht eine entsprechende Gruppe in configuration_values.

Anpassen:

• Nur ändern, wenn ein neuer genreabhängiger Runtime-Pfad hinzukommt, wegfällt oder umbenannt wird.
• Keine fachlichen Werte dort pflegen.
• paths müssen gültige Pfade sein; falsche Pfade werden durch Validate/Audit sichtbar.

2.3 configuration_values

configuration_values ist die eigentliche zentrale Wertefläche.

Auswirkung:

• Die Runtime-Konfigurationsklassen lesen diese Werte bevorzugt über GenreConfig.
• Änderungen hier beeinflussen Retrieval, Shop-Suche, Commerce-Routing, Search Repair, Antwortregeln, Follow-up-Auflösung, Produktrollentrennung und Regression-Guardrails.
• Die alten Pfade sollen leer oder eingefroren bleiben.

Anpassen:

• Fachliche Änderungen immer hier vornehmen.
• Die bestehende Gruppenstruktur beibehalten.
• source_paths nicht entfernen.
• Nach Änderungen immer Validate, Regression und Audits ausführen.

2.4 source_paths

source_paths verknüpft einen Wertknoten in configuration_values mit seinen alten/effective Config-Pfaden.

Auswirkung:

• Dient Audit, Source-of-Truth-Guard und Migrationsnachvollziehbarkeit.
• Liefert nicht selbst den Runtime-Wert.
• Falsche oder unbekannte Pfade erzeugen Validate-/Audit-Probleme.

Anpassen:

• Bei reinen Wertänderungen normalerweise unverändert lassen.
• Nur ändern, wenn die technische Verdrahtung oder ein Legacy-Pfad wirklich geändert wurde.
• Wenn ein Wertknoten direkte Payload enthält, muss er selbst oder ein Parent-Knoten source_paths deklarieren.
• Doppelte oder leere source_paths sind nicht zulässig.

---

3. Runtime-Lesemodell

Die wichtigsten Klassen erhalten GenreConfig per Dependency Injection und lesen fachliche Werte bevorzugt aus genre.yaml:

Klasse	Liest aus genre.yaml	Typische Wirkung
DomainVocabularyConfig	Produktrollen, Vocabulary-Views, Prompt-/Shop-/Retrieval-Views, Maps	Grundvokabular, Shop-/Prompt-Rollen, Evidence-Begriffe
CommerceQueryParserConfig	Marken, Canonical-Terms	Query-Normalisierung für Shop-Suche
QueryEnricherConfig	Query-Enrichment-Regeln	Erweiterung/Umformung von Suchanfragen
CommerceIntentConfig	Commerce-Signale, Größen-/Farb-/Produktmuster	Erkennung von Kauf-, Preis-, Shop- und Beratungsabsicht
SalesIntentConfig	Sales-/Vergleichs-/ROI-Signale	Sales-orientierte Intent-Erkennung
AgentRunnerConfig	Follow-ups, Shop-Query-Cleanup, Direct Answer, Längenfilter, RAG-Anker	Gesprächskontext, Shop-Fallbacks, direkte Shopantworten
PromptBuilderConfig	Antwortpriorität, Formatregeln, Fact-Grounding, Evidence Guards	Qualität und Grenzen der finalen Antwort
SearchRepairConfig	Direct-Attribute-Lookup, Kandidatenmuster, Repair-Tokens	Reparatur schwacher Shop-Suchen
NdjsonHybridRetrieverConfig	Exact Selection, Indicator-/Tabellenmuster	Präzision bei RAG-Fakten und Tabellenextraktion
LanguageCleanupConfig	Protected Terms	Schutz wichtiger Tokens vor Cleanup
GovernanceConfig	Regression-/Audit-Guardrails	Schutz vor Regressions- und Core-Listen-Rückfällen

Die Legacy-YAMLs sind weiterhin wichtig, aber nicht mehr der primäre Pflegeort für genreabhängige Fachwerte.

---

4. Gruppenübersicht mit Auswirkungen

4.1 product_roles

Zweck: Definiert, welche Begriffe als Hauptprodukt, Zubehör, Verbrauchsmaterial oder produktrollenbezogene Prompt-/Shop-Begriffe gelten.

Wichtige Werte:

• primary_product_terms.terms
• accessory_product_terms.terms
• requested_accessory_code_terms.terms
• shop_views.*
• prompt_views.*
• no_llm_fallback_terms.*

Auswirkung:

• Entscheidet, ob eine Anfrage eher Gerät/Hauptprodukt oder Zubehör meint.
• Beeinflusst Shop-Query-Aufbau, Produktrollentrennung und Antwortformat.
• Verhindert z. B., dass Zubehör als Gerät oder Geräte als Zubehör beantwortet werden.
• Steuert No-LLM-Fallbacks bei einfachen oder schwach belegten Anfragen.

Anpassung:

• Für ein neues Genre zuerst diese Gruppe anpassen.
• Hauptproduktbegriffe vollständig ersetzen, nicht nur ergänzen.
• Zubehör- und Verbrauchsmaterialbegriffe getrennt halten.
• Synonyme, Umlaute und ASCII-Varianten aufnehmen, wenn Nutzer sie realistisch verwenden.
• Keine zu allgemeinen Wörter wie produkt, artikel, teil allein als starke Rollenbegriffe verwenden, sonst steigt Fehlrouting.

Beispiel Wasseranalyse:

primary_product_terms:
  terms:
    - messgerät
    - analysegerät
    - testomat
accessory_product_terms:
  terms:
    - indikator
    - reagenz
    - zubehör

Beispiel Umwidmung Fashion:

primary_product_terms:
  terms:
    - shirt
    - hose
    - jacke
    - schuh
accessory_product_terms:
  terms:
    - gürtel
    - tasche
    - pflegeset

---

4.2 product_attributes

Zweck: Definiert genreabhängige Attribute und Constraints, z. B. Kabellänge, Messgröße, Größe, Farbe oder Material.

Wichtige Werte:

• direct_attribute_cleanup.product_type_terms
• direct_attribute_cleanup.stop_terms
• direct_attribute_cleanup.comparative_constraint_patterns
• size_and_color_terms.*
• numeric_length_constraints.length_sort.*
• numeric_length_constraints.length_filter.*

Auswirkung:

• Beeinflusst direkte Produktattribut-Suchen wie „Anschlusskabel länger 20m“.
• Steuert, welche Wörter nach Cleanup übrig bleiben müssen, damit Search Repair greift.
• Aktiviert Sortierung oder Filterung nach numerischen Längen-/Größenwerten.
• Commerce-Intent erkennt Größe/Farbe/Varianten besser oder schlechter abhängig von diesen Listen.

Anpassung:

• Produktartbegriffe an das Genre anpassen, z. B. anschlusskabel durch sneaker, sofa, akku, ersatzfilter ersetzen.
• Stop-Terme nur für Bedienwörter verwenden, nicht für fachliche Kernbegriffe.
• Regex-Patterns vorsichtig ändern und mit realen Anfragen testen.
• Für Fashion Größen/Farben ausbauen; für Ersatzteile eher Maße, Kompatibilität, Seriennummern, Gewinde, Spannung usw. pflegen.

Achtung:

• nicht, kein, Modellkürzel und fachliche Kurzbegriffe dürfen nicht versehentlich als Stopword entfernt werden.
• Numerische Patterns müssen Einheiten passend zum Genre abbilden. Bei Fashion wäre cm, inch, EU, UK; bei Kabeln m, meter.

---

4.3 brands_and_canonical_terms

Zweck: Pflegt Marken, Token-Normalisierung, Synonyme und Query-Enrichment.

Wichtige Werte:

• known_brands.terms
• canonical_terms.map
• query_enrichment_rules.rules
• accessory_focus_variants.map
• rag_evidence_synonyms.map

Auswirkung:

• Marken werden in Shop-Queries und Query-Parsing besser erkannt.
• Plural-/Sprachvarianten werden auf kanonische Suchbegriffe zurückgeführt.
• Query-Enrichment ergänzt fachlich sinnvolle verwandte Suchbegriffe.
• Evidence-Guards verstehen Synonyme besser.

Anpassung:

• Markenliste shop- und genrebezogen pflegen.
• Canonical Map nur für eindeutige Äquivalenzen verwenden.
• Query-Enrichment nicht als Ranking-Hack missbrauchen; nur semantisch nahe Begriffe ergänzen.
• Synonyme nicht mit Nicht-Äquivalenten mischen.

Beispiel:

canonical_terms:
  map:
    reagenzien: reagenz
    indicators: indikator

Für Fashion:

canonical_terms:
  map:
    sneakers: sneaker
    shirts: shirt
    t-shirts: tshirt

---

4.4 intent_and_routing

Zweck: Steuert, ob eine Anfrage als Shop-, Preis-, Beratungs-, Produktwahl-, Vergleichs- oder Sales-Anfrage erkannt wird.

Wichtige Werte:

• fuzzy_routing_terms.terms
• commerce_intent.strong_signals
• commerce_intent.advisory_signals
• commerce_intent.advisory_product_selection_patterns
• commerce_intent.explicit_commerce_intent_patterns
• commerce_intent.model_like_product_pattern
• sales_intent.*

Auswirkung:

• Entscheidet, ob Shop-Suche gestartet wird.
• Erkennt Follow-ups wie „suche im shop“ oder „was kostet das“.
• Unterscheidet Beratung von reiner Wissensfrage.
• Beeinflusst, wann Produktlisten, Preise oder Produktempfehlungen erzeugt werden.

Anpassung:

• Shop-/Preis-/Kaufbegriffe meist generisch belassen.
• Produktwahlmuster genrebezogen anpassen, z. B. mit welchem testomat durch welche jacke, welcher akku, welches ersatzteil ersetzen.
• model_like_product_pattern nur ändern, wenn Modell-/SKU-Struktur im neuen Genre anders ist.
• Sales-Signale nur anpassen, wenn die Installation tatsächlich Sales-/B2B-Beratung leisten soll.

Risiko:

• Zu breite starke Commerce-Signale führen dazu, dass Wissensfragen fälschlich als Shop-Anfragen behandelt werden.
• Zu enge Muster verhindern gewünschte Shop-Follow-ups.

---

4.5 context_resolution

Zweck: Löst referenzielle Folgefragen und baut aus dem Verlauf sinnvolle Shop-Queries.

Wichtige Werte:

• commercial_table_follow_up.*
• referential_terms.terms
• history_anchor_enrichment.*
• meta_query_guard.*
• rag_anchor_enrichment.*

Auswirkung:

• „Was kostet der Indikator?“ kann aus vorherigem Kontext Indikatortyp 300 ableiten.
• „Suche im Shop“ kann aus einer vorherigen Produktempfehlung eine konkrete Shop-Suche erzeugen.
• Meta-only-Anfragen wie shop, preis, kosten werden nicht verworfen, wenn brauchbarer Verlaufskontext existiert.
• Numerische RAG-Anker wie 0,02 °dH können mit Produktankern kombiniert werden.

Anpassung:

• history_anchor_patterns und anchor_patterns an typische Modell-, Zubehör- oder Variantenanker des Genres anpassen.
• query_template_with_model und query_template_without_model nur ändern, wenn Referenzauflösung anders formuliert werden soll.
• meta_only_terms generisch halten, aber context_fallback_filter_terms genrebezogen prüfen.
• rag_anchor_enrichment.subject_terms an fachliche Kernthemen des Genres anpassen.

Beispiel Wasseranalyse:

query_template_with_model: '{model} indikator'
query_template_without_model: 'indikator'

Für Ersatzteile könnte es z. B. werden:

query_template_with_model: '{model} ersatzteil'
query_template_without_model: 'ersatzteil'

---

4.6 shop_query_runtime

Zweck: Steuert Shop-Query-Cleanup, direkte Shopantworten, semantische Suchbegriffe und Ergebnisidentität.

Wichtige Werte:

• current_input_preservation_terms.terms
• semantic_shop_search_tokens.terms
• stopword_cleanup.terms
• compound_prefix_match.terms
• primary_identity_repair.stop_terms
• direct_answer.*

Auswirkung:

• Bestimmte kurze Begriffe wie pH, rx, orp bleiben in Shop-Queries erhalten.
• Semantische Shop-Suchbegriffe verbessern Query-Erweiterung.
• Stopword-Cleanup entfernt Bedienwörter aus Shop-Queries.
• Direct Answer bestimmt, wie Shop-Ergebnisse direkt textlich ausgegeben werden.

Anpassung:

• Für jedes neue Genre kurze geschützte Produkt-/Attributtokens eintragen, z. B. xl, usb-c, m8, a4, sofern relevant.
• Stopwords nicht mit Produktkürzeln vermischen.
• Direct-Answer-Texte an Tonalität und Produktdomäne anpassen.
• max_results so wählen, dass Antworten nicht überladen werden.

Achtung:

• Wenn ein wichtiger kurzer Begriff nicht geschützt ist, kann er beim Cleanup verschwinden.
• Wenn zu viele allgemeine Begriffe geschützt sind, werden Shop-Queries unscharf.

---

4.7 result_identity_and_answer_policy

Zweck: Definiert Prompt-Regeln, Antwortpriorität, Produktrollen-Trennung und Evidence-Guards.

Wichtige Werte:

• prompt_rules.output_priority_technical
• prompt_rules.response_format_technical
• prompt_rules.response_format_accessory
• prompt_rules.fact_grounding_technical
• prompt_rules.fact_grounding_with_shop
• prompt_keyword_views.technical_product_keywords
• measurement_evidence_guard_terms.*
• measurement_evidence_maps.*

Auswirkung:

• Bestimmt, welche Fakten in technischen Antworten priorisiert werden.
• Verhindert, dass Eigenschaften eines Produkts einem anderen Produkt zugeschrieben werden.
• Steuert die Trennung zwischen Gerät/Hauptprodukt und Zubehör/Verbrauchsmaterial.
• Sichert, dass Messfähigkeit, Zubehörbezug oder Attributbelege nur beantwortet werden, wenn sie belegt sind.

Anpassung:

• Antwortregeln domänenspezifisch, aber knapp und testbar formulieren.
• Evidence-Maps für echte fachliche Mess-/Attributdimensionen pflegen.
• Nicht-Äquivalenzen explizit halten, z. B. freies Chlor ist nicht automatisch Gesamtchlor.
• Für ein anderes Genre positive und negative Kontextbegriffe neu definieren.

Beispiel:

measurement_evidence_maps:
  request_terms:
    redox:
      - redox
      - orp
  non_equivalent_terms:
    free_chlorine:
      - Gesamtchlor

Für Fashion könnte eine analoge Struktur z. B. Größen-/Material-/Passform-Evidence absichern.

---

4.8 search_repair

Zweck: Repariert schwache oder zu kurze Shop-Suchen und extrahiert Modell-/Zubehör-/Spezifitätskandidaten.

Wichtige Werte:

• direct_product_attribute_lookup.*
• candidate_patterns.specific_model_candidate_patterns
• candidate_patterns.patterns.*
• candidate_terms.*

Auswirkung:

• Verbessert Suche, wenn die primäre Shop-Suche zu wenig oder falsche Ergebnisse liefert.
• Erkennt Modellkandidaten, Zubehörcodes, Bundle-/Accessory-Begriffe und Spezifitätsanker.
• Hilft bei Fällen wie direkten Produktattributfragen oder unvollständigen Shop-Follow-ups.

Anpassung:

• Candidate-Terms an das Genre anpassen.
• Regex nur ändern, wenn Modell-/SKU-/Zubehörcode-Struktur wirklich anders ist.
• min_query_tokens_after_cleanup nicht zu niedrig setzen, sonst repariert das System sehr unspezifische Anfragen.
• Accessory-Code-Muster für neue Domänen neu modellieren, z. B. Ersatzteilnummern, DIN-/Normteile, SKU-Formate.

Regex-Hinweis:

• Patterns sind Strings wie '/.../iu'.
• YAML-Quoting beibehalten.
• Nach Änderung immer Syntax und Regression testen.

---

4.9 retrieval_and_language

Zweck: Schützt wichtige Sprache-/Fachbegriffe und steuert genreabhängige Retrieval-Hilfen.

Wichtige Werte:

• protected_terms.terms
• cleanup_profiles.*
• retrieval_vocabulary_views.*
• exact_selection.*

Auswirkung:

• Protected Terms verhindern, dass wichtige Wörter beim Cleanup entfernt werden.
• Retrieval-Vocabulary hilft, Dokumenttypen, Geräte, Reagenzien/Zubehör oder Produkttexte zu erkennen.
• Exact Selection verbessert gezielte Tabellen-/Faktauswahl, z. B. Indikatortabellen.
• Falsche Werte hier können RAG-Fakten, Follow-up-Präzision und Tabellenextraktion deutlich verschlechtern.

Anpassung:

• Protected Terms mit kurzen, wichtigen Tokens des Genres füllen.
• Cleanup-Profile nur vorsichtig ändern; allgemeine Sprachbereinigung gehört weiter in language.yaml, fachlicher Schutz in genre.yaml.
• looks_like_*-Listen an Dokument- und Produkttypen des neuen Genres anpassen.
• Exact-Selection-Bereiche nur verwenden, wenn das Genre ähnliche strukturierte Tabellen-/Faktmuster hat.

Achtung:

• Negationen wie nicht, kein, keine schützen.
• Kurze Modell- oder Fachkürzel schützen, z. B. pH, rx, th; in anderen Genres z. B. XL, USB, M8.

---

4.10 shop_data_mapping

Zweck: Beschreibt, wie Shopware-Felder und Produkttexte für diese Installation interpretiert werden.

Wichtige Werte:

• custom_fields.primary
• custom_fields.secondary
• custom_fields.use_cases
• custom_fields.languages
• text.*
• role_guard.*
• commerce_connection.*

Auswirkung:

• Bestimmt, welche Shopware-Custom-Fields für Produktbeschreibung, Attribute, Einsatzgebiete oder Sprache genutzt werden.
• Textlabels beeinflussen die Darstellung/Interpretation von Shopdaten.
• Role Guard filtert Zubehör bei Geräteanfragen bzw. hält ambige Produkte bei Geräteanfragen.
• Store-API-URL und max results sind runtime-/env-aufgelöste Pfade und im Guard explizit erlaubt.

Anpassung:

• Bei anderem Shopdatenmodell zuerst custom_fields prüfen.
• Labels an Shopdaten anpassen, aber nicht mit Prompt-Regeln verwechseln.
• Role Guard nur ändern, wenn die Produktdaten sauber zwischen Hauptprodukt und Zubehör unterscheiden.
• Credentials und technische Verbindungswerte nicht hart in genre.yaml eintragen; ENV-Referenzen beibehalten.

---

4.11 governance_and_regression

Zweck: Schützt das aktive Genre durch Regression-Baselines und Audit-Regeln.

Wichtige Werte:

• regression_baseline.*
• vocabulary_guardrails
• core_pattern_audit.*

Auswirkung:

• Regressionstests wissen, welche Kurzmodelle, Messwerte, fachlichen Keywords und Shop-Query-Fälle geschützt sind.
• Pattern-Audit erkennt, wenn wieder harte Fachlisten in PHP-Code oder falsche Config-Pfade wandern.
• Verhindert Rückfälle in Core-Keywordlisten.

Anpassung:

• Bei Genre-Umwidmung Regression-Baseline konsequent austauschen.
• Keine alten Wasseranalyse-Werte stehen lassen, wenn sie für das neue Genre nicht gelten.
• core_pattern_audit.domain_marker_terms mit neuen Fachmarkern füllen, damit Audit Rückfälle erkennt.
• Technische Audit-Ausnahmen nur erweitern, wenn wirklich nötig und mit Begründung.

---

5. Source-of-Truth-Guard

Der Guard wird über config/retriex/governance.yaml gesteuert:

genre_source_of_truth:
  enabled: true
  source: genre.yaml
  legacy_mode: frozen_or_empty_fallback

Er prüft:

1. genre.configuration_values ist vorhanden und nicht leer.
2. Jede adaptation_surface-Gruppe hat eine passende configuration_values-Gruppe.
3. Jeder relevante Wertknoten ist durch source_paths abgedeckt.
4. Alle source_paths zeigen auf bekannte Config-Pfade.
5. Alte Legacy-Pfade sind entweder leer, runtime-aufgelöst erlaubt oder per SHA-256-Hash eingefroren.
6. Wenn ein eingefrorener Legacy-Wert geändert wird, schlägt Validate/Audit fehl.

Bedeutung für die Pflege:

• Fachliche Werte in genre.yaml ändern.
• Legacy-Werte nicht parallel ändern.
• Wenn ein Legacy-Pfad absichtlich nicht leer bleiben muss, braucht er einen bewussten Hash-Eintrag in governance.yaml.
• Wenn ein neuer Runtime-Pfad genreabhängig wird, muss er in adaptation_surface, configuration_values.source_paths und ggf. in die Guard-Logik aufgenommen werden.

---

6. Sichere Änderungsreihenfolge

Kleine Wertänderung innerhalb des aktuellen Genres

1. Passende Gruppe in configuration_values finden.
2. Nur dort Werte ändern.
3. source_paths unverändert lassen.
4. YAML-Syntax prüfen.
5. Pflichtchecks ausführen.
6. Relevante manuelle Regression mit realen Beispielanfragen testen.

Neues Synonym oder neue Marke

1. Prüfen, ob es ein Rollenbegriff, Attribut, Canonical Term oder Query-Enrichment ist.
2. In der passenden Gruppe ergänzen:
   • Marke: brands_and_canonical_terms.known_brands.terms
   • Synonym mit echter Gleichwertigkeit: canonical_terms.map
   • Query-Erweiterung: query_enrichment_rules.rules
   • Evidence-Synonym: rag_evidence_synonyms.map
3. Keine Duplikate in Legacy-YAMLs eintragen.
4. Shop- und RAG-Testfälle ausführen.

Neues Attribut oder Constraint

1. Produkt-/Attributbegriff in product_attributes.direct_attribute_cleanup.product_type_terms aufnehmen.
2. Wenn nötig Cleanup-Stopterms prüfen.
3. Vergleichs-/Filterpattern nur ergänzen, wenn echte Nutzerformulierungen vorliegen.
4. Wenn das Attribut in Antworten belegt werden muss, zusätzlich result_identity_and_answer_policy prüfen.
5. Tests mit positiver und negativer Anfrage ausführen.

Umwidmung auf ein neues Genre

Empfohlene Reihenfolge:

1. id, label, description ändern.
2. product_roles vollständig neu definieren.
3. product_attributes neu definieren.
4. brands_and_canonical_terms austauschen.
5. intent_and_routing auf neue Produktsprache anpassen.
6. context_resolution auf neue Verlaufanker umstellen.
7. shop_query_runtime und geschützte Kurzbegriffe anpassen.
8. result_identity_and_answer_policy neu formulieren.
9. search_repair für neue Modell-/SKU-/Zubehörmuster anpassen.
10. retrieval_and_language auf neue Dokument-/Produktbegriffe umstellen.
11. shop_data_mapping an Shopware-Felder prüfen.
12. governance_and_regression komplett neu setzen.
13. Tests und Audits ausführen.

Wichtig: Nicht nur neue Werte ergänzen, sondern alte Wasseranalyse-spezifische Werte entfernen, wenn sie im neuen Genre keine Bedeutung haben. Sonst bleiben falsche Anker aktiv.

---

7. Pflichtchecks nach Änderungen

Im Projekt mit installiertem vendor/ ausführen:

bin/console cache:clear
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

Zusätzlich sinnvoll:

php -l src/Config/GenreConfig.php
python3 - <<'PY'
import yaml
from pathlib import Path
for path in Path('config/retriex').glob('*.yaml'):
    yaml.safe_load(path.read_text())
print('YAML parse OK')
PY

Hinweis: In der entpackten ZIP liegt kein vendor/, deshalb sind die bin/console-Checks dort nicht lokal ausführbar. Sie müssen im echten Projektstand mit Dependencies laufen.

---

8. Typische Fehler und Auswirkungen

Fehler	Auswirkung	Korrektur
Fachliche Werte in Legacy-YAML ergänzt	Source-of-Truth-Guard kann brechen; doppelte Pflege kehrt zurück	Wert nach genre.yaml verschieben, Legacy leer/eingefroren lassen
source_paths entfernt	Validate/Audit meldet fehlende Abdeckung	source_paths am Wertknoten oder Parent wiederherstellen
Allgemeines Wort als starkes Rollenwort	Falsches Routing, unscharfe Shop-Suche	Nur fachlich trennscharfe Begriffe verwenden
Wichtiges Kürzel nicht geschützt	Query-Cleanup entfernt es; Shop/RAG verliert Präzision	In protected_terms oder current_input_preservation_terms aufnehmen
Regex falsch escaped	Runtime-/Validate-Fehler oder keine Treffer	YAML-Quoting und Regex-Syntax prüfen
Alte Genrebegriffe bei Umwidmung behalten	Antworten/Shopqueries driften ins alte Genre	Alte Listen aktiv bereinigen
Negationen als Stopwords entfernt	Antworten können semantisch falsch werden	nicht, kein, keine schützen
Query-Enrichment zu breit	Shop-Suche findet falsche Produkte	Nur echte fachliche Nähe ergänzen
Evidence-Synonyme zu breit	Eigenschaften werden falsch übertragen	Synonyme und Nicht-Äquivalenzen sauber trennen

---

9. Entscheidungsregeln: Wohin gehört welcher Wert?

Wertart	Gehört nach genre.yaml?	Zielgruppe
Produktrollen, Zubehörrollen, Verbrauchsmaterialrollen	Ja	product_roles
Marken und eindeutige Synonyme	Ja	brands_and_canonical_terms
Shop-/Kauf-/Preis-Signale mit Genrebezug	Ja	intent_and_routing
Nutzer-Stopwords ohne Fachbezug	Eher nein	language.yaml, falls allgemeine Sprachschicht
Geschützte Fachkürzel	Ja	retrieval_and_language.protected_terms oder shop_query_runtime.current_input_preservation_terms
Prompt-Antwortregeln mit Fachbezug	Ja	result_identity_and_answer_policy
Technische Prompt-Struktur ohne Fachbezug	Nein	prompt.yaml
Modellparameter, Temperatur, Top-K	Nein	Model-/Runtime-Konfiguration
Shopware-Credentials	Nein	ENV / technische Config
Shopware-Custom-Field-Mapping	Ja, wenn installations-/genreabhängig	shop_data_mapping
Regression-Fachwerte	Ja	governance_and_regression
Audit-Source-Roots und technische Pfadausnahmen	Eher nein bzw. nur Governance	governance.yaml / governance_and_regression.core_pattern_audit je nach bestehender Struktur

---

10. Minimalbeispiel: neues Zubehör-Synonym ergänzen

Ziel: Nutzer sagen künftig auch „Chemiesatz“ für Reagenz-/Indikator-Zubehör.

Prüfen, ob es Rolle, Canonical Term oder Evidence-Synonym ist:

• Als Zubehörrolle relevant: ja.
• Als Suchnormalisierung relevant: eventuell.
• Als Evidence-Synonym relevant: nur wenn fachlich gleichwertig belegt.

Mögliche Änderung:

configuration_values:
  product_roles:
    accessory_product_terms:
      terms:
        - indikator
        - reagenz
        - chemiesatz

Optional zusätzlich:

configuration_values:
  brands_and_canonical_terms:
    canonical_terms:
      map:
        chemiesatz: reagenz

Danach testen:

• „welcher chemiesatz passt zu ...“
• „suche chemiesatz im shop“
• Negativtest: Gerät darf dadurch nicht als Zubehör klassifiziert werden.

---

11. Minimalbeispiel: neues kurzes Attribut schützen

Ziel: Im neuen Genre ist M8 ein wichtiger Anschluss-/Gewindetyp und darf nicht aus Shop-Queries verschwinden.

Mögliche Änderung:

configuration_values:
  retrieval_and_language:
    protected_terms:
      terms:
        - m8
  shop_query_runtime:
    current_input_preservation_terms:
      terms:
        - m8

Danach testen:

• „zeige mir kabel m8 länger 5m“
• „suche im shop nach m8“
• „was kostet das m8 kabel“ nach vorherigem Kontext

---

12. Kurzfazit

genre.yaml ist die fachliche Source of Truth für eine Single-Genre-RetrieX-Installation.

Bei Anpassungen gilt:

1. Fachwerte in configuration_values ändern.
2. adaptation_surface nur als Inventar pflegen.
3. source_paths als Audit-Verknüpfung erhalten.
4. Legacy-YAMLs nicht wieder mit Fachwerten füllen.
5. Nach jeder Änderung Validate, Regression und Audits ausführen.
6. Bei Genre-Umwidmung alte Fachbegriffe bewusst entfernen, nicht nur neue ergänzen.