sqlbenchdag 0.1.0__py3-none-any.whl

sql_benchmarks/assets/ingestion_factory.py

@@ -0,0 +1,88 @@
+import os
+import yaml
+from dagster import asset, AssetExecutionContext
+from typing import List
+from ..constants import DATA_DIR, EXPERIMENTS_DIR, ACTIVE_CONFIG_PATH
+from ..partitions import partitions_def
+from ..utils.common import load_context, get_engine_asset_prefix, get_scoped_asset_name
+
+CTX = load_context()
+ACTIVE_ENGINES = CTX.get('engines', []) 
+EXP_ID = CTX['meta'].get("experiment_id", "unknown")
+
+def load_dataset_config():
+    """Reads the active experiment YAML to find the tables configured for the dataset."""
+    config_path = ACTIVE_CONFIG_PATH
+    if not os.path.exists(config_path):
+        return {}
+    with open(config_path, "r") as f:
+        conf = yaml.safe_load(f) or {}
+    return conf.get("dataset", {}).get("tables", {})
+
+TABLES_CONFIG = load_dataset_config()
+
+ingestion_assets: List[object] = []
+
+def make_ingestion_asset(engine: str, table_name: str):
+    """
+    Creates a single ingestion asset for a given engine and table, 
+    delegating execution to the engine's bulk_load method.
+    """
+    prefix = get_engine_asset_prefix(engine)
+    base_asset_name = f"{prefix}{table_name}_table"
+    scoped_name = get_scoped_asset_name(base_asset_name, EXP_ID)
+
+    tags = {}
+    tags["experiment_scope"] = "partitioned"  
+    
+    deps = [
+        get_scoped_asset_name(f"{table_name}_parquet", EXP_ID),
+        get_scoped_asset_name(f"{table_name}_quality", EXP_ID)
+    ]
+
+    @asset(
+        name=scoped_name,
+        group_name="ingestion",
+        partitions_def=partitions_def,
+        deps=deps, 
+        required_resource_keys={engine},
+        op_tags=tags
+    )
+    def _ingest(context: AssetExecutionContext):
+        partition_key = context.partition_key
+        
+        # 1. Dynamic Resource Retrieval (Polymorphic)
+        db = getattr(context.resources, engine)
+        
+        # 2. FIND THE EXACT FILE
+        filename = f"{table_name}_{partition_key}.parquet"
+        parquet_path = os.path.join(DATA_DIR, "staging", filename)
+        
+        if not os.path.exists(parquet_path):
+             raise FileNotFoundError(f"Parquet file not found: {parquet_path}")
+        
+        # 3. DEFINE TARGET TABLE NAME
+        target_table_name = f"{table_name}_{partition_key}"
+        
+        context.log.info(f"Ingesting {parquet_path} into {engine} table '{target_table_name}'...")
+
+        # 4. Use the polymorphic bulk_load method
+        db.bulk_load(
+            filepath=parquet_path,
+            table_name=target_table_name,
+            partition_key=partition_key,
+            table_def=TABLES_CONFIG.get(table_name),
+        )
+        
+        return None 
+
+    return _ingest
+
+
+# --- Dynamic Asset Creation ---
+# Loop 1: Iterate over the configured engines (e.g., duckdb, postgres)
+for engine in ACTIVE_ENGINES:
+    # Loop 2: Iterate over the correct list of table names from your verified config logic
+    for table_name in TABLES_CONFIG.keys():
+        asset_obj = make_ingestion_asset(engine, table_name)
+        ingestion_assets.append(asset_obj)

sql_benchmarks/assets/maintenance.py

@@ -0,0 +1,63 @@
+import shutil
+import os
+from dagster import asset
+from ..constants import DATA_DIR
+
+# We define this asset to depend on the LAST step of the pipeline.
+# Usually, this is the Reporting/Dashboard asset, or the Benchmarks themselves.
+# Since reporting aggregates everything, depending on 'performance_dashboard' 
+# ensures the run is fully complete before we wipe the source data.
+# Note: You need to import the upstream asset key or use string reference.
+
+@asset(
+    group_name="maintenance",
+    deps=["performance_dashboard"],  # Runs ONLY after the dashboard is updated
+    description="Deletes the heavy staging Parquet files after a successful run."
+)
+def cleanup_staging_data(context):
+    """
+    Removes the generated parquet files to prevent disk overflow.
+    This runs per-partition if your job is partitioned, or once per run.
+    """
+    # 1. Identify the Target Directory
+    # We need to be careful not to delete the 'results' folder, only 'staging'.
+    # Assuming DATA_DIR points to 'experiments/data' or similar.
+    
+    # If we are in a partitioned run, we might want to delete only that partition's data.
+    if context.has_partition_key:
+        partition = context.partition_key
+        # Assuming data_factory creates a folder named after the partition or table
+        # This requires knowing exactly how data_factory names its output.
+        # Based on previous code: output_dir = os.path.join(DATA_DIR, partition_key)
+        
+        target_dir = os.path.join(DATA_DIR, partition)
+        
+        if os.path.exists(target_dir):
+            context.log.info(f"Partitioned Run: Deleting staging data at {target_dir}")
+            shutil.rmtree(target_dir)
+        else:
+            context.log.warning(f"Target dir {target_dir} not found. Already cleaned?")
+            
+    else:
+        # Non-partitioned run (Standard cleanup)
+        # We assume standard structure creates subfolders in DATA_DIR
+        # DANGER: Be specific. Don't just wipe DATA_DIR if it contains results.
+        
+        # Let's list the subdirectories in DATA_DIR and assume they are data folders
+        # generated by the factory.
+        if os.path.exists(DATA_DIR):
+            context.log.info(f"Full Run: Cleaning up staging directory {DATA_DIR}")
+            
+            # Option A: Delete everything inside DATA_DIR
+            # shutil.rmtree(DATA_DIR)
+            # os.makedirs(DATA_DIR) # Recreate empty folder
+            
+            # Option B (Safer): Delete specific known subfolders if possible.
+            # For now, since this is staging, Option A is acceptable IF results are stored elsewhere.
+            # (Your results are likely in 'experiments/results', right?)
+            
+            for item in os.listdir(DATA_DIR):
+                item_path = os.path.join(DATA_DIR, item)
+                if os.path.isdir(item_path):
+                    shutil.rmtree(item_path)
+                    context.log.info(f"Deleted {item}")

sql_benchmarks/assets/reporting.py

@@ -0,0 +1,385 @@
+import os
+import polars as pl
+import pandas as pd
+import plotly.express as px
+from dagster import asset, AssetExecutionContext, MetadataValue, MaterializeResult, DagsterEventType, EventRecordsFilter
+
+from ..constants import RESULTS_DIR, REPORTS_DIR
+from ..utils.common import load_context
+from .benchmark_factory import benchmark_assets
+import glob
+import json
+
+all_benchmark_keys = [k.key for k in benchmark_assets]
+
+# ==========================================
+# 1. PURE LOGIC (Testable)
+# ==========================================
+    # Use environment-aware path resolution
+def parse_fragments_to_records(experiment_id):
+    """
+    Scans the results directory for the given experiment_id
+    and parses all fragment JSONs into a flat list of records.
+    """
+    # Look into the isolated experiment folder as per specification
+    fragments_pattern = os.path.join(RESULTS_DIR, experiment_id, "fragments", "*.json")
+    fragment_files = glob.glob(fragments_pattern)
+    
+    records = []
+    
+    for fpath in fragment_files:
+        try:
+            with open(fpath, "r") as f:
+                data = json.load(f)
+            
+            meta = data.get("meta", {})
+            metrics = data.get("metrics", {})
+            params = data.get("parameters", {})
+            
+            if meta.get("experiment_id") != experiment_id:
+                continue
+
+            asset_name = meta.get("asset", "unknown_asset")
+            
+            # Extract Partition from Filename: asset_name__PARTITION.json
+            filename = os.path.basename(fpath)
+            partition_name = "default"
+            
+            # Logic: Split by asset_name + "__"
+            # It's safer to use the known separator "__"
+            if "__" in filename:
+                # Remove extension
+                name_no_ext = os.path.splitext(filename)[0]
+                parts = name_no_ext.split("__")
+                if len(parts) >= 2:
+                    partition_name = parts[-1]
+            
+            # DNF fragments have duration_seconds=None; preserve as None in the CSV
+            # so downstream analysis can distinguish "timed out" from "0ms".
+            raw_duration = metrics.get("duration_seconds")
+            duration_val = float(raw_duration) if raw_duration is not None else None
+
+            # Per-replication spread (older fragments lack durations_raw)
+            raw_list = metrics.get("durations_raw") or []
+            duration_min = min(raw_list) if raw_list else duration_val
+            duration_max = max(raw_list) if raw_list else duration_val
+
+            row = {
+                "Asset": asset_name,
+                "Partition": partition_name,
+                "Duration": duration_val,
+                "Duration_Min": duration_min,
+                "Duration_Max": duration_max,
+                "DNF": bool(metrics.get("dnf", False)),
+                "Engine": str(meta.get("engine", "Unknown")),
+                # None (blank in CSV) when the experiment has no 'rows'
+                # dimension (e.g. TPC-H uses scale_factor) — 0 must never
+                # be the disguise for "absent".
+                "Rows": int(params["rows"]) if "rows" in params else None,
+                "Selectivity": float(params.get("derived_selectivity", 0.0) or 0.0)
+            }
+            # Note: the old 'System' column (engine + disk_type label) was
+            # removed as a duplicate of 'Engine'; disk_type survives as its
+            # own column via the parameter merge below.
+
+            # Merge ALL parameters into the row (Dynamic Columns)
+            # This ensures 'null_probability' etc appear in CSV.
+            # Case-insensitive guard: 'rows' must not duplicate 'Rows'.
+            existing = {c.lower() for c in row}
+            for k, v in params.items():
+                if k.lower() not in existing:
+                    row[k] = v
+
+            records.append(row)
+            
+        except Exception as e:
+            print(f"Skipping malformed fragment {fpath}: {e}")
+            continue
+            
+    return records
+
+# ==========================================
+# 2. THE ASSET (Orchestration)
+# ==========================================
+@asset(
+    deps=all_benchmark_keys,
+    group_name="reporting",
+    description="Generates a Multi-View Dashboard."
+)
+def performance_dashboard(context: AssetExecutionContext):
+    instance = context.instance
+    try:
+        CTX = load_context()
+        EXP_ID = CTX['meta'].get("experiment_id", "unknown")
+    except Exception:
+        context.log.warning("Could not read active context.")
+        return
+
+    # 1. FETCH & PARSE (New Logic)
+    records = parse_fragments_to_records(EXP_ID)
+
+    if not records:
+        context.log.info(f"No records found for experiment: {EXP_ID}")
+        return
+
+    # 3. PREPARE DATA
+    df = pl.DataFrame(records)
+    
+    # Deduplicate: Keep last run for same (Asset, Partition, Engine)
+    # Rows might technically differ but Partition should cover it.
+    unique_keys = ["Asset", "Partition", "Engine", "Rows"]
+    # Filter keys that actually exist (to be safe if Partition is missing in legacy)
+    unique_keys = [k for k in unique_keys if k in df.columns]
+    
+    df = df.unique(subset=unique_keys, keep="last").sort("Rows")
+    pldf = df.to_pandas()
+
+    # 3.5 SANITIZE DATA (The "Gas in the Trunk")
+    # ------------------------------------------
+    # Drop columns that are effectively "Null" or "Default" across the entire dataset
+    # This prevents "Selectivity=0.0" from appearing in titles when it wasn't used.
+    
+    cols_to_drop = []
+    for col in pldf.columns:
+        if col in ["Asset", "Engine", "Partition", "Duration"]:
+            continue
+            
+        # Check if column is all null or all default (0.0 for float, 0 for int)
+        is_all_null = pldf[col].isnull().all()
+        is_all_zero = (pldf[col] == 0).all() and pd.api.types.is_numeric_dtype(pldf[col])
+        is_single_value = pldf[col].nunique() <= 1
+        
+        # Heuristic: If it's 0 everywhere, it's likely a parser default, UNLESS it's "Rows" (which shouldn't be 0)
+        # or if the user explicitly set 0. But for Selectivity/Skew, 0 is often "Not Used".
+        if col != "Rows" and (is_all_null or is_all_zero):
+             cols_to_drop.append(col)
+        # Also drop constant columns from the "Matrix Params" consideration (but keep in DF for reference if needed?)
+        # Actually, simpler to just drop them from the DF used for plotting considerations.
+    
+    if cols_to_drop:
+        context.log.info(f"Dropping irrelevant/default columns: {cols_to_drop}")
+        pldf = pldf.drop(columns=cols_to_drop)
+
+    # Fill NaNs in remaining parameters to prevent fragmentation
+    # e.g. if 'null_probability' is present in some rows but NaN in others, fill with 0 via Polars upstream or Pandas here.
+    # For numeric params, 0 is usually safe default for "parameter not present".
+    numeric_cols = pldf.select_dtypes(include=['number']).columns
+    pldf[numeric_cols] = pldf[numeric_cols].fillna(0)
+
+    # 4. RENDER (Visualization - Matrix Explorer)
+    figures_html = []
+    
+    # Identify Matrix Parameters (numeric columns that aren't fixed labels)
+    excluded_cols = {"Asset", "Partition", "Duration", "Duration_Min", "Duration_Max", "Engine"}
+    matrix_params = [c for c in pldf.columns if c not in excluded_cols and pd.api.types.is_numeric_dtype(pldf[c])]
+    
+    context.log.info(f"Matrix Params Detected: {matrix_params}")
+    if "null_probability" in pldf.columns:
+         context.log.info(f"Unique Null Probs: {pldf['null_probability'].unique().tolist()}")
+
+    # -------------------------------------------------------------------------
+    # 1. Comparison by Engine (The Basics)
+    # -------------------------------------------------------------------------
+    try:
+        # Side-by-Side Engine Comparison (Fixed Rows Scaling)
+        # Check if "Rows" is a parameter, as it's the standard X-axis
+        if "Rows" in matrix_params:
+             fig_compare = px.line(
+                pldf, 
+                x="Rows", 
+                y="Duration", 
+                color="Engine", 
+                line_dash="Asset", 
+                symbol="Engine",
+                log_x=True,
+                log_y=True,
+                markers=True,
+                title="<b>Global Comparison</b>: Engine Scaling (Rows vs Duration)"
+            )
+             figures_html.append(fig_compare.to_html(full_html=False, include_plotlyjs='cdn'))
+    except Exception as e:
+         context.log.warning(f"Global Plot Error: {e}")
+
+    # -------------------------------------------------------------------------
+    # 2. DYNAMIC DISCOVERY ENGINE (The "Smart Logic")
+    # -------------------------------------------------------------------------
+    unique_systems = sorted(pldf["Engine"].unique())
+    
+    for system in unique_systems:
+        system_df = pldf[pldf["Engine"] == system].copy()
+        
+        # A. Discover Roles
+        # -----------------
+        # Candidates for X-Axis: Numeric params with > 1 unique value
+        x_candidates = []
+        for p in matrix_params:
+            if system_df[p].nunique() > 1:
+                x_candidates.append(p)
+        
+        # Heuristic: Prefer "Rows" if available, else param with max cardinality
+        if "Rows" in x_candidates:
+            x_axis = "Rows"
+        elif x_candidates:
+            # Pick max cardinality
+            x_axis = max(x_candidates, key=lambda c: system_df[c].nunique())
+        else:
+            # Fallback if nothing varies (single point)
+            x_axis = matrix_params[0] if matrix_params else "Asset"
+
+        # B. Classify Remaining Parameters (Series vs Slices)
+        # ---------------------------------------------------
+        other_params = [p for p in matrix_params if p != x_axis]
+        
+        # Slices: High Cardinality OR Orthogonal Dimensions we want to isolate
+        # Series: Low Cardinality dimensions we want to compare on one chart
+        
+        slice_params = []
+        series_params = ["Asset"] # Always compare Assets (Logic) on same chart
+        
+        for p in other_params:
+            # Exclude parameters that are just case variants of X-Axis (Rows vs rows)
+            if p.lower() == x_axis.lower():
+                continue
+                
+            unique_count = system_df[p].nunique()
+            # If it has only 1 value, it doesn't matter (it's fixed context), 
+            # but we can treat it as a Slice to be safe/explicit in title.
+            # If it has many values (>5), slice it to avoid clutter.
+            # If it has few values (2-5), add to SERIES (lines).
+            if unique_count > 5:
+                slice_params.append(p)
+            elif unique_count > 1:
+                series_params.append(p)
+            else:
+                # It's a fixed value, add to slice context implicitly
+                slice_params.append(p)
+
+        # C. Generate Plots via Slicing
+        # -----------------------------
+        # Group by all slice parameters to create distinct scenarios
+        if slice_params:
+            # Sort to ensure consistent grouping order
+            slice_params = sorted(slice_params)
+            grouped = system_df.groupby(slice_params)
+        else:
+            grouped = [((), system_df)]
+
+        for group_keys, slice_df in grouped:
+            if not isinstance(group_keys, tuple):
+                group_keys = (group_keys,)
+            
+            # 1. Build Title
+            title_parts = [f"<b>{system}</b>: Varying <b>{x_axis}</b>"]
+            if slice_params:
+                ctx_str = ", ".join([f"{k}={v}" for k, v in zip(slice_params, group_keys)])
+                title_parts.append(f"<span style='font-size:12px'>({ctx_str})</span>")
+            title = "<br>".join(title_parts)
+
+            # 2. Construct Series Column (Legend)
+            # Combine all series params into one string column "Series"
+            # e.g. "2VL - 10% Nulls"
+            slice_df = slice_df.copy()
+            
+            if len(series_params) > 1:
+                # We have multiple dimensions (Asset + NullProb + ...)
+                # Create a composite key
+                def make_series_label(row):
+                    parts = []
+                    for sp in series_params:
+                        val = row[sp]
+                        # Beautify: If val is float, format it? 
+                        # For now, simplistic str()
+                        parts.append(str(val))
+                    return " / ".join(parts)
+                
+                slice_df["_Series_"] = slice_df.apply(make_series_label, axis=1)
+                color_col = "_Series_"
+                symbol_col = "Asset" # Keep using Asset for symbol if present
+            else:
+                # Simple case: Only Asset varies
+                slice_df["_Series_"] = slice_df[series_params[0]].astype(str)
+                color_col = "_Series_"
+                symbol_col = "_Series_"
+
+            try:
+                # 3. Plot
+                scenario_df = slice_df
+                scenario_df = scenario_df.sort_values(by=x_axis)
+                
+                fig = px.line(
+                    scenario_df,
+                    x=x_axis,
+                    y="Duration",
+                    color=color_col,
+                    symbol=symbol_col if symbol_col in slice_df.columns else None,
+                    markers=True,
+                    log_y=True,
+                    log_x=True if "Rows" in x_axis or "null" in x_axis.lower() else False,
+                    title=title,
+                    labels={x_axis: x_axis, "Duration": "Duration (s)", "_Series_": " / ".join(series_params)}
+                )
+                figures_html.append(fig.to_html(full_html=False, include_plotlyjs=False))
+            except Exception as e:
+                context.log.warning(f"Dynamic Plot Error ({system}): {e}")
+
+    # -------------------------------------------------------------------------
+    # 3. 3D Landscape (The "Bonus")
+    # -------------------------------------------------------------------------
+    if "null_probability" in matrix_params and "Rows" in matrix_params:
+         try:
+             fig_3d = px.scatter_3d(
+                 pldf, 
+                 x="Rows", 
+                 y="null_probability", 
+                 z="Duration", 
+                 color="Engine",
+                 symbol="Asset",
+                 log_x=True,
+                 log_z=True,
+                 title="<b>3D Landscape</b>: Rows x Nulls x Duration",
+                 height=800
+             )
+             figures_html.append(fig_3d.to_html(full_html=False, include_plotlyjs=False))
+         except Exception as e:
+             context.log.warning(f"3D Plot Error: {e}")
+
+    # -------------------------------------------------------------------------
+    # 4. SAVE (Side Effect)
+    # -------------------------------------------------------------------------
+    exp_dir = os.path.join(RESULTS_DIR, EXP_ID)
+    os.makedirs(exp_dir, exist_ok=True)
+    
+    html_path = os.path.join(exp_dir, f"{EXP_ID}.html")
+    csv_path = os.path.join(exp_dir, f"{EXP_ID}.csv")
+    
+    with open(html_path, "w") as f:
+        f.write(f"<h1>Benchmark: {EXP_ID}</h1>")
+        f.write(f"<p>Generated at: {pd.Timestamp.now()}</p><hr>")
+        f.write("<br><hr><br>".join(figures_html))
+
+    # -------------------------------------------------------------------------
+    # 5. WRITE CSV
+    # -------------------------------------------------------------------------
+    df.write_csv(csv_path)
+
+    # -------------------------------------------------------------------------
+    # 6. SCALING LAW (auto-analysis, sealed with the capsule)
+    # Fit each engine's power-law exponent from the raw fragments. Written
+    # before the coordinator seals the capsule, so the exponents are
+    # tamper-protected alongside the timings. Absent for experiments without
+    # a row-scaled matrix (e.g. TPC-H scale_factor) — that's expected.
+    # -------------------------------------------------------------------------
+    from ..utils.scaling import analyze_capsule
+    scaling = analyze_capsule(RESULTS_DIR, EXP_ID)
+    if scaling:
+        with open(os.path.join(exp_dir, "scaling.json"), "w") as f:
+            json.dump(scaling, f, indent=2)
+        alphas = {e: r["alpha"] for e, r in scaling.items()}
+        context.log.info(f"Scaling law (alpha per engine): {alphas}")
+
+    return MaterializeResult(
+        metadata={
+            "dashboard_path": MetadataValue.path(html_path),
+            "results_csv_path": MetadataValue.path(csv_path),
+            "experiment_id": EXP_ID
+        })

sql_benchmarks/assets/semantic_gate.py

@@ -0,0 +1,76 @@
+import os
+import json
+from dagster import asset, AssetExecutionContext, MaterializeResult, MetadataValue
+from ..constants import RESULTS_DIR, VIOLATIONS_DIR
+from ..partitions import partitions_def
+from ..utils.common import load_context, get_scoped_asset_name
+from ..utils.semantic_auditor import SemanticAuditor
+
+CTX = load_context()
+EXP_ID = CTX['meta'].get("experiment_id", "unknown")
+
+def make_semantic_gate_asset(benchmark_asset_key):
+    """
+    Creates a SemanticGate asset that validates the results of a benchmark.
+    """
+    # The gate name should be semantic_gate_<benchmark_name>
+    benchmark_name = benchmark_asset_key.path[-1]
+    base_gate_name = f"semantic_gate_{benchmark_name.replace(f'e_{EXP_ID}__', '')}"
+    asset_name = get_scoped_asset_name(base_gate_name, EXP_ID)
+    
+    @asset(
+        name=asset_name,
+        group_name="semantic_firewall",
+        partitions_def=partitions_def,
+        deps=[benchmark_asset_key],
+        description=f"Audits benchmark results for {benchmark_name} for hallucinations."
+    )
+    def _gate(context: AssetExecutionContext):
+        partition_key = context.partition_key
+        
+        # 1. Locate the fragment produced by the dependency
+        # matches: benchmark_factory.py:30
+        from ..utils.common import load_context
+        ctx = load_context()
+        fragment_path = os.path.join(
+            RESULTS_DIR, 
+            "fragments",
+            f"{benchmark_name}__{partition_key}.json"
+        )
+        
+        if not os.path.exists(fragment_path):
+            context.log.warning(f"Fragment not found for audit: {fragment_path}")
+            return MaterializeResult(metadata={"status": "missing_fragment"})
+
+        # 2. Audit
+        with open(fragment_path, "r") as f:
+            data = json.load(f)
+            
+        auditor = SemanticAuditor()
+        report = auditor.audit_fragment(data)
+        
+        # 3. Handle Violations
+        if not report["success"]:
+            context.log.error(f"SEMANTIC HALLUCINATION DETECTED: {report['violations']}")
+            # In a real system, we might raise an error or mark it with a high-severity tag.
+            # For this PoC, we add metadata.
+            metadata = {
+                "audit_status": "FAILED",
+                "violations": MetadataValue.json(report["violations"]),
+                "fragment_path": MetadataValue.path(fragment_path)
+            }
+        else:
+            metadata = {
+                "audit_status": "PASSED",
+                "fragment_path": MetadataValue.path(fragment_path)
+            }
+            
+        return MaterializeResult(metadata=metadata)
+
+    return _gate
+
+def get_semantic_gate_assets(benchmark_assets):
+    """
+    Generates gate assets based on a list of benchmark assets.
+    """
+    return [make_semantic_gate_asset(b.key) for b in benchmark_assets]

sql_benchmarks/cli.py

@@ -0,0 +1,69 @@
+"""Command-line entry point for running experiments.
+
+Exposed as the `sqlbench` console script (see pyproject.toml). The top-level
+run_experiment.py is a thin shim over this so `./run.sh` keeps working.
+"""
+import os
+import argparse
+import sys
+
+from .coordinator import ExperimentCoordinator
+from .constants import EXPERIMENTS_DIR, EXPERIMENT_EXTENSIONS, PROCESSED_SUFFIX
+
+
+def _is_safe_path(path: str, base: str) -> bool:
+    """Returns True only if path is within base (prevents directory traversal)."""
+    return os.path.realpath(path).startswith(os.path.realpath(base) + os.sep)
+
+
+def resolve_targets(target_input: str) -> list:
+    """Resolves input string to a list of YAML files."""
+    # Absolute or relative path to a specific file
+    if os.path.isfile(target_input):
+        abs_path = os.path.abspath(target_input)
+        # Must live within the experiments directory
+        if not _is_safe_path(abs_path, EXPERIMENTS_DIR):
+            print(f"[ERROR] Path '{target_input}' is outside the experiments directory.")
+            return []
+        return [abs_path]
+
+    # Symbolic name (e.g. "queue", "archive") — resolved relative to EXPERIMENTS_DIR only
+    symbolic_path = os.path.join(EXPERIMENTS_DIR, target_input)
+    if os.path.isdir(symbolic_path) and _is_safe_path(symbolic_path, EXPERIMENTS_DIR):
+        return sorted([
+            os.path.join(symbolic_path, f)
+            for f in os.listdir(symbolic_path)
+            if f.endswith(EXPERIMENT_EXTENSIONS) and not f.endswith(PROCESSED_SUFFIX)
+        ])
+
+    return []
+
+
+def main():
+    parser = argparse.ArgumentParser(description="SQL Benchmarks Experiment Runner (Thin Wrapper)")
+    parser.add_argument("target", help="YAML file or directory (e.g., 'queue')")
+    parser.add_argument("--auto", action="store_true", help="Automated mode")
+    args = parser.parse_args()
+
+    targets = resolve_targets(args.target)
+    if not targets:
+        print(f"[ERROR] No valid targets found for '{args.target}'")
+        sys.exit(1)
+
+    print(f"[RUNNER] Processing {len(targets)} targets...")
+
+    overall_success = True
+    for target in targets:
+        print(f"\n>>> COORDINATING: {os.path.basename(target)}")
+        coordinator = ExperimentCoordinator(target, headless=args.auto)
+        if not coordinator.run():
+            overall_success = False
+            if not args.auto:
+                break  # Stop on first failure in interactive mode
+
+    if not overall_success:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()