Add structured AutoML report API for LLM-friendly output (#807)

Author: pplonski

examples/scripts/report_structured_classification.py

@@ -0,0 +1,43 @@
+import os
+
+from sklearn.datasets import make_classification
+
+from supervised import AutoML
+
+
+def main():
+    X, y = make_classification(
+        n_samples=300,
+        n_features=12,
+        n_informative=6,
+        n_redundant=2,
+        random_state=123,
+    )
+
+    results_path = "AutoML_report_structured_classification"
+    automl = AutoML(
+        mode="Explain",
+        total_time_limit=300,
+        results_path=results_path,
+        random_state=123,
+        verbose=0,
+    )
+    automl.fit(X, y)
+
+    print("\n=== report_structured(model_details=False) ===\n")
+    print(automl.report_structured(model_details=False))
+
+    print("\n=== report_structured(model_details=True) ===\n")
+    print(automl.report_structured(model_details=True))
+
+    payload = automl.report_structured(format="dict", model_details=False)
+    print("\nTop-level keys:", sorted(payload.keys()))
+    print("Number of models in report:", len(payload.get("models", [])))
+
+    report_path = os.path.join(results_path, "report_structured.json")
+    print("Structured report JSON:", report_path)
+    print("Exists:", os.path.exists(report_path))
+
+
+if __name__ == "__main__":
+    main()

examples/scripts/report_structured_fairness.py

@@ -0,0 +1,57 @@
+import os
+
+import pandas as pd
+from sklearn.datasets import make_classification
+
+from supervised import AutoML
+
+
+def main():
+    X, y = make_classification(
+        n_samples=300,
+        n_features=10,
+        n_informative=5,
+        n_redundant=1,
+        random_state=123,
+    )
+
+    # Construct two categorical sensitive features.
+    sensitive_features = pd.DataFrame(
+        {
+            "gender": ["female" if i % 2 == 0 else "male" for i in range(len(y))],
+            "group": ["A" if i % 3 == 0 else "B" for i in range(len(y))],
+        }
+    )
+
+    results_path = "AutoML_report_structured_fairness"
+    automl = AutoML(
+        mode="Explain",
+        total_time_limit=300,
+        fairness_metric="demographic_parity_ratio",
+        fairness_threshold=0.8,
+        privileged_groups=[{"gender": "male"}],
+        underprivileged_groups=[{"gender": "female"}],
+        results_path=results_path,
+        random_state=123,
+        verbose=0,
+    )
+    automl.fit(X, y, sensitive_features=sensitive_features)
+
+    print("\n=== report_structured(model_details=False) ===\n")
+    print(automl.report_structured(model_details=False))
+
+    print("\n=== report_structured(model_details=True) ===\n")
+    print(automl.report_structured(model_details=True))
+
+    payload = automl.report_structured(format="dict", model_details=False)
+    print("\nTop-level keys:", sorted(payload.keys()))
+    print("Number of models in report:", len(payload.get("models", [])))
+    print("Fairness summary available:", payload.get("fairness_summary") is not None)
+
+    report_path = os.path.join(results_path, "report_structured.json")
+    print("Structured report JSON:", report_path)
+    print("Exists:", os.path.exists(report_path))
+
+
+if __name__ == "__main__":
+    main()

examples/scripts/report_structured_regression.py

@@ -0,0 +1,43 @@
+import os
+
+from sklearn.datasets import make_regression
+
+from supervised import AutoML
+
+
+def main():
+    X, y = make_regression(
+        n_samples=300,
+        n_features=12,
+        n_informative=8,
+        noise=2.0,
+        random_state=123,
+    )
+
+    results_path = "AutoML_report_structured_regression"
+    automl = AutoML(
+        mode="Explain",
+        total_time_limit=300,
+        results_path=results_path,
+        random_state=123,
+        verbose=0,
+    )
+    automl.fit(X, y)
+
+    print("\n=== report_structured(model_details=False) ===\n")
+    print(automl.report_structured(model_details=False))
+
+    print("\n=== report_structured(model_details=True) ===\n")
+    print(automl.report_structured(model_details=True))
+
+    payload = automl.report_structured(format="dict", model_details=False)
+    print("\nTop-level keys:", sorted(payload.keys()))
+    print("Number of models in report:", len(payload.get("models", [])))
+
+    report_path = os.path.join(results_path, "report_structured.json")
+    print("Structured report JSON:", report_path)
+    print("Exists:", os.path.exists(report_path))
+
+
+if __name__ == "__main__":
+    main()

supervised/automl.py

@@ -535,6 +535,9 @@ def score(
     def report(self, width=900, height=1200):
         return self._report(width, height)
 
+    def report_structured(self, format="markdown", model_details=True):
+        return self._report_structured(format, model_details)
+
     def need_retrain(
         self,
         X: Union[numpy.ndarray, pandas.DataFrame],

supervised/base_automl.py

@@ -46,6 +46,11 @@
 from supervised.utils.jsonencoder import MLJSONEncoder
 from supervised.utils.leaderboard_plots import LeaderboardPlots
 from supervised.utils.metric import Metric, UserDefinedEvalMetric
+from supervised.utils.report_structured import (
+    build_structured_report,
+    save_structured_report,
+    to_markdown,
+)
 from supervised.utils.utils import dump_data, load_data
 
 logger = logging.getLogger(__name__)
@@ -2475,6 +2480,34 @@ def _report(self, width=900, height=1200):
 
         return self._show_report(main_readme_html, width, height)
 
+    def _report_structured(self, format="markdown", model_details=True):
+        self._results_path = self._get_results_path()
+        if self._fit_level != "finished":
+            self.load(self._results_path)
+        elif self._models is None or len(self._models) == 0:
+            # Handle objects where fit() returned early because results already exist.
+            # In that case, fit_level can be "finished" but models might not be loaded.
+            self.load(self._results_path)
+
+        if self._models is None or len(self._models) == 0:
+            raise AutoMLException(
+                "This model has not been fitted yet. Please call `fit()` first."
+            )
+
+        if format not in ["markdown", "dict", "json"]:
+            raise ValueError(
+                f"Wrong format '{format}'. Allowed formats are: markdown, dict, json."
+            )
+
+        payload = build_structured_report(self)
+        save_structured_report(payload, self._results_path)
+
+        if format == "dict":
+            return payload
+        if format == "json":
+            return json.dumps(payload, indent=4)
+        return to_markdown(payload, model_details)
+
     def _need_retrain(self, X, y, sample_weight, decrease):
         metric = self._best_model.get_metric()