@barivia/barsom-mcp 0.14.0 → 0.15.3

package/dist/tools/train.js

@@ -1,6 +1,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, 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.
 
@@ -124,29 +125,41 @@ export async function runTrain(action, args) {
             : action === "impute" ? "variant=train_impute"
                 : "variant=som";
         data.effective_params = `${variantPrefix}, ${paramSummary}`;
+        const hasTransforms = action !== "impute" &&
+            transforms != null &&
+            typeof transforms === "object" &&
+            Object.keys(transforms).length > 0;
+        const extras = buildTrainSubmitExtras({
+            newJobId,
+            totalRows,
+            hasTransforms,
+            prepareJobId: data.prepare_job_id ?? null,
+            variantPrefix,
+            paramSummary,
+            impute: action === "impute",
+        });
         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}). `;
+            let msg = extras.message;
             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.`;
+                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 = `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.`;
+            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);
     }
@@ -229,6 +242,13 @@ export async function runTrain(action, args) {
             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`));
+            totalRows = Number(preview?.total_rows ?? 0);
+        }
+        catch { /* ignore */ }
+        const hasTransforms = transforms != null && typeof transforms === "object" && Object.keys(transforms).length > 0;
         const maxNodeSummary = max_nodes === undefined ? "max_nodes=auto(~2*sqrt(n_samples))" : `max_nodes=${max_nodes}`;
         const paramSummary = [
             "variant=floop",
@@ -238,10 +258,17 @@ export async function runTrain(action, args) {
             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.`;
+        const extras = buildTrainSubmitExtras({
+            newJobId,
+            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/train_finalize.js

@@ -0,0 +1,25 @@
+import { apiCall, pollUntilComplete } 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) {
+    const finalizeJobId = data.finalize_job_id;
+    if (!finalizeJobId)
+        return { finalizeJobId: null, note: null };
+    const poll = await pollUntilComplete(finalizeJobId, timeoutMs);
+    if (poll.status === "failed") {
+        throw new Error(`Training job ${jobId}: finalize_training ${finalizeJobId} failed: ${poll.error ?? "unknown error"}`);
+    }
+    if (poll.status !== "completed") {
+        throw new Error(`Training job ${jobId}: finalize_training ${finalizeJobId} did not complete (status=${poll.status})`);
+    }
+    return {
+        finalizeJobId,
+        note: `Finalize job ${finalizeJobId} completed (figures and summary uploaded).`,
+    };
+}
+/** Re-fetch GET /v1/jobs/:id after finalize so callers see cleared finalize_job_id. */
+export async function refreshJobAfterFinalize(jobId) {
+    return (await apiCall("GET", `/v1/jobs/${jobId}`));
+}

package/dist/train_submit_message.js

@@ -0,0 +1,52 @@
+import { getVizPort } from "./shared.js";
+export function buildTrainSubmitExtras(opts) {
+    const { newJobId, totalRows, hasTransforms, prepareJobId, variantPrefix, paramSummary, impute, resultsHint } = opts;
+    const monitorUrl = getVizPort() > 0
+        ? `http://localhost:${getVizPort()}/viz/training-monitor?mode=standalone&job_id=${encodeURIComponent(newJobId)}`
+        : null;
+    let msg = `Job submitted (${variantPrefix}, ${paramSummary}). `;
+    if (prepareJobId) {
+        msg += `Preprocessing job prepare_training_matrix (${prepareJobId}) runs on worker-io first; train job ${newJobId} starts after it completes. Poll jobs(action=status, job_id="${prepareJobId}") until completed, then poll the train job. `;
+    }
+    msg += `Recommended: training_monitor(job_id="${newJobId}")`;
+    if (monitorUrl)
+        msg += ` or open ${monitorUrl}`;
+    msg += ` while polling jobs(action=status, job_id="${newJobId}") every 60–120s for large jobs. `;
+    msg += `When status is completed, check jobs(action=status) for finalize_job_id — if present, poll that finalize_training job before results(action=get). `;
+    msg += `Then use results(action=get, job_id="${newJobId}")`;
+    if (resultsHint) {
+        msg += ` to ${resultsHint}`;
+    }
+    else if (impute) {
+        msg += ` for the map and imputed.csv`;
+    }
+    else {
+        msg += ` to view the map and metrics`;
+    }
+    msg += `.`;
+    if (totalRows >= 1_000_000 || hasTransforms) {
+        msg += ` Large-table note: progress may stay low during staging preprocess before epochs start.`;
+        if (hasTransforms && totalRows >= 1_000_000) {
+            if (prepareJobId) {
+                msg += ` Transforms run in prepare_training_matrix on worker-io (full dataset, no CSV re-download on GPU).`;
+            }
+            else {
+                msg += ` Transforms require prepare_training_matrix on worker-io for staged datasets; the API enqueues it automatically when needed.`;
+            }
+        }
+    }
+    const pollSteps = prepareJobId
+        ? [
+            `1) jobs(action=status, job_id="${prepareJobId}") until prepare completes`,
+            `2) jobs(action=status, job_id="${newJobId}") every 60–120s until completed`,
+            `3) if finalize_job_id is set, poll it until completed`,
+            `4) results(action=download, job_id="${newJobId}", folder=".", include_json=true)`,
+        ]
+        : [
+            `1) training_monitor(job_id="${newJobId}")`,
+            `2) jobs(action=status, job_id="${newJobId}") every 60–120s until completed`,
+            `3) if finalize_job_id is set, poll it until completed`,
+            `4) results(action=download, job_id="${newJobId}", folder=".", include_json=true)`,
+        ];
+    return { message: msg, suggested_next_step: pollSteps.join(" → ") };
+}