@vespermcp/mcp-server 1.2.19 → 1.2.21

package/build/index.js

@@ -453,6 +453,17 @@ jobManager.on("processJob", async (job, execute) => {
 async function handlePrepareJob(jobId, query, requirements) {
     hydrateExternalKeys();
     const update = (updates) => jobManager.updateJob(jobId, updates);
+    // Ensure core Python packages are available for dataset operations
+    try {
+        await ensurePythonModules([
+            { module: "polars", packageName: "polars" },
+            { module: "datasets", packageName: "datasets" },
+        ]);
+    }
+    catch (e) {
+        console.error(`[Prepare] Python dependency setup warning: ${e.message}`);
+        // Continue anyway - direct file downloads may still work without datasets lib
+    }
     const requestedRows = extractRequestedRows(query, requirements);
     let selectedDataset;
     let datasetIdForDownload = "";
@@ -749,19 +760,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "vesper_download_assets",
-                description: "Download real image/media assets using smart source-aware recipes (HuggingFace, Kaggle, direct URL).",
+                description: "Download real image/media assets using smart source-aware recipes (HuggingFace, Kaggle, direct URL). Auto-detects image columns from HF feature types, column names, and value patterns. Supports PIL Images, URL-based images, and binary image data.",
                 inputSchema: {
                     type: "object",
                     properties: {
-                        dataset_id: { type: "string", description: "Unique dataset identifier." },
+                        dataset_id: { type: "string", description: "Unique dataset identifier (e.g. 'user/dataset')." },
                         source: { type: "string", enum: ["huggingface", "kaggle", "url"], description: "Asset source type." },
-                        repo_id: { type: "string", description: "Repo ID for HuggingFace (e.g. cifar100)." },
+                        repo_id: { type: "string", description: "Repo ID for HuggingFace (e.g. 'user/dataset'). Auto-inferred from dataset_id if omitted." },
                         kaggle_ref: { type: "string", description: "Kaggle dataset ref (owner/dataset)." },
                         urls: { type: "array", items: { type: "string" }, description: "Direct asset URLs." },
                         output_format: { type: "string", enum: ["webdataset", "imagefolder", "parquet"], description: "Output asset format." },
                         max_items: { type: "number", description: "Optional cap on number of assets to fetch." },
                         workers: { type: "number", description: "Parallel worker count (default 8)." },
-                        image_column: { type: "string", description: "Optional explicit image column for HuggingFace datasets." },
+                        image_column: { type: "string", description: "Explicit image column name. If omitted, auto-detected from HF features, column names, and sample values." },
                     },
                     required: ["dataset_id", "source"],
                 },
@@ -1225,6 +1236,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: true,
                 };
             }
+            // Pre-install Python datasets library for HuggingFace fallback
+            if (source === "huggingface") {
+                try {
+                    await ensurePythonModules([
+                        { module: "datasets", packageName: "datasets" },
+                    ]);
+                }
+                catch {
+                    // Continue - direct download may still work
+                }
+            }
             try {
                 const localPath = await dataIngestor.ensureData(datasetId, source, () => undefined);
                 try {
@@ -1248,7 +1270,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             hydrateExternalKeys();
             const datasetId = String(request.params.arguments?.dataset_id || "").trim();
             const source = String(request.params.arguments?.source || "").trim().toLowerCase();
-            const repoId = request.params.arguments?.repo_id ? String(request.params.arguments.repo_id) : undefined;
+            // Auto-infer repo_id from dataset_id if not provided (common for HuggingFace)
+            const repoId = request.params.arguments?.repo_id
+                ? String(request.params.arguments.repo_id)
+                : (source === "huggingface" && datasetId.includes("/") ? datasetId : undefined);
             const kaggleRef = request.params.arguments?.kaggle_ref ? String(request.params.arguments.kaggle_ref) : undefined;
             const urls = Array.isArray(request.params.arguments?.urls)
                 ? (request.params.arguments?.urls).map(v => String(v))
@@ -1274,6 +1299,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             if (source === "huggingface") {
                 requiredModules.push({ module: "datasets", packageName: "datasets" });
+                requiredModules.push({ module: "PIL", packageName: "Pillow" });
             }
             if (source === "kaggle") {
                 requiredModules.push({ module: "kaggle", packageName: "kaggle" });
@@ -1304,8 +1330,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 const result = await runPythonJson(scriptPath, ["download", JSON.stringify(payload)]);
                 if (!result?.ok) {
+                    const errMsg = result?.error || "Unknown error";
+                    // Enhance error messages for common failures
+                    let hint = "";
+                    if (errMsg.includes("No image column")) {
+                        hint = "\n\nHint: Specify image_column parameter with the column name containing images/URLs.";
+                    }
+                    else if (errMsg.includes("Authentication") || errMsg.includes("401") || errMsg.includes("403")) {
+                        hint = "\n\nHint: Use configure_keys tool to set HF_TOKEN for gated/private datasets.";
+                    }
                     return {
-                        content: [{ type: "text", text: `ERROR: asset download failed: ${result?.error || "Unknown error"}` }],
+                        content: [{ type: "text", text: `ERROR: asset download failed: ${errMsg}${hint}` }],
                         isError: true,
                     };
                 }

package/build/ingestion/hf-downloader.js

@@ -94,8 +94,18 @@ export class HFDownloader {
         }
         catch (error) {
             const msg = String(error?.message || error);
-            if (msg.includes("401") || msg.includes("403") || msg.toLowerCase().includes("unauthorized")) {
-                throw new Error("Hugging Face gated/private dataset requires token. Run 'vespermcp config keys' to set HF token.");
+            if (msg.includes("401") || msg.toLowerCase().includes("unauthorized")) {
+                throw new Error(`Authentication required for dataset '${repoId}'. ` +
+                    `This dataset may be gated or private. ` +
+                    `Use the configure_keys tool to set your HF_TOKEN, then retry.`);
+            }
+            if (msg.includes("403") || msg.toLowerCase().includes("forbidden")) {
+                throw new Error(`Access denied for dataset '${repoId}'. ` +
+                    `You may need to accept the dataset's usage agreement on huggingface.co, ` +
+                    `then set HF_TOKEN via configure_keys tool.`);
+            }
+            if (msg.includes("404") || msg.toLowerCase().includes("not found")) {
+                throw new Error(`Dataset '${repoId}' not found on HuggingFace. Check the dataset ID.`);
             }
             console.error(`[HF] Failed to list files for ${repoId}:`, msg);
             return null;

package/build/ingestion/ingestor.js

@@ -1,5 +1,6 @@
 import path from "path";
 import fs from "fs";
+import { spawn } from "child_process";
 import { HFDownloader } from "./hf-downloader.js";
 import { KaggleSource } from "../metadata/kaggle-source.js";
 import { OpenMLSource } from "../metadata/openml-source.js";
@@ -63,25 +64,49 @@ export class DataIngestor {
         if (source === "huggingface") {
             onProgress?.("Discovering data files on HuggingFace Hub...");
             const remotePath = await this.hfDownloader.findBestFile(datasetId);
-            if (!remotePath)
-                throw new Error(`No suitable data files found in HuggingFace repo: ${datasetId}`);
-            const ext = path.extname(remotePath).substring(1).toLowerCase() || "csv";
-            const targetPath = this.getTargetPath(datasetId, ext);
-            this.store.registerDownload(datasetId, targetPath, "downloading");
-            try {
-                await this.hfDownloader.download(datasetId, remotePath, targetPath, (progress) => {
-                    onProgress?.(`Downloading ${path.basename(remotePath)}...`, progress);
-                });
-                const resolvedPath = await this.hfDownloader.resolveExternalDataFromMetadata(targetPath, (progress) => {
-                    onProgress?.("Resolving external dataset file...", progress);
-                });
-                const stats = fs.statSync(resolvedPath);
-                this.completeDownload(datasetId, resolvedPath, stats.size);
-                return resolvedPath;
+            if (remotePath) {
+                // Direct file download path (repo has raw data files)
+                const ext = path.extname(remotePath).substring(1).toLowerCase() || "csv";
+                const targetPath = this.getTargetPath(datasetId, ext);
+                this.store.registerDownload(datasetId, targetPath, "downloading");
+                try {
+                    await this.hfDownloader.download(datasetId, remotePath, targetPath, (progress) => {
+                        onProgress?.(`Downloading ${path.basename(remotePath)}...`, progress);
+                    });
+                    const resolvedPath = await this.hfDownloader.resolveExternalDataFromMetadata(targetPath, (progress) => {
+                        onProgress?.("Resolving external dataset file...", progress);
+                    });
+                    const stats = fs.statSync(resolvedPath);
+                    this.completeDownload(datasetId, resolvedPath, stats.size);
+                    return resolvedPath;
+                }
+                catch (e) {
+                    const msg = String(e?.message || e);
+                    // If auth error, propagate immediately with helpful message
+                    if (msg.includes("401") || msg.includes("403") || msg.includes("Authentication") || msg.includes("Access denied")) {
+                        this.failDownload(datasetId, msg);
+                        throw e;
+                    }
+                    // For other download errors, try the fallback
+                    onProgress?.(`Direct download failed (${msg}), trying datasets library fallback...`);
+                }
             }
-            catch (e) {
-                this.failDownload(datasetId, e.message);
-                throw e;
+            // Fallback: Use Python datasets library to download and convert
+            // This runs when findBestFile returns null OR when direct download fails (non-auth)
+            if (!fs.existsSync(this.getTargetPath(datasetId, "parquet")) || !this.store.getDownloadStatus(datasetId)?.status?.includes("completed")) {
+                onProgress?.("Using HuggingFace datasets library to download...");
+                const targetPath = this.getTargetPath(datasetId, "parquet");
+                this.store.registerDownload(datasetId, targetPath, "downloading");
+                try {
+                    const result = await this.hfDatasetsFallback(datasetId, targetPath, onProgress);
+                    const stats = fs.statSync(result);
+                    this.completeDownload(datasetId, result, stats.size);
+                    return result;
+                }
+                catch (e) {
+                    this.failDownload(datasetId, e.message);
+                    throw e;
+                }
             }
         }
         else if (source === "kaggle") {
@@ -159,4 +184,85 @@ export class DataIngestor {
         const safeId = datasetId.replace(/\//g, "_").replace(/:/g, "_");
         return path.join(this.rawDataDir, `${safeId}.${extension}`);
     }
+    /**
+     * Fallback: Use Python `datasets` library to download a HuggingFace dataset
+     * when no raw data files are found in the repo file listing.
+     */
+    async hfDatasetsFallback(datasetId, targetPath, onProgress) {
+        const pyCmd = process.platform === "win32" ? "py" : "python";
+        // Resolve the fallback script path
+        const homeDir = process.env.HOME || process.env.USERPROFILE || this.projectRoot;
+        const dataRoot = path.join(homeDir, ".vesper");
+        const scriptCandidates = [
+            path.resolve(dataRoot, "python", "hf_fallback.py"),
+            path.resolve(this.projectRoot, "python", "hf_fallback.py"),
+            path.resolve(this.projectRoot, "..", "src", "python", "hf_fallback.py"),
+            path.resolve(this.projectRoot, "..", "python", "hf_fallback.py"),
+        ];
+        let scriptPath = scriptCandidates.find(p => fs.existsSync(p));
+        if (!scriptPath) {
+            scriptPath = scriptCandidates[0]; // Will fail with a clear error
+        }
+        const token = process.env.HF_TOKEN || process.env.HUGGINGFACE_TOKEN || undefined;
+        const payload = {
+            repo_id: datasetId,
+            output_path: targetPath,
+            token: token || null,
+            max_rows: 500000,
+        };
+        onProgress?.("Downloading via datasets library (this may take a moment)...", 30);
+        return new Promise((resolve, reject) => {
+            const proc = spawn(pyCmd, [scriptPath, JSON.stringify(payload)], {
+                env: {
+                    ...process.env,
+                    PYTHONUTF8: "1",
+                    PIP_DISABLE_PIP_VERSION_CHECK: "1",
+                },
+            });
+            let stdout = "";
+            let stderr = "";
+            proc.stdout.on("data", (d) => (stdout += d.toString()));
+            proc.stderr.on("data", (d) => {
+                const msg = d.toString();
+                stderr += msg;
+                // Forward progress info
+                if (msg.includes("Downloading") || msg.includes("Loading")) {
+                    onProgress?.(msg.trim().split("\n").pop() || "Downloading...", 50);
+                }
+            });
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill();
+                }
+                catch { /* no-op */ }
+                reject(new Error(`HuggingFace datasets download timed out after 10 minutes for ${datasetId}`));
+            }, 600000); // 10 min timeout
+            proc.on("close", (code) => {
+                clearTimeout(timer);
+                if (code !== 0) {
+                    let errorMsg = stderr || stdout || `Python exited with code ${code}`;
+                    try {
+                        const parsed = JSON.parse(stdout);
+                        if (parsed.error)
+                            errorMsg = parsed.error;
+                    }
+                    catch { /* use stderr */ }
+                    reject(new Error(`HuggingFace datasets fallback failed: ${errorMsg}`));
+                    return;
+                }
+                try {
+                    const result = JSON.parse(stdout);
+                    if (!result.ok) {
+                        reject(new Error(result.error || "Unknown error from HF fallback"));
+                        return;
+                    }
+                    onProgress?.(`Downloaded ${result.rows?.toLocaleString() || "?"} rows (${result.columns?.length || "?"} columns)`, 90);
+                    resolve(result.path);
+                }
+                catch {
+                    reject(new Error(`Failed to parse HF fallback output: ${stdout}`));
+                }
+            });
+        });
+    }
 }

package/build/python/asset_downloader_engine.py

@@ -3,9 +3,14 @@ import asyncio
 import json
 import os
 import sys
+import warnings
 from pathlib import Path
 from typing import Any, Dict
 
+# Suppress noisy HF warnings
+warnings.filterwarnings("ignore", message=".*trust_remote_code.*")
+warnings.filterwarnings("ignore", message=".*legacy.*")
+
 CURRENT_DIR = Path(__file__).resolve().parent
 if str(CURRENT_DIR) not in sys.path:
     sys.path.insert(0, str(CURRENT_DIR))
@@ -24,6 +29,11 @@ async def _run_download(args: argparse.Namespace) -> Dict[str, Any]:
     workers = int(payload.get("workers") or 8)
     recipes_dir = payload.get("recipes_dir")
 
+    # Auto-set HF token from payload if provided
+    token = payload.get("token") or payload.get("hf_token")
+    if token:
+        os.environ["HF_TOKEN"] = str(token)
+
     downloader = AssetDownloader(output_root=output_root, workers=workers, recipes_dir=recipes_dir)
 
     result = await downloader.download_assets(
@@ -66,7 +76,16 @@ def main() -> None:
 
         _print({"ok": False, "error": f"Unknown action: {args.action}"})
     except Exception as e:
-        _print({"ok": False, "error": str(e)})
+        error_msg = str(e)
+        # Provide actionable error messages
+        if "401" in error_msg or "403" in error_msg or "Unauthorized" in error_msg:
+            error_msg = (
+                "Authentication required. This dataset may be gated/private. "
+                "Use configure_keys tool to set HF_TOKEN, then retry."
+            )
+        elif "No image column" in error_msg:
+            error_msg += " Hint: specify image_column parameter with the name of the column containing images."
+        _print({"ok": False, "error": error_msg})
 
 
 if __name__ == "__main__":

package/build/python/hf_fallback.py

@@ -0,0 +1,298 @@
+"""
+HuggingFace Datasets Library Fallback Downloader.
+
+Used when the HF Hub file listing finds no suitable data files
+(e.g. script-based datasets, gated datasets, datasets that use
+the `datasets` library format).
+
+Handles:
+- Legacy script-based datasets (trust_remote_code)
+- Gated/private datasets (token auth)
+- Image datasets (PIL Image columns → stripped for tabular export)
+- Various split formats (DatasetDict, single split)
+
+Usage:
+    python hf_fallback.py '{"repo_id": "user/dataset", "output_path": "/path/to/output.parquet", "token": "optional", "max_rows": 100000, "split": "train"}'
+
+Output: JSON to stdout
+    {"ok": true, "path": "/path/to/output.parquet", "rows": 12345, "columns": ["col1", "col2"]}
+    {"ok": false, "error": "..."}
+"""
+import sys
+import json
+import os
+import warnings
+
+# Suppress noisy HF warnings about trust_remote_code etc.
+warnings.filterwarnings("ignore", message=".*trust_remote_code.*")
+warnings.filterwarnings("ignore", message=".*legacy.*")
+
+
+def _detect_image_columns(ds):
+    """Detect columns that contain HF Image features or PIL Image objects."""
+    image_cols = []
+    features = getattr(ds, "features", None)
+    if features:
+        for name, feat in features.items():
+            feat_cls = feat.__class__.__name__.lower()
+            feat_str = str(feat).lower()
+            if feat_cls == "image" or "image(" in feat_str:
+                image_cols.append(name)
+    return image_cols
+
+
+def _strip_image_columns(ds, image_cols):
+    """Remove image columns from dataset so it can be exported to Parquet/CSV.
+    
+    Image columns contain PIL Image objects that can't be serialized to tabular
+    formats. We replace them with a placeholder string indicating the column
+    was an image column.
+    """
+    if not image_cols:
+        return ds
+    
+    # Remove the image columns entirely for tabular export
+    cols_to_keep = [c for c in ds.column_names if c not in image_cols]
+    if not cols_to_keep:
+        # Dataset is ALL image columns — keep them but cast to path strings if possible
+        return ds
+    
+    return ds.select_columns(cols_to_keep)
+
+
+def _load_dataset_robust(repo_id, token, split):
+    """Load a HuggingFace dataset with multiple fallback strategies.
+    
+    Strategy order:
+    1. Normal load with trust_remote_code=True (handles legacy script datasets)
+    2. Load without trust_remote_code (newer datasets that reject it)
+    3. Load with streaming=True then materialize (handles very large datasets)
+    """
+    from datasets import load_dataset, DatasetDict
+
+    errors = []
+    splits_to_try = [split] if split else ["train", "test", "validation", None]
+    
+    # Strategy 1: Normal load with trust_remote_code
+    for s in splits_to_try:
+        try:
+            kwargs = {"path": repo_id, "trust_remote_code": True}
+            if token:
+                kwargs["token"] = token
+            if s:
+                kwargs["split"] = s
+            ds = load_dataset(**kwargs)
+            return ds, s
+        except (ValueError, KeyError):
+            continue
+        except Exception as e:
+            msg = str(e)
+            # Auth errors should be raised immediately, not retried
+            if any(x in msg for x in ["401", "403", "gated", "Unauthorized", "access"]):
+                raise
+            if "split" in msg.lower() or "key" in msg.lower():
+                continue
+            errors.append(f"trust_remote_code=True, split={s}: {msg}")
+    
+    # Strategy 2: Load WITHOUT trust_remote_code (some repos reject it)
+    for s in splits_to_try:
+        try:
+            kwargs = {"path": repo_id}
+            if token:
+                kwargs["token"] = token
+            if s:
+                kwargs["split"] = s
+            ds = load_dataset(**kwargs)
+            return ds, s
+        except (ValueError, KeyError):
+            continue
+        except Exception as e:
+            msg = str(e)
+            if any(x in msg for x in ["401", "403", "gated", "Unauthorized", "access"]):
+                raise
+            if "split" in msg.lower() or "key" in msg.lower():
+                continue
+            errors.append(f"trust_remote_code=False, split={s}: {msg}")
+    
+    # Strategy 3: Streaming fallback (for very large / oddly structured datasets)
+    for s in splits_to_try:
+        if s is None:
+            continue  # streaming requires a split
+        try:
+            kwargs = {"path": repo_id, "streaming": True, "trust_remote_code": True}
+            if token:
+                kwargs["token"] = token
+            if s:
+                kwargs["split"] = s
+            ds_stream = load_dataset(**kwargs)
+            # Materialize from streaming iterator
+            from datasets import Dataset as HFDataset
+            rows = []
+            for i, row in enumerate(ds_stream):
+                if i >= 500000:
+                    break
+                rows.append(row)
+            if rows:
+                ds = HFDataset.from_list(rows)
+                return ds, s
+        except Exception:
+            continue
+    
+    # All strategies failed
+    error_summary = "; ".join(errors[:3]) if errors else "No valid configuration found"
+    return None, error_summary
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"ok": False, "error": "Missing payload argument"}))
+        sys.exit(1)
+
+    try:
+        payload = json.loads(sys.argv[1])
+    except json.JSONDecodeError as e:
+        print(json.dumps({"ok": False, "error": f"Invalid JSON payload: {e}"}))
+        sys.exit(1)
+
+    repo_id = payload.get("repo_id", "").strip()
+    output_path = payload.get("output_path", "").strip()
+    token = payload.get("token") or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_TOKEN") or None
+    max_rows = payload.get("max_rows", 500000)
+    split = payload.get("split")  # None = auto-detect
+
+    if not repo_id:
+        print(json.dumps({"ok": False, "error": "repo_id is required"}))
+        sys.exit(1)
+
+    if not output_path:
+        print(json.dumps({"ok": False, "error": "output_path is required"}))
+        sys.exit(1)
+
+    try:
+        from datasets import load_dataset
+    except ImportError:
+        print(json.dumps({"ok": False, "error": "Python 'datasets' library not installed. Install with: pip install datasets"}))
+        sys.exit(1)
+
+    try:
+        import polars as pl
+    except ImportError:
+        pl = None
+
+    try:
+        ds, used_split = _load_dataset_robust(repo_id, token, split)
+
+        if ds is None:
+            print(json.dumps({"ok": False, "error": f"Could not load dataset '{repo_id}': {used_split}"}))
+            sys.exit(1)
+
+        # Handle DatasetDict (when no split specified)
+        from datasets import DatasetDict, Dataset
+        if isinstance(ds, DatasetDict):
+            # Pick the best split
+            for preferred in ["train", "test", "validation"]:
+                if preferred in ds:
+                    ds = ds[preferred]
+                    used_split = preferred
+                    break
+            else:
+                # Just pick the first available split
+                first_key = list(ds.keys())[0]
+                ds = ds[first_key]
+                used_split = first_key
+
+        # Limit rows if needed
+        total_rows = len(ds)
+        if max_rows and total_rows > max_rows:
+            ds = ds.select(range(max_rows))
+            total_rows = max_rows
+
+        # Detect and handle image columns (PIL Image objects can't be exported to Parquet)
+        image_cols = _detect_image_columns(ds)
+        has_images = len(image_cols) > 0
+        
+        if has_images:
+            # Strip image columns for tabular export, note them in output
+            export_ds = _strip_image_columns(ds, image_cols)
+        else:
+            export_ds = ds
+
+        # Ensure output directory exists
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+        # Export to parquet
+        columns = export_ds.column_names
+
+        try:
+            if output_path.endswith(".parquet"):
+                export_ds.to_parquet(output_path)
+            elif output_path.endswith(".csv"):
+                export_ds.to_csv(output_path)
+            else:
+                # Default to parquet
+                if not output_path.endswith(".parquet"):
+                    output_path = output_path + ".parquet"
+                export_ds.to_parquet(output_path)
+        except Exception as export_err:
+            # If parquet export fails (e.g. complex nested types), try CSV
+            csv_path = output_path.replace(".parquet", ".csv")
+            try:
+                export_ds.to_csv(csv_path)
+                output_path = csv_path
+            except Exception:
+                raise export_err  # Re-raise original error
+
+        result = {
+            "ok": True,
+            "path": output_path,
+            "rows": total_rows,
+            "columns": columns,
+            "split": used_split
+        }
+        
+        if has_images:
+            result["image_columns"] = image_cols
+            result["note"] = (
+                f"This dataset contains image columns ({', '.join(image_cols)}). "
+                "Image data was stripped for tabular export. "
+                "Use vesper_download_assets with source='huggingface' to download the actual images."
+            )
+
+        print(json.dumps(result))
+
+    except Exception as e:
+        error_msg = str(e)
+        # Provide helpful, actionable hints
+        if "401" in error_msg or "Unauthorized" in error_msg:
+            error_msg = (
+                f"Authentication required for dataset '{repo_id}'. "
+                "This dataset may be gated or private. "
+                "Use the configure_keys tool to set your HF_TOKEN, then retry."
+            )
+        elif "403" in error_msg or "Forbidden" in error_msg:
+            error_msg = (
+                f"Access denied for dataset '{repo_id}'. "
+                "You may need to accept the dataset's usage agreement on huggingface.co, "
+                "then set HF_TOKEN via configure_keys tool."
+            )
+        elif "gated" in error_msg.lower():
+            error_msg = (
+                f"Dataset '{repo_id}' is gated. "
+                "Visit https://huggingface.co/datasets/{repo_id} to request access, "
+                "then set HF_TOKEN via configure_keys tool."
+            ).format(repo_id=repo_id)
+        elif "FileNotFoundError" in error_msg or "does not exist" in error_msg.lower() or "doesn't exist" in error_msg.lower():
+            error_msg = f"Dataset '{repo_id}' not found on HuggingFace. Check the dataset ID."
+        elif "script" in error_msg.lower() and "no longer supported" in error_msg.lower():
+            error_msg = (
+                f"Dataset '{repo_id}' uses a legacy loading script that is no longer supported "
+                "by the current version of the datasets library. "
+                "Try: pip install datasets --upgrade, or use an older datasets version."
+            )
+
+        print(json.dumps({"ok": False, "error": error_msg}))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()