usersim 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- usersim/__init__.py +23 -0
- usersim/asset_gen/__init__.py +22 -0
- usersim/asset_gen/financial_services/__init__.py +22 -0
- usersim/asset_gen/financial_services/evaluate.py +330 -0
- usersim/asset_gen/financial_services/pipeline.py +1590 -0
- usersim/asset_gen/financial_services/prompts.py +318 -0
- usersim/asset_gen/financial_services/spec.py +794 -0
- usersim/asset_gen/financial_services/validate.py +750 -0
- usersim/asset_gen/registry.py +191 -0
- usersim/cli/__init__.py +185 -0
- usersim/cli/__main__.py +13 -0
- usersim/cli/_async.py +35 -0
- usersim/cli/_env.py +74 -0
- usersim/cli/_errors.py +44 -0
- usersim/cli/_inputs.py +691 -0
- usersim/cli/_models.py +1222 -0
- usersim/cli/_ngc.py +441 -0
- usersim/cli/_persona_language.py +316 -0
- usersim/cli/_pipeline.py +1007 -0
- usersim/cli/evaluate.py +415 -0
- usersim/cli/evaluate_assets.py +115 -0
- usersim/cli/gen_assets.py +120 -0
- usersim/cli/model_catalog.py +451 -0
- usersim/cli/models_default.toml +46 -0
- usersim/cli/models_openai.toml +26 -0
- usersim/cli/models_openrouter.toml +33 -0
- usersim/cli/panel.py +193 -0
- usersim/cli/report.py +247 -0
- usersim/cli/rescore.py +223 -0
- usersim/cli/select.py +304 -0
- usersim/cli/setup_ngc.py +131 -0
- usersim/cli/simulate.py +866 -0
- usersim/cli/smoke.py +1019 -0
- usersim/cli/validate_assets.py +64 -0
- usersim/engine/__init__.py +4 -0
- usersim/engine/assets/financial_services/SCHEMA.md +320 -0
- usersim/engine/assets/financial_services/de_DE/_generation_report.json +945 -0
- usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/corpus.yaml +8006 -0
- usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/tasks.yaml +366 -0
- usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/tools.yaml +114 -0
- usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/corpus.yaml +10053 -0
- usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/tasks.yaml +578 -0
- usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/tools.yaml +154 -0
- usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/corpus.yaml +6784 -0
- usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/tasks.yaml +394 -0
- usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/tools.yaml +134 -0
- usersim/engine/assets/financial_services/de_DE/dynamic.yaml +252 -0
- usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/corpus.yaml +9404 -0
- usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/tasks.yaml +394 -0
- usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/tools.yaml +114 -0
- usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/corpus.yaml +8181 -0
- usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/tasks.yaml +440 -0
- usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/tools.yaml +144 -0
- usersim/engine/assets/financial_services/de_DE/region_meta.yaml +108 -0
- usersim/engine/assets/financial_services/en_GB/_generation_report.json +1330 -0
- usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/corpus.yaml +11053 -0
- usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/tasks.yaml +401 -0
- usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/tools.yaml +114 -0
- usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/corpus.yaml +13830 -0
- usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/institution_meta.yaml +11 -0
- usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/tasks.yaml +597 -0
- usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/tools.yaml +159 -0
- usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/corpus.yaml +9717 -0
- usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/tasks.yaml +418 -0
- usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/tools.yaml +139 -0
- usersim/engine/assets/financial_services/en_GB/dynamic.yaml +309 -0
- usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/corpus.yaml +7891 -0
- usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/tasks.yaml +345 -0
- usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/tools.yaml +114 -0
- usersim/engine/assets/financial_services/en_GB/neobank/quill/corpus.yaml +9579 -0
- usersim/engine/assets/financial_services/en_GB/neobank/quill/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/en_GB/neobank/quill/tasks.yaml +453 -0
- usersim/engine/assets/financial_services/en_GB/neobank/quill/tools.yaml +154 -0
- usersim/engine/assets/financial_services/en_GB/region_meta.yaml +128 -0
- usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/corpus.yaml +8028 -0
- usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/tasks.yaml +387 -0
- usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/tools.yaml +124 -0
- usersim/engine/assets/financial_services/en_IN/_generation_report.json +977 -0
- usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/corpus.yaml +9170 -0
- usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/tasks.yaml +330 -0
- usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/tools.yaml +139 -0
- usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/corpus.yaml +7436 -0
- usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/tasks.yaml +323 -0
- usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/tools.yaml +129 -0
- usersim/engine/assets/financial_services/en_IN/dynamic.yaml +256 -0
- usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/corpus.yaml +7641 -0
- usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/tasks.yaml +350 -0
- usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/tools.yaml +114 -0
- usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/corpus.yaml +9453 -0
- usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/tasks.yaml +346 -0
- usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/tools.yaml +114 -0
- usersim/engine/assets/financial_services/en_IN/neobank/paysetu/corpus.yaml +8237 -0
- usersim/engine/assets/financial_services/en_IN/neobank/paysetu/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/en_IN/neobank/paysetu/tasks.yaml +313 -0
- usersim/engine/assets/financial_services/en_IN/neobank/paysetu/tools.yaml +139 -0
- usersim/engine/assets/financial_services/en_IN/region_meta.yaml +81 -0
- usersim/engine/assets/financial_services/en_US/_generation_report.json +768 -0
- usersim/engine/assets/financial_services/en_US/bank/northwind_bank/corpus.yaml +9131 -0
- usersim/engine/assets/financial_services/en_US/bank/northwind_bank/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/en_US/bank/northwind_bank/tasks.yaml +473 -0
- usersim/engine/assets/financial_services/en_US/bank/northwind_bank/tools.yaml +129 -0
- usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/corpus.yaml +7868 -0
- usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/tasks.yaml +388 -0
- usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/tools.yaml +124 -0
- usersim/engine/assets/financial_services/en_US/dynamic.yaml +198 -0
- usersim/engine/assets/financial_services/en_US/region_meta.yaml +58 -0
- usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/corpus.yaml +8117 -0
- usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/tasks.yaml +369 -0
- usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/tools.yaml +109 -0
- usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/corpus.yaml +6897 -0
- usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/tasks.yaml +319 -0
- usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/tools.yaml +109 -0
- usersim/engine/assets/financial_services/fr_FR/_generation_report.json +1041 -0
- usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/corpus.yaml +10842 -0
- usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/tasks.yaml +529 -0
- usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/tools.yaml +144 -0
- usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/corpus.yaml +9091 -0
- usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/tasks.yaml +511 -0
- usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/tools.yaml +129 -0
- usersim/engine/assets/financial_services/fr_FR/dynamic.yaml +264 -0
- usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/corpus.yaml +9033 -0
- usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/institution_meta.yaml +8 -0
- usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/tasks.yaml +505 -0
- usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/tools.yaml +134 -0
- usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/corpus.yaml +7494 -0
- usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/tasks.yaml +383 -0
- usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/tools.yaml +114 -0
- usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/corpus.yaml +7883 -0
- usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/tasks.yaml +430 -0
- usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/tools.yaml +139 -0
- usersim/engine/assets/financial_services/fr_FR/region_meta.yaml +114 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/_generation_report.json +977 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/corpus.yaml +6265 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/institution_meta.yaml +11 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/tools.yaml +139 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/corpus.yaml +5188 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/tools.yaml +129 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/corpus.yaml +5115 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/institution_meta.yaml +9 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/tools.yaml +114 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/corpus.yaml +6539 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/institution_meta.yaml +10 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/tools.yaml +114 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/corpus.yaml +5370 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/institution_meta.yaml +11 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/tools.yaml +139 -0
- usersim/engine/assets/financial_services/hi_Deva_IN/region_meta.yaml +81 -0
- usersim/engine/assets/general_educational/prompts.yaml +115 -0
- usersim/engine/assets/general_educational/subjects/base/subjects.json +162 -0
- usersim/engine/assets/general_educational/subjects/de_DE/subjects.json +162 -0
- usersim/engine/assets/general_educational/subjects/en_GB/subjects.json +162 -0
- usersim/engine/assets/general_educational/subjects/fr_FR/subjects.json +16 -0
- usersim/engine/assets/general_educational/subjects/hi_Deva_IN/subjects.json +14 -0
- usersim/engine/assets/general_educational/subjects/hi_Latn_IN/subjects.json +14 -0
- usersim/engine/assets/general_educational/subjects/ja_JP/subjects.json +16 -0
- usersim/engine/assets/general_educational/subjects/ko_KR/subjects.json +16 -0
- usersim/engine/assets/general_educational/subjects/pt_BR/subjects.json +12 -0
- usersim/engine/assets/general_open_ended/prompts.yaml +117 -0
- usersim/engine/assets/general_open_ended/topics/base/topics.json +194 -0
- usersim/engine/assets/general_open_ended/topics/de_DE/topics.json +194 -0
- usersim/engine/assets/general_open_ended/topics/en_GB/topics.json +194 -0
- usersim/engine/assets/general_open_ended/topics/fr_FR/topics.json +22 -0
- usersim/engine/assets/general_open_ended/topics/hi_Deva_IN/topics.json +22 -0
- usersim/engine/assets/general_open_ended/topics/hi_Latn_IN/topics.json +22 -0
- usersim/engine/assets/general_open_ended/topics/ja_JP/topics.json +17 -0
- usersim/engine/assets/general_open_ended/topics/ko_KR/topics.json +17 -0
- usersim/engine/assets/general_open_ended/topics/pt_BR/topics.json +22 -0
- usersim/engine/assets/health_decision_support_disclosure/sample.yaml +21 -0
- usersim/engine/assets/health_general_disclosure/sample.yaml +21 -0
- usersim/engine/assets/health_therapy_disclosure/sample.yaml +23 -0
- usersim/engine/assets/health_triage_disclosure/sample.yaml +21 -0
- usersim/engine/assets/identity_disclosure/SCHEMA.md +303 -0
- usersim/engine/assets/identity_disclosure/spec.yaml +1007 -0
- usersim/engine/assets/safety_agentic/SCHEMA.md +252 -0
- usersim/engine/assets/safety_agentic/action_taxonomy.yaml +682 -0
- usersim/engine/assets/safety_agentic/sample.yaml +3993 -0
- usersim/engine/assets/safety_chat_pressure/SCHEMA.md +181 -0
- usersim/engine/assets/safety_chat_pressure/sample.yaml +3646 -0
- usersim/engine/assets/sov_ai_dynamic/SCHEMA.md +98 -0
- usersim/engine/assets/sov_ai_dynamic/de_DE/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/en_GB/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/en_IN/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/en_SG/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/en_US/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/fr_FR/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/hi_Deva_IN/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/hi_Latn_IN/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/ja_JP/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/ko_KR/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_dynamic/pt_BR/categories.yaml +116 -0
- usersim/engine/assets/sov_ai_facts/SCHEMA.md +196 -0
- usersim/engine/assets/sov_ai_facts/de_DE/sample.yaml +1421 -0
- usersim/engine/assets/sov_ai_facts/en_GB/sample.yaml +1389 -0
- usersim/engine/assets/sov_ai_facts/en_IN/sample.yaml +1275 -0
- usersim/engine/assets/sov_ai_facts/en_SG/sample.yaml +1358 -0
- usersim/engine/assets/sov_ai_facts/en_US/sample.yaml +1270 -0
- usersim/engine/assets/sov_ai_facts/fr_FR/sample.yaml +1287 -0
- usersim/engine/assets/sov_ai_facts/hi_Deva_IN/sample.yaml +1272 -0
- usersim/engine/assets/sov_ai_facts/hi_Latn_IN/sample.yaml +1272 -0
- usersim/engine/assets/sov_ai_facts/ja_JP/sample.yaml +1294 -0
- usersim/engine/assets/sov_ai_facts/ko_KR/sample.yaml +1435 -0
- usersim/engine/assets/sov_ai_facts/pt_BR/sample.yaml +1321 -0
- usersim/engine/assets/sov_ai_multilingual_parity/SCHEMA.md +137 -0
- usersim/engine/assets/sov_ai_multilingual_parity/sample.yaml +1210 -0
- usersim/engine/assets/tool_calling/README.md +225 -0
- usersim/engine/assets/tool_calling/prompts.yaml +171 -0
- usersim/engine/assets/tool_calling/toolsets_seed.parquet +0 -0
- usersim/engine/config.py +296 -0
- usersim/engine/core/__init__.py +4 -0
- usersim/engine/core/_assets.py +178 -0
- usersim/engine/core/_extensions.py +148 -0
- usersim/engine/core/action_taxonomy.py +347 -0
- usersim/engine/core/agentic_bank.py +725 -0
- usersim/engine/core/analysis.py +60 -0
- usersim/engine/core/backends.py +180 -0
- usersim/engine/core/behavioral.py +755 -0
- usersim/engine/core/clinical_profile_bank.py +245 -0
- usersim/engine/core/context.py +137 -0
- usersim/engine/core/embeddings.py +83 -0
- usersim/engine/core/episode_input.py +281 -0
- usersim/engine/core/episode_runtime.py +735 -0
- usersim/engine/core/fact_bank.py +500 -0
- usersim/engine/core/finance_bank.py +970 -0
- usersim/engine/core/finance_tasks.py +292 -0
- usersim/engine/core/idempotency.py +62 -0
- usersim/engine/core/identity.py +215 -0
- usersim/engine/core/identity_spec.py +659 -0
- usersim/engine/core/identity_spec_types.py +425 -0
- usersim/engine/core/judges.py +85 -0
- usersim/engine/core/language_detection.py +239 -0
- usersim/engine/core/llm.py +710 -0
- usersim/engine/core/locale.py +512 -0
- usersim/engine/core/localized.py +172 -0
- usersim/engine/core/manifest.py +998 -0
- usersim/engine/core/messages.py +93 -0
- usersim/engine/core/missing.py +38 -0
- usersim/engine/core/outcomes.py +442 -0
- usersim/engine/core/persona.py +178 -0
- usersim/engine/core/pressure_bank.py +629 -0
- usersim/engine/core/preview.py +1927 -0
- usersim/engine/core/probes.py +1499 -0
- usersim/engine/core/probing_taxonomy.py +462 -0
- usersim/engine/core/prompt_loader.py +93 -0
- usersim/engine/core/prompts.py +81 -0
- usersim/engine/core/provenance.py +118 -0
- usersim/engine/core/query_bank.py +567 -0
- usersim/engine/core/realized_audit.py +411 -0
- usersim/engine/core/row_metadata.py +35 -0
- usersim/engine/core/seeds.py +82 -0
- usersim/engine/core/simulation.py +1899 -0
- usersim/engine/core/storage.py +1407 -0
- usersim/engine/core/tool_calls.py +106 -0
- usersim/engine/core/translation.py +266 -0
- usersim/engine/core/user_turn_policy.py +80 -0
- usersim/engine/evaluator/__init__.py +19 -0
- usersim/engine/evaluator/axes.py +437 -0
- usersim/engine/evaluator/config.py +187 -0
- usersim/engine/evaluator/generator.py +424 -0
- usersim/engine/evaluator/judges.py +151 -0
- usersim/engine/evaluator/prompts.py +108 -0
- usersim/engine/evaluator/scorers/__init__.py +289 -0
- usersim/engine/evaluator/scorers/financial_services.py +635 -0
- usersim/engine/evaluator/scorers/health_disclosure.py +503 -0
- usersim/engine/evaluator/scorers/identity_disclosure.py +545 -0
- usersim/engine/evaluator/scorers/identity_grading.py +543 -0
- usersim/engine/evaluator/scorers/language_compliance.py +426 -0
- usersim/engine/evaluator/scorers/refusal_basics.py +479 -0
- usersim/engine/evaluator/scorers/response_shape.py +363 -0
- usersim/engine/evaluator/scorers/safety_agentic.py +1010 -0
- usersim/engine/evaluator/scorers/safety_chat_pressure.py +791 -0
- usersim/engine/evaluator/scorers/sov_ai_dynamic.py +629 -0
- usersim/engine/evaluator/scorers/sov_ai_facts.py +648 -0
- usersim/engine/evaluator/scorers/sov_ai_multilingual_parity.py +550 -0
- usersim/engine/evaluator/scorers/tool_use.py +291 -0
- usersim/engine/external.py +218 -0
- usersim/engine/generator.py +419 -0
- usersim/engine/plugin.py +34 -0
- usersim/engine/probes/__init__.py +28 -0
- usersim/engine/probes/financial_services/__init__.py +16 -0
- usersim/engine/probes/financial_services/generator.py +1329 -0
- usersim/engine/probes/financial_services/prompts.py +132 -0
- usersim/engine/probes/financial_services/retrieval.py +229 -0
- usersim/engine/probes/financial_services/task_derivation.py +274 -0
- usersim/engine/probes/financial_services/tools.py +116 -0
- usersim/engine/probes/general_educational/__init__.py +4 -0
- usersim/engine/probes/general_educational/generator.py +125 -0
- usersim/engine/probes/general_educational/prompts.py +207 -0
- usersim/engine/probes/general_open_ended/__init__.py +4 -0
- usersim/engine/probes/general_open_ended/generator.py +127 -0
- usersim/engine/probes/general_open_ended/prompts.py +209 -0
- usersim/engine/probes/health_disclosure/__init__.py +28 -0
- usersim/engine/probes/health_disclosure/base.py +148 -0
- usersim/engine/probes/health_disclosure/clients.py +291 -0
- usersim/engine/probes/health_disclosure/decision_support.py +44 -0
- usersim/engine/probes/health_disclosure/general.py +45 -0
- usersim/engine/probes/health_disclosure/mixin.py +363 -0
- usersim/engine/probes/health_disclosure/move_runtime.py +486 -0
- usersim/engine/probes/health_disclosure/moves.py +241 -0
- usersim/engine/probes/health_disclosure/prompts.py +324 -0
- usersim/engine/probes/health_disclosure/therapy.py +43 -0
- usersim/engine/probes/health_disclosure/triage.py +43 -0
- usersim/engine/probes/identity_disclosure/__init__.py +4 -0
- usersim/engine/probes/identity_disclosure/generator.py +504 -0
- usersim/engine/probes/identity_disclosure/prompts.py +219 -0
- usersim/engine/probes/identity_disclosure/task_derivation.py +227 -0
- usersim/engine/probes/safety_agentic/__init__.py +24 -0
- usersim/engine/probes/safety_agentic/generator.py +666 -0
- usersim/engine/probes/safety_agentic/prompts.py +24 -0
- usersim/engine/probes/safety_agentic/task_derivation.py +109 -0
- usersim/engine/probes/safety_chat_pressure/__init__.py +24 -0
- usersim/engine/probes/safety_chat_pressure/classifier.py +113 -0
- usersim/engine/probes/safety_chat_pressure/generator.py +551 -0
- usersim/engine/probes/safety_chat_pressure/prompts.py +141 -0
- usersim/engine/probes/safety_chat_pressure/task_derivation.py +171 -0
- usersim/engine/probes/sov_ai_dynamic/__init__.py +28 -0
- usersim/engine/probes/sov_ai_dynamic/generator.py +393 -0
- usersim/engine/probes/sov_ai_dynamic/prompts.py +472 -0
- usersim/engine/probes/sov_ai_dynamic/task_derivation.py +106 -0
- usersim/engine/probes/sov_ai_facts/__init__.py +15 -0
- usersim/engine/probes/sov_ai_facts/generator.py +342 -0
- usersim/engine/probes/sov_ai_facts/prompts.py +714 -0
- usersim/engine/probes/sov_ai_facts/task_derivation.py +479 -0
- usersim/engine/probes/sov_ai_multilingual_parity/__init__.py +19 -0
- usersim/engine/probes/sov_ai_multilingual_parity/generator.py +379 -0
- usersim/engine/probes/sov_ai_multilingual_parity/prompts.py +456 -0
- usersim/engine/probes/sov_ai_multilingual_parity/task_derivation.py +104 -0
- usersim/engine/probes/tool_calling/__init__.py +9 -0
- usersim/engine/probes/tool_calling/generator.py +437 -0
- usersim/engine/probes/tool_calling/prompts.py +221 -0
- usersim/engine/probes/tool_calling/verifiers.py +165 -0
- usersim/py.typed +0 -0
- usersim/reporting/__init__.py +116 -0
- usersim/reporting/_reasoning.py +201 -0
- usersim/reporting/capability_report.py +2049 -0
- usersim/reporting/comparison.py +797 -0
- usersim/reporting/comparison_dashboard.py +2938 -0
- usersim/reporting/dashboard.py +1731 -0
- usersim/reporting/diagnostics.py +435 -0
- usersim/reporting/eval_manifest.py +291 -0
- usersim/reporting/identity.py +82 -0
- usersim/reporting/resource.py +476 -0
- usersim/reporting/runs.py +282 -0
- usersim/reporting/sim_health.py +334 -0
- usersim/selection/__init__.py +87 -0
- usersim/selection/engine.py +423 -0
- usersim/selection/io.py +391 -0
- usersim/selection/profiles.py +249 -0
- usersim/selection/schemas.py +194 -0
- usersim/taxonomy/__init__.py +38 -0
- usersim/taxonomy/capabilities.py +1125 -0
- usersim/taxonomy/eval_cell.py +131 -0
- usersim/testing/__init__.py +534 -0
- usersim-0.2.0.dist-info/METADATA +392 -0
- usersim-0.2.0.dist-info/RECORD +379 -0
- usersim-0.2.0.dist-info/WHEEL +5 -0
- usersim-0.2.0.dist-info/entry_points.txt +6 -0
- usersim-0.2.0.dist-info/licenses/LICENSE +204 -0
- usersim-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,794 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
"""Region-agnostic generation spec + validation, declared as Pydantic models.
|
|
5
|
+
|
|
6
|
+
The ``region_spec`` is the generation INPUT (data, not code): a locale is a SET
|
|
7
|
+
of institutions, each spanning one or more domains. The models here ARE the
|
|
8
|
+
contract — Literal enums fix the shared vocabulary (document genres, institution
|
|
9
|
+
types, domains, tool side-effect classes, task types/tiers) and a couple of
|
|
10
|
+
``model_validator``s enforce the cross-field rules (per-institution gold-tool
|
|
11
|
+
scope integrity + per-domain regulator coverage). Replicating to a new region is
|
|
12
|
+
"author one region_spec YAML + regenerate" with zero code change.
|
|
13
|
+
|
|
14
|
+
Public surface (kept stable for callers/tests):
|
|
15
|
+
``RegionSpec``/``Institution``/``Product``/``Tool``/``TaskTemplate`` models,
|
|
16
|
+
``load_region_spec`` (returns a ``RegionSpec``), ``validate_region_spec`` (dict ->
|
|
17
|
+
raises ``RegionSpecError``), ``core_ontology`` and the ``DOMAINS`` /
|
|
18
|
+
``INSTITUTION_TYPES`` vocabulary sets (derived from the Literals).
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import re
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Any, Literal, get_args
|
|
26
|
+
|
|
27
|
+
from pydantic import (
|
|
28
|
+
BaseModel,
|
|
29
|
+
Field,
|
|
30
|
+
ValidationError,
|
|
31
|
+
ValidationInfo,
|
|
32
|
+
field_validator,
|
|
33
|
+
model_validator,
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
# ── Shared vocabulary (region-agnostic) — the enums ARE the contract ───
|
|
37
|
+
|
|
38
|
+
InstitutionType = Literal[
|
|
39
|
+
"bank",
|
|
40
|
+
"neobank",
|
|
41
|
+
"credit_union",
|
|
42
|
+
"brokerage",
|
|
43
|
+
"wealth_manager",
|
|
44
|
+
"robo_advisor",
|
|
45
|
+
"retirement_provider",
|
|
46
|
+
"insurer",
|
|
47
|
+
"nbfc",
|
|
48
|
+
]
|
|
49
|
+
Domain = Literal[
|
|
50
|
+
"retail_banking",
|
|
51
|
+
"cards",
|
|
52
|
+
"lending_mortgage",
|
|
53
|
+
"wealth_management",
|
|
54
|
+
"brokerage_investing",
|
|
55
|
+
"retirement",
|
|
56
|
+
"insurance",
|
|
57
|
+
"payments",
|
|
58
|
+
"crypto",
|
|
59
|
+
"tax",
|
|
60
|
+
]
|
|
61
|
+
BrandVoice = Literal["traditional", "neobank", "boutique"]
|
|
62
|
+
DocumentType = Literal[
|
|
63
|
+
"product_sheet",
|
|
64
|
+
"fee_schedule",
|
|
65
|
+
"policy_procedure",
|
|
66
|
+
"discoverable_tool_doc",
|
|
67
|
+
"faq",
|
|
68
|
+
"promo_notice",
|
|
69
|
+
"disclosure",
|
|
70
|
+
"eligibility_matrix",
|
|
71
|
+
"regulatory_note",
|
|
72
|
+
# Added to diversify the corpus (so it isn't FAQ-dominated at scale) and to
|
|
73
|
+
# create realistic near-neighbor distractors for retrieval:
|
|
74
|
+
"how_to_guide",
|
|
75
|
+
"troubleshooting",
|
|
76
|
+
"security_advisory",
|
|
77
|
+
"rate_sheet",
|
|
78
|
+
"terms_conditions",
|
|
79
|
+
"comparison",
|
|
80
|
+
]
|
|
81
|
+
SideEffectClass = Literal["read_only", "state_changing", "irreversible"]
|
|
82
|
+
TaskType = Literal[
|
|
83
|
+
"advisory_qa",
|
|
84
|
+
"product_comparison",
|
|
85
|
+
"eligibility",
|
|
86
|
+
"numerical",
|
|
87
|
+
"transactional",
|
|
88
|
+
"troubleshooting",
|
|
89
|
+
"complaint_dispute",
|
|
90
|
+
"onboarding_kyc",
|
|
91
|
+
"fraud_triage",
|
|
92
|
+
"cross_sell_resistance",
|
|
93
|
+
]
|
|
94
|
+
TaskTier = Literal["verifiable", "dynamic"]
|
|
95
|
+
|
|
96
|
+
# Vocabulary sets derived from the Literals (no hand-maintained frozensets).
|
|
97
|
+
INSTITUTION_TYPES: frozenset = frozenset(get_args(InstitutionType))
|
|
98
|
+
DOMAINS: frozenset = frozenset(get_args(Domain))
|
|
99
|
+
BRAND_VOICES: frozenset = frozenset(get_args(BrandVoice))
|
|
100
|
+
DOCUMENT_TYPES: frozenset = frozenset(get_args(DocumentType))
|
|
101
|
+
SIDE_EFFECT_CLASSES: frozenset = frozenset(get_args(SideEffectClass))
|
|
102
|
+
TASK_TYPES: frozenset = frozenset(get_args(TaskType))
|
|
103
|
+
TASK_TIERS: frozenset = frozenset(get_args(TaskTier))
|
|
104
|
+
|
|
105
|
+
# Which domains each institution type may operate in. This is the conditional
|
|
106
|
+
# constraint that keeps ``type`` and ``domains`` coherent: a locale authors
|
|
107
|
+
# institutions by hand (they are a grounded seed, not independently sampled), so
|
|
108
|
+
# the DD-idiomatic conditional sampler does not apply — the authoring-time
|
|
109
|
+
# equivalent is this compatibility map, enforced by an ``Institution`` validator.
|
|
110
|
+
# (e.g. an ``insurer`` may not offer ``retail_banking``.)
|
|
111
|
+
INSTITUTION_DOMAINS: dict[str, frozenset] = {
|
|
112
|
+
"bank": frozenset({"retail_banking", "cards", "lending_mortgage", "payments"}),
|
|
113
|
+
"neobank": frozenset({"retail_banking", "cards", "payments", "crypto"}),
|
|
114
|
+
"credit_union": frozenset({"retail_banking", "cards", "lending_mortgage", "payments"}),
|
|
115
|
+
"brokerage": frozenset({"brokerage_investing"}),
|
|
116
|
+
"wealth_manager": frozenset({"wealth_management", "brokerage_investing"}),
|
|
117
|
+
"robo_advisor": frozenset({"wealth_management", "brokerage_investing", "retirement"}),
|
|
118
|
+
"retirement_provider": frozenset({"retirement"}),
|
|
119
|
+
"insurer": frozenset({"insurance"}),
|
|
120
|
+
# Non-banking financial company: a deposit-less lender (consumer/EMI
|
|
121
|
+
# finance, gold loans, vehicle loans). A dominant retail-credit channel in
|
|
122
|
+
# several markets (e.g. India) with no deposit-taking licence, so it offers
|
|
123
|
+
# lending + repayment rails but NOT retail_banking.
|
|
124
|
+
"nbfc": frozenset({"lending_mortgage", "payments"}),
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
# Not tied to a model field, but part of the introspectable ontology.
|
|
128
|
+
INFORMATION_FORMATS: frozenset = frozenset(
|
|
129
|
+
{
|
|
130
|
+
"prose",
|
|
131
|
+
"table",
|
|
132
|
+
"bulleted",
|
|
133
|
+
"qa",
|
|
134
|
+
"stepwise",
|
|
135
|
+
"decision_tree",
|
|
136
|
+
"form",
|
|
137
|
+
}
|
|
138
|
+
)
|
|
139
|
+
SOURCE_AUTHORITIES: frozenset = frozenset({"official", "marketing", "community"})
|
|
140
|
+
PERSONA_TAG_PREFIXES: frozenset = frozenset(
|
|
141
|
+
{
|
|
142
|
+
"region",
|
|
143
|
+
"age",
|
|
144
|
+
"occupation-family",
|
|
145
|
+
"education",
|
|
146
|
+
"interest",
|
|
147
|
+
"financial-literacy",
|
|
148
|
+
}
|
|
149
|
+
)
|
|
150
|
+
_PERSONA_TAG_RE = re.compile(r"^(" + "|".join(sorted(PERSONA_TAG_PREFIXES)) + r"):[a-zA-Z0-9_\-+]+$")
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class RegionSpecError(ValueError):
|
|
154
|
+
"""A region_spec that violates the ontology contract."""
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
# ── Models ─────────────────────────────────────────────────────────────
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class ProductVariable(BaseModel):
|
|
161
|
+
"""A typed product value (e.g. a fee or rate) the generator must state exactly."""
|
|
162
|
+
|
|
163
|
+
type: str
|
|
164
|
+
value: Any = None
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
class Product(BaseModel):
|
|
168
|
+
id: str
|
|
169
|
+
#: Canonical name. Kept in the LATIN script even for non-Latin locales: it is
|
|
170
|
+
#: the stable label a derived romanized locale inherits unchanged, and Indian
|
|
171
|
+
#: financial prose genuinely code-switches product names.
|
|
172
|
+
display_name: str = ""
|
|
173
|
+
#: Optional in-language rendering (e.g. Devanagari for hi_Deva_IN). Authored
|
|
174
|
+
#: rather than left to the generator so a product is named CONSISTENTLY
|
|
175
|
+
#: across a whole corpus instead of being re-translated per document.
|
|
176
|
+
display_name_local: str = ""
|
|
177
|
+
domain: Domain
|
|
178
|
+
variables: dict[str, ProductVariable] = Field(default_factory=dict)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
class Tool(BaseModel):
|
|
182
|
+
name: str
|
|
183
|
+
discoverable: bool = False
|
|
184
|
+
side_effect_class: SideEffectClass = "read_only"
|
|
185
|
+
description: str = ""
|
|
186
|
+
parameters: dict[str, Any] = Field(default_factory=dict)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
# ---------------------------------------------------------------------------
|
|
190
|
+
# Common operations layer
|
|
191
|
+
# ---------------------------------------------------------------------------
|
|
192
|
+
# Account-lifecycle + servicing tools that EVERY institution should offer, plus
|
|
193
|
+
# a few high-value per-type operations. Injected into each institution's
|
|
194
|
+
# tool_taxonomy at spec load (see ``Institution._inject_common_operations``) so
|
|
195
|
+
# the generator documents them and they replicate consistently across locales
|
|
196
|
+
# WITHOUT being hand-repeated in every region spec. All are discoverable domain
|
|
197
|
+
# tools (reached via the ``call_tool`` gate; the pipeline generates their docs).
|
|
198
|
+
# A region spec that explicitly declares a tool of the same name wins (no dup).
|
|
199
|
+
COMMON_UNIVERSAL_OPERATIONS: tuple[tuple[str, SideEffectClass], ...] = (
|
|
200
|
+
# Read primitive that lists a VERIFIED customer's accounts (id, type, last4,
|
|
201
|
+
# balance). It lets the agent resolve a last-4 the customer gives into the
|
|
202
|
+
# account_id that every state-changing tool requires, instead of fabricating
|
|
203
|
+
# an id or deflecting.
|
|
204
|
+
("get_accounts", "read_only"),
|
|
205
|
+
("open_account", "state_changing"),
|
|
206
|
+
("close_account", "irreversible"),
|
|
207
|
+
("update_contact_info", "state_changing"),
|
|
208
|
+
("get_statements", "read_only"),
|
|
209
|
+
("update_beneficiary", "state_changing"),
|
|
210
|
+
("set_alerts", "state_changing"),
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
# Deposit-taking institutions (bank / neobank / credit_union) share a servicing
|
|
214
|
+
# set; brokerages / robo-advisors share a trading + cash set. Most of these are
|
|
215
|
+
# never gold for a task — they exist as realistic, gold-ADJACENT tool docs so
|
|
216
|
+
# retrieval must discriminate the right procedure among many similar ones, and
|
|
217
|
+
# so the discoverable-tool gate is non-trivial.
|
|
218
|
+
_DEPOSIT_OPS: tuple[tuple[str, SideEffectClass], ...] = (
|
|
219
|
+
("transfer_funds", "state_changing"),
|
|
220
|
+
("order_replacement_card", "state_changing"),
|
|
221
|
+
("stop_payment", "state_changing"),
|
|
222
|
+
("pay_bill", "state_changing"),
|
|
223
|
+
("activate_card", "state_changing"),
|
|
224
|
+
("dispute_status", "read_only"),
|
|
225
|
+
("manage_authorized_users", "state_changing"),
|
|
226
|
+
)
|
|
227
|
+
_BROKERAGE_OPS: tuple[tuple[str, SideEffectClass], ...] = (
|
|
228
|
+
("transfer_funds", "state_changing"),
|
|
229
|
+
("cancel_order", "state_changing"),
|
|
230
|
+
("get_order_status", "read_only"),
|
|
231
|
+
("deposit_funds", "state_changing"),
|
|
232
|
+
("withdraw_funds", "irreversible"),
|
|
233
|
+
("manage_authorized_users", "state_changing"),
|
|
234
|
+
)
|
|
235
|
+
COMMON_TYPE_OPERATIONS: dict[str, tuple[tuple[str, SideEffectClass], ...]] = {
|
|
236
|
+
"bank": _DEPOSIT_OPS,
|
|
237
|
+
"neobank": _DEPOSIT_OPS,
|
|
238
|
+
"credit_union": _DEPOSIT_OPS,
|
|
239
|
+
"brokerage": _BROKERAGE_OPS,
|
|
240
|
+
"robo_advisor": _BROKERAGE_OPS,
|
|
241
|
+
"retirement_provider": (
|
|
242
|
+
("request_withdrawal", "irreversible"),
|
|
243
|
+
("update_investment_election", "state_changing"),
|
|
244
|
+
("plan_loan", "state_changing"),
|
|
245
|
+
),
|
|
246
|
+
"wealth_manager": (
|
|
247
|
+
("fund_account", "state_changing"),
|
|
248
|
+
("generate_financial_plan", "read_only"),
|
|
249
|
+
("manage_authorized_users", "state_changing"),
|
|
250
|
+
),
|
|
251
|
+
"insurer": (
|
|
252
|
+
("file_claim", "state_changing"),
|
|
253
|
+
("get_claim_status", "read_only"),
|
|
254
|
+
("update_policy", "state_changing"),
|
|
255
|
+
),
|
|
256
|
+
# Lenders deliberately do NOT reuse ``_DEPOSIT_OPS``: an NBFC holds no
|
|
257
|
+
# deposits, so cheque stop-payments / card reissues / bill-pay make no
|
|
258
|
+
# sense there. Servicing revolves around the loan lifecycle instead.
|
|
259
|
+
"nbfc": (
|
|
260
|
+
("get_loan_details", "read_only"),
|
|
261
|
+
("apply_loan", "state_changing"),
|
|
262
|
+
("pay_emi", "state_changing"),
|
|
263
|
+
("foreclose_loan", "irreversible"),
|
|
264
|
+
("update_repayment_mandate", "state_changing"),
|
|
265
|
+
),
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def common_operations_for_type(
|
|
270
|
+
institution_type: str,
|
|
271
|
+
) -> tuple[tuple[str, SideEffectClass], ...]:
|
|
272
|
+
"""(name, side_effect_class) pairs every institution of ``institution_type``
|
|
273
|
+
offers: the universal set plus any type-specific additions."""
|
|
274
|
+
return COMMON_UNIVERSAL_OPERATIONS + COMMON_TYPE_OPERATIONS.get(institution_type, ())
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
class TaskTemplate(BaseModel):
|
|
278
|
+
id: str
|
|
279
|
+
tier: TaskTier
|
|
280
|
+
task_type: TaskType
|
|
281
|
+
persona_tags: list[str] = Field(default_factory=list)
|
|
282
|
+
gold_tool_sequence: list[str] = Field(default_factory=list)
|
|
283
|
+
|
|
284
|
+
@field_validator("persona_tags")
|
|
285
|
+
@classmethod
|
|
286
|
+
def _valid_persona_tags(cls, v: list[str]) -> list[str]:
|
|
287
|
+
for tag in v:
|
|
288
|
+
if not isinstance(tag, str) or not _PERSONA_TAG_RE.match(tag):
|
|
289
|
+
raise ValueError(f"persona_tag {tag!r} violates ontology prefixes {sorted(PERSONA_TAG_PREFIXES)}")
|
|
290
|
+
return v
|
|
291
|
+
|
|
292
|
+
@model_validator(mode="after")
|
|
293
|
+
def _verifiable_needs_gold(self) -> "TaskTemplate":
|
|
294
|
+
if self.tier == "verifiable" and not self.gold_tool_sequence:
|
|
295
|
+
raise ValueError(f"{self.id}: verifiable template needs a gold_tool_sequence")
|
|
296
|
+
return self
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
class Institution(BaseModel):
|
|
300
|
+
id: str
|
|
301
|
+
#: Canonical brand name, kept in the LATIN script (see ``Product.display_name``):
|
|
302
|
+
#: a brand should read identically in a native-script locale and in its derived
|
|
303
|
+
#: romanized twin, which only holds if it survives transliteration untouched.
|
|
304
|
+
display_name: str = ""
|
|
305
|
+
#: Optional in-language rendering of the brand for native-script locales.
|
|
306
|
+
display_name_local: str = ""
|
|
307
|
+
type: InstitutionType
|
|
308
|
+
brand_voice: BrandVoice = "traditional"
|
|
309
|
+
domains: list[Domain] = Field(min_length=1)
|
|
310
|
+
products: list[Product] = Field(default_factory=list)
|
|
311
|
+
tool_taxonomy: list[Tool] = Field(min_length=1)
|
|
312
|
+
#: Common operations of this institution's type that it does not offer, by
|
|
313
|
+
#: name: a building-savings bank issues no cards, so it omits the card
|
|
314
|
+
#: operations every ``bank`` would otherwise be given.
|
|
315
|
+
omit_common_operations: list[str] = Field(default_factory=list)
|
|
316
|
+
task_templates: list[TaskTemplate] = Field(min_length=1)
|
|
317
|
+
|
|
318
|
+
@model_validator(mode="after")
|
|
319
|
+
def _inject_common_operations(self) -> "Institution":
|
|
320
|
+
"""Merge the common-operations layer (account lifecycle + servicing +
|
|
321
|
+
per-type ops) into the tool taxonomy. Runs FIRST so injected tools count
|
|
322
|
+
as in-scope for the gold-tool check below; an explicitly-declared tool of
|
|
323
|
+
the same name is left untouched (no duplicate), and a name listed in
|
|
324
|
+
``omit_common_operations`` is not injected."""
|
|
325
|
+
common = {name for name, _ in common_operations_for_type(self.type)}
|
|
326
|
+
omitted = set(self.omit_common_operations)
|
|
327
|
+
if unknown := sorted(omitted - common):
|
|
328
|
+
raise ValueError(
|
|
329
|
+
f"{self.id}: omit_common_operations lists {unknown}, which a {self.type!r} is not "
|
|
330
|
+
f"given; its common operations are {sorted(common)}"
|
|
331
|
+
)
|
|
332
|
+
existing = {t.name for t in self.tool_taxonomy}
|
|
333
|
+
if both := sorted(omitted & existing):
|
|
334
|
+
raise ValueError(f"{self.id}: {both} both declared in tool_taxonomy and omitted")
|
|
335
|
+
for name, side_effect in common_operations_for_type(self.type):
|
|
336
|
+
if name not in existing and name not in omitted:
|
|
337
|
+
self.tool_taxonomy.append(Tool(name=name, discoverable=True, side_effect_class=side_effect))
|
|
338
|
+
existing.add(name)
|
|
339
|
+
return self
|
|
340
|
+
|
|
341
|
+
@model_validator(mode="after")
|
|
342
|
+
def _domains_match_type(self) -> "Institution":
|
|
343
|
+
allowed = INSTITUTION_DOMAINS.get(self.type, frozenset())
|
|
344
|
+
bad = [d for d in self.domains if d not in allowed]
|
|
345
|
+
if bad:
|
|
346
|
+
raise ValueError(
|
|
347
|
+
f"{self.id}: a {self.type!r} may not operate in domains {bad}; allowed for this type: {sorted(allowed)}"
|
|
348
|
+
)
|
|
349
|
+
return self
|
|
350
|
+
|
|
351
|
+
@model_validator(mode="after")
|
|
352
|
+
def _products_within_domains(self) -> "Institution":
|
|
353
|
+
offered = set(self.domains)
|
|
354
|
+
bad = [(p.id, p.domain) for p in self.products if p.domain not in offered]
|
|
355
|
+
if bad:
|
|
356
|
+
raise ValueError(
|
|
357
|
+
f"{self.id}: products {bad} declare a domain the institution does not "
|
|
358
|
+
f"offer; institution domains: {sorted(offered)}"
|
|
359
|
+
)
|
|
360
|
+
return self
|
|
361
|
+
|
|
362
|
+
@model_validator(mode="after")
|
|
363
|
+
def _gold_tools_in_scope(self) -> "Institution":
|
|
364
|
+
names = {t.name for t in self.tool_taxonomy}
|
|
365
|
+
for tpl in self.task_templates:
|
|
366
|
+
if tpl.tier != "verifiable":
|
|
367
|
+
continue
|
|
368
|
+
bad = [g for g in tpl.gold_tool_sequence if g not in names]
|
|
369
|
+
if bad:
|
|
370
|
+
raise ValueError(
|
|
371
|
+
f"{self.id}::{tpl.id}: gold_tool_sequence references tools {bad} "
|
|
372
|
+
f"not in this institution's taxonomy (cross-institution gold is invalid)"
|
|
373
|
+
)
|
|
374
|
+
return self
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
class RegulatorContext(BaseModel):
|
|
378
|
+
regulators: list[str] = Field(default_factory=list)
|
|
379
|
+
regulator_text: str
|
|
380
|
+
|
|
381
|
+
@field_validator("regulator_text")
|
|
382
|
+
@classmethod
|
|
383
|
+
def _nonempty(cls, v: str) -> str:
|
|
384
|
+
if not v or not v.strip():
|
|
385
|
+
raise ValueError("needs a non-empty regulator_text")
|
|
386
|
+
return v
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
#: Identity fields a region's agents may demand before acting on an account.
|
|
390
|
+
#: ``full_name`` / ``date_of_birth`` are universal; the rest are region-specific
|
|
391
|
+
#: national identifiers (e.g. India's PAN, issued by the income-tax department
|
|
392
|
+
#: and near-universally used for financial KYC).
|
|
393
|
+
IDENTITY_FIELDS: frozenset = frozenset(
|
|
394
|
+
{
|
|
395
|
+
"full_name",
|
|
396
|
+
"date_of_birth",
|
|
397
|
+
"pan",
|
|
398
|
+
"aadhaar_last4",
|
|
399
|
+
"national_id_last4",
|
|
400
|
+
}
|
|
401
|
+
)
|
|
402
|
+
|
|
403
|
+
#: Region-agnostic default: name + date of birth, which every market accepts.
|
|
404
|
+
DEFAULT_IDENTITY_REQUIRED_FIELDS: tuple[str, ...] = ("full_name", "date_of_birth")
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
class IdentityVerification(BaseModel):
|
|
408
|
+
"""Per-region KYC contract for the ``verify_identity`` framework primitive.
|
|
409
|
+
|
|
410
|
+
Regions differ in what counts as proof of identity, so the required set is
|
|
411
|
+
DATA rather than code: India expects a PAN alongside name + DOB, while the
|
|
412
|
+
US stops at name + DOB. The simulator gates its mock ``verify_identity`` on
|
|
413
|
+
this list and grounds the persona with matching values, so an agent that
|
|
414
|
+
skips a required field fails verification instead of waving the customer
|
|
415
|
+
through.
|
|
416
|
+
"""
|
|
417
|
+
|
|
418
|
+
required_fields: list[str] = Field(
|
|
419
|
+
default_factory=lambda: list(DEFAULT_IDENTITY_REQUIRED_FIELDS),
|
|
420
|
+
min_length=1,
|
|
421
|
+
)
|
|
422
|
+
|
|
423
|
+
@field_validator("required_fields")
|
|
424
|
+
@classmethod
|
|
425
|
+
def _known_fields(cls, v: list[str]) -> list[str]:
|
|
426
|
+
unknown = sorted(set(v) - IDENTITY_FIELDS)
|
|
427
|
+
if unknown:
|
|
428
|
+
raise ValueError(
|
|
429
|
+
f"identity_verification.required_fields: unknown field(s) {unknown} (known: {sorted(IDENTITY_FIELDS)})"
|
|
430
|
+
)
|
|
431
|
+
return v
|
|
432
|
+
|
|
433
|
+
|
|
434
|
+
#: Region-NEUTRAL fallback label for the account a listing tool reports, keyed by
|
|
435
|
+
#: domain. Deliberately generic: retail deposit products are named differently in
|
|
436
|
+
#: every market ("checking account" exists in the US and nowhere else, India says
|
|
437
|
+
#: savings / current), so the default must be true everywhere and regions override
|
|
438
|
+
#: it with local vocabulary via ``RegionSpec.account_labels``.
|
|
439
|
+
DEFAULT_DOMAIN_ACCOUNT_LABELS: dict[str, str] = {
|
|
440
|
+
"retail_banking": "deposit account",
|
|
441
|
+
"payments": "payment account",
|
|
442
|
+
"cards": "credit card account",
|
|
443
|
+
"lending_mortgage": "loan account",
|
|
444
|
+
"brokerage_investing": "brokerage account",
|
|
445
|
+
"retirement": "retirement account",
|
|
446
|
+
"wealth_management": "managed investment account",
|
|
447
|
+
"insurance": "policy",
|
|
448
|
+
"crypto": "crypto account",
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
class DocTitleVocabulary(BaseModel):
|
|
453
|
+
"""In-language overrides for the vocabulary the doc PLAN builds titles from.
|
|
454
|
+
|
|
455
|
+
Document titles are minted deterministically by ``build_product_doc_plan`` /
|
|
456
|
+
``build_shared_doc_plan`` as ``<product> <sep> <angle>``, and that string is
|
|
457
|
+
also the sibling cross-reference handle the whole institution shares. So the
|
|
458
|
+
angle words are reader-facing prose, and in a non-English locale they have to
|
|
459
|
+
be authored in that language: leaving them to the generator produced a corpus
|
|
460
|
+
whose bodies were 93% Devanagari while 44% of customer-facing TITLES were
|
|
461
|
+
still English, because the model was simultaneously told to write titles in
|
|
462
|
+
Hindi and to reproduce each sibling's title EXACTLY. It cannot do both, and
|
|
463
|
+
the concatenated title+body script check could not see the split (a 40-char
|
|
464
|
+
English title inside a 2,000-char Hindi body still scores ~0.93).
|
|
465
|
+
|
|
466
|
+
Every field is optional and an empty value falls back to the English default
|
|
467
|
+
in ``pipeline.py``, so a locale that omits the block — en_US and en_IN today —
|
|
468
|
+
plans byte-for-byte as before.
|
|
469
|
+
"""
|
|
470
|
+
|
|
471
|
+
#: Per-genre angle lists, keyed by document_type; overrides one genre at a
|
|
472
|
+
#: time, so a locale can translate ``fee_schedule`` and inherit the rest.
|
|
473
|
+
product_genre_angles: dict[str, list[str]] = Field(default_factory=dict)
|
|
474
|
+
faq_intents: list[str] = Field(default_factory=list)
|
|
475
|
+
how_to_intents: list[str] = Field(default_factory=list)
|
|
476
|
+
troubleshooting_intents: list[str] = Field(default_factory=list)
|
|
477
|
+
comparison_intents: list[str] = Field(default_factory=list)
|
|
478
|
+
#: Per-variable angle templates; must contain a ``{v}`` slot for the label.
|
|
479
|
+
faq_variable_template: str = ""
|
|
480
|
+
how_to_variable_template: str = ""
|
|
481
|
+
troubleshooting_variable_template: str = ""
|
|
482
|
+
#: Machine variable name -> reader-facing label. Unmapped names keep the
|
|
483
|
+
#: default underscores-to-spaces rendering, which is why en_IN currently
|
|
484
|
+
#: ships titles like "below mab charge explained".
|
|
485
|
+
variable_labels: dict[str, str] = Field(default_factory=dict)
|
|
486
|
+
#: Machine domain -> reader-facing label, for the regulatory-note topic.
|
|
487
|
+
domain_labels: dict[str, str] = Field(default_factory=dict)
|
|
488
|
+
#: Separator between the product name and the angle.
|
|
489
|
+
topic_separator: str = ""
|
|
490
|
+
#: Shared-cluster topics. ``{domain}`` / ``{tool}`` are substituted; a tool
|
|
491
|
+
#: name stays VERBATIM because it is an identifier the agent must call.
|
|
492
|
+
fee_overview_topic: str = ""
|
|
493
|
+
general_faq_topic: str = ""
|
|
494
|
+
regulatory_note_topic: str = ""
|
|
495
|
+
tool_policy_topic: str = ""
|
|
496
|
+
tool_reference_topic: str = ""
|
|
497
|
+
|
|
498
|
+
@model_validator(mode="after")
|
|
499
|
+
def _templates_keep_their_slots(self) -> "DocTitleVocabulary":
|
|
500
|
+
"""A template that loses its placeholder silently collapses every doc of
|
|
501
|
+
that genre onto one title, which then de-duplicates down to a single
|
|
502
|
+
document. Fail at spec load instead."""
|
|
503
|
+
for field, slot in (
|
|
504
|
+
("faq_variable_template", "{v}"),
|
|
505
|
+
("how_to_variable_template", "{v}"),
|
|
506
|
+
("troubleshooting_variable_template", "{v}"),
|
|
507
|
+
("regulatory_note_topic", "{domain}"),
|
|
508
|
+
("tool_policy_topic", "{tool}"),
|
|
509
|
+
("tool_reference_topic", "{tool}"),
|
|
510
|
+
):
|
|
511
|
+
value = getattr(self, field)
|
|
512
|
+
if value and slot not in value:
|
|
513
|
+
raise ValueError(f"doc_titles.{field} = {value!r} must contain {slot}")
|
|
514
|
+
return self
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
class LanguageConventions(BaseModel):
|
|
518
|
+
"""Spelling and usage the generated prose follows, for a language whose regional
|
|
519
|
+
variants share a script (British and US English), which the script check cannot
|
|
520
|
+
tell apart.
|
|
521
|
+
|
|
522
|
+
``guidance`` goes into the brief and doc-gen prompts. ``respell`` maps each form
|
|
523
|
+
the prose must not contain to the form written instead: the prompts name both,
|
|
524
|
+
generation rewrites any that still appear in a document body, and
|
|
525
|
+
``validate-assets`` fails a document title or body that uses one. Both empty
|
|
526
|
+
adds nothing to the prompts or the corpus.
|
|
527
|
+
"""
|
|
528
|
+
|
|
529
|
+
guidance: str = ""
|
|
530
|
+
#: Whole words or phrases, matched case-insensitively. A replacement follows the
|
|
531
|
+
#: capitalisation of the form it replaces: all capitals, a leading capital, or
|
|
532
|
+
#: as written here.
|
|
533
|
+
respell: dict[str, str] = Field(default_factory=dict)
|
|
534
|
+
|
|
535
|
+
@field_validator("respell")
|
|
536
|
+
@classmethod
|
|
537
|
+
def _no_blank_forms(cls, v: dict[str, str]) -> dict[str, str]:
|
|
538
|
+
"""A blank form would match at every word boundary."""
|
|
539
|
+
if any(not form.strip() or not replacement.strip() for form, replacement in v.items()):
|
|
540
|
+
raise ValueError("language_conventions.respell forms and replacements must not be blank")
|
|
541
|
+
return {form.strip(): replacement.strip() for form, replacement in v.items()}
|
|
542
|
+
|
|
543
|
+
def _pattern(self) -> re.Pattern[str] | None:
|
|
544
|
+
if not self.respell:
|
|
545
|
+
return None
|
|
546
|
+
alternatives = "|".join(sorted((re.escape(form) for form in self.respell), key=len, reverse=True))
|
|
547
|
+
return re.compile(rf"(?<!\w)({alternatives})(?!\w)", re.IGNORECASE)
|
|
548
|
+
|
|
549
|
+
def find(self, text: str) -> list[str]:
|
|
550
|
+
"""The forms in ``respell`` that ``text`` uses, lowercased, in order."""
|
|
551
|
+
pattern = self._pattern()
|
|
552
|
+
return [form.lower() for form in pattern.findall(text)] if pattern else []
|
|
553
|
+
|
|
554
|
+
def apply(self, text: str) -> str:
|
|
555
|
+
"""``text`` with every form in ``respell`` replaced."""
|
|
556
|
+
pattern = self._pattern()
|
|
557
|
+
if pattern is None:
|
|
558
|
+
return text
|
|
559
|
+
replacements = {form.lower(): replacement for form, replacement in self.respell.items()}
|
|
560
|
+
|
|
561
|
+
def replace(match: re.Match[str]) -> str:
|
|
562
|
+
found = match.group(1)
|
|
563
|
+
replacement = replacements[found.lower()]
|
|
564
|
+
if len(found) > 1 and found.isupper():
|
|
565
|
+
return replacement.upper()
|
|
566
|
+
if found[0].isupper():
|
|
567
|
+
return replacement[0].upper() + replacement[1:]
|
|
568
|
+
return replacement
|
|
569
|
+
|
|
570
|
+
return pattern.sub(replace, text)
|
|
571
|
+
|
|
572
|
+
|
|
573
|
+
class RegionSpec(BaseModel):
|
|
574
|
+
schema_version: str = "v0.1"
|
|
575
|
+
#: Optional locale of a BASE spec in the same directory to inherit from.
|
|
576
|
+
#: A ``region_spec`` is keyed by LOCALE, but institutions / products /
|
|
577
|
+
#: regulators are properties of the REGION — identical across every language
|
|
578
|
+
#: spoken there. India alone has three surfaces (en_IN, hi_Deva_IN,
|
|
579
|
+
#: hi_Latn_IN), so without inheritance the same 400-line model would be
|
|
580
|
+
#: copied per language and drift the first time a fee changed in only one.
|
|
581
|
+
#: A language variant therefore overlays just what differs (locale, language,
|
|
582
|
+
#: in-language names). Resolved at load time; never serialized.
|
|
583
|
+
extends: str | None = None
|
|
584
|
+
region: str
|
|
585
|
+
locale: str
|
|
586
|
+
currency: str
|
|
587
|
+
currency_symbol: str = "$"
|
|
588
|
+
#: Human-readable language for generated document CONTENT (e.g. "English (US)",
|
|
589
|
+
#: "Japanese", "Brazilian Portuguese"). Threaded into the doc-gen prompt so a
|
|
590
|
+
#: non-English locale produces native-language docs. Region-specific data, not
|
|
591
|
+
#: derived from ``locale``, so authors control script/register explicitly.
|
|
592
|
+
language: str
|
|
593
|
+
#: Optional spelling and usage for ``language``; see :class:`LanguageConventions`.
|
|
594
|
+
#: A LANGUAGE surface, like ``doc_titles``.
|
|
595
|
+
language_conventions: LanguageConventions = Field(default_factory=LanguageConventions)
|
|
596
|
+
number_format: str | None = None
|
|
597
|
+
privacy_regime: str | None = None
|
|
598
|
+
#: Optional; omitted means the region-agnostic name + DOB default.
|
|
599
|
+
identity_verification: IdentityVerification = Field(default_factory=IdentityVerification)
|
|
600
|
+
#: Optional per-domain label for the account the simulator's read tools report,
|
|
601
|
+
#: in this region's own product vocabulary (US: "checking account"; India:
|
|
602
|
+
#: "savings account"). Region data rather than code, because naming an account
|
|
603
|
+
#: after a product the market does not have reads as the wrong institution to
|
|
604
|
+
#: the customer. Omitted domains fall back to
|
|
605
|
+
#: ``DEFAULT_DOMAIN_ACCOUNT_LABELS``; a task's authored ``account_type`` always
|
|
606
|
+
#: wins over both.
|
|
607
|
+
account_labels: dict[str, str] = Field(default_factory=dict)
|
|
608
|
+
#: Optional in-language overrides for the words the doc plan builds titles
|
|
609
|
+
#: from. A LANGUAGE surface, not a region property, so it belongs in the
|
|
610
|
+
#: language overlay next to ``display_name_local`` rather than in the region
|
|
611
|
+
#: model. Omitted entirely => the English defaults in ``pipeline.py``.
|
|
612
|
+
doc_titles: DocTitleVocabulary = Field(default_factory=DocTitleVocabulary)
|
|
613
|
+
bank_id: str | None = None
|
|
614
|
+
bank_version: str | None = None
|
|
615
|
+
task_contract_version: str | None = None
|
|
616
|
+
document_types: list[DocumentType] = Field(min_length=1)
|
|
617
|
+
domain_regulators: dict[str, RegulatorContext] = Field(default_factory=dict)
|
|
618
|
+
#: Optional per-institution-type emphasis for the generated brief, keyed by
|
|
619
|
+
#: institution type. This is where MARKET-SPECIFIC framing belongs (US: RMDs,
|
|
620
|
+
#: best-interest/fiduciary; India: NPS/PPF lock-ins, AMFI market-risk wording,
|
|
621
|
+
#: gold-loan LTV). Unset types fall back to a region-neutral default, so a new
|
|
622
|
+
#: locale never silently inherits another market's instruments or statutes.
|
|
623
|
+
concept_guidance: dict[str, str] = Field(default_factory=dict)
|
|
624
|
+
institutions: list[Institution] = Field(min_length=1)
|
|
625
|
+
|
|
626
|
+
@field_validator("concept_guidance")
|
|
627
|
+
@classmethod
|
|
628
|
+
def _known_types(cls, v: dict[str, str]) -> dict[str, str]:
|
|
629
|
+
unknown = sorted(set(v) - INSTITUTION_TYPES)
|
|
630
|
+
if unknown:
|
|
631
|
+
raise ValueError(
|
|
632
|
+
f"concept_guidance: unknown institution type(s) {unknown} (known: {sorted(INSTITUTION_TYPES)})"
|
|
633
|
+
)
|
|
634
|
+
return v
|
|
635
|
+
|
|
636
|
+
@field_validator("account_labels")
|
|
637
|
+
@classmethod
|
|
638
|
+
def _known_label_domains(cls, v: dict[str, str]) -> dict[str, str]:
|
|
639
|
+
unknown = sorted(set(v) - DOMAINS)
|
|
640
|
+
if unknown:
|
|
641
|
+
raise ValueError(f"account_labels: unknown domain(s) {unknown} (known: {sorted(DOMAINS)})")
|
|
642
|
+
return v
|
|
643
|
+
|
|
644
|
+
@field_validator("region", "locale", "currency")
|
|
645
|
+
@classmethod
|
|
646
|
+
def _nonempty(cls, v: str, info: ValidationInfo) -> str:
|
|
647
|
+
if not v or not v.strip():
|
|
648
|
+
raise ValueError(f"missing/empty required field {info.field_name!r}")
|
|
649
|
+
return v
|
|
650
|
+
|
|
651
|
+
@model_validator(mode="after")
|
|
652
|
+
def _domain_regulator_coverage(self) -> "RegionSpec":
|
|
653
|
+
seen: set = set()
|
|
654
|
+
for inst in self.institutions:
|
|
655
|
+
if inst.id in seen:
|
|
656
|
+
raise ValueError(f"{inst.id}: duplicate institution id")
|
|
657
|
+
seen.add(inst.id)
|
|
658
|
+
declared = {d for inst in self.institutions for d in inst.domains}
|
|
659
|
+
missing = sorted(declared - set(self.domain_regulators))
|
|
660
|
+
if missing:
|
|
661
|
+
raise ValueError(
|
|
662
|
+
f"domain_regulators: missing regulator context for domains {missing} "
|
|
663
|
+
f"(every offered domain needs a regulator_text)"
|
|
664
|
+
)
|
|
665
|
+
return self
|
|
666
|
+
|
|
667
|
+
|
|
668
|
+
# ── Loading / validation entry points (stable public surface) ──────────
|
|
669
|
+
|
|
670
|
+
|
|
671
|
+
def _validate(raw: Any, *, src: str) -> RegionSpec:
|
|
672
|
+
try:
|
|
673
|
+
return RegionSpec.model_validate(raw)
|
|
674
|
+
except ValidationError as e:
|
|
675
|
+
raise RegionSpecError(f"{src}: {e}") from e
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
def _is_id_keyed(items: Any) -> bool:
|
|
679
|
+
"""True for a non-empty list whose every entry is a mapping carrying an ``id``.
|
|
680
|
+
|
|
681
|
+
Structural rather than an allowlist of field names: one rule to remember
|
|
682
|
+
("entries with an ``id`` are patched by id, everything else is replaced"), and
|
|
683
|
+
a new id-bearing list needs no change here. ``institutions``, ``products`` and
|
|
684
|
+
``task_templates`` all qualify; ``document_types`` / ``domains`` /
|
|
685
|
+
``gold_tool_sequence`` (plain strings) and ``tool_taxonomy`` (keyed by
|
|
686
|
+
``name``, not ``id``) do not, and so replace wholesale.
|
|
687
|
+
"""
|
|
688
|
+
return bool(items) and all(isinstance(e, dict) and "id" in e for e in items)
|
|
689
|
+
|
|
690
|
+
|
|
691
|
+
def _merge_overlay(base: Any, overlay: Any, *, path: str = "") -> Any:
|
|
692
|
+
"""Deep-merge ``overlay`` onto ``base`` for region_spec inheritance.
|
|
693
|
+
|
|
694
|
+
Mappings merge key-by-key. Lists of ``id``-bearing entries merge per id — an
|
|
695
|
+
overlay entry patches the matching base entry, an unmatched one is appended,
|
|
696
|
+
and order follows the base — so a language variant can rename a single
|
|
697
|
+
product without repeating the lineup. Every other list replaces wholesale
|
|
698
|
+
(``document_types`` is a set-like choice, not a patch).
|
|
699
|
+
|
|
700
|
+
An overlay cannot DELETE an inherited entry or null out an inherited field;
|
|
701
|
+
a variant that needs to drop institutions should be authored standalone
|
|
702
|
+
rather than as an overlay.
|
|
703
|
+
"""
|
|
704
|
+
if isinstance(base, dict) and isinstance(overlay, dict):
|
|
705
|
+
out = dict(base)
|
|
706
|
+
for k, v in overlay.items():
|
|
707
|
+
out[k] = _merge_overlay(base.get(k), v, path=f"{path}.{k}" if path else k)
|
|
708
|
+
return out
|
|
709
|
+
if isinstance(base, list) and isinstance(overlay, list) and _is_id_keyed(base):
|
|
710
|
+
if not _is_id_keyed(overlay):
|
|
711
|
+
raise RegionSpecError(
|
|
712
|
+
f"{path or '<list>'}: the base list is keyed by 'id', so every "
|
|
713
|
+
f"overlay entry must be a mapping carrying an 'id' to patch "
|
|
714
|
+
f"(got {overlay!r})"
|
|
715
|
+
)
|
|
716
|
+
by_id = {e["id"]: dict(e) for e in base}
|
|
717
|
+
order = [e["id"] for e in base]
|
|
718
|
+
for entry in overlay:
|
|
719
|
+
eid = entry["id"]
|
|
720
|
+
if eid in by_id:
|
|
721
|
+
by_id[eid] = _merge_overlay(by_id[eid], entry, path=path)
|
|
722
|
+
else:
|
|
723
|
+
by_id[eid] = dict(entry)
|
|
724
|
+
order.append(eid)
|
|
725
|
+
return [by_id[i] for i in order]
|
|
726
|
+
return overlay if overlay is not None else base
|
|
727
|
+
|
|
728
|
+
|
|
729
|
+
def load_region_spec(path: str | Path) -> RegionSpec:
|
|
730
|
+
"""Load + validate a region_spec YAML, resolving ``extends``.
|
|
731
|
+
|
|
732
|
+
Raises :class:`RegionSpecError`.
|
|
733
|
+
"""
|
|
734
|
+
raw, p = _read_spec_yaml(path)
|
|
735
|
+
seen: list[str] = []
|
|
736
|
+
while raw.get("extends"):
|
|
737
|
+
base_locale = str(raw.pop("extends"))
|
|
738
|
+
if base_locale in seen:
|
|
739
|
+
raise RegionSpecError(f"{p}: circular extends chain via {base_locale!r} ({' -> '.join(seen)})")
|
|
740
|
+
seen.append(base_locale)
|
|
741
|
+
base_path = p.parent / f"{base_locale}.yaml"
|
|
742
|
+
if not base_path.exists():
|
|
743
|
+
raise RegionSpecError(f"{p}: extends {base_locale!r} but {base_path} does not exist")
|
|
744
|
+
base_raw, _ = _read_spec_yaml(base_path)
|
|
745
|
+
# The overlay wins; the base may itself extend another spec.
|
|
746
|
+
raw = _merge_overlay(base_raw, raw)
|
|
747
|
+
return _validate(raw, src=str(p))
|
|
748
|
+
|
|
749
|
+
|
|
750
|
+
def _read_spec_yaml(path: str | Path) -> tuple[dict[str, Any], Path]:
|
|
751
|
+
import yaml
|
|
752
|
+
|
|
753
|
+
p = Path(path)
|
|
754
|
+
if not p.exists():
|
|
755
|
+
raise RegionSpecError(f"{path}: file not found")
|
|
756
|
+
with p.open("r", encoding="utf-8") as fh:
|
|
757
|
+
raw = yaml.safe_load(fh)
|
|
758
|
+
if not isinstance(raw, dict):
|
|
759
|
+
raise RegionSpecError(f"{path}: top-level must be a mapping")
|
|
760
|
+
return raw, p
|
|
761
|
+
|
|
762
|
+
|
|
763
|
+
def validate_region_spec(spec: Any, *, src: str = "<region_spec>") -> RegionSpec:
|
|
764
|
+
"""Validate a region_spec mapping. Raises :class:`RegionSpecError`.
|
|
765
|
+
|
|
766
|
+
Rejects a mapping carrying ``extends``: resolving inheritance needs the spec
|
|
767
|
+
DIRECTORY to find the base, which this signature does not take. Validating
|
|
768
|
+
such a mapping would otherwise succeed while silently ignoring everything the
|
|
769
|
+
base was meant to contribute.
|
|
770
|
+
"""
|
|
771
|
+
if isinstance(spec, dict) and spec.get("extends"):
|
|
772
|
+
raise RegionSpecError(
|
|
773
|
+
f"{src}: 'extends' can only be resolved by load_region_spec(path) "
|
|
774
|
+
f"(the base spec is looked up next to the file). Either call "
|
|
775
|
+
f"load_region_spec, or inline the base's fields into this mapping."
|
|
776
|
+
)
|
|
777
|
+
return _validate(spec, src=src)
|
|
778
|
+
|
|
779
|
+
|
|
780
|
+
def core_ontology() -> dict[str, Any]:
|
|
781
|
+
"""The full ontology vocabulary as a dict (for docs / introspection)."""
|
|
782
|
+
return {
|
|
783
|
+
"institution_types": sorted(INSTITUTION_TYPES),
|
|
784
|
+
"domains": sorted(DOMAINS),
|
|
785
|
+
"institution_domains": {k: sorted(v) for k, v in INSTITUTION_DOMAINS.items()},
|
|
786
|
+
"brand_voices": sorted(BRAND_VOICES),
|
|
787
|
+
"document_types": sorted(DOCUMENT_TYPES),
|
|
788
|
+
"information_formats": sorted(INFORMATION_FORMATS),
|
|
789
|
+
"source_authorities": sorted(SOURCE_AUTHORITIES),
|
|
790
|
+
"side_effect_classes": sorted(SIDE_EFFECT_CLASSES),
|
|
791
|
+
"task_types": sorted(TASK_TYPES),
|
|
792
|
+
"task_tiers": sorted(TASK_TIERS),
|
|
793
|
+
"persona_tag_prefixes": sorted(PERSONA_TAG_PREFIXES),
|
|
794
|
+
}
|