@barivia/barsom-mcp 0.23.12 → 0.23.14

package/dist/job_status_format.js

@@ -64,6 +64,10 @@ export function formatJobStatusText(job_id, data) {
         else if (prepareJobId) {
             parts.push(`phase: waiting_for_prepare (prepare_job_id=${prepareJobId})`);
         }
+        else if (progress >= 5) {
+            // Progress advanced but phase not yet stamped — do not imply early ingest.
+            parts.push(`phase: running`);
+        }
         else {
             parts.push(`phase: preprocessing (not set yet — often download/parse before first progress tick)`);
         }

package/dist/shared.js

@@ -66,7 +66,7 @@ function newRequestId() {
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.23.12";
+export const CLIENT_VERSION = "0.23.14";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -1218,6 +1218,27 @@ export function coerceFiguresArg(v) {
     }
     return val;
 }
+/**
+ * Images to inline after results(action=feature_divergences).
+ * Default is text-only (omit / none / default / combined_only) so headless LLM hosts
+ * (e.g. Ornith) are not rejected for image MCP content. Opt in with "all"/"images" or a filename array.
+ */
+export function getFeatureDivergenceImagesToFetch(files, figures) {
+    const isRasterOrSvg = (f) => /\.(png|svg)$/i.test(f);
+    if (figures === "all" || figures === "images") {
+        return files.filter(isRasterOrSvg);
+    }
+    if (Array.isArray(figures)) {
+        return figures.map((name) => {
+            const n = String(name);
+            if (/\.(png|svg|pdf)$/i.test(n))
+                return n;
+            return `${n}.png`;
+        });
+    }
+    // omit, "none", "default", "combined_only" → no inline images
+    return [];
+}
 /** Attach result figures with captions; tracks inlined names for dedup. */
 export async function attachResultsImages(content, jobId, jobType, summary, figures, includeIndividual, inlinedImages) {
     for (const name of getResultsImagesToFetch(jobType, summary, figures, includeIndividual)) {

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, attachResultsImages, resolveOutputDpi, POLL_RECOLOR_MAX_MS, fmtDensityDiffNode, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, structuredTextResult, coerceFiguresArg, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, attachResultsImages, resolveOutputDpi, POLL_RECOLOR_MAX_MS, fmtDensityDiffNode, getCaptionForImage, shouldFetchAllRemainingFigures, getFeatureDivergenceImagesToFetch, mimeForFilename, structuredTextResult, coerceFiguresArg, } 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**.
 
@@ -33,14 +33,14 @@ action=export: Structured data exports (not the same as download). Use export_ty
 
 action=download: Save figures/artifacts to disk (deduped file list). Use so user can open, share, or version files locally.
   - folder: e.g. "." or "./results". Relative to the client's working directory (or MCP workspace). Each job lands in a dedicated subfolder under folder: {job_type}_{label} when label was set at train time, otherwise {job_type}_{job_id_prefix} — so parallel downloads never overwrite summary.json or figure names.
-  - figures: "all" (default) downloads published image files; OR a string array of exact artifact filenames from the job (e.g. ["predictions.csv"], ["combined.png","umatrix.png"]). Enum tokens like "none" are for action=get, not download.
+  - figures: "all" (default) downloads published image files; OR a string array of **exact** artifact filenames from summary.files / the Available list (e.g. ["combined.png","component_1_alcohol.png"]). Do not invent bare component_1.png — published planes are component_{i}_{feature}.png. Logical tokens like component_1 are for action=get/recolor only. Enum "none" is for get/feature_divergences, not download.
   - include_json: when true, also saves summary.json and other JSON artifacts (use this when you need CSVs listed in summary.files without naming each figure).
 
 action=recolor: Change colormap or output format — no retraining. Returns a new job_id; auto-polls 60s.
   AFTER: use results(action=get, job_id=NEW_JOB_ID).
   Colormaps: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, balance, hsv, twilight, RdBu, Spectral. Also: thermal, hot, grays, RdYlBu, delta, curl, phase, rainbow, tol_bright, tol_muted.
 
-action=feature_divergences: Recompute component-plane divergences (min-shift sum-normalized denormalized planes). Finalize already writes symmetric KL + rankings; use this for Wasserstein or a refresh. metrics default ["symmetric_kl","directed_kl"]; add "wasserstein" for W1. Auto-polls then summarizes top pairs vs Pearson top_correlations.
+action=feature_divergences: Recompute component-plane divergences (min-shift sum-normalized denormalized planes). Finalize already writes directed KL heatmap (divergence_kl: cell (i,j)=KL(pᵢ‖pⱼ); upper/lower triangles opposite directions) plus SKL pair tops and mean-outgoing ranking in JSON; use this for Wasserstein or a refresh. metrics default ["symmetric_kl","directed_kl"]; add "wasserstein" for W1. Auto-polls then returns text + structuredContent (tops/metrics/files). Default is **text-only** (no inline images) for headless LLM hosts; opt in with figures="all" or figures=["divergence_kl.png"]. Prefer results(download) for heatmaps on text-only clients.
 
 NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or temporal flow (use inference(action=transition_flow)).`, {
         action: z
@@ -50,7 +50,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
         figures: z.preprocess(coerceFiguresArg, z
             .union([z.enum(["default", "combined_only", "all", "images", "none"]), z.array(z.string())])
             .optional()
-            .describe("Prefer string 'all'/'none'. action=get: omit=combined only; 'all'=all plots; 'none'=metrics text only; array=logical names (combined,umatrix,…). action=download: 'all'=image files; array=exact filenames (e.g. combined.png). Stringified JSON arrays from hosts are accepted.")),
+            .describe("Prefer string 'all'/'none'. action=get: omit=combined only; 'all'=all plots; 'none'=metrics text only; array=logical names (combined,umatrix,…). action=feature_divergences: omit/'none'=text-only (default); 'all'/'images'=inline heatmaps; array=exact heatmap filenames. action=download: 'all'=image files; array=exact filenames from summary.files (e.g. component_1_alcohol.png — not bare component_1.png). Stringified JSON arrays from hosts are accepted.")),
         include_individual: z
             .boolean()
             .optional()
@@ -419,7 +419,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                     ...(topCorrLine ? ["", topCorrLine] : []),
                     ...(topDivLine ? [topDivLine] : []),
                     ...(klComplexityLine ? [klComplexityLine] : []),
-                    ...(topDivLine || klComplexityLine ? ["(Compare Pearson vs KL: high |r| ≠ low KL; use results(action=feature_divergences, metrics=[\"wasserstein\"]) for W1.)"] : []),
+                    ...(topDivLine || klComplexityLine ? ["(divergence_kl.png is directed KL: cell (i,j)=KL(pᵢ‖pⱼ), upper/lower triangles opposite directions. Compare Pearson vs SKL pair tops; use results(action=feature_divergences, metrics=[\"wasserstein\"]) for W1.)"] : []),
                     ...(siom ? ["", "SIOM layer coverage (distinct from grid dead nodes):",
                         `  Utilization: ${siom.utilization !== undefined ? Number(siom.utilization).toFixed(4) : "N/A"}`,
                         `  SIOM dead fraction: ${siom.dead_fraction !== undefined ? Number(siom.dead_fraction).toFixed(4) : "N/A"}`,
@@ -664,12 +664,16 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 }
             }
             const savedDir = path.join(folder, jobSubfolder);
+            const availCap = 40;
+            const availableNote = missing.length > 0 && files.length > 0
+                ? ` Available (${Math.min(files.length, availCap)}${files.length > availCap ? ` of ${files.length}` : ""}): ${files.slice(0, availCap).join(", ")}${files.length > availCap ? ", …" : ""}. Use exact names from this list (component planes are component_{i}_{feature}.png, not bare component_1.png).`
+                : "";
             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.`,
+                            text: `No files saved.${missNote}${availableNote} Check job_id and that the job is completed.`,
                         }],
                 };
             }
@@ -679,7 +683,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             return {
                 content: [{
                         type: "text",
-                        text: `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}.${missNote}`,
+                        text: `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}.${missNote}${availableNote}`,
                     }],
             };
         }
@@ -707,6 +711,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             return { content: [{ type: "text", text: `Recolor job ${newJobId} submitted. Poll with jobs(action=status, job_id="${newJobId}"), then results(action=get, job_id="${newJobId}").` }] };
         }
         if (action === "feature_divergences") {
+            resetInlineAttachBudget();
             const body = {
                 metrics: divergenceMetrics ?? ["symmetric_kl", "directed_kl"],
                 output_format: output_format ?? "png",
@@ -721,7 +726,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
                 return {
                     content: [{
                             type: "text",
-                            text: `Feature divergences job ${newJobId} submitted (parent ${job_id}). Poll with jobs(action=status, job_id="${newJobId}"), then results(action=get, job_id="${newJobId}").`,
+                            text: `Feature divergences job ${newJobId} submitted (parent ${job_id}). Poll with jobs(action=status, job_id="${newJobId}"), then results(action=get, job_id="${newJobId}", figures="none").`,
                         }],
                 };
             }
@@ -730,28 +735,47 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             const topDivs = sum.top_divergences ?? [];
             const klComp = sum.feature_kl_complexity ?? [];
             const topW1 = sum.top_wasserstein ?? null;
+            const files = sum.files ?? [];
+            const toInline = getFeatureDivergenceImagesToFetch(files, figuresArg);
             const lines = [
                 `Feature divergences complete — job_id: ${newJobId} (parent training: ${job_id})`,
-                `Method: ${sum.divergence_method ?? "symmetric_kl_min_shift_sum_norm_denormalized_component_planes"}`,
+                `Method: ${sum.divergence_method ?? "kl_min_shift_sum_norm_denormalized_component_planes"}`,
                 `Weight space: ${sum.weight_space ?? "denormalized"}`,
                 `Metrics: ${JSON.stringify(sum.metrics ?? body.metrics)}`,
                 topDivs.length
                     ? `Top symmetric KL pairs: ${topDivs.map((t) => `${t.f1}&${t.f2}=${typeof t.symmetric_kl === "number" ? Number(t.symmetric_kl).toFixed(3) : t.symmetric_kl}`).join(", ")}`
                     : "",
                 klComp.length
-                    ? `KL complexity ranking: ${klComp.map((t) => `${t.feature}=${typeof t.mean_outgoing_kl === "number" ? Number(t.mean_outgoing_kl).toFixed(3) : t.mean_outgoing_kl}`).join(", ")}`
+                    ? `KL complexity ranking (mean outgoing directed KL): ${klComp.map((t) => `${t.feature}=${typeof t.mean_outgoing_kl === "number" ? Number(t.mean_outgoing_kl).toFixed(3) : t.mean_outgoing_kl}`).join(", ")}`
                     : "",
                 topW1 && topW1.length
                     ? `Top Wasserstein pairs: ${topW1.map((t) => `${t.f1}&${t.f2}=${typeof t.wasserstein === "number" ? Number(t.wasserstein).toFixed(3) : t.wasserstein}`).join(", ")}`
                     : "",
-                `Artifacts refreshed on parent result (divergence_kl / feature_divergences.json). Compare with Pearson top_correlations from results(get) on the training job.`,
+                files.length ? `Artifacts: ${files.join(", ")}` : "",
+                toInline.length === 0
+                    ? `Text-only response (default). Heatmaps: results(download, job_id="${job_id}" or "${newJobId}") or re-call with figures="all" on vision-capable hosts.`
+                    : "",
+                `Artifacts refreshed on parent result (divergence_kl = directed KL heatmap, upper/lower triangles opposite directions; feature_divergences.json has both directed_kl and symmetric_kl). Compare with Pearson top_correlations from results(get) on the training job.`,
             ].filter(Boolean);
             const content = [{ type: "text", text: lines.join("\n") }];
-            const files = sum.files ?? [];
-            for (const f of files.filter((x) => /\.(png|svg)$/i.test(x))) {
+            const inlinedImages = new Set();
+            for (const f of toInline) {
                 await tryAttachImage(content, newJobId, f);
+                inlinedImages.add(f);
             }
-            return { content };
+            const structuredPayload = {
+                job_id: newJobId,
+                parent_job_id: job_id,
+                job_type: "feature_divergences",
+                metrics: sum.metrics ?? body.metrics,
+                top_divergences: topDivs,
+                feature_kl_complexity: klComp,
+                top_wasserstein: topW1,
+                files,
+                figures_inlined: [...inlinedImages],
+            };
+            const summaryText = content.filter((c) => c.type === "text").map((c) => c.text).join("\n\n");
+            return structuredTextResult(structuredPayload, summaryText, content);
         }
         throw new Error("Invalid action");
     });

package/package.json

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