@barivia/barsom-mcp 0.20.3 → 0.21.0

package/README.md

@@ -162,7 +162,7 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 | Tool | Role |
 |------|------|
-| `training_monitor` | Live QE + topographic-error curves (ordering/convergence, dual y-axis), FLooP step progress when applicable; optional — `jobs(action=status)` is enough |
+| `training_monitor` | Live QE + **panel** topographic-error curves (ordering/convergence, dual y-axis); **Panel TE** and **Map TE** scalars at kernel end; FLooP step progress when applicable; optional — `jobs(action=status)` is enough |
 | `results_explorer` | Browse metrics and figures after training completes |
 | `_fetch_figure` | **Host / App only** — Results Explorer invokes this for one raster figure; not for agent chat |
 
@@ -180,6 +180,7 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 
 ### Migration notes
 
+- **Fixed-panel live TE (0.20.4):** mid-training TE curves use a fixed evaluation panel (`te_panel_size` on `train`). Monitors show **Panel TE** and **Map TE** separately; curve tail no longer snaps to map TE.
 - **Features (0.20.0, non-breaking):**
   - **FLooP-SIOM maps are now projectable.** `inference(action=project_columns)`, `inference(action=predict)`, and `datasets(action=add_expression, project_onto_job=<floop_job>)` work on FLooP-SIOM (free/chain) maps — values render onto the FLooP Voronoi layout instead of failing. Grid-only ops (`inference(action=transition_flow | impute_column | render_variant)`) return a clear `unsupported_topology_for_inference` message; use a fixed-grid SOM/SIOM for those. No client change required.
   - **`datasets(action=reduce_spectral)` column selectors.** New optional `columns_range` (`[first, last]`, the server expands the inclusive numeric block — preferred for wide spectra over sending thousands of names) and `columns_except` (drop non-frequency columns like id/label/target from the block, or use alone for "all numeric except these"). `columns_except` composes with `columns_block` or `columns_range`; `columns_block` and `columns_range` are mutually exclusive. Existing `columns_block` callers are unaffected.

package/dist/audit.js

@@ -2,6 +2,7 @@
  * MCP tool audit wrapper — tool name, action, latency, outcome; no secrets.
  */
 import { logAudit } from "./logger.js";
+import { runWithTrace } from "./shared.js";
 /** Keys safe to include in audit param summaries (no paths, keys, or bodies). */
 const AUDIT_PARAM_KEYS = new Set([
     "action",
@@ -160,7 +161,9 @@ export function registerAuditedTool(server, name, description, schema, handler)
     server.tool(name, description, schema, (async (args) => {
         const rec = args;
         const action = typeof rec.action === "string" && rec.action.length > 0 ? rec.action : "default";
-        return runMcpToolAudit(name, action, rec, () => handler(args));
+        // One trace per tool invocation: every apiCall inside this handler shares one
+        // trace_id, so the API + job chain reconstruct the whole logical action.
+        return runWithTrace(() => runMcpToolAudit(name, action, rec, () => handler(args)));
     }));
 }
 /** Attach audit flags to a tool result (stripped before returning to MCP client). */

package/dist/shared.js

@@ -5,6 +5,7 @@ import fs from "node:fs/promises";
 import { createReadStream, createWriteStream } from "node:fs";
 import { createGzip } from "node:zlib";
 import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
@@ -26,7 +27,7 @@ export const RETRYABLE_STATUS = new Set([502, 503, 504]);
  * 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.20.3";
+export const CLIENT_VERSION = "0.21.0";
 /** 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). */
@@ -342,6 +343,30 @@ function throwApiError(status, bodyText, requestId) {
 /**
  * @param requestTimeoutMs Optional per-request timeout (default `BARIVIA_FETCH_TIMEOUT_MS`).
  */
+// ---- Distributed-trace context (W3C traceparent) ----
+//
+// One logical user action (a tool call that may make several API requests, e.g.
+// upload + analyze + train + poll) shares ONE trace_id so the API and the whole job
+// chain (stage -> prepare -> train -> finalize) can be reconstructed end-to-end. The
+// trace id is scoped per tool invocation via AsyncLocalStorage (see registerAuditedTool);
+// each API call mints a fresh span id. Falls back to a per-call trace if no scope is set.
+const _traceStore = new AsyncLocalStorage();
+function _newTraceId() {
+    return randomUUID().replace(/-/g, ""); // 32 hex
+}
+function _newSpanId() {
+    return randomUUID().replace(/-/g, "").slice(0, 16); // 16 hex
+}
+/** Run `fn` within a fresh trace scope so all apiCall()s inside share one trace_id. */
+export function runWithTrace(fn) {
+    return _traceStore.run(_newTraceId(), fn);
+}
+function _currentTraceId() {
+    return _traceStore.getStore() ?? _newTraceId();
+}
+function _traceparentHeader() {
+    return `00-${_currentTraceId()}-${_newSpanId()}-01`;
+}
 export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs) {
     const url = `${API_URL}${path}`;
     const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
@@ -350,6 +375,7 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
         Authorization: `Bearer ${API_KEY}`,
         "Content-Type": contentType,
         "X-Request-ID": requestId,
+        traceparent: _traceparentHeader(),
         "X-Barsom-Client-Version": CLIENT_VERSION,
         ...extraHeaders,
     };
@@ -424,6 +450,7 @@ export async function apiRawCall(path, requestTimeoutMs) {
                 headers: {
                     Authorization: `Bearer ${API_KEY}`,
                     "X-Request-ID": requestId,
+                    traceparent: _traceparentHeader(),
                 },
             }, effectiveTimeout);
             if (!resp.ok) {

package/dist/tools/training_core.js

@@ -78,6 +78,8 @@ export const TRAINING_INPUT_SCHEMA = {
             convergence: z.tuple([z.number(), z.number()]),
         })]).optional()),
     batch_size: z.number().int().optional(),
+    te_panel_size: z.number().int().optional()
+        .describe("Fixed evaluation-panel size for live topographic error during training (default clamp(grid_nodes*6, 500, 10000))"),
     quality_metrics: z.union([z.enum(["fast", "standard", "full"]), z.array(z.string())]).optional(),
     backend: z.enum(["auto", "cpu", "gpu", "gpu_graphs"]).optional().default("auto"),
     output_format: z.enum(["png", "pdf", "svg"]).optional().default("png"),

package/dist/tools/training_monitor.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
 import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
-import { lastEpochTeFromCurves, snapTeCurvesToMapTe } from "../training_monitor_curve.js";
+import { lastEpochTeFromCurves } from "../training_monitor_curve.js";
 export const TRAINING_MONITOR_URI = "ui://barsom/training-monitor";
 export const TRAINING_MONITOR_REFRESH_MS = 5000;
 function hasCurveArrays(data) {
@@ -72,13 +72,13 @@ async function enrichWithTrainingLog(job_id, data) {
         if (status === "completed" || status === "failed" || status === "cancelled") {
             merged.topographic_error = mapTe;
         }
-        return snapTeCurvesToMapTe(merged);
+        return merged;
     }
     catch {
         if (epochTe != null) {
-            return snapTeCurvesToMapTe({ ...data, epoch_topographic_error: epochTe });
+            return { ...data, epoch_topographic_error: epochTe };
         }
-        return data.kernel_complete === true ? snapTeCurvesToMapTe(data) : data;
+        return data;
     }
 }
 export function registerTrainingMonitorTool(server) {

package/dist/training_monitor_curve.js

@@ -16,25 +16,8 @@ export function isKernelTrainingComplete(data, status) {
         return true;
     return status === "completed";
 }
-/** Snap the last TE curve point to authoritative full-map TE when kernel training is done. */
-export function snapTeCurvesToMapTe(data) {
-    const mapTe = data.map_topographic_error ??
-        (data.kernel_complete === true ? data.topographic_error : null);
-    if (mapTe == null || !Number.isFinite(Number(mapTe)))
-        return data;
-    const out = { ...data };
-    for (const key of ["ordering_topographic_errors", "convergence_topographic_errors"]) {
-        const arr = out[key];
-        if (Array.isArray(arr) && arr.length > 0) {
-            const copy = arr.slice();
-            copy[copy.length - 1] = Number(mapTe);
-            out[key] = copy;
-        }
-    }
-    return out;
-}
-export function teCurveLabel(base, kernelComplete) {
-    return kernelComplete ? `${base} (→ map TE)` : `${base} (sampled)`;
+export function teCurveLabel(base, _kernelComplete = false) {
+    return `${base} (panel)`;
 }
 export function formatCurveSourceNote(data) {
     const src = data.training_curve_source_batches;
@@ -49,17 +32,20 @@ export function formatCurveSourceNote(data) {
     if (convTotal != null && convTotal > convShown) {
         parts.push(`${convShown} of ${convTotal.toLocaleString()} convergence batch samples`);
     }
-    const mapTe = data.map_topographic_error;
-    const epochTe = data.epoch_topographic_error;
-    if (mapTe != null &&
-        epochTe != null &&
-        Number.isFinite(Number(mapTe)) &&
-        Number.isFinite(Number(epochTe)) &&
-        Math.abs(Number(epochTe) - Number(mapTe)) > 0.0005) {
-        parts.push(`Live TE is a subsampled batch estimate during training; final point snaps to map TE ${Number(mapTe).toFixed(4)} (last sampled ${Number(epochTe).toFixed(4)})`);
+    const teEval = data.te_evaluation;
+    const panelM = teEval?.te_panel_size;
+    const panelN = teEval?.te_panel_n_train;
+    if (typeof panelM === "number" && typeof panelN === "number" && panelN > 0) {
+        const strat = teEval?.te_panel_stratified === true ? ", stratified by mesh" : "";
+        parts.push(`TE curve uses a fixed panel of ${panelM.toLocaleString()} of ${panelN.toLocaleString()} training rows${strat}`);
     }
-    else if (mapTe != null && Number.isFinite(Number(mapTe))) {
-        parts.push(`TE curve final point is full-map topographic error (${Number(mapTe).toFixed(4)}).`);
+    const panelTe = data.panel_topographic_error;
+    const mapTe = data.map_topographic_error;
+    if (panelTe != null &&
+        mapTe != null &&
+        Number.isFinite(Number(panelTe)) &&
+        Number.isFinite(Number(mapTe))) {
+        parts.push(`Panel TE ${Number(panelTe).toFixed(4)} · Map TE ${Number(mapTe).toFixed(4)} (full training set)`);
     }
     if (parts.length === 0)
         return null;
@@ -82,8 +68,7 @@ export function alignTeToQeAxis(te, qeLen) {
     return [...Array(pad).fill(null), ...te];
 }
 /**
- * Last sampled TE point from the (batch-aligned) live TE curve. This is the most
- * recent per-epoch TE estimate, distinct from the final trained-map TE in the summary.
+ * Last panel TE point from the (batch-aligned) live TE curve.
  */
 export function lastEpochTeFromCurves(data) {
     const conv = data.convergence_topographic_errors;