From d736645ed855bff93759a159279014e6e3b772ff Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Thu, 29 Oct 2026 18:05:14 -0400
Subject: [PATCH 1/3] feat(engine): declare the locale pre-flight on the probe
 class

A probe whose banks are split by locale sets locale_bank_check on its class, and the run pre-flight loads the bank each run locale runs on, named by the bank_locale classmethod, before any model call. authoring_guide is the link a refusal gives for building a bank in another locale, and the feature-request link appears for probes that ship with User Sim.

financial_services, sov_ai_facts and sov_ai_dynamic declare theirs, and the pre-flight in cli/_pipeline.py names no probe. assert_probe_conforms checks the three declarations, and the extension fixture exercises them from an installed package.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/assets.md                        |  23 ++--
 architecture/probes.md                        |   9 +-
 docs/engine/AUTHORING_A_PROBE.md              |  28 +++++
 docs/extensions.md                            |  18 ++-
 src/usersim/cli/_pipeline.py                  | 107 +++++-------------
 src/usersim/engine/core/probes.py             |  23 +++-
 .../probes/financial_services/generator.py    |  14 +++
 .../engine/probes/sov_ai_dynamic/generator.py |   7 ++
 .../engine/probes/sov_ai_facts/generator.py   |   7 ++
 src/usersim/testing/__init__.py               |  16 +++
 templates/probe/README.md                     |   5 +-
 templates/probe/generator_bank_verbatim.py    |  11 ++
 tests/engine/test_conformance_suite.py        |  35 ++++++
 .../usersim_extension_fixture/probe.py        |   7 ++
 .../extension_package/verify_seams.py         |  22 ++++
 tests/test_packaging_contract.py              |  66 ++++++++++-
 16 files changed, 295 insertions(+), 103 deletions(-)

diff --git a/architecture/assets.md b/architecture/assets.md
index 51be88d..707de13 100644
--- a/architecture/assets.md
+++ b/architecture/assets.md
@@ -45,17 +45,18 @@ checkout.
 ## Pre-flight
 
 Before any model call, a run verifies that every selected probe's assets
-exist, including the locale subtree for the locale-scoped probes:
-`financial_services`, `sov_ai_facts` and `sov_ai_dynamic`. A locale that runs
-on another locale's bank is checked against that bank, the one the probe loads
-in its place: a registered India variant with no subtree of its own runs on
-`en_IN`'s. For `financial_services` a subtree counts once it has tasks, and
-`hi_Deva_IN` and `hi_Latn_IN` run on `en_IN`'s until theirs does. Every
-missing path is reported at once, with what to do: drop the probe or the
-locale from the run, or point `--assets-dir` somewhere else. When a probe
-can't run one of the run's locales, the refusal also names the locales it can
-run and links the feature-request form, and for `financial_services` the guide
-to authoring a bank.
+exist. A probe whose banks are split by locale declares a `locale_bank_check`
+on its class, and the run loads the bank each run locale runs on with it:
+`financial_services`, `sov_ai_facts` and `sov_ai_dynamic` declare one. The
+class's `bank_locale` names that bank, the one the probe loads in the locale's
+place when it has none of its own: a registered India variant with no subtree
+of its own runs on `en_IN`'s. For `financial_services` a subtree counts once it
+has tasks, and `hi_Deva_IN` and `hi_Latn_IN` run on `en_IN`'s until theirs
+does. Every missing path is reported at once, with what to do: drop the probe
+or the locale from the run, or point `--assets-dir` somewhere else. When a
+probe can't run one of the run's locales, the refusal also names the locales it
+can run and the guide the class's `authoring_guide` links, if any, and for a
+probe that ships with User Sim, the feature-request form.
 
 Without this, a missing bank surfaces from inside a loader partway through a
 run, after the other probes in the mix have already been paid for, while
diff --git a/architecture/probes.md b/architecture/probes.md
index 902b9e8..c9d5ec4 100644
--- a/architecture/probes.md
+++ b/architecture/probes.md
@@ -111,7 +111,8 @@ A probe's content lives at `engine/assets/<label>/`, resolved through
 `probe_assets_dir()`. A run fails pre-flight, before any model call, if a
 selected probe's bank is missing or, for the probes whose banks are split by
 locale, doesn't load for a run locale (a finance bank without tasks, for
-instance). The refusal names the probe, the locale and the locales that can
-run, rather than failing from inside a loader mid-run. `simulate` and its
-`--dry-run`, `--materialize-inputs`, `--inputs` and notebook 01 all run the
-check. See [assets.md](assets.md).
+instance). Those probes declare a `locale_bank_check` on the class, which the
+pre-flight calls on the bank the class's `bank_locale` names. The refusal names
+the probe, the locale and the locales that can run, rather than failing from
+inside a loader mid-run. `simulate` and its `--dry-run`, `--materialize-inputs`,
+`--inputs` and notebook 01 all run the check. See [assets.md](assets.md).
diff --git a/docs/engine/AUTHORING_A_PROBE.md b/docs/engine/AUTHORING_A_PROBE.md
index 35fa758..0c6af91 100644
--- a/docs/engine/AUTHORING_A_PROBE.md
+++ b/docs/engine/AUTHORING_A_PROBE.md
@@ -302,6 +302,34 @@ or `None` if nothing matched. The substrate:
 Your probe then reads `self._task` from the prompt-formatting hooks
 and from `should_succeed` / `build_result_extras`.
 
+### Check each locale's bank before a run
+
+Before any model call, a run checks that each selected probe's asset folder
+exists and holds bank files. A probe whose banks are split by locale also sets
+`locale_bank_check`, and the run then loads the bank each run locale runs on
+and refuses a locale whose bank is missing or does not load:
+
+```python
+def _check_locale_bank(locale_dir: Path) -> None:
+    MyBank.from_yaml((locale_dir / "sample.yaml").read_text(encoding="utf-8"))
+
+
+class MyProbe(BankVerbatimMixin, BankBackedProbe):
+    locale_bank_check = staticmethod(_check_locale_bank)
+    authoring_guide = "https://example.com/my-probe/README.md#adding-a-locale"
+```
+
+- **`locale_bank_check`** takes one locale's folder, `<asset folder>/<locale>/`,
+  and raises whatever would stop the bank loader. The refusal quotes the error.
+- **`bank_locale(locale, probe_dir)`**, a classmethod, names the locale whose
+  bank a row in `locale` runs on, as the bank loader picks it. By default, an
+  India language variant runs on its own bank when it has one and on `en_IN`'s
+  otherwise; any other locale runs on its own. `financial_services` overrides
+  it, since its bank for a locale counts only once it has tasks.
+- **`authoring_guide`** is an `https://` link to how to build the probe's bank
+  for another locale. The refusal links it when a run asks for a locale the
+  probe has no bank for.
+
 ---
 
 ## Step 4: write your `LocalePromptPack`
diff --git a/docs/extensions.md b/docs/extensions.md
index 6af877b..9f51b21 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -113,11 +113,14 @@ class RecipeBank:
     recipes: tuple[Recipe, ...]
 
 
+def read_recipe_bank(locale_dir: Path) -> RecipeBank:
+    doc = yaml.safe_load((locale_dir / "recipes.yaml").read_text(encoding="utf-8"))
+    return RecipeBank(doc["bank_id"], doc["bank_version"], tuple(Recipe(**r) for r in doc["recipes"]))
+
+
 @cache
 def load_recipe_bank(locale: str) -> RecipeBank:
-    path = RecipeProbe.assets_dir() / locale / "recipes.yaml"
-    doc = yaml.safe_load(path.read_text(encoding="utf-8"))
-    return RecipeBank(doc["bank_id"], doc["bank_version"], tuple(Recipe(**r) for r in doc["recipes"]))
+    return read_recipe_bank(RecipeProbe.assets_dir() / locale)
 
 
 @register_probe(family="acme_recipes", prompt_version="v1.0", variants=("default",))
@@ -125,6 +128,7 @@ class RecipeProbe(BankBackedProbe):
     label = "acme_recipes"
     assets_root = Path(__file__).parent / "assets"
     bank_loader = staticmethod(load_recipe_bank)
+    locale_bank_check = staticmethod(read_recipe_bank)
     placeholder_warning_kind = "acme_used_placeholder_recipe"
     output_columns = ("acme_recipe_id",)
 
@@ -147,6 +151,8 @@ class RecipeProbe(BankBackedProbe):
 - **`load_recipe_bank`** reads under `RecipeProbe.assets_dir()`, the probe's
   folder on the asset search path, so a folder `--assets-dir` or
   `USERSIM_ASSET_PATH` names reaches it too.
+- **`locale_bank_check`** reads one locale's bank, so a run in a locale with no
+  bank that loads stops before any model call rather than failing every row.
 - **`placeholder_warning_kind`** is the warning a row records when its recipe
   is marked `placeholder: true`. Its `<prefix>_used_placeholder_<thing>` form is
   what the capability report counts as placeholder content.
@@ -272,5 +278,7 @@ usersim simulate --locale en_US --num-rows 5 \
   --probe-mix "acme_recipes=1.0" --out output/trajectories
 ```
 
-`--assets-dir` pins every probe in a run to the folder it names, this one
-included, so a run that passes it needs `acme_recipes/` there too.
+The package has a bank for `en_US` only, so a run with `--locale fr_FR` stops
+before any model call and says the probe has no bank for it. `--assets-dir`
+pins every probe in a run to the folder it names, this one included, so a run
+that passes it needs `acme_recipes/` there too.
diff --git a/src/usersim/cli/_pipeline.py b/src/usersim/cli/_pipeline.py
index 65ba7aa..f276116 100644
--- a/src/usersim/cli/_pipeline.py
+++ b/src/usersim/cli/_pipeline.py
@@ -34,7 +34,7 @@
 from copy import deepcopy
 from pathlib import Path
 from types import SimpleNamespace
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from usersim.cli._errors import ConfigError
 from usersim.cli._models import (
@@ -49,6 +49,9 @@
 )
 from usersim.engine.evaluator.prompts import EVAL_PROMPT_VERSION
 
+if TYPE_CHECKING:
+    from usersim.engine.core.probes import BaseProbe
+
 logger = logging.getLogger("usersim.cli.pipeline")
 
 DEFAULT_TOOL_CALLING_THEMES: tuple[str, ...] = (
@@ -185,65 +188,9 @@ def resolve_toolset_seed_path(
     return present[0] if present else None
 
 
-def _load_finance_locale(locale_dir: Path) -> None:
-    from usersim.engine.core.finance_bank import load_finance_bank
-
-    load_finance_bank(locale_dir)
-
-
-def _load_facts_locale(locale_dir: Path) -> None:
-    from usersim.engine.core.fact_bank import load_fact_bank
-
-    load_fact_bank(locale_dir / "sample.yaml")
-
-
-def _load_dynamic_locale(locale_dir: Path) -> None:
-    from usersim.engine.core.probing_taxonomy import load_probing_taxonomy
-
-    load_probing_taxonomy(locale_dir / "categories.yaml")
-
-
-#: Probe asset trees that are partitioned by locale rather than flat, with the
-#: loader for one locale's subtree. The subtree existing is not enough: a finance
-#: bank without tasks aborts every row once the run is already going, so the
-#: pre-flight loads it.
-_LOCALE_SCOPED_PROBES: dict[str, Callable[[Path], None]] = {
-    "financial_services": _load_finance_locale,
-    "sov_ai_dynamic": _load_dynamic_locale,
-    "sov_ai_facts": _load_facts_locale,
-}
-
-
-def _finance_bank_locale(probe_dir: Path, locale: str) -> str:
-    from usersim.engine.core.finance_bank import finance_bank_locale, has_finance_tasks
-
-    return finance_bank_locale(locale, has_tasks=lambda loc: has_finance_tasks(probe_dir / loc))
-
-
-def _own_or_base_bank_locale(probe_dir: Path, locale: str) -> str:
-    from usersim.engine.core.locale import asset_locale
-
-    return asset_locale(locale, exists=lambda loc: (probe_dir / loc).is_dir())
-
-
-#: Which locale's bank a row in a locale runs on, resolved as the probe and its
-#: scorer resolve it. A probe not listed uses an India variant's own bank when
-#: it has one, and its base locale's otherwise.
-_BANK_LOCALE: dict[str, Callable[[Path, str], str]] = {
-    "financial_services": _finance_bank_locale,
-}
-
-#: Where to ask for a probe in a locale it has no bank for.
+#: Where to ask for a locale of a probe that ships with User Sim.
 _FEATURE_REQUEST_URL = "https://github.com/NVIDIA-NeMo/UserSim/issues/new?template=feature-request.yml"
 
-#: How to build a probe's bank for another locale, for the probes that document it.
-_BANK_AUTHORING_GUIDES: dict[str, str] = {
-    "financial_services": (
-        "https://github.com/NVIDIA-NeMo/UserSim/blob/main/"
-        "src/usersim/engine/probes/financial_services/README.md#authoring-a-new-locale"
-    ),
-}
-
 
 def verify_probe_assets(
     probe_mix: dict[str, float],
@@ -273,10 +220,11 @@ def verify_probe_locales(
     against every locale would refuse pairs the rows never ask for.
     """
     from usersim.engine.core._assets import probe_assets_dir
+    from usersim.engine.core.probes import resolve_probe
 
     root = Path(assets_dir) if assets_dir is not None else None
     problems: list[str] = []
-    probes_missing_a_locale: list[str] = []
+    probes_missing_a_locale: list[type[BaseProbe]] = []
 
     for probe in sorted(probe_locales):
         probe_dir = probe_assets_dir(probe, assets_root=root)
@@ -286,13 +234,13 @@ def verify_probe_locales(
         if not any(probe_dir.rglob("*.yaml")) and not any(probe_dir.rglob("*.json")):
             problems.append(f"{probe}: {probe_dir} contains no bank files")
             continue
-        load = _LOCALE_SCOPED_PROBES.get(probe)
-        if load is None:
+        cls = resolve_probe(probe)
+        if cls.locale_bank_check is None:
             continue
-        locale_problems = _locale_bank_problems(probe, probe_dir, probe_locales[probe], load)
+        locale_problems = _locale_bank_problems(cls, probe_dir, probe_locales[probe])
         problems.extend(locale_problems)
         if locale_problems:
-            probes_missing_a_locale.append(probe)
+            probes_missing_a_locale.append(cls)
 
     if problems:
         raise ConfigError(
@@ -303,35 +251,36 @@ def verify_probe_locales(
         )
 
 
-def _remedies(probes_missing_a_locale: Sequence[str]) -> list[str]:
+def _remedies(probes_missing_a_locale: Sequence[type[BaseProbe]]) -> list[str]:
     """What to do about a refusal, with links when a probe can't run one of the run's locales."""
+    from usersim.engine.core.probes import BUILTIN_PROBE_MODULES
+
     remedies = [
         "Drop the probe from --probe-mix or the locale from the run, or point --assets-dir at a tree that has them."
     ]
-    if probes_missing_a_locale:
+    if any(cls.__module__ in BUILTIN_PROBE_MODULES for cls in probes_missing_a_locale):
         remedies.append(f"To ask for a locale, open a feature request: {_FEATURE_REQUEST_URL}")
     remedies.extend(
-        f"To build a {probe} bank yourself, see {_BANK_AUTHORING_GUIDES[probe]}"
-        for probe in probes_missing_a_locale
-        if probe in _BANK_AUTHORING_GUIDES
+        f"To build a {cls.label} bank yourself, see {cls.authoring_guide}"
+        for cls in probes_missing_a_locale
+        if cls.authoring_guide
     )
     return remedies
 
 
-def _locale_bank_problems(
-    probe: str,
-    probe_dir: Path,
-    locales: Sequence[str],
-    load: Callable[[Path], None],
-) -> list[str]:
-    """The locales ``probe`` can't run in, as one line naming those that can."""
-    resolve = _BANK_LOCALE.get(probe, _own_or_base_bank_locale)
+def _locale_bank_problems(cls: type[BaseProbe], probe_dir: Path, locales: Sequence[str]) -> list[str]:
+    """The locales ``cls`` can't run in, as one line naming those that can."""
+    probe = cls.label
+    check = cls.locale_bank_check
     errors: dict[Path, str | None] = {}
 
+    def resolve(loc: str) -> str:
+        return cls.bank_locale(loc, probe_dir)
+
     def load_error(locale_dir: Path) -> str | None:
         if locale_dir not in errors:
             try:
-                load(locale_dir)
+                check(locale_dir)
                 errors[locale_dir] = None
             except Exception as exc:  # whatever stops the loader stops every row
                 errors[locale_dir] = f"{type(exc).__name__}: {exc}"
@@ -343,7 +292,7 @@ def has_bank(loc: str) -> bool:
     failures: list[str] = []
     for loc in dict.fromkeys(locales):
         # A locale without a bank of its own may run on its base locale's.
-        bank_locale = resolve(probe_dir, loc)
+        bank_locale = resolve(loc)
         via = "" if bank_locale == loc else f" (through {bank_locale})"
         if not has_bank(bank_locale):
             failures.append(f"{loc}{via}: no bank")
@@ -352,7 +301,7 @@ def has_bank(loc: str) -> bool:
     if not failures:
         return []
     runnable = sorted(d.name for d in probe_dir.iterdir() if d.is_dir() and load_error(d) is None)
-    can_run = _runnable_locales(runnable, lambda loc: resolve(probe_dir, loc))
+    can_run = _runnable_locales(runnable, resolve)
     return [f"{probe} can't run {'; '.join(failures)}. Locales that can run: {can_run}"]
 
 
diff --git a/src/usersim/engine/core/probes.py b/src/usersim/engine/core/probes.py
index 5b08bb6..a6df21c 100644
--- a/src/usersim/engine/core/probes.py
+++ b/src/usersim/engine/core/probes.py
@@ -57,7 +57,7 @@
 )
 
 from usersim.engine.core.columns import output_columns_problem
-from usersim.engine.core.locale import india_variant
+from usersim.engine.core.locale import asset_locale, india_variant
 from usersim.engine.core.outcomes import (
     OutcomeBuilder,
     Provenance,
@@ -278,6 +278,27 @@ def assets_dir(cls) -> Path:
 
         return probe_assets_dir(cls.label)
 
+    # Loads one locale's bank from its folder, ``<asset folder>/<locale>/``,
+    # and raises when no row could run on it. A probe whose banks are split by
+    # locale sets it, and a run's pre-flight then loads the bank each run
+    # locale resolves to (``bank_locale``) before any model call. ``None``
+    # checks only that the probe's asset folder holds bank files.
+    locale_bank_check: Callable[[Path], object] | None = None
+
+    # Where to read how to build this probe's bank for another locale. The
+    # pre-flight links it when a run asks for a locale the probe has no bank for.
+    authoring_guide: str | None = None
+
+    @classmethod
+    def bank_locale(cls, locale: str, probe_dir: Path) -> str:
+        """The locale whose bank in ``probe_dir`` a row in ``locale`` runs on.
+
+        The pre-flight resolves it as the probe's bank loader does. By default,
+        an India language variant runs on its own bank when ``probe_dir`` holds
+        one and on its base locale's otherwise; any other locale runs on its own.
+        """
+        return asset_locale(locale, exists=lambda loc: (probe_dir / loc).is_dir())
+
     # The top-level columns ``build_result_extras`` adds beyond the core ones
     # (``CORE_RESULT_COLUMNS``). A run keeps the core columns plus the union of
     # every registered probe's ``output_columns`` and drops any other key, so
diff --git a/src/usersim/engine/probes/financial_services/generator.py b/src/usersim/engine/probes/financial_services/generator.py
index 6a4e3a7..b612a64 100644
--- a/src/usersim/engine/probes/financial_services/generator.py
+++ b/src/usersim/engine/probes/financial_services/generator.py
@@ -34,6 +34,7 @@
 import json
 import logging
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, Sequence
 
 from usersim.engine.core.behavioral import (
@@ -46,6 +47,8 @@
     DEFAULT_IDENTITY_REQUIRED_FIELDS,
     FinanceBank,
     finance_bank_locale,
+    has_finance_tasks,
+    load_finance_bank,
     load_finance_bank_for_locale,
     reset_finance_bank_cache,
 )
@@ -338,6 +341,12 @@ class FinancialServicesProbe(ToolExecutionMixin, BankBackedProbe):
     bank_loader = staticmethod(_bank_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_FINANCE
     bank_version_key = None  # per-locale
+    # A bank without tasks aborts every row, so the pre-flight loads it.
+    locale_bank_check = staticmethod(load_finance_bank)
+    authoring_guide = (
+        "https://github.com/NVIDIA-NeMo/UserSim/blob/main/"
+        "src/usersim/engine/probes/financial_services/README.md#authoring-a-new-locale"
+    )
     # Agentic shape: re-offer tools until the assistant stops (search -> read
     # -> act -> confirm), capped per turn by ToolExecutionMixin.
     tool_loop_mode = "multi"
@@ -383,6 +392,11 @@ def __init__(self, **kwargs: Any) -> None:
 
     # ── BankBackedProbe API ─────────────────────────────────────────
 
+    @classmethod
+    def bank_locale(cls, locale: str, probe_dir: Path) -> str:
+        """The locale :func:`finance_bank_locale` picks for ``locale`` among the banks in ``probe_dir``."""
+        return finance_bank_locale(locale, has_tasks=lambda loc: has_finance_tasks(probe_dir / loc))
+
     def _load_bank_for_locale(self, locale: str) -> FinanceBank:
         """Load the bank :func:`finance_bank_locale` picks for ``locale``, which the scorer reads too.
 
diff --git a/src/usersim/engine/probes/sov_ai_dynamic/generator.py b/src/usersim/engine/probes/sov_ai_dynamic/generator.py
index 6337806..0ca01f6 100644
--- a/src/usersim/engine/probes/sov_ai_dynamic/generator.py
+++ b/src/usersim/engine/probes/sov_ai_dynamic/generator.py
@@ -51,6 +51,7 @@
 
 import logging
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.behavioral import get_conversation_language
@@ -63,6 +64,7 @@
 )
 from usersim.engine.core.probing_taxonomy import (
     Category,
+    load_probing_taxonomy,
     load_probing_taxonomy_for_locale,
     reset_probing_taxonomy_cache,
 )
@@ -111,6 +113,10 @@ def _bank_loader(locale: str):
     return _load_taxonomy_for_locale(locale)
 
 
+def _check_locale_bank(locale_dir: Path) -> None:
+    load_probing_taxonomy(locale_dir / "categories.yaml")
+
+
 def should_succeed(state: ConversationState) -> bool:
     """Sim-side guardrail: did we actually probe a category?
 
@@ -178,6 +184,7 @@ class SovAiDynamicProbe(BankBackedProbe):
     bank_loader = staticmethod(_bank_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_TAXONOMY
     bank_version_key = None  # locale-keyed (the inclusion convention)
+    locale_bank_check = staticmethod(_check_locale_bank)
 
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
diff --git a/src/usersim/engine/probes/sov_ai_facts/generator.py b/src/usersim/engine/probes/sov_ai_facts/generator.py
index e04e83e..6579b4c 100644
--- a/src/usersim/engine/probes/sov_ai_facts/generator.py
+++ b/src/usersim/engine/probes/sov_ai_facts/generator.py
@@ -48,10 +48,12 @@
 from __future__ import annotations
 
 import logging
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.fact_bank import (
     Fact,
+    load_fact_bank,
     load_fact_bank_for_locale,
     reset_fact_bank_cache,
 )
@@ -117,6 +119,10 @@ def _bank_loader(locale: str):
     return _load_bank_for_locale(locale)
 
 
+def _check_locale_bank(locale_dir: Path) -> None:
+    load_fact_bank(locale_dir / "sample.yaml")
+
+
 def should_succeed(state: ConversationState) -> bool:
     """Sim-side guardrail: did we actually probe a fact?
 
@@ -160,6 +166,7 @@ class SovAiFactsProbe(BankVerbatimMixin, BankBackedProbe):
     bank_loader = staticmethod(_bank_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_FACT
     bank_version_key = None  # locale-keyed (the inclusion convention)
+    locale_bank_check = staticmethod(_check_locale_bank)
 
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
diff --git a/src/usersim/testing/__init__.py b/src/usersim/testing/__init__.py
index 6cb7e8a..908cae7 100644
--- a/src/usersim/testing/__init__.py
+++ b/src/usersim/testing/__init__.py
@@ -184,6 +184,22 @@ def probe_conformance_problems(probe: str | type) -> list[str]:
         if kind_problem:
             problems.append(f"{cls.__qualname__}.placeholder_warning_kind {kind_problem}")
 
+    # The pre-flight reads these on the class, before any row runs.
+    check = getattr(cls, "locale_bank_check", None)
+    if check is not None and not callable(check):
+        problems.append(
+            f"{cls.__qualname__}.locale_bank_check must be None or a function that loads one "
+            f"locale's bank folder; got {check!r}"
+        )
+    if not isinstance(inspect.getattr_static(cls, "bank_locale", None), classmethod):
+        problems.append(f"{cls.__qualname__}.bank_locale must be a classmethod; the pre-flight calls it on the class.")
+    guide = getattr(cls, "authoring_guide", None)
+    if guide is not None and not (isinstance(guide, str) and guide.startswith("https://")):
+        problems.append(
+            f"{cls.__qualname__}.authoring_guide must be None or an https:// URL, which works from an "
+            f"installed package; got {guide!r}"
+        )
+
     for klass, key in _reserved_metadata_writes(cls):
         problems.append(
             f"{klass} writes state.metadata[{key!r}], which the conversation loop owns. "
diff --git a/templates/probe/README.md b/templates/probe/README.md
index b96a7f1..be5e522 100644
--- a/templates/probe/README.md
+++ b/templates/probe/README.md
@@ -121,7 +121,10 @@ When porting one of the templates into a new module:
 - [ ] Wire the asset bank (if applicable): set `bank_loader`,
       `placeholder_warning_kind` (a `WarningKind.USED_PLACEHOLDER_*`
       member), `bank_version_key`. See
-      `core/probes.py::BankBackedProbe` for the contract.
+      `core/probes.py::BankBackedProbe` for the contract. A bank split
+      by locale also sets `locale_bank_check`, so a run refuses a locale
+      whose bank is missing before any model call (step 3 of
+      `docs/engine/AUTHORING_A_PROBE.md`).
 - [ ] Keep the probe's own per-row data under metadata keys of its own.
       The loop writes the keys in `RESERVED_METADATA_KEYS`
       (`core/simulation.py`); a probe reads them, and
diff --git a/templates/probe/generator_bank_verbatim.py b/templates/probe/generator_bank_verbatim.py
index aec3093..6e49420 100644
--- a/templates/probe/generator_bank_verbatim.py
+++ b/templates/probe/generator_bank_verbatim.py
@@ -46,6 +46,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from usersim.engine.core.outcomes import WarningKind
@@ -80,6 +81,15 @@ def _demo_bank_loader(locale: str = "en_US"):
     raise NotImplementedError("replace with your real bank loader")
 
 
+def _demo_locale_bank_check(locale_dir: Path) -> None:
+    """Stub check: load the bank in ``locale_dir``, one locale's folder.
+
+    A run's pre-flight calls it for each run locale before any model
+    call; whatever it raises refuses that locale.
+    """
+    raise NotImplementedError("replace with a load of one locale's bank")
+
+
 @register_probe(
     family="demo_bank_verbatim",
     prompt_version="v1.0",
@@ -97,6 +107,7 @@ class DemoBankVerbatimProbe(BankVerbatimMixin, BankBackedProbe):
     bank_loader = staticmethod(_demo_bank_loader)
     placeholder_warning_kind = WarningKind.USED_PLACEHOLDER_FACT
     bank_version_key: str | None = None  # locale-keyed (inclusion convention)
+    locale_bank_check = staticmethod(_demo_locale_bank_check)
 
     def derive_task(
         self,
diff --git a/tests/engine/test_conformance_suite.py b/tests/engine/test_conformance_suite.py
index 20251b2..52ffb7a 100644
--- a/tests/engine/test_conformance_suite.py
+++ b/tests/engine/test_conformance_suite.py
@@ -179,6 +179,41 @@ class Mislabelled(BaseProbe):
             problems
         )
 
+    @pytest.mark.parametrize(
+        ("attributes", "expected"),
+        [
+            ({"locale_bank_check": "sample.yaml"}, "PreflightProbe.locale_bank_check must be None or a function"),
+            (
+                {"bank_locale": lambda self, locale, probe_dir: locale},
+                "PreflightProbe.bank_locale must be a classmethod",
+            ),
+            (
+                {"authoring_guide": "README.md#locales"},
+                "PreflightProbe.authoring_guide must be None or an https:// URL",
+            ),
+        ],
+        ids=["check-not-callable", "bank-locale-not-a-classmethod", "relative-guide"],
+    )
+    async def test_unusable_preflight_declarations_are_reported(self, attributes, expected) -> None:
+        """The pre-flight reads these on the class before any row runs, so a wrong one fails the whole run."""
+        cls = type("PreflightProbe", (BaseProbe,), {"label": "preflight_probe", **attributes})
+
+        problems = probe_conformance_problems(cls)
+        assert any(expected in p for p in problems), problems
+
+    async def test_usable_preflight_declarations_are_accepted(self) -> None:
+        class Declared(BaseProbe):
+            label = "declared_probe"
+            locale_bank_check = staticmethod(lambda locale_dir: None)
+            authoring_guide = "https://example.com/declared-probe/locales"
+
+            @classmethod
+            def bank_locale(cls, locale, probe_dir):
+                return locale
+
+        declarations = ("locale_bank_check", "bank_locale", "authoring_guide")
+        assert not [p for p in probe_conformance_problems(Declared) if any(d in p for d in declarations)]
+
     @pytest.mark.parametrize(
         ("probe", "key"), [(_WritesEarlyStop, "early_stop"), (_SeedsJudgeRatings, "user_judge_ratings")]
     )
diff --git a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
index 5376e9e..f305827 100644
--- a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
+++ b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
@@ -6,11 +6,18 @@
 from usersim.engine.core.probes import BaseProbe, register_probe
 
 
+def _check_locale_bank(locale_dir: Path) -> None:
+    if not (locale_dir / "sample.yaml").is_file():
+        raise FileNotFoundError(f"no sample.yaml in {locale_dir}")
+
+
 @register_probe(family="fixture", prompt_version="v1.0", variants=("default",))
 class FixtureProbe(BaseProbe):
     label = "fixture_probe"
     assets_root = Path(__file__).parent / "assets"
     output_columns = ("fixture_probe_marker",)
+    locale_bank_check = staticmethod(_check_locale_bank)
+    authoring_guide = "https://example.com/fixture-probe/locales"
 
     def get_user_system_prompt(self) -> str:
         return "You are a fixture user."
diff --git a/tests/fixtures/extension_package/verify_seams.py b/tests/fixtures/extension_package/verify_seams.py
index e59cc05..2abc8cf 100644
--- a/tests/fixtures/extension_package/verify_seams.py
+++ b/tests/fixtures/extension_package/verify_seams.py
@@ -100,6 +100,28 @@ def check(seam: str, condition: bool, detail: str = "") -> None:
 kept = ConversationSimulatorConfig(name="conversation_messages").side_effect_columns
 check("output_columns joins the run's columns", "fixture_probe_marker" in kept, f"saw {len(kept)} columns")
 
+# The pre-flight checks a contributed probe's locale banks with the check its
+# class declares, and a refusal links the probe's own authoring guide.
+from usersim.cli._errors import ConfigError  # noqa: E402
+from usersim.cli._pipeline import verify_probe_assets  # noqa: E402
+
+
+def preflight_refusal(locales: list[str]) -> str:
+    try:
+        verify_probe_assets({"fixture_probe": 1.0}, locales)
+    except ConfigError as error:
+        return str(error)
+    return ""
+
+
+check("pre-flight passes a locale with a bank", not preflight_refusal(["en_US"]), preflight_refusal(["en_US"]))
+refusal = preflight_refusal(["fr_FR"])
+check(
+    "pre-flight refuses a locale without one, linking the probe's guide",
+    "fixture_probe can't run fr_FR: no bank" in refusal and "https://example.com/fixture-probe/locales" in refusal,
+    refusal,
+)
+
 # The published conformance suite must pass for a real external probe.
 from usersim.testing import probe_conformance_problems  # noqa: E402
 
diff --git a/tests/test_packaging_contract.py b/tests/test_packaging_contract.py
index 72cfd35..1534776 100644
--- a/tests/test_packaging_contract.py
+++ b/tests/test_packaging_contract.py
@@ -380,16 +380,78 @@ def test_a_locale_without_a_bank_says_how_to_ask_for_one(self) -> None:
 
     def test_the_refusal_links_point_at_files_in_this_repository(self) -> None:
         """The links are absolute, to work from an installed package; moving a file must not break them quietly."""
-        from usersim.cli._pipeline import _BANK_AUTHORING_GUIDES, _FEATURE_REQUEST_URL
+        import usersim.engine.generator  # noqa: F401  (populates registry)
+        from usersim.cli._pipeline import _FEATURE_REQUEST_URL
+        from usersim.engine.core.probes import known_probes, resolve_probe
 
         template = _FEATURE_REQUEST_URL.split("?template=", 1)[1]
         assert (_REPO_ROOT / ".github" / "ISSUE_TEMPLATE" / template).is_file()
-        for url in _BANK_AUTHORING_GUIDES.values():
+        guides = [resolve_probe(p).authoring_guide for p in known_probes() if resolve_probe(p).authoring_guide]
+        assert guides, "no built-in probe links a guide, so this test checks nothing"
+        for url in guides:
             path, anchor = url.removeprefix("https://github.com/NVIDIA-NeMo/UserSim/blob/main/").split("#")
             lines = (_REPO_ROOT / path).read_text(encoding="utf-8").splitlines()
             headings = {line.lstrip("#").strip().lower().replace(" ", "-") for line in lines if line.startswith("#")}
             assert anchor in headings, f"{path} has no heading for #{anchor}"
 
+    @staticmethod
+    def _bank_check(locale_dir: Path) -> None:
+        if not (locale_dir / "bank.yaml").read_text(encoding="utf-8").strip():
+            raise ValueError("the bank is empty")
+
+    def test_a_probe_declares_its_locale_pre_flight(self, tmp_path: Path, register_test_probe) -> None:
+        """A probe from another package is checked by its own class, and its refusal links its own guide."""
+        from usersim.cli._errors import ConfigError
+        from usersim.cli._pipeline import verify_probe_assets
+
+        for locale, bank in (("en_US", "recipes: [curry]\n"), ("de_DE", "")):
+            (tmp_path / "ext_banks" / locale).mkdir(parents=True)
+            (tmp_path / "ext_banks" / locale / "bank.yaml").write_text(bank, encoding="utf-8")
+        register_test_probe(
+            "ext_banks",
+            assets_root=tmp_path,
+            locale_bank_check=staticmethod(self._bank_check),
+            authoring_guide="https://example.com/ext-banks/locales",
+        )
+
+        verify_probe_assets({"ext_banks": 1.0}, ["en_US"], None)
+        with pytest.raises(ConfigError) as exc:
+            verify_probe_assets({"ext_banks": 1.0}, ["de_DE", "fr_FR"], None)
+        problems, remedies = str(exc.value).split("\n\n", 1)
+        assert problems.splitlines()[1:] == [
+            "  - ext_banks can't run de_DE: its bank does not load (ValueError: the bank is empty); "
+            "fr_FR: no bank. Locales that can run: en_US"
+        ]
+        # A feature request here is for the probes that ship with User Sim.
+        assert remedies.splitlines() == [
+            "Drop the probe from --probe-mix or the locale from the run, or point --assets-dir at a tree that has them.",
+            "To build a ext_banks bank yourself, see https://example.com/ext-banks/locales",
+        ]
+
+    def test_a_probe_names_the_bank_a_locale_runs_on(self, tmp_path: Path, register_test_probe) -> None:
+        """The pre-flight checks the bank the class's bank_locale picks, not the locale's own folder."""
+        from usersim.cli._errors import ConfigError
+        from usersim.cli._pipeline import verify_probe_assets
+
+        (tmp_path / "ext_banks" / "shared").mkdir(parents=True)
+        bank = tmp_path / "ext_banks" / "shared" / "bank.yaml"
+        bank.write_text("recipes: [curry]\n", encoding="utf-8")
+        register_test_probe(
+            "ext_banks",
+            assets_root=tmp_path,
+            locale_bank_check=staticmethod(self._bank_check),
+            bank_locale=classmethod(lambda cls, locale, probe_dir: "shared"),
+        )
+
+        verify_probe_assets({"ext_banks": 1.0}, ["de_DE", "fr_FR"], None)
+        bank.write_text("", encoding="utf-8")
+        with pytest.raises(ConfigError) as exc:
+            verify_probe_assets({"ext_banks": 1.0}, ["de_DE"], None)
+        assert str(exc.value).splitlines()[1] == (
+            "  - ext_banks can't run de_DE (through shared): its bank does not load (ValueError: the bank is empty)."
+            " Locales that can run: none"
+        )
+
     def test_every_missing_probe_reported_at_once(self, tmp_path: Path) -> None:
         from usersim.cli._errors import ConfigError
         from usersim.cli._pipeline import verify_probe_assets

From e6e39289e0f0812901db855652dbd01c32c6be20 Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Thu, 29 Oct 2026 18:05:21 -0400
Subject: [PATCH 2/3] feat(engine): let a probe list the themes its rows draw
 from

BaseProbe.themes(locale) returns the themes the rows of a probe draw from, read with the run asset root installed, as rows read their banks. theme() reads the theme of a row back as a mapping, from JSON text or from a mapping. A run refuses a probe that lists no themes for a run locale.

general_open_ended and general_educational read theirs from their seed files. The sampler graph names no other probe but tool_calling, which takes its themes and toolsets from the run settings.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/probes.md                        |  6 ++
 docs/engine/AUTHORING_A_PROBE.md              | 29 +++++++++
 src/usersim/cli/_pipeline.py                  | 61 +++++++------------
 src/usersim/engine/core/probes.py             | 20 ++++++
 .../probes/general_educational/generator.py   |  9 ++-
 .../probes/general_open_ended/generator.py    |  9 ++-
 src/usersim/testing/__init__.py               |  7 ++-
 templates/probe/README.md                     |  3 +
 tests/engine/core/test_episode_input.py       | 46 ++++++++++++++
 tests/engine/core/test_probes_substrate.py    | 19 ++++++
 tests/engine/test_conformance_suite.py        | 11 +++-
 .../assets/fixture_probe/en_US/themes.yaml    |  2 +
 .../usersim_extension_fixture/probe.py        |  6 ++
 .../extension_package/verify_seams.py         | 12 ++++
 tests/test_cli.py                             |  6 --
 15 files changed, 191 insertions(+), 55 deletions(-)
 create mode 100644 tests/fixtures/extension_package/usersim_extension_fixture/assets/fixture_probe/en_US/themes.yaml

diff --git a/architecture/probes.md b/architecture/probes.md
index c9d5ec4..7f9bddf 100644
--- a/architecture/probes.md
+++ b/architecture/probes.md
@@ -116,3 +116,9 @@ pre-flight calls on the bank the class's `bank_locale` names. The refusal names
 the probe, the locale and the locales that can run, rather than failing from
 inside a loader mid-run. `simulate` and its `--dry-run`, `--materialize-inputs`,
 `--inputs` and notebook 01 all run the check. See [assets.md](assets.md).
+
+A probe whose conversations vary by topic lists its themes in a `themes`
+classmethod, read under its asset folder. A run draws one per row into the
+`theme` column, and the probe reads it back with `theme()`. A probe that lists
+none gets a placeholder it never reads. `tool_calling` takes its themes and
+toolsets from the run's settings instead.
diff --git a/docs/engine/AUTHORING_A_PROBE.md b/docs/engine/AUTHORING_A_PROBE.md
index 0c6af91..9196e94 100644
--- a/docs/engine/AUTHORING_A_PROBE.md
+++ b/docs/engine/AUTHORING_A_PROBE.md
@@ -330,6 +330,35 @@ class MyProbe(BankVerbatimMixin, BankBackedProbe):
   for another locale. The refusal links it when a run asks for a locale the
   probe has no bank for.
 
+### Give each row a theme
+
+A probe whose conversations vary by topic lists the topics in a `themes`
+classmethod. A run draws one per row, stores it in the row's `theme` column,
+and the probe reads it back with `self.theme()`:
+
+```python
+class MyProbe(BaseProbe):
+    @classmethod
+    def themes(cls, locale: str) -> list[dict]:
+        path = cls.assets_dir() / locale / "topics.json"
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._topic = self.theme().get("description", "a topic of their choice")
+```
+
+- **`themes(locale)`** returns the themes as mappings, read under
+  `assets_dir()`, so the run's asset root reaches them as it reaches the bank
+  loader. A run refuses a probe that returns none for a run locale.
+  `general_open_ended` and `general_educational` read theirs from their seed
+  files.
+- **`self.theme()`** returns the row's theme as a mapping, whether the row
+  holds it as JSON text, as a run stores it, or as the mapping a test passes
+  to `run_episode`.
+- **`None`**, the default `themes`, is a probe that reads no theme. Its rows
+  hold a placeholder.
+
 ---
 
 ## Step 4: write your `LocalePromptPack`
diff --git a/src/usersim/cli/_pipeline.py b/src/usersim/cli/_pipeline.py
index f276116..c63736d 100644
--- a/src/usersim/cli/_pipeline.py
+++ b/src/usersim/cli/_pipeline.py
@@ -71,45 +71,31 @@
     "general_educational": 1 / 3,
 }
 
-# Probes that consume the ``theme`` column. Other probes are
-# persona-derived (they read curated assets like fact / query / pressure
-# / agentic banks) and the ``theme`` column is irrelevant to them.
-THEME_DRIVEN_PROBES: frozenset = frozenset(
-    {
-        "tool_calling",
-        "general_open_ended",
-        "general_educational",
-    }
-)
-
-# Sentinel value used in the SubcategorySamplerParams entry for
-# non-theme-driven probes. The probe never reads this; it
-# exists so DD's SubcategorySampler has a value to draw when the
-# probe_type sampled is one that doesn't use themes.
+# The ``theme`` value of a row whose probe reads no theme. The probe never
+# reads it; it exists so DD's SubcategorySampler has a value to draw.
 _NO_THEME_PLACEHOLDER: str = "__not_used__"
 
 
-def seed_themes(
-    locale: str,
-    probe: str,
-    kind: str,
-    assets_dir: Path | str | None = None,
-) -> list[str]:
-    """Load a theme-driven probe's seeds and JSON-encode them for the sampler.
-
-    Called only for probes actually present in the run's ``probe_mix``, so an
-    assets root that ships seeds for just one general probe stays usable
-    (``load_seeds`` raises ``FileNotFoundError`` when neither the locale nor
-    the ``base`` seed file exists).
-
-    ``ensure_ascii=False`` so non-Latin theme descriptions (Japanese / Hindi /
-    Chinese / etc.) survive serialization as readable native script rather
-    than ``\\uXXXX`` escapes. Downstream ``json.loads`` reads either form
-    correctly; the parquet column is just easier on human eyeballs this way.
+def _probe_themes(probe: str, locale: str, assets_dir: Path) -> list[str]:
+    """``probe``'s themes in ``locale``, JSON-encoded for the sampler.
+
+    Read with ``assets_dir`` installed as the run installs it for each row, so
+    a probe finds its themes where its rows find their banks. ``ensure_ascii``
+    is off so non-Latin descriptions stay readable in the stored column.
     """
-    from usersim.engine.core.seeds import load_seeds
+    from usersim.engine.core._assets import reset_runtime_assets_dir, set_runtime_assets_dir
+    from usersim.engine.core.probes import resolve_probe
 
-    return [json.dumps(t, ensure_ascii=False) for t in load_seeds(locale, probe, kind, assets_dir)]
+    token = set_runtime_assets_dir(assets_dir)
+    try:
+        themes = resolve_probe(probe).themes(locale)
+    finally:
+        reset_runtime_assets_dir(token)
+    if themes is None:
+        return [_NO_THEME_PLACEHOLDER]
+    if not themes:
+        raise ConfigError(f"{probe} has no themes for {locale}, so none of its rows can be sampled.")
+    return [json.dumps(theme, ensure_ascii=False) for theme in themes]
 
 
 #: Seed-file suffixes the ``tool_calling`` toolset seed may use. Both are
@@ -560,14 +546,11 @@ def _add_episode_input_columns(
     toolset_kwargs: dict[str, Any] = {}
     for probe in probe_mix:
         if probe == "tool_calling":
+            # Its themes and toolsets are settings of the run.
             themes[probe] = list(tool_calling_themes or DEFAULT_TOOL_CALLING_THEMES)
             toolset_kwargs = _wire_toolsets(config_builder, dd, resolved_toolset_seed)
-        elif probe == "general_open_ended":
-            themes[probe] = seed_themes(locale, probe, "topics", assets_dir)
-        elif probe == "general_educational":
-            themes[probe] = seed_themes(locale, probe, "subjects", assets_dir)
         else:
-            themes[probe] = [_NO_THEME_PLACEHOLDER]
+            themes[probe] = _probe_themes(probe, locale, assets_dir)
     config_builder.add_column(
         dd.SamplerColumnConfig(
             name="theme",
diff --git a/src/usersim/engine/core/probes.py b/src/usersim/engine/core/probes.py
index a6df21c..7f85f63 100644
--- a/src/usersim/engine/core/probes.py
+++ b/src/usersim/engine/core/probes.py
@@ -51,6 +51,7 @@
 from typing import (
     Any,
     Callable,
+    Mapping,
     Protocol,
     Sequence,
     runtime_checkable,
@@ -58,6 +59,7 @@
 
 from usersim.engine.core.columns import output_columns_problem
 from usersim.engine.core.locale import asset_locale, india_variant
+from usersim.engine.core.messages import _parse_theme
 from usersim.engine.core.outcomes import (
     OutcomeBuilder,
     Provenance,
@@ -299,6 +301,16 @@ def bank_locale(cls, locale: str, probe_dir: Path) -> str:
         """
         return asset_locale(locale, exists=lambda loc: (probe_dir / loc).is_dir())
 
+    @classmethod
+    def themes(cls, locale: str) -> Sequence[Mapping[str, Any]] | None:
+        """The themes this probe's rows in ``locale`` draw from, read under ``assets_dir()``.
+
+        A run samples one theme per row and stores it, JSON-encoded, in the
+        row's ``theme`` column, where the probe reads it back. ``None``, the
+        default, is a probe that reads no theme.
+        """
+        return None
+
     # The top-level columns ``build_result_extras`` adds beyond the core ones
     # (``CORE_RESULT_COLUMNS``). A run keeps the core columns plus the union of
     # every registered probe's ``output_columns`` and drops any other key, so
@@ -361,6 +373,14 @@ def __init__(
         )
         self._patience = float(self._profile.get("patience", 0.5))
 
+    def theme(self) -> dict[str, Any]:
+        """This row's theme, the one the run drew from ``themes``, as a mapping.
+
+        A run stores it as JSON text, and ``run_episode`` passes the value it is
+        given; both read back the same. A row without one reads as ``{}``.
+        """
+        return _parse_theme(self._data.get(getattr(self._cfg, "theme_column", "theme"), "{}"))
+
     # ── Required hooks (must be overridden) ─────────────────────────
 
     def get_user_system_prompt(self) -> str:  # pragma: no cover — abstract
diff --git a/src/usersim/engine/probes/general_educational/generator.py b/src/usersim/engine/probes/general_educational/generator.py
index 6e9c17d..5611c7c 100644
--- a/src/usersim/engine/probes/general_educational/generator.py
+++ b/src/usersim/engine/probes/general_educational/generator.py
@@ -18,10 +18,10 @@
     format_disclosure_instructions,
     format_interaction_style_instructions,
 )
-from usersim.engine.core.messages import _parse_theme
 from usersim.engine.core.persona import format_persona_for_prompt
 from usersim.engine.core.probes import BaseProbe, dispatch_episode, register_probe
 from usersim.engine.core.prompt_loader import render_prompt
+from usersim.engine.core.seeds import load_seeds
 from usersim.engine.core.simulation import language_instruction
 from usersim.engine.probes.general_educational.prompts import (
     assistant_system_prompt,
@@ -51,9 +51,14 @@ class EducationalProbe(BaseProbe):
 
     label = "general_educational"
 
+    @classmethod
+    def themes(cls, locale: str) -> list[dict[str, Any]]:
+        """The subjects in ``locale``'s seed file, or in the base file when the locale has none."""
+        return load_seeds(locale, cls.label, "subjects")
+
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
-        theme = _parse_theme(self._data.get(getattr(self._cfg, "theme_column", "theme"), "{}"))
+        theme = self.theme()
         # Parsed once; the prompt itself is rendered per call in
         # get_user_system_prompt so all three prompt hooks resolve alike.
         self._subject = theme.get("description", theme.get("type", "general subject"))
diff --git a/src/usersim/engine/probes/general_open_ended/generator.py b/src/usersim/engine/probes/general_open_ended/generator.py
index 52f076c..2fe0a5a 100644
--- a/src/usersim/engine/probes/general_open_ended/generator.py
+++ b/src/usersim/engine/probes/general_open_ended/generator.py
@@ -18,10 +18,10 @@
     format_disclosure_instructions,
     format_interaction_style_instructions,
 )
-from usersim.engine.core.messages import _parse_theme
 from usersim.engine.core.persona import format_persona_for_prompt
 from usersim.engine.core.probes import BaseProbe, dispatch_episode, register_probe
 from usersim.engine.core.prompt_loader import render_prompt
+from usersim.engine.core.seeds import load_seeds
 from usersim.engine.core.simulation import language_instruction
 from usersim.engine.probes.general_open_ended.prompts import (
     assistant_system_prompt,
@@ -50,9 +50,14 @@ class OpenEndedProbe(BaseProbe):
 
     label = "general_open_ended"
 
+    @classmethod
+    def themes(cls, locale: str) -> list[dict[str, Any]]:
+        """The topics in ``locale``'s seed file, or in the base file when the locale has none."""
+        return load_seeds(locale, cls.label, "topics")
+
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
-        theme = _parse_theme(self._data.get(getattr(self._cfg, "theme_column", "theme"), "{}"))
+        theme = self.theme()
         # Parsed once; the prompt itself is rendered per call in
         # get_user_system_prompt so all three prompt hooks resolve alike.
         self._topic = theme.get("description", theme.get("type", "general topic"))
diff --git a/src/usersim/testing/__init__.py b/src/usersim/testing/__init__.py
index 908cae7..845aab7 100644
--- a/src/usersim/testing/__init__.py
+++ b/src/usersim/testing/__init__.py
@@ -184,15 +184,16 @@ def probe_conformance_problems(probe: str | type) -> list[str]:
         if kind_problem:
             problems.append(f"{cls.__qualname__}.placeholder_warning_kind {kind_problem}")
 
-    # The pre-flight reads these on the class, before any row runs.
+    # A run reads these on the class, before any row runs.
     check = getattr(cls, "locale_bank_check", None)
     if check is not None and not callable(check):
         problems.append(
             f"{cls.__qualname__}.locale_bank_check must be None or a function that loads one "
             f"locale's bank folder; got {check!r}"
         )
-    if not isinstance(inspect.getattr_static(cls, "bank_locale", None), classmethod):
-        problems.append(f"{cls.__qualname__}.bank_locale must be a classmethod; the pre-flight calls it on the class.")
+    for hook in ("bank_locale", "themes"):
+        if not isinstance(inspect.getattr_static(cls, hook, None), classmethod):
+            problems.append(f"{cls.__qualname__}.{hook} must be a classmethod; a run calls it on the class.")
     guide = getattr(cls, "authoring_guide", None)
     if guide is not None and not (isinstance(guide, str) and guide.startswith("https://")):
         problems.append(
diff --git a/templates/probe/README.md b/templates/probe/README.md
index be5e522..f65a617 100644
--- a/templates/probe/README.md
+++ b/templates/probe/README.md
@@ -125,6 +125,9 @@ When porting one of the templates into a new module:
       by locale also sets `locale_bank_check`, so a run refuses a locale
       whose bank is missing before any model call (step 3 of
       `docs/engine/AUTHORING_A_PROBE.md`).
+- [ ] If the probe's conversations vary by topic, list the topics in a
+      `themes` classmethod and read the row's with `self.theme()` (step 3
+      of `docs/engine/AUTHORING_A_PROBE.md`).
 - [ ] Keep the probe's own per-row data under metadata keys of its own.
       The loop writes the keys in `RESERVED_METADATA_KEYS`
       (`core/simulation.py`); a probe reads them, and
diff --git a/tests/engine/core/test_episode_input.py b/tests/engine/core/test_episode_input.py
index dba1a13..3ed4ccb 100644
--- a/tests/engine/core/test_episode_input.py
+++ b/tests/engine/core/test_episode_input.py
@@ -132,6 +132,52 @@ def test_materialization_supports_every_registered_probe(probe_type: str, tmp_pa
 }
 
 
+@pytest.mark.parametrize(
+    ("probe_type", "kind"), [("general_open_ended", "topics"), ("general_educational", "subjects")]
+)
+def test_a_general_probe_draws_its_theme_from_its_seeds(probe_type: str, kind: str) -> None:
+    from usersim.engine.core.seeds import load_seeds
+
+    (row,) = materialize_episode_inputs(locale="en_US", num_rows=1, probe_mix={probe_type: 1.0}, random_seed=5)
+
+    assert json.loads(row["theme"]) in load_seeds("en_US", probe_type, kind)
+
+
+def _themes_from_its_folder(cls: type, locale: str) -> list[dict]:
+    return json.loads((cls.assets_dir() / locale / "themes.json").read_text(encoding="utf-8"))
+
+
+def test_a_probes_themes_reach_its_rows(register_test_probe, tmp_path: Path) -> None:
+    """A probe's themes, read under its own asset folder as its banks are, are what its rows sample."""
+    (tmp_path / "ext_themes" / "en_US").mkdir(parents=True)
+    bread = {"type": "Baking", "description": "Pain de campagne à la maison"}
+    (tmp_path / "ext_themes" / "en_US" / "themes.json").write_text(json.dumps([bread]), encoding="utf-8")
+    register_test_probe("ext_themes", assets_root=tmp_path, themes=classmethod(_themes_from_its_folder))
+
+    (row,) = materialize_episode_inputs(locale="en_US", num_rows=1, probe_mix={"ext_themes": 1.0}, random_seed=5)
+
+    assert json.loads(row["theme"]) == bread
+    assert "à la maison" in row["theme"]
+
+
+def test_a_probe_that_reads_no_theme_gets_a_placeholder(register_test_probe) -> None:
+    register_test_probe("ext_no_themes")
+
+    (row,) = materialize_episode_inputs(locale="en_US", num_rows=1, probe_mix={"ext_no_themes": 1.0}, random_seed=5)
+
+    assert row["theme"] == "__not_used__"
+
+
+def test_a_probe_with_no_themes_for_the_locale_is_refused(register_test_probe) -> None:
+    """An empty list leaves the sampler nothing to draw for the probe's rows."""
+    from usersim.cli._errors import ConfigError
+
+    register_test_probe("ext_no_themes", themes=classmethod(lambda cls, locale: []))
+
+    with pytest.raises(ConfigError, match="ext_no_themes has no themes for en_US"):
+        materialize_episode_inputs(locale="en_US", num_rows=1, probe_mix={"ext_no_themes": 1.0}, random_seed=5)
+
+
 def test_every_registered_probe_has_a_pinned_trajectory_id() -> None:
     """Guard against a probe landing without a trajectory-identity decision."""
     assert set(_PINNED_TRAJECTORY_IDS) == set(known_probes())
diff --git a/tests/engine/core/test_probes_substrate.py b/tests/engine/core/test_probes_substrate.py
index b6cbc75..ac50c51 100644
--- a/tests/engine/core/test_probes_substrate.py
+++ b/tests/engine/core/test_probes_substrate.py
@@ -117,6 +117,25 @@ def test_implements_protocol(self) -> None:
     def test_get_tools_for_assistant_default_none(self) -> None:
         assert self._build().get_tools_for_assistant() is None
 
+    @pytest.mark.parametrize(
+        "stored",
+        [
+            '{"type": "cooking", "description": "Weeknight dinners"}',
+            {"type": "cooking", "description": "Weeknight dinners"},
+        ],
+        ids=["json-text", "mapping"],
+    )
+    def test_a_row_reads_its_theme_back_as_a_mapping(self, stored) -> None:
+        """A run stores the theme as JSON text; a caller of run_episode may pass the mapping itself."""
+        probe = _MinimalProbe(persona={}, locale="en_US", language="English", models={}, data={"theme": stored})
+        assert probe.theme() == {"type": "cooking", "description": "Weeknight dinners"}
+
+    def test_a_row_without_a_theme_reads_as_empty(self) -> None:
+        assert self._build().theme() == {}
+
+    def test_a_probe_reads_no_theme_by_default(self) -> None:
+        assert _MinimalProbe.themes("en_US") is None
+
     def test_format_gate_prompt_substitutes(self) -> None:
         probe = self._build()
         prompt = probe.format_gate_prompt("Hello?", "(no history)")
diff --git a/tests/engine/test_conformance_suite.py b/tests/engine/test_conformance_suite.py
index 52ffb7a..819ad88 100644
--- a/tests/engine/test_conformance_suite.py
+++ b/tests/engine/test_conformance_suite.py
@@ -191,11 +191,12 @@ class Mislabelled(BaseProbe):
                 {"authoring_guide": "README.md#locales"},
                 "PreflightProbe.authoring_guide must be None or an https:// URL",
             ),
+            ({"themes": lambda self, locale: None}, "PreflightProbe.themes must be a classmethod"),
         ],
-        ids=["check-not-callable", "bank-locale-not-a-classmethod", "relative-guide"],
+        ids=["check-not-callable", "bank-locale-not-a-classmethod", "relative-guide", "themes-not-a-classmethod"],
     )
     async def test_unusable_preflight_declarations_are_reported(self, attributes, expected) -> None:
-        """The pre-flight reads these on the class before any row runs, so a wrong one fails the whole run."""
+        """A run reads these on the class before any row runs, so a wrong one fails the whole run."""
         cls = type("PreflightProbe", (BaseProbe,), {"label": "preflight_probe", **attributes})
 
         problems = probe_conformance_problems(cls)
@@ -211,7 +212,11 @@ class Declared(BaseProbe):
             def bank_locale(cls, locale, probe_dir):
                 return locale
 
-        declarations = ("locale_bank_check", "bank_locale", "authoring_guide")
+            @classmethod
+            def themes(cls, locale):
+                return [{"type": "cooking"}]
+
+        declarations = ("locale_bank_check", "bank_locale", "authoring_guide", "themes")
         assert not [p for p in probe_conformance_problems(Declared) if any(d in p for d in declarations)]
 
     @pytest.mark.parametrize(
diff --git a/tests/fixtures/extension_package/usersim_extension_fixture/assets/fixture_probe/en_US/themes.yaml b/tests/fixtures/extension_package/usersim_extension_fixture/assets/fixture_probe/en_US/themes.yaml
new file mode 100644
index 0000000..150a29f
--- /dev/null
+++ b/tests/fixtures/extension_package/usersim_extension_fixture/assets/fixture_probe/en_US/themes.yaml
@@ -0,0 +1,2 @@
+- type: fixture topic
+  description: A topic every fixture row draws.
diff --git a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
index f305827..154546e 100644
--- a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
+++ b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
@@ -3,6 +3,8 @@
 
 from pathlib import Path
 
+import yaml
+
 from usersim.engine.core.probes import BaseProbe, register_probe
 
 
@@ -19,6 +21,10 @@ class FixtureProbe(BaseProbe):
     locale_bank_check = staticmethod(_check_locale_bank)
     authoring_guide = "https://example.com/fixture-probe/locales"
 
+    @classmethod
+    def themes(cls, locale: str) -> list[dict]:
+        return yaml.safe_load((cls.assets_dir() / locale / "themes.yaml").read_text(encoding="utf-8"))
+
     def get_user_system_prompt(self) -> str:
         return "You are a fixture user."
 
diff --git a/tests/fixtures/extension_package/verify_seams.py b/tests/fixtures/extension_package/verify_seams.py
index 2abc8cf..dc81a90 100644
--- a/tests/fixtures/extension_package/verify_seams.py
+++ b/tests/fixtures/extension_package/verify_seams.py
@@ -122,6 +122,18 @@ def preflight_refusal(locales: list[str]) -> str:
     refusal,
 )
 
+# A contributed probe's themes come from its installed assets, read as a run
+# reads them, with the run's asset root installed.
+from usersim.cli._pipeline import _probe_themes  # noqa: E402
+from usersim.engine.core._assets import default_assets_dir  # noqa: E402
+
+themes = _probe_themes("fixture_probe", "en_US", default_assets_dir())
+check(
+    "themes come from the contributed assets",
+    themes == ['{"type": "fixture topic", "description": "A topic every fixture row draws."}'],
+    str(themes),
+)
+
 # The published conformance suite must pass for a real external probe.
 from usersim.testing import probe_conformance_problems  # noqa: E402
 
diff --git a/tests/test_cli.py b/tests/test_cli.py
index b439ba9..da97761 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -36,7 +36,6 @@
 )
 from usersim.cli._pipeline import (
     DEFAULT_PROBE_MIX,
-    THEME_DRIVEN_PROBES,
     build_simulator_config_builder,
     known_probes,
 )
@@ -369,11 +368,6 @@ def test_default_probe_mix_is_general_family_only(self):
             "general_educational",
         }
 
-    def test_theme_driven_set_matches_subcategory_branches(self):
-        # The pipeline's theme-column dispatcher only has explicit
-        # branches for these three; everything else uses the placeholder.
-        assert THEME_DRIVEN_PROBES == frozenset({"tool_calling", "general_open_ended", "general_educational"})
-
     @pytest.mark.parametrize(
         "probe",
         sorted(

From 3dc1dc825da19f40793675455ca8a5e6b555ac35 Mon Sep 17 00:00:00 2001
From: Yev Meyer <ymeyer@nvidia.com>
Date: Thu, 29 Oct 2026 18:57:50 -0400
Subject: [PATCH 3/3] feat(engine): let a probe name the models it calls

A probe that calls a model beyond the user, assistant, tool-response, judge and summary models names its alias in the model_aliases classmethod. Every row gets each declared alias the model registry has, one the registry lacks is left out for the probe to handle, and the setup fingerprint counts the settings of each declared model.

financial_services declares the model that embeds its search queries, so the generator and the setup fingerprint name no probe. assert_probe_conforms checks that the declaration is a classmethod returning a tuple of names.

Signed-off-by: Yev Meyer <ymeyer@nvidia.com>
---
 architecture/cli.md                           | 11 ++--
 docs/engine/AUTHORING_A_PROBE.md              | 22 +++++++
 docs/engine/EXTERNAL_PROBE_RUNTIME.md         |  1 +
 src/usersim/cli/_inputs.py                    | 14 +++--
 src/usersim/engine/core/probes.py             | 21 +++++++
 src/usersim/engine/generator.py               | 22 +++----
 .../probes/financial_services/generator.py    | 11 ++--
 src/usersim/testing/__init__.py               | 17 +++++-
 templates/probe/README.md                     |  3 +
 tests/engine/test_conformance_suite.py        | 20 ++++++-
 tests/engine/test_probe_model_aliases.py      | 57 +++++++++++++++++++
 .../usersim_extension_fixture/probe.py        |  4 ++
 .../extension_package/verify_seams.py         |  6 ++
 tests/test_cli_simulate_inputs.py             | 12 ++++
 14 files changed, 190 insertions(+), 31 deletions(-)
 create mode 100644 tests/engine/test_probe_model_aliases.py

diff --git a/architecture/cli.md b/architecture/cli.md
index 01fac3e..3d12cb8 100644
--- a/architecture/cli.md
+++ b/architecture/cli.md
@@ -43,10 +43,13 @@ them: `api_response_model` for tool-calling probes and `summary_model` for the
 loop's light work: summaries for context management, early-stop checks, the
 pressure probe's capitulation check, and translating India-variant openings
 and `financial_services` search queries.
-Without it, `user_model` does that work. `eval` requires `evaluator_model`,
-kept distinct from `judge_model` so the in-sim gate and the post-hoc rubric
-can be sized independently. A missing required alias fails at config
-construction, not mid-run.
+Without it, `user_model` does that work. A probe that calls a model of its own
+names the alias in `model_aliases` on its class, as `financial_services` does
+for the model that embeds its search queries: each declared alias the file
+defines reaches the probe, and one it lacks is left out. `eval` requires
+`evaluator_model`, kept distinct from `judge_model` so the in-sim gate and the
+post-hoc rubric can be sized independently. A missing required alias fails at
+config construction, not mid-run.
 
 `usersim.cli.model_catalog` holds per-model inference defaults: temperature,
 top_p, max_tokens, and any model-family-specific `extra_body`. A TOML row
diff --git a/docs/engine/AUTHORING_A_PROBE.md b/docs/engine/AUTHORING_A_PROBE.md
index 9196e94..5e753a7 100644
--- a/docs/engine/AUTHORING_A_PROBE.md
+++ b/docs/engine/AUTHORING_A_PROBE.md
@@ -235,6 +235,28 @@ def load_my_bank(locale: str) -> MyBank:
 [`docs/extensions.md`](../extensions.md) builds a whole package around such a
 probe.
 
+### Call a model of your own
+
+A probe that calls a model beyond the conversation's own (the user, assistant,
+tool-response, judge and summary models) names its alias in the models file in
+a `model_aliases` classmethod:
+
+```python
+class MyProbe(BaseProbe):
+    @classmethod
+    def model_aliases(cls, cfg) -> tuple[str, ...]:
+        return ("my_probe_critic_model",)
+```
+
+Each row's `models` holds every declared alias the models file defines, so the
+probe reads its model as `self._models.get("my_probe_critic_model")`. An alias
+the file lacks is left out, and the probe handles its absence: `get` returns
+`None`, and the probe can fall back or raise an error that names the alias. A
+run's setup fingerprint counts the settings of each declared model. `cfg` is
+the run's `ConversationSimulatorConfig`, for an alias that is itself a setting:
+`financial_services` declares the model named by `finance_embedding_model_alias`,
+which embeds its search queries, and searches lexically without it.
+
 ---
 
 ## Step 3: wire the asset bank
diff --git a/docs/engine/EXTERNAL_PROBE_RUNTIME.md b/docs/engine/EXTERNAL_PROBE_RUNTIME.md
index 4c0aced..ab9b332 100644
--- a/docs/engine/EXTERNAL_PROBE_RUNTIME.md
+++ b/docs/engine/EXTERNAL_PROBE_RUNTIME.md
@@ -148,6 +148,7 @@ as a Data Designer model facade.
 runtime_models["api_response_model"] = my_tool_response_model
 ```
 
+A probe names any other model it calls in `model_aliases` on its class.
 `financial_services` optionally embeds its `kb_search` queries with the model
 named by `finance_embedding_model_alias` (`embedding_model` by default, anything
 exposing `agenerate_text_embeddings()`); without one, dense retrieval falls back
diff --git a/src/usersim/cli/_inputs.py b/src/usersim/cli/_inputs.py
index 3244947..ad15e8a 100644
--- a/src/usersim/cli/_inputs.py
+++ b/src/usersim/cli/_inputs.py
@@ -368,9 +368,10 @@ def setup_fingerprint(models: Any, inputs: EpisodeInputs) -> tuple[str, dict[str
 
     Returns the fingerprint and the run record that names it. Covered:
 
-    - every simulator model alias as Data Designer sends it, provider settings
-      included (``api_key``, a provider's name and ``max_parallel_requests``
-      are left out: they don't change what a model says);
+    - every simulator model alias, and every alias a registered probe names in
+      ``model_aliases``, as Data Designer sends it, provider settings included
+      (``api_key``, a provider's name and ``max_parallel_requests`` are left
+      out: they don't change what a model says);
     - the shared ``usersim_config`` as loaded, defaults applied, with whether
       the assistant's reasoning is replayed as the run's models file sets it;
     - the contents of every asset root, a probe's declared ``assets_root``
@@ -382,13 +383,14 @@ def setup_fingerprint(models: Any, inputs: EpisodeInputs) -> tuple[str, dict[str
     """
     from usersim.engine.config import MODEL_ALIASES, ConversationSimulatorConfig
     from usersim.engine.core.manifest import _own_version
+    from usersim.engine.core.probes import declared_model_aliases
     from usersim.engine.core.storage import RUN_KIND_STORED
 
-    simulation = ConversationSimulatorConfig.model_validate(_run_config(inputs, models)).model_dump(mode="json")
+    config = ConversationSimulatorConfig.model_validate(_run_config(inputs, models))
+    simulation = config.model_dump(mode="json")
     for key in _PER_ROW_SETTINGS:
         simulation.pop(key, None)
-    aliases = [*MODEL_ALIASES, simulation.get("finance_embedding_model_alias") or ""]
-    readable, hashed = _model_settings(models, [alias for alias in aliases if alias])
+    readable, hashed = _model_settings(models, [*MODEL_ALIASES, *declared_model_aliases(config)])
     fingerprint = _digest(
         {
             "models": hashed,
diff --git a/src/usersim/engine/core/probes.py b/src/usersim/engine/core/probes.py
index 7f85f63..54e9ae4 100644
--- a/src/usersim/engine/core/probes.py
+++ b/src/usersim/engine/core/probes.py
@@ -311,6 +311,19 @@ def themes(cls, locale: str) -> Sequence[Mapping[str, Any]] | None:
         """
         return None
 
+    @classmethod
+    def model_aliases(cls, cfg: Any) -> tuple[str, ...]:
+        """Models this probe calls beyond the user, assistant, tool-response, judge and summary models.
+
+        Each is an alias in the models file. Every row's ``models`` holds each
+        alias a registered probe names here that the models file defines; one
+        the file lacks is left out, and the probe handles its absence. A run's
+        setup fingerprint counts each one's settings.
+        ``cfg`` is the run's ``ConversationSimulatorConfig``, for a probe whose
+        alias is one of its settings.
+        """
+        return ()
+
     # The top-level columns ``build_result_extras`` adds beyond the core ones
     # (``CORE_RESULT_COLUMNS``). A run keeps the core columns plus the union of
     # every registered probe's ``output_columns`` and drops any other key, so
@@ -1540,6 +1553,14 @@ def declared_output_columns() -> tuple[str, ...]:
     return tuple(columns)
 
 
+def declared_model_aliases(cfg: Any) -> tuple[str, ...]:
+    """The aliases every registered probe names in ``model_aliases``, each once, in label order."""
+    aliases: dict[str, None] = {}
+    for label in known_probes():
+        aliases.update(dict.fromkeys(alias for alias in _PROBE_REGISTRY[label].model_aliases(cfg) if alias))
+    return tuple(aliases)
+
+
 def resolve_probe(label: str) -> type[BaseProbe]:
     """Look up a probe class by label. Raises ``KeyError`` if unknown."""
     if label not in _PROBE_REGISTRY:
diff --git a/src/usersim/engine/generator.py b/src/usersim/engine/generator.py
index 48e0ce5..3f48164 100644
--- a/src/usersim/engine/generator.py
+++ b/src/usersim/engine/generator.py
@@ -42,7 +42,7 @@
 )
 from usersim.engine.core.outcomes import Provenance
 from usersim.engine.core.persona import persona_full_name
-from usersim.engine.core.probes import BankLoadError, dispatch_episode, load_builtin_probes
+from usersim.engine.core.probes import BankLoadError, declared_model_aliases, dispatch_episode, load_builtin_probes
 from usersim.engine.core.provenance import get_code_sha
 
 logger = logging.getLogger("usersim.engine")
@@ -148,20 +148,16 @@ async def _generate_row(self, data: dict) -> dict:
                 else:
                     raise
 
-        # The embedding model is NOT a chat alias, so it's absent from
-        # MODEL_ALIASES -- but the financial_services probe needs its facade in
-        # the models dict to embed kb_search queries for dense retrieval. Add it
-        # best-effort: if it isn't configured/resolvable, dense retrieval falls
-        # back to lexical (the probe logs a loud warning), never a hard failure.
-        embed_alias = getattr(self.config, "finance_embedding_model_alias", None)
-        if embed_alias and embed_alias not in models:
+        # The models probes call beyond the conversation's own, best-effort:
+        # one the registry lacks is left out, and the probe that names it
+        # handles its absence.
+        for alias in declared_model_aliases(cfg):
+            if alias in models:
+                continue
             try:
-                models[embed_alias] = self.get_model(embed_alias)
+                models[alias] = self.get_model(alias)
             except Exception:
-                logger.debug(
-                    "  |-- embedding model %r not in registry; finance dense retrieval will fall back to lexical",
-                    embed_alias,
-                )
+                logger.debug("  |-- model alias %r not in the model registry; probes run without it", alias)
 
         t_record_start = time.monotonic()
 
diff --git a/src/usersim/engine/probes/financial_services/generator.py b/src/usersim/engine/probes/financial_services/generator.py
index b612a64..968d38e 100644
--- a/src/usersim/engine/probes/financial_services/generator.py
+++ b/src/usersim/engine/probes/financial_services/generator.py
@@ -376,11 +376,7 @@ def __init__(self, **kwargs: Any) -> None:
             t.name for t in self._institution.tools if t.side_effect_class == "read_only"
         )
         self._retrieval_mode = getattr(self._cfg, "finance_retrieval_mode", "hybrid")
-        self._embedding_alias = getattr(
-            self._cfg,
-            "finance_embedding_model_alias",
-            "embedding_model",
-        )
+        (self._embedding_alias,) = self.model_aliases(self._cfg)
         # Tripped the first time dense mode has to fall back to lexical (no query
         # vector) so a misconfigured run -- dense requested but no embedding model
         # -- is loud instead of silently degrading to word overlap.
@@ -392,6 +388,11 @@ def __init__(self, **kwargs: Any) -> None:
 
     # ── BankBackedProbe API ─────────────────────────────────────────
 
+    @classmethod
+    def model_aliases(cls, cfg: Any) -> tuple[str, ...]:
+        """The model that embeds ``kb_search`` queries; without it, dense retrieval falls back to lexical."""
+        return (getattr(cfg, "finance_embedding_model_alias", "embedding_model"),)
+
     @classmethod
     def bank_locale(cls, locale: str, probe_dir: Path) -> str:
         """The locale :func:`finance_bank_locale` picks for ``locale`` among the banks in ``probe_dir``."""
diff --git a/src/usersim/testing/__init__.py b/src/usersim/testing/__init__.py
index 845aab7..321f379 100644
--- a/src/usersim/testing/__init__.py
+++ b/src/usersim/testing/__init__.py
@@ -191,9 +191,11 @@ def probe_conformance_problems(probe: str | type) -> list[str]:
             f"{cls.__qualname__}.locale_bank_check must be None or a function that loads one "
             f"locale's bank folder; got {check!r}"
         )
-    for hook in ("bank_locale", "themes"):
+    for hook in ("bank_locale", "themes", "model_aliases"):
         if not isinstance(inspect.getattr_static(cls, hook, None), classmethod):
             problems.append(f"{cls.__qualname__}.{hook} must be a classmethod; a run calls it on the class.")
+    if isinstance(inspect.getattr_static(cls, "model_aliases", None), classmethod):
+        problems.extend(_model_aliases_problems(cls))
     guide = getattr(cls, "authoring_guide", None)
     if guide is not None and not (isinstance(guide, str) and guide.startswith("https://")):
         problems.append(
@@ -217,6 +219,19 @@ def probe_conformance_problems(probe: str | type) -> list[str]:
     return problems
 
 
+def _model_aliases_problems(cls: type) -> list[str]:
+    """What is wrong with the aliases ``cls.model_aliases`` gives a run with default settings."""
+    from usersim.engine.config import ConversationSimulatorConfig
+
+    try:
+        aliases = cls.model_aliases(ConversationSimulatorConfig(name="conversation_messages"))
+    except Exception as error:
+        return [f"{cls.__qualname__}.model_aliases raised {type(error).__name__}: {error}"]
+    if not isinstance(aliases, tuple) or not all(isinstance(alias, str) and alias for alias in aliases):
+        return [f"{cls.__qualname__}.model_aliases must return a tuple of alias names; got {aliases!r}"]
+    return []
+
+
 def _reserved_metadata_writes(cls: type) -> list[tuple[str, str]]:
     """``(class, key)`` for each reserved metadata key the probe's own classes write.
 
diff --git a/templates/probe/README.md b/templates/probe/README.md
index f65a617..07c2982 100644
--- a/templates/probe/README.md
+++ b/templates/probe/README.md
@@ -128,6 +128,9 @@ When porting one of the templates into a new module:
 - [ ] If the probe's conversations vary by topic, list the topics in a
       `themes` classmethod and read the row's with `self.theme()` (step 3
       of `docs/engine/AUTHORING_A_PROBE.md`).
+- [ ] If the probe calls a model beyond the conversation's own, name its
+      alias in a `model_aliases` classmethod (step 2 of
+      `docs/engine/AUTHORING_A_PROBE.md`).
 - [ ] Keep the probe's own per-row data under metadata keys of its own.
       The loop writes the keys in `RESERVED_METADATA_KEYS`
       (`core/simulation.py`); a probe reads them, and
diff --git a/tests/engine/test_conformance_suite.py b/tests/engine/test_conformance_suite.py
index 819ad88..28eaf16 100644
--- a/tests/engine/test_conformance_suite.py
+++ b/tests/engine/test_conformance_suite.py
@@ -192,8 +192,20 @@ class Mislabelled(BaseProbe):
                 "PreflightProbe.authoring_guide must be None or an https:// URL",
             ),
             ({"themes": lambda self, locale: None}, "PreflightProbe.themes must be a classmethod"),
+            ({"model_aliases": lambda self, cfg: ()}, "PreflightProbe.model_aliases must be a classmethod"),
+            (
+                {"model_aliases": classmethod(lambda cls, cfg: "critic_model")},
+                "PreflightProbe.model_aliases must return a tuple of alias names; got 'critic_model'",
+            ),
+        ],
+        ids=[
+            "check-not-callable",
+            "bank-locale-not-a-classmethod",
+            "relative-guide",
+            "themes-not-a-classmethod",
+            "model-aliases-not-a-classmethod",
+            "model-aliases-a-bare-string",
         ],
-        ids=["check-not-callable", "bank-locale-not-a-classmethod", "relative-guide", "themes-not-a-classmethod"],
     )
     async def test_unusable_preflight_declarations_are_reported(self, attributes, expected) -> None:
         """A run reads these on the class before any row runs, so a wrong one fails the whole run."""
@@ -216,7 +228,11 @@ def bank_locale(cls, locale, probe_dir):
             def themes(cls, locale):
                 return [{"type": "cooking"}]
 
-        declarations = ("locale_bank_check", "bank_locale", "authoring_guide", "themes")
+            @classmethod
+            def model_aliases(cls, cfg):
+                return ("critic_model",)
+
+        declarations = ("locale_bank_check", "bank_locale", "authoring_guide", "themes", "model_aliases")
         assert not [p for p in probe_conformance_problems(Declared) if any(d in p for d in declarations)]
 
     @pytest.mark.parametrize(
diff --git a/tests/engine/test_probe_model_aliases.py b/tests/engine/test_probe_model_aliases.py
new file mode 100644
index 0000000..b4d545c
--- /dev/null
+++ b/tests/engine/test_probe_model_aliases.py
@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Models a probe names in ``model_aliases`` reach its rows.
+
+A probe that calls a model beyond the conversation's own names its alias on
+the class. Every row gets each declared model the registry has, and one the
+registry lacks is left out for the probe to handle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from usersim.engine.config import ConversationSimulatorConfig
+from usersim.engine.core.probes import declared_model_aliases
+from usersim.engine.generator import ConversationSimulatorGenerator
+from usersim.testing import ScriptedModel, _episode_runtime, _scripted_models
+
+PERSONA = {"first_name": "Sarah", "last_name": "Johnson", "age": 35, "city": "Seattle"}
+
+
+def test_the_built_in_probes_declare_the_embedding_model() -> None:
+    assert declared_model_aliases(ConversationSimulatorConfig(name="conversation_messages")) == ("embedding_model",)
+
+
+def test_a_declared_alias_follows_the_setting_that_names_it() -> None:
+    config = ConversationSimulatorConfig(name="conversation_messages", finance_embedding_model_alias="my_embedder")
+
+    assert declared_model_aliases(config) == ("my_embedder",)
+
+
+async def test_a_row_gets_the_declared_models_the_registry_has(register_test_probe) -> None:
+    seen: dict[str, Any] = {}
+
+    def user_prompt(self) -> str:
+        seen.update(self._models)
+        return "You are a home cook."
+
+    register_test_probe(
+        "ext_critic",
+        model_aliases=classmethod(lambda cls, cfg: ("ext_critic_model", "ext_absent_model")),
+        get_user_system_prompt=user_prompt,
+        get_assistant_system_prompt=lambda self: "",
+    )
+    config = ConversationSimulatorConfig(name="conversation_messages", max_turns=1)
+    critic = ScriptedModel("critic")
+    models = {**_scripted_models(ScriptedModel, []), "ext_critic_model": critic}
+    runtime = _episode_runtime(
+        "ext_critic", models, config=config, persona=PERSONA, data=None, profile=None, language="English"
+    )
+
+    row = await ConversationSimulatorGenerator.with_models(config, models).agenerate(runtime.preamble.to_row())
+
+    assert row["conversation_status"] is True
+    assert seen["ext_critic_model"] is critic
+    assert "ext_absent_model" not in seen
diff --git a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
index 154546e..915973b 100644
--- a/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
+++ b/tests/fixtures/extension_package/usersim_extension_fixture/probe.py
@@ -21,6 +21,10 @@ class FixtureProbe(BaseProbe):
     locale_bank_check = staticmethod(_check_locale_bank)
     authoring_guide = "https://example.com/fixture-probe/locales"
 
+    @classmethod
+    def model_aliases(cls, cfg) -> tuple[str, ...]:
+        return ("fixture_critic_model",)
+
     @classmethod
     def themes(cls, locale: str) -> list[dict]:
         return yaml.safe_load((cls.assets_dir() / locale / "themes.yaml").read_text(encoding="utf-8"))
diff --git a/tests/fixtures/extension_package/verify_seams.py b/tests/fixtures/extension_package/verify_seams.py
index dc81a90..34b36e8 100644
--- a/tests/fixtures/extension_package/verify_seams.py
+++ b/tests/fixtures/extension_package/verify_seams.py
@@ -134,6 +134,12 @@ def preflight_refusal(locales: list[str]) -> str:
     str(themes),
 )
 
+# A model a contributed probe declares joins the models every row resolves.
+from usersim.engine.core.probes import declared_model_aliases  # noqa: E402
+
+declared = declared_model_aliases(ConversationSimulatorConfig(name="conversation_messages"))
+check("model_aliases joins the run's models", "fixture_critic_model" in declared, str(declared))
+
 # The published conformance suite must pass for a real external probe.
 from usersim.testing import probe_conformance_problems  # noqa: E402
 
diff --git a/tests/test_cli_simulate_inputs.py b/tests/test_cli_simulate_inputs.py
index 28a66fb..c35bed7 100644
--- a/tests/test_cli_simulate_inputs.py
+++ b/tests/test_cli_simulate_inputs.py
@@ -246,6 +246,18 @@ def test_a_model_setting_that_can_change_a_conversation_is_a_new_setup(rows, mod
     assert _fingerprint(rows, models()) != _fingerprint(rows)
 
 
+def test_a_model_a_probe_declares_is_part_of_the_setup(rows, register_test_probe):
+    """A model a probe calls changes what its conversations say, like the conversation's own models."""
+    register_test_probe("ext_critic", model_aliases=classmethod(lambda cls, cfg: ("ext_critic_model",)))
+
+    def with_critic(model: str) -> ModelsConfig:
+        base = _models()
+        critic = replace(base.models[0], alias="ext_critic_model", model=model)
+        return ModelsConfig(providers=base.providers, models=(*base.models, critic))
+
+    assert _fingerprint(rows, with_critic("acme/critic-a")) != _fingerprint(rows, with_critic("acme/critic-b"))
+
+
 def test_the_runs_models_file_decides_replay_whatever_the_rows_were_stored_with(rows, tmp_path):
     """The assistant under test comes from the run's models file, and so does replaying its reasoning."""
     from usersim.engine.core.llm import replaying_assistant_reasoning