upgini 1.2.166a4253.dev1__tar.gz → 1.2.167a4220.dev1__tar.gz

{upgini-1.2.166a4253.dev1 → upgini-1.2.167a4220.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upgini
-Version: 1.2.166a4253.dev1
+Version: 1.2.167a4220.dev1
 Summary: Intelligent data search & enrichment for Machine Learning
 Project-URL: Bug Reports, https://github.com/upgini/upgini/issues
 Project-URL: Homepage, https://upgini.com/

upgini-1.2.167a4220.dev1/src/upgini/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.2.167.a4220.dev1"

{upgini-1.2.166a4253.dev1 → upgini-1.2.167a4220.dev1}/src/upgini/features_enricher.py

@@ -32,6 +32,7 @@ from sklearn.preprocessing import OrdinalEncoder
 
 from upgini.autofe.feature import Feature
 from upgini.autofe.timeseries import TimeSeriesBase
+from upgini.autofe.utils import pydantic_dump_method
 from upgini.autofe.vector import EnsembleModel
 from upgini.data_source.data_source_publisher import CommercialSchema
 from upgini.dataset import Dataset
@@ -91,10 +92,14 @@ from upgini.utils.deduplicate_utils import (
     clean_full_duplicates,
     remove_fintech_duplicates,
 )
+from upgini.report.assemble import assemble_report_data
+from upgini.report.html import generate_html_report
 from upgini.utils.display_utils import (
     display_html_dataframe,
     do_without_pandas_limits,
+    ipython_available,
     prepare_and_show_report,
+    show_button_open_report,
     show_request_quote_button,
 )
 from upgini.utils.email_utils import (
@@ -174,6 +179,9 @@ class FeaturesEnricher(TransformerMixin):
 
     shared_datasets: list of str, optional (default=None)
         list of private shared dataset ids for custom search
+
+    reports_path: str, optional (default=None)
+        Directory for the HTML search report. Defaults to a `reports` folder in the current working directory.
     """
 
     TARGET_NAME = "target"
@@ -251,6 +259,7 @@ class FeaturesEnricher(TransformerMixin):
         sample_config: SampleConfig | None = None,
         print_trace_id: bool = False,
         print_loaded_report: bool = True,
+        reports_path: str | None = None,
         **kwargs,
     ):
         self.bundle = get_custom_bundle(custom_bundle_config)
@@ -275,6 +284,7 @@ class FeaturesEnricher(TransformerMixin):
 
         self.passed_features: list[str] = []
         self.df_with_original_index: pd.DataFrame | None = None
+        self._fit_match_search_keys: dict[str, SearchKey] | None = None
         self.fit_columns_renaming: dict[str, str] | None = None
         self.country_added = False
         self.fit_generated_features: list[str] = []
@@ -308,6 +318,7 @@ class FeaturesEnricher(TransformerMixin):
         self.relevant_data_sources: pd.DataFrame = self.EMPTY_DATA_SOURCES
         self._relevant_data_sources_wo_links: pd.DataFrame = self.EMPTY_DATA_SOURCES
         self.metrics: pd.DataFrame | None = None
+        self.metrics_metric_name: str | None = None
         self.feature_names_ = []
         self.external_source_feature_names = []
         self.feature_importances_ = []
@@ -317,6 +328,9 @@ class FeaturesEnricher(TransformerMixin):
         self.disable_force_downsampling = disable_force_downsampling
         self.print_trace_id = print_trace_id
         self.add_info: AddInfo | None = None
+        self.reports_path = reports_path
+        self.search_duration_seconds: float | None = None
+        self.report_file_path: str | None = None
 
         if search_id:
             search_task = SearchTask(search_id, rest_client=self.rest_client, logger=self.logger)
@@ -1136,18 +1150,9 @@ class FeaturesEnricher(TransformerMixin):
                     uplift_perc = None
                     enriched_estimator = None
                     ensemble_score_column = self._get_ensemble_score_column(fitting_X, fitting_enriched_X)
-                    if set(fitting_X.columns) != set(fitting_enriched_X.columns):
-                        if self.baseline_score_column is not None and ensemble_score_column is not None:
-                            self.logger.info(
-                                f"Only ensemble model returned; calculate enriched {metric} via roc_auc "
-                                f"on ensemble score column: {ensemble_score_column}"
-                            )
-                        else:
-                            self.logger.info(
-                                f"Calculate enriched {metric} on train combined "
-                                f"features: {fitting_enriched_X.columns.to_list()}"
-                            )
-                        enriched_estimator = EstimatorWrapper.create(
+
+                    def evaluate_enriched(score_column, description: str):
+                        wrapper = EstimatorWrapper.create(
                             estimator,
                             self.logger,
                             model_task_type,
@@ -1159,22 +1164,48 @@ class FeaturesEnricher(TransformerMixin):
                             text_features=text_features,
                             has_time=has_time,
                         )
-                        enriched_cv_result = enriched_estimator.cross_val_predict(
-                            fitting_enriched_X, enriched_y_sorted, ensemble_score_column
+                        cv_result = wrapper.cross_val_predict(
+                            fitting_enriched_X, enriched_y_sorted, score_column
                         )
-                        enriched_metric = enriched_cv_result.get_display_metric()
-                        updating_shaps = enriched_cv_result.shap_values
-
-                        if enriched_metric is None:
-                            self.logger.warning(
-                                f"Enriched {metric} on train combined features is None (maybe all features was removed)"
-                            )
-                            enriched_estimator = None
-                        else:
-                            self.logger.info(f"Enriched {metric} on train combined features: {enriched_metric}")
-                        if baseline_metric is not None and enriched_metric is not None:
-                            uplift = (enriched_cv_result.metric - baseline_cv_result.metric) * multiplier
-                            uplift_perc = uplift / abs(baseline_cv_result.metric) * 100
+                        display_metric = cv_result.get_display_metric()
+                        if display_metric is None:
+                            self.logger.warning(f"Enriched {metric} {description} is None")
+                            return None, None, cv_result.shap_values, None, None
+                        self.logger.info(f"Enriched {metric} {description}: {display_metric}")
+                        sample_uplift = None
+                        sample_uplift_perc = None
+                        if baseline_metric is not None:
+                            sample_uplift = (cv_result.metric - baseline_cv_result.metric) * multiplier
+                            sample_uplift_perc = sample_uplift / abs(baseline_cv_result.metric) * 100
+                        return wrapper, display_metric, cv_result.shap_values, sample_uplift, sample_uplift_perc
+
+                    if ensemble_score_column is not None:
+                        self.logger.info(
+                            f"Only ensemble model returned; calculate enriched {metric} via roc_auc "
+                            f"on ensemble score column: {ensemble_score_column}"
+                        )
+                        (
+                            enriched_estimator,
+                            enriched_metric,
+                            updating_shaps,
+                            uplift,
+                            uplift_perc,
+                        ) = evaluate_enriched(
+                            ensemble_score_column,
+                            f"on ensemble score column {ensemble_score_column}",
+                        )
+                    elif set(fitting_X.columns) != set(fitting_enriched_X.columns):
+                        self.logger.info(
+                            f"Calculate enriched {metric} on train combined "
+                            f"features: {fitting_enriched_X.columns.to_list()}"
+                        )
+                        (
+                            enriched_estimator,
+                            enriched_metric,
+                            updating_shaps,
+                            uplift,
+                            uplift_perc,
+                        ) = evaluate_enriched(None, "on train combined features")
 
                     train_metrics = {
                         self.bundle.get("quality_metrics_segment_header"): self.bundle.get(
@@ -1321,6 +1352,7 @@ class FeaturesEnricher(TransformerMixin):
                     elif uplift_col in metrics_df.columns and (metrics_df[uplift_col] < 0).any():
                         self.logger.warning("Uplift is negative")
 
+                    self.metrics_metric_name = metric
                     return metrics_df
             except Exception as e:
                 error_message = "Failed to calculate metrics" + (
@@ -1759,10 +1791,12 @@ class FeaturesEnricher(TransformerMixin):
         rows_to_drop: pd.DataFrame | None = None,
         left_columns: list[str] | None = None,
     ) -> tuple[pd.DataFrame, list[str], dict[str, SearchKey]] | None:
-        if self.df_with_original_index is None or self._search_task is None:
+        if self._search_task is None:
             return None
         if self.fit_columns_renaming is None or self.fit_search_keys is None:
             return None
+        if self.df_with_original_index is None and not self.__has_persisted_match_hashes():
+            return None
 
         fit_features = self._search_task.get_all_initial_raw_features(self._get_trace_id(), metrics_calculation=True)
         if fit_features is None or len(fit_features) == 0:
@@ -1775,6 +1809,12 @@ class FeaturesEnricher(TransformerMixin):
             ]
             self.logger.info(f"After dropping target outliers size: {len(fit_features)}")
 
+        generated_features = [self.fit_columns_renaming.get(c, c) for c in (self.fit_generated_features or [])]
+        search_keys = {self.fit_columns_renaming.get(k, k): v for k, v in self.fit_search_keys.items()}
+
+        if self.df_with_original_index is None:
+            return fit_features.rename(columns=self.fit_columns_renaming), generated_features, search_keys
+
         left = self.df_with_original_index
         if left_columns is not None:
             left = left.loc[:, left_columns]
@@ -1791,10 +1831,80 @@ class FeaturesEnricher(TransformerMixin):
             drop_system_record_id=False,
         )
         enriched_Xy = enriched_Xy.rename(columns=self.fit_columns_renaming)
-        generated_features = [self.fit_columns_renaming.get(c, c) for c in (self.fit_generated_features or [])]
-        search_keys = {self.fit_columns_renaming.get(k, k): v for k, v in self.fit_search_keys.items()}
         return enriched_Xy, generated_features, search_keys
 
+    def __has_persisted_match_hashes(self) -> bool:
+        if self.add_info is None:
+            return False
+        entity_ids = self.add_info.transform_match_entity_ids
+        hashes = self.add_info.transform_match_hashes
+        return bool(entity_ids) and bool(hashes) and len(entity_ids) == len(hashes)
+
+    def __reuse_match_columns(self, df: pd.DataFrame, search_keys: dict[str, SearchKey]) -> list[str] | None:
+        if self._search_task is None:
+            return None
+        features_for_transform = [
+            f
+            for f in self._search_task.get_features_for_transform()
+            if f not in get_derived_search_key_columns(search_keys)
+        ]
+        renaming = self.fit_columns_renaming or {}
+        reverse = {v: k for k, v in renaming.items()}
+        resolved: list[str] = []
+        for feature in features_for_transform:
+            col = feature if feature in df.columns else reverse.get(feature)
+            if col is None or col not in df.columns:
+                self.logger.info(f"Skip persisting transform match hashes: missing column {feature}")
+                return None
+            if col not in search_keys:
+                resolved.append(col)
+        match_cols = self.__transform_match_columns(search_keys, resolved)
+        missing = [c for c in match_cols if c not in df.columns]
+        if missing:
+            self.logger.info(f"Skip persisting transform match hashes: missing columns {missing}")
+            return None
+        return match_cols
+
+    def __persist_transform_match_hashes(self) -> None:
+        if self.add_info is None or self.df_with_original_index is None or self._search_task is None:
+            return
+        if ENTITY_SYSTEM_RECORD_ID not in self.df_with_original_index.columns:
+            return
+        match_cols = self.__reuse_match_columns(
+            self.df_with_original_index,
+            self._fit_match_search_keys or self.fit_search_keys or {},
+        )
+        if not match_cols:
+            return
+        match_hash = pd.util.hash_pandas_object(self.df_with_original_index[match_cols], index=False).astype("float64")
+        pairs = pd.DataFrame(
+            {
+                ENTITY_SYSTEM_RECORD_ID: self.df_with_original_index[ENTITY_SYSTEM_RECORD_ID].to_numpy(),
+                MATCH_HASH: match_hash.to_numpy(),
+            }
+        )
+        pairs = self.__dedupe_on(pairs, [ENTITY_SYSTEM_RECORD_ID])
+        pairs = self.__dedupe_on(pairs, [MATCH_HASH])
+        self.add_info.transform_match_entity_ids = [float(v) for v in pairs[ENTITY_SYSTEM_RECORD_ID].to_numpy()]
+        self.add_info.transform_match_hashes = [float(v) for v in pairs[MATCH_HASH].to_numpy()]
+        try:
+            payload = pydantic_dump_method(self.add_info)(exclude_none=True)
+            payload.pop("autodetected_search_keys", None)
+            self._search_task.update_add_info(self._get_trace_id(), payload)
+        except Exception:
+            self.logger.exception("Failed to persist transform match hashes in add_info")
+
+    def __persisted_hash_pairs(self) -> pd.DataFrame | None:
+        if not self.__has_persisted_match_hashes():
+            return None
+        pairs = pd.DataFrame(
+            {
+                ENTITY_SYSTEM_RECORD_ID: self.add_info.transform_match_entity_ids,
+                MATCH_HASH: self.add_info.transform_match_hashes,
+            }
+        )
+        return self.__dedupe_on(pairs, [MATCH_HASH])
+
     @staticmethod
     def __transform_match_columns(search_keys: dict[str, SearchKey], features_for_transform: list[str]) -> list[str]:
         return sorted(dict.fromkeys(list(search_keys.keys()) + list(features_for_transform)))
@@ -1831,41 +1941,50 @@ class FeaturesEnricher(TransformerMixin):
         feature_cols: list[str],
         enriched_Xy: pd.DataFrame,
     ) -> pd.DataFrame | None:
-        if self.df_with_original_index is None or enriched_Xy is None or len(enriched_Xy) == 0:
+        if enriched_Xy is None or len(enriched_Xy) == 0:
             return None
         if not match_columns_hashed or not feature_cols:
             return None
         if ENTITY_SYSTEM_RECORD_ID not in enriched_Xy.columns:
             return None
-        if ENTITY_SYSTEM_RECORD_ID not in self.df_with_original_index.columns:
-            return None
 
         ads_cols = [c for c in feature_cols if c in enriched_Xy.columns]
         if not ads_cols:
             return None
 
-        key_cols = [c for c in match_columns_hashed if c in self.df_with_original_index.columns]
-        if len(key_cols) != len(match_columns_hashed):
-            return None
-
         ads = self.__dedupe_on(enriched_Xy.loc[:, [ENTITY_SYSTEM_RECORD_ID] + ads_cols], [ENTITY_SYSTEM_RECORD_ID])
         covered_ids = ads[ENTITY_SYSTEM_RECORD_ID].to_numpy()
 
-        fit_keys = self.df_with_original_index.loc[:, key_cols + [ENTITY_SYSTEM_RECORD_ID]]
-        covered_mask = fit_keys[ENTITY_SYSTEM_RECORD_ID].isin(covered_ids)
-        if not covered_mask.all():
-            fit_keys = fit_keys.loc[covered_mask]
-        fit_keys = self.__dedupe_on(fit_keys, [ENTITY_SYSTEM_RECORD_ID])
-        if len(fit_keys) == 0:
+        if self.df_with_original_index is not None and ENTITY_SYSTEM_RECORD_ID in self.df_with_original_index.columns:
+            key_cols = [c for c in match_columns_hashed if c in self.df_with_original_index.columns]
+            if len(key_cols) != len(match_columns_hashed):
+                return None
+            fit_keys = self.df_with_original_index.loc[:, key_cols + [ENTITY_SYSTEM_RECORD_ID]]
+            covered_mask = fit_keys[ENTITY_SYSTEM_RECORD_ID].isin(covered_ids)
+            if not covered_mask.all():
+                fit_keys = fit_keys.loc[covered_mask]
+            fit_keys = self.__dedupe_on(fit_keys, [ENTITY_SYSTEM_RECORD_ID])
+            if len(fit_keys) == 0:
+                return None
+            aligned = self.__align_match_frame(fit_keys, df_transform, match_columns_hashed)
+            if aligned is None:
+                return None
+            match_hash = pd.util.hash_pandas_object(aligned, index=False).astype("float64")
+            lookup = ads.set_index(ENTITY_SYSTEM_RECORD_ID).reindex(fit_keys[ENTITY_SYSTEM_RECORD_ID].to_numpy())
+            lookup[MATCH_HASH] = match_hash.to_numpy()
+            lookup.reset_index(drop=True, inplace=True)
+            return self.__dedupe_on(lookup, [MATCH_HASH])
+
+        pairs = self.__persisted_hash_pairs()
+        if pairs is None:
             return None
-
-        aligned = self.__align_match_frame(fit_keys, df_transform, match_columns_hashed)
-        if aligned is None:
+        covered_mask = pairs[ENTITY_SYSTEM_RECORD_ID].isin(covered_ids)
+        if not covered_mask.all():
+            pairs = pairs.loc[covered_mask]
+        if len(pairs) == 0:
             return None
-
-        match_hash = pd.util.hash_pandas_object(aligned, index=False).astype("float64")
-        lookup = ads.set_index(ENTITY_SYSTEM_RECORD_ID).reindex(fit_keys[ENTITY_SYSTEM_RECORD_ID].to_numpy())
-        lookup[MATCH_HASH] = match_hash.to_numpy()
+        lookup = ads.set_index(ENTITY_SYSTEM_RECORD_ID).reindex(pairs[ENTITY_SYSTEM_RECORD_ID].to_numpy())
+        lookup[MATCH_HASH] = pairs[MATCH_HASH].to_numpy()
         lookup.reset_index(drop=True, inplace=True)
         return self.__dedupe_on(lookup, [MATCH_HASH])
 
@@ -2135,6 +2254,69 @@ class FeaturesEnricher(TransformerMixin):
         column = new_external[0]
         return column if self._is_ensemble_feature(column) else None
 
+    def _has_single_ensemble_score(self) -> bool:
+        return self._get_single_ensemble_score_name() is not None
+
+    def _get_single_ensemble_score_name(self) -> str | None:
+        selected = list(self.feature_names_ or [])
+        ensemble = [name for name in selected if self._is_ensemble_feature(name)]
+        if len(ensemble) != 1:
+            return None
+        etalon_columns = set()
+        if self._search_task is not None:
+            etalon_columns = {
+                meta.name
+                for meta in (self._search_task.get_all_features_metadata_v2() or [])
+                if meta.source == "etalon"
+            }
+        extras = [name for name in selected if name != ensemble[0] and name not in etalon_columns]
+        if extras:
+            return None
+        return ensemble[0]
+
+    def _reports_dir(self) -> Path:
+        return Path(self.reports_path) if self.reports_path else Path.cwd() / "reports"
+
+    def _reference_rows(self) -> int | None:
+        if self.X is None:
+            return None
+        rows = _num_samples(self.X)
+        for eval_pair in self.eval_set or []:
+            rows += _num_samples(eval_pair[0])
+        return rows
+
+    def _report_sample_names(self) -> list[str]:
+        samples = [self.bundle.get("quality_metrics_train_segment")]
+        for idx, _ in enumerate(self.eval_set or []):
+            samples.append(self.bundle.get("quality_metrics_eval_segment").format(idx + 1))
+        return samples
+
+    def _assemble_report_data(self):
+        search_id = self._search_task.search_task_id if self._search_task is not None else (self.search_id or "")
+        return assemble_report_data(
+            search_id=search_id,
+            search_keys=[str(sk) for sk in self.search_keys.values()],
+            search_duration_seconds=self.search_duration_seconds,
+            reference_rows=self._reference_rows(),
+            samples=self._report_sample_names(),
+            metrics_df=self.metrics,
+            metric_name=self.metrics_metric_name,
+            bundle=self.bundle,
+        )
+
+    def _write_score_report(self) -> str | None:
+        if self._search_task is None or not self._has_single_ensemble_score():
+            return None
+        report_data = self._assemble_report_data()
+        html = generate_html_report(report_data)
+        reports_dir = self._reports_dir()
+        reports_dir.mkdir(parents=True, exist_ok=True)
+        path = reports_dir / f"upgini-report-{report_data.metadata.search_id}.html"
+        path.write_text(html, encoding="utf-8")
+        self.report_file_path = str(path)
+        self.logger.info(f"Score report saved to {path}")
+        return self.report_file_path
+
     def _is_ensemble_feature(self, column_name: str) -> bool:
         renaming = self.fit_columns_renaming or {}
         aliases = self._column_name_aliases([column_name], renaming)
@@ -4034,8 +4216,10 @@ if response.status_code == 200:
         self._search_task = None
         self.warning_counter.reset()
         self.df_with_original_index = None
+        self._fit_match_search_keys = None
         self.__cached_sampled_datasets = dict()
         self.metrics = None
+        self.metrics_metric_name = None
         self.fit_columns_renaming = None
         self.fit_dropped_features = set()
         self.fit_generated_features = []
@@ -4280,6 +4464,8 @@ if response.status_code == 200:
 
         # TODO check that this is correct for enrichment
         self.df_with_original_index = df.copy()
+        # Search keys at this point are pre-explode; transform hashes the same grain.
+        self._fit_match_search_keys = dict(self.fit_search_keys)
         # TODO check maybe need to drop _time column from df_with_original_index
 
         df, unnest_search_keys = self._explode_multiple_search_keys(df, self.fit_search_keys, self.fit_columns_renaming)
@@ -4443,6 +4629,8 @@ if response.status_code == 200:
                 raise e
 
             self._search_task.poll_result(self._get_trace_id(), quiet=True)
+            self.__persist_transform_match_hashes()
+            self.search_duration_seconds = time.time() - start_time
 
             seconds_left = time.time() - start_time
             progress = SearchProgress(97.0, ProgressStage.GENERATING_REPORT, seconds_left)
@@ -5849,6 +6037,15 @@ if response.status_code == 200:
 
     def __show_report_button(self, display_id: str | None = None, display_handle=None):
         try:
+            report_path = self._write_score_report()
+            if report_path is not None:
+                if not ipython_available():
+                    print(f"Full report saved to {report_path}")
+                    return
+                return show_button_open_report(
+                    report_path, display_id=display_id, display_handle=display_handle
+                )
+
             eval_sets_drift_df = self._get_eval_sets_drift_summary()
 
             return prepare_and_show_report(

{upgini-1.2.166a4253.dev1 → upgini-1.2.167a4220.dev1}/src/upgini/metadata.py

@@ -395,6 +395,10 @@ class AddInfo(BaseModel):
     true_one_hot_groups: Optional[Dict[str, List[str]]] = None
     pseudo_one_hot_groups: Optional[Dict[str, List[str]]] = None
     autodetected_search_keys: Optional[Dict[str, SearchKey]] = None
+    # Unique pre-explode match hashes for transform reuse after restore (search_id).
+    # Parallel lists: entity_system_record_id[i] <-> hash[i].
+    transform_match_entity_ids: Optional[List[float]] = None
+    transform_match_hashes: Optional[List[float]] = None
 
 
 class AdsHintType(str, Enum):

upgini-1.2.167a4220.dev1/src/upgini/report/__init__.py

@@ -0,0 +1,5 @@
+from upgini.report.assemble import assemble_report_data, format_search_duration
+from upgini.report.data import ReportData
+from upgini.report.html import generate_html_report
+
+__all__ = ["ReportData", "assemble_report_data", "format_search_duration", "generate_html_report"]

upgini-1.2.167a4220.dev1/src/upgini/report/assemble.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+import pandas as pd
+
+from upgini.__about__ import __version__
+from upgini.report.data import QualitySample, ReportData, ReportMetadata
+from upgini.resource_bundle import ResourceBundle
+
+
+def format_search_duration(seconds: Optional[float]) -> Optional[str]:
+    if seconds is None:
+        return None
+    total = max(0, int(round(seconds)))
+    hours, remainder = divmod(total, 3600)
+    minutes, secs = divmod(remainder, 60)
+    if hours:
+        return f"{hours} h {minutes} min {secs} sec"
+    if minutes:
+        return f"{minutes} min {secs} sec"
+    return f"{secs} sec"
+
+
+def assemble_report_data(
+    *,
+    search_id: str,
+    search_keys: list[str],
+    generated_at: Optional[datetime] = None,
+    pylib_version: Optional[str] = None,
+    search_duration_seconds: Optional[float] = None,
+    reference_rows: Optional[int] = None,
+    samples: Optional[list[str]] = None,
+    metrics_df: Optional[pd.DataFrame] = None,
+    metric_name: Optional[str] = None,
+    bundle: ResourceBundle,
+) -> ReportData:
+    generated_at = generated_at or datetime.now(timezone.utc)
+    return ReportData(
+        metadata=ReportMetadata(
+            search_id=search_id,
+            generated_at=generated_at.strftime("%Y-%m-%d %H:%M UTC"),
+            pylib_version=pylib_version or __version__,
+            search_keys=list(search_keys or []),
+            search_duration=format_search_duration(search_duration_seconds),
+            reference_rows=reference_rows,
+            samples=list(samples or []),
+        ),
+        quality_by_sample=_quality_samples(metrics_df, metric_name, bundle),
+    )
+
+
+def _quality_samples(
+    metrics_df: Optional[pd.DataFrame], metric_name: Optional[str], bundle: ResourceBundle
+) -> list[QualitySample]:
+    if metrics_df is None or metrics_df.empty:
+        return []
+    segment_col = bundle.get("quality_metrics_segment_header")
+    uplift_col = bundle.get("quality_metrics_uplift_header")
+    uplift_pct_col = bundle.get("quality_metrics_uplift_perc_header")
+    baseline_col = bundle.get("quality_metrics_baseline_header").format(metric_name) if metric_name else None
+    enriched_col = bundle.get("quality_metrics_enriched_header").format(metric_name) if metric_name else None
+
+    samples: list[QualitySample] = []
+    for _, row in metrics_df.iterrows():
+        samples.append(
+            QualitySample(
+                evaluation_scope=(_as_str(row[segment_col]) or "") if segment_col in metrics_df.columns else "",
+                metric=metric_name or "",
+                baseline=_as_str(row[baseline_col]) if baseline_col in metrics_df.columns else None,
+                enriched=_as_str(row[enriched_col]) if enriched_col in metrics_df.columns else None,
+                uplift=_as_float(row[uplift_col]) if uplift_col in metrics_df.columns else None,
+                relative_uplift=_as_str(row[uplift_pct_col]) if uplift_pct_col in metrics_df.columns else None,
+            )
+        )
+    return samples
+
+
+def _as_str(value) -> Optional[str]:
+    return None if pd.isna(value) else str(value)
+
+
+def _as_float(value) -> Optional[float]:
+    return None if pd.isna(value) else float(value)

upgini-1.2.167a4220.dev1/src/upgini/report/data.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ReportMetadata:
+    search_id: str
+    generated_at: str
+    pylib_version: str
+    search_keys: list[str] = field(default_factory=list)
+    search_duration: Optional[str] = None
+    reference_rows: Optional[int] = None
+    samples: list[str] = field(default_factory=list)
+
+
+@dataclass
+class QualitySample:
+    evaluation_scope: str
+    metric: str
+    baseline: Optional[str] = None
+    enriched: Optional[str] = None
+    uplift: Optional[float] = None
+    relative_uplift: Optional[str] = None
+
+
+@dataclass
+class FeatureRow:
+    name: str
+    shap: Optional[float] = None
+    psi: Optional[float] = None
+    drift: Optional[float] = None
+    coverage: Optional[float] = None
+    provider: str = ""
+    source: str = ""
+    stability_status: Optional[str] = None
+
+
+@dataclass
+class SourceRow:
+    provider: str
+    source: str
+    shap_sum: Optional[float] = None
+    feature_count: Optional[int] = None
+
+
+@dataclass
+class SearchResultsSummary:
+    relevant_features: Optional[int] = None
+    model_features: Optional[int] = None
+    data_sources: Optional[int] = None
+    stable_features_share: Optional[float] = None
+
+
+@dataclass
+class ModelFeatureShap:
+    rank: int
+    feature: str
+    provider: str = ""
+    mean_abs_shap: Optional[float] = None
+
+
+@dataclass
+class ReportData:
+    metadata: ReportMetadata
+    quality_by_sample: list[QualitySample] = field(default_factory=list)
+    summary: SearchResultsSummary = field(default_factory=SearchResultsSummary)
+    features: list[FeatureRow] = field(default_factory=list)
+    sources: list[SourceRow] = field(default_factory=list)
+    autofe: list[dict[str, str]] = field(default_factory=list)
+    model_feature_shap: list[ModelFeatureShap] = field(default_factory=list)