@barivia/barsom-mcp 0.20.4 → 0.22.1

package/dist/tools/guide_barsom.js

@@ -5,7 +5,7 @@ const OFFLINE_STUB = `## Offline / API unavailable
 
 Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
 
-**Core tools:** \`datasets\`, \`jobs\` (train_map, train_siom_map, train_floop_siom where entitled), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+**Core tools:** \`datasets\`, \`train\` (map, siom_map, impute, floop_siom where entitled), \`jobs\` (status/list/compare — lifecycle only), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {

package/dist/tools/inference.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, pollUntilComplete, tryAttachImage } from "../shared.js";
+import { apiCall, pollUntilComplete, tryAttachImage, POLL_INFERENCE_MAX_MS, POLL_PROJECT_MAX_MS, resolveOutputDpi, fmtDensityDiffNode } from "../shared.js";
 import { pollPrepareIfPresent } from "../inference_prepare.js";
 const PREDICT_PREVIEW_ROW_CAP = 10;
 /** One line per scored row when worker embedded `predictions_preview` (n_rows ≤ cap). Exported for tests. */
@@ -123,8 +123,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
         top_k: z.number().int().min(1).optional().default(10)
             .describe("action=transition_flow: number of top-flow nodes in the statistics summary (default 10)."),
     }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n, target_column, only_missing, impute_aggregation, cv_folds, target_column_kind, weighting, inputs, lag, min_transitions, top_k }) => {
-        const dpiMap = { standard: 1, retina: 2, print: 4 };
-        const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
+        const numericDpi = resolveOutputDpi(output_dpi);
         if (action === "batch_predict")
             return runBatchPredict({ job_id, inputs });
         if (action === "transition_flow") {
@@ -136,10 +135,10 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             if (colormap !== undefined)
                 body.colormap = colormap;
             if (output_dpi && output_dpi !== "retina")
-                body.output_dpi = dpiMap[output_dpi] ?? 2;
+                body.output_dpi = resolveOutputDpi(output_dpi);
             const data = (await apiCall("POST", `/v1/results/${job_id}/transition-flow`, body));
             const flowJobId = data.id;
-            const poll = await pollUntilComplete(flowJobId, 120_000);
+            const poll = await pollUntilComplete(flowJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const res = (await apiCall("GET", `/v1/results/${flowJobId}`));
                 const summary = (res.summary ?? {});
@@ -195,7 +194,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             const predictJobId = data.id;
             const prepareId = await pollPrepareIfPresent(data, "inference(predict)");
             // annotated runs over the full dataset; allow up to 120s like compact
-            const poll = await pollUntilComplete(predictJobId, 120_000);
+            const poll = await pollUntilComplete(predictJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${predictJobId}`));
                 const summary = (results.summary ?? {});
@@ -254,7 +253,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 body.weighting = weighting;
             const data = (await apiCall("POST", `/v1/results/${job_id}/impute_column`, body));
             const imputeJobId = data.id;
-            const poll = await pollUntilComplete(imputeJobId, 120_000);
+            const poll = await pollUntilComplete(imputeJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${imputeJobId}`));
                 const summary = (results.summary ?? {});
@@ -281,19 +280,18 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 body.colormap = colormap;
             const data = (await apiCall("POST", `/v1/results/${job_id}/compare_datasets`, body));
             const compareJobId = data.id;
-            const poll = await pollUntilComplete(compareJobId, 120_000);
+            const poll = await pollUntilComplete(compareJobId, POLL_INFERENCE_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${compareJobId}`));
                 const summary = (results.summary ?? {});
                 const gained = summary.top_gained_nodes ?? [];
                 const lost = summary.top_lost_nodes ?? [];
-                const fmtNode = (n) => `  node ${n.node_index ?? "?"} [${(n.coords ?? [0, 0]).map(v => Number(v).toFixed(1)).join(",")}] Δ=${Number(n.density_diff ?? 0).toFixed(4)}`;
                 const n = top_n ?? 10;
                 const content = [{ type: "text", text: [
                             `Dataset comparison — job: ${compareJobId}`,
                             `Dataset A rows: ${summary.n_rows_a ?? "?"} | Dataset B rows: ${summary.n_rows_b ?? "?"}`,
-                            `Top ${Math.min(n, gained.length)} gained (B > A):`, ...gained.slice(0, n).map(fmtNode),
-                            `Top ${Math.min(n, lost.length)} lost (A > B):`, ...lost.slice(0, n).map(fmtNode),
+                            `Top ${Math.min(n, gained.length)} gained (B > A):`, ...gained.slice(0, n).map(fmtDensityDiffNode),
+                            `Top ${Math.min(n, lost.length)} lost (A > B):`, ...lost.slice(0, n).map(fmtDensityDiffNode),
                         ].join("\n") }];
                 content.push({ type: "text", text: "Density difference — Positive (red) = Dataset B gained density; Negative (blue) = Dataset A had more density." });
                 await tryAttachImage(content, compareJobId, `density_diff.${summary.output_format ?? output_format ?? "png"}`);
@@ -314,7 +312,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             const data = (await apiCall("POST", `/v1/results/${job_id}/project_columns`, body));
             const projJobId = data.id;
             const prepareId = await pollPrepareIfPresent(data, "inference(project_columns)");
-            const poll = await pollUntilComplete(projJobId, 90_000);
+            const poll = await pollUntilComplete(projJobId, POLL_PROJECT_MAX_MS);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${projJobId}`));
                 const summary = (results.summary ?? {});

package/dist/tools/results.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, getResultsImagesToFetch, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, attachResultsImages, resolveOutputDpi, POLL_RECOLOR_MAX_MS, fmtDensityDiffNode, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, structuredTextResult, } from "../shared.js";
 export function registerResultsTool(server) {
     registerAuditedTool(server, "results", `Retrieve, recolor, download, or export figures and metrics for a completed map job. Presentation and artifact access only — operations on the frozen map (predict, compare, project, impute_column, transition_flow) live in **inference**.
 
@@ -85,7 +85,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             .optional()
             .describe("action=export: training_log=learning curve; weights=weight matrix; nodes=per-node stats; clusters=regime boundaries; transition_matrix=Markov transition matrix"),
     }, async ({ action, job_id, figures, include_individual, include_json, folder, colormap, output_format, output_dpi, recolor_figures, export_type: exportType }) => {
-        const dpiMap = { standard: 1, retina: 2, print: 4 };
+        const figuresArg = figures;
         if (action === "get") {
             resetInlineAttachBudget();
             const data = (await apiCall("GET", `/v1/results/${job_id}`));
@@ -119,13 +119,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         ``, `Arrows show net directional drift. Long/bright = frequent transitions. Short = stable states.`,
                         `Background = U-matrix. Use results(action=transition_flow, lag=N) with larger N for longer-term structure.`,
                     ].join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "project_variable") {
                 const varName = summary.variable_name ?? "variable";
@@ -140,13 +134,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         `  Mean: ${stats.mean !== undefined ? Number(stats.mean).toFixed(3) : "N/A"}`,
                         `  Nodes with data: ${stats.n_nodes_with_data ?? "N/A"}`,
                     ].join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "project_columns") {
                 const cols = summary.columns ?? [];
@@ -158,18 +146,12 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...Object.entries(colStats).map(([col, s]) => `  ${col}: nodes=${s.n_nodes_with_data ?? "?"} | min=${s.min !== undefined ? Number(s.min).toFixed(3) : "—"} | max=${s.max !== undefined ? Number(s.max).toFixed(3) : "—"}`),
                 ];
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "compare_datasets") {
                 const gained = summary.top_gained_nodes ?? [];
                 const lost = summary.top_lost_nodes ?? [];
-                const fmtNode = (n) => `  node ${n.node_index ?? "?"} [${(n.coords ?? [0, 0]).map((v) => Number(v).toFixed(1)).join(",")}] Δ=${Number(n.density_diff ?? 0).toFixed(4)}`;
+                const fmtNode = fmtDensityDiffNode;
                 const lines = [
                     `Dataset Comparison — ${resultsHeader}`,
                     `Parent map job: ${summary.parent_job_id ?? "N/A"} | Dataset A: ${summary.n_rows_a ?? "?"} rows | Dataset B: ${summary.n_rows_b ?? "?"} rows`,
@@ -179,13 +161,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...lost.slice(0, 5).map(fmtNode),
                 ];
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "enrich_dataset") {
                 // Older exports: summary.job_type from stored results (read-only display).
@@ -256,23 +232,22 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                         : []),
                     cv ? [
                         "",
-                        `Held-out imputation accuracy (cv_folds=${cv.cv_folds ?? "?"}, method=${cv.cv_method ?? "held_out_prototype_on_trained_map"}):`,
+                        `Held-out imputation accuracy (cv_folds=${cv.cv_folds ?? "?"}, method=${cv.cv_method ?? "kfold_holdout_pool"}):`,
                         cv.columns_sampled ? `  (sampled ${cv.columns_evaluated ?? "?"} columns for speed)` : "",
-                        cv.aggregate ? `  Aggregate MAE: ${fmt(cv.aggregate.mae)} | RMSE: ${fmt(cv.aggregate.rmse)}` : "",
-                        "  See quality.csv (header column: feature).",
+                        cv.aggregate ? `  Aggregate MAE/RMSE (non-cyclic columns): ${fmt(cv.aggregate.mae)} | ${fmt(cv.aggregate.rmse)}` : "",
+                        cv.aggregate?.excluded_cyclic_columns
+                            ? `  Excluded cyclic columns from aggregate: ${cv.aggregate.excluded_cyclic_columns}`
+                            : "",
+                        "  See quality.csv — linear: mae/rmse/r2; cyclic_pairs: circ_mae_rad + mean_resultant_length only.",
+                        "  k-fold is relative column difficulty, not external missing-cell ground truth.",
                     ].filter(Boolean).join("\n") : "\nHeld-out accuracy: skipped (cv_folds=0). Set cv_folds=5 to validate imputation.",
                     "",
                     `Artifacts: ${(summary.files ?? []).filter((f) => f !== "summary.json").join(", ")}`,
                     "Next: results(action=download) for imputed.csv / quality.csv; inference(impute_column) with this job_id as parent for held-out columns.",
+                    "Optional imputation_uncertainty.csv pool_std is prototype-neighbourhood dispersion (not calibrated predictive SD).",
                 ].filter((l) => l !== "");
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else if (jobType === "reduce_spectral") {
                 const method = String(summary.method ?? "?");
@@ -349,13 +324,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     files.length > 0 ? `Artifacts: ${files.join(", ")}` : "",
                 ].filter((l) => l !== "");
                 content.push({ type: "text", text: lines.join("\n") });
-                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             else {
                 const grid = summary.grid ?? [0, 0];
@@ -438,14 +407,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...((jobType === "train_som" || jobType === "train_siom" || jobType === "train_impute") ? ["", `Next: results_explorer(job_id="${job_id}") to browse all figures interactively; results(action=export, export_type=training_log) for learning curve; results(action=download) to save figures${jobType === "train_impute" ? " (includes imputed.csv)" : ""}; jobs(action=compare, job_ids=[...]) to compare runs; inference(action=predict) to score new data; inference(action=project_columns) to project other variables onto the map.`] : []),
                 ].filter((l) => l !== "").join("\n");
                 content.push({ type: "text", text: textSummary });
-                const imagesToFetch = getResultsImagesToFetch(jobType, summary, figures, include_individual);
-                for (const name of imagesToFetch) {
-                    const cap = getCaptionForImage(name);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, name);
-                    inlinedImages.add(name);
-                }
+                await attachResultsImages(content, job_id, jobType, summary, figuresArg, include_individual, inlinedImages);
             }
             const files = summary.files ?? [];
             const jobType2 = summary.job_type ?? "train_som";
@@ -476,7 +438,16 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     : "";
                 content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots, figures=all for everything, or figures="none" for metrics-only.` });
             }
-            return { content };
+            const structuredPayload = {
+                job_id,
+                job_type: jobType2,
+                label: jobLabel,
+                summary,
+                files,
+                figures_inlined: [...inlinedImages],
+            };
+            const summaryText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n\n");
+            return structuredTextResult(structuredPayload, summaryText, content);
         }
         if (action === "export") {
             if (!exportType)
@@ -633,16 +604,36 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             }
             await fs.mkdir(resolvedDir, { recursive: true });
             const saved = [];
+            const missing = [];
             for (const filename of toDownload) {
                 try {
                     const { data: buf } = await apiRawCall(`/v1/results/${job_id}/image/${filename}`);
                     await fs.writeFile(path.join(resolvedDir, filename), buf);
                     saved.push(filename);
                 }
-                catch { /* skip missing files */ }
+                catch {
+                    missing.push(filename);
+                }
             }
             const savedDir = path.join(folder, jobSubfolder);
-            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
+            if (saved.length === 0) {
+                const missNote = missing.length > 0 ? ` Missing/failed: ${missing.join(", ")}.` : "";
+                return {
+                    content: [{
+                            type: "text",
+                            text: `No files saved.${missNote} Check job_id and that the job is completed.`,
+                        }],
+                };
+            }
+            const missNote = missing.length > 0
+                ? ` Missing/failed (${missing.length}): ${missing.join(", ")}.`
+                : "";
+            return {
+                content: [{
+                        type: "text",
+                        text: `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}.${missNote}`,
+                    }],
+            };
         }
         if (action === "recolor") {
             if (!colormap)
@@ -651,11 +642,11 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 colormap,
                 figures: recolor_figures ?? ["combined"],
                 output_format: output_format ?? "png",
-                output_dpi: dpiMap[output_dpi ?? "retina"] ?? 2,
+                output_dpi: resolveOutputDpi(output_dpi),
             };
             const data = (await apiCall("POST", `/v1/results/${job_id}/render`, body));
             const newJobId = data.id;
-            const poll = await pollUntilComplete(newJobId, 60_000);
+            const poll = await pollUntilComplete(newJobId, POLL_RECOLOR_MAX_MS);
             if (poll.status === "completed") {
                 const content = [{ type: "text", text: `Re-rendered with colormap "${colormap}". New job_id: ${newJobId}.` }];
                 for (const fig of recolor_figures ?? ["combined"]) {

package/dist/tools/train.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { buildTrainSubmitExtras } from "../train_submit_message.js";
-import { TRAINING_INPUT_SCHEMA, buildTrainMapParams, buildFloopParams, fetchTrainingPresets, } from "./training_core.js";
+import { TRAINING_INPUT_SCHEMA, buildTrainMapParams, buildFloopParams, fetchTrainingPresets, assertValidNormalizationArgs, } 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 |
@@ -18,12 +18,13 @@ Parameter details (grid, epochs, batch, model, presets, normalize, categorical_f
 
 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. Supports transforms (log/sqrt/etc., not rank), temporal_features, cyclic_features, 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 with two labeled numbers per column (kfold_holdout_pool = honest held-out; resubstitution_optimistic = in-sample, optimistic). Optional SIOM coverage knobs: gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch (same names as siom_map). Artifacts: imputed.csv, imputation_mask.csv, optional imputation_uncertainty.csv, summary.siom when SIOM path runs. A completed impute job_id is a valid parent for inference(impute_column).
+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.
 NOT FOR: lifecycle (status/list/compare/cancel/delete) → use jobs; scoring data → use inference.
 
 Rank transform (map/siom/floop only): training-only — batch predict, project_columns, and impute_column cannot score rank-transformed columns.`;
 function assertImputeTrainingArgs(args) {
+    assertValidNormalizationArgs(args);
     const normalize = args.normalize;
     if (normalize === "sepd") {
         throw new Error("train(impute) does not support normalize=sepd");
@@ -48,6 +49,48 @@ function assertImputeTrainingArgs(args) {
         throw new Error("train(impute) does not support auto_log_transforms yet.");
     }
 }
+/** Shared POST /v1/jobs + train submit message extras (map/siom/impute and floop). */
+async function submitTrainJob(opts) {
+    const submitBody = { dataset_id: opts.dataset_id, params: opts.params };
+    if (opts.label && opts.label.trim() !== "")
+        submitBody.label = opts.label;
+    const data = (await apiCall("POST", "/v1/jobs", submitBody));
+    const newJobId = data.id;
+    data.effective_params = `${opts.variantPrefix}, ${opts.paramSummary}`;
+    data.results_hint = opts.resultsHint;
+    if (opts.gridLargeForRows) {
+        data.grid_auto_warning = true;
+    }
+    const extras = buildTrainSubmitExtras({
+        newJobId,
+        totalRows: opts.totalRows,
+        hasTransforms: opts.hasTransforms,
+        prepareJobId: data.prepare_job_id ?? null,
+        variantPrefix: opts.variantPrefix,
+        paramSummary: opts.paramSummary,
+        impute: opts.impute,
+        resultsHint: opts.resultsHint,
+    });
+    let msg = extras.message;
+    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);
+        if (waitMinutes > 1)
+            msg = `You are #${pending + 1} in queue. Estimated wait: ~${waitMinutes} min. ${msg}`;
+    }
+    catch {
+        /* ignore queue enrichment */
+    }
+    if (opts.gridLargeForRows) {
+        msg += ` Note: Grid may be large for ${opts.totalRows} rows (consider grid=auto for fewer dead nodes).`;
+    }
+    data.message = msg;
+    data.suggested_next_step = extras.suggested_next_step;
+    return textResult(data);
+}
 /**
  * Core training dispatcher. Shared by the `train` tool and the deprecated
  * `jobs(train_*)` wrappers. Every branch posts to the same /v1/jobs route.
@@ -55,7 +98,7 @@ function assertImputeTrainingArgs(args) {
 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, 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;
+        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, emit_cell_uncertainty, } = args;
         let PRESETS = {};
         try {
             PRESETS = await fetchTrainingPresets();
@@ -72,11 +115,14 @@ export async function runTrain(action, args) {
         if (action === "impute") {
             assertImputeTrainingArgs(args);
         }
+        else {
+            assertValidNormalizationArgs(args);
+        }
         const { params, paramSummary, effectiveGrid } = buildTrainMapParams({
-            preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features,
+            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, sigma_f, learning_rate, batch_size, quality_metrics, backend,
+            normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend,
             output_format, output_dpi, colormap, row_range,
         }, PRESETS);
         if (action === "impute") {
@@ -134,62 +180,34 @@ export async function runTrain(action, args) {
             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}`;
         const hasTransforms = transforms != null &&
             typeof transforms === "object" &&
             Object.keys(transforms).length > 0;
-        const extras = buildTrainSubmitExtras({
-            newJobId,
+        const gridLargeForRows = effectiveGrid && totalRows > 0 && effectiveGrid[0] * effectiveGrid[1] > totalRows * 0.75;
+        const resultsHint = action === "impute" ? "view the map and imputed.csv"
+            : "view the map and metrics";
+        const variantPrefix = action === "siom_map" ? "variant=siom"
+            : action === "impute" ? "variant=train_impute"
+                : "variant=som";
+        return submitTrainJob({
+            dataset_id,
+            params,
+            label,
             totalRows,
             hasTransforms,
-            prepareJobId: data.prepare_job_id ?? null,
             variantPrefix,
             paramSummary,
+            resultsHint,
             impute: action === "impute",
+            gridLargeForRows: !!gridLargeForRows,
         });
-        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 = extras.message;
-            if (waitMinutes > 1)
-                msg = `You are #${pending + 1} in queue. Estimated wait: ~${waitMinutes} min. ${msg}`;
-            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;
-            data.suggested_next_step = extras.suggested_next_step;
-        }
-        catch {
-            let msg = extras.message;
-            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;
-            data.suggested_next_step = extras.suggested_next_step;
-        }
-        return textResult(data);
     }
     if (action === "floop_siom") {
         if (!dataset_id)
             throw new Error("train(floop_siom) requires dataset_id");
+        assertValidNormalizationArgs(args);
         const { transforms, label } = args;
         const { params, paramSummary } = buildFloopParams(args);
-        const submitBody = { dataset_id, params };
-        if (label && label.trim() !== "")
-            submitBody.label = label;
-        const data = (await apiCall("POST", "/v1/jobs", submitBody));
-        const newJobId = data.id;
         let totalRows = 0;
         try {
             const preview = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=1`));
@@ -197,19 +215,16 @@ export async function runTrain(action, args) {
         }
         catch { /* ignore */ }
         const hasTransforms = transforms != null && typeof transforms === "object" && Object.keys(transforms).length > 0;
-        data.effective_params = paramSummary;
-        const extras = buildTrainSubmitExtras({
-            newJobId,
+        return submitTrainJob({
+            dataset_id,
+            params,
+            label,
             totalRows,
             hasTransforms,
-            prepareJobId: data.prepare_job_id ?? null,
             variantPrefix: "variant=floop",
             paramSummary,
             resultsHint: "view FLooP-SIOM figures and metrics",
         });
-        data.message = extras.message;
-        data.suggested_next_step = extras.suggested_next_step;
-        return textResult(data);
     }
     throw new Error("Invalid train action");
 }

package/dist/tools/training_core.js

@@ -4,11 +4,30 @@
  * the `train` tool reuses a single set of definitions (no drift).
  */
 import { z } from "zod";
-import { apiCall } from "../shared.js";
+import { apiCall, resolveOutputDpi } from "../shared.js";
 export async function fetchTrainingPresets() {
     const configData = (await apiCall("GET", "/v1/training/config"));
     return configData?.presets || {};
 }
+const ALLOWED_NORM_METHODS = new Set(["zscore", "mad", "sigmoidal", "sepd", "none"]);
+const ALLOWED_NORMALIZE_GLOBALS = new Set(["all", "auto", "mad", "sigmoidal", "sepd", "zscore"]);
+/**
+ * Fail closed on unknown normalize / normalization_methods values before POST /v1/jobs.
+ */
+export function assertValidNormalizationArgs(args) {
+    const normalize = args.normalize;
+    if (typeof normalize === "string" && normalize.length > 0 && !ALLOWED_NORMALIZE_GLOBALS.has(normalize)) {
+        throw new Error(`Unknown normalize=${normalize}. Use auto|mad|sigmoidal|sepd|zscore|all, or pass a string[] of feature names.`);
+    }
+    const nm = args.normalization_methods;
+    if (nm && typeof nm === "object" && !Array.isArray(nm)) {
+        for (const [col, method] of Object.entries(nm)) {
+            if (!ALLOWED_NORM_METHODS.has(String(method))) {
+                throw new Error(`Unknown normalization_methods.${col}=${method}. Allowed: zscore|mad|sigmoidal|sepd|none.`);
+            }
+        }
+    }
+}
 /**
  * Fetch presets + the plan-scoped allowed_job_types in one /v1/training/config call.
  * Used to scope train-action selection to entitled modes.
@@ -49,6 +68,8 @@ export const TRAINING_INPUT_SCHEMA = {
         feature: z.string(),
         period: z.number(),
     })).optional(),
+    cyclic_pairs: z.array(z.array(z.string()).min(2).max(2)).optional()
+        .describe("impute only: [[cos_col, sin_col], ...] for circular prototype means + atomic chord BMU. Those columns get circular quality metrics only (no Euclidean R²)."),
     temporal_features: z.array(z.object({
         columns: z.array(z.string()),
         format: z.string(),
@@ -87,13 +108,13 @@ export const TRAINING_INPUT_SCHEMA = {
     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."),
+        .describe("impute only: quality.csv — linear cols: kfold_holdout_pool + resubstitution_optimistic; cyclic_pairs cols: circular metrics only (no Euclidean R²). Aggregate MAE/RMSE excludes cyclic columns. 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)"),
+        .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)"),
     gamma_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional())
@@ -159,9 +180,8 @@ export function buildFloopParams(args) {
         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;
+        params.output_dpi = resolveOutputDpi(output_dpi);
     if (colormap)
         params.colormap = colormap;
     if (n_initial !== undefined)
@@ -225,7 +245,7 @@ export function buildFloopParams(args) {
     return { params, paramSummary };
 }
 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, normalization_methods, 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 { 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, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, } = args;
     const p = preset ? presets[preset] : undefined;
     const params = {
         model: model ?? "SOM",
@@ -245,6 +265,8 @@ export function buildTrainMapParams(args, presets) {
         params.epochs = p.epochs;
     if (cyclic_features?.length)
         params.cyclic_features = cyclic_features;
+    if (cyclic_pairs?.length)
+        params.cyclic_pairs = cyclic_pairs;
     if (columns?.length)
         params.columns = columns;
     if (auto_log_transforms)
@@ -274,9 +296,8 @@ export function buildTrainMapParams(args, presets) {
     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;
+        params.output_dpi = resolveOutputDpi(output_dpi);
     if (colormap)
         params.colormap = colormap;
     if (row_range && row_range.length >= 2 && row_range[0] <= row_range[1])

package/dist/tools/training_guidance.js

@@ -1,7 +1,7 @@
 import { registerAuditedTool } from "../audit.js";
 import { fetchTrainingGuidanceFromApi } from "../shared.js";
 export function registerTrainingGuidanceTool(server) {
-    registerAuditedTool(server, "training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines, normalization MAD vs SEPD guide). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints + normalization decision ladder — review, then submit with train. For full orientation and SOP, call guide_barsom_workflow first. Optional UI: results_explorer—not required; jobs + results suffice.", {}, async () => {
+    registerAuditedTool(server, "training_guidance", "Structured presets, parameter hints, and normalization decisions for train. Served from the API, filtered to your plan. Review, then submit with train.", {}, async () => {
         const text = await fetchTrainingGuidanceFromApi();
         return { content: [{ type: "text", text }] };
     });

package/dist/train_finalize.js

@@ -1,9 +1,9 @@
-import { apiCall, pollUntilComplete } from "./shared.js";
+import { apiCall, pollUntilComplete, POLL_FINALIZE_MAX_MS } from "./shared.js";
 /**
  * When train compute finishes, finalize_training may still be rendering figures on worker-io.
  * Poll it before fetching results.
  */
-export async function pollFinalizeIfPresent(jobId, data, timeoutMs = 600_000) {
+export async function pollFinalizeIfPresent(jobId, data, timeoutMs = POLL_FINALIZE_MAX_MS) {
     const finalizeJobId = data.finalize_job_id;
     if (!finalizeJobId)
         return { finalizeJobId: null, note: null };