@barivia/barsom-mcp 0.2.4 → 0.2.6

package/dist/index.js

@@ -7,7 +7,7 @@
  * BARIVIA_API_URL as environment variables.
  *
  * Usage (in MCP client config, e.g. Cursor / Claude Desktop):
- *
+
  *   {
  *     "mcpServers": {
  *       "analytics-engine": {
@@ -263,64 +263,142 @@ registerAppTool(server, "explore_som", {
     await tryAttachImage(content, job_id, `combined.${imgExt}`);
     return { content };
 });
-// ---- upload_dataset ----
-server.tool("upload_dataset", `Upload a CSV dataset for SOM analysis. Returns dataset metadata including ID.
-
-PREFER file_path over csv_data: when the user points to a local file, use file_path.
-The MCP reads the file directly — no need to pass large CSV strings through the LLM.
-
-BEST FOR: Tabular data with numeric columns (sensor readings, financial data, process
-measurements, survey results). CSV with header row required.
-NOT FOR: Images, text documents, or pre-trained embeddings.
-
-TIMING: Upload is near-instant for datasets under 100MB.
-
-AFTER uploading, ask the user these questions to guide the analysis:
-1. "What are you trying to discover in this data?" (clustering, anomalies, temporal patterns)
-2. "Are any columns cyclic/periodic?" (hour=24, weekday=7, wind direction=360)
-3. "Are any columns irrelevant or should be excluded?"
-4. "Should any features be weighted more heavily?"
-5. "Do any columns have very skewed distributions?" (suggest transforms)
-
-COMMON MISTAKES:
-- Uploading without previewing first — always use preview_dataset before train_som
-- Including ID columns or row indices — these add noise without meaning
-- Forgetting to check for datetime columns that could provide temporal features
-
-Show the column names from the response so the user can identify features.
-TIP: Use the prepare_training prompt for a structured preprocessing checklist.`, {
-    name: z.string().describe("Human-readable dataset name"),
-    file_path: z
-        .string()
+// ---- datasets ----
+server.tool("datasets", `Manage datasets: upload, preview, subset, or delete.
+
+action=upload: Upload a CSV for SOM analysis. Prefer file_path over csv_data so the MCP reads the file directly. Returns dataset ID and metadata. Then use datasets(action=preview) before train_som.
+action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train_som on an unfamiliar dataset.
+action=subset: Create a new dataset from a subset of an existing one (by row range and/or column filter). Use to train on a slice (e.g. first 2000 rows, or region=Europe) without re-uploading. Requires name and at least one of row_range or filter. row_range: [start, end] 1-based inclusive. filter: { column, op, value } with op in eq, in, gt, lt, gte, lte.
+action=delete: Remove a dataset and free the slot.
+
+BEST FOR: Tabular numeric data. CSV with header required. Use list(type=datasets) to see existing datasets. To train on a subset, use datasets(action=subset) then train_som on the new dataset_id, or pass row_range in train_som params.`, {
+    action: z
+        .enum(["upload", "preview", "subset", "delete"])
+        .describe("upload: add a CSV; preview: inspect before training; subset: create subset dataset; delete: remove dataset"),
+    name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
+    file_path: z.string().optional().describe("Path to local CSV (for upload; prefer over csv_data)"),
+    csv_data: z.string().optional().describe("Inline CSV string (for upload; use for small data)"),
+    dataset_id: z.string().optional().describe("Dataset ID (required for preview, subset, and delete)"),
+    n_rows: z.number().int().optional().default(5).describe("Sample rows to return (preview only)"),
+    row_range: z
+        .tuple([z.number().int(), z.number().int()])
         .optional()
-        .describe("Path to a local CSV file. Use this when the user has a file on disk — the MCP reads it directly. Absolute or relative to the MCP process CWD (often the project root)."),
-    csv_data: z
-        .string()
+        .describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),
+    filter: z
+        .object({
+        column: z.string(),
+        op: z.enum(["eq", "in", "gt", "lt", "gte", "lte"]),
+        value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
+    })
         .optional()
-        .describe("CSV data with header row. Use for small inline data (<10KB). Prefer file_path for larger files."),
-}, async ({ name, file_path, csv_data }) => {
-    let body;
-    if (file_path) {
-        const resolved = path.resolve(file_path);
-        try {
-            body = await fs.readFile(resolved, "utf-8");
+        .describe("For subset: filter rows by column value (e.g. { column: 'region', op: 'eq', value: 'Europe' })"),
+}, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filter }) => {
+    if (action === "upload") {
+        if (!name)
+            throw new Error("datasets(upload) requires name");
+        let body;
+        if (file_path) {
+            const resolved = path.resolve(file_path);
+            try {
+                body = await fs.readFile(resolved, "utf-8");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Cannot read file "${resolved}": ${msg}`);
+            }
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Cannot read file "${resolved}": ${msg}`);
+        else if (csv_data && csv_data.length > 0) {
+            body = csv_data;
         }
+        else {
+            throw new Error("datasets(upload) requires file_path or csv_data");
+        }
+        const data = await apiCall("POST", "/v1/datasets", body, {
+            "X-Dataset-Name": name,
+            "Content-Type": "text/csv",
+        });
+        return textResult(data);
+    }
+    if (action === "preview") {
+        if (!dataset_id)
+            throw new Error("datasets(preview) requires dataset_id");
+        const data = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=${n_rows ?? 5}`));
+        const cols = data.columns ?? [];
+        const stats = data.column_stats ?? [];
+        const hints = data.cyclic_hints ?? [];
+        const samples = data.sample_rows ?? [];
+        const dtCols = data.datetime_columns ?? [];
+        const temporalSugg = data.temporal_suggestions ?? [];
+        const fmt = (v) => v === null || v === undefined ? "—" : Number(v).toFixed(3);
+        const lines = [
+            `Dataset: ${data.name} (${data.dataset_id})`,
+            `${data.total_rows} rows × ${data.total_cols} columns`,
+            ``,
+            `Column Statistics:`,
+            `| Column | Min | Max | Mean | Std | Nulls | Numeric |`,
+            `|--------|-----|-----|------|-----|-------|---------|`,
+        ];
+        for (const s of stats) {
+            lines.push(`| ${s.column} | ${fmt(s.min)} | ${fmt(s.max)} | ${fmt(s.mean)} | ${fmt(s.std)} | ${s.null_count ?? 0} | ${s.is_numeric !== false ? "yes" : "no"} |`);
+        }
+        if (hints.length > 0) {
+            lines.push(``, `Detected Cyclic Feature Hints:`);
+            for (const h of hints) {
+                lines.push(`  • ${h.column} — period=${h.period} (${h.reason})`);
+            }
+        }
+        if (dtCols.length > 0) {
+            lines.push(``, `Detected Datetime Columns:`);
+            for (const dc of dtCols) {
+                const formats = dc.detected_formats ?? [];
+                const fmtStrs = formats
+                    .map((f) => `${f.format} — ${f.description} (${(f.match_rate * 100).toFixed(0)}% match)`)
+                    .join("; ");
+                lines.push(`  • ${dc.column}: sample="${dc.sample}" → ${fmtStrs}`);
+            }
+        }
+        if (temporalSugg.length > 0) {
+            lines.push(``, `Temporal Feature Suggestions (require user approval):`);
+            for (const ts of temporalSugg) {
+                lines.push(`  • Columns: ${ts.columns.join(" + ")} → format: "${ts.format}"`);
+                lines.push(`    Available components: ${ts.available_components.join(", ")}`);
+            }
+        }
+        if (samples.length > 0) {
+            lines.push(``, `Sample Rows (first ${samples.length}):`);
+            lines.push(`| ${cols.join(" | ")} |`);
+            lines.push(`| ${cols.map(() => "---").join(" | ")} |`);
+            for (const row of samples) {
+                lines.push(`| ${cols.map((c) => String(row[c] ?? "")).join(" | ")} |`);
+            }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    if (action === "subset") {
+        if (!dataset_id)
+            throw new Error("datasets(subset) requires dataset_id");
+        if (!name)
+            throw new Error("datasets(subset) requires name");
+        if (row_range === undefined && filter === undefined) {
+            throw new Error("datasets(subset) requires at least one of row_range or filter");
+        }
+        const body = { name };
+        if (row_range !== undefined)
+            body.row_range = row_range;
+        if (filter !== undefined)
+            body.filter = filter;
+        const data = await apiCall("POST", `/v1/datasets/${dataset_id}/subset`, JSON.stringify(body), {
+            "Content-Type": "application/json",
+        });
+        return textResult(data);
     }
-    else if (csv_data && csv_data.length > 0) {
-        body = csv_data;
-    }
-    else {
-        throw new Error("Provide either file_path or csv_data");
+    if (action === "delete") {
+        if (!dataset_id)
+            throw new Error("datasets(delete) requires dataset_id");
+        const data = await apiCall("DELETE", `/v1/datasets/${dataset_id}`);
+        return textResult(data);
     }
-    const data = await apiCall("POST", "/v1/datasets", body, {
-        "X-Dataset-Name": name,
-        "Content-Type": "text/csv",
-    });
-    return textResult(data);
+    throw new Error("Invalid action");
 });
 // ---- train_som ----
 server.tool("train_som", `Train a Self-Organizing Map on the dataset. Returns a job_id for polling.
@@ -343,11 +421,11 @@ BEFORE calling, ask the user:
 5. Quick exploration or refined map?
 
 PRESET TABLE:
-| preset   | grid  | epochs   | batch_size |
-| quick    | 15x15 | [10, 0]  | 64         |
-| standard | 25x25 | [20, 10] | 64         |
-| refined  | 40x40 | [40, 20] | 32         |
-| high_res | 60x60 | [50, 30] | 32         |
+| preset   | grid  | epochs    | batch_size |
+| quick    | 15x15 | [15, 5]   | 48         |
+| standard | 25x25 | [30, 15]  | 48         |
+| refined  | 40x40 | [50, 25]  | 32         |
+| high_res | 60x60 | [60, 40]  | 32         |
 
 TRAINING PHASES:
 - Ordering: large neighborhoods → global structure. sigma_f controls end-radius (default 1.0).
@@ -356,7 +434,7 @@ TRAINING PHASES:
 
 TRANSFORMS: Per-column preprocessing before normalization.
   transforms: {revenue: "log", volume: "log1p", pressure: "sqrt"}
-  Suggest when preview_dataset shows large value ranges or right-skewed distributions.
+  Suggest when datasets(action=preview) shows large value ranges or right-skewed distributions.
 
 TEMPORAL FEATURES: NEVER auto-apply. Always ask which components to extract.
   temporal_features: [{columns: ['Date'], format: 'dd.mm.yyyy', extract: ['day_of_year'], cyclic: true}]
@@ -370,25 +448,25 @@ COMMON MISTAKES:
 - Not log-transforming skewed columns → a few outliers dominate the normalization.
 - Using default batch_size for quality-sensitive work: set batch_size=32–64 for sharper maps.
 - Skipping convergence phase: ordering alone gives rough structure; convergence refines it.
-- Not checking get_training_log: if QE is still dropping, add more epochs.
+- Not checking get_job_export(export="training_log"): if QE is still dropping, add more epochs.
 
 QUALITY TARGETS: QE < 1.5 good, TE < 0.05 good, explained variance > 0.8 good.
 If QE > 2 → more epochs or larger grid. If TE > 0.15 → larger grid or periodic=true.
 
-OUTPUT: format (png/pdf/svg), dpi (standard/retina/print), colormap (viridis/plasma/inferno).
+OUTPUT: format (png/pdf/svg), dpi (standard/retina/print), colormap (e.g. viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral).
 
 After training, use get_results → analyze(clusters) → component_planes → feature_correlation.
 See docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.`, {
-    dataset_id: z.string().describe("Dataset ID from upload_dataset"),
+    dataset_id: z.string().describe("Dataset ID from datasets(action=upload) or list(type=datasets)"),
     preset: z
         .enum(["quick", "standard", "refined", "high_res"])
         .optional()
         .describe("Training preset — sets sensible defaults for grid, epochs, and batch_size. " +
         "Explicit params override preset values. " +
-        "quick: 15×15, [10,0], batch=64. " +
-        "standard: 25×25, [20,10], batch=64, best with GPU. " +
-        "refined: 40×40, [40,20], batch=32, best with GPU. " +
-        "high_res: 60×60, [50,30], batch=32, best with GPU."),
+        "quick: 15×15, [15,5], batch=48. " +
+        "standard: 25×25, [30,15], batch=48, best with GPU. " +
+        "refined: 40×40, [50,25], batch=32, best with GPU. " +
+        "high_res: 60×60, [60,40], batch=32, best with GPU."),
     grid_x: z
         .number()
         .int()
@@ -529,13 +607,17 @@ See docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.`,
     colormap: z
         .string()
         .optional()
-        .describe("Override default colormap for component planes (e.g. viridis, plasma, inferno, coolwarm). U-matrix always uses grays, cyclic features use twilight."),
-}, async ({ dataset_id, preset, grid_x, grid_y, epochs, model, periodic, columns, transforms, cyclic_features, temporal_features, feature_weights, normalize, sigma_f, learning_rate, batch_size, backend, output_format, output_dpi, colormap, }) => {
+        .describe("Override default colormap for component planes and hit histogram. Examples: viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix always uses grays, cyclic features use twilight."),
+    row_range: z
+        .tuple([z.number().int().min(1), z.number().int().min(1)])
+        .optional()
+        .describe("Train on a subset of rows only: [start, end] 1-based inclusive. Alternative to creating a subset dataset with datasets(action=subset)."),
+}, async ({ dataset_id, preset, grid_x, grid_y, epochs, model, periodic, columns, transforms, cyclic_features, temporal_features, feature_weights, normalize, sigma_f, learning_rate, batch_size, backend, output_format, output_dpi, colormap, row_range, }) => {
     const PRESETS = {
-        quick: { grid: [15, 15], epochs: [10, 0], batch_size: 64 },
-        standard: { grid: [25, 25], epochs: [20, 10], batch_size: 64, backend: "cuda" },
-        refined: { grid: [40, 40], epochs: [40, 20], batch_size: 32, backend: "cuda" },
-        high_res: { grid: [60, 60], epochs: [50, 30], batch_size: 32, backend: "cuda" },
+        quick: { grid: [15, 15], epochs: [15, 5], batch_size: 48 },
+        standard: { grid: [25, 25], epochs: [30, 15], batch_size: 48, backend: "cuda" },
+        refined: { grid: [40, 40], epochs: [50, 25], batch_size: 32, backend: "cuda" },
+        high_res: { grid: [60, 60], epochs: [60, 40], batch_size: 32, backend: "cuda" },
     };
     const p = preset ? PRESETS[preset] : undefined;
     const params = {
@@ -598,6 +680,9 @@ See docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.`,
     if (colormap) {
         params.colormap = colormap;
     }
+    if (row_range && row_range.length >= 2 && row_range[0] <= row_range[1]) {
+        params.row_range = row_range;
+    }
     const data = await apiCall("POST", "/v1/jobs", { dataset_id, params });
     return textResult(data);
 });
@@ -624,6 +709,59 @@ When status is 'failed', show the error to the user and suggest parameter adjust
     }
     return { content: [{ type: "text", text }] };
 });
+/** Resolve get_results figures param to list of image filenames to fetch. */
+function getResultsImagesToFetch(jobType, summary, figures, includeIndividual) {
+    const ext = summary.output_format ?? "png";
+    if (jobType === "transition_flow") {
+        const lag = summary.lag ?? 1;
+        return [`transition_flow_lag${lag}.${ext}`];
+    }
+    if (jobType === "project_variable") {
+        const varName = summary.variable_name ?? "variable";
+        const safe = String(varName).replace(/[^a-zA-Z0-9_]/g, "_");
+        return [`projected_${safe}.${ext}`];
+    }
+    if (jobType === "derive_variable") {
+        const varName = summary.variable_name ?? "variable";
+        const safe = String(varName).replace(/[^a-zA-Z0-9_]/g, "_");
+        return [`projected_${safe}.${ext}`];
+    }
+    // train_som
+    const features = summary.features ?? [];
+    const combinedName = `combined.${ext}`;
+    const umatrixName = `umatrix.${ext}`;
+    const hitHistName = `hit_histogram.${ext}`;
+    const componentNames = features.map((f, i) => `component_${i + 1}_${f.replace(/[^a-zA-Z0-9_]/g, "_")}.${ext}`);
+    const allList = [combinedName, umatrixName, hitHistName, ...componentNames];
+    if (figures === undefined || figures === "default") {
+        return includeIndividual ? allList : [combinedName];
+    }
+    if (figures === "combined_only")
+        return [combinedName];
+    if (figures === "all")
+        return allList;
+    if (Array.isArray(figures)) {
+        const nameToFile = {
+            combined: combinedName,
+            umatrix: umatrixName,
+            hit_histogram: hitHistName,
+        };
+        features.forEach((_, i) => {
+            nameToFile[`component_${i + 1}`] = componentNames[i];
+        });
+        return figures
+            .map((key) => {
+            const k = key.trim().toLowerCase();
+            if (nameToFile[k])
+                return nameToFile[k];
+            if (key.includes("."))
+                return key;
+            return null;
+        })
+            .filter((f) => f != null);
+    }
+    return [combinedName];
+}
 // ---- get_results ----
 server.tool("get_results", `Retrieve results of a completed SOM training, projection, or derived variable job.
 
@@ -632,11 +770,15 @@ TIMING: Near-instant (reads pre-computed results from S3).
 
 Returns: text summary with metrics and inline images (combined view and all plots shown directly in chat).
 
-DOWNLOAD LINKS: Links to API-domain or presigned URLs may not work when clicked (MCP holds the API key, not the browser). Images are inlined. For weights, use get_weights. For node stats, use get_node_data. If the user wants to save a file, offer to fetch and return the content via the appropriate tool.
+DOWNLOAD LINKS: Links to API-domain or presigned URLs may not work when clicked (MCP holds the API key, not the browser). Images are inlined. For weights use get_job_export(export="weights"); for node stats use get_job_export(export="nodes"). If the user wants to save a file, offer to fetch via the appropriate tool.
 
 OPTIONS:
-- include_individual=true: shows each component plane, U-matrix, and hit histogram
-  as separate inline images. Best for side-by-side feature comparison.
+- figures: request specific plots only. Omit for default (combined only; or all if include_individual=true).
+  - "combined_only": only the combined view.
+  - "all": combined + umatrix + hit_histogram + all component planes.
+  - Array of logical names: e.g. figures: ["umatrix"] for just the U-matrix, or figures: ["combined","hit_histogram"] or ["combined","umatrix","component_1","component_2"]. Logical names: combined, umatrix, hit_histogram, component_1, component_2, ... (component_N = Nth feature).
+- include_individual=true: when figures is omitted, shows each component plane, U-matrix, and hit histogram
+  as separate inline images. Ignored when figures is set.
 
 AFTER showing results, guide the user:
 1. "The U-matrix shows [N] distinct regions. Does this match expected groupings?"
@@ -647,20 +789,28 @@ AFTER showing results, guide the user:
 6. If explained variance < 0.7: suggest transforms, feature selection, or more training
 
 WORKFLOW: get_results → analyze(clusters) → component_planes → feature_correlation.
-Use get_training_log() for the learning curve (QE vs epoch — healthy=steady decline then plateau).
-Use quality_report() for extended metrics (trustworthiness, neighborhood preservation).
+Request specific figures with get_results(job_id, figures=[...]) (e.g. figures: ["umatrix"] or figures: ["combined","hit_histogram"]) or run analyze(job_id, analysis_type) for a single view.
+Use get_job_export(export="training_log") for the learning curve (QE vs epoch — healthy=steady decline then plateau).
+Use analyze(job_id, "quality_report") for extended metrics (trustworthiness, neighborhood preservation).
 
 METRIC INTERPRETATION:
 - QE < 1.5: good fit. QE > 2: consider more epochs, larger grid, or batch_size=32.
 - TE < 0.05: good topology. TE > 0.15: grid too small.
 - Explained variance > 0.8: good. < 0.7: try transforms, fewer features, or more training.`, {
     job_id: z.string().describe("Job ID of a completed job"),
+    figures: z
+        .union([
+        z.enum(["default", "combined_only", "all"]),
+        z.array(z.string()),
+    ])
+        .optional()
+        .describe("Which figures to return. Omit or 'default' for combined only (or all if include_individual=true). 'combined_only': just combined view. 'all': combined + umatrix + hit_histogram + all component planes. Or array of logical names: combined, umatrix, hit_histogram, component_1, component_2, ..."),
     include_individual: z
         .boolean()
         .optional()
         .default(false)
-        .describe("If true, inline each individual plot (component planes, u-matrix, hit histogram) separately instead of just the combined view. Useful for side-by-side feature comparison or publication-quality individual figures."),
-}, async ({ job_id, include_individual }) => {
+        .describe("If true and figures is omitted, inline each individual plot (component planes, u-matrix, hit histogram). Ignored when figures is set."),
+}, async ({ job_id, figures, include_individual }) => {
     const data = (await apiCall("GET", `/v1/results/${job_id}`));
     const summary = (data.summary ?? {});
     const downloadUrls = (data.download_urls ?? {});
@@ -691,8 +841,10 @@ METRIC INTERPRETATION:
                 `Use transition_flow(lag=N) with larger N to reveal longer-term temporal structure.`,
             ].join("\n"),
         });
-        await tryAttachImage(content, job_id, flowImg);
-        inlinedImages.add(flowImg);
+        for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
+            await tryAttachImage(content, job_id, name);
+            inlinedImages.add(name);
+        }
     }
     else if (jobType === "project_variable") {
         const varName = summary.variable_name ?? "variable";
@@ -715,8 +867,10 @@ METRIC INTERPRETATION:
                 `learned feature space, even if it wasn't used in training.`,
             ].join("\n"),
         });
-        await tryAttachImage(content, job_id, projImg);
-        inlinedImages.add(projImg);
+        for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
+            await tryAttachImage(content, job_id, name);
+            inlinedImages.add(name);
+        }
     }
     else {
         // ── Default: train_som results ──────────────────────────────────────────
@@ -747,7 +901,7 @@ METRIC INTERPRETATION:
             `  Davies-Bouldin:     ${fmt(summary.davies_bouldin)}      (lower is better)`,
             `  Calinski-Harabasz:  ${fmt(summary.calinski_harabasz)}   (higher is better)`,
             ordErrors && ordErrors.length > 0
-                ? `  Final ordering QE: ${ordErrors.at(-1)?.toFixed(4)} (use get_training_log for full curve)`
+                ? `  Final ordering QE: ${ordErrors.at(-1)?.toFixed(4)} (use get_job_export(export="training_log") for full curve)`
                 : "",
             ``,
             `Features: ${features.join(", ")}`,
@@ -758,34 +912,16 @@ METRIC INTERPRETATION:
                 ? `Transforms: ${Object.entries(summary.transforms).map(([k, v]) => `${k}=${v}`).join(", ")}`
                 : "",
             ``,
-            `Use analyze() for deeper insights, quality_report() for extended metrics, get_training_log() for learning curves.`,
+            `Use analyze() for deeper insights and quality_report; get_job_export(export="training_log") for learning curves.`,
         ]
             .filter((l) => l !== "")
             .join("\n");
         content.push({ type: "text", text: textSummary });
         const imgExt = summary.output_format ?? "png";
-        const combinedName = `combined.${imgExt}`;
-        await tryAttachImage(content, job_id, combinedName);
-        inlinedImages.add(combinedName);
-        if (include_individual) {
-            const feats = summary.features ?? [];
-            const imageNames = [
-                `umatrix.${imgExt}`,
-                `hit_histogram.${imgExt}`,
-                ...feats.map((f, i) => `component_${i + 1}_${f.replace(/[^a-zA-Z0-9_]/g, "_")}.${imgExt}`),
-            ];
-            const results = await Promise.allSettled(imageNames.map((name) => apiRawCall(`/v1/results/${job_id}/image/${name}`).then((r) => ({ name, ...r }))));
-            for (const r of results) {
-                if (r.status === "fulfilled") {
-                    content.push({
-                        type: "image",
-                        data: r.value.data.toString("base64"),
-                        mimeType: mimeForFilename(r.value.name),
-                        annotations: { audience: ["user"], priority: 0.8 },
-                    });
-                    inlinedImages.add(r.value.name);
-                }
-            }
+        const imagesToFetch = getResultsImagesToFetch(jobType, summary, figures, include_individual);
+        for (const name of imagesToFetch) {
+            await tryAttachImage(content, job_id, name);
+            inlinedImages.add(name);
         }
     }
     // Inline remaining image files; for JSON provide tool hints (no clickable URLs — auth required)
@@ -797,21 +933,114 @@ METRIC INTERPRETATION:
         }
         else if (fname.endsWith(".json")) {
             const hint = fname === "weights.json"
-                ? `Use get_weights for full weight matrix including node_coords.`
+                ? `Use get_job_export(export="weights") for full weight matrix including node_coords.`
                 : fname === "node_stats.json"
-                    ? `Use get_node_data for per-node statistics.`
+                    ? `Use get_job_export(export="nodes") for per-node statistics.`
                     : fname === "summary.json"
                         ? null
-                        : `Use get_weights or get_node_data for structured data.`;
+                        : `Use get_job_export for structured data (weights or nodes).`;
             if (hint) {
                 content.push({ type: "text", text: `${fname}: ${hint}` });
             }
         }
     }
+    // List available artifacts so the LLM can offer to fetch specific views
+    if (files.length > 0) {
+        const features = summary.features ?? [];
+        const logicalNames = jobType === "train_som"
+            ? `Logical names: combined, umatrix, hit_histogram, ${features.map((_, i) => `component_${i + 1}`).join(", ")}. `
+            : "";
+        content.push({
+            type: "text",
+            text: `Available to fetch individually: ${files.join(", ")}. ${logicalNames}Use get_results(job_id, figures=[...]) to request specific plots, get_results(job_id, include_individual=true) or figures="all" to inline all plots, or analyze(job_id, analysis_type) for a specific view (u_matrix, component_planes, bmu_hits, clusters, quality_report, etc.).`,
+        });
+    }
+    return { content };
+});
+// ---- recolor_som ----
+server.tool("recolor_som", `Re-render a completed SOM result with a different colormap — no retraining.
+
+Use when the user wants to see the same combined (or other) plot with another color scheme (e.g. plasma, inferno, coolwarm). Submits a short render job; when complete, use get_results(new_job_id) or get_result_image to retrieve the recolored figure(s).
+
+Colormaps: e.g. viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix and cyclic panels keep fixed colormaps (grays, twilight).`, {
+    job_id: z.string().describe("Job ID of a completed SOM training job (parent)"),
+    colormap: z.string().describe("Colormap name (e.g. viridis, plasma, inferno, magma, coolwarm)"),
+    figures: z
+        .array(z.string())
+        .optional()
+        .default(["combined"])
+        .describe("Which figures to re-render: combined (default), umatrix, hit_histogram, component_1, component_2, ..."),
+    output_format: z.enum(["png", "pdf", "svg"]).optional().default("png"),
+    output_dpi: z.number().int().min(1).max(4).optional().default(2),
+}, async ({ job_id, colormap, figures, output_format, output_dpi }) => {
+    const body = { colormap, figures, output_format, output_dpi };
+    const data = (await apiCall("POST", `/v1/results/${job_id}/render`, JSON.stringify(body), {
+        "Content-Type": "application/json",
+    }));
+    const newJobId = data.id;
+    const content = [
+        {
+            type: "text",
+            text: [
+                `Re-render job submitted with colormap "${colormap}".`,
+                `New job_id: ${newJobId}. Poll get_job_status(job_id="${newJobId}") until status is 'completed', then use get_results(job_id="${newJobId}") or get_result_image to retrieve the recolored plot(s). No retraining was performed.`,
+            ].join("\n"),
+        },
+    ];
     return { content };
 });
+// ---- download_results ----
+server.tool("download_results", `Save result figures (and optionally JSON) to a folder on disk. Use so the user can open, share, or version files locally without writing their own download script.
+
+folder: path to the directory (e.g. "." for current/workspace, "./results", or absolute path). In Cursor, the process cwd is typically the project root.
+figures: "all" (default) = all image files from the job; "images" = same; or an array of filenames e.g. ["combined.png", "umatrix.png"].
+include_json: if true, also save summary.json (and other JSON artifacts) into the same folder.`, {
+    job_id: z.string().describe("Job ID of a completed job"),
+    folder: z.string().describe("Directory path to save files (e.g. '.' or './results'). Relative paths are relative to process cwd (usually project root)."),
+    figures: z
+        .union([z.enum(["all", "images"]), z.array(z.string())])
+        .optional()
+        .default("all")
+        .describe("Which files to download: 'all' (default) or 'images' for all image files, or array of filenames e.g. ['combined.png', 'umatrix.png']"),
+    include_json: z.boolean().optional().default(false).describe("If true, also download summary.json and other JSON files"),
+}, async ({ job_id, folder, figures, include_json }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const summary = (data.summary ?? {});
+    const files = summary.files ?? [];
+    const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
+    const isJson = (f) => f.endsWith(".json");
+    let toDownload;
+    if (figures === "all" || figures === "images") {
+        toDownload = include_json ? files : files.filter(isImage);
+    }
+    else {
+        toDownload = figures;
+        if (include_json && !toDownload.includes("summary.json")) {
+            toDownload = [...toDownload, "summary.json"];
+        }
+    }
+    const resolvedDir = path.resolve(folder);
+    await fs.mkdir(resolvedDir, { recursive: true });
+    const saved = [];
+    for (const filename of toDownload) {
+        try {
+            const { data: buf } = await apiRawCall(`/v1/results/${job_id}/image/${filename}`);
+            const outPath = path.join(resolvedDir, filename);
+            await fs.writeFile(outPath, buf);
+            saved.push(filename);
+        }
+        catch {
+            // Skip missing or failed files
+        }
+    }
+    const text = saved.length > 0
+        ? `Saved ${saved.length} file(s) to ${resolvedDir}: ${saved.join(", ")}`
+        : `No files saved (job may have no matching files or download failed). Check job_id and that the job is completed.`;
+    return { content: [{ type: "text", text }] };
+});
 // ---- analyze ----
 server.tool("analyze", `Run a specific analysis on SOM results. Use after get_results to drill into aspects.
+Request specific plots: get_results(job_id, figures=[...]) for chosen figures (e.g. figures: ["umatrix"]) or analyze(job_id, analysis_type) for a single analysis view.
 
 Available analysis types and when to use them:
 
@@ -833,6 +1062,8 @@ Available analysis types and when to use them:
                       high-density regions? Do they correspond to known operating modes?"
   feature_gradient  — Spatial rate of change per feature. Ask: "Where does this
                       feature change most rapidly? Does it align with cluster boundaries?"
+  quality_report    — Comprehensive quality report: QE, TE, silhouette, trustworthiness,
+                      neighborhood preservation, topographic product, and recommendations.
 
 WORKFLOW RECOMMENDATION:
 1. Start with clusters → check quality metrics and recommendations
@@ -859,6 +1090,7 @@ INTERPRETATION TIPS:
         "transition_flow",
         "local_density",
         "feature_gradient",
+        "quality_report",
     ])
         .describe("Type of analysis to run"),
     params: z
@@ -1087,6 +1319,64 @@ INTERPRETATION TIPS:
         }
         await tryAttachImage(content, job_id, `umatrix.${ext}`);
     }
+    else if (analysis_type === "quality_report") {
+        const qrData = (await apiCall("GET", `/v1/results/${job_id}/quality-report`));
+        const std = qrData.standard_metrics ?? {};
+        const clust = qrData.cluster_metrics ?? {};
+        const topo = qrData.topology_metrics ?? {};
+        const train = qrData.training ?? {};
+        const qrGrid = qrData.grid ?? [0, 0];
+        const fmt = (v) => v !== null && v !== undefined ? v.toFixed(4) : "—";
+        const fmtPct = (v) => v !== null && v !== undefined ? `${(v * 100).toFixed(1)}%` : "—";
+        const recommendations = [];
+        const qe = std.quantization_error;
+        const te = std.topographic_error;
+        const ev = std.explained_variance;
+        const sil = clust.silhouette;
+        const trust = topo.trustworthiness;
+        if (qe !== null && qe !== undefined && qe > 2.0)
+            recommendations.push("QE is high → try more epochs or a larger grid");
+        if (te !== null && te !== undefined && te > 0.15)
+            recommendations.push("TE is high → topology is not well-preserved, try larger grid");
+        if (ev !== null && ev !== undefined && ev < 0.7)
+            recommendations.push("Explained variance < 70% → consider more training or feature selection");
+        if (sil !== null && sil !== undefined && sil < 0.1)
+            recommendations.push("Low silhouette → clusters overlap, try sigma_f=0.5 or more epochs");
+        if (trust !== null && trust !== undefined && trust < 0.85)
+            recommendations.push("Trustworthiness < 85% → local neighborhood structure is distorted");
+        if (recommendations.length === 0)
+            recommendations.push("All metrics look healthy — good map quality!");
+        const epochs = train.epochs;
+        const epochStr = epochs
+            ? epochs[1] === 0 ? `${epochs[0]} ordering only` : `${epochs[0]}+${epochs[1]}`
+            : "—";
+        const qrLines = [
+            `Quality Report — Job ${job_id}`,
+            `Grid: ${qrGrid[0]}×${qrGrid[1]} | Model: ${qrData.model ?? "SOM"} | Samples: ${qrData.n_samples ?? "?"}`,
+            `Epochs: ${epochStr} | Duration: ${train.duration_seconds ? `${train.duration_seconds}s` : "—"}`,
+            ``,
+            `Standard Metrics:`,
+            `  Quantization Error:  ${fmt(std.quantization_error)}   (lower is better)`,
+            `  Topographic Error:   ${fmt(std.topographic_error)}   (lower is better)`,
+            `  Distortion:          ${fmt(std.distortion)}`,
+            `  Kaski-Lagus Error:   ${fmt(std.kaski_lagus_error)}   (lower is better)`,
+            `  Explained Variance:  ${fmtPct(std.explained_variance)}`,
+            ``,
+            `Cluster Quality Metrics:`,
+            `  Silhouette Score:    ${fmt(clust.silhouette)}   (higher is better, -1 to +1)`,
+            `  Davies-Bouldin:      ${fmt(clust.davies_bouldin)}   (lower is better)`,
+            `  Calinski-Harabasz:   ${fmt(clust.calinski_harabasz)}   (higher is better)`,
+            ``,
+            `Topology Metrics:`,
+            `  Neighborhood Preservation: ${fmtPct(topo.neighborhood_preservation)}   (higher is better)`,
+            `  Trustworthiness:           ${fmtPct(topo.trustworthiness)}   (higher is better)`,
+            `  Topographic Product:       ${fmt(topo.topographic_product)}   (near 0 is ideal)`,
+            ``,
+            `Recommendations:`,
+            ...recommendations.map((r) => `  • ${r}`),
+        ];
+        content.push({ type: "text", text: qrLines.join("\n") });
+    }
     return { content };
 });
 // ---- compare_runs ----
@@ -1133,324 +1423,147 @@ After comparing, ask the user:
         content: [{ type: "text", text: lines.join("\n") }],
     };
 });
-// ---- cancel_job ----
-server.tool("cancel_job", `Cancel a pending or running job.
-
-TIMING: Cancellation is not instant — the worker checks between training phases.
-Expect up to 30s delay for the job to actually stop.
-
-Use when a training run is too slow, wrong parameters were submitted, or you
-want to free the worker for a different job. Partial results are discarded.
-After cancelling, submit a new job with corrected parameters.`, {
-    job_id: z.string().describe("Job ID to cancel"),
-}, async ({ job_id }) => {
-    const data = await apiCall("POST", `/v1/jobs/${job_id}/cancel`);
-    return textResult(data);
-});
-// ---- delete_job ----
-server.tool("delete_job", `Delete a job and all its S3 result files.
-
-Use when:
-- Cleaning up old or failed jobs to free storage
-- Removing test runs before going to production
-- The job is cancelled and you no longer need the record
-
-WARNING: This permanently deletes all result files (images, weights, node stats).
-The job ID will no longer be usable with get_results or any other tools.`, {
-    job_id: z.string().describe("Job ID to delete"),
-}, async ({ job_id }) => {
-    const data = await apiCall("DELETE", `/v1/jobs/${job_id}`);
-    return textResult(data);
-});
-// ---- preview_dataset ----
-server.tool("preview_dataset", `Preview a dataset before training — shows columns, statistics, sample rows, and detections.
-
-BEST FOR: Understanding data structure before training. ALWAYS call this before train_som
-on an unfamiliar dataset.
-NOT FOR: Large data exploration (returns only sample rows). Use derive_variable for computations.
-
-TIMING: Near-instant (reads only header + sample rows from S3).
-
-This tool detects:
-1. Column types (numeric vs string) and basic stats (min/max/mean/std)
-2. Cyclic feature candidates (columns named hour, weekday, angle, direction, etc.)
-3. Datetime columns with format auto-detection
-4. Skewed distributions (large max/min ratios suggest log transforms)
-
-AFTER previewing, ask the user:
-- "Which columns are relevant?" → columns parameter in train_som
-- "I see cyclic candidates: [list]. Encode cyclically?" → cyclic_features
-- "Column X ranges 0.01–50,000. Log-transform?" → transforms: {X: "log"}
-- "Datetime columns found. Extract temporal features?" → temporal_features (NEVER auto-apply)
-- "Are any features more important than others?" → feature_weights
-
-COMMON MISTAKES:
-- Skipping preview and training on all columns (including IDs, timestamps, irrelevant features)
-- Not checking for datetime columns that could provide valuable cyclic features
-- Ignoring skewed distributions that will dominate normalization
-
-TIP: Use the prepare_training prompt for a structured walkthrough of all decisions.`, {
-    dataset_id: z.string().describe("Dataset ID to preview"),
-    n_rows: z
-        .number()
-        .int()
-        .optional()
-        .default(5)
-        .describe("Number of sample rows to return (default 5)"),
-}, async ({ dataset_id, n_rows }) => {
-    const data = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=${n_rows ?? 5}`));
-    const cols = data.columns ?? [];
-    const stats = data.column_stats ?? [];
-    const hints = data.cyclic_hints ?? [];
-    const samples = data.sample_rows ?? [];
-    const dtCols = data.datetime_columns ?? [];
-    const temporalSugg = data.temporal_suggestions ?? [];
-    const fmt = (v) => v === null || v === undefined ? "—" : Number(v).toFixed(3);
-    const lines = [
-        `Dataset: ${data.name} (${data.dataset_id})`,
-        `${data.total_rows} rows × ${data.total_cols} columns`,
-        ``,
-        `Column Statistics:`,
-        `| Column | Min | Max | Mean | Std | Nulls | Numeric |`,
-        `|--------|-----|-----|------|-----|-------|---------|`,
-    ];
-    for (const s of stats) {
-        lines.push(`| ${s.column} | ${fmt(s.min)} | ${fmt(s.max)} | ${fmt(s.mean)} | ${fmt(s.std)} | ${s.null_count ?? 0} | ${s.is_numeric !== false ? "yes" : "no"} |`);
+// ---- manage_job ----
+server.tool("manage_job", `Cancel or delete a job.
+
+action=cancel: Cancel a pending or running job. Not instant — worker checks between phases (expect up to 30s). Use when run is too slow, wrong params, or to free the worker. Partial results discarded.
+action=delete: Permanently delete a job and all S3 result files. Use to free storage, remove test runs, or clean up after cancel. WARNING: Job ID will no longer work with get_results or other tools.`, {
+    job_id: z.string().describe("Job ID to cancel or delete"),
+    action: z
+        .enum(["cancel", "delete"])
+        .describe("cancel: stop the job; delete: remove job and all result files"),
+}, async ({ job_id, action }) => {
+    if (action === "cancel") {
+        const data = await apiCall("POST", `/v1/jobs/${job_id}/cancel`);
+        return textResult(data);
     }
-    if (hints.length > 0) {
-        lines.push(``, `Detected Cyclic Feature Hints:`);
-        for (const h of hints) {
-            lines.push(`  • ${h.column} — period=${h.period} (${h.reason})`);
-        }
-    }
-    if (dtCols.length > 0) {
-        lines.push(``, `Detected Datetime Columns:`);
-        for (const dc of dtCols) {
-            const formats = dc.detected_formats ?? [];
-            const fmtStrs = formats
-                .map((f) => `${f.format} — ${f.description} (${(f.match_rate * 100).toFixed(0)}% match)`)
-                .join("; ");
-            lines.push(`  • ${dc.column}: sample="${dc.sample}" → ${fmtStrs}`);
-            if (formats.length > 1) {
-                lines.push(`    ⚠ AMBIGUOUS: multiple formats match. Ask user to clarify.`);
-            }
-        }
-    }
-    if (temporalSugg.length > 0) {
-        lines.push(``, `Temporal Feature Suggestions (require user approval):`);
-        for (const ts of temporalSugg) {
-            lines.push(`  • Columns: ${ts.columns.join(" + ")} → format: "${ts.format}"`);
-            lines.push(`    Available components: ${ts.available_components.join(", ")}`);
-            lines.push(`    ${ts.note}`);
-        }
-        lines.push(``, `To use temporal features in train_som, add:`, `  temporal_features: [{columns: [...], format: "...", extract: [...], cyclic: true}]`);
-    }
-    if (samples.length > 0) {
-        lines.push(``, `Sample Rows (first ${samples.length}):`);
-        lines.push(`| ${cols.join(" | ")} |`);
-        lines.push(`| ${cols.map(() => "---").join(" | ")} |`);
-        for (const row of samples) {
-            lines.push(`| ${cols.map((c) => String(row[c] ?? "")).join(" | ")} |`);
-        }
-    }
-    return {
-        content: [{ type: "text", text: lines.join("\n") }],
-    };
-});
-// ---- delete_dataset ----
-server.tool("delete_dataset", "Delete a dataset and its stored data. Frees a dataset slot for new uploads.", {
-    dataset_id: z.string().describe("Dataset ID to delete"),
-}, async ({ dataset_id }) => {
-    const data = await apiCall("DELETE", `/v1/datasets/${dataset_id}`);
-    return textResult(data);
-});
-// ---- list_datasets ----
-server.tool("list_datasets", `List all datasets uploaded by the current organization.
-
-Use this to check what data is available before calling train_som,
-or to find dataset IDs for datasets that were uploaded previously.`, {}, async () => {
-    const data = await apiCall("GET", "/v1/datasets");
+    const data = await apiCall("DELETE", `/v1/jobs/${job_id}`);
     return textResult(data);
 });
-// ---- list_jobs ----
-server.tool("list_jobs", `List all SOM training jobs, optionally filtered by dataset.
-
-Shows status, params, and metrics for each job. Use this to:
-- Find job IDs for compare_runs
-- Check which jobs are completed vs pending
-- Review what hyperparameters were used in previous runs`, {
+// ---- list ----
+server.tool("list", `List datasets or jobs.
+
+type=datasets: List all datasets uploaded by the organization. Use to check what data is available before train_som or to find dataset IDs.
+type=jobs: List SOM training jobs (optionally filtered by dataset_id). Use to find job IDs for compare_runs, check completed vs pending, or review hyperparameters.`, {
+    type: z
+        .enum(["datasets", "jobs"])
+        .describe("What to list: datasets or jobs"),
     dataset_id: z
         .string()
         .optional()
-        .describe("Filter by dataset ID (omit to list all jobs)"),
-}, async ({ dataset_id }) => {
+        .describe("Filter jobs by dataset ID (only used when type=jobs)"),
+}, async ({ type, dataset_id }) => {
+    if (type === "datasets") {
+        const data = await apiCall("GET", "/v1/datasets");
+        return textResult(data);
+    }
     const path = dataset_id
         ? `/v1/jobs?dataset_id=${dataset_id}`
         : "/v1/jobs";
     const data = await apiCall("GET", path);
     return textResult(data);
 });
-// ---- get_training_log ----
-server.tool("get_training_log", `Retrieve the learning curve and training diagnostics for a completed job.
-
-Returns per-epoch quantization error arrays, ASCII sparklines, AND an inline
-learning curve plot (generated during training) showing QE vs epoch for both
-ordering and convergence phases.
-
-Use this to diagnose training quality:
-
-- **Healthy**: errors drop steadily, then plateau (converged)
-- **Still learning**: errors still dropping at end → try more epochs
-- **Diverged**: errors increase → learning rate too high, try lower values
-- **Flat from start**: poor initialization or tiny grid
+// ---- get_job_export ----
+server.tool("get_job_export", `Export structured data from a completed SOM training job.
 
-After showing the log, ask the user:
-- "The training shows [observation]. Would you like to adjust epochs or learning rate?"
-- If errors plateaued early: "Convergence was reached quickly. Consider a larger grid for more detail."
-- If errors were still falling: "Training was cut short. Add more epochs for a better map."
-
-Also shows training duration, which helps estimate time for future runs.
-
-BATCH SIZE EFFECT: Smaller batch sizes (32–64) produce more update steps per epoch,
-often yielding lower final QE and smoother convergence curves. If the learning curve
-plateaus early, try more epochs. If it's noisy, try a larger batch size for stability.`, {
+export=training_log: Learning curve and diagnostics (per-epoch QE, sparklines, inline plot). Use to diagnose convergence, plateau, or divergence.
+export=weights: Raw weight matrix with node_coords, normalized/denormalized values, normalization stats. Use for external analysis or custom visualizations. Can be large (e.g. 600KB+ for 30×30×12).
+export=nodes: Per-node statistics (hit count, feature mean/std). Use to profile clusters and characterize operating modes.`, {
     job_id: z.string().describe("Job ID of a completed training job"),
-}, async ({ job_id }) => {
-    const data = (await apiCall("GET", `/v1/results/${job_id}/training-log`));
-    const ordErrors = data.ordering_errors ?? [];
-    const convErrors = data.convergence_errors ?? [];
-    const duration = data.training_duration_seconds;
-    const epochs = data.epochs;
-    const sparkline = (arr) => {
-        if (arr.length === 0)
-            return "(no data)";
-        const blocks = "▁▂▃▄▅▆▇█";
-        const min = Math.min(...arr);
-        const max = Math.max(...arr);
-        const range = max - min || 1;
-        return arr
-            .map((v) => blocks[Math.min(7, Math.floor(((v - min) / range) * 7))])
-            .join("");
-    };
-    const lines = [
-        `Training Log — Job ${job_id}`,
-        `Grid: ${JSON.stringify(data.grid)} | Model: ${data.model ?? "SOM"}`,
-        `Epochs: ${epochs ? `[${epochs[0]} ordering, ${epochs[1]} convergence]` : "N/A"}`,
-        `Duration: ${duration !== null && duration !== undefined ? `${duration}s` : "N/A"}`,
-        `Features: ${data.n_features ?? "?"} | Samples: ${data.n_samples ?? "?"}`,
-        ``,
-        `Ordering Phase (${ordErrors.length} epochs):`,
-        `  Start QE: ${ordErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${ordErrors.at(-1)?.toFixed(4) ?? "—"}`,
-        `  Curve:    ${sparkline(ordErrors)}`,
-    ];
-    if (convErrors.length > 0) {
-        lines.push(``, `Convergence Phase (${convErrors.length} epochs):`, `  Start QE: ${convErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${convErrors.at(-1)?.toFixed(4) ?? "—"}`, `  Curve:    ${sparkline(convErrors)}`);
-    }
-    else if ((epochs?.[1] ?? 0) === 0) {
-        lines.push(``, `Convergence phase: skipped (epochs[1]=0)`);
-    }
-    const finalQe = data.quantization_error;
-    const finalEv = data.explained_variance;
-    if (finalQe !== null && finalQe !== undefined) {
-        lines.push(``, `Final QE: ${finalQe.toFixed(4)} | Explained Variance: ${(finalEv ?? 0).toFixed(4)}`);
-    }
-    const content = [
-        { type: "text", text: lines.join("\n") },
-    ];
-    // Inline the pre-generated learning curve plot (worker saves it during training).
-    // Try png first (default), then pdf/svg in case the job used a different format.
-    let attached = false;
-    for (const lcExt of ["png", "pdf", "svg"]) {
-        try {
-            const { data: lcBuf } = await apiRawCall(`/v1/results/${job_id}/image/learning_curve.${lcExt}`);
-            content.push({
-                type: "image",
-                data: lcBuf.toString("base64"),
-                mimeType: mimeForFilename(`learning_curve.${lcExt}`),
-                annotations: { audience: ["user"], priority: 0.8 },
-            });
-            attached = true;
-            break;
+    export: z
+        .enum(["training_log", "weights", "nodes"])
+        .describe("What to export: training_log, weights, or nodes"),
+}, async ({ job_id, export: exportType }) => {
+    if (exportType === "training_log") {
+        const data = (await apiCall("GET", `/v1/results/${job_id}/training-log`));
+        const ordErrors = data.ordering_errors ?? [];
+        const convErrors = data.convergence_errors ?? [];
+        const duration = data.training_duration_seconds;
+        const epochs = data.epochs;
+        const sparkline = (arr) => {
+            if (arr.length === 0)
+                return "(no data)";
+            const blocks = "▁▂▃▄▅▆▇█";
+            const min = Math.min(...arr);
+            const max = Math.max(...arr);
+            const range = max - min || 1;
+            return arr
+                .map((v) => blocks[Math.min(7, Math.floor(((v - min) / range) * 7))])
+                .join("");
+        };
+        const lines = [
+            `Training Log — Job ${job_id}`,
+            `Grid: ${JSON.stringify(data.grid)} | Model: ${data.model ?? "SOM"}`,
+            `Epochs: ${epochs ? `[${epochs[0]} ordering, ${epochs[1]} convergence]` : "N/A"}`,
+            `Duration: ${duration !== null && duration !== undefined ? `${duration}s` : "N/A"}`,
+            `Features: ${data.n_features ?? "?"} | Samples: ${data.n_samples ?? "?"}`,
+            ``,
+            `Ordering Phase (${ordErrors.length} epochs):`,
+            `  Start QE: ${ordErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${ordErrors.at(-1)?.toFixed(4) ?? "—"}`,
+            `  Curve:    ${sparkline(ordErrors)}`,
+        ];
+        if (convErrors.length > 0) {
+            lines.push(``, `Convergence Phase (${convErrors.length} epochs):`, `  Start QE: ${convErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${convErrors.at(-1)?.toFixed(4) ?? "—"}`, `  Curve:    ${sparkline(convErrors)}`);
         }
-        catch {
-            continue;
+        else if ((epochs?.[1] ?? 0) === 0) {
+            lines.push(``, `Convergence phase: skipped (epochs[1]=0)`);
         }
+        const finalQe = data.quantization_error;
+        const finalEv = data.explained_variance;
+        if (finalQe !== null && finalQe !== undefined) {
+            lines.push(``, `Final QE: ${finalQe.toFixed(4)} | Explained Variance: ${(finalEv ?? 0).toFixed(4)}`);
+        }
+        const content = [
+            { type: "text", text: lines.join("\n") },
+        ];
+        let attached = false;
+        for (const lcExt of ["png", "pdf", "svg"]) {
+            try {
+                const { data: lcBuf } = await apiRawCall(`/v1/results/${job_id}/image/learning_curve.${lcExt}`);
+                content.push({
+                    type: "image",
+                    data: lcBuf.toString("base64"),
+                    mimeType: mimeForFilename(`learning_curve.${lcExt}`),
+                    annotations: { audience: ["user"], priority: 0.8 },
+                });
+                attached = true;
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!attached) {
+            content.push({ type: "text", text: "(learning curve plot not available)" });
+        }
+        return { content };
     }
-    if (!attached) {
-        content.push({ type: "text", text: "(learning curve plot not available)" });
-    }
-    return { content };
-});
-// ---- get_weights ----
-server.tool("get_weights", `Export the raw SOM weight matrix for a completed job.
-
-BEST FOR: Exporting the trained model for external analysis, custom visualizations, or comparing weight structures.
-
-Returns a structured weight matrix with:
-- node_coords: [x,y] per node (SOM topology coordinates for spatial mapping)
-- Normalized and denormalized weight values per feature
-- Normalization statistics (mean/std used during training)
-
-Response includes node_coords (SOM topology coordinates) for spatial mapping.
-
-Use this to:
-- Export the trained model for external analysis
-- Visualize the weight space in custom tools
-- Compare weight structures between training runs
-- Build custom projections or classifications
-
-Output can be large for big grids (e.g. 600KB+ for 30×30×12). Consider filtering
-to specific features if you only need a subset.`, {
-    job_id: z.string().describe("Job ID of a completed training job"),
-}, async ({ job_id }) => {
-    const data = (await apiCall("GET", `/v1/results/${job_id}/weights`));
-    const features = data.features ?? [];
-    const nNodes = data.n_nodes ?? 0;
-    const grid = data.grid ?? [0, 0];
-    const lines = [
-        `SOM Weights — Job ${job_id}`,
-        `Grid: ${grid[0]}×${grid[1]} | Nodes: ${nNodes} | Features: ${features.length}`,
-        `node_coords: [x,y] per node for topology`,
-        `Features: ${features.join(", ")}`,
-        ``,
-        `Normalization Stats:`,
-    ];
-    const normStats = data.normalization_stats ?? {};
-    for (const [feat, s] of Object.entries(normStats)) {
-        lines.push(`  ${feat}: mean=${s.mean?.toFixed(4)}, std=${s.std?.toFixed(4)}`);
+    if (exportType === "weights") {
+        const data = (await apiCall("GET", `/v1/results/${job_id}/weights`));
+        const features = data.features ?? [];
+        const nNodes = data.n_nodes ?? 0;
+        const grid = data.grid ?? [0, 0];
+        const lines = [
+            `SOM Weights — Job ${job_id}`,
+            `Grid: ${grid[0]}×${grid[1]} | Nodes: ${nNodes} | Features: ${features.length}`,
+            `node_coords: [x,y] per node for topology`,
+            `Features: ${features.join(", ")}`,
+            ``,
+            `Normalization Stats:`,
+        ];
+        const normStats = data.normalization_stats ?? {};
+        for (const [feat, s] of Object.entries(normStats)) {
+            lines.push(`  ${feat}: mean=${s.mean?.toFixed(4)}, std=${s.std?.toFixed(4)}`);
+        }
+        lines.push(``, `Full weight matrix available in the response JSON (includes node_coords).`, `Use the denormalized_weights array for original-scale values.`);
+        return {
+            content: [
+                { type: "text", text: lines.join("\n") },
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
     }
-    lines.push(``, `Full weight matrix available in the response JSON (includes node_coords).`, `Use the denormalized_weights array for original-scale values.`);
-    return {
-        content: [
-            { type: "text", text: lines.join("\n") },
-            { type: "text", text: JSON.stringify(data, null, 2) },
-        ],
-    };
-});
-// ---- get_node_data ----
-server.tool("get_node_data", `Get per-node statistics for a completed SOM job.
-
-BEST FOR: Profiling clusters, finding dominant vs rare nodes, characterizing operating modes.
-
-Returns for each SOM node:
-- Hit count (how many data points map to this node)
-- Feature mean and std for all samples that map to this node
-
-This answers "what data lives in this cluster?" — enabling characterization
-of distinct operating modes, regimes, or behavioral groups.
-
-Use this to:
-- Profile each cluster by its feature distributions
-- Find dominant nodes (high hit count) vs rare nodes
-- Compare feature distributions between nodes
-- Identify the most "representative" state for each cluster
-
-After showing node data, ask the user:
-- "Do these cluster profiles match your domain knowledge?"
-- "Which nodes represent the most common operating states?"
-- "Are there any nodes with extreme feature values worth investigating?"`, {
-    job_id: z.string().describe("Job ID of a completed training job"),
-}, async ({ job_id }) => {
+    // exportType === "nodes"
     const data = (await apiCall("GET", `/v1/results/${job_id}/nodes`));
     const topNodes = [...data]
         .sort((a, b) => (b.hit_count ?? 0) - (a.hit_count ?? 0))
@@ -1531,7 +1644,7 @@ HINT: If values length mismatch, suggest derive_variable for formula-based varia
     colormap: z
         .string()
         .optional()
-        .describe("Override colormap for the projection plot (default: plasma)."),
+        .describe("Override colormap for the projection plot (default: plasma). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral."),
 }, async ({ job_id, variable_name, values, aggregation, output_format, output_dpi, colormap }) => {
     const dpiMap = { standard: 1, retina: 2, print: 4 };
     const body = {
@@ -1781,7 +1894,7 @@ COMMON MISTAKES:
     colormap: z
         .string()
         .optional()
-        .describe("Colormap for projection visualization (default: plasma)"),
+        .describe("Colormap for projection visualization (default: plasma). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral."),
 }, async ({ dataset_id, name, expression, project_onto_job, aggregation, options, output_format, output_dpi, colormap, }) => {
     const dpiMap = { standard: 1, retina: 2, print: 4 };
     if (project_onto_job) {
@@ -1866,7 +1979,7 @@ COMMON MISTAKES:
                             `Min: ${summary.min ?? "?"} | Max: ${summary.max ?? "?"} | Mean: ${summary.mean ?? "?"}`,
                             ``,
                             `The column is now available in the dataset. Include it in train_som`,
-                            `via the 'columns' parameter, or use preview_dataset to verify.`,
+                            `via the 'columns' parameter, or use datasets(action=preview) to verify.`,
                         ]
                             .filter((l) => l !== "")
                             .join("\n"),
@@ -1889,87 +2002,6 @@ COMMON MISTAKES:
         };
     }
 });
-// ---- quality_report ----
-server.tool("quality_report", `Generate a comprehensive quality report for a trained SOM.
-
-Returns all available metrics organized by category:
-- **Standard metrics**: Quantization Error (QE), Topographic Error (TE), Distortion
-- **Cluster metrics**: Silhouette, Davies-Bouldin, Calinski-Harabasz
-- **Topology metrics**: Neighborhood Preservation, Trustworthiness, Topographic Product
-- **Training info**: duration, epochs, learning parameters
-
-Metric interpretation guide:
-- QE < 0.5: excellent | 0.5–1.0: good | 1.0–2.0: fair | >2.0: needs improvement
-- TE < 0.05: excellent | 0.05–0.10: good | 0.10–0.20: fair | >0.20: poor topology
-- Trustworthiness: closer to 1.0 = better (local neighborhoods preserved)
-- Neighborhood Preservation: closer to 1.0 = better (global structure preserved)
-- Topographic Product: near 0 = well-sized grid | <0 = grid too small | >0 = grid too large
-
-After showing the report, ask the user:
-- "Which metrics are most important for your use case?"
-- "Do any metrics suggest the map needs retraining?"`, {
-    job_id: z.string().describe("Job ID of a completed training job"),
-}, async ({ job_id }) => {
-    const data = (await apiCall("GET", `/v1/results/${job_id}/quality-report`));
-    const std = data.standard_metrics ?? {};
-    const clust = data.cluster_metrics ?? {};
-    const topo = data.topology_metrics ?? {};
-    const train = data.training ?? {};
-    const grid = data.grid ?? [0, 0];
-    const fmt = (v) => v !== null && v !== undefined ? v.toFixed(4) : "—";
-    const fmtPct = (v) => v !== null && v !== undefined ? `${(v * 100).toFixed(1)}%` : "—";
-    const recommendations = [];
-    const qe = std.quantization_error;
-    const te = std.topographic_error;
-    const ev = std.explained_variance;
-    const sil = clust.silhouette;
-    const trust = topo.trustworthiness;
-    const nbp = topo.neighborhood_preservation;
-    if (qe !== null && qe !== undefined && qe > 2.0)
-        recommendations.push("QE is high → try more epochs or a larger grid");
-    if (te !== null && te !== undefined && te > 0.15)
-        recommendations.push("TE is high → topology is not well-preserved, try larger grid");
-    if (ev !== null && ev !== undefined && ev < 0.7)
-        recommendations.push("Explained variance < 70% → consider more training or feature selection");
-    if (sil !== null && sil !== undefined && sil < 0.1)
-        recommendations.push("Low silhouette → clusters overlap, try sigma_f=0.5 or more epochs");
-    if (trust !== null && trust !== undefined && trust < 0.85)
-        recommendations.push("Trustworthiness < 85% → local neighborhood structure is distorted");
-    if (recommendations.length === 0)
-        recommendations.push("All metrics look healthy — good map quality!");
-    const epochs = train.epochs;
-    const epochStr = epochs
-        ? epochs[1] === 0 ? `${epochs[0]} ordering only` : `${epochs[0]}+${epochs[1]}`
-        : "—";
-    const lines = [
-        `Quality Report — Job ${job_id}`,
-        `Grid: ${grid[0]}×${grid[1]} | Model: ${data.model ?? "SOM"} | Samples: ${data.n_samples ?? "?"}`,
-        `Epochs: ${epochStr} | Duration: ${train.duration_seconds ? `${train.duration_seconds}s` : "—"}`,
-        ``,
-        `Standard Metrics:`,
-        `  Quantization Error:  ${fmt(std.quantization_error)}   (lower is better)`,
-        `  Topographic Error:   ${fmt(std.topographic_error)}   (lower is better)`,
-        `  Distortion:          ${fmt(std.distortion)}`,
-        `  Kaski-Lagus Error:   ${fmt(std.kaski_lagus_error)}   (lower is better)`,
-        `  Explained Variance:  ${fmtPct(std.explained_variance)}`,
-        ``,
-        `Cluster Quality Metrics:`,
-        `  Silhouette Score:    ${fmt(clust.silhouette)}   (higher is better, -1 to +1)`,
-        `  Davies-Bouldin:      ${fmt(clust.davies_bouldin)}   (lower is better)`,
-        `  Calinski-Harabasz:   ${fmt(clust.calinski_harabasz)}   (higher is better)`,
-        ``,
-        `Topology Metrics:`,
-        `  Neighborhood Preservation: ${fmtPct(topo.neighborhood_preservation)}   (higher is better)`,
-        `  Trustworthiness:           ${fmtPct(topo.trustworthiness)}   (higher is better)`,
-        `  Topographic Product:       ${fmt(topo.topographic_product)}   (near 0 is ideal)`,
-        ``,
-        `Recommendations:`,
-        ...recommendations.map((r) => `  • ${r}`),
-    ];
-    return {
-        content: [{ type: "text", text: lines.join("\n") }],
-    };
-});
 // ---- system_info ----
 server.tool("system_info", `Get plan capabilities, backend info, live status, and training time estimates.
 
@@ -2052,7 +2084,7 @@ server.prompt("prepare_training", "Guided pre-training checklist. Use after uplo
                     `5. FEATURE WEIGHTS: Should any features be emphasized or de-emphasized?\n` +
                     `6. DERIVED VARIABLES: Any new columns to compute from existing ones? (e.g., ratios, differences)\n` +
                     `7. GRID & MODEL: What grid size and model type?\n\n` +
-                    `Start by calling preview_dataset to show me the columns and statistics.`,
+                    `Start by calling datasets(action=preview, dataset_id=...) to show me the columns and statistics.`,
             },
         },
     ],