@barivia/barmesh-mcp 0.8.3 → 0.8.4

package/dist/shared.js

@@ -35,7 +35,7 @@ function newRequestId() {
     return randomUUID();
 }
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.8.3";
+export const CLIENT_VERSION = "0.8.4";
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Large per-cell CSV uploads may exceed the default fetch timeout. */
 export const UPLOAD_DATASET_TIMEOUT_MS = 180_000;

package/dist/tools/results.js

@@ -21,6 +21,18 @@ function formatMeshResultsSummary(jobId, data, summary) {
     const curveNote = (ord?.length ?? 0) > 0 || (conv?.length ?? 0) > 0
         ? `Training curves: ${ord?.length ?? 0} ordering + ${conv?.length ?? 0} convergence batch samples (≤1000 each in API/MCP responses).`
         : "";
+    const topDivs = summary.top_divergences;
+    const klComp = summary.feature_kl_complexity;
+    const topDivLine = topDivs && topDivs.length > 0
+        ? `Top feature-plane symmetric KL pairs (component association — not mesh SKL/EMD): ${topDivs
+            .map((t) => `${t.f1}&${t.f2}=${typeof t.symmetric_kl === "number" ? Number(t.symmetric_kl).toFixed(3) : t.symmetric_kl}`)
+            .join(", ")}`
+        : "";
+    const klComplexityLine = klComp && klComp.length > 0
+        ? `Feature KL complexity (mean outgoing): ${klComp
+            .map((t) => `${t.feature}=${typeof t.mean_outgoing_kl === "number" ? Number(t.mean_outgoing_kl).toFixed(3) : t.mean_outgoing_kl}`)
+            .join(", ")}`
+        : "";
     return [
         header,
         `Preset: ${String(summary.preset ?? "generic")} | Grid: ${grid.length >= 2 ? `${grid[0]}×${grid[1]}` : "N/A"} | Reference: ${String(summary.reference_mesh ?? "N/A")}`,
@@ -28,8 +40,13 @@ function formatMeshResultsSummary(jobId, data, summary) {
         meshes.length > 0 ? `\nDistances vs reference:\n${meshLines.join("\n")}` : "",
         stepLines.length > 0 ? `\nStepwise:\n${stepLines.join("\n")}` : "",
         readingLine ? `\nConvergence: ${readingLine}` : "",
+        topDivLine,
+        klComplexityLine,
         curveNote,
         "\nAdvisory: SOM distances complement, not replace, numerical uncertainty analysis (use barmesh_richardson for classical GCI).",
+        topDivLine || klComplexityLine
+            ? "Feature-plane KL (divergence_kl / feature_divergences.json) measures association between SOM component planes; mesh SKL/EMD measure fingerprint distance between meshes. Refresh or add W1 via barmesh_results(action=feature_divergences, metrics=[\"wasserstein\"])."
+            : "",
         "For every figure: barmesh_results_explorer(job_id) or barmesh_results(action=download). Use figures=\"none\" to skip inline images.",
     ].filter(Boolean).join("\n");
 }
@@ -40,6 +57,8 @@ const TEXT_ARTIFACTS = [
     "distances_to_ref.txt",
     "emd_stepwise.txt",
     "cfd_metrics.json",
+    "feature_divergences.json",
+    "weights.json",
     "richardson_gci.csv",
 ];
 export function registerResultsTool(server) {
@@ -47,18 +66,22 @@ export function registerResultsTool(server) {
 
 | Action | Use when |
 |--------|----------|
-| get | Read the summary. mesh_convergence: distances + inline figures. richardson: triplet p/GCI table + topology_warning; see richardson_gci.csv. |
-| image | Download one figure by filename (e.g. KL_ref.png, combined.pdf). |
+| get | Read the summary. mesh_convergence: distances + inline figures + feature-plane KL tops when present. richardson: triplet p/GCI table + topology_warning; see richardson_gci.csv. |
+| image | Download one figure by filename (e.g. KL_ref.png, combined.pdf, divergence_kl.png). |
 | render | Re-render the figures as publication PDFs (or SVG) on demand — PDFs are NOT generated by default. |
 | download | Save figures and metrics to a local folder (headless / agent path). |
+| feature_divergences | Refresh feature-plane KL matrices / optional Wasserstein on SOM component planes (async; not mesh fingerprint KL). |
 
 BEST FOR: After barmesh_jobs(action=status) shows completed (and finalize finished if defer_figures was used).
-FIGURES: Default bundle is combined.png, overview_distances.png (all KL/EMD panels), plot_vol_all_meshes.png, plot_vol_steps.png, and learning_curve.png — not redundant per-feature PNGs. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
+FIGURES: Default bundle is combined.png, overview_distances.png (all KL/EMD panels), plot_vol_all_meshes.png, plot_vol_steps.png, and learning_curve.png — not redundant per-feature PNGs or divergence_kl. action=get inlines the headline set; pass figures="all" for every artifact listed in summary.files, figures="none" for metrics only (recommended for agents).
+FEATURE-PLANE KL: mesh SKL/EMD (KL_ref, EMD_*) compare meshes; divergence_kl / feature_divergences.json compare SOM component planes (barsom-parallel). Finalize already writes symmetric KL; use action=feature_divergences for W1 or a refresh.
 PDFs ON DEMAND: vector PDFs are not produced by default. Use action=render (format=pdf) once, then action=image or action=download.
 If GET /v1/results returns 404 shortly after status=completed, cfd_finalize may still be rendering — poll barmesh_jobs(status) until finalize_job_id completes.
 UNAVAILABLE: If the mesh analysis API is temporarily unavailable, say so plainly and suggest retry later (~retry_after_sec). Figures already downloaded stay usable.
 NOT FOR: Submitting jobs.`, {
-        action: z.enum(["get", "image", "render", "download"]).describe("get: summary + figures; image: one file; render: lazy PDF/SVG; download: save to disk"),
+        action: z
+            .enum(["get", "image", "render", "download", "feature_divergences"])
+            .describe("get: summary + figures; image: one file; render: lazy PDF/SVG; download: save to disk; feature_divergences: feature-plane KL/W1 (async)."),
         job_id: z.string().describe("Job ID"),
         filename: z.string().optional().describe("For action=image: the figure filename (e.g. KL_ref.png or, after render, KL_ref.pdf)"),
         format: z.enum(["pdf", "png", "svg"]).optional().describe("For action=render: output format to generate (default pdf). PNG previews already exist by default."),
@@ -68,8 +91,60 @@ NOT FOR: Submitting jobs.`, {
             .describe("For action=get/download: which figures (default headline panels; 'all'; 'none'; or a list of base names)"),
         folder: z.string().optional().describe("For action=download: directory to save into (relative to workspace). Files land in a per-job subfolder."),
         include_json: z.boolean().optional().describe("For action=download: also save summary.json and text/CSV artifacts"),
+        metrics: z
+            .array(z.enum(["symmetric_kl", "directed_kl", "wasserstein"]))
+            .optional()
+            .describe("action=feature_divergences: which matrices (default symmetric_kl+directed_kl). Add wasserstein for W1."),
+        wasserstein_method: z
+            .enum(["sinkhorn", "exact"])
+            .optional()
+            .describe("action=feature_divergences: OT solver when metrics includes wasserstein (default sinkhorn)."),
+        output_format: z.enum(["png", "pdf", "svg"]).optional().describe("action=feature_divergences: heatmap format (default png)."),
+        output_dpi: z.number().int().min(1).max(4).optional().describe("action=feature_divergences: PNG scale factor (default 2)."),
     }, async (args) => {
-        const { action, job_id, filename, format, figures, folder, include_json } = args;
+        const { action, job_id, filename, format, figures, folder, include_json, metrics: divergenceMetrics, wasserstein_method: wassersteinMethod, output_format, output_dpi, } = args;
+        if (action === "feature_divergences") {
+            const body = {
+                metrics: divergenceMetrics ?? ["symmetric_kl", "directed_kl"],
+                output_format: output_format ?? "png",
+                output_dpi: output_dpi ?? 2,
+            };
+            if (wassersteinMethod != null)
+                body.wasserstein_method = wassersteinMethod;
+            const data = (await apiCall("POST", `/v1/results/${job_id}/feature_divergences`, body));
+            const newJobId = data.id;
+            const poll = await pollUntilComplete(newJobId, POLL_STAGE_MAX_MS);
+            if (poll.status !== "completed") {
+                return textResult(`Feature divergences job ${newJobId} submitted (parent mesh job ${job_id}). Poll with barmesh_jobs(action=status, job_id="${newJobId}"), then barmesh_results(action=get, job_id="${job_id}").`);
+            }
+            const res = (await apiCall("GET", `/v1/results/${newJobId}`));
+            const sum = (res.summary ?? {});
+            const topDivs = sum.top_divergences ?? [];
+            const klComp = sum.feature_kl_complexity ?? [];
+            const topW1 = sum.top_wasserstein ?? null;
+            const lines = [
+                `Feature-plane divergences complete — job_id: ${newJobId} (parent mesh job: ${job_id})`,
+                `Method: ${sum.divergence_method ?? "symmetric_kl_min_shift_sum_norm_denormalized_component_planes"}`,
+                `Weight space: ${sum.weight_space ?? "denormalized"} (physical component planes)`,
+                `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(", ")}`
+                    : "",
+                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). This is feature-plane association — distinct from mesh fingerprint SKL/EMD (KL_ref, EMD_*).`,
+            ].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))) {
+                await tryAttachImage(content, job_id, f);
+            }
+            return { content };
+        }
         if (action === "render") {
             const fmt = format ?? "pdf";
             const submit = (await apiCall("POST", "/v1/cfd/render", { job_id, format: fmt }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barmesh-mcp",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "barmesh MCP proxy — SOM-based CFD mesh-convergence and Richardson/GCI analysis on the Barivia cloud API",
   "keywords": [
     "mcp",