Improve validate_applicable_state error messages - High Priority Updates (#5126)

Summary:
Pull Request resolved: #5126

Fix actively misleading or broken NotApplicableState error messages across ax/analysis:

- **utils.py**: Replace raw Python kwarg f-string syntax ({trial_indices=}, {trial_statuses=}) with readable key=value output in `validate_experiment_has_trials` messages
- **utils.py**: Remove raw Adapter repr ({adapter}) from `validate_adapter_can_predict` messages; replace with user-readable text
- **best_trials.py**: Replace backtick-quoted class names (`OptimizationConfig`, `GenerationStrategy`) with plain-language descriptions and actionable steps
- **sensitivity.py**: Replace opaque "`TorchAdapter` is required." with a message explaining what the user needs to do
- **top_surfaces.py**: Remove {type(relevant_adapter)} type repr; replace with plain-language message matching `sensitivity.py`
- **marginal_effects.py**: Fix typo "but got.'" (missing space before quote) and remove {type(parameter).`__name__`} internal class name from error message
- **objective_p_feasible_frontier.py**: Fix "Optimization_config" underscore bug (should read "optimization config"), and replace raw Adapter repr ({relevant_adapter}, {relevant_adapter.generator}) with `__name__` type strings

Audited in https://docs.google.com/document/d/1mxkLvXz0SvdWqO9UrVq5hsFY6MlcwDSk7oVRzdU6kN0/edit?tab=t.0 with the help of AI Agent

Reviewed By: bernardbeckerman

Differential Revision: D97528392

fbshipit-source-id: c4557c66977f18b545a0bb70093361b7705ff45f

Author: shrutipatel31

ax/analysis/best_trials.py

@@ -100,9 +100,9 @@ def validate_applicable_state(
         # Validate optimization config exists
         if experiment is None or experiment.optimization_config is None:
             return (
-                "`BestTrials` analysis requires an `OptimizationConfig`. "
-                "Ensure the `Experiment` has an `optimization_config` set to compute "
-                "this analysis."
+                "BestTrials requires an OptimizationConfig with defined objective(s). "
+                "Define the optimization objective during experiment setup (via "
+                "configure_optimization in the Client) before running this analysis."
             )
 
         # Check for trials with required status
@@ -121,9 +121,10 @@ def validate_applicable_state(
         if self.use_model_predictions or optimization_config.is_moo_problem:
             if generation_strategy is None:
                 return (
-                    "`BestTrials` analysis requires a `GenerationStrategy` input "
-                    "when using model predictions or for multi-objective "
-                    "optimization problems."
+                    "BestTrials requires a GenerationStrategy when using model "
+                    "predictions or for multi-objective optimization. This analysis "
+                    "requires a predictive model, which becomes available after "
+                    "enough trials have completed. Run more trials to enable it."
                 )
 
         return None

ax/analysis/plotly/marginal_effects.py

@@ -104,8 +104,9 @@ def validate_applicable_state(
                 parameter = experiment.parameters.get(param_name)
                 if not isinstance(parameter, ChoiceParameter):
                     return (
-                        "MarginalEffectsPlot is only for `ChoiceParameter`s, but got."
-                        f"'{param_name}' which is of type {type(parameter).__name__}."
+                        f"MarginalEffectsPlot is only applicable to ChoiceParameters, "
+                        f"but '{param_name}' is a {type(parameter).__name__}, not a "
+                        "ChoiceParameter. Check the experiment's parameter types."
                     )
 
     @override

ax/analysis/plotly/objective_p_feasible_frontier.py

@@ -128,7 +128,10 @@ def validate_applicable_state(
         experiment = none_throws(experiment)
 
         if experiment.optimization_config is None:
-            return "Optimization_config must be set to compute frontier."
+            return (
+                "The experiment must have an OptimizationConfig set in "
+                "order to compute the objective vs. P(feasible) frontier."
+            )
 
         if isinstance(experiment.optimization_config, MultiObjectiveOptimizationConfig):
             return "Multi-objective optimization is not supported."
@@ -158,10 +161,11 @@ def validate_applicable_state(
             relevant_adapter.generator, BoTorchGenerator
         ):
             return (
-                "The Objective vs P(feasible) plot cannot be computed using the"
-                f" current Adapter ({relevant_adapter}) and generator"
-                f" ({relevant_adapter.generator}). Only TorchAdapters using"
-                " BoTorchGenerators are supported."
+                "This plot requires a TorchAdapter using a BoTorchGenerator. "
+                f"The current adapter is a {type(relevant_adapter).__name__} with "
+                f"a {type(relevant_adapter.generator).__name__} generator. "
+                "This error will resolve once the optimization progresses "
+                "to a Bayesian modeling stage."
             )
 
     @override

ax/analysis/plotly/sensitivity.py

@@ -116,7 +116,11 @@ def validate_applicable_state(
         )
 
         if not isinstance(relevant_adapter, TorchAdapter):
-            return "TorchAdapter is required."
+            return (
+                "This analysis requires a fitted Bayesian model (TorchAdapter). "
+                "Ensure the optimization has run enough trials and the generation "
+                "strategy has reached a model-based stage."
+            )
 
     @override
     def compute(

ax/analysis/plotly/tests/test_marginal_effects.py

@@ -86,14 +86,16 @@ def test_validate_applicable_state(self) -> None:
             data=self.experiment.lookup_data(trial_indices=[0]),
         )
 
+        result = none_throws(
+            self.analysis_all_variables.validate_applicable_state(
+                experiment=self.experiment, adapter=adapter
+            )
+        )
         self.assertIn(
-            "MarginalEffectsPlot is only for `ChoiceParameter`s",
-            none_throws(
-                self.analysis_all_variables.validate_applicable_state(
-                    experiment=self.experiment, adapter=adapter
-                )
-            ),
+            "MarginalEffectsPlot is only applicable to ChoiceParameters", result
         )
+        # Verify type(parameter).__name__ rendered correctly (x is a RangeParameter)
+        self.assertIn("RangeParameter", result)
 
     def test_compute(self) -> None:
         adapter = get_thompson(

ax/analysis/plotly/tests/test_objective_p_feasible_frontier.py

@@ -162,7 +162,8 @@ def test_validate_applicable_state(self) -> None:
         opt_config = self.experiment.optimization_config
         self.experiment._optimization_config = None
         self.assertIn(
-            "Optimization_config must be set to compute frontier",
+            "The experiment must have an OptimizationConfig set in "
+            "order to compute the objective vs. P(feasible) frontier",
             none_throws(
                 ObjectivePFeasibleFrontierPlot().validate_applicable_state(
                     experiment=self.experiment
@@ -215,6 +216,24 @@ def test_validate_applicable_state(self) -> None:
             ),
         )
 
+        # Restore valid constraints and verify type().__name__ renders correctly
+        # for the adapter/generator type check
+        metric_name = self.experiment.metrics["branin_b"].name
+        opt_config.outcome_constraints = [
+            OutcomeConstraint(
+                expression=f"{metric_name} <= 10.0",
+                metric_name_to_signature={metric_name: metric_name},
+            ),
+        ]
+        adapter = Generators.SOBOL(experiment=self.experiment)
+        result = none_throws(
+            ObjectivePFeasibleFrontierPlot().validate_applicable_state(
+                experiment=self.experiment, adapter=adapter
+            )
+        )
+        self.assertIn("RandomAdapter", result)
+        self.assertIn("SobolGenerator", result)
+
     def test_scalarized_objective_raises(self) -> None:
         """Scalarized objectives should be rejected in validate_applicable_state."""
         self.experiment.optimization_config = OptimizationConfig(

ax/analysis/plotly/tests/test_sensitivity.py

@@ -251,6 +251,18 @@ def test_task_params_excluded(self) -> None:
                 exclude_task=True,
             )
 
+    def test_validate_applicable_state_non_torch_adapter(self) -> None:
+        client = get_test_client()
+        adapter = Generators.SOBOL(
+            experiment=client.experiment,
+        )
+        analysis = SensitivityAnalysisPlot(metric_name="bar")
+        reason = analysis.validate_applicable_state(adapter=adapter)
+        self.assertIn(
+            "This analysis requires a fitted Bayesian model (TorchAdapter). ",
+            none_throws(reason),
+        )
+
     def test_wrap_label(self) -> None:
         cases = [
             ("short name unchanged", "x", "x"),

ax/analysis/plotly/tests/test_top_surfaces.py

@@ -54,16 +54,17 @@ def test_validate_applicable_state(self) -> None:
                     },
                 )
 
+        result = none_throws(
+            TopSurfacesAnalysis(
+                metric_name="bar", order="first"
+            ).validate_applicable_state(client._experiment, client._generation_strategy)
+        )
         self.assertIn(
-            "TorchAdapter is required",
-            none_throws(
-                TopSurfacesAnalysis(
-                    metric_name="bar", order="first"
-                ).validate_applicable_state(
-                    client._experiment, client._generation_strategy
-                )
-            ),
+            "This analysis requires a fitted Bayesian model (TorchAdapter)",
+            result,
         )
+        # Verify type(relevant_adapter).__name__ rendered correctly
+        self.assertIn("RandomAdapter", result)
         for _ in range(5):
             for trial_index, parameterization in client.get_next_trials(
                 max_trials=1
@@ -77,7 +78,7 @@ def test_validate_applicable_state(self) -> None:
                 )
 
         self.assertIn(
-            "no data for metrics {'baz'}",
+            "Data for the following metrics is not yet available: {'baz'}",
             none_throws(
                 TopSurfacesAnalysis(
                     metric_name="baz", order="first"

ax/analysis/plotly/top_surfaces.py

@@ -112,7 +112,11 @@ def validate_applicable_state(
             )
 
             if not isinstance(relevant_adapter, TorchAdapter):
-                return f"TorchAdapter is required, found {type(relevant_adapter)}."
+                return (
+                    "This analysis requires a fitted Bayesian model (TorchAdapter). "
+                    f"The current adapter is a {type(relevant_adapter).__name__}. "
+                    "Wait for the optimization to progress to a model-based stage."
+                )
         except UserInputError as e:
             return e.message
 

ax/analysis/tests/test_best_trials.py

@@ -162,7 +162,7 @@ def test_generation_strategy_requirements(self) -> None:
                 experiment=self.experiment, generation_strategy=None
             )
             self.assertIsNotNone(error)
-            self.assertIn("requires a `GenerationStrategy`", error)
+            self.assertIn("requires a GenerationStrategy", error)
 
     def test_trial_status_filter(self) -> None:
         """Test that trial_statuses parameter filters correctly."""