benchbox 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

benchbox/core/base_benchmark.py

@@ -143,83 +143,105 @@ class BaseBenchmark(abc.ABC):
         Returns:
             Fully configured BenchmarkResults object
         """
-        import time
-        import uuid
-        from datetime import datetime
-
-        # Calculate basic metrics from query results
-        total_queries = len(query_results)
-        successful_queries = len([r for r in query_results if r.get("status") == "SUCCESS"])
-        failed_queries = total_queries - successful_queries
-
-        # Calculate timing metrics
-        successful_results = [r for r in query_results if r.get("status") == "SUCCESS"]
-        total_execution_time = sum(r.get("execution_time", 0.0) for r in successful_results)
-        average_query_time = total_execution_time / max(successful_queries, 1)
-
-        # Generate standard identifiers
-        execution_id = kwargs.get(
-            "execution_id",
-            f"{self.benchmark_name.lower().replace(' ', '_')}_{int(time.time())}",
+        from benchbox.core.results.builder import (
+            BenchmarkInfoInput,
+            ResultBuilder,
+            RunConfigInput,
+            normalize_benchmark_id,
+        )
+        from benchbox.core.results.models import ExecutionPhases
+        from benchbox.core.results.platform_info import PlatformInfoInput
+        from benchbox.core.results.query_normalizer import normalize_query_result
+
+        execution_metadata = execution_metadata or {}
+        benchmark_name = self.benchmark_name
+        short_name = benchmark_name[:-10] if benchmark_name.lower().endswith(" benchmark") else benchmark_name
+        benchmark_id = execution_metadata.get("benchmark_id") or normalize_benchmark_id(benchmark_name)
+
+        platform_info = kwargs.get("platform_info", {}) or {}
+        platform_input = PlatformInfoInput(
+            name=platform,
+            platform_version=platform_info.get("platform_version") or platform_info.get("version") or "unknown",
+            client_library_version=platform_info.get("client_library_version")
+            or platform_info.get("client_version")
+            or "unknown",
+            execution_mode=execution_metadata.get("mode", "sql"),
+            config=platform_info if isinstance(platform_info, dict) else {},
         )
-        timestamp = kwargs.get("timestamp", datetime.now())
 
-        from benchbox.core.results.models import BenchmarkResults
+        builder = ResultBuilder(
+            benchmark=BenchmarkInfoInput(
+                name=short_name,
+                scale_factor=self.scale_factor,
+                test_type=kwargs.get("test_execution_type", "standard"),
+                benchmark_id=benchmark_id,
+                display_name=short_name,
+            ),
+            platform=platform_input,
+            execution_id=kwargs.get("execution_id"),
+        )
 
-        result = BenchmarkResults(
-            # Core benchmark info
-            benchmark_name=self.benchmark_name,
-            platform=platform,
-            scale_factor=self.scale_factor,
-            execution_id=execution_id,
-            timestamp=timestamp,
-            # Timing and performance
-            duration_seconds=kwargs.get("duration_seconds", total_execution_time),
-            total_queries=total_queries,
-            successful_queries=successful_queries,
-            failed_queries=failed_queries,
-            query_results=query_results,
-            total_execution_time=total_execution_time,
-            average_query_time=average_query_time,
-            # Infrastructure metrics (with sensible defaults)
-            data_loading_time=kwargs.get("data_loading_time", 0.0),
-            schema_creation_time=kwargs.get("schema_creation_time", 0.0),
-            total_rows_loaded=kwargs.get("total_rows_loaded", 0),
-            data_size_mb=kwargs.get("data_size_mb", 0.0),
-            table_statistics=kwargs.get("table_statistics", {}),
-            platform_info=kwargs.get("platform_info", {}),
-            # Enhanced tracking elements
-            query_plans_captured=kwargs.get("query_plans_captured", 0),
-            plan_capture_failures=kwargs.get("plan_capture_failures", 0),
-            plan_capture_errors=kwargs.get("plan_capture_errors", []),
-            execution_phases=None,  # phases parameter is dict but field expects ExecutionPhases dataclass
-            execution_metadata=execution_metadata or {},
-            # System info (can be populated by caller)
-            system_profile=kwargs.get("system_profile", {}),
-            anonymous_machine_id=kwargs.get("anonymous_machine_id", str(uuid.uuid4())[:8]),
-            # Validation
-            validation_status=kwargs.get("validation_status", "UNKNOWN"),
-            validation_details=kwargs.get("validation_details", {}),
-            # Tuning info
-            tunings_applied=kwargs.get("tunings_applied", {}),
-            tuning_config_hash=kwargs.get("tuning_config_hash"),
-            tuning_source_file=kwargs.get("tuning_source_file"),
-            tuning_validation_status=kwargs.get("tuning_validation_status", "NOT_APPLIED"),
-            tuning_metadata_saved=kwargs.get("tuning_metadata_saved", False),
+        run_cfg = execution_metadata.get("run_config") if isinstance(execution_metadata, dict) else None
+        if isinstance(run_cfg, dict):
+            compression = run_cfg.get("compression") or {}
+            builder.set_run_config(
+                RunConfigInput(
+                    compression_type=compression.get("type"),
+                    compression_level=compression.get("level"),
+                    seed=run_cfg.get("seed"),
+                    phases=run_cfg.get("phases"),
+                    query_subset=run_cfg.get("query_subset"),
+                    tuning_mode=run_cfg.get("tuning_mode"),
+                    tuning_config=run_cfg.get("tuning_config"),
+                    platform_options=run_cfg.get("platform_options"),
+                )
+            )
+
+        for qr in query_results:
+            builder.add_query_result(normalize_query_result(qr))
+
+        table_statistics = kwargs.get("table_statistics", {}) or {}
+        for table_name, row_count in table_statistics.items():
+            builder.add_table_stats(table_name, row_count)
+
+        if kwargs.get("data_loading_time"):
+            builder.set_loading_time(float(kwargs.get("data_loading_time", 0.0)) * 1000)
+
+        builder.set_execution_metadata(execution_metadata)
+        builder.set_validation_status(kwargs.get("validation_status", "UNKNOWN"), kwargs.get("validation_details", {}))
+        builder.set_system_profile(kwargs.get("system_profile", {}))
+        builder.set_tuning_info(
+            tunings_applied=kwargs.get("tunings_applied"),
+            config_hash=kwargs.get("tuning_config_hash"),
+            source_file=kwargs.get("tuning_source_file"),
+        )
+        builder.add_plan_capture_stats(
+            kwargs.get("query_plans_captured", 0),
+            kwargs.get("plan_capture_failures", 0),
+            kwargs.get("plan_capture_errors", []),
         )
+        if kwargs.get("cost_summary"):
+            builder.set_cost_summary(kwargs.get("cost_summary"))
+
+        phases_obj = phases if isinstance(phases, ExecutionPhases) else None
+        if phases_obj:
+            builder.set_execution_phases(phases_obj)
+        if isinstance(phases, dict):
+            for phase_name, phase_data in phases.items():
+                if isinstance(phase_data, dict):
+                    builder.set_phase_status(
+                        phase_name,
+                        phase_data.get("status", "NOT_RUN"),
+                        phase_data.get("duration_ms"),
+                    )
 
         if performance_characteristics is not None:
-            result.performance_characteristics = performance_characteristics
-
-        if execution_metadata is not None:
-            result.execution_metadata = execution_metadata
+            builder.add_execution_metadata("performance_characteristics", performance_characteristics)
 
         if resource_utilization is not None:
-            result.resource_utilization = resource_utilization
-        else:
-            result.resource_utilization = {}
+            builder.add_execution_metadata("resource_utilization", resource_utilization)
 
-        return result
+        return builder.build()
 
     def create_minimal_benchmark_result(
         self,

benchbox/core/coffeeshop/queries.py

@@ -3,7 +3,7 @@
 The query set has been rewritten to operate solely on the canonical
 ``dim_locations``, ``dim_products``, and ``order_lines`` tables emitted by the
 new generator. Queries emphasise sales performance, regional trends, product
-mix, and pricing behaviour—mirroring typical analytics performed on the
+mix, and pricing behaviour - mirroring typical analytics performed on the
 reference dataset.
 """
 

benchbox/core/coffeeshop/schema.py

@@ -2,7 +2,7 @@
 
 The CoffeeShop benchmark now models the three-table star schema provided by the
 reference generator (https://github.com/JosueBogran/coffeeshopdatageneratorv2).
-The schema includes two dimensions—``dim_locations`` and ``dim_products``—and a
+The schema includes two dimensions-``dim_locations`` and ``dim_products``-and a
 single ``order_lines`` fact table that applies the required order-line
 explosion. All previous dimension tables (customers, stores, staff, time_dim)
 and the legacy ``transactions`` fact table have been removed.

benchbox/core/comparison/plotter.py

@@ -73,7 +73,7 @@ class UnifiedComparisonPlotter:
                 DistributionBoxPlot,
                 DistributionSeries,
                 PerformanceBarChart,
-                QueryVarianceHeatmap,
+                QueryHeatmap,
                 export_figure,
                 get_theme,
             )
@@ -95,7 +95,7 @@ class UnifiedComparisonPlotter:
         self._performance_bar_cls = PerformanceBarChart
         self._distribution_series_cls = DistributionSeries
         self._distribution_box_cls = DistributionBoxPlot
-        self._query_heatmap_cls = QueryVarianceHeatmap
+        self._query_heatmap_cls = QueryHeatmap
 
         for chart_type in chart_types:
             try:
@@ -198,7 +198,7 @@ class UnifiedComparisonPlotter:
         return chart.figure(), f"{self.platform_type.value}_distribution"
 
     def _render_query_heatmap(self):
-        """Render query variance heatmap."""
+        """Render query execution time heatmap."""
         # Collect all query IDs
         query_ids = sorted({qr.query_id for r in self.results for qr in r.query_results})
         if not query_ids or len(self.results) < 2:
@@ -219,7 +219,8 @@ class UnifiedComparisonPlotter:
             matrix=matrix,
             queries=query_ids,
             platforms=platform_names,
-            title=f"{type_label} Query Performance Heatmap",
+            title=f"{type_label} Query Execution Times",
+            colorbar_title="Execution Time (ms)",
         )
         return chart.figure(), f"{self.platform_type.value}_query_heatmap"
 

benchbox/core/dataframe/__init__.py

@@ -80,6 +80,19 @@ from benchbox.core.dataframe.data_loader import (
     get_tpcds_column_names,
     get_tpch_column_names,
 )
+from benchbox.core.dataframe.maintenance_interface import (
+    DELTA_LAKE_CAPABILITIES,
+    ICEBERG_CAPABILITIES,
+    PARQUET_CAPABILITIES,
+    POLARS_CAPABILITIES,
+    BaseDataFrameMaintenanceOperations,
+    DataFrameMaintenanceCapabilities,
+    DataFrameMaintenanceOperations,
+    MaintenanceOperationType,
+    MaintenanceResult,
+    TransactionIsolation,
+    get_maintenance_operations_for_platform,
+)
 from benchbox.core.dataframe.profiling import (
     ComparisonResult,
     DataFrameProfiler,
@@ -135,6 +148,19 @@ __all__ = [
     # Protocols
     "DataFrameOps",
     "DataFrameGroupBy",
+    # Maintenance Operations
+    "DataFrameMaintenanceOperations",
+    "DataFrameMaintenanceCapabilities",
+    "BaseDataFrameMaintenanceOperations",
+    "MaintenanceResult",
+    "MaintenanceOperationType",
+    "TransactionIsolation",
+    "get_maintenance_operations_for_platform",
+    # Pre-defined capabilities
+    "DELTA_LAKE_CAPABILITIES",
+    "ICEBERG_CAPABILITIES",
+    "PARQUET_CAPABILITIES",
+    "POLARS_CAPABILITIES",
     # Enums
     "JoinType",
     "AggregateFunction",

benchbox/core/dataframe/benchmark_suite.py

@@ -1478,7 +1478,7 @@ class DataFrameComparisonPlotter:
                 DistributionBoxPlot,
                 DistributionSeries,
                 PerformanceBarChart,
-                QueryVarianceHeatmap,
+                QueryHeatmap,
                 export_figure,
                 get_theme,
             )
@@ -1500,7 +1500,7 @@ class DataFrameComparisonPlotter:
         self._performance_bar_cls = PerformanceBarChart
         self._distribution_series_cls = DistributionSeries
         self._distribution_box_cls = DistributionBoxPlot
-        self._query_heatmap_cls = QueryVarianceHeatmap
+        self._query_heatmap_cls = QueryHeatmap
 
         for chart_type in chart_types:
             try:
@@ -1601,7 +1601,7 @@ class DataFrameComparisonPlotter:
         return chart.figure(), "dataframe_distribution"
 
     def _render_query_heatmap(self):
-        """Render query variance heatmap."""
+        """Render query execution time heatmap."""
         # Collect all query IDs
         query_ids = sorted({qr.query_id for r in self.results for qr in r.query_results})
         if not query_ids or len(self.results) < 2:
@@ -1621,7 +1621,8 @@ class DataFrameComparisonPlotter:
             matrix=matrix,
             queries=query_ids,
             platforms=platform_names,
-            title="DataFrame Query Performance Heatmap",
+            title="DataFrame Query Execution Times",
+            colorbar_title="Execution Time (ms)",
         )
         return chart.figure(), "dataframe_query_heatmap"
 

benchbox/core/dataframe/context.py

@@ -362,6 +362,36 @@ class DataFrameContext(Protocol):
         """
         ...
 
+    def scalar_to_df(self, data: dict[str, Any]) -> Any:
+        """Create a single-row DataFrame from scalar values.
+
+        This method creates a DataFrame with one row containing the provided
+        column-value pairs. It provides a platform-agnostic way to return
+        scalar aggregation results as DataFrames, avoiding direct imports
+        of pandas or other libraries in query implementations.
+
+        Args:
+            data: Dictionary mapping column names to scalar values.
+                  Each value should be a single scalar (int, float, str, etc.),
+                  not a list or array.
+
+        Returns:
+            DataFrame with a single row containing the scalar values
+
+        Example:
+            ```python
+            # Instead of: pd.DataFrame({"count": [len(df)]})
+            return ctx.scalar_to_df({"count": len(df)})
+
+            # Multiple columns:
+            return ctx.scalar_to_df({
+                "total_orders": len(orders),
+                "total_revenue": orders["price"].sum()
+            })
+            ```
+        """
+        ...
+
     @property
     def family(self) -> str:
         """Return the DataFrame family ('pandas' or 'expression')."""
@@ -636,6 +666,21 @@ class DataFrameContextImpl(Generic[DF], ABC):
             The scalar value
         """
 
+    @abstractmethod
+    def scalar_to_df(self, data: dict[str, Any]) -> Any:
+        """Create a single-row DataFrame from scalar values.
+
+        This method creates a DataFrame with one row containing the provided
+        column-value pairs. It provides a platform-agnostic way to return
+        scalar aggregation results as DataFrames.
+
+        Args:
+            data: Dictionary mapping column names to scalar values
+
+        Returns:
+            DataFrame with a single row containing the scalar values
+        """
+
     def to_date(self, value: str | date | datetime) -> date:
         """Convert a value to a Python date.