@barivia/barsom-mcp 0.11.1 → 0.14.0

package/dist/tools/train.js

@@ -0,0 +1,262 @@
+import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
+import { apiCall, textResult } from "../shared.js";
+import { TRAINING_INPUT_SCHEMA, buildTrainMapParams, fetchTrainingPresets, } from "./training_core.js";
+export const TRAIN_DESCRIPTION = `Submit a self-organizing map training job. Returns a job_id; poll with jobs(action=status) and then results(action=get). All actions are async.
+
+| Action | Use when |
+|--------|----------|
+| map | Standard SOM on a fixed hex grid — complete-case numeric data (no NaNs in training columns). |
+| siom_map | Self-interacting map — same grid flow plus SIOM coverage control (gamma, siom_decay, penalty) to avoid dead nodes. |
+| impute | Sparse training data: trains a missing-tolerant map (accelerated missSOM) AND returns dense imputed.csv in one job. Plain numeric columns only. |
+| floop_siom | FLooP-SIOM — a growing node-budget manifold instead of a fixed grid; default topology=free (CHL). Requires a plan with all_algorithms (Premium/Enterprise). |
+| baseline_study | One-call heuristic baseline SOM (grid ~5·√n, MAD normalization) for a quick first map. |
+
+Parameter details (grid, epochs, batch, model, presets, normalize, categorical_features, backend, FLooP max_nodes/effort, SIOM geometry) live in the **training_guidance** tool / **prepare_training** prompt — call them instead of guessing. Backend strings are "cpu" | "gpu" | "gpu_graphs" (no colon); on CPU-only hosts pass backend=cpu.
+
+ASYNC: every action returns a job_id immediately. Poll jobs(action=status, job_id=...) every 10–15s (do NOT poll faster). Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min — do not assume failure before 3 minutes on CPU. When status is completed, call results(action=get, job_id=...).
+
+action=impute: use when many cells are missing across training columns; use inference(impute_column) instead when you already have a complete-case map and need to fill one held-out column. Defaults model=auto, cv_folds=5 → quality.csv with two labeled numbers per column (kfold_holdout_pool = honest held-out; resubstitution_optimistic = in-sample, optimistic). Artifacts: imputed.csv, imputation_mask.csv, optional imputation_uncertainty.csv. A completed impute job_id is a valid parent for inference(impute_column).
+action=floop_siom: max_nodes is a TOTAL node budget (not a grid width/area); if coverage collapses, reduce max_nodes before increasing effort.
+NOT FOR: lifecycle (status/list/compare/cancel/delete) → use jobs; scoring data → use inference.`;
+/**
+ * Core training dispatcher. Shared by the `train` tool and the deprecated
+ * `jobs(train_*)` wrappers. Every branch posts to the same /v1/jobs route.
+ */
+export async function runTrain(action, args) {
+    const dataset_id = args.dataset_id;
+    if (action === "baseline_study") {
+        if (!dataset_id)
+            throw new Error("train(baseline_study) requires dataset_id");
+        const dsInfo = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=1`));
+        const nSamples = dsInfo.total_rows || 1000;
+        const totalNodes = Math.round(5 * Math.sqrt(nSamples));
+        const side = Math.max(5, Math.round(Math.sqrt(totalNodes)));
+        const params = {
+            model: "SOM",
+            periodic: false,
+            normalize: "mad",
+            grid: [side, side],
+            epochs: [10, 20],
+            batch_size: 32,
+            quality_metrics: "standard",
+            output_format: "png",
+            output_dpi: 2,
+            colormap: "coolwarm",
+        };
+        const data = (await apiCall("POST", "/v1/jobs", { dataset_id, params }));
+        const jid = String(data.id ?? "");
+        return { content: [{ type: "text", text: `Baseline study submitted. Job ID: ${jid}\nGrid size: ${side}x${side}\nNormalization: MAD\n\nPoll with jobs(action=status, job_id="${jid}") until complete, then retrieve with results(action=get, job_id="${jid}"). Optional: training_monitor(job_id="${jid}") for a visual panel—not required.` }] };
+    }
+    if (action === "map" || action === "siom_map" || action === "impute") {
+        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, label, cv_folds, viz_mode, viz_top_components, emit_cell_uncertainty, } = args;
+        let PRESETS = {};
+        try {
+            PRESETS = await fetchTrainingPresets();
+        }
+        catch (e) {
+            if (e.httpStatus === 401 || e.httpStatus === 403)
+                throw e;
+            if (preset && grid_x === undefined && epochs === undefined) {
+                throw new Error("Could not fetch training config from server, and missing explicit grid/epochs.");
+            }
+        }
+        if (!dataset_id)
+            throw new Error(`train(${action}) requires dataset_id`);
+        const { params, paramSummary, effectiveGrid } = buildTrainMapParams({
+            preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features,
+            temporal_features, feature_weights, transforms, auto_log_transforms,
+            time_delay_embeddings, categorical_features,
+            normalize, sigma_f, learning_rate, batch_size, quality_metrics, backend,
+            output_format, output_dpi, colormap, row_range,
+        }, PRESETS);
+        if (action === "impute") {
+            params._job_type = "train_impute";
+            params.model = model ?? "auto";
+            params.cv_folds = cv_folds ?? 5;
+            if (viz_mode !== undefined)
+                params.viz_mode = viz_mode;
+            if (viz_top_components !== undefined)
+                params.viz_top_components = viz_top_components;
+            if (emit_cell_uncertainty !== undefined)
+                params.emit_cell_uncertainty = emit_cell_uncertainty;
+            // Plain numeric path only — strip unsupported keys if caller passed them
+            delete params.cyclic_features;
+            delete params.temporal_features;
+            delete params.categorical_features;
+            delete params.transforms;
+            delete params.auto_log_transforms;
+            delete params.time_delay_embeddings;
+        }
+        if (action === "siom_map") {
+            params._job_type = "train_siom";
+            if (gamma !== undefined)
+                params.gamma = gamma;
+            if (gamma_f !== undefined)
+                params.gamma_f = gamma_f;
+            if (siom_decay !== undefined)
+                params.siom_decay = siom_decay;
+            if (siom_penalty !== undefined)
+                params.siom_penalty = siom_penalty;
+            if (penalty_alpha !== undefined)
+                params.penalty_alpha = penalty_alpha;
+            if (reset_per_epoch !== undefined)
+                params.reset_per_epoch = reset_per_epoch;
+            if (siom_feature_geometry !== undefined)
+                params.siom_feature_geometry = siom_feature_geometry;
+            if (siom_qe_backend !== undefined)
+                params.siom_qe_backend = siom_qe_backend;
+            if (siom_qe_batch_size !== undefined)
+                params.siom_qe_batch_size = siom_qe_batch_size;
+        }
+        let totalRows = 0;
+        try {
+            const preview = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=1`));
+            totalRows = Number(preview?.total_rows ?? 0);
+        }
+        catch { /* ignore */ }
+        const submitBody = { dataset_id, params };
+        if (label && label.trim() !== "")
+            submitBody.label = label;
+        const data = (await apiCall("POST", "/v1/jobs", submitBody));
+        const newJobId = data.id;
+        const variantPrefix = action === "siom_map" ? "variant=siom"
+            : action === "impute" ? "variant=train_impute"
+                : "variant=som";
+        data.effective_params = `${variantPrefix}, ${paramSummary}`;
+        try {
+            const sys = (await apiCall("GET", "/v1/system/info"));
+            const pending = Number(sys.status?.pending_jobs ?? sys.pending_jobs ?? 0);
+            const totalEta = Number(sys.training_time_estimates_seconds?.total ??
+                (sys.gpu_available ? 45 : 120));
+            const waitMinutes = Math.round((pending * totalEta) / 60);
+            let msg = `Job submitted (${variantPrefix}, ${paramSummary}). `;
+            if (waitMinutes > 1)
+                msg += `You are #${pending + 1} in queue. Estimated wait: ~${waitMinutes} min. `;
+            msg += `Poll with jobs(action=status, job_id="${newJobId}"). When status is completed, use results(action=get, job_id="${newJobId}") to view the map${action === "impute" ? " and imputed.csv" : ""} and metrics.`;
+            msg += ` Optional: training_monitor(job_id="${newJobId}") for charts—not required.`;
+            if (effectiveGrid && totalRows > 0 && effectiveGrid[0] * effectiveGrid[1] > totalRows * 0.75) {
+                msg += ` Note: Grid may be large for ${totalRows} rows (consider grid=auto for fewer dead nodes).`;
+            }
+            data.message = msg;
+        }
+        catch {
+            let msg = `Job submitted (${variantPrefix}, ${paramSummary}). Poll with jobs(action=status, job_id="${newJobId}"). When status is completed, use results(action=get, job_id="${newJobId}") to view the map${action === "impute" ? " and imputed.csv" : ""} and metrics.`;
+            msg += ` Optional: training_monitor(job_id="${newJobId}") for charts—not required.`;
+            if (effectiveGrid && totalRows > 0 && effectiveGrid[0] * effectiveGrid[1] > totalRows * 0.75) {
+                msg += ` Note: Grid may be large for ${totalRows} rows (consider grid=auto for fewer dead nodes).`;
+            }
+            data.message = msg;
+        }
+        return textResult(data);
+    }
+    if (action === "floop_siom") {
+        const { columns, cyclic_features, temporal_features, feature_weights, transforms, auto_log_transforms, normalize, row_range, output_format, output_dpi, colormap, topology, max_nodes, effort, n_initial, n_passes, growth_interval, neighborhood_size, edge_max_age, max_degree, gamma, siom_decay, siom_penalty, penalty_alpha, error_threshold, error_decay, ring_close_threshold, sigma_0, sigma_f, eta_0, eta_f, elastic_lambda, elastic_mu, elastic_anchor, anchor_percentile, label, } = args;
+        if (!dataset_id)
+            throw new Error("train(floop_siom) requires dataset_id");
+        const params = {
+            _job_type: "train_floop_siom",
+            topology,
+            effort,
+            normalize,
+            output_format: output_format ?? "png",
+        };
+        if (max_nodes !== undefined)
+            params.max_nodes = max_nodes;
+        if (columns?.length)
+            params.columns = columns;
+        if (cyclic_features?.length)
+            params.cyclic_features = cyclic_features;
+        if (temporal_features?.length)
+            params.temporal_features = temporal_features;
+        if (feature_weights && Object.keys(feature_weights).length > 0)
+            params.feature_weights = feature_weights;
+        if (transforms && Object.keys(transforms).length > 0)
+            params.transforms = transforms;
+        if (auto_log_transforms)
+            params.auto_log_transforms = auto_log_transforms;
+        if (row_range && row_range.length >= 2 && row_range[0] <= row_range[1])
+            params.row_range = row_range;
+        const dpiMap = { standard: 1, retina: 2, print: 4 };
+        if (output_dpi && output_dpi !== "retina")
+            params.output_dpi = dpiMap[output_dpi] ?? 2;
+        if (colormap)
+            params.colormap = colormap;
+        if (n_initial !== undefined)
+            params.n_initial = n_initial;
+        if (n_passes !== undefined)
+            params.n_passes = n_passes;
+        if (growth_interval !== undefined)
+            params.growth_interval = growth_interval;
+        if (neighborhood_size !== undefined)
+            params.neighborhood_size = neighborhood_size;
+        if (edge_max_age !== undefined)
+            params.edge_max_age = edge_max_age;
+        if (max_degree !== undefined)
+            params.max_degree = max_degree;
+        if (gamma !== undefined)
+            params.gamma = gamma;
+        if (siom_decay !== undefined)
+            params.siom_decay = siom_decay;
+        if (siom_penalty !== undefined)
+            params.siom_penalty = siom_penalty;
+        if (penalty_alpha !== undefined)
+            params.penalty_alpha = penalty_alpha;
+        if (error_threshold !== undefined)
+            params.error_threshold = error_threshold;
+        if (error_decay !== undefined)
+            params.error_decay = error_decay;
+        if (ring_close_threshold !== undefined)
+            params.ring_close_threshold = ring_close_threshold;
+        if (sigma_0 !== undefined)
+            params.sigma_0 = sigma_0;
+        if (sigma_f !== undefined)
+            params.sigma_f = sigma_f;
+        if (eta_0 !== undefined)
+            params.eta_0 = eta_0;
+        if (eta_f !== undefined)
+            params.eta_f = eta_f;
+        if (elastic_lambda !== undefined)
+            params.elastic_lambda = elastic_lambda;
+        if (elastic_mu !== undefined)
+            params.elastic_mu = elastic_mu;
+        if (elastic_anchor !== undefined)
+            params.elastic_anchor = elastic_anchor;
+        if (anchor_percentile !== undefined)
+            params.anchor_percentile = anchor_percentile;
+        const submitBody = { dataset_id, params };
+        if (label && label.trim() !== "")
+            submitBody.label = label;
+        const data = (await apiCall("POST", "/v1/jobs", submitBody));
+        const newJobId = data.id;
+        const maxNodeSummary = max_nodes === undefined ? "max_nodes=auto(~2*sqrt(n_samples))" : `max_nodes=${max_nodes}`;
+        const paramSummary = [
+            "variant=floop",
+            `topology=${topology ?? "free"}`,
+            maxNodeSummary,
+            `effort=${effort ?? "standard"}`,
+            gamma !== undefined ? `gamma=${gamma}` : "",
+        ].filter(Boolean).join(", ");
+        data.effective_params = paramSummary;
+        data.message =
+            `Job submitted (${paramSummary}). Poll with jobs(action=status, job_id="${newJobId}"). ` +
+                `When status is completed, use results(action=get, job_id="${newJobId}") to view FLooP-SIOM figures and metrics. ` +
+                `Optional: training_monitor(job_id="${newJobId}") for charts—not required.`;
+        return textResult(data);
+    }
+    throw new Error("Invalid train action");
+}
+export function registerTrainTool(server) {
+    registerAuditedTool(server, "train", TRAIN_DESCRIPTION, {
+        action: z
+            .enum(["map", "siom_map", "impute", "floop_siom", "baseline_study"])
+            .describe("map: standard SOM; siom_map: self-interacting map; impute: missing-tolerant map + imputed.csv; floop_siom: growing manifold (Premium/Enterprise); baseline_study: one-call heuristic baseline SOM"),
+        dataset_id: z.string().optional().describe("Dataset ID to train on (required for all actions)."),
+        label: z
+            .string()
+            .max(120)
+            .optional()
+            .describe("Optional run label (≤120 chars); appears in jobs(list) and the jobs(compare) table; sanitized server-side. Useful for sweeps (e.g. label=\"sweep_periodic_true\")."),
+        ...TRAINING_INPUT_SCHEMA,
+    }, async (args) => runTrain(args.action, args));
+}

package/dist/tools/training_core.js

@@ -0,0 +1,185 @@
+/**
+ * Shared training surface for the barsom proxy: the Zod input schema for training
+ * parameters, the param-building helper, and preset fetch. Declared once here so
+ * the `train` tool, the deprecated `jobs(train_*)` wrappers, and `training_prep`
+ * all reuse the same definitions (no drift).
+ */
+import { z } from "zod";
+import { apiCall } from "../shared.js";
+export async function fetchTrainingPresets() {
+    const configData = (await apiCall("GET", "/v1/training/config"));
+    return configData?.presets || {};
+}
+/**
+ * Zod raw shape for all training parameters (core SOM + impute + SIOM + FLooP).
+ * Spread into the `train` tool input schema and the deprecated `jobs` wrapper
+ * schema. Does NOT include tool-level keys (action, dataset_id, label, job_id).
+ */
+export const TRAINING_INPUT_SCHEMA = {
+    preset: z.enum(["quick", "standard", "refined", "high_res"]).optional(),
+    grid_x: z.number().int().optional()
+        .describe("Grid width. Omit grid_x AND grid_y (and preset) to auto-size the map (~5·√√n per side); the result reports hit_stats.active_node_fraction and a grid_suggestion when too many nodes are dead."),
+    grid_y: z.number().int().optional().describe("Grid height. See grid_x for auto-sizing."),
+    epochs: z.preprocess((v) => {
+        if (v === undefined || v === null)
+            return v;
+        if (typeof v === "string") {
+            const n = parseInt(v, 10);
+            if (!Number.isNaN(n))
+                return n;
+            const m = v.match(/^\[\s*(\d+)\s*,\s*(\d+)\s*\]$/);
+            if (m)
+                return [parseInt(m[1], 10), parseInt(m[2], 10)];
+        }
+        return v;
+    }, z.union([z.number().int(), z.array(z.number().int()).length(2)]).optional()),
+    model: z.enum(["auto", "SOM", "SIOM", "RSOM", "SOM-SOFT", "RSOM-SOFT"]).optional(),
+    periodic: z.boolean().optional().default(true),
+    columns: z.array(z.string()).optional(),
+    cyclic_features: z.array(z.object({
+        feature: z.string(),
+        period: z.number(),
+    })).optional(),
+    temporal_features: z.array(z.object({
+        columns: z.array(z.string()),
+        format: z.string(),
+        extract: z.array(z.enum(["hour_of_day", "day_of_year", "month", "day_of_week", "minute_of_hour"])),
+        cyclic: z.boolean().default(true),
+        separator: z.string().optional(),
+    })).optional(),
+    feature_weights: z.record(z.number()).optional(),
+    transforms: z.record(z.enum(["log", "log1p", "log10", "sqrt", "square", "abs", "invert", "rank", "none"])).optional(),
+    auto_log_transforms: z.boolean().optional().default(false),
+    time_delay_embeddings: z.array(z.object({
+        feature: z.string(),
+        lags: z.array(z.number().int().min(1))
+    })).optional(),
+    categorical_features: z.array(z.object({
+        feature: z.string(),
+        categories: z.array(z.string()),
+        weight: z.number().positive()
+    })).optional(),
+    normalize: z.union([z.enum(["all", "auto", "mad", "sigmoidal"]), z.array(z.string())]).optional().default("auto"),
+    sigma_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    learning_rate: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.union([z.number(), z.object({
+            ordering: z.tuple([z.number(), z.number()]),
+            convergence: z.tuple([z.number(), z.number()]),
+        })]).optional()),
+    batch_size: z.number().int().optional(),
+    quality_metrics: z.union([z.enum(["fast", "standard", "full"]), z.array(z.string())]).optional(),
+    backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().default("auto"),
+    output_format: z.enum(["png", "pdf", "svg"]).optional().default("png"),
+    output_dpi: z.enum(["standard", "retina", "print"]).optional().default("retina"),
+    colormap: z.string().optional(),
+    row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional(),
+    cv_folds: z.number().int().min(0).max(20).optional()
+        .describe("impute only: per-column imputation quality → quality.csv with two labeled methods (kfold_holdout_pool = held-out; resubstitution_optimistic = in-sample). 0=off, default 5."),
+    viz_mode: z.enum(["full", "summary", "summary_plus_top"]).optional()
+        .describe("Visualization density; auto-capped when feature count > 40"),
+    viz_top_components: z.number().int().min(0).max(64).optional()
+        .describe("With viz_mode=summary_plus_top: upload top-N component maps by variance (default 8)"),
+    emit_cell_uncertainty: z.boolean().optional()
+        .describe("impute: write imputation_uncertainty.csv (pool_std per imputed cell)"),
+    gamma: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    gamma_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    siom_decay: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    siom_penalty: z.enum(["linear", "log", "exp"]).optional(),
+    penalty_alpha: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    reset_per_epoch: z.boolean().optional(),
+    siom_feature_geometry: z.enum(["l2", "mixed", "auto"]).optional().describe("siom_map: l2 (default) = legacy L2 on cos/sin columns; mixed = cyclic torus distance when cyclic pairs exist; auto = mixed only when cyclic encodings are present"),
+    siom_qe_backend: z.enum(["cpu", "cuda", "auto"]).optional().describe("siom_map: backend for metric-aligned siom_qe when using mixed geometry; auto uses GPU when available"),
+    siom_qe_batch_size: z.number().int().min(1).max(1_000_000).optional().describe("siom_map: batch size for GPU SIOM QE (default 256 on worker)"),
+    topology: z.enum(["free", "chain"]).optional().default("free"),
+    max_nodes: z.number().int().min(2).optional(),
+    effort: z.enum(["quick", "standard", "thorough"]).optional().default("standard"),
+    n_initial: z.number().int().min(2).optional(),
+    n_passes: z.number().int().min(1).optional(),
+    growth_interval: z.number().int().min(1).optional(),
+    neighborhood_size: z.number().int().min(1).optional(),
+    edge_max_age: z.number().int().min(1).optional(),
+    max_degree: z.number().int().min(0).optional(),
+    error_threshold: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    error_decay: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    ring_close_threshold: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    sigma_0: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    eta_0: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    eta_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    elastic_lambda: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    elastic_mu: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    elastic_anchor: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+    anchor_percentile: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
+};
+export function buildTrainMapParams(args, presets) {
+    const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, } = args;
+    const p = preset ? presets[preset] : undefined;
+    const params = {
+        model: model ?? "SOM",
+        periodic: periodic ?? true,
+        normalize: normalize ?? "auto",
+    };
+    if (grid_x !== undefined && grid_y !== undefined)
+        params.grid = [grid_x, grid_y];
+    else if (p)
+        params.grid = p.grid;
+    if (epochs !== undefined)
+        params.epochs = epochs;
+    else if (p)
+        params.epochs = p.epochs;
+    if (cyclic_features?.length)
+        params.cyclic_features = cyclic_features;
+    if (columns?.length)
+        params.columns = columns;
+    if (auto_log_transforms)
+        params.auto_log_transforms = auto_log_transforms;
+    if (time_delay_embeddings?.length)
+        params.time_delay_embeddings = time_delay_embeddings;
+    if (categorical_features?.length)
+        params.categorical_features = categorical_features;
+    if (transforms && Object.keys(transforms).length > 0)
+        params.transforms = transforms;
+    if (temporal_features?.length)
+        params.temporal_features = temporal_features;
+    if (feature_weights && Object.keys(feature_weights).length > 0)
+        params.feature_weights = feature_weights;
+    if (sigma_f !== undefined)
+        params.sigma_f = sigma_f;
+    if (learning_rate !== undefined)
+        params.learning_rate = learning_rate;
+    if (batch_size !== undefined)
+        params.batch_size = batch_size;
+    else if (p)
+        params.batch_size = p.batch_size;
+    if (quality_metrics !== undefined)
+        params.quality_metrics = quality_metrics;
+    if (backend !== undefined && backend !== "auto")
+        params.backend = backend;
+    else if (p?.backend)
+        params.backend = p.backend;
+    params.output_format = output_format ?? "png";
+    const dpiMap = { standard: 1, retina: 2, print: 4 };
+    if (output_dpi && output_dpi !== "retina")
+        params.output_dpi = dpiMap[output_dpi] ?? 2;
+    if (colormap)
+        params.colormap = colormap;
+    if (row_range && row_range.length >= 2 && row_range[0] <= row_range[1])
+        params.row_range = row_range;
+    if (siom_feature_geometry !== undefined)
+        params.siom_feature_geometry = siom_feature_geometry;
+    if (siom_qe_backend !== undefined)
+        params.siom_qe_backend = siom_qe_backend;
+    if (siom_qe_batch_size !== undefined)
+        params.siom_qe_batch_size = siom_qe_batch_size;
+    const effectiveGrid = params.grid;
+    const effectiveEpochs = params.epochs;
+    const effectiveBatch = params.batch_size;
+    const effectiveBackend = params.backend;
+    const paramSummary = [
+        effectiveGrid ? `grid=${effectiveGrid[0]}×${effectiveGrid[1]}` : "grid=auto",
+        effectiveEpochs ? `epochs=${Array.isArray(effectiveEpochs) ? effectiveEpochs.join("+") : effectiveEpochs}` : "epochs=auto",
+        effectiveBatch ? `batch=${effectiveBatch}` : "batch=auto",
+        `model=${params.model}`,
+        effectiveBackend ? `backend=${effectiveBackend}` : "",
+        preset ? `(from preset: ${preset})` : "",
+    ].filter(Boolean).join(", ");
+    return { params, paramSummary, effectiveGrid };
+}

package/dist/tools/training_prep.js

@@ -1,10 +1,36 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
-import { apiCall, fetchTrainingGuidanceFromApi, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
-import { buildTrainMapParams, fetchTrainingPresets, } from "./jobs.js";
+import { apiCall, fetchTrainingGuidanceFromApi, getClientSupportsMcpApps, getVizPort, pollUntilComplete, POLL_DERIVE_MAX_MS, structuredTextResult, } from "../shared.js";
+import { buildTrainMapParams, fetchTrainingPresets, } from "./training_core.js";
 import { attachTrainingReviewPayload, consumeTrainingReview, getTrainingReview, storeTrainingReview, } from "./training_review_store.js";
 export const TRAINING_PREP_URI = "ui://barsom/training-prep";
+/**
+ * Fetch column analysis the same way datasets(action=analyze) does: enqueue the
+ * async sampled analyze job, poll, then read the summary. Falls back to the legacy
+ * synchronous GET on older APIs (404). Analysis is advisory in prep, so a job that
+ * is still running / failed degrades to an empty analysis (preview + presets still
+ * render) rather than failing the whole prep call.
+ */
+async function fetchAnalyzeData(datasetId) {
+    try {
+        const submit = (await apiCall("POST", `/v1/datasets/${datasetId}/analyze`));
+        const jobId = (submit.id ?? submit.job_id);
+        if (!jobId)
+            return {};
+        const poll = await pollUntilComplete(jobId, POLL_DERIVE_MAX_MS);
+        if (poll.status !== "completed")
+            return {};
+        const results = (await apiCall("GET", `/v1/results/${jobId}`));
+        return (results.summary ?? results);
+    }
+    catch (err) {
+        if (err?.httpStatus === 404) {
+            return (await apiCall("GET", `/v1/datasets/${datasetId}/analyze`));
+        }
+        throw err;
+    }
+}
 function getNumericColumns(preview) {
     const stats = preview.column_stats ?? [];
     return stats
@@ -139,7 +165,7 @@ function buildGuidanceLines(guidanceText) {
 async function buildTrainingPrepPayload(datasetId, input) {
     const [preview, analyze, presets, guidanceText, preparePrompt] = await Promise.all([
         apiCall("GET", `/v1/datasets/${datasetId}/preview?n_rows=5`),
-        apiCall("GET", `/v1/datasets/${datasetId}/analyze`),
+        fetchAnalyzeData(datasetId),
         fetchTrainingPresets().catch(() => ({})),
         fetchTrainingGuidanceFromApi().catch(() => "No training guidance available."),
         fetchPreparePrompt(datasetId),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barsom-mcp",
-  "version": "0.11.1",
+  "version": "0.14.0",
   "description": "barSOM MCP proxy — connect any MCP client to the barSOM cloud API for Self-Organizing Map analytics",
   "keywords": [
     "mcp",