refactor(config): dedup resolver helpers and fix deferred review items (refs #301)

Author: stanlrt

docs/using-raitap/configuration/python-api.md

@@ -80,7 +80,7 @@ run(cfg, auto_install_deps=True)
 
 | YAML pattern                                                     | Python builder                                                                                                                                                                                                       |
 | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `use: captum` + `algorithm: IntegratedGradients`   | `captum(algorithm="IntegratedGradients", ...)` (the `use` key is baked in)                                                                                                                                          |
+| `use: captum` + `algorithm: IntegratedGradients`                 | `captum(algorithm="IntegratedGradients", ...)` (the `use` key is baked in)                                                                                                                                           |
 | `defaults: [raitap_schema, _self_]`                              | Not needed — `AppConfig` already *is* the schema. The defaults entry is a Hydra-only construct.                                                                                                                      |
 | Group/name selection (`transparency: captum` + dict key in YAML) | Use the dict key on the Python side too: `transparency={"my_run": captum(algorithm=...)}`.                                                                                                                           |
 | List of visualisers                                              | One builder per visualiser (`captum_image`, `image_pair`, …): flat constructor kwargs, optional `call={...}` for render-time options. `visualisers=[captum_image(max_samples=4, call={"show_sample_names": True})]`. |

src/raitap/_adapters.py

@@ -87,6 +87,11 @@ def __call__(self, ctx: CtxT, /) -> ResultT: ...
 # (:func:`raitap.configs.registry_resolve.resolve_target_fqn`). Group
 # ``"_unscoped"`` holds visualisers, which have no Hydra config group.
 _TARGET_FQN: dict[str, dict[str, str]] = {}
+# group -> FamilyConfig.package_style ("nested" | "flat"). The source of truth
+# for whether a group's Hydra config holds multiple named entries
+# (``cfg.<group>.<name>``) or a single one (``cfg.<group>``) — read by
+# :mod:`raitap._config_schema` instead of hardcoding the group set there.
+_GROUP_PACKAGE_STYLE: dict[str, str] = {}
 # adapter class name -> uv extra (consumed by raitap.deps.inference)
 ADAPTER_EXTRAS: dict[str, str] = {}
 # group -> set of wrapped third-party library names; used by
@@ -357,6 +362,7 @@ def _register_core(
             cls._adapter_group = family.group
             fqn = _class_fqn(cls)
             _TARGET_FQN.setdefault(family.group, {})[registry_name] = fqn
+            _GROUP_PACKAGE_STYLE[family.group] = family.package_style
             schema = schema_override or family.schema
             builder = _use_node(schema, registry_name, cls.__name__)
             # Hydra groups use ``/`` for nesting; OmegaConf packages use ``.``.

src/raitap/_config_schema.py

@@ -33,11 +33,30 @@
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
-# Families whose Hydra package style is "nested" (:class:`raitap._adapters.
-# FamilyConfig`, ``package_style="nested"``) — multiple named entries share
-# the group. Every other group (including ``data/labels`` / ``data/inputs``)
-# is "flat": one config per group.
-_NESTED_GROUPS = frozenset({"transparency", "robustness"})
+# Fallback only: used when a group is missing from
+# :data:`raitap._adapters._GROUP_PACKAGE_STYLE` (e.g. no adapter of that
+# family has registered yet, or the "_unscoped"/data groups, which carry no
+# ``FamilyConfig``). The live map is the source of truth — see
+# :func:`_group_is_nested`.
+_NESTED_GROUPS_FALLBACK = frozenset({"transparency", "robustness"})
+
+
+def _group_is_nested(group: str) -> bool:
+    """True when ``group``'s Hydra package style is "nested" (multiple named
+    entries share the group, e.g. ``cfg.transparency.<name>.use``).
+
+    Reads :data:`raitap._adapters._GROUP_PACKAGE_STYLE`, populated by each
+    family decorator from its own :class:`~raitap._adapters.FamilyConfig`
+    (the real source of truth), falling back to the historical hardcoded set
+    only when the group isn't recorded there (e.g. ``"_unscoped"``, ``data/*``,
+    or a family with no adapters registered yet).
+    """
+    from raitap._adapters import _GROUP_PACKAGE_STYLE
+
+    style = _GROUP_PACKAGE_STYLE.get(group)
+    if style is not None:
+        return style == "nested"
+    return group in _NESTED_GROUPS_FALLBACK
 
 
 def _use_enum_schema(registry_names: Iterable[str]) -> dict[str, Any]:
@@ -92,7 +111,7 @@ def build_config_schema() -> dict[str, Any]:
         if group == "_unscoped":
             properties["visualiser"] = _group_schema(registry_names, nested=False)
             continue
-        schema = _group_schema(registry_names, nested=group in _NESTED_GROUPS)
+        schema = _group_schema(registry_names, nested=_group_is_nested(group))
         _set_nested_property(properties, group.split("/"), schema)
 
     return {

src/raitap/configs/registry_resolve.py

@@ -39,6 +39,24 @@ def reject_config_target(cfg: Any) -> None:
             reject_config_target(item)
 
 
+def use_key_enabled(cfg: Any) -> bool:
+    """True when ``cfg`` (already ``cfg_to_dict``'d) carries a non-empty ``use``.
+
+    Shared by :func:`raitap.metrics.factory.metrics_run_enabled` and
+    :func:`raitap.reporting.factory.reporting_enabled`, which both gate an
+    optional config block on "is `use` set to a non-empty string", after
+    rejecting a ``_target_``-carrying block loudly instead of silently reading
+    it as "not configured". Callers keep their own ``None``-config
+    short-circuit (this helper assumes a non-``None`` config was already
+    turned into a dict).
+    """
+    reject_config_target(cfg)
+    use = cfg.get("use")
+    if use is None:
+        return False
+    return bool(str(use).strip())
+
+
 def resolve_target_fqn(group: str, use: str) -> str:
     from raitap._adapters import _TARGET_FQN
 
@@ -47,11 +65,32 @@ def resolve_target_fqn(group: str, use: str) -> str:
         return group_map[use]
     except KeyError:
         valid = ", ".join(sorted(group_map))
+        error_group = "visualiser" if group == "_unscoped" else group
         raise ValueError(
-            f"Unknown {group} key {use!r}. Valid keys: {valid or '(none registered)'}."
+            f"Unknown {error_group} key {use!r}. Valid keys: {valid or '(none registered)'}."
         ) from None
 
 
+def stamp_target_from_use(cfg: dict[str, Any], *, group: str) -> None:
+    """Reject ``_target_``, resolve ``cfg["use"]`` against ``group``, and stamp
+    the resolved FQN back onto ``cfg`` as ``_target_`` (popping ``use``).
+
+    Mutates ``cfg`` in place. Shared by
+    :func:`raitap.metrics.factory.create_metric`,
+    :func:`raitap.transparency.evaluation.step.grade_explanations`, and
+    :func:`raitap.data._parser_factory.create_parser`, which all resolve a
+    ``use:``-keyed config to a vetted ``_target_`` before handing it to
+    ``hydra.utils.instantiate``. Callers keep their own post-instantiate
+    tails (return shape, error wording) — this helper only covers the shared
+    reject-resolve-stamp-pop core. Preserves the security ordering: ``cfg``
+    is rejected for a smuggled ``_target_`` *before* ``use`` is resolved.
+    """
+    reject_config_target(cfg)
+    use = str(cfg.get("use", ""))
+    cfg["_target_"] = resolve_target_fqn(group, use)
+    cfg.pop("use", None)
+
+
 def instantiate_partial_from_use(
     cfg: Any,
     *,

src/raitap/data/_parser_factory.py

@@ -8,18 +8,15 @@
 
 from raitap import raitap_log
 from raitap.configs import cfg_to_dict
-from raitap.configs.registry_resolve import reject_config_target, resolve_target_fqn
+from raitap.configs.registry_resolve import stamp_target_from_use
 
 
 def create_parser(config: Any, *, group: str, kind: str) -> Any:
     """Instantiate a parser from a ``use:``-keyed config, resolved via the
     trusted registry seam (``raitap.configs.registry_resolve``)."""
     cfg = cfg_to_dict(config)
-    reject_config_target(cfg)
-    use = cfg.get("use", "")
-    fqn = resolve_target_fqn(group, use)
-    cfg["_target_"] = fqn
-    cfg.pop("use", None)
+    stamp_target_from_use(cfg, group=group)
+    fqn = cfg["_target_"]
     try:
         return instantiate(cfg)
     except Exception as e:

src/raitap/deps/static_scan.py

@@ -191,7 +191,10 @@ def scan_adapter_registry() -> dict[str, dict[str, str]]:
     the legacy ``_target_`` lookup. This scanner mirrors that: the family
     decorator name (e.g. ``robustness_adapter``) determines the group via
     :data:`_DECORATOR_GROUP`, and ``extra`` defaults to ``registry_name`` the
-    same way :func:`scan_adapter_extras` and ``_register_core`` do.
+    same way :func:`scan_adapter_extras` and ``_register_core`` do — except for
+    the ``"_unscoped"`` group (``transparency_evaluator``, ``family=None`` at
+    runtime), where ``_register_core`` gives no auto-extra at all: only an
+    explicit ``extra=`` kwarg counts, else the extra is left empty.
     """
     import raitap
 
@@ -203,8 +206,10 @@ def scan_adapter_registry() -> dict[str, dict[str, str]]:
             continue
         kwargs = _string_kwargs(deco)
         registry_name = kwargs.get("registry_name")
-        if registry_name:
-            found.setdefault(group, {})[registry_name] = kwargs.get("extra", registry_name)
+        if not registry_name:
+            continue
+        default_extra = "" if group == "_unscoped" else registry_name
+        found.setdefault(group, {})[registry_name] = kwargs.get("extra", default_extra)
     return found
 
 

src/raitap/metrics/factory.py

@@ -11,7 +11,7 @@
 
 from raitap import raitap_log
 from raitap.configs import cfg_to_dict, resolve_run_dir
-from raitap.configs.registry_resolve import reject_config_target, resolve_target_fqn
+from raitap.configs.registry_resolve import stamp_target_from_use, use_key_enabled
 from raitap.reporting.sections import Reportable, ReportGroup, ReportSection
 from raitap.reporting.staging import _copy_asset
 from raitap.tracking.base_tracker import BaseTracker, Trackable
@@ -34,24 +34,15 @@ def metrics_run_enabled(config: AppConfig) -> bool:
     metrics_cfg = config.metrics
     if metrics_cfg is None:
         return False
-    metrics_dict = cfg_to_dict(metrics_cfg)
-    # Reject a `_target_`-carrying block loudly instead of silently reading it
-    # as "not configured" — this guard gates non-schema-checked config blocks.
-    reject_config_target(metrics_dict)
-    use = metrics_dict.get("use")
-    if use is None:
-        return False
-    return bool(str(use).strip())
+    return use_key_enabled(cfg_to_dict(metrics_cfg))
 
 
 def create_metric(metrics_config: Any) -> tuple[BaseMetricComputer, str]:
     """Instantiate a metric computer from config (``use: <registry key>`` + kwargs)."""
     metrics_cfg = cfg_to_dict(metrics_config)
-    reject_config_target(metrics_cfg)
     use = str(metrics_cfg.get("use", ""))
-    resolved_target = resolve_target_fqn("metrics", use)
-    metrics_cfg["_target_"] = resolved_target
-    metrics_cfg.pop("use", None)
+    stamp_target_from_use(metrics_cfg, group="metrics")
+    resolved_target = metrics_cfg["_target_"]
 
     try:
         metric = instantiate(metrics_cfg)

src/raitap/reporting/factory.py

@@ -8,7 +8,7 @@
 
 from raitap import raitap_log
 from raitap.configs import cfg_to_dict
-from raitap.configs.registry_resolve import instantiate_partial_from_use, reject_config_target
+from raitap.configs.registry_resolve import instantiate_partial_from_use, use_key_enabled
 from raitap.tracking.base_tracker import BaseTracker, Trackable
 
 if TYPE_CHECKING:
@@ -24,14 +24,7 @@ def reporting_enabled(config: AppConfig) -> bool:
     """Check if reporting is enabled in config."""
     if config.reporting is None:
         return False
-    reporting_cfg = cfg_to_dict(config.reporting)
-    # Reject a `_target_`-carrying block loudly instead of silently reading it
-    # as "disabled" — this guard gates non-schema-checked callback configs.
-    reject_config_target(reporting_cfg)
-    use = reporting_cfg.get("use")
-    if use is None:
-        return False
-    return bool(str(use).strip())
+    return use_key_enabled(cfg_to_dict(config.reporting))
 
 
 @dataclass

src/raitap/tracking/smoke_test_mlflow.py

@@ -104,6 +104,7 @@ def main() -> int:
             num_classes=1000,
         ),
         tracking=TrackingConfig(
+            use="mlflow",
             output_forwarding_url=tracking_uri,
             log_model=args.log_model,
         ),

src/raitap/transparency/evaluation/step.py

@@ -16,7 +16,7 @@
 
 from hydra.utils import instantiate
 
-from raitap.configs.registry_resolve import reject_config_target, resolve_target_fqn
+from raitap.configs.registry_resolve import stamp_target_from_use
 from raitap.configs.utils import cfg_to_dict
 from raitap.transparency.evaluation.semantics import EvaluationContext
 
@@ -42,10 +42,7 @@ def grade_explanations(
     if evaluation_cfg is None or not explanations:
         return []
     cfg = cfg_to_dict(evaluation_cfg)
-    reject_config_target(cfg)
-    use = cfg.get("use", "")
-    cfg["_target_"] = resolve_target_fqn("_unscoped", use)
-    cfg.pop("use", None)
+    stamp_target_from_use(cfg, group="_unscoped")
     evaluator = instantiate(cfg)
     backend = prepared.backend  # type: ignore[attr-defined]
     model = backend.autograd_module()