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

benchbox/core/write_primitives/generator.py

@@ -31,6 +31,7 @@ from benchbox.core.tpch.generator import TPCHDataGenerator
 from benchbox.utils.cloud_storage import CloudStorageGeneratorMixin, create_path_handler
 from benchbox.utils.compression_mixin import CompressionMixin
 from benchbox.utils.datagen_manifest import DataGenerationManifest, resolve_compression_metadata
+from benchbox.utils.file_format import detect_compression
 from benchbox.utils.path_utils import get_benchmark_runs_datagen_path
 from benchbox.utils.verbosity import VerbosityMixin, compute_verbosity
 
@@ -674,7 +675,8 @@ class WritePrimitivesDataGenerator(CompressionMixin, CloudStorageGeneratorMixin,
                 break
 
             # Decompress if needed based on file extension
-            if file_path.suffix == ".zst":
+            compression = detect_compression(file_path)
+            if compression == "zstd":
                 try:
                     import zstandard as zstd
 
@@ -686,14 +688,19 @@ class WritePrimitivesDataGenerator(CompressionMixin, CloudStorageGeneratorMixin,
                 except ImportError:
                     self.log_verbose(f"zstandard not available, skipping {file_path}")
                     continue
-            elif file_path.suffix == ".gz":
+            elif compression == "gzip":
                 with gzip.open(file_path, "rt", encoding="utf-8") as f:
                     rows.extend(self._parse_tbl_stream(f, limit - len(rows)))
-            elif file_path.suffix == ".bz2":
+            elif compression == "bzip2":
                 with bz2.open(file_path, "rt", encoding="utf-8") as f:
                     rows.extend(self._parse_tbl_stream(f, limit - len(rows)))
+            elif compression == "xz":
+                import lzma
+
+                with lzma.open(file_path, "rt", encoding="utf-8") as f:
+                    rows.extend(self._parse_tbl_stream(f, limit - len(rows)))
             else:
-                # Uncompressed .tbl file or numbered shard
+                # Uncompressed .tbl file or numbered shard, or unsupported compression
                 with open(file_path, encoding="utf-8") as f:
                     rows.extend(self._parse_tbl_stream(f, limit - len(rows)))
 

benchbox/mcp/__init__.py

@@ -51,7 +51,11 @@ from __future__ import annotations
 try:
     from mcp.server.fastmcp import FastMCP
 except ImportError as e:
-    raise ImportError("MCP SDK not installed. Install with: uv add benchbox --extra mcp") from e
+    raise ImportError(
+        "MCP SDK not installed. Install with:\n"
+        "  pip install 'benchbox[mcp]'  # pip/venv\n"
+        "  uv add benchbox --extra mcp  # uv project"
+    ) from e
 
 # Lazy imports to avoid circular dependencies
 __all__ = [

benchbox/mcp/errors.py

@@ -35,6 +35,7 @@ class ErrorCode(str, Enum):
     VALIDATION_INVALID_PHASE = "VALIDATION_INVALID_PHASE"
     VALIDATION_INVALID_FORMAT = "VALIDATION_INVALID_FORMAT"
     VALIDATION_UNSUPPORTED_PLATFORM = "VALIDATION_UNSUPPORTED_PLATFORM"
+    VALIDATION_UNSUPPORTED_MODE = "VALIDATION_UNSUPPORTED_MODE"
 
     # Platform errors
     PLATFORM_UNAVAILABLE = "PLATFORM_UNAVAILABLE"
@@ -89,6 +90,7 @@ ERROR_CATEGORIES: dict[ErrorCode, ErrorCategory] = {
     ErrorCode.VALIDATION_INVALID_PHASE: ErrorCategory.CLIENT,
     ErrorCode.VALIDATION_INVALID_FORMAT: ErrorCategory.CLIENT,
     ErrorCode.VALIDATION_UNSUPPORTED_PLATFORM: ErrorCategory.CLIENT,
+    ErrorCode.VALIDATION_UNSUPPORTED_MODE: ErrorCategory.CLIENT,
     # Platform errors
     ErrorCode.PLATFORM_UNAVAILABLE: ErrorCategory.PLATFORM,
     ErrorCode.PLATFORM_DEPENDENCIES_MISSING: ErrorCategory.PLATFORM,
@@ -284,6 +286,33 @@ def make_platform_error(
     )
 
 
+def make_unsupported_mode_error(
+    platform: str,
+    requested_mode: str,
+    supported_modes: list[str],
+) -> dict[str, Any]:
+    """Create an unsupported execution mode error response.
+
+    Args:
+        platform: Platform name
+        requested_mode: The mode that was requested but not supported
+        supported_modes: List of modes the platform actually supports
+
+    Returns:
+        Standardized error response.
+    """
+    return make_error(
+        ErrorCode.VALIDATION_UNSUPPORTED_MODE,
+        f"Platform '{platform}' does not support {requested_mode} mode",
+        details={
+            "platform": platform,
+            "requested_mode": requested_mode,
+            "supported_modes": supported_modes,
+        },
+        suggestion=f"Use one of: {', '.join(supported_modes)}" if supported_modes else None,
+    )
+
+
 def make_execution_error(
     message: str,
     execution_id: str | None = None,

benchbox/mcp/resources/registry.py

@@ -178,7 +178,7 @@ def register_all_resources(mcp: FastMCP) -> None:
                 "description": metadata.get("description", ""),
                 "category": metadata.get("category", "unknown"),
                 "available": info.available if info else False,
-                "recommended": metadata.get("recommended", False),
+                "adoption": metadata.get("adoption", "niche"),
                 "installation_command": metadata.get("installation_command", ""),
                 "capabilities": {
                     "supports_sql": capabilities.get("supports_sql", False),
@@ -207,7 +207,11 @@ def register_all_resources(mcp: FastMCP) -> None:
                 }
             )
 
-        result_files = list(results_dir.glob("*.json"))
+        result_files = [
+            path
+            for path in results_dir.glob("*.json")
+            if not path.name.endswith(".plans.json") and not path.name.endswith(".tuning.json")
+        ]
         runs = []
 
         for file_path in sorted(result_files, key=lambda p: p.stat().st_mtime, reverse=True)[:20]:
@@ -215,14 +219,15 @@ def register_all_resources(mcp: FastMCP) -> None:
                 with open(file_path) as f:
                     data = json.load(f)
 
+                benchmark_block = data.get("benchmark", {}) if isinstance(data.get("benchmark"), dict) else {}
                 runs.append(
                     {
                         "file": file_path.name,
-                        "platform": data.get("platform", {}).get("type", "unknown"),
-                        "benchmark": data.get("benchmark", "unknown"),
-                        "scale_factor": data.get("scale_factor", "unknown"),
-                        "timestamp": data.get("timestamp"),
-                        "execution_id": data.get("execution_id", "unknown"),
+                        "platform": data.get("platform", {}).get("name", "unknown"),
+                        "benchmark": benchmark_block.get("id", "unknown"),
+                        "scale_factor": benchmark_block.get("scale_factor", "unknown"),
+                        "timestamp": data.get("run", {}).get("timestamp"),
+                        "execution_id": data.get("run", {}).get("id", "unknown"),
                     }
                 )
             except Exception as e:

benchbox/mcp/schemas.py

@@ -174,6 +174,32 @@ def validate_filename(filename: str) -> str:
     return filename
 
 
+MODE_CHOICES = ("sql", "dataframe", "data_only")
+
+
+def validate_mode(mode: str | None) -> str | None:
+    """Validate execution mode value.
+
+    Args:
+        mode: Execution mode to validate ('sql', 'dataframe', or 'data_only')
+
+    Returns:
+        Lowercased, validated mode or None if input is None
+
+    Raises:
+        MCPValidationError: If mode is invalid
+    """
+    if mode is None:
+        return None
+    mode_lower = mode.strip().lower()
+    # Normalize aliases
+    if mode_lower in ("datagen", "generate"):
+        mode_lower = "data_only"
+    if mode_lower not in MODE_CHOICES:
+        raise MCPValidationError(f"Invalid mode: {mode}. Must be 'sql', 'dataframe', or 'data_only'")
+    return mode_lower
+
+
 def validate_scale_factor(scale_factor: float) -> float:
     """Validate a scale factor.
 
@@ -211,6 +237,13 @@ class RunBenchmarkInput(BaseModel):
     scale_factor: Annotated[float, Field(gt=0, le=MAX_SCALE_FACTOR, default=0.01, description="Data scale factor")]
     queries: Annotated[str | None, Field(default=None, max_length=2000, description="Comma-separated query IDs")]
     phases: Annotated[str | None, Field(default=None, max_length=200, description="Comma-separated phase names")]
+    mode: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Execution mode: 'sql', 'dataframe', or 'data_only'. Uses platform default if not specified.",
+        ),
+    ] = None
 
     @field_validator("platform")
     @classmethod
@@ -235,6 +268,11 @@ class RunBenchmarkInput(BaseModel):
             validate_query_list(v)
         return v
 
+    @field_validator("mode")
+    @classmethod
+    def validate_mode_field(cls, v: str | None) -> str | None:
+        return validate_mode(v)
+
 
 class DryRunInput(BaseModel):
     """Input schema for dry_run tool."""
@@ -245,6 +283,13 @@ class DryRunInput(BaseModel):
     benchmark: Annotated[str, Field(min_length=1, max_length=50, description="Benchmark name")]
     scale_factor: Annotated[float, Field(gt=0, le=MAX_SCALE_FACTOR, default=0.01, description="Data scale factor")]
     queries: Annotated[str | None, Field(default=None, max_length=2000, description="Comma-separated query IDs")]
+    mode: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Execution mode: 'sql', 'dataframe', or 'data_only'. Uses platform default if not specified.",
+        ),
+    ] = None
 
     @field_validator("platform")
     @classmethod
@@ -268,6 +313,11 @@ class DryRunInput(BaseModel):
             validate_query_list(v)
         return v
 
+    @field_validator("mode")
+    @classmethod
+    def validate_mode_field(cls, v: str | None) -> str | None:
+        return validate_mode(v)
+
 
 class ValidateConfigInput(BaseModel):
     """Input schema for validate_config tool."""
@@ -277,6 +327,13 @@ class ValidateConfigInput(BaseModel):
     platform: Annotated[str, Field(min_length=1, max_length=50, description="Target database platform")]
     benchmark: Annotated[str, Field(min_length=1, max_length=50, description="Benchmark name")]
     scale_factor: Annotated[float, Field(gt=0, le=MAX_SCALE_FACTOR, default=1.0, description="Data scale factor")]
+    mode: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Execution mode: 'sql', 'dataframe', or 'data_only'. Uses platform default if not specified.",
+        ),
+    ] = None
 
     @field_validator("platform")
     @classmethod
@@ -293,6 +350,11 @@ class ValidateConfigInput(BaseModel):
     def validate_sf(cls, v: float) -> float:
         return validate_scale_factor(v)
 
+    @field_validator("mode")
+    @classmethod
+    def validate_mode_field(cls, v: str | None) -> str | None:
+        return validate_mode(v)
+
 
 class GetBenchmarkInfoInput(BaseModel):
     """Input schema for get_benchmark_info tool."""

benchbox/mcp/server.py

@@ -17,10 +17,11 @@ from mcp.server.fastmcp import FastMCP
 
 from benchbox.mcp.prompts import register_all_prompts
 from benchbox.mcp.resources import register_all_resources
-from benchbox.mcp.tools.analytics import register_analytics_tools, register_historical_tools
-from benchbox.mcp.tools.benchmark import register_benchmark_tools, register_datagen_tools
-from benchbox.mcp.tools.discovery import register_dependency_tools, register_discovery_tools
+from benchbox.mcp.tools.analytics import register_analytics_tools
+from benchbox.mcp.tools.benchmark import register_benchmark_tools
+from benchbox.mcp.tools.discovery import register_discovery_tools
 from benchbox.mcp.tools.results import register_results_tools
+from benchbox.mcp.tools.visualization import register_visualization_tools
 
 # Configure logging to stderr (stdout is reserved for MCP JSON-RPC)
 logging.basicConfig(
@@ -43,18 +44,26 @@ def create_benchbox_server() -> FastMCP:
     Returns:
         Configured FastMCP server instance.
     """
+    # Suppress all console output - MCP servers must not write to stdout
+    # (stdout is reserved exclusively for JSON-RPC messages)
+    from benchbox.utils.printing import set_quiet
+
+    set_quiet(True)
+
     # Create the FastMCP server
     mcp = FastMCP(
         name="benchbox",
         instructions="""BenchBox is a SQL benchmarking framework for OLAP databases.
 
 Use these tools to:
-1. **Discover** available platforms and benchmarks (list_platforms, list_benchmarks)
-2. **Run** benchmarks with specific configurations (run_benchmark, dry_run)
-3. **Analyze** results and compare runs (get_results, compare_results)
+1. **Discover** available platforms and benchmarks (list_available, get_benchmark_info)
+2. **Run** benchmarks with specific configurations (run_benchmark with dry_run/validate_only flags)
+3. **Analyze** results and compare runs (get_results, analyze_results)
+4. **Visualize** results with charts (generate_chart, suggest_charts)
 
 Start by listing available benchmarks or platforms to see what's possible.
 For a quick test, try: run_benchmark(platform="duckdb", benchmark="tpch", scale_factor=0.01)
+Then visualize: generate_chart(result_files="<result_file>", chart_type="performance_bar")
 """,
     )
 
@@ -62,23 +71,17 @@ For a quick test, try: run_benchmark(platform="duckdb", benchmark="tpch", scale_
     logger.info("Registering discovery tools...")
     register_discovery_tools(mcp)
 
-    logger.info("Registering dependency tools...")
-    register_dependency_tools(mcp)
-
     logger.info("Registering benchmark execution tools...")
     register_benchmark_tools(mcp)
 
-    logger.info("Registering data generation tools...")
-    register_datagen_tools(mcp)
-
     logger.info("Registering results tools...")
     register_results_tools(mcp)
 
     logger.info("Registering analytics tools...")
     register_analytics_tools(mcp)
 
-    logger.info("Registering historical analysis tools...")
-    register_historical_tools(mcp)
+    logger.info("Registering visualization tools...")
+    register_visualization_tools(mcp)
 
     logger.info("Registering resources...")
     register_all_resources(mcp)

benchbox/mcp/tools/__init__.py

@@ -7,6 +7,7 @@ Tools are organized into modules:
 - discovery: Platform and benchmark discovery (list_platforms, list_benchmarks, etc.)
 - benchmark: Benchmark execution (run_benchmark, dry_run, validate_config)
 - results: Results management (get_results, compare_results, export_results)
+- visualization: Chart generation (generate_chart, generate_chart_set, compare_results_chart)
 
 Copyright 2026 Joe Harris / BenchBox Project
 
@@ -16,9 +17,11 @@ Licensed under the MIT License. See LICENSE file in the project root for details
 from benchbox.mcp.tools.benchmark import register_benchmark_tools
 from benchbox.mcp.tools.discovery import register_discovery_tools
 from benchbox.mcp.tools.results import register_results_tools
+from benchbox.mcp.tools.visualization import register_visualization_tools
 
 __all__ = [
     "register_discovery_tools",
     "register_benchmark_tools",
     "register_results_tools",
+    "register_visualization_tools",
 ]