@barivia/barsom-mcp 0.21.0 → 0.22.2

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 };

package/dist/training_monitor_curve.js

@@ -16,7 +16,7 @@ export function isKernelTrainingComplete(data, status) {
         return true;
     return status === "completed";
 }
-export function teCurveLabel(base, _kernelComplete = false) {
+export function teCurveLabel(base) {
     return `${base} (panel)`;
 }
 export function formatCurveSourceNote(data) {