# 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: ```yaml 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: ```yaml 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: ```yaml primary_product_terms: terms: - messgerät - analysegerät - testomat accessory_product_terms: terms: - indikator - reagenz - zubehör ``` Beispiel Umwidmung Fashion: ```yaml 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: ```yaml canonical_terms: map: reagenzien: reagenz indicators: indikator ``` Für Fashion: ```yaml 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: ```yaml query_template_with_model: '{model} indikator' query_template_without_model: 'indikator' ``` Für Ersatzteile könnte es z. B. werden: ```yaml 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: ```yaml 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: ```yaml 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: ```bash 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: ```bash 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: ```yaml configuration_values: product_roles: accessory_product_terms: terms: - indikator - reagenz - chemiesatz ``` Optional zusätzlich: ```yaml 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: ```yaml 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.