@barivia/barsom-mcp 0.22.4 → 0.23.2

package/dist/tools/train.js

@@ -4,6 +4,7 @@ import { apiCall } from "../shared.js";
 import { buildTrainSubmitExtras } from "../train_submit_message.js";
 import { TRAINING_MONITOR_URI, buildTrainingMonitorResult, } from "./training_monitor.js";
 import { TRAINING_INPUT_SCHEMA, buildTrainMapParams, buildFloopParams, fetchTrainingPresets, assertValidNormalizationArgs, } from "./training_core.js";
+import { SMALL_N_SOFT, buildSmallNGuardrailLines, suggestedAutoGridSide, } from "../training_scale_guidance.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 |
@@ -13,11 +14,11 @@ export const TRAIN_DESCRIPTION = `Submit a self-organizing map training job. Ret
 | impute | Sparse training data: trains a missing-tolerant map (accelerated missSOM; SIOM missSOM when model=auto on som_siom+ or model=SIOM) AND returns dense imputed.csv in one job. Plain numeric columns only. Optional SIOM knobs: gamma, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch. |
 | 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). |
 
-First quick map (no separate baseline action): use \`train(action=map, preset=quick)\` (or \`normalize=mad\` with a grid sized from the preview row count); see the \`baseline_explore\` preset in **training_guidance**.
+First quick map (no separate baseline action): use \`train(action=map, preset=quick)\` when n is large enough (hundreds+ rows); for n<1000 prefer omitting grid_x/grid_y for auto (~sqrt(5·√n)) or an explicit small grid — see **training_guidance** / analyze next_steps. On CPU, preset=quick 15×15 is typically very fast up to ~100k rows — do not subsample first.
 
 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=...).
+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: preset=quick 15×15 often tens of seconds even at ~30k–100k rows on CPU | 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. Supports transforms (log/sqrt/etc., not rank), temporal_features, cyclic_features, optional cyclic_pairs=[[cos,sin],...] (circular prototype refresh + atomic chord BMU; those columns get circular quality metrics only — never quote Euclidean R² on cos/sin), and normalization_methods (zscore/mad/sigmoidal/none — not sepd). Does not support auto_log_transforms, rank transforms, or normalize=sepd. Defaults model=auto (SIOM missSOM on som_siom+ plans, else plain missSOM), cv_folds=5 → quality.csv (linear: kfold_holdout_pool + resubstitution_optimistic; cyclic pairs: kfold_holdout_circular). Aggregate MAE/RMSE excludes cyclic columns. Do not treat k-fold alone as true missing-cell ground truth. Optional SIOM knobs: gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch. Artifacts: imputed.csv, imputation_mask.csv, optional imputation_uncertainty.csv (pool_std = neighbourhood dispersion). 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.
@@ -55,6 +56,10 @@ async function submitTrainJob(opts) {
     const submitBody = { dataset_id: opts.dataset_id, params: opts.params };
     if (opts.label && opts.label.trim() !== "")
         submitBody.label = opts.label;
+    if (opts.description !== undefined)
+        submitBody.description = opts.description;
+    if (opts.tags !== undefined)
+        submitBody.tags = opts.tags;
     const data = (await apiCall("POST", "/v1/jobs", submitBody));
     const newJobId = data.id;
     data.effective_params = `${opts.variantPrefix}, ${opts.paramSummary}`;
@@ -62,6 +67,11 @@ async function submitTrainJob(opts) {
     if (opts.gridLargeForRows) {
         data.grid_auto_warning = true;
     }
+    const guardrails = opts.guardrailLines ?? [];
+    if (guardrails.length > 0) {
+        data.training_guardrails = guardrails;
+        data.small_n_warning = opts.totalRows > 0 && opts.totalRows < SMALL_N_SOFT;
+    }
     const extras = buildTrainSubmitExtras({
         newJobId,
         totalRows: opts.totalRows,
@@ -85,8 +95,12 @@ async function submitTrainJob(opts) {
     catch {
         /* ignore queue enrichment */
     }
-    if (opts.gridLargeForRows) {
-        msg += ` Note: Grid may be large for ${opts.totalRows} rows (consider grid=auto for fewer dead nodes).`;
+    if (guardrails.length > 0) {
+        msg += ` ${guardrails.join(" ")}`;
+    }
+    else if (opts.gridLargeForRows) {
+        const autoSide = suggestedAutoGridSide(opts.totalRows);
+        msg += ` Note: Grid may be large for ${opts.totalRows} rows — prefer omitting grid_x/grid_y for auto (~${autoSide}×${autoSide}) to reduce dead nodes.`;
     }
     data.message = msg;
     data.suggested_next_step = extras.suggested_next_step;
@@ -104,7 +118,7 @@ async function submitTrainJob(opts) {
 export async function runTrain(action, args) {
     const dataset_id = args.dataset_id;
     if (action === "map" || action === "siom_map" || action === "impute") {
-        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, 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, viz_upload_cyclic_components, emit_cell_uncertainty, } = args;
+        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, 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, description, tags, cv_folds, viz_mode, viz_top_components, viz_upload_cyclic_components, emit_cell_uncertainty, } = args;
         let PRESETS = {};
         try {
             PRESETS = await fetchTrainingPresets();
@@ -191,6 +205,16 @@ export async function runTrain(action, args) {
             typeof transforms === "object" &&
             Object.keys(transforms).length > 0;
         const gridLargeForRows = effectiveGrid && totalRows > 0 && effectiveGrid[0] * effectiveGrid[1] > totalRows * 0.75;
+        const nFeatures = Array.isArray(columns) ? columns.length
+            : Array.isArray(params.columns) ? params.columns.length
+                : undefined;
+        const guardrailLines = buildSmallNGuardrailLines({
+            n: totalRows,
+            nFeatures,
+            preset: typeof preset === "string" ? preset : undefined,
+            gridX: effectiveGrid?.[0],
+            gridY: effectiveGrid?.[1],
+        });
         const resultsHint = action === "impute" ? "view the map and imputed.csv"
             : "view the map and metrics";
         const variantPrefix = action === "siom_map" ? "variant=siom"
@@ -200,6 +224,8 @@ export async function runTrain(action, args) {
             dataset_id,
             params,
             label,
+            description,
+            tags,
             totalRows,
             hasTransforms,
             variantPrefix,
@@ -207,13 +233,14 @@ export async function runTrain(action, args) {
             resultsHint,
             impute: action === "impute",
             gridLargeForRows: !!gridLargeForRows,
+            guardrailLines,
         });
     }
     if (action === "floop_siom") {
         if (!dataset_id)
             throw new Error("train(floop_siom) requires dataset_id");
         assertValidNormalizationArgs(args);
-        const { transforms, label } = args;
+        const { transforms, label, description, tags } = args;
         const { params, paramSummary } = buildFloopParams(args);
         let totalRows = 0;
         try {
@@ -226,6 +253,8 @@ export async function runTrain(action, args) {
             dataset_id,
             params,
             label,
+            description,
+            tags,
             totalRows,
             hasTransforms,
             variantPrefix: "variant=floop",
@@ -246,6 +275,14 @@ export function registerTrainTool(server) {
             .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\")."),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional free-text description for inventory/navigation (shown in jobs(list) and account(inventory))."),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Optional tags for inventory/navigation (e.g. [\"sweep\",\"baseline\"])."),
         ...TRAINING_INPUT_SCHEMA,
     }, async (args) => runTrain(args.action, args));
 }

package/dist/tools/training_core.js

@@ -46,7 +46,7 @@ export async function fetchTrainingConfig() {
 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."),
+        .describe("Grid width. Omit grid_x AND grid_y (and preset) to auto-size via sqrt(5·√n) per side (clamped 5–50; ~6×6 at n≈45). Pass grid_x/grid_y — not a bare `grid` field. Results report hit_stats.active_node_fraction and grid_suggestion when 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)
@@ -118,17 +118,17 @@ export const TRAINING_INPUT_SCHEMA = {
     emit_cell_uncertainty: z.boolean().optional()
         .describe("impute: write imputation_uncertainty.csv (pool_std = prototype-neighbourhood dispersion, not calibrated SD; pool_n = contributing nodes)"),
     gamma: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
-        .describe("siom_map / impute (SIOM or auto on som_siom+): self-interaction strength γ (default 0.5 on worker)"),
+        .describe("siom_map / impute (SIOM or auto on som_siom+): self-interaction strength γ (default 0.5). Prefer γ∈[0.5,1.5] on large n; γ>1.5 often diminishing returns."),
     gamma_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
-        .describe("siom_map / impute SIOM: final γ for exponential decay schedule (0 = constant γ)"),
+        .describe("siom_map / impute SIOM: final γ for exponential decay (0 = constant γ). Pattern: start strict, relax late (e.g. 1.5→0.2)."),
     siom_decay: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
-        .describe("siom_map / impute SIOM: occupation EMA decay λ (default 0.01; 0 = cumulative counting)"),
+        .describe("siom_map / impute SIOM: occupation EMA decay λ (default 0.01; 0 = cumulative). Avoid pairing high γ with aggressive decay (e.g. 0.05)."),
     siom_penalty: z.enum(["linear", "log", "exp"]).optional()
-        .describe("siom_map / impute SIOM: occupation penalty shape"),
+        .describe("siom_map / impute SIOM: occupation penalty shape (linear default; prefer exp over log — log often worsens TE)"),
     penalty_alpha: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
         .describe("siom_map / impute SIOM: scaling α inside log/exp penalty"),
     reset_per_epoch: z.boolean().optional()
-        .describe("siom_map / impute SIOM: reset occupation μ at each epoch"),
+        .describe("siom_map / impute SIOM: reset occupation μ each epoch (default false; avoid with high γ — can collapse EV)"),
     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)"),

package/dist/training_scale_guidance.js

@@ -0,0 +1,73 @@
+/**
+ * Scale / small-n guidance shared by datasets(preview|analyze) and train submit.
+ * Auto-grid formula matches API/worker: clamp(round(sqrt(5*sqrt(n))), 5, 50).
+ */
+export const SMALL_N_SOFT = 1000;
+export const SMALL_N_HARD = 100;
+/** Agents should not suggest sample_n below this unless the user asks. */
+export const SAMPLE_N_SUGGEST_THRESHOLD = 100_000;
+/** Worker/API auto grid side length. */
+export function suggestedAutoGridSide(n) {
+    if (!Number.isFinite(n) || n < 1)
+        return 5;
+    return Math.max(5, Math.min(50, Math.round(Math.sqrt(5 * Math.sqrt(n)))));
+}
+export function presetGridCells(preset) {
+    switch (preset) {
+        case "quick":
+            return 15 * 15;
+        case "standard":
+            return 25 * 25;
+        case "refined":
+            return 40 * 40;
+        case "high_res":
+            return 60 * 60;
+        default:
+            return null;
+    }
+}
+/**
+ * Build prominent small-n / oversize-grid warnings for agents.
+ * Empty when n is healthy and the chosen grid is not oversized.
+ */
+export function buildSmallNGuardrailLines(opts) {
+    const { n, nFeatures, preset, gridX, gridY } = opts;
+    if (!Number.isFinite(n) || n <= 0)
+        return [];
+    const lines = [];
+    const autoSide = suggestedAutoGridSide(n);
+    const cells = gridX !== undefined && gridY !== undefined
+        ? gridX * gridY
+        : presetGridCells(preset);
+    if (n < SMALL_N_HARD) {
+        lines.push(`JUMPBACK — small-n (${n} rows): maps are fragile below ~100 rows. Prefer grid_x/grid_y ≈ ${autoSide}×${autoSide} (omit both for auto ≈ sqrt(5·√n)), not preset=quick/standard (15×15/25×25 → mostly dead nodes). Drop redundant geo features (keep distance OR lat/lon, not all three when |r|>0.9). Check hit_stats.active_node_fraction / TE before narrating insights.`);
+    }
+    else if (n < SMALL_N_SOFT) {
+        lines.push(`Warning — small-n (${n} rows < 1000): oversized grids leave dead nodes. Auto grid ≈ ${autoSide}×${autoSide}; omit grid_x/grid_y for auto, or size so |features|×grid_cells is not ≫ n. preset=quick (15×15) is often too large below a few hundred rows — verify active_node_fraction after train.`);
+    }
+    if (cells !== null && cells > n * 0.75) {
+        lines.push(`Grid risk: ${cells} cells vs ${n} rows (cells ≫ n) → expect dead nodes / TE≈1. Use auto (~${autoSide}×${autoSide}) or a smaller explicit grid_x/grid_y.`);
+    }
+    if (nFeatures !== undefined &&
+        nFeatures > 0 &&
+        cells !== null &&
+        nFeatures * cells > n * 2) {
+        lines.push(`Capacity risk: ${nFeatures} features × ${cells} cells ≫ ${n} rows. Drop highly correlated columns (see analyze recommendations) and/or shrink the grid before train.`);
+    }
+    return lines;
+}
+/** CPU scale guidance: do not subsample by default below 100k. */
+export function buildCpuScaleGuidanceLines(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return [];
+    if (n <= SAMPLE_N_SUGGEST_THRESHOLD) {
+        return [
+            `Scale: on CPU, preset=quick (15×15) is typically very fast up to ~100k rows (tens of seconds). Do NOT call datasets(subset)/sample_n for n=${n.toLocaleString()} — train the full dataset_id unless the user asks to downsample. Only suggest sample_n when n>100k or the user requests it.`,
+        ];
+    }
+    return [
+        `Scale: n=${n.toLocaleString()} > 100k — full-table train is still supported; suggest sample_n only if the user wants a faster exploratory pass or ops runbook says so. Never auto-subset silently.`,
+    ];
+}
+/** Periodicity caveat for analyze next_steps (row-order dependent). */
+export const PERIODICITY_ROW_ORDER_NOTE = "Periodicity assumes meaningful row order (time/sequence). If the CSV is unordered or shuffled, ignore lag-based suggestions; only use cyclic_features when the column is genuinely cyclic (e.g. hour, month, angle).";

package/package.json

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