@barivia/barsom-mcp 0.10.0 → 0.10.3

package/README.md

@@ -97,11 +97,12 @@ Call at the **start of mapping work** (or when the user asks what the MCP can do
 
 | Action | Use when |
 |--------|----------|
-| `train_map` | Submitting a new map training job — full control: model type, grid, epochs, cyclic/temporal features, transforms. Returns `job_id`; poll with `jobs(action=status, job_id=...)`. |
+| `train_map` | Submitting a new map training job — full control: model type, grid, epochs, cyclic/temporal features, transforms. Returns `job_id`; poll with `jobs(action=status, job_id=...)`. Complete-case data only (no NaNs in training columns). |
+| `train_impute` | Sparse training data: accelerated missSOM / SIOM missSOM — trains a map and imputes missing cells in one job. Defaults: `model=auto`, `cv_folds=5`. Returns map artifacts + `imputed.csv`, `imputation_mask.csv`, optional `quality.csv` / `imputation_uncertainty.csv`. Plain numeric columns only. Valid parent for `inference(impute_column)`. |
 | `train_siom_map` | Submitting a self-interacting map training job — same grid-map workflow plus SIOM controls such as `gamma`, `siom_decay`, and penalty selection. |
 | `train_floop_siom` | Submitting a FLooP-SIOM job — growing node-budget manifold; default `topology=free` (CHL); optional `topology=chain` for strict 1D linked list. |
 | `train_floop_chain` | Deprecated alias for `train_floop_siom` — same behavior. |
-| `status` | Polling after any async job — every 10–15s |
+| `status` | Polling after any async job — every 10–15s; map jobs expose `progress_phase` (ordering, convergence, cv, artifacts) |
 | `list` | Finding job IDs, checking pipeline state |
 | `compare` | Picking the best run from a set (QE, TE, silhouette table) |
 | `cancel` | Stopping a running job |
@@ -127,7 +128,7 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 | Action | Output | Timing |
 |--------|--------|--------|
 | `predict` | Score rows against the trained map. **Inputs:** `dataset_id` (defaults to the parent training dataset) **or** inline `rows` (≤500). **Output style** (`output` param): `"compact"` → `predictions.csv` (row_id, bmu_x/y, bmu_node_index, cluster_id [+ QE / qe_p95 / potential_anomaly when scoring **new** data]); `"annotated"` → `annotated.csv` (original CSV + BMU columns appended). **Regime auto-detected:** when the resolved dataset matches the training dataset, QE columns are intentionally omitted in compact output (training-set fit ≠ generalisation; the p95 anomaly flag would be circular). Prefer `dataset_id` for batches and SIOM/irregular maps. | 5–120s |
-| `impute_column` | Fill a numeric **target_column** not used in training: **requires** `dataset_id` + `target_column`. Dataset must contain all training features plus the target. Pools observed target values from rows mapped to this row's BMU and topology neighbors (BMU + neighbors, often 7 nodes on hex interior; fewer on borders unless the map is periodic). `only_missing` (default true); `impute_aggregation`: mean or median. **Not** held-out validated — map-local estimate. Output **`imputed.csv`**. | 5–120s |
+| `impute_column` | Fill a numeric **target_column** not used in training: **requires** `dataset_id` + `target_column`. Parent job: completed **train_map** or **train_impute**. Dataset must contain all training features plus the target. Pools observed target values from rows mapped to this row's BMU and topology neighbors (BMU + neighbors, often 7 nodes on hex interior; fewer on borders unless the map is periodic). `only_missing` (default true); `impute_aggregation`: mean or median. **Not** held-out validated — map-local estimate. Output **`imputed.csv`**. For holes across many training columns, prefer **jobs(train_impute)** first. | 5–120s |
 | `compare` | density-diff heatmap + top gained/lost nodes — drift, A/B, cohort | 30–120s |
 | `project_columns` | Project one or more dataset columns onto the trained map (component planes) | async |
 | `report` | Report **manifest** (figure names, download URLs, metrics, cluster summary) — sync; use with `results(download)` on the training `job_id` for `report.pdf` when present; build custom PDFs in Quarto/Jupyter | immediate |

package/dist/audit.js

@@ -0,0 +1,118 @@
+/**
+ * MCP tool audit wrapper — tool name, action, latency, outcome; no secrets.
+ */
+import { logAudit } from "./logger.js";
+/** Keys safe to include in audit param summaries (no paths, keys, or bodies). */
+const AUDIT_PARAM_KEYS = new Set([
+    "action",
+    "job_type",
+    "model",
+    "preset",
+    "backend",
+    "output_format",
+    "figures",
+    "job_id",
+    "dataset_id",
+    "compare",
+    "topology",
+    "viz_mode",
+]);
+function scrubParams(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (!AUDIT_PARAM_KEYS.has(k))
+            continue;
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function extractIds(result) {
+    const ids = {};
+    if (result === null || typeof result !== "object")
+        return ids;
+    const r = result;
+    if (typeof r.job_id === "string")
+        ids.job_id = r.job_id;
+    if (typeof r.id === "string" && !ids.job_id)
+        ids.job_id = r.id;
+    if (typeof r.dataset_id === "string")
+        ids.dataset_id = r.dataset_id;
+    const sc = r.structuredContent;
+    if (sc && typeof sc === "object") {
+        const s = sc;
+        if (typeof s.jobId === "string")
+            ids.job_id = s.jobId;
+        if (typeof s.datasetId === "string")
+            ids.dataset_id = s.datasetId;
+    }
+    try {
+        const text = JSON.stringify(result);
+        const jobMatch = text.match(/"job_id"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (jobMatch && !ids.job_id)
+            ids.job_id = jobMatch[1];
+        const dsMatch = text.match(/"dataset_id"\s*:\s*"([a-f0-9-]{36})"/i);
+        if (dsMatch && !ids.dataset_id)
+            ids.dataset_id = dsMatch[1];
+    }
+    catch {
+        /* ignore */
+    }
+    return ids;
+}
+function errorCodeFrom(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.httpStatus !== undefined)
+            return `http_${e.httpStatus}`;
+        const m = e.message ?? "";
+        const codeMatch = m.match(/error_code:\s*(\w+)/);
+        if (codeMatch)
+            return codeMatch[1];
+    }
+    return undefined;
+}
+/**
+ * Run a tool handler with structured audit logging.
+ */
+export async function runMcpToolAudit(tool, action, args, handler) {
+    const t0 = Date.now();
+    const params = scrubParams(args);
+    try {
+        const result = await handler();
+        const ids = extractIds(result);
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "ok",
+            ...ids,
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        return result;
+    }
+    catch (err) {
+        logAudit({
+            tool,
+            action,
+            duration_ms: Date.now() - t0,
+            outcome: "error",
+            error_code: errorCodeFrom(err),
+            ...(Object.keys(params).length > 0 ? { params } : {}),
+        });
+        throw err;
+    }
+}
+/**
+ * Register an MCP tool with structured audit logging on each invocation.
+ */
+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));
+    }));
+}

package/dist/logger.js

@@ -0,0 +1,40 @@
+/**
+ * Structured stdout/stderr logging for the MCP proxy (Docker json-file friendly).
+ */
+const SERVICE_NAME = process.env.BARIVIA_SERVICE_NAME ?? process.env.BARSOM_SERVICE_NAME ?? "mcp-proxy";
+const LOG_FORMAT = (process.env.BARIVIA_LOG_FORMAT ?? process.env.BARSOM_LOG_FORMAT ?? "text").toLowerCase();
+function emit(fields) {
+    const level = fields.level ?? "info";
+    const payload = {
+        ts: new Date().toISOString(),
+        level,
+        service: SERVICE_NAME,
+        ...fields,
+    };
+    delete payload.level;
+    if (LOG_FORMAT === "json") {
+        console.error(JSON.stringify(payload));
+        return;
+    }
+    const parts = [`${payload.ts} ${level.toUpperCase().padEnd(5)} ${fields.msg}`];
+    for (const [k, v] of Object.entries(payload)) {
+        if (k === "ts" || k === "msg" || k === "service")
+            continue;
+        if (v !== undefined && v !== null && v !== "") {
+            parts.push(`${k}=${String(v)}`);
+        }
+    }
+    console.error(parts.join(" | "));
+}
+export function logInfo(msg, fields = {}) {
+    emit({ ...fields, level: "info", msg });
+}
+export function logWarn(msg, fields = {}) {
+    emit({ ...fields, level: "warn", msg });
+}
+export function logError(msg, fields = {}) {
+    emit({ ...fields, level: "error", msg });
+}
+export function logAudit(fields) {
+    emit({ ...fields, event: "mcp_tool_call", level: "info", msg: "mcp_tool_call" });
+}

package/dist/prepare_training_prompt.js

@@ -1,5 +1,5 @@
 import { apiCall } from "./shared.js";
-const FALLBACK_PREFIX = "Please run datasets(action=preview, dataset_id=\"{id}\") to inspect columns, then datasets(action=analyze, dataset_id=\"{id}\") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id=\"{id}\", ...) for a standard fixed-grid SOM, jobs(action=train_siom_map, dataset_id=\"{id}\", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id=\"{id}\", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).";
+const FALLBACK_PREFIX = "Before upload: for jobs(action=train_map) ensure training columns have no NaNs; for jobs(action=train_impute) missing cells in training columns are OK (plain numeric only). Please run datasets(action=preview, dataset_id=\"{id}\") to inspect columns, then datasets(action=analyze, dataset_id=\"{id}\") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id=\"{id}\", ...) for complete-case data, jobs(action=train_impute, dataset_id=\"{id}\", ...) for sparse matrices, jobs(action=train_siom_map, dataset_id=\"{id}\", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id=\"{id}\", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).";
 /** Used by the `prepare_training` MCP prompt; prefers tier-scoped text from the API when online. */
 export async function resolvePrepareTrainingPromptText(datasetId) {
     let promptText = FALLBACK_PREFIX.replaceAll("{id}", datasetId);

package/dist/shared.js

@@ -4,6 +4,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { logInfo } from "./logger.js";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -19,7 +20,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.10.0";
+export const CLIENT_VERSION = "0.10.3";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Poll window for datasets(add_expression) / derive jobs (server-side work can exceed 30s). */
@@ -277,7 +278,7 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
     }
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     const t0 = Date.now();
-    console.error(`${new Date().toISOString()} API -> ${method} ${path} rid=${requestId}`);
+    logInfo("API request", { rid: requestId, method, path });
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
         try {
@@ -292,10 +293,19 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
                     await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
                     continue;
                 }
-                console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
+                logInfo("API response", {
+                    rid: requestId,
+                    outcome: "error",
+                    duration_ms: Date.now() - t0,
+                    error_code: `http_${resp.status}`,
+                });
                 throwApiError(resp.status, text, requestId);
             }
-            console.error(`${new Date().toISOString()} API <- ${resp.status} ${Date.now() - t0}ms rid=${requestId}`);
+            logInfo("API response", {
+                rid: requestId,
+                outcome: "ok",
+                duration_ms: Date.now() - t0,
+            });
             return JSON.parse(text);
         }
         catch (err) {

package/dist/tools/account.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall } from "../shared.js";
 export function registerAccountTool(server) {
-    server.tool("account", `Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.
 
 | Action | Use when |
 |--------|----------|

package/dist/tools/datasets.js

@@ -2,9 +2,10 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { gzipSync } from "node:zlib";
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, } from "../shared.js";
 export function registerDatasetsTool(server) {
-    server.tool("datasets", `Manage datasets: upload, preview, list, subset, add_expression, or delete.
+    registerAuditedTool(server, "datasets", `Manage datasets: upload, preview, list, subset, add_expression, or delete.
 
 | Action | Use when |
 |--------|----------|
@@ -19,8 +20,8 @@ export function registerDatasetsTool(server) {
 
 action=upload: PREFER file_path — server reads from workspace root (token-efficient; no file content in context). Use csv_data only for small inline pastes (e.g. <10KB). Returns dataset ID. Then use datasets(action=preview) before jobs(action=train_map).
 
-Step 0 (before upload): (1) CSV with header; one row per observation. (2) Columns you will use for training must be numeric (or datetime if you will use temporal extraction). (3) No NaNs/missing in those columns (engine does not impute). (4) Categoricals: encode (e.g. one-hot, label) or exclude — do not use raw categorical columns as training features; preview shows which columns are non-numeric. (5) Optional: if you plan to use transition_flow, sort rows chronologically before upload.
-Step 1 (after upload): Upload, then always datasets(action=preview) to verify column types and spot cyclics/datetime. Add derived columns with datasets(action=add_expression, dataset_id=..., name=..., expression=...); fix or subset before jobs(action=train_map).
+Step 0 (before upload): (1) CSV with header; one row per observation. (2) Columns you will use for training must be numeric (or datetime if you will use temporal extraction). (3) Complete-case path (jobs action=train_map): no NaNs in training columns. Sparse path (jobs action=train_impute): missing cells in training columns are OK — the job trains missSOM and returns dense imputed.csv; plain numeric columns only. (4) Categoricals: encode (e.g. one-hot, label) or exclude — do not use raw categorical columns as training features; preview shows which columns are non-numeric. (5) Optional: if you plan to use transition_flow, sort rows chronologically before upload.
+Step 1 (after upload): Upload, then always datasets(action=preview) to verify column types and spot cyclics/datetime. Add derived columns with datasets(action=add_expression, dataset_id=..., name=..., expression=...); choose train_map (complete-case) or train_impute (sparse matrix) before submit.
 
 action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before jobs(action=train_map) on an unfamiliar dataset.
 action=analyze: Pre-training analysis on numeric columns — Pearson correlation, autocorrelation periodicity scores, and column recommendations (train, consider_dropping, project_later, low_variance). Use to choose which columns to include in training and which to project onto the map after training.
@@ -42,7 +43,7 @@ action=delete: Remove a dataset and all S3 data permanently.
 
 BEST FOR: Tabular numeric data. CSV with header required.
 NOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.
-ESCALATION: If upload fails with column errors, open the file locally and verify the header row. If preview shows unexpected nulls, the user must clean the CSV before training.`, {
+ESCALATION: If upload fails with column errors, open the file locally and verify the header row. If preview shows nulls in training columns: use jobs(action=train_impute) for sparse data, or clean/subset for jobs(action=train_map).`, {
         action: z
             .enum(["upload", "preview", "analyze", "list", "subset", "delete", "add_expression", "reduce_spectral"])
             .describe("upload: add CSV; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression; reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
@@ -256,10 +257,12 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const considerDropping = rec.consider_dropping ?? [];
             const projectLater = rec.project_later ?? [];
             const lowVariance = rec.low_variance ?? [];
+            const periodicityCaveat = data.periodicity_caveat;
             const lines = [
                 `Pre-training analysis: ${data.name} (${data.dataset_id})`,
                 `${data.total_rows} rows × ${columns.length} numeric columns analyzed`,
                 ``,
+                ...(periodicityCaveat ? [`Note: ${periodicityCaveat}`, ``] : []),
                 `Column recommendations:`,
                 `  Train (use in jobs(action=train_map)): ${trainList.length ? trainList.join(", ") : "—"}`,
                 `  Consider dropping (highly correlated with another): ${considerDropping.length ? considerDropping.join(", ") : "—"}`,

package/dist/tools/explore_map.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, getResultsImagesToFetch, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 export const RESULTS_EXPLORER_URI = "ui://barsom/results-explorer";
 export const MAP_EXPLORER_URI = RESULTS_EXPLORER_URI;
@@ -164,13 +165,13 @@ export function registerExploreMapTool(server) {
         },
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
-    registerAppTool(server, "results_explorer", toolConfig, async ({ job_id }) => handleResultsExplorer(job_id));
+    registerAppTool(server, "results_explorer", toolConfig, async (args) => runMcpToolAudit("results_explorer", "default", args, () => handleResultsExplorer(String(args.job_id))));
     registerAppTool(server, "explore_map", {
         ...toolConfig,
         title: "Results Explorer",
         description: `${toolConfig.description} Deprecated alias for results_explorer — migrate configs to results_explorer.`,
-    }, async ({ job_id }) => handleResultsExplorer(job_id));
-    server.tool("_fetch_figure", "Host / MCP App use only — do NOT invoke from agent chat. Results Explorer calls this to load one raster figure as base64; agents should use results(action=get) or results_explorer instead.", {
+    }, async (args) => runMcpToolAudit("explore_map", "default", args, () => handleResultsExplorer(String(args.job_id))));
+    registerAuditedTool(server, "_fetch_figure", "Host / MCP App use only — do NOT invoke from agent chat. Results Explorer calls this to load one raster figure as base64; agents should use results(action=get) or results_explorer instead.", {
         job_id: z.string(),
         filename: z.string(),
     }, async ({ job_id, filename }) => {

package/dist/tools/feedback.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, API_URL, fetchWithTimeout, textResult } from "../shared.js";
 export function registerFeedbackTool(server) {
-    server.tool("send_feedback", `Send feedback or feature requests to Barivia developers (max 1400 characters, ~190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.`, { feedback: z.string().max(1400).describe("Feedback text (max 1400 characters)") }, async ({ feedback }) => {
+    registerAuditedTool(server, "send_feedback", `Send feedback or feature requests to Barivia developers (max 1400 characters, ~190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.`, { feedback: z.string().max(1400).describe("Feedback text (max 1400 characters)") }, async ({ feedback }) => {
         try {
             const data = await apiCall("POST", "/v1/feedback", { feedback });
             return textResult(data);

package/dist/tools/guide_barsom.js

@@ -1,3 +1,4 @@
+import { registerAuditedTool } from "../audit.js";
 import { fetchWorkflowGuideFromApi } from "../shared.js";
 /** Minimal orientation when the API is unreachable; full SOP lives on GET /v1/docs/workflow. */
 const OFFLINE_STUB = `## Offline / API unavailable
@@ -8,7 +9,7 @@ Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guid
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {
-    server.tool("guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt or training_prep.", {}, async () => {
+    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt or training_prep.", {}, async () => {
         const md = await fetchWorkflowGuideFromApi();
         if (md) {
             const text = "Plan-scoped workflow (from Barivia API). Text below reflects your API key / plan.\n\n" + md;

package/dist/tools/inference.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, pollUntilComplete, tryAttachImage } from "../shared.js";
 const PREDICT_PREVIEW_ROW_CAP = 10;
 /** One line per scored row when worker embedded `predictions_preview` (n_rows ≤ cap). Exported for tests. */
@@ -30,7 +31,7 @@ export function formatPredictPreviewLines(summary) {
     return lines;
 }
 export function registerInferenceTool(server) {
-    server.tool("inference", `Use a trained map as a persistent inference artifact — score data, annotate the source CSV, compare datasets, project columns, or generate a report manifest.
+    registerAuditedTool(server, "inference", `Use a trained map as a persistent inference artifact — score data, annotate the source CSV, compare datasets, project columns, or generate a report manifest.
 
 | Action | Use when | Timing |
 |--------|----------|--------|

package/dist/tools/jobs.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs.
 
@@ -29,10 +30,10 @@ ESCALATION (action=status):
 - failed → error message and optional failure_stage (e.g. preprocessing, training, metrics, visualization, upload) indicate which phase broke:
   - memory/allocation error: reduce batch_size or grid size and retrain
   - column missing: verify with datasets(action=preview)
-  - NaN error: user must clean the dataset
+  - NaN error on train_map: use jobs(action=train_impute) for sparse training columns, or clean the CSV for complete-case train_map
 
 action=train_map / train_siom_map: Submits a grid-map training job. Returns job_id — poll with jobs(action=status, job_id=...).
-action=train_impute: Submits missing-tolerant map training on a dataset with holes in the feature matrix. 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. Plain numeric columns only (no cyclic/temporal/categorical). Returns map artifacts plus imputed.csv (dense matrix). Same grid/epochs/backend params as train_map.
+action=train_impute: Submits missing-tolerant map training (accelerated missSOM / SIOM missSOM). Use when many cells are missing across training columns; use inference(impute_column) when you already have a complete-case map and need to fill one held-out column. Plain numeric columns only (no cyclic/temporal/categorical). Defaults: model=auto (SIOM on som_siom+ plans), cv_folds=5 → quality.csv (header feature). status returns progress_phase (ordering/convergence/cv/artifacts). High-dim auto policy: >40 features caps viz; >100 fast metrics; >200 GPU when entitled. Params: viz_mode, viz_top_components, emit_cell_uncertainty, quality_metrics. Artifacts: imputed.csv, imputation_mask.csv, optional imputation_uncertainty.csv. Completed train_impute job_id is a valid parent for inference(impute_column).
   Presets: quick | standard | refined | high_res — use preset=... for grid/epochs/batch defaults; call training_guidance for details.
   Presets refined/high_res may use GPU. On CPU-only hosts pass backend=cpu. API expects strings "cpu" | "gpu" | "gpu_graphs" (no colon). Future backends (e.g. non-CUDA) may be added under the same contract.
   normalize: "auto" (default) = scale only non-cyclic features; "all" = scale every feature. Use "auto" when using cyclic_features.
@@ -224,7 +225,7 @@ export function buildTrainMapParams(args, presets) {
     return { params, paramSummary, effectiveGrid };
 }
 export function registerJobsTool(server, description) {
-    server.tool("jobs", description, {
+    registerAuditedTool(server, "jobs", description, {
         action: z
             .enum(["status", "list", "compare", "cancel", "delete", "train_map", "train_impute", "train_siom_map", "train_floop_siom", "train_floop_chain", "batch_predict", "run_baseline_study"])
             .describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files; train_map: submit standard map training; train_siom_map: submit SIOM map training; train_floop_siom: submit FLooP-SIOM (preferred); train_floop_chain: deprecated alias for train_floop_siom; batch_predict: submit multiple predict jobs at once; run_baseline_study: auto-configure and train a baseline SOM"),
@@ -269,7 +270,7 @@ export function registerJobsTool(server, description) {
             }
             return v;
         }, z.union([z.number().int(), z.array(z.number().int()).length(2)]).optional()),
-        model: z.enum(["SOM", "RSOM", "SOM-SOFT", "RSOM-SOFT"]).optional().default("SOM"),
+        model: z.enum(["auto", "SOM", "SIOM", "RSOM", "SOM-SOFT", "RSOM-SOFT"]).optional(),
         periodic: z.boolean().optional().default(true),
         columns: z.array(z.string()).optional(),
         cyclic_features: z.array(z.object({
@@ -309,7 +310,13 @@ export function registerJobsTool(server, description) {
         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("train_impute only: held-out MAE/RMSE/R2 per column (0=off, 2..20) → quality.csv"),
+            .describe("train_impute only: held-out MAE/RMSE/R2 per column (0=off, default 5) → quality.csv"),
+        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("train_impute: write imputation_uncertainty.csv (pool_std per imputed cell)"),
         gamma: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
         gamma_f: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
         siom_decay: z.preprocess((v) => (v !== undefined && v !== null && typeof v === "string") ? parseFloat(v) : v, z.number().optional()),
@@ -366,7 +373,7 @@ export function registerJobsTool(server, description) {
             return { content: [{ type: "text", text: `Baseline study submitted. Job ID: ${jid}\nGrid size: ${side}x${side}\nNormalization: MAD\n\nPoll with jobs(action=status, job_id="${jid}") until complete, then retrieve with results(action=get, job_id="${jid}"). Optional: training_monitor(job_id="${jid}") for a visual panel—not required.` }] };
         }
         if (action === "train_map" || action === "train_siom_map" || action === "train_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, } = args;
+            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;
             let PRESETS = {};
             try {
                 PRESETS = await fetchTrainingPresets();
@@ -389,8 +396,14 @@ export function registerJobsTool(server, description) {
             }, PRESETS);
             if (action === "train_impute") {
                 params._job_type = "train_impute";
-                if (cv_folds !== undefined)
-                    params.cv_folds = cv_folds;
+                params.model = model ?? "auto";
+                params.cv_folds = cv_folds ?? 5;
+                if (viz_mode !== undefined)
+                    params.viz_mode = viz_mode;
+                if (viz_top_components !== undefined)
+                    params.viz_top_components = viz_top_components;
+                if (emit_cell_uncertainty !== undefined)
+                    params.emit_cell_uncertainty = emit_cell_uncertainty;
                 // Plain numeric path only — strip unsupported keys if caller passed them
                 delete params.cyclic_features;
                 delete params.temporal_features;
@@ -567,6 +580,10 @@ export function registerJobsTool(server, description) {
             const label = data.label != null && data.label !== "" ? String(data.label) : null;
             const jobDesc = label ? `Job ${label} (id: ${job_id})` : `Job ${job_id}`;
             let text = `${jobDesc}: ${status} (${progress.toFixed(1)}%)`;
+            const phase = data.progress_phase != null && data.progress_phase !== "" ? String(data.progress_phase) : null;
+            if (phase && status === "running") {
+                text += ` — phase: ${phase}`;
+            }
             if (status === "completed") {
                 text += ` | Results ready. Use results(action=get, job_id="${job_id}") to retrieve.`;
             }

package/dist/tools/results.js

@@ -1,9 +1,10 @@
 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, getResultsImagesToFetch, getCaptionForImage, mimeForFilename, } from "../shared.js";
 export function registerResultsTool(server) {
-    server.tool("results", `Retrieve, recolor, download, export, or run temporal flow on a completed map job.
+    registerAuditedTool(server, "results", `Retrieve, recolor, download, export, or run temporal flow on a completed map job.
 
 | Action | Use when | Sync/Async |
 |--------|----------|------------|
@@ -29,7 +30,7 @@ action=export: Structured data exports. Use export_type= to choose what to expor
   - export_type=nodes: per-node hit count + feature stats. Profile clusters and operating modes.
 
 action=download: Save figures to disk. Use so user can open, share, or version files locally.
-  - folder: e.g. "." or "./results". Interpreted relative to the client's current working directory (or workspace). Files are always written into a per-job subfolder (the job label, else the job_id) under this folder, so downloading several jobs into one folder never overwrites the shared filenames every job emits (e.g. summary.json).
+  - folder: e.g. "." or "./results". Interpreted relative to the client's current working directory (or workspace). Files are written into a per-job subfolder named job_type + label (or job_id) under this folder, so downloading several jobs (even with the same label across types) never overwrites shared filenames like summary.json.
   - figures: "all" (default) or array of filenames.
   - include_json: also save summary.json.
 
@@ -247,6 +248,44 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                         "Map-local pool estimates — not held-out validated predictions.",
                     ].join("\n") });
             }
+            else if (jobType === "train_impute") {
+                const imp = summary.imputation ?? {};
+                const cv = imp.cv_quality ?? null;
+                const policy = summary.effective_policy ?? {};
+                const hitStats = summary.hit_stats ?? {};
+                const siom = summary.siom ?? undefined;
+                const fmt = (v) => v !== null && v !== undefined ? Number(v).toFixed(4) : "N/A";
+                const lines = [
+                    `missSOM train+impute (${summary.model ?? imp.variant ?? "SOM"}) — ${resultsHeader}`,
+                    `Grid: ${(summary.grid ?? [0, 0]).join("×")} | Features: ${summary.n_features ?? 0} | Samples: ${summary.n_samples ?? 0}`,
+                    `Missing cells: ${imp.n_missing_cells ?? "?"} (${imp.missing_fraction !== undefined ? (Number(imp.missing_fraction) * 100).toFixed(1) + "%" : "?"})`,
+                    `Map quality — QE: ${fmt(summary.quantization_error)} | TE: ${fmt(summary.topographic_error)} | EV: ${fmt(summary.explained_variance)}`,
+                    `Observed-dimension QE: ${fmt(imp.observed_quantization_error)}`,
+                    ...(siom ? [`SIOM — utilization: ${fmt(siom.utilization)} | dead_fraction: ${fmt(siom.dead_fraction)} | siom_qe: ${fmt(siom.siom_qe)}`] : []),
+                    hitStats.grid_suggestion ? `Grid hint: ${String(hitStats.grid_suggestion)}` : "",
+                    ...(policy.auto_rules_applied && Array.isArray(policy.auto_rules_applied) && policy.auto_rules_applied.length > 0
+                        ? [`Auto policy: ${policy.auto_rules_applied.join(", ")} (${policy.viz_mode ?? "viz"}, metrics=${policy.quality_metrics ?? "?"})`]
+                        : []),
+                    cv ? [
+                        "",
+                        `Held-out imputation accuracy (cv_folds=${cv.cv_folds ?? "?"}, method=${cv.cv_method ?? "held_out_prototype_on_trained_map"}):`,
+                        cv.columns_sampled ? `  (sampled ${cv.columns_evaluated ?? "?"} columns for speed)` : "",
+                        cv.aggregate ? `  Aggregate MAE: ${fmt(cv.aggregate.mae)} | RMSE: ${fmt(cv.aggregate.rmse)}` : "",
+                        "  See quality.csv (header column: feature).",
+                    ].filter(Boolean).join("\n") : "\nHeld-out accuracy: skipped (cv_folds=0). Set cv_folds=5 to validate imputation.",
+                    "",
+                    `Artifacts: ${(summary.files ?? []).filter((f) => f !== "summary.json").join(", ")}`,
+                    "Next: results(action=download) for imputed.csv / quality.csv; inference(impute_column) with this job_id as parent for held-out columns.",
+                ].filter((l) => l !== "");
+                content.push({ type: "text", text: lines.join("\n") });
+                for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
+                    const cap = getCaptionForImage(name);
+                    if (cap)
+                        content.push({ type: "text", text: cap });
+                    await tryAttachImage(content, job_id, name);
+                    inlinedImages.add(name);
+                }
+            }
             else if (jobType === "reduce_spectral") {
                 const method = String(summary.method ?? "?");
                 const sourceCols = summary.source_columns ?? [];
@@ -581,7 +620,8 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             // Always namespace each job's files into its own subfolder so that
             // downloading multiple jobs (or job types) into the same folder never
             // overwrites the shared filenames every job emits (e.g. summary.json).
-            const jobSubfolder = (jobLabel ?? job_id).replace(/[^a-zA-Z0-9_.-]/g, "_");
+            // Prefix job_type so the same label on train vs predict/impute/flow jobs cannot collide.
+            const jobSubfolder = `${jobType}_${jobLabel ?? job_id}`.replace(/[^a-zA-Z0-9_.-]/g, "_");
             resolvedDir = path.join(resolvedDir, jobSubfolder);
             if (jobType === "render_variant" && summary.colormap) {
                 const colormapDir = String(summary.colormap).replace(/[^a-zA-Z0-9_-]/g, "_");

package/dist/tools/training_guidance.js

@@ -1,6 +1,7 @@
+import { registerAuditedTool } from "../audit.js";
 import { fetchTrainingGuidanceFromApi } from "../shared.js";
 export function registerTrainingGuidanceTool(server) {
-    server.tool("training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints; training_prep = interactive UI + submit_prepared_training. For full orientation and SOP, call guide_barsom_workflow first. Optional UIs: training_prep, results_explorer—not required; jobs + results suffice.", {}, async () => {
+    registerAuditedTool(server, "training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints; training_prep = interactive UI + submit_prepared_training. For full orientation and SOP, call guide_barsom_workflow first. Optional UIs: training_prep, results_explorer—not required; jobs + results suffice.", {}, async () => {
         const text = await fetchTrainingGuidanceFromApi();
         return { content: [{ type: "text", text }] };
     });

package/dist/tools/training_monitor.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { runMcpToolAudit } from "../audit.js";
 import { apiCall, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
 export const TRAINING_MONITOR_URI = "ui://barsom/training-monitor";
 function buildStructuredContent(job_id, data) {
@@ -20,7 +21,8 @@ export function registerTrainingMonitorTool(server) {
             job_id: z.string().describe("Training job ID to monitor"),
         },
         _meta: { ui: { resourceUri: TRAINING_MONITOR_URI } },
-    }, async ({ job_id }) => {
+    }, async (args) => runMcpToolAudit("training_monitor", "default", args, async () => {
+        const job_id = String(args.job_id);
         const data = (await apiCall("GET", `/v1/jobs/${job_id}`));
         const structuredContent = buildStructuredContent(job_id, data);
         const status = String(data.status ?? "unknown");
@@ -39,5 +41,5 @@ export function registerTrainingMonitorTool(server) {
             });
         }
         return structuredTextResult(structuredContent, text, content);
-    });
+    }));
 }

package/dist/tools/training_prep.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { registerAuditedTool, runMcpToolAudit } from "../audit.js";
 import { apiCall, fetchTrainingGuidanceFromApi, getClientSupportsMcpApps, getVizPort, structuredTextResult, } from "../shared.js";
 import { buildTrainMapParams, fetchTrainingPresets, } from "./jobs.js";
 import { attachTrainingReviewPayload, consumeTrainingReview, getTrainingReview, storeTrainingReview, } from "./training_review_store.js";
@@ -324,11 +325,11 @@ export function registerTrainingPrepTools(server) {
         description: "Interactive training prep UI + guarded submit (submit_prepared_training). Prep ladder: prepare_training prompt = narrative checklist; training_guidance tool = JSON/presets; this tool = visual review. Opens inline review of variables, transforms, encodings, and hyperparameters.",
         inputSchema: trainPrepSchema,
         _meta: { ui: { resourceUri: TRAINING_PREP_URI } },
-    }, async ({ dataset_id, ...args }) => {
+    }, async ({ dataset_id, ...args }) => runMcpToolAudit("training_prep", "default", { dataset_id, ...args }, async () => {
         const payload = await buildTrainingPrepPayload(dataset_id, args);
         return structuredTextResult(payload, undefined, buildTrainingPrepContent(payload));
-    });
-    server.tool("submit_prepared_training", "Submit a previously reviewed training-prep configuration. Requires an unexpired review token and explicit confirmation.", {
+    }));
+    registerAuditedTool(server, "submit_prepared_training", "Submit a previously reviewed training-prep configuration. Requires an unexpired review token and explicit confirmation.", {
         review_token: z.string().describe("Review token returned inside training_prep structured content."),
         explicit_confirm: z.boolean().describe("Must be true to submit the reviewed training job."),
     }, async ({ review_token, explicit_confirm }) => {

package/package.json

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