vesper-wizard 2.1.4 → 2.1.6

package/build/export/exporter.js

@@ -1,10 +1,12 @@
 import { spawn } from "child_process";
 import path from "path";
 import fs from "fs";
+import { ensurePythonPackages, resolvePythonCommand } from "../utils/python-runtime.js";
 export class DataExporter {
-    pythonPath = "python";
+    buildDir;
     scriptPath;
     constructor(buildDir = process.cwd()) {
+        this.buildDir = buildDir;
         const homeDir = process.env.HOME || process.env.USERPROFILE || buildDir;
         const dataRoot = path.join(homeDir, ".vesper");
         const scriptPath0 = path.resolve(dataRoot, "python", "export_engine.py");
@@ -26,27 +28,38 @@ export class DataExporter {
         else {
             this.scriptPath = scriptPath0;
         }
-        // Detect Python command
-        if (process.platform === "win32") {
-            this.pythonPath = "py";
-        }
     }
     /**
      * Exports a dataset file to a specified format
      */
     async export(inputFile, outputFile, format, options = {}) {
+        const pythonRequirements = [
+            { module: "polars", packageName: "polars" },
+        ];
+        if (format === "feather") {
+            pythonRequirements.push({ module: "pyarrow", packageName: "pyarrow" });
+        }
+        if (format === "tfrecord") {
+            pythonRequirements.push({ module: "tensorflow", packageName: "tensorflow" });
+        }
+        const pythonPath = await ensurePythonPackages(this.buildDir, pythonRequirements).catch(() => resolvePythonCommand(this.buildDir));
         return new Promise((resolve, reject) => {
             if (!fs.existsSync(inputFile)) {
                 reject(new Error(`Input file not found: ${inputFile}`));
                 return;
             }
             const args = [this.scriptPath, inputFile, outputFile, format, JSON.stringify(options)];
-            const process = spawn(this.pythonPath, args);
+            const childProcess = spawn(pythonPath, args, {
+                env: {
+                    ...process.env,
+                    PYTHONIOENCODING: "utf-8",
+                },
+            });
             let stdout = "";
             let stderr = "";
-            process.stdout.on("data", (data) => stdout += data.toString());
-            process.stderr.on("data", (data) => stderr += data.toString());
-            process.on("close", (code) => {
+            childProcess.stdout.on("data", (data) => stdout += data.toString());
+            childProcess.stderr.on("data", (data) => stderr += data.toString());
+            childProcess.on("close", (code) => {
                 if (code !== 0) {
                     reject(new Error(`Export failed: ${stderr || stdout}`));
                     return;

package/build/gateway/unified-dataset-gateway.js

@@ -3,6 +3,7 @@ import path from "path";
 import http from "http";
 import https from "https";
 import { HuggingFaceScraper } from "../metadata/scraper.js";
+import { analyzeDatasetQuery } from "../search/query-intent.js";
 export class UnifiedDatasetGateway {
     deps;
     constructor(deps) {
@@ -236,7 +237,7 @@ export class UnifiedDatasetGateway {
     async discoverFromSource(source, query, limit) {
         switch (source) {
             case "huggingface":
-                return await new HuggingFaceScraper().scrape(limit, true, query);
+                return await new HuggingFaceScraper().scrape(limit, true, await analyzeDatasetQuery(query));
             case "openml":
                 return await this.deps.openmlSource.discover(query, limit);
             case "kaggle":

package/build/index.js

@@ -361,6 +361,21 @@ function extractRequestedRows(query, requirements) {
         if (Number.isFinite(n) && n > 0)
             return n;
     }
+    const commaNumbers = [...text.matchAll(/\b\d{1,3}(?:,\d{3})+\b/g)]
+        .map(m => Number(m[0].replace(/,/g, "")))
+        .filter(n => Number.isFinite(n) && n > 0);
+    if (commaNumbers.length > 0)
+        return Math.max(...commaNumbers);
+    const humanSized = [...text.matchAll(/\b(\d+(?:\.\d+)?)\s*([kmb])\b/gi)]
+        .map(m => {
+        const base = Number(m[1]);
+        const suffix = m[2].toLowerCase();
+        const multiplier = suffix === "k" ? 1_000 : suffix === "m" ? 1_000_000 : 1_000_000_000;
+        return Math.round(base * multiplier);
+    })
+        .filter(n => Number.isFinite(n) && n > 0);
+    if (humanSized.length > 0)
+        return Math.max(...humanSized);
     const allNums = [...text.matchAll(/\b\d{4,9}\b/g)]
         .map(m => Number(m[0]))
         .filter(n => Number.isFinite(n) && n > 0);
@@ -644,7 +659,7 @@ jobManager.on("processJob", async (job, execute) => {
         console.error(`[Vesper] Starting prepareDatasetTask for job ${job.id}...`);
         const metadata = job.metadata ? JSON.parse(job.metadata) : {};
         switch (job.type) {
-            case "prepare": return await handlePrepareJob(job.id, metadata.query, metadata.requirements);
+            case "prepare": return await handlePrepareJob(job.id, metadata.query, metadata.requirements, metadata.outputDir);
             case "clean": return await handleCleanJob(job.id, metadata.datasetId, metadata.ops);
             default: throw new Error(`Unhandled job type: ${job.type}`);
         }
@@ -662,7 +677,7 @@ jobManager.on("processJob", async (job, execute) => {
 /**
  * Logic for preparing a dataset (Search + Ingest + Process)
  */
-async function handlePrepareJob(jobId, query, requirements) {
+async function handlePrepareJob(jobId, query, requirements, outputDir) {
     hydrateExternalKeys();
     const update = (updates) => jobManager.updateJob(jobId, updates);
     const pipelineSteps = ["search", "validate", "download", "normalize", "quality", "register"];
@@ -689,6 +704,7 @@ async function handlePrepareJob(jobId, query, requirements) {
         // Continue anyway - direct file downloads may still work without datasets lib
     }
     const requestedRows = extractRequestedRows(query, requirements);
+    const searchQuery = requirements ? `${query} ${requirements}` : query;
     let selectedDataset;
     let datasetIdForDownload = "";
     let source;
@@ -729,7 +745,7 @@ async function handlePrepareJob(jobId, query, requirements) {
     else {
         markPipelineStep("search", "running");
         update({ progress: 10, status_text: "Searching for best dataset matching query..." });
-        const results = await searchEngine.search(query, { limit: 10 });
+        const results = await searchEngine.search(searchQuery, { limit: 10 });
         if (results.length === 0) {
             markPipelineStep("search", "failed");
             throw new Error("No datasets found matching the query. Try refining your search terms.");
@@ -777,7 +793,7 @@ async function handlePrepareJob(jobId, query, requirements) {
         let currentRows = await countRows(rawFilePath);
         if (currentRows < requestedRows) {
             update({ progress: 64, status_text: `Only ${currentRows.toLocaleString()} rows found. Fetching more matching datasets...` });
-            const additional = await searchEngine.search(query, { limit: 8 });
+            const additional = await searchEngine.search(searchQuery, { limit: 8 });
             const sourceFiles = [rawFilePath];
             let totalRows = currentRows;
             for (const ds of additional) {
@@ -882,7 +898,7 @@ async function handlePrepareJob(jobId, query, requirements) {
     }
     markPipelineStep("register", "running");
     update({ progress: 85, status_text: "Installing dataset into project..." });
-    const installPath = await installService.install(datasetIdForDownload, rawFilePath);
+    const installPath = await installService.install(datasetIdForDownload, rawFilePath, outputDir);
     update({ progress: 100, status_text: "Preparation complete!" });
     // Register prepared dataset in local registry for lookup by export/list tools
     try {
@@ -1013,7 +1029,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         target_dir: {
                             type: "string",
-                            description: "Optional output directory for operation='download'.",
+                            description: "Optional output directory for operation='download'. Defaults to the current working directory when omitted.",
+                        },
+                        output_dir: {
+                            type: "string",
+                            description: "Alias for target_dir. Defaults to the current working directory when omitted.",
                         },
                         public_only: {
                             type: "boolean",
@@ -1052,7 +1072,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "download_dataset",
-                description: "Download a dataset by source and ID/slug into local Vesper storage. Defaults to HuggingFace. Public providers work keylessly, while Kaggle and data.world can use server-managed credentials when configured.",
+                description: "Download a dataset by source and ID/slug into a local directory. Defaults to HuggingFace. Public providers work keylessly, while Kaggle and data.world can use server-managed credentials when configured.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1067,7 +1087,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         target_dir: {
                             type: "string",
-                            description: "Optional target directory for downloaded files.",
+                            description: "Optional target directory for downloaded files. Defaults to the current working directory when omitted.",
+                        },
+                        output_dir: {
+                            type: "string",
+                            description: "Alias for target_dir. Defaults to the current working directory when omitted.",
                         }
                     },
                     required: ["dataset_id"],
@@ -1194,6 +1218,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         query: { type: "string" },
                         requirements: { type: "string" },
+                        target_dir: { type: "string", description: "Optional local directory for the prepared dataset. Defaults to the current working directory when omitted." },
+                        output_dir: { type: "string", description: "Alias for target_dir. Defaults to the current working directory when omitted." },
                         download_images: { type: "boolean", description: "When true, enables post-prepare smart asset downloading for image/media datasets." },
                         cleaning_options: { type: "object" },
                         split_config: { type: "object" },
@@ -1238,7 +1264,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         target_dir: {
                             type: "string",
-                            description: "Optional custom local directory for export (e.g., './naruto-quotes').",
+                            description: "Optional custom local directory for export. Defaults to the current working directory when omitted.",
+                        },
+                        output_dir: {
+                            type: "string",
+                            description: "Alias for target_dir. Defaults to the current working directory when omitted.",
                         },
                         format: {
                             type: "string",
@@ -1425,7 +1455,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (tool === "vesper_export" && req === "split") {
                         // Auto-trigger prepare_dataset (start a background prepare job)
                         try {
-                            jobManager.createJob("prepare", 0, { query: String(datasetId), requirements: undefined, downloadImages: false });
+                            jobManager.createJob("prepare", 0, { query: String(datasetId), requirements: undefined, downloadImages: false, outputDir: process.cwd() });
                             // Mark split as complete so export can proceed; export handler will also wait for data if needed.
                             markStepComplete(String(datasetId), "split");
                         }
@@ -1481,6 +1511,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         if (!datasetId) {
                             throw new McpError(ErrorCode.InvalidParams, "dataset_id is required for operation='download'");
                         }
+                        const requestedTargetDir = request.params.arguments?.target_dir
+                            ? String(request.params.arguments.target_dir).trim()
+                            : request.params.arguments?.output_dir
+                                ? String(request.params.arguments.output_dir).trim()
+                                : "";
+                        const targetDir = requestedTargetDir || process.cwd();
                         try {
                             await ensurePythonModules([{ module: "datasets", packageName: "datasets" }]);
                         }
@@ -1490,7 +1526,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         const result = await unifiedDatasetGateway.download({
                             datasetId,
                             source,
-                            targetDir: request.params.arguments?.target_dir ? String(request.params.arguments.target_dir) : undefined,
+                            targetDir,
                         });
                         try {
                             upsertRegistry(result.dataset_id, result.copied_to || result.local_path, "completed");
@@ -1597,7 +1633,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 hydrateExternalKeys();
                 const source = String(request.params.arguments?.source || "huggingface").toLowerCase();
                 const datasetId = String(request.params.arguments?.dataset_id || "").trim();
-                const targetDir = request.params.arguments?.target_dir ? String(request.params.arguments.target_dir) : undefined;
+                const requestedTargetDir = request.params.arguments?.target_dir
+                    ? String(request.params.arguments.target_dir).trim()
+                    : request.params.arguments?.output_dir
+                        ? String(request.params.arguments.output_dir).trim()
+                        : "";
+                const targetDir = requestedTargetDir || process.cwd();
                 if (!datasetId) {
                     throw new McpError(ErrorCode.InvalidParams, "dataset_id is required");
                 }
@@ -1975,10 +2016,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const query = String(request.params.arguments?.query);
                 const requirements = request.params.arguments?.requirements ? String(request.params.arguments?.requirements) : undefined;
                 const downloadImages = request.params.arguments?.download_images === true;
+                const requestedOutputDir = request.params.arguments?.target_dir
+                    ? String(request.params.arguments.target_dir).trim()
+                    : request.params.arguments?.output_dir
+                        ? String(request.params.arguments.output_dir).trim()
+                        : "";
+                const outputDir = requestedOutputDir || process.cwd();
                 if (!query || query === "undefined") {
                     throw new McpError(ErrorCode.InvalidParams, "query is required - describe the dataset you need or provide a dataset ID");
                 }
-                const job = jobManager.createJob("prepare", 0, { query, requirements, downloadImages });
+                const job = jobManager.createJob("prepare", 0, { query, requirements, downloadImages, outputDir });
                 return {
                     content: [{ type: "text", text: `Preparation job started. ID: ${job.id}. Vesper is finding and preparing the best dataset for you. Use check_job_status to monitor progress.` }]
                 };
@@ -2019,7 +2066,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "export_dataset": {
                 const datasetId = String(request.params.arguments?.dataset_id);
-                const targetDir = request.params.arguments?.target_dir ? String(request.params.arguments?.target_dir) : undefined;
+                const requestedTargetDir = request.params.arguments?.target_dir
+                    ? String(request.params.arguments?.target_dir).trim()
+                    : request.params.arguments?.output_dir
+                        ? String(request.params.arguments?.output_dir).trim()
+                        : "";
+                const targetDir = requestedTargetDir || process.cwd();
                 const requestedFormat = String(request.params.arguments?.format || "feather");
                 const fastMode = request.params.arguments?.fast === true;
                 const preview = request.params.arguments?.preview === true;
@@ -2032,7 +2084,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     console.error(`[Export] No local data found for ${datasetId}. Attempting to prepare automatically...`);
                     // Start a prepare job for this dataset id (acts like calling prepare_dataset)
                     try {
-                        jobManager.createJob("prepare", 0, { query: datasetId, requirements: undefined, downloadImages: false });
+                        jobManager.createJob("prepare", 0, { query: datasetId, requirements: undefined, downloadImages: false, outputDir: process.cwd() });
                     }
                     catch (e) {
                         console.error(`[Export] Failed to start prepare job for ${datasetId}: ${e?.message || e}`);

package/build/metadata/scraper.js

@@ -3,12 +3,18 @@ import { categorizeLicense } from "./license.js";
 import { calculateQualityScore } from "./quality.js";
 import { classifyDomain } from "./domain.js";
 import { retryWithBackoff, delayBetweenRequests } from "./rate-limiter.js";
+import { analyzeDatasetQuery, buildIntentSearchQuery, scoreDatasetAgainstIntent } from "../search/query-intent.js";
 export class HuggingFaceScraper {
     /**
      * Bulk discovery: Fetch many datasets quickly without deep details.
      * Hits the 25k target in minutes.
      */
-    async scrapeBulk(limit = 1000, query) {
+    async scrapeBulk(limit = 1000, queryOrIntent) {
+        const intent = typeof queryOrIntent === "string"
+            ? await analyzeDatasetQuery(queryOrIntent)
+            : queryOrIntent;
+        const query = typeof queryOrIntent === "string" ? queryOrIntent : intent?.searchQuery;
+        const hfQuery = intent ? buildIntentSearchQuery(intent) : query;
         const filterMsg = query ? `, query: ${query}` : "";
         console.error(`[Bulk Scraper] Fetching datasets (target limit: ${limit}${filterMsg})...`);
         const results = [];
@@ -18,7 +24,7 @@ export class HuggingFaceScraper {
             for await (const ds of listDatasets({
                 limit: limit,
                 additionalFields: ["description", "tags", "downloadsAllTime", "createdAt"],
-                search: { query: query },
+                search: { query: hfQuery },
                 ...(hfToken ? { accessToken: hfToken } : {})
             })) {
                 if (results.length >= limit)
@@ -86,8 +92,12 @@ export class HuggingFaceScraper {
         }
         return results;
     }
-    async scrape(limit = 100, applyMVPFilters = true, query // Use as general search query
-    ) {
+    async scrape(limit = 100, applyMVPFilters = true, queryOrIntent) {
+        const intent = typeof queryOrIntent === "string"
+            ? await analyzeDatasetQuery(queryOrIntent)
+            : queryOrIntent;
+        const query = typeof queryOrIntent === "string" ? queryOrIntent : intent?.searchQuery;
+        const hfQuery = intent ? buildIntentSearchQuery(intent) : query;
         const filterMsg = query ? `, query: ${query}` : "";
         console.error(`Fetching datasets (target limit: ${limit}, MVP filters: ${applyMVPFilters}${filterMsg})...`);
         const results = [];
@@ -113,7 +123,7 @@ export class HuggingFaceScraper {
             for await (const ds of listDatasets({
                 limit: fetchLimit,
                 additionalFields: ["description", "tags"],
-                search: { query: query },
+                search: { query: hfQuery },
                 ...(hfToken ? { accessToken: hfToken } : {})
             })) {
                 if (results.length >= limit)
@@ -290,6 +300,9 @@ export class HuggingFaceScraper {
                             description_length: description.length,
                             has_readme: !!(cardData.readme || cardData.readme_content)
                         };
+                        if (intent) {
+                            metadata.intent_score = scoreDatasetAgainstIntent(metadata, intent);
+                        }
                         results.push(metadata);
                     }
                     catch (e) {
@@ -340,8 +353,12 @@ export class HuggingFaceScraper {
         if (otherErrors > 0) {
             console.error(`[HF Scraper] ⚠️ ${otherErrors} datasets skipped due to errors`);
         }
-        // Sort by downloads descending
-        return results.sort((a, b) => b.downloads - a.downloads);
+        return results.sort((a, b) => {
+            const intentDelta = Number(b.intent_score || 0) - Number(a.intent_score || 0);
+            if (intentDelta !== 0)
+                return intentDelta;
+            return b.downloads - a.downloads;
+        });
     }
     extractTask(tags) {
         const taskTags = [

package/build/search/engine.js

@@ -1,4 +1,5 @@
 import { JITOrchestrator } from "./jit-orchestrator.js";
+import { analyzeDatasetQuery, scoreDatasetAgainstIntent } from "./query-intent.js";
 import fs from "fs";
 function log(msg) {
     fs.appendFileSync("debug.log", new Date().toISOString() + " " + msg + "\n");
@@ -17,9 +18,10 @@ export class SearchEngine {
     async search(query, options = {}) {
         const limit = options.limit || 5;
         const enableJIT = options.enableJIT !== false; // Default: true
+        const intent = await analyzeDatasetQuery(query);
         log(`Search request: "${query}" Limit=${limit} Safe=${options.safeOnly} JIT=${enableJIT}`);
         // 1. Perform local search
-        const localResults = await this.localSearch(query, options);
+        const localResults = await this.localSearch(query, options, intent);
         // 2. Check if JIT should be triggered
         const shouldTrigger = enableJIT && this.shouldTriggerJIT(localResults, query);
         if (!shouldTrigger) {
@@ -28,10 +30,10 @@ export class SearchEngine {
         }
         // 3. Trigger JIT fallback
         console.error(`\nWARNING: Low confidence results (${localResults.length} found, top score: ${localResults[0]?.relevance_score || 0})`);
-        await this.jitOrchestrator.fetchAndIngest(query, 10);
+        await this.jitOrchestrator.fetchAndIngest(query, 10, intent);
         // 4. Re-run local search with updated index
         console.error(`Re-searching with updated library...`);
-        const enhancedResults = await this.localSearch(query, options);
+        const enhancedResults = await this.localSearch(query, options, intent);
         const newCount = enhancedResults.length - localResults.length;
         if (newCount > 0) {
             console.error(`Found ${newCount} additional results\n`);
@@ -41,7 +43,7 @@ export class SearchEngine {
     /**
      * Perform hybrid search (Vector + Lexical + Penalties)
      */
-    async localSearch(query, options) {
+    async localSearch(query, options, intent) {
         const limit = options.limit || 5;
         // 1. Parse Query
         const words = query.toLowerCase().split(/\s+/);
@@ -136,11 +138,13 @@ export class SearchEngine {
             bonus = sourceBonuses[metadata.source] || 0;
             // Final Combined Score
             // 70% Vector, 30% Lexical, minus Penalties, plus Bonuses
-            const finalScore = (vectorScore * 0.7) + (lexicalScore * 0.3) - penalty + bonus;
+            const intentScore = scoreDatasetAgainstIntent(metadata, intent);
+            const finalScore = (vectorScore * 0.7) + (lexicalScore * 0.3) - penalty + bonus + intentScore;
             metadata.relevance_score = Math.round(finalScore * 100) / 100;
             metadata.vector_score = Math.round(vectorScore * 100) / 100;
             metadata.lexical_score = Math.round(lexicalScore * 100) / 100;
             metadata.accessibility_bonus = bonus;
+            metadata.intent_score = intentScore;
             results.push(metadata);
         }
         // Sort by final score and limit

package/build/search/jit-orchestrator.js

@@ -2,6 +2,7 @@ import { HuggingFaceScraper } from "../metadata/scraper.js";
 import { UCIScraper } from "../metadata/uci-scraper.js";
 import { GitHubScraper } from "../metadata/github-scraper.js";
 import { WorldBankScraper, NASAScraper } from "../metadata/institutional-scrapers.js";
+import { analyzeDatasetQuery, buildIntentSearchQuery } from "./query-intent.js";
 // Common stop words to filter out for better search
 const STOP_WORDS = new Set([
     "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
@@ -61,7 +62,7 @@ export class JITOrchestrator {
     /**
      * Main JIT workflow: fetch, save, index, return new datasets
      */
-    async fetchAndIngest(query, limit = 10) {
+    async fetchAndIngest(query, limit = 10, providedIntent) {
         // Rate limiting check
         if (!this.canTrigger(query)) {
             console.error(`[JIT] Query "${query}" was searched recently. Waiting...`);
@@ -69,9 +70,12 @@ export class JITOrchestrator {
         }
         console.error(`\n[JIT] Searching live sources for: "${query}"`);
         this.lastTriggerTime.set(query, Date.now());
-        // Simplify query for better API results
-        const keywords = this.simplifyQuery(query);
-        if (keywords.length > 0) {
+        const intent = providedIntent || await analyzeDatasetQuery(query);
+        const keywords = this.simplifyQuery(buildIntentSearchQuery(intent));
+        if (intent.llmBacked || intent.language || intent.task || intent.domain || intent.minRows) {
+            console.error(`[JIT] Intent: ${JSON.stringify({ language: intent.language, task: intent.task, domain: intent.domain, minRows: intent.minRows, searchQuery: intent.searchQuery })}`);
+        }
+        else if (keywords.length > 0) {
             console.error(`[JIT] Keywords extracted: ${keywords.join(", ")}`);
         }
         const newDatasets = [];
@@ -81,15 +85,16 @@ export class JITOrchestrator {
             // Get existing dataset IDs to avoid duplicates
             const existing = this.metadataStore.getAllDatasets();
             existing.forEach(ds => existingIds.add(ds.id));
-            // 1. Scrape HuggingFace - try each keyword separately for better results
-            let hfResults = [];
-            for (const keyword of keywords) {
-                if (hfResults.length >= limit)
-                    break;
-                const results = await this.scrapeHuggingFace(keyword, Math.ceil(limit / keywords.length));
-                for (const ds of results) {
-                    if (!hfResults.some(existing => existing.id === ds.id)) {
-                        hfResults.push(ds);
+            let hfResults = await this.scrapeHuggingFace(intent, limit);
+            if (hfResults.length < Math.max(3, Math.floor(limit / 2))) {
+                for (const keyword of keywords) {
+                    if (hfResults.length >= limit)
+                        break;
+                    const results = await this.scrapeHuggingFace(keyword, Math.ceil(limit / Math.max(keywords.length, 1)));
+                    for (const ds of results) {
+                        if (!hfResults.some(existing => existing.id === ds.id)) {
+                            hfResults.push(ds);
+                        }
                     }
                 }
             }
@@ -170,7 +175,6 @@ export class JITOrchestrator {
     async scrapeHuggingFace(query, limit) {
         const scraper = new HuggingFaceScraper();
         try {
-            // Pass the query as a general search term
             return await scraper.scrape(limit, true, query);
         }
         catch (error) {

package/build/search/query-intent.js

@@ -0,0 +1,409 @@
+import { classifyDomain } from "../metadata/domain.js";
+const STOP_WORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "as", "is", "was", "are", "were", "been",
+    "be", "have", "has", "had", "do", "does", "did", "will", "would",
+    "could", "should", "may", "might", "must", "shall", "can", "need",
+    "about", "into", "through", "during", "before", "after", "above",
+    "below", "between", "under", "again", "further", "then", "once",
+    "here", "there", "when", "where", "why", "how", "all", "each",
+    "few", "more", "most", "other", "some", "such", "no", "nor", "not",
+    "only", "own", "same", "so", "than", "too", "very", "just", "also",
+    "dataset", "datasets", "data", "find", "search", "looking", "need", "want",
+    "give", "show", "me", "please"
+]);
+const LANGUAGE_ALIASES = {
+    english: ["english", "en", "eng"],
+    spanish: ["spanish", "es", "spa"],
+    french: ["french", "fr", "fra"],
+    german: ["german", "de", "deu"],
+    portuguese: ["portuguese", "pt", "por"],
+    chinese: ["chinese", "zh", "cmn"],
+    japanese: ["japanese", "ja", "jpn"],
+    korean: ["korean", "ko", "kor"],
+    arabic: ["arabic", "ar", "ara"],
+    russian: ["russian", "ru", "rus"],
+    hindi: ["hindi", "hi", "hin"],
+    multilingual: ["multilingual", "bilingual", "cross-lingual", "crosslingual"],
+};
+const TASK_PATTERNS = [
+    { task: "translation", patterns: [/\btranslation\b/i, /\bmachine translation\b/i, /\bparallel corpus\b/i] },
+    { task: "question-answering", patterns: [/\bquestion answering\b/i, /\bqa\b/i, /\bq&a\b/i] },
+    { task: "summarization", patterns: [/\bsummarization\b/i, /\bsummary\b/i, /\btl;dr\b/i] },
+    { task: "sentiment-analysis", patterns: [/\bsentiment\b/i, /\bsentiment analysis\b/i] },
+    { task: "text-classification", patterns: [/\bclassification\b/i, /\bclassifier\b/i, /\btext classification\b/i] },
+    { task: "token-classification", patterns: [/\bner\b/i, /\bnamed entity\b/i, /\btoken classification\b/i] },
+    { task: "text-generation", patterns: [/\btext generation\b/i, /\bgenerative\b/i, /\binstruction\b/i, /\bchat\b/i] },
+    { task: "image-classification", patterns: [/\bimage classification\b/i] },
+    { task: "object-detection", patterns: [/\bobject detection\b/i, /\bdetection\b/i] },
+];
+const intentCache = new Map();
+export async function analyzeDatasetQuery(query, requirements) {
+    const cacheKey = `${query || ""}::${requirements || ""}`;
+    const cached = intentCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const task = (async () => {
+        const heuristic = buildHeuristicIntent(query, requirements);
+        const llmIntent = await tryLlmIntent(heuristic, requirements);
+        return llmIntent ? mergeIntent(heuristic, llmIntent) : heuristic;
+    })();
+    intentCache.set(cacheKey, task);
+    return task;
+}
+export function scoreDatasetAgainstIntent(dataset, intent) {
+    if (!intent)
+        return 0;
+    const text = [
+        dataset.name,
+        dataset.description,
+        dataset.task,
+        dataset.domain || "",
+        dataset.tags.join(" "),
+        dataset.languages.join(" "),
+    ].join(" ").toLowerCase();
+    let score = 0;
+    if (intent.language) {
+        const aliases = getLanguageAliases(intent.language);
+        const datasetLanguages = dataset.languages.map(normalizeToken);
+        const languageMatch = aliases.some(alias => datasetLanguages.includes(alias) || text.includes(alias));
+        if (languageMatch) {
+            score += 0.45;
+        }
+        else if (dataset.languages.length > 0) {
+            score -= 0.55;
+        }
+        else {
+            score -= 0.1;
+        }
+    }
+    if (intent.task) {
+        if (matchesTask(dataset, intent.task, text)) {
+            score += 0.35;
+        }
+        else {
+            score -= 0.3;
+        }
+    }
+    if (intent.domain && intent.domain !== "general" && intent.domain !== "unknown") {
+        const datasetDomain = String(dataset.domain || "").toLowerCase();
+        if (datasetDomain === intent.domain || text.includes(intent.domain)) {
+            score += 0.25;
+        }
+        else {
+            score -= 0.2;
+        }
+    }
+    if (intent.minRows && intent.minRows > 0) {
+        const totalExamples = Number(dataset.total_examples || 0);
+        if (totalExamples > 0) {
+            const ratio = totalExamples / intent.minRows;
+            if (ratio >= 1) {
+                score += Math.min(0.45, 0.18 + (Math.log10(ratio + 1) * 0.15));
+            }
+            else if (ratio < 0.05) {
+                score -= 1.2;
+            }
+            else if (ratio < 0.25) {
+                score -= 0.8;
+            }
+            else if (ratio < 0.5) {
+                score -= 0.45;
+            }
+            else {
+                score -= 0.15;
+            }
+        }
+        else {
+            score -= 0.08;
+        }
+    }
+    if (intent.positiveTerms.length > 0) {
+        const matches = intent.positiveTerms.filter(term => text.includes(term)).length;
+        score += Math.min(0.25, matches * 0.06);
+    }
+    if (intent.negativeTerms.some(term => text.includes(term))) {
+        score -= 0.7;
+    }
+    return Math.round(score * 100) / 100;
+}
+export function buildIntentSearchQuery(intent) {
+    return intent.searchQuery;
+}
+function buildHeuristicIntent(query, requirements) {
+    const originalQuery = `${query || ""} ${requirements || ""}`.trim();
+    const normalizedQuery = originalQuery.toLowerCase();
+    const negativeTerms = [...normalizedQuery.matchAll(/(?:^|\s)-([\w-]{2,})/g)].map(match => normalizeToken(match[1]));
+    const positiveTerms = tokenize(normalizedQuery)
+        .filter(token => !negativeTerms.includes(token))
+        .slice(0, 8);
+    const task = detectTask(normalizedQuery);
+    const language = detectLanguage(normalizedQuery);
+    const domain = classifyDomain(normalizedQuery, [], normalizedQuery, task);
+    const minRows = extractRequestedRows(normalizedQuery);
+    const searchTerms = [
+        language,
+        task,
+        domain !== "general" && domain !== "unknown" ? domain : undefined,
+        ...positiveTerms,
+    ].filter((value, index, self) => !!value && self.indexOf(value) === index);
+    return {
+        originalQuery,
+        normalizedQuery,
+        searchQuery: searchTerms.slice(0, 6).join(" ") || normalizedQuery,
+        positiveTerms,
+        negativeTerms,
+        language,
+        task: task || undefined,
+        domain,
+        minRows,
+        llmBacked: false,
+    };
+}
+function mergeIntent(base, llmIntent) {
+    const language = llmIntent.language ? normalizeToken(llmIntent.language) : base.language;
+    const task = llmIntent.task ? normalizeToken(llmIntent.task) : base.task;
+    const domain = llmIntent.domain ? normalizeToken(llmIntent.domain) : base.domain;
+    const minRows = typeof llmIntent.minRows === "number" && Number.isFinite(llmIntent.minRows)
+        ? llmIntent.minRows
+        : base.minRows;
+    const positiveTerms = Array.from(new Set([...(llmIntent.positiveTerms || []), ...base.positiveTerms].map(normalizeToken))).filter(Boolean);
+    const negativeTerms = Array.from(new Set([...(llmIntent.negativeTerms || []), ...base.negativeTerms].map(normalizeToken))).filter(Boolean);
+    const merged = {
+        ...base,
+        language,
+        task,
+        domain,
+        minRows,
+        positiveTerms,
+        negativeTerms,
+        llmBacked: true,
+    };
+    merged.searchQuery = [
+        merged.language,
+        merged.task,
+        merged.domain !== "general" && merged.domain !== "unknown" ? merged.domain : undefined,
+        ...merged.positiveTerms,
+    ].filter((value, index, self) => !!value && self.indexOf(value) === index).slice(0, 6).join(" ") || merged.normalizedQuery;
+    return merged;
+}
+async function tryLlmIntent(base, requirements) {
+    const openAiKey = process.env.OPENAI_API_KEY;
+    if (openAiKey) {
+        return await callOpenAiIntent(base, requirements).catch(() => undefined);
+    }
+    const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+    if (geminiKey) {
+        return await callGeminiIntent(base, requirements, geminiKey).catch(() => undefined);
+    }
+    return undefined;
+}
+async function callOpenAiIntent(base, requirements) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    try {
+        const response = await fetch("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+            },
+            body: JSON.stringify({
+                model: process.env.OPENAI_MODEL || "gpt-4o-mini",
+                temperature: 0,
+                response_format: { type: "json_object" },
+                messages: [
+                    {
+                        role: "system",
+                        content: "Extract dataset search intent as JSON with keys: language, task, domain, minRows, positiveTerms, negativeTerms. Use null for unknowns.",
+                    },
+                    {
+                        role: "user",
+                        content: JSON.stringify({ query: base.originalQuery, requirements: requirements || null, heuristic: base }),
+                    },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        const content = body?.choices?.[0]?.message?.content;
+        return parseIntentPayload(content);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function callGeminiIntent(base, requirements, apiKey) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    try {
+        const model = process.env.GEMINI_MODEL || "gemini-1.5-flash";
+        const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${encodeURIComponent(apiKey)}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                generationConfig: {
+                    temperature: 0,
+                    responseMimeType: "application/json",
+                },
+                contents: [{
+                        role: "user",
+                        parts: [{
+                                text: `Extract dataset search intent as JSON with keys language, task, domain, minRows, positiveTerms, negativeTerms. Query payload: ${JSON.stringify({ query: base.originalQuery, requirements: requirements || null, heuristic: base })}`,
+                            }],
+                    }],
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        const content = body?.candidates?.[0]?.content?.parts?.[0]?.text;
+        return parseIntentPayload(content);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseIntentPayload(content) {
+    if (typeof content !== "string" || !content.trim()) {
+        return undefined;
+    }
+    const jsonText = extractJsonObject(content);
+    if (!jsonText) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(jsonText);
+        return {
+            language: typeof parsed.language === "string" ? parsed.language : undefined,
+            task: typeof parsed.task === "string" ? parsed.task : undefined,
+            domain: typeof parsed.domain === "string" ? parsed.domain : undefined,
+            minRows: typeof parsed.minRows === "number"
+                ? parsed.minRows
+                : typeof parsed.min_rows === "number"
+                    ? parsed.min_rows
+                    : undefined,
+            positiveTerms: Array.isArray(parsed.positiveTerms)
+                ? parsed.positiveTerms.filter((item) => typeof item === "string")
+                : Array.isArray(parsed.positive_terms)
+                    ? parsed.positive_terms.filter((item) => typeof item === "string")
+                    : undefined,
+            negativeTerms: Array.isArray(parsed.negativeTerms)
+                ? parsed.negativeTerms.filter((item) => typeof item === "string")
+                : Array.isArray(parsed.negative_terms)
+                    ? parsed.negative_terms.filter((item) => typeof item === "string")
+                    : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        return trimmed;
+    }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+        return trimmed.slice(start, end + 1);
+    }
+    return undefined;
+}
+function detectLanguage(text) {
+    for (const [language, aliases] of Object.entries(LANGUAGE_ALIASES)) {
+        if (aliases.some(alias => new RegExp(`(^|[^a-z])${escapeRegex(alias)}([^a-z]|$)`, "i").test(text))) {
+            return language;
+        }
+    }
+    return undefined;
+}
+function detectTask(text) {
+    const match = TASK_PATTERNS.find(entry => entry.patterns.some(pattern => pattern.test(text)));
+    return match?.task;
+}
+function tokenize(text) {
+    return Array.from(new Set(text
+        .replace(/[^\w\s-]/g, " ")
+        .split(/\s+/)
+        .map(normalizeToken)
+        .filter(token => token.length > 2 && !STOP_WORDS.has(token) && !/^\d+$/.test(token))));
+}
+function normalizeToken(value) {
+    return value.toLowerCase().replace(/^[^a-z0-9]+|[^a-z0-9-]+$/g, "").trim();
+}
+function extractRequestedRows(text) {
+    const explicit = text.match(/(\d[\d,\s]{1,12})\s*(samples?|rows?|records?)/i);
+    if (explicit) {
+        const value = Number(explicit[1].replace(/[\s,]/g, ""));
+        if (Number.isFinite(value) && value > 0) {
+            return value;
+        }
+    }
+    const humanSized = text.match(/(\d+(?:\.\d+)?)\s*([kmb])\s*(samples?|rows?|records?)/i);
+    if (humanSized) {
+        const base = Number(humanSized[1]);
+        const suffix = humanSized[2].toLowerCase();
+        const multiplier = suffix === "k" ? 1_000 : suffix === "m" ? 1_000_000 : 1_000_000_000;
+        const value = Math.round(base * multiplier);
+        if (Number.isFinite(value) && value > 0) {
+            return value;
+        }
+    }
+    const commaNumbers = [...text.matchAll(/\b\d{1,3}(?:,\d{3})+\b/g)]
+        .map(match => Number(match[0].replace(/,/g, "")))
+        .filter(value => Number.isFinite(value) && value > 0);
+    if (commaNumbers.length > 0) {
+        return Math.max(...commaNumbers);
+    }
+    const humanSizedAnywhere = [...text.matchAll(/\b(\d+(?:\.\d+)?)\s*([kmb])\b/gi)]
+        .map(match => {
+        const base = Number(match[1]);
+        const suffix = match[2].toLowerCase();
+        const multiplier = suffix === "k" ? 1_000 : suffix === "m" ? 1_000_000 : 1_000_000_000;
+        return Math.round(base * multiplier);
+    })
+        .filter(value => Number.isFinite(value) && value > 0);
+    if (humanSizedAnywhere.length > 0) {
+        return Math.max(...humanSizedAnywhere);
+    }
+    const allNumbers = [...text.matchAll(/\b\d{4,9}\b/g)]
+        .map(match => Number(match[0]))
+        .filter(value => Number.isFinite(value) && value > 0);
+    if (allNumbers.length > 0) {
+        return Math.max(...allNumbers);
+    }
+    return undefined;
+}
+function matchesTask(dataset, task, text) {
+    const normalizedTask = normalizeToken(task);
+    const aliases = {
+        "question-answering": ["question-answering", "qa", "question answering"],
+        "text-classification": ["text-classification", "classification", "text classification"],
+        "token-classification": ["token-classification", "ner", "named entity"],
+        "sentiment-analysis": ["sentiment-analysis", "sentiment"],
+        translation: ["translation", "machine-translation", "parallel corpus"],
+        summarization: ["summarization", "summary"],
+        "text-generation": ["text-generation", "generation", "chat", "instruction"],
+        "image-classification": ["image-classification", "image classification"],
+        "object-detection": ["object-detection", "object detection"],
+    };
+    const variants = aliases[normalizedTask] || [normalizedTask];
+    return variants.some(variant => normalizeToken(dataset.task).includes(variant) || text.includes(variant));
+}
+function getLanguageAliases(language) {
+    const normalized = normalizeToken(language);
+    return (LANGUAGE_ALIASES[normalized] || [normalized]).map(normalizeToken);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/build/utils/python-runtime.js

@@ -0,0 +1,130 @@
+import { spawn } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+function getHomeDir(buildDir) {
+    return os.homedir() || process.env.HOME || process.env.USERPROFILE || buildDir;
+}
+export function getVesperDataRoot(buildDir = process.cwd()) {
+    return path.join(getHomeDir(buildDir), ".vesper");
+}
+export function getManagedPythonPath(buildDir = process.cwd()) {
+    const dataRoot = getVesperDataRoot(buildDir);
+    return process.platform === "win32"
+        ? path.join(dataRoot, ".venv", "Scripts", "python.exe")
+        : path.join(dataRoot, ".venv", "bin", "python");
+}
+function getFallbackPythonCommand() {
+    return process.platform === "win32" ? "py" : "python3";
+}
+export function resolvePythonCommand(buildDir = process.cwd()) {
+    const managedPython = getManagedPythonPath(buildDir);
+    if (fs.existsSync(managedPython)) {
+        return managedPython;
+    }
+    const envPython = process.env.VESPER_PYTHON;
+    if (envPython) {
+        return envPython;
+    }
+    const localCandidates = process.platform === "win32"
+        ? [
+            path.resolve(buildDir, ".venv", "Scripts", "python.exe"),
+            path.resolve(buildDir, "..", ".venv", "Scripts", "python.exe")
+        ]
+        : [
+            path.resolve(buildDir, ".venv", "bin", "python"),
+            path.resolve(buildDir, "..", ".venv", "bin", "python")
+        ];
+    for (const candidate of localCandidates) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return getFallbackPythonCommand();
+}
+function runPythonCommand(pythonPath, args, timeoutMs = 300000) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(pythonPath, args, {
+            env: {
+                ...process.env,
+                PYTHONIOENCODING: "utf-8",
+            },
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            proc.kill();
+            resolve({ code: 124, stdout, stderr: stderr || `Python command timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+        proc.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function createManagedPythonEnv(buildDir) {
+    const dataRoot = getVesperDataRoot(buildDir);
+    const venvDir = path.join(dataRoot, ".venv");
+    const managedPython = getManagedPythonPath(buildDir);
+    if (fs.existsSync(managedPython)) {
+        return managedPython;
+    }
+    fs.mkdirSync(dataRoot, { recursive: true });
+    const bootstrapAttempts = process.platform === "win32"
+        ? [
+            { command: "py", args: ["-3", "-m", "venv", venvDir] },
+            { command: "python", args: ["-m", "venv", venvDir] },
+        ]
+        : [
+            { command: "python3", args: ["-m", "venv", venvDir] },
+            { command: "python", args: ["-m", "venv", venvDir] },
+        ];
+    let lastError = "";
+    for (const attempt of bootstrapAttempts) {
+        try {
+            const result = await runPythonCommand(attempt.command, attempt.args, 180000);
+            if (result.code === 0 && fs.existsSync(managedPython)) {
+                await runPythonCommand(managedPython, ["-m", "pip", "install", "--disable-pip-version-check", "--upgrade", "pip"], 300000);
+                return managedPython;
+            }
+            lastError = (result.stderr || result.stdout || "Unknown venv creation error").trim();
+        }
+        catch (error) {
+            lastError = error?.message || String(error);
+        }
+    }
+    throw new Error(`Failed to create Vesper Python environment. ${lastError}`.trim());
+}
+export async function ensurePythonPackages(buildDir, requirements) {
+    const pythonPath = await createManagedPythonEnv(buildDir).catch(() => resolvePythonCommand(buildDir));
+    const missing = [];
+    for (const requirement of requirements) {
+        const check = await runPythonCommand(pythonPath, [
+            "-c",
+            `import importlib.util,sys; sys.exit(0 if importlib.util.find_spec(${JSON.stringify(requirement.module)}) else 1)`
+        ], 20000);
+        if (check.code !== 0) {
+            missing.push(requirement);
+        }
+    }
+    if (missing.length === 0) {
+        return pythonPath;
+    }
+    const packages = [...new Set(missing.map(requirement => requirement.packageName))];
+    const install = await runPythonCommand(pythonPath, ["-m", "pip", "install", "--disable-pip-version-check", ...packages], 600000);
+    if (install.code !== 0) {
+        const details = (install.stderr || install.stdout || "Unknown pip install error").trim();
+        throw new Error(`Failed to install Python packages (${packages.join(", ")}). ${details}`);
+    }
+    return pythonPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vesper-wizard",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "description": "AI-powered dataset discovery, quality analysis, and preparation MCP server with multimodal support (text, image, audio, video)",
   "type": "module",
   "main": "build/index.js",

package/scripts/postinstall.cjs

@@ -2,13 +2,34 @@
 
 const { execSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 console.log('\n🚀 Setting up Vesper MCP Server...\n');
 
+function getPythonBootstrapCommand() {
+    const attempts = process.platform === 'win32'
+        ? ['py -3', 'python']
+        : ['python3', 'python'];
+
+    for (const command of attempts) {
+        try {
+            execSync(`${command} --version`, { stdio: 'pipe' });
+            return command;
+        } catch {
+            // try next command
+        }
+    }
+
+    return null;
+}
+
 // 1. Check for Python
+const pythonBootstrap = getPythonBootstrapCommand();
 try {
-    execSync('python --version', { stdio: 'pipe' });
+    if (!pythonBootstrap) {
+        throw new Error('Python not found');
+    }
     console.log('✅ Python found');
 } catch (e) {
     console.warn('⚠️  Python not found. Please install Python 3.8+ for full functionality.');
@@ -16,36 +37,15 @@ try {
     process.exit(0); // Don't fail installation
 }
 
-// 2. Install Python dependencies
-console.log('\n📦 Installing Python dependencies...');
-const pythonPackages = [
-    'opencv-python',
-    'pillow',
-    'numpy',
-    'librosa',
-    'soundfile',
-    'aiohttp',
-    'aiofiles',
-    'datasets',
-    'webdataset',
-    'kaggle'
-];
-
-try {
-    execSync(`python -m pip install ${pythonPackages.join(' ')}`, {
-        stdio: 'inherit',
-        timeout: 120000 // 2 minutes timeout
-    });
-    console.log('✅ Python dependencies installed');
-} catch (e) {
-    console.warn('⚠️  Failed to install some Python dependencies.');
-    console.warn('   You may need to install them manually:');
-    console.warn(`   pip install ${pythonPackages.join(' ')}\n`);
-}
-
-// 3. Create data directories
-const homeDir = process.env.HOME || process.env.USERPROFILE;
+const homeDir = os.homedir() || process.env.HOME || process.env.USERPROFILE;
 const vesperDataDir = path.join(homeDir, '.vesper');
+const managedVenvDir = path.join(vesperDataDir, '.venv');
+const managedPython = process.platform === 'win32'
+    ? path.join(managedVenvDir, 'Scripts', 'python.exe')
+    : path.join(managedVenvDir, 'bin', 'python');
+const requirementsPath = path.resolve(__dirname, '..', 'requirements.txt');
+
+// 2. Create data directories
 const dirs = [
     vesperDataDir,
     path.join(vesperDataDir, 'data'),
@@ -62,7 +62,49 @@ dirs.forEach(dir => {
 
 console.log(`✅ Data directories created at ${vesperDataDir}`);
 
-// 4. Rebuild better-sqlite3 for current Node.js version
+// 3. Create a managed Vesper Python environment
+console.log('\n🐍 Preparing managed Python environment...');
+try {
+    if (!fs.existsSync(managedPython)) {
+        execSync(`${pythonBootstrap} -m venv "${managedVenvDir}"`, {
+            stdio: 'inherit',
+            timeout: 180000,
+        });
+    }
+    console.log(`✅ Managed Python ready at ${managedVenvDir}`);
+} catch (e) {
+    console.warn('⚠️  Failed to create the managed Vesper Python environment.');
+    console.warn(`   Vesper will fall back to PATH Python and may need to self-heal at runtime. ${(e && e.message) || ''}`.trim());
+}
+
+// 4. Install Python dependencies into the managed environment
+console.log('\n📦 Installing Python dependencies...');
+const pythonPackages = [
+    'opencv-python',
+    'pillow',
+    'librosa',
+    'soundfile',
+    'pyarrow'
+];
+
+try {
+    const targetPython = fs.existsSync(managedPython) ? `"${managedPython}"` : pythonBootstrap;
+    execSync(`${targetPython} -m pip install --disable-pip-version-check --upgrade pip`, {
+        stdio: 'inherit',
+        timeout: 180000,
+    });
+    execSync(`${targetPython} -m pip install --disable-pip-version-check -r "${requirementsPath}" ${pythonPackages.join(' ')}`, {
+        stdio: 'inherit',
+        timeout: 600000,
+    });
+    console.log('✅ Python dependencies installed');
+} catch (e) {
+    console.warn('⚠️  Failed to install some Python dependencies.');
+    console.warn('   You may need to install them manually into the Vesper runtime:');
+    console.warn(`   ${fs.existsSync(managedPython) ? managedPython : pythonBootstrap} -m pip install -r "${requirementsPath}" ${pythonPackages.join(' ')}\n`);
+}
+
+// 5. Rebuild better-sqlite3 for current Node.js version
 console.log('\n🔧 Rebuilding native modules for current Node.js...');
 try {
     execSync('npm rebuild better-sqlite3', {
@@ -76,7 +118,7 @@ try {
     console.warn('   If you see ERR_DLOPEN_FAILED, run: npm rebuild better-sqlite3');
 }
 
-// 5. Auto-configure Claude Desktop (Best Effort)
+// 6. Auto-configure Claude Desktop (Best Effort)
 console.log('\n⚙️  Attempting to auto-configure Claude Desktop...');
 
 function getClaudeConfigPath() {