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.
Files changed (379) hide show
  1. usersim/__init__.py +23 -0
  2. usersim/asset_gen/__init__.py +22 -0
  3. usersim/asset_gen/financial_services/__init__.py +22 -0
  4. usersim/asset_gen/financial_services/evaluate.py +330 -0
  5. usersim/asset_gen/financial_services/pipeline.py +1590 -0
  6. usersim/asset_gen/financial_services/prompts.py +318 -0
  7. usersim/asset_gen/financial_services/spec.py +794 -0
  8. usersim/asset_gen/financial_services/validate.py +750 -0
  9. usersim/asset_gen/registry.py +191 -0
  10. usersim/cli/__init__.py +185 -0
  11. usersim/cli/__main__.py +13 -0
  12. usersim/cli/_async.py +35 -0
  13. usersim/cli/_env.py +74 -0
  14. usersim/cli/_errors.py +44 -0
  15. usersim/cli/_inputs.py +691 -0
  16. usersim/cli/_models.py +1222 -0
  17. usersim/cli/_ngc.py +441 -0
  18. usersim/cli/_persona_language.py +316 -0
  19. usersim/cli/_pipeline.py +1007 -0
  20. usersim/cli/evaluate.py +415 -0
  21. usersim/cli/evaluate_assets.py +115 -0
  22. usersim/cli/gen_assets.py +120 -0
  23. usersim/cli/model_catalog.py +451 -0
  24. usersim/cli/models_default.toml +46 -0
  25. usersim/cli/models_openai.toml +26 -0
  26. usersim/cli/models_openrouter.toml +33 -0
  27. usersim/cli/panel.py +193 -0
  28. usersim/cli/report.py +247 -0
  29. usersim/cli/rescore.py +223 -0
  30. usersim/cli/select.py +304 -0
  31. usersim/cli/setup_ngc.py +131 -0
  32. usersim/cli/simulate.py +866 -0
  33. usersim/cli/smoke.py +1019 -0
  34. usersim/cli/validate_assets.py +64 -0
  35. usersim/engine/__init__.py +4 -0
  36. usersim/engine/assets/financial_services/SCHEMA.md +320 -0
  37. usersim/engine/assets/financial_services/de_DE/_generation_report.json +945 -0
  38. usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/corpus.yaml +8006 -0
  39. usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/institution_meta.yaml +9 -0
  40. usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/tasks.yaml +366 -0
  41. usersim/engine/assets/financial_services/de_DE/bank/bausparkasse_heimstatt/tools.yaml +114 -0
  42. usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/corpus.yaml +10053 -0
  43. usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/institution_meta.yaml +10 -0
  44. usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/tasks.yaml +578 -0
  45. usersim/engine/assets/financial_services/de_DE/bank/sparkasse_lindenhain/tools.yaml +154 -0
  46. usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/corpus.yaml +6784 -0
  47. usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/institution_meta.yaml +8 -0
  48. usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/tasks.yaml +394 -0
  49. usersim/engine/assets/financial_services/de_DE/brokerage/kranich_invest/tools.yaml +134 -0
  50. usersim/engine/assets/financial_services/de_DE/dynamic.yaml +252 -0
  51. usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/corpus.yaml +9404 -0
  52. usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/institution_meta.yaml +8 -0
  53. usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/tasks.yaml +394 -0
  54. usersim/engine/assets/financial_services/de_DE/insurer/hanseatica_versicherung/tools.yaml +114 -0
  55. usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/corpus.yaml +8181 -0
  56. usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/institution_meta.yaml +10 -0
  57. usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/tasks.yaml +440 -0
  58. usersim/engine/assets/financial_services/de_DE/neobank/kompass_direktbank/tools.yaml +144 -0
  59. usersim/engine/assets/financial_services/de_DE/region_meta.yaml +108 -0
  60. usersim/engine/assets/financial_services/en_GB/_generation_report.json +1330 -0
  61. usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/corpus.yaml +11053 -0
  62. usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/institution_meta.yaml +9 -0
  63. usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/tasks.yaml +401 -0
  64. usersim/engine/assets/financial_services/en_GB/bank/fernbridge_building_society/tools.yaml +114 -0
  65. usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/corpus.yaml +13830 -0
  66. usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/institution_meta.yaml +11 -0
  67. usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/tasks.yaml +597 -0
  68. usersim/engine/assets/financial_services/en_GB/bank/wrenfield_bank/tools.yaml +159 -0
  69. usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/corpus.yaml +9717 -0
  70. usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/institution_meta.yaml +8 -0
  71. usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/tasks.yaml +418 -0
  72. usersim/engine/assets/financial_services/en_GB/brokerage/copperleaf_invest/tools.yaml +139 -0
  73. usersim/engine/assets/financial_services/en_GB/dynamic.yaml +309 -0
  74. usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/corpus.yaml +7891 -0
  75. usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/institution_meta.yaml +8 -0
  76. usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/tasks.yaml +345 -0
  77. usersim/engine/assets/financial_services/en_GB/insurer/kingsmere_insurance/tools.yaml +114 -0
  78. usersim/engine/assets/financial_services/en_GB/neobank/quill/corpus.yaml +9579 -0
  79. usersim/engine/assets/financial_services/en_GB/neobank/quill/institution_meta.yaml +10 -0
  80. usersim/engine/assets/financial_services/en_GB/neobank/quill/tasks.yaml +453 -0
  81. usersim/engine/assets/financial_services/en_GB/neobank/quill/tools.yaml +154 -0
  82. usersim/engine/assets/financial_services/en_GB/region_meta.yaml +128 -0
  83. usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/corpus.yaml +8028 -0
  84. usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/institution_meta.yaml +8 -0
  85. usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/tasks.yaml +387 -0
  86. usersim/engine/assets/financial_services/en_GB/retirement_provider/oakhaven_pensions/tools.yaml +124 -0
  87. usersim/engine/assets/financial_services/en_IN/_generation_report.json +977 -0
  88. usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/corpus.yaml +9170 -0
  89. usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/institution_meta.yaml +10 -0
  90. usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/tasks.yaml +330 -0
  91. usersim/engine/assets/financial_services/en_IN/bank/chandrika_bank/tools.yaml +139 -0
  92. usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/corpus.yaml +7436 -0
  93. usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/institution_meta.yaml +8 -0
  94. usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/tasks.yaml +323 -0
  95. usersim/engine/assets/financial_services/en_IN/brokerage/tarang_invest/tools.yaml +129 -0
  96. usersim/engine/assets/financial_services/en_IN/dynamic.yaml +256 -0
  97. usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/corpus.yaml +7641 -0
  98. usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/institution_meta.yaml +8 -0
  99. usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/tasks.yaml +350 -0
  100. usersim/engine/assets/financial_services/en_IN/insurer/abhaya_insurance/tools.yaml +114 -0
  101. usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/corpus.yaml +9453 -0
  102. usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/institution_meta.yaml +9 -0
  103. usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/tasks.yaml +346 -0
  104. usersim/engine/assets/financial_services/en_IN/nbfc/kalash_finserv/tools.yaml +114 -0
  105. usersim/engine/assets/financial_services/en_IN/neobank/paysetu/corpus.yaml +8237 -0
  106. usersim/engine/assets/financial_services/en_IN/neobank/paysetu/institution_meta.yaml +10 -0
  107. usersim/engine/assets/financial_services/en_IN/neobank/paysetu/tasks.yaml +313 -0
  108. usersim/engine/assets/financial_services/en_IN/neobank/paysetu/tools.yaml +139 -0
  109. usersim/engine/assets/financial_services/en_IN/region_meta.yaml +81 -0
  110. usersim/engine/assets/financial_services/en_US/_generation_report.json +768 -0
  111. usersim/engine/assets/financial_services/en_US/bank/northwind_bank/corpus.yaml +9131 -0
  112. usersim/engine/assets/financial_services/en_US/bank/northwind_bank/institution_meta.yaml +9 -0
  113. usersim/engine/assets/financial_services/en_US/bank/northwind_bank/tasks.yaml +473 -0
  114. usersim/engine/assets/financial_services/en_US/bank/northwind_bank/tools.yaml +129 -0
  115. usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/corpus.yaml +7868 -0
  116. usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/institution_meta.yaml +8 -0
  117. usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/tasks.yaml +388 -0
  118. usersim/engine/assets/financial_services/en_US/brokerage/solstice_invest/tools.yaml +124 -0
  119. usersim/engine/assets/financial_services/en_US/dynamic.yaml +198 -0
  120. usersim/engine/assets/financial_services/en_US/region_meta.yaml +58 -0
  121. usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/corpus.yaml +8117 -0
  122. usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/institution_meta.yaml +8 -0
  123. usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/tasks.yaml +369 -0
  124. usersim/engine/assets/financial_services/en_US/retirement_provider/evergreen_retirement/tools.yaml +109 -0
  125. usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/corpus.yaml +6897 -0
  126. usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/institution_meta.yaml +8 -0
  127. usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/tasks.yaml +319 -0
  128. usersim/engine/assets/financial_services/en_US/wealth_manager/meridian_wealth/tools.yaml +109 -0
  129. usersim/engine/assets/financial_services/fr_FR/_generation_report.json +1041 -0
  130. usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/corpus.yaml +10842 -0
  131. usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/institution_meta.yaml +10 -0
  132. usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/tasks.yaml +529 -0
  133. usersim/engine/assets/financial_services/fr_FR/bank/credit_mirabelle/tools.yaml +144 -0
  134. usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/corpus.yaml +9091 -0
  135. usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/institution_meta.yaml +8 -0
  136. usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/tasks.yaml +511 -0
  137. usersim/engine/assets/financial_services/fr_FR/brokerage/valbreuil_bourse/tools.yaml +129 -0
  138. usersim/engine/assets/financial_services/fr_FR/dynamic.yaml +264 -0
  139. usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/corpus.yaml +9033 -0
  140. usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/institution_meta.yaml +8 -0
  141. usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/tasks.yaml +505 -0
  142. usersim/engine/assets/financial_services/fr_FR/insurer/egide_assurances/tools.yaml +134 -0
  143. usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/corpus.yaml +7494 -0
  144. usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/institution_meta.yaml +9 -0
  145. usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/tasks.yaml +383 -0
  146. usersim/engine/assets/financial_services/fr_FR/nbfc/ondine_credit/tools.yaml +114 -0
  147. usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/corpus.yaml +7883 -0
  148. usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/institution_meta.yaml +10 -0
  149. usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/tasks.yaml +430 -0
  150. usersim/engine/assets/financial_services/fr_FR/neobank/kiosque/tools.yaml +139 -0
  151. usersim/engine/assets/financial_services/fr_FR/region_meta.yaml +114 -0
  152. usersim/engine/assets/financial_services/hi_Deva_IN/_generation_report.json +977 -0
  153. usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/corpus.yaml +6265 -0
  154. usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/institution_meta.yaml +11 -0
  155. usersim/engine/assets/financial_services/hi_Deva_IN/bank/chandrika_bank/tools.yaml +139 -0
  156. usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/corpus.yaml +5188 -0
  157. usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/institution_meta.yaml +9 -0
  158. usersim/engine/assets/financial_services/hi_Deva_IN/brokerage/tarang_invest/tools.yaml +129 -0
  159. usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/corpus.yaml +5115 -0
  160. usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/institution_meta.yaml +9 -0
  161. usersim/engine/assets/financial_services/hi_Deva_IN/insurer/abhaya_insurance/tools.yaml +114 -0
  162. usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/corpus.yaml +6539 -0
  163. usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/institution_meta.yaml +10 -0
  164. usersim/engine/assets/financial_services/hi_Deva_IN/nbfc/kalash_finserv/tools.yaml +114 -0
  165. usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/corpus.yaml +5370 -0
  166. usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/institution_meta.yaml +11 -0
  167. usersim/engine/assets/financial_services/hi_Deva_IN/neobank/paysetu/tools.yaml +139 -0
  168. usersim/engine/assets/financial_services/hi_Deva_IN/region_meta.yaml +81 -0
  169. usersim/engine/assets/general_educational/prompts.yaml +115 -0
  170. usersim/engine/assets/general_educational/subjects/base/subjects.json +162 -0
  171. usersim/engine/assets/general_educational/subjects/de_DE/subjects.json +162 -0
  172. usersim/engine/assets/general_educational/subjects/en_GB/subjects.json +162 -0
  173. usersim/engine/assets/general_educational/subjects/fr_FR/subjects.json +16 -0
  174. usersim/engine/assets/general_educational/subjects/hi_Deva_IN/subjects.json +14 -0
  175. usersim/engine/assets/general_educational/subjects/hi_Latn_IN/subjects.json +14 -0
  176. usersim/engine/assets/general_educational/subjects/ja_JP/subjects.json +16 -0
  177. usersim/engine/assets/general_educational/subjects/ko_KR/subjects.json +16 -0
  178. usersim/engine/assets/general_educational/subjects/pt_BR/subjects.json +12 -0
  179. usersim/engine/assets/general_open_ended/prompts.yaml +117 -0
  180. usersim/engine/assets/general_open_ended/topics/base/topics.json +194 -0
  181. usersim/engine/assets/general_open_ended/topics/de_DE/topics.json +194 -0
  182. usersim/engine/assets/general_open_ended/topics/en_GB/topics.json +194 -0
  183. usersim/engine/assets/general_open_ended/topics/fr_FR/topics.json +22 -0
  184. usersim/engine/assets/general_open_ended/topics/hi_Deva_IN/topics.json +22 -0
  185. usersim/engine/assets/general_open_ended/topics/hi_Latn_IN/topics.json +22 -0
  186. usersim/engine/assets/general_open_ended/topics/ja_JP/topics.json +17 -0
  187. usersim/engine/assets/general_open_ended/topics/ko_KR/topics.json +17 -0
  188. usersim/engine/assets/general_open_ended/topics/pt_BR/topics.json +22 -0
  189. usersim/engine/assets/health_decision_support_disclosure/sample.yaml +21 -0
  190. usersim/engine/assets/health_general_disclosure/sample.yaml +21 -0
  191. usersim/engine/assets/health_therapy_disclosure/sample.yaml +23 -0
  192. usersim/engine/assets/health_triage_disclosure/sample.yaml +21 -0
  193. usersim/engine/assets/identity_disclosure/SCHEMA.md +303 -0
  194. usersim/engine/assets/identity_disclosure/spec.yaml +1007 -0
  195. usersim/engine/assets/safety_agentic/SCHEMA.md +252 -0
  196. usersim/engine/assets/safety_agentic/action_taxonomy.yaml +682 -0
  197. usersim/engine/assets/safety_agentic/sample.yaml +3993 -0
  198. usersim/engine/assets/safety_chat_pressure/SCHEMA.md +181 -0
  199. usersim/engine/assets/safety_chat_pressure/sample.yaml +3646 -0
  200. usersim/engine/assets/sov_ai_dynamic/SCHEMA.md +98 -0
  201. usersim/engine/assets/sov_ai_dynamic/de_DE/categories.yaml +116 -0
  202. usersim/engine/assets/sov_ai_dynamic/en_GB/categories.yaml +116 -0
  203. usersim/engine/assets/sov_ai_dynamic/en_IN/categories.yaml +116 -0
  204. usersim/engine/assets/sov_ai_dynamic/en_SG/categories.yaml +116 -0
  205. usersim/engine/assets/sov_ai_dynamic/en_US/categories.yaml +116 -0
  206. usersim/engine/assets/sov_ai_dynamic/fr_FR/categories.yaml +116 -0
  207. usersim/engine/assets/sov_ai_dynamic/hi_Deva_IN/categories.yaml +116 -0
  208. usersim/engine/assets/sov_ai_dynamic/hi_Latn_IN/categories.yaml +116 -0
  209. usersim/engine/assets/sov_ai_dynamic/ja_JP/categories.yaml +116 -0
  210. usersim/engine/assets/sov_ai_dynamic/ko_KR/categories.yaml +116 -0
  211. usersim/engine/assets/sov_ai_dynamic/pt_BR/categories.yaml +116 -0
  212. usersim/engine/assets/sov_ai_facts/SCHEMA.md +196 -0
  213. usersim/engine/assets/sov_ai_facts/de_DE/sample.yaml +1421 -0
  214. usersim/engine/assets/sov_ai_facts/en_GB/sample.yaml +1389 -0
  215. usersim/engine/assets/sov_ai_facts/en_IN/sample.yaml +1275 -0
  216. usersim/engine/assets/sov_ai_facts/en_SG/sample.yaml +1358 -0
  217. usersim/engine/assets/sov_ai_facts/en_US/sample.yaml +1270 -0
  218. usersim/engine/assets/sov_ai_facts/fr_FR/sample.yaml +1287 -0
  219. usersim/engine/assets/sov_ai_facts/hi_Deva_IN/sample.yaml +1272 -0
  220. usersim/engine/assets/sov_ai_facts/hi_Latn_IN/sample.yaml +1272 -0
  221. usersim/engine/assets/sov_ai_facts/ja_JP/sample.yaml +1294 -0
  222. usersim/engine/assets/sov_ai_facts/ko_KR/sample.yaml +1435 -0
  223. usersim/engine/assets/sov_ai_facts/pt_BR/sample.yaml +1321 -0
  224. usersim/engine/assets/sov_ai_multilingual_parity/SCHEMA.md +137 -0
  225. usersim/engine/assets/sov_ai_multilingual_parity/sample.yaml +1210 -0
  226. usersim/engine/assets/tool_calling/README.md +225 -0
  227. usersim/engine/assets/tool_calling/prompts.yaml +171 -0
  228. usersim/engine/assets/tool_calling/toolsets_seed.parquet +0 -0
  229. usersim/engine/config.py +296 -0
  230. usersim/engine/core/__init__.py +4 -0
  231. usersim/engine/core/_assets.py +178 -0
  232. usersim/engine/core/_extensions.py +148 -0
  233. usersim/engine/core/action_taxonomy.py +347 -0
  234. usersim/engine/core/agentic_bank.py +725 -0
  235. usersim/engine/core/analysis.py +60 -0
  236. usersim/engine/core/backends.py +180 -0
  237. usersim/engine/core/behavioral.py +755 -0
  238. usersim/engine/core/clinical_profile_bank.py +245 -0
  239. usersim/engine/core/context.py +137 -0
  240. usersim/engine/core/embeddings.py +83 -0
  241. usersim/engine/core/episode_input.py +281 -0
  242. usersim/engine/core/episode_runtime.py +735 -0
  243. usersim/engine/core/fact_bank.py +500 -0
  244. usersim/engine/core/finance_bank.py +970 -0
  245. usersim/engine/core/finance_tasks.py +292 -0
  246. usersim/engine/core/idempotency.py +62 -0
  247. usersim/engine/core/identity.py +215 -0
  248. usersim/engine/core/identity_spec.py +659 -0
  249. usersim/engine/core/identity_spec_types.py +425 -0
  250. usersim/engine/core/judges.py +85 -0
  251. usersim/engine/core/language_detection.py +239 -0
  252. usersim/engine/core/llm.py +710 -0
  253. usersim/engine/core/locale.py +512 -0
  254. usersim/engine/core/localized.py +172 -0
  255. usersim/engine/core/manifest.py +998 -0
  256. usersim/engine/core/messages.py +93 -0
  257. usersim/engine/core/missing.py +38 -0
  258. usersim/engine/core/outcomes.py +442 -0
  259. usersim/engine/core/persona.py +178 -0
  260. usersim/engine/core/pressure_bank.py +629 -0
  261. usersim/engine/core/preview.py +1927 -0
  262. usersim/engine/core/probes.py +1499 -0
  263. usersim/engine/core/probing_taxonomy.py +462 -0
  264. usersim/engine/core/prompt_loader.py +93 -0
  265. usersim/engine/core/prompts.py +81 -0
  266. usersim/engine/core/provenance.py +118 -0
  267. usersim/engine/core/query_bank.py +567 -0
  268. usersim/engine/core/realized_audit.py +411 -0
  269. usersim/engine/core/row_metadata.py +35 -0
  270. usersim/engine/core/seeds.py +82 -0
  271. usersim/engine/core/simulation.py +1899 -0
  272. usersim/engine/core/storage.py +1407 -0
  273. usersim/engine/core/tool_calls.py +106 -0
  274. usersim/engine/core/translation.py +266 -0
  275. usersim/engine/core/user_turn_policy.py +80 -0
  276. usersim/engine/evaluator/__init__.py +19 -0
  277. usersim/engine/evaluator/axes.py +437 -0
  278. usersim/engine/evaluator/config.py +187 -0
  279. usersim/engine/evaluator/generator.py +424 -0
  280. usersim/engine/evaluator/judges.py +151 -0
  281. usersim/engine/evaluator/prompts.py +108 -0
  282. usersim/engine/evaluator/scorers/__init__.py +289 -0
  283. usersim/engine/evaluator/scorers/financial_services.py +635 -0
  284. usersim/engine/evaluator/scorers/health_disclosure.py +503 -0
  285. usersim/engine/evaluator/scorers/identity_disclosure.py +545 -0
  286. usersim/engine/evaluator/scorers/identity_grading.py +543 -0
  287. usersim/engine/evaluator/scorers/language_compliance.py +426 -0
  288. usersim/engine/evaluator/scorers/refusal_basics.py +479 -0
  289. usersim/engine/evaluator/scorers/response_shape.py +363 -0
  290. usersim/engine/evaluator/scorers/safety_agentic.py +1010 -0
  291. usersim/engine/evaluator/scorers/safety_chat_pressure.py +791 -0
  292. usersim/engine/evaluator/scorers/sov_ai_dynamic.py +629 -0
  293. usersim/engine/evaluator/scorers/sov_ai_facts.py +648 -0
  294. usersim/engine/evaluator/scorers/sov_ai_multilingual_parity.py +550 -0
  295. usersim/engine/evaluator/scorers/tool_use.py +291 -0
  296. usersim/engine/external.py +218 -0
  297. usersim/engine/generator.py +419 -0
  298. usersim/engine/plugin.py +34 -0
  299. usersim/engine/probes/__init__.py +28 -0
  300. usersim/engine/probes/financial_services/__init__.py +16 -0
  301. usersim/engine/probes/financial_services/generator.py +1329 -0
  302. usersim/engine/probes/financial_services/prompts.py +132 -0
  303. usersim/engine/probes/financial_services/retrieval.py +229 -0
  304. usersim/engine/probes/financial_services/task_derivation.py +274 -0
  305. usersim/engine/probes/financial_services/tools.py +116 -0
  306. usersim/engine/probes/general_educational/__init__.py +4 -0
  307. usersim/engine/probes/general_educational/generator.py +125 -0
  308. usersim/engine/probes/general_educational/prompts.py +207 -0
  309. usersim/engine/probes/general_open_ended/__init__.py +4 -0
  310. usersim/engine/probes/general_open_ended/generator.py +127 -0
  311. usersim/engine/probes/general_open_ended/prompts.py +209 -0
  312. usersim/engine/probes/health_disclosure/__init__.py +28 -0
  313. usersim/engine/probes/health_disclosure/base.py +148 -0
  314. usersim/engine/probes/health_disclosure/clients.py +291 -0
  315. usersim/engine/probes/health_disclosure/decision_support.py +44 -0
  316. usersim/engine/probes/health_disclosure/general.py +45 -0
  317. usersim/engine/probes/health_disclosure/mixin.py +363 -0
  318. usersim/engine/probes/health_disclosure/move_runtime.py +486 -0
  319. usersim/engine/probes/health_disclosure/moves.py +241 -0
  320. usersim/engine/probes/health_disclosure/prompts.py +324 -0
  321. usersim/engine/probes/health_disclosure/therapy.py +43 -0
  322. usersim/engine/probes/health_disclosure/triage.py +43 -0
  323. usersim/engine/probes/identity_disclosure/__init__.py +4 -0
  324. usersim/engine/probes/identity_disclosure/generator.py +504 -0
  325. usersim/engine/probes/identity_disclosure/prompts.py +219 -0
  326. usersim/engine/probes/identity_disclosure/task_derivation.py +227 -0
  327. usersim/engine/probes/safety_agentic/__init__.py +24 -0
  328. usersim/engine/probes/safety_agentic/generator.py +666 -0
  329. usersim/engine/probes/safety_agentic/prompts.py +24 -0
  330. usersim/engine/probes/safety_agentic/task_derivation.py +109 -0
  331. usersim/engine/probes/safety_chat_pressure/__init__.py +24 -0
  332. usersim/engine/probes/safety_chat_pressure/classifier.py +113 -0
  333. usersim/engine/probes/safety_chat_pressure/generator.py +551 -0
  334. usersim/engine/probes/safety_chat_pressure/prompts.py +141 -0
  335. usersim/engine/probes/safety_chat_pressure/task_derivation.py +171 -0
  336. usersim/engine/probes/sov_ai_dynamic/__init__.py +28 -0
  337. usersim/engine/probes/sov_ai_dynamic/generator.py +393 -0
  338. usersim/engine/probes/sov_ai_dynamic/prompts.py +472 -0
  339. usersim/engine/probes/sov_ai_dynamic/task_derivation.py +106 -0
  340. usersim/engine/probes/sov_ai_facts/__init__.py +15 -0
  341. usersim/engine/probes/sov_ai_facts/generator.py +342 -0
  342. usersim/engine/probes/sov_ai_facts/prompts.py +714 -0
  343. usersim/engine/probes/sov_ai_facts/task_derivation.py +479 -0
  344. usersim/engine/probes/sov_ai_multilingual_parity/__init__.py +19 -0
  345. usersim/engine/probes/sov_ai_multilingual_parity/generator.py +379 -0
  346. usersim/engine/probes/sov_ai_multilingual_parity/prompts.py +456 -0
  347. usersim/engine/probes/sov_ai_multilingual_parity/task_derivation.py +104 -0
  348. usersim/engine/probes/tool_calling/__init__.py +9 -0
  349. usersim/engine/probes/tool_calling/generator.py +437 -0
  350. usersim/engine/probes/tool_calling/prompts.py +221 -0
  351. usersim/engine/probes/tool_calling/verifiers.py +165 -0
  352. usersim/py.typed +0 -0
  353. usersim/reporting/__init__.py +116 -0
  354. usersim/reporting/_reasoning.py +201 -0
  355. usersim/reporting/capability_report.py +2049 -0
  356. usersim/reporting/comparison.py +797 -0
  357. usersim/reporting/comparison_dashboard.py +2938 -0
  358. usersim/reporting/dashboard.py +1731 -0
  359. usersim/reporting/diagnostics.py +435 -0
  360. usersim/reporting/eval_manifest.py +291 -0
  361. usersim/reporting/identity.py +82 -0
  362. usersim/reporting/resource.py +476 -0
  363. usersim/reporting/runs.py +282 -0
  364. usersim/reporting/sim_health.py +334 -0
  365. usersim/selection/__init__.py +87 -0
  366. usersim/selection/engine.py +423 -0
  367. usersim/selection/io.py +391 -0
  368. usersim/selection/profiles.py +249 -0
  369. usersim/selection/schemas.py +194 -0
  370. usersim/taxonomy/__init__.py +38 -0
  371. usersim/taxonomy/capabilities.py +1125 -0
  372. usersim/taxonomy/eval_cell.py +131 -0
  373. usersim/testing/__init__.py +534 -0
  374. usersim-0.2.0.dist-info/METADATA +392 -0
  375. usersim-0.2.0.dist-info/RECORD +379 -0
  376. usersim-0.2.0.dist-info/WHEEL +5 -0
  377. usersim-0.2.0.dist-info/entry_points.txt +6 -0
  378. usersim-0.2.0.dist-info/licenses/LICENSE +204 -0
  379. 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
+ }