feat: simplify structured report with model-specific details (#808)

Author: pplonski

README.md

@@ -493,14 +493,14 @@ Each call creates/updates:
 <results_path>/report_structured.json
 ```
 
-Use the `model_details` argument to control markdown verbosity:
+Use `model_name` to display detailed metrics for one selected model:
 
 ```python
-compact = automl.report_structured(model_details=False)
-detailed = automl.report_structured(model_details=True)
+compact = automl.report_structured()
+detailed = automl.report_structured(model_name="3_Linear")
 ```
 
-The detailed markdown includes per-model metric tables, fairness details (if used), and feature importance summaries when importance files are available.
+When `model_name` is provided, the markdown includes detailed metrics, fairness details (if used), and feature importance summaries for that model.
 
 # Installation  
 

examples/scripts/report_structured_classification.py

@@ -1,3 +1,17 @@
+"""
+Example: structured report for binary classification.
+
+What this script does:
+- Trains AutoML on synthetic classification data.
+- Prints the compact structured report (leaderboard + global feature summary).
+- Selects one model name from the leaderboard and prints detailed report output
+  for that single model with `report_structured(model_name=...)`.
+
+Why this helps:
+- The compact report is easy to inspect in notebooks and by LLMs.
+- The on-demand model details keep output short unless deeper analysis is needed.
+"""
+
 import os
 
 from sklearn.datasets import make_classification
@@ -24,15 +38,22 @@ def main():
     )
     automl.fit(X, y)
 
-    print("\n=== report_structured(model_details=False) ===\n")
-    print(automl.report_structured(model_details=False))
+    print("\n=== report_structured() ===\n")
+    print(automl.report_structured())
 
-    print("\n=== report_structured(model_details=True) ===\n")
-    print(automl.report_structured(model_details=True))
-
-    payload = automl.report_structured(format="dict", model_details=False)
+    payload = automl.report_structured(format="dict")
     print("\nTop-level keys:", sorted(payload.keys()))
-    print("Number of models in report:", len(payload.get("models", [])))
+    selected_model_name = None
+    leaderboard = payload.get("leaderboard", [])
+    if len(leaderboard) > 1:
+        selected_model_name = leaderboard[1].get("name")
+    elif leaderboard:
+        selected_model_name = leaderboard[0].get("name")
+    print("Selected model:", selected_model_name)
+
+    if selected_model_name:
+        print(f"\n=== report_structured(model_name='{selected_model_name}') ===\n")
+        print(automl.report_structured(model_name=selected_model_name))
 
     report_path = os.path.join(results_path, "report_structured.json")
     print("Structured report JSON:", report_path)

examples/scripts/report_structured_fairness.py

@@ -1,3 +1,16 @@
+"""
+Example: structured report for fairness-aware classification.
+
+What this script does:
+- Trains AutoML with sensitive features and fairness constraints.
+- Prints the compact structured report output.
+- Selects one model from leaderboard and prints detailed output for that model.
+
+Why this helps:
+- Keeps default report concise.
+- Allows targeted fairness/metrics inspection only for a chosen model.
+"""
+
 import os
 
 import pandas as pd
@@ -37,16 +50,22 @@ def main():
     )
     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() ===\n")
+    print(automl.report_structured())
 
-    print("\n=== report_structured(model_details=True) ===\n")
-    print(automl.report_structured(model_details=True))
-
-    payload = automl.report_structured(format="dict", model_details=False)
+    payload = automl.report_structured(format="dict")
     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)
+    selected_model_name = None
+    leaderboard = payload.get("leaderboard", [])
+    if len(leaderboard) > 1:
+        selected_model_name = leaderboard[1].get("name")
+    elif leaderboard:
+        selected_model_name = leaderboard[0].get("name")
+    print("Selected model:", selected_model_name)
+
+    if selected_model_name:
+        print(f"\n=== report_structured(model_name='{selected_model_name}') ===\n")
+        print(automl.report_structured(model_name=selected_model_name))
 
     report_path = os.path.join(results_path, "report_structured.json")
     print("Structured report JSON:", report_path)

examples/scripts/report_structured_regression.py

@@ -1,3 +1,16 @@
+"""
+Example: structured report for regression.
+
+What this script does:
+- Trains AutoML on synthetic regression data.
+- Prints compact structured report output.
+- Selects one model from the leaderboard and prints on-demand details for that model.
+
+Why this helps:
+- Shows the default short report flow.
+- Demonstrates how to inspect one model deeply without printing all model details.
+"""
+
 import os
 
 from sklearn.datasets import make_regression
@@ -24,15 +37,22 @@ def main():
     )
     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))
+    print("\n=== report_structured() ===\n")
+    print(automl.report_structured())
 
-    payload = automl.report_structured(format="dict", model_details=False)
+    payload = automl.report_structured(format="dict")
     print("\nTop-level keys:", sorted(payload.keys()))
-    print("Number of models in report:", len(payload.get("models", [])))
+    selected_model_name = None
+    leaderboard = payload.get("leaderboard", [])
+    if len(leaderboard) > 1:
+        selected_model_name = leaderboard[1].get("name")
+    elif leaderboard:
+        selected_model_name = leaderboard[0].get("name")
+    print("Selected model:", selected_model_name)
+
+    if selected_model_name:
+        print(f"\n=== report_structured(model_name='{selected_model_name}') ===\n")
+        print(automl.report_structured(model_name=selected_model_name))
 
     report_path = os.path.join(results_path, "report_structured.json")
     print("Structured report JSON:", report_path)

supervised/automl.py

@@ -535,8 +535,8 @@ 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 report_structured(self, format="markdown", model_name=None):
+        return self._report_structured(format, model_name)
 
     def need_retrain(
         self,

supervised/base_automl.py

@@ -47,6 +47,7 @@
 from supervised.utils.leaderboard_plots import LeaderboardPlots
 from supervised.utils.metric import Metric, UserDefinedEvalMetric
 from supervised.utils.report_structured import (
+    build_compact_view,
     build_structured_report,
     save_structured_report,
     to_markdown,
@@ -2480,7 +2481,7 @@ 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):
+    def _report_structured(self, format="markdown", model_name=None):
         self._results_path = self._get_results_path()
         if self._fit_level != "finished":
             self.load(self._results_path)
@@ -2502,11 +2503,16 @@ def _report_structured(self, format="markdown", model_details=True):
         payload = build_structured_report(self)
         save_structured_report(payload, self._results_path)
 
+        try:
+            output_payload = build_compact_view(payload, model_name)
+        except ValueError as e:
+            raise AutoMLException(str(e))
+
         if format == "dict":
-            return payload
+            return output_payload
         if format == "json":
-            return json.dumps(payload, indent=4)
-        return to_markdown(payload, model_details)
+            return json.dumps(output_payload, indent=4)
+        return to_markdown(output_payload, model_name)
 
     def _need_retrain(self, X, y, sample_weight, decrease):
         metric = self._best_model.get_metric()