From 5237bb0c6320283005041c760ac894b12e4a99b1 Mon Sep 17 00:00:00 2001 From: team 1 Date: Thu, 7 May 2026 14:23:33 +0200 Subject: [PATCH] howto config genre --- genre_yaml_konfigurationsanleitung.md | 774 ++++++++++++++++++++++++++ 1 file changed, 774 insertions(+) create mode 100644 genre_yaml_konfigurationsanleitung.md diff --git a/genre_yaml_konfigurationsanleitung.md b/genre_yaml_konfigurationsanleitung.md new file mode 100644 index 0000000..b207fae --- /dev/null +++ b/genre_yaml_konfigurationsanleitung.md @@ -0,0 +1,774 @@ +# 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.