@barivia/barsom-mcp 0.7.16 → 0.9.0

package/README.md

@@ -29,6 +29,8 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 
 **Also available:** hosted HTTP MCP at **`https://mcp.barivia.se/mcp`** (same API key; no npm) for clients that support remote MCP.
 
+**Cursor / multi-account note:** Cursor's tool dispatcher resolves tools under a `serverIdentifier` (e.g. `user-barivia-bbb-maps`), which can differ from the key you wrote in `mcp.json` (e.g. `barivia-bbb-maps`). If a tool call fails with **"server does not exist"** or similar, list the resolved identifier with your client's tool inspector (`mcp.list-tools` or equivalent) and use that identifier — not the `mcp.json` key.
+
 **Future:** A **private npm org** scoped package is an option later (paid npm teams/orgs; users authenticate with npm, usually simpler than GitHub Packages for pure npm consumers).
 
 ## Environment Variables
@@ -40,14 +42,14 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 | `BARIVIA_WORKSPACE_ROOT` | No | `process.cwd()` or `PWD` | Directory for relative `file_path` and `save_to_disk`. In Cursor MCP, `process.cwd()` is often the MCP install dir — add `BARIVIA_WORKSPACE_ROOT` to your MCP config `env` with your project path (e.g. `/home/user/myproject`). Absolute paths and `file://` URIs work without it. |
 | `BARIVIA_FETCH_TIMEOUT_MS` | No | `30000` | Per-request HTTP timeout (ms) to the API. Increase (e.g. `120000`) on slow networks or when the API does long-running work. Large dataset uploads use a separate longer timeout internally. |
 | `BARIVIA_VIZ_PORT` | No | OS-assigned | When the client has no MCP Apps support, the proxy may start a local viz server on `127.0.0.1`; set a fixed port if you need stable bookmark URLs. |
-| `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | No | unset | If `1` or `true`, `datasets(upload)` **file_path** and `file://` paths must resolve under the MCP workspace root (same rule as relative paths). Default allows **absolute** paths anywhere on the machine the client can read — treat that as **high trust** (same API key can already exfiltrate org data via the API). |
+| `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | No | `1` (enabled) | File uploads are constrained to the MCP workspace root by default. Set to `0` or `false` to allow absolute paths anywhere on the machine (high trust). **Changed in v0.x:** previously defaulted to off; now on for security. If uploads fail with "paths outside the workspace are disabled", either set `BARIVIA_WORKSPACE_ROOT` to cover your data directory, or opt out with `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0`. |
 
 Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` / `BARSOM_WORKSPACE_ROOT` are also accepted as fallbacks.
 
 ### Trust model (who are we trusting?)
 
 - **API key** — Anyone with your key can access your tenant on the Barivia API like any other HTTP client. The proxy does not add a separate authorization layer.
-- **Local machine** — The process runs with **your** OS user. It can read files you pass as `file_path` (and, by default, **any** absolute path). Prefer `BARIVIA_WORKSPACE_ROOT` + project-relative paths; use **`BARIVIA_ENFORCE_WORKSPACE_SANDBOX=1`** when you want uploads constrained to the workspace.
+- **Local machine** — The process runs with **your** OS user. File uploads are now sandboxed to the workspace root by default (`BARIVIA_ENFORCE_WORKSPACE_SANDBOX=1`). Set `BARIVIA_WORKSPACE_ROOT` to your project directory; use `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0` only if you need unrestricted absolute-path access.
 - **Logs** — stderr may include API paths and tool activity; do not log secrets in MCP client configs.
 
 **Supported stack:** Node **18+** (see `engines` in `package.json`). Built with `@modelcontextprotocol/sdk` **^1.x** — if a major MCP client upgrade breaks tools, check SDK release notes alongside this package version.
@@ -88,6 +90,7 @@ Call at the **start of mapping work** (or when the user asks what the MCP can do
 | `list` | Finding dataset IDs |
 | `subset` | Creating a filtered/sliced copy (row_range, filter conditions) |
 | `add_expression` | Add a derived column from an expression (formula → new column on the dataset) |
+| `reduce_spectral` | Pre-training reducer for long ordered numeric blocks (spectra, time series, sensor fingerprints, gene panels). Methods: **pca** (top-k principal components), **log_sample** (k columns at log-spaced indices — scattering, audio bands), **uniform_sample** (k columns at evenly-spaced indices — regularly-sampled time series), **stats** (6 fixed per-row summary columns). All produce one feature vector per row; appends derived columns to the dataset. |
 | `delete` | Removing a dataset |
 
 ### `jobs(action)`
@@ -123,8 +126,8 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 | Action | Output | Timing |
 |--------|--------|--------|
-| `predict` | predictions.csv: per-row bmu_x/y, cluster_id, quantization_error, potential_anomaly (QE > 95th pct); summary includes qe_p95 | 5–120s |
-| `enrich` | enriched.csv: training data + bmu_x/y/node_index/cluster_id | 5–60s |
+| `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 |
 | `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 |
@@ -153,6 +156,16 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 When the client does not advertise MCP Apps support, the proxy starts **`viz-server`** on **`127.0.0.1`** (localhost-only). Tool responses can include `http://127.0.0.1:PORT/viz/...` links. See **Local viz fallback** under Environment Variables.
 
+#### Choosing where to view results
+
+The right viewer depends on **(MCP App support)** **and** **(can the human reach the proxy's `127.0.0.1`)** — not on whether the agent is "text" or "GUI".
+
+| Path | When to use | Caveats |
+|------|-------------|---------|
+| **Embedded MCP App** (`ui://barsom/results-explorer`) | Client supports MCP Apps (Cursor, Claude Desktop with App support). Preferred default. | None of the topology issues below — transported over the MCP channel. Works for local proxy, remote SSH proxy, or container. |
+| **Localhost `viz-server` link** | MCP Apps unsupported AND the human user is on the same host as the proxy (typical local Cursor + local stdio proxy). | Ephemeral port (lost on proxy restart). **Unreachable** when the proxy runs on a remote SSH host while the user is elsewhere, in a container with no port forwarding, or behind a strict host firewall. Pure text agents on the same host CAN use this path — the user just clicks the link. |
+| **`results(action=get)` text-only path** | Always works. Use when (a) the agent is headless / autonomous (no human to click anything) or (b) proxy and user are on different hosts and MCP Apps is unsupported. With **`figures="none"`** it's also the leanest path for parameter sweeps and LLM clients (no image payloads). | Returns metrics text and inline images via MCP content; never starts a server. |
+
 ### Migration notes
 
 - **`explore_map` → `results_explorer`:** Update Cursor, Claude Desktop, or other MCP configs that still reference `explore_map`. The alias remains for backward compatibility.

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as n,RESOURCE_MIME_TYPE as s}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as i}from"./viz-server.js";import{API_KEY as a,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as f,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as g}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as y}from"./tools/account.js";import{registerInferenceTool as w}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as P,TRAINING_PREP_URI as I}from"./tools/training_prep.js";import{registerTrainingMonitorTool as k,TRAINING_MONITOR_URI as A}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as T}from"./prepare_training_prompt.js";a||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const C=new e({name:"analytics-engine",version:"0.7.16",instructions:"# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `jobs(train_map)`, `jobs(train_siom_map)`, or `jobs(train_floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool). Then `jobs(compare)`, `results(download/recolor/transition_flow)`, or `inference` as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool map (compact)\n\n| Area | Tool | Notes |\n|------|------|--------|\n| Data | `datasets` | upload, preview, analyze, list, subset, add_expression, delete |\n| Jobs | `jobs` | train_map, train_siom_map, train_floop_siom (entitled), status, list, compare, cancel, delete, batch_predict, run_baseline_study; `train_floop_chain` = deprecated alias for train_floop_siom |\n| Results | `results` | get, export, download, recolor (async), transition_flow (async; time-ordered rows only) |\n| Inference | `inference` | predict, enrich, compare, project_columns, report |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow` | orientation + SOP |\n| Parameters | `training_guidance` | presets and field hints (API-scoped) |\n| Prep | `prepare_training` prompt, `training_prep` + `submit_prepared_training` | checklist / interactive UI |\n| Explore | `results_explorer`, `training_monitor` | optional MCP Apps; `explore_map` = deprecated alias of `results_explorer`; `jobs(status)` and `results(get)` suffice without them |\n| Other | `send_feedback` | only after user agrees |\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions, `results(recolor)`, `results(transition_flow)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Slow networks: users can raise `BARIVIA_FETCH_TIMEOUT_MS`.\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints; `training_prep` = UI + guarded submit. Do not guess tiers or FLooP entitlement.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `recolor`, `transition_flow`, or `project_columns`, use the **new** `job_id` returned for follow-up `results` if applicable."});n(C,b,b,{mimeType:s},async()=>{const e=await c("results-explorer");return{contents:[{uri:b,mimeType:s,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(C,I,I,{mimeType:s},async()=>{const e=await c("training-prep");return{contents:[{uri:I,mimeType:s,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(C,A,A,{mimeType:s},async()=>{const e=await c("training-monitor");return{contents:[{uri:A,mimeType:s,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),j(C),h(C),P(C),k(C),u(C),f(C,_),g(C),y(C),w(C),v(C),x(C),C.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool).","","**Key tools:** `datasets` (data), `jobs` (train/poll/compare/…), `results` (get/download/export/recolor/transition_flow), `inference` (predict/enrich/compare/project_columns/report), `account` (status/credits/queue).","","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints) · `training_prep` + `submit_prepared_training` (interactive UI).","","**Optional UI:** `results_explorer`, `training_monitor` — nice for browsing; not required if you use `results` + `jobs(status)`.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `transition_flow` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),C.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints; training_prep tool = interactive UI + submit_prepared_training.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await T(e)}}]}));const M=new t;(async function(){try{const e=await i(l,p,c);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=C.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(s))},await C.connect(M)})().catch(console.error);
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as n,RESOURCE_MIME_TYPE as s}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as a}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d,CLIENT_VERSION as u}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerJobsTool as g,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as w}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as v}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as k}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as O}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as S}from"./prepare_training_prompt.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const A=new e({name:"analytics-engine",version:u,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `jobs(train_map)`, `jobs(train_siom_map)`, or `jobs(train_floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool). Then `jobs(compare)`, `results(download/recolor/transition_flow)`, or `inference` as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool map (compact)\n\n| Area | Tool | Notes |\n|------|------|--------|\n| Data | `datasets` | upload, preview, analyze, list, subset, add_expression, reduce_spectral (pca/log_sample/uniform_sample/stats for long ordered numeric blocks), delete |\n| Jobs | `jobs` | train_map, train_siom_map, train_floop_siom (entitled), status, list, compare, cancel, delete, batch_predict, run_baseline_study; `train_floop_chain` = deprecated alias for train_floop_siom |\n| Results | `results` | get (figures="none" for metrics-only), export, download, recolor (async), transition_flow (async; time-ordered rows only) |\n| Inference | `inference` | predict (regime-aware; output="compact"|"annotated"), impute_column (neighbor-pool fill for a non-training column), compare, project_columns, report |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow` | orientation + SOP |\n| Parameters | `training_guidance` | presets and field hints (API-scoped) |\n| Prep | `prepare_training` prompt, `training_prep` + `submit_prepared_training` | checklist / interactive UI |\n| Explore | `results_explorer`, `training_monitor` | optional MCP Apps; `explore_map` = deprecated alias of `results_explorer`; `jobs(status)` and `results(get)` suffice without them |\n| Other | `send_feedback` | only after user agrees |\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions, `results(recolor)`, `results(transition_flow)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Slow networks: users can raise `BARIVIA_FETCH_TIMEOUT_MS`.\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints; `training_prep` = UI + guarded submit. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `recolor`, `transition_flow`, or `project_columns`, use the **new** `job_id` returned for follow-up `results` if applicable.'});n(A,y,y,{mimeType:s},async()=>{const e=await c("results-explorer");return{contents:[{uri:y,mimeType:s,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(A,k,k,{mimeType:s},async()=>{const e=await c("training-prep");return{contents:[{uri:k,mimeType:s,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(A,O,O,{mimeType:s},async()=>{const e=await c("training-monitor");return{contents:[{uri:O,mimeType:s,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),v(A),h(A),I(A),M(A),f(A),g(A,_),b(A),w(A),j(A),P(A),x(A),A.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool).","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `jobs` (train/poll/compare/…; train_map accepts an optional `label` for readable compare rows), `results` (get/download/export/recolor/transition_flow; figures="none" for metrics-only), `inference` (predict; impute_column for topology-neighbor pool fill; compare; project_columns; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints) · `training_prep` + `submit_prepared_training` (interactive UI).","","**Optional UI:** `results_explorer`, `training_monitor` — nice for browsing; not required if you use `results` + `jobs(status)`.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `transition_flow` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),A.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints; training_prep tool = interactive UI + submit_prepared_training.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await S(e)}}]}));const T=new t;(async function(){try{const e=await a(l,p,c);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=A.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(s))},await A.connect(T)})().catch(console.error);

package/dist/shared.js

@@ -14,6 +14,12 @@ export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY
 export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "30000", 10);
 export const MAX_RETRIES = 2;
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/**
+ * Single source of truth for the proxy version. Sent to the API as
+ * 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.9.0";
 /** 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). */
@@ -105,8 +111,10 @@ export function sandboxPath(userPath, root) {
     return resolved;
 }
 function enforceWorkspaceSandboxUpload() {
-    const v = process.env.BARIVIA_ENFORCE_WORKSPACE_SANDBOX ?? "";
-    return v === "1" || v.toLowerCase() === "true";
+    const v = process.env.BARIVIA_ENFORCE_WORKSPACE_SANDBOX ?? "1";
+    if (v === "0" || v.toLowerCase() === "false")
+        return false;
+    return true;
 }
 /**
  * Resolves file_path for dataset upload. Security: auth before read, generic errors, reject "..".
@@ -254,12 +262,18 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
         Authorization: `Bearer ${API_KEY}`,
         "Content-Type": contentType,
         "X-Request-ID": requestId,
+        "X-Barsom-Client-Version": CLIENT_VERSION,
         ...extraHeaders,
     };
     let serializedBody;
     if (body !== undefined) {
-        serializedBody =
-            contentType === "application/json" ? JSON.stringify(body) : String(body);
+        if (body instanceof Uint8Array) {
+            serializedBody = body; // pre-encoded bytes (e.g. gzipped CSV upload)
+        }
+        else {
+            serializedBody =
+                contentType === "application/json" ? JSON.stringify(body) : String(body);
+        }
     }
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     const t0 = Date.now();
@@ -508,6 +522,9 @@ export async function tryAttachImage(content, jobId, filename) {
 }
 /** Resolve get_results figures param to list of image filenames to fetch. */
 export function getResultsImagesToFetch(jobType, summary, figures, includeIndividual) {
+    // Metrics-only mode: skip every image fetch (sweeps and LLM clients).
+    if (figures === "none")
+        return [];
     const ext = summary.output_format ?? "pdf";
     if (jobType === "transition_flow") {
         const lag = summary.lag ?? 1;

package/dist/tools/datasets.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { gzipSync } from "node:zlib";
 import { z } from "zod";
 import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, } from "../shared.js";
 export function registerDatasetsTool(server) {
@@ -13,6 +14,7 @@ export function registerDatasetsTool(server) {
 | list | Finding dataset IDs for train_map, preview, or subset — see all available datasets |
 | subset | Creating a filtered/sliced view without re-uploading the full CSV |
 | add_expression | Add a computed column from an expression (same as project(expression) without project_onto_job) — dataset_id + name + expression |
+| reduce_spectral | Collapse a long ordered numeric block (e.g. 1000-point spectrum, time series, sensor fingerprint) into a small per-row feature set so the SOM can train on signal-dense features. Methods: pca, log_sample, uniform_sample, stats. |
 | delete | Cleaning up after experiments or freeing the dataset slot |
 
 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).
@@ -30,14 +32,20 @@ action=subset: Create a new dataset from a subset of an existing one. Requires n
     Examples: { column: "region", op: "eq", value: "Europe" } | { column: "age", op: "between", value: [18, 65] }
   - Combine row_range + filters to slice both rows and values.
   - Single filter object is also accepted (auto-wrapped).
+action=reduce_spectral: Run a pre-training reducer over an ordered block of numeric columns. All four methods produce one feature vector per row (rows in = rows out; only the column dimension is collapsed) and append derived columns to the dataset. Choose by data shape:
+  - pca:            top-k principal components — general first try when many columns are correlated (spectroscopy, gene panels, sensor arrays). Returns explained_variance_ratio.
+  - log_sample:     keep k columns at log-spaced indices — SAXS/WAXS & powder diffraction, log-frequency / octave-like audio, attenuation vs wavelength (UV–Vis–IR stacks), depth profiling, chromatography retention ladders — anywhere column order is exponential, logarithmic, or perceptually log-spaced.
+  - uniform_sample: keep k columns at evenly-spaced indices — regularly-sampled time series, frame-by-frame features, evenly-binned histograms.
+  - stats:          6 fixed per-row statistics (mean, std, min, max, skew, integral) — cheap baseline for any sequenced numeric block; k is ignored.
+  Required params: name (prefix for derived columns), method, columns_block (ordered source column names ≥ 2), k (≥ 1, < length(columns_block); ignored for stats).
 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.`, {
         action: z
-            .enum(["upload", "preview", "analyze", "list", "subset", "delete", "add_expression"])
-            .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"),
+            .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"),
         name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
         file_path: z.string().optional().describe("Path to local CSV (PREFERRED): absolute path, file:// URI, or relative to workspace root. Token-efficient; server reads file."),
         csv_data: z.string().optional().describe("Inline CSV string for small pastes only (<10KB). Avoid for large files — use file_path instead to avoid token explosion."),
@@ -81,7 +89,21 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
         })
             .optional()
             .describe("action=add_expression: evaluation options (missing, window for rolling)"),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options }) => {
+        method: z
+            .enum(["pca", "log_sample", "uniform_sample", "stats"])
+            .optional()
+            .describe("action=reduce_spectral: pca = top-k principal components (general first try); log_sample = k columns at log-spaced indices (scattering, audio bands, attenuation); uniform_sample = k columns at evenly-spaced indices (regularly-sampled time series); stats = 6 fixed per-row summary columns (mean, std, min, max, skew, integral; k ignored)"),
+        columns_block: z
+            .array(z.string())
+            .optional()
+            .describe("action=reduce_spectral: ordered list of source column names representing the block (≥ 2; ≥ k+1 for non-stats methods)"),
+        k: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("action=reduce_spectral: output dimensionality. Required for pca/log_sample/uniform_sample; ignored for stats."),
+    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, method, columns_block, k }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("datasets(upload) requires name");
@@ -93,10 +115,17 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 if (ext !== ".csv" && ext !== ".tsv") {
                     throw new Error("Only .csv and .tsv files can be uploaded as datasets.");
                 }
+                const MAX_UPLOAD_BYTES = 256 * 1024 * 1024; // 256 MB (gzip keeps the wire payload small)
                 try {
+                    const stat = await fs.stat(resolved);
+                    if (stat.size > MAX_UPLOAD_BYTES) {
+                        throw new Error(`File too large (${(stat.size / 1024 / 1024).toFixed(1)} MB). Maximum upload size is ${MAX_UPLOAD_BYTES / 1024 / 1024} MB.`);
+                    }
                     body = await fs.readFile(resolved, "utf-8");
                 }
-                catch {
+                catch (err) {
+                    if (err instanceof Error && err.message.includes("too large"))
+                        throw err;
                     throw new Error(`File not accessible at resolved path. file_path is relative to workspace root. ` +
                         `Set BARIVIA_WORKSPACE_ROOT in your MCP config env if needed (current: ${await getWorkspaceRootAsync(server)}).`);
                 }
@@ -107,10 +136,19 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             else {
                 throw new Error("datasets(upload) requires file_path or csv_data. Prefer file_path for token efficiency.");
             }
-            const data = (await apiCall("POST", "/v1/datasets", body, {
+            // gzip large CSVs to keep the wire payload (and the API's compressed-body
+            // cap) small; the API transparently decompresses. Small bodies stay plain.
+            const GZIP_THRESHOLD = 1024 * 1024; // 1 MB
+            const uploadHeaders = {
                 "X-Dataset-Name": name,
                 "Content-Type": "text/csv",
-            }, UPLOAD_DATASET_TIMEOUT_MS));
+            };
+            let uploadBody = body;
+            if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
+                uploadBody = gzipSync(Buffer.from(body, "utf-8"));
+                uploadHeaders["Content-Encoding"] = "gzip";
+            }
+            const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null)
                 data.suggested_next_step = `Suggested next step: datasets(action=preview, dataset_id=${id}) to inspect columns before training.`;
@@ -265,7 +303,8 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const periodicStrong = periodicity.filter((p) => p.dominant_score > 0.4);
             if (periodicStrong.length > 0) {
                 const lags = [...new Set(periodicStrong.map((p) => p.dominant_lag))].sort((a, b) => a - b);
-                nextSteps.push(`Columns show periodic behavior at lags ${lags.join(", ")}. Consider cyclic_features or temporal_features with matching periods.`);
+                nextSteps.push(`Note: periodicity is computed on row order. If your CSV is not sorted by time, ignore lag-based suggestions; only use cyclic_features when the column is genuinely cyclic (e.g. hour, month, angle).`);
+                nextSteps.push(`Columns show periodic behavior at lags ${lags.join(", ")} (assuming row order is meaningful). Consider cyclic_features or temporal_features with matching periods.`);
                 nextSteps.push(`For datetime columns: run datasets(action=preview) for temporal_suggestions; match lags (e.g. 365→day_of_year, 12→month, 7→day_of_week, 24→hour_of_day) to choose which temporal components to extract.`);
             }
             nextSteps.push(`Then call jobs(action=train_map, dataset_id=${dataset_id}, columns=[...], ...).`);
@@ -311,6 +350,58 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 content: [{ type: "text", text: `datasets(add_expression) job ${deriveJobId} submitted. Poll with jobs(action=status, job_id="${deriveJobId}").` }],
             };
         }
+        if (action === "reduce_spectral") {
+            if (!dataset_id)
+                throw new Error("datasets(reduce_spectral) requires dataset_id");
+            if (!name)
+                throw new Error("datasets(reduce_spectral) requires name (prefix for derived columns)");
+            if (!method)
+                throw new Error("datasets(reduce_spectral) requires method: pca | log_sample | uniform_sample | stats");
+            if (!columns_block || columns_block.length < 2) {
+                throw new Error("datasets(reduce_spectral) requires columns_block: ordered array of ≥ 2 source column names");
+            }
+            if (method !== "stats" && (k === undefined || k < 1)) {
+                throw new Error(`datasets(reduce_spectral) requires k ≥ 1 for method '${method}'`);
+            }
+            if (method !== "stats" && k !== undefined && k >= columns_block.length) {
+                throw new Error(`datasets(reduce_spectral) requires k < length(columns_block); got k=${k}, columns_block=${columns_block.length}`);
+            }
+            const body = { name, method, columns: columns_block };
+            if (method !== "stats")
+                body.k = k;
+            const data = (await apiCall("POST", `/v1/datasets/${dataset_id}/reduce_spectral`, body));
+            const reduceJobId = data.id;
+            const poll = await pollUntilComplete(reduceJobId, 120_000);
+            if (poll.status === "completed") {
+                const results = (await apiCall("GET", `/v1/results/${reduceJobId}`));
+                const summary = (results.summary ?? {});
+                const outCols = summary.output_columns ?? [];
+                const sourceCols = summary.source_columns ?? [];
+                const lines = [
+                    `Spectral reduction complete (${method}) — job: ${reduceJobId}`,
+                    `Source: ${sourceCols.length} columns → Output: ${outCols.length} columns appended to dataset ${dataset_id}`,
+                    `New columns: ${outCols.join(", ")}`,
+                ];
+                if (method === "pca") {
+                    const ev = summary.explained_variance_ratio;
+                    const evTotal = summary.explained_variance_total;
+                    if (ev)
+                        lines.push(`Explained variance per component: [${ev.map((v) => v.toFixed(3)).join(", ")}] | total: ${evTotal !== undefined ? evTotal.toFixed(3) : "N/A"}`);
+                }
+                else if (method === "log_sample" || method === "uniform_sample") {
+                    const idxs = summary.selected_indices;
+                    if (idxs) {
+                        lines.push(`Selected source-column indices (1-based): [${idxs.join(", ")}]`);
+                    }
+                }
+                lines.push(`Use datasets(action=preview, dataset_id=${dataset_id}) to inspect the new columns, then jobs(action=train_map, dataset_id=${dataset_id}, columns=[..., "${outCols[0] ?? ""}", …]) to train on the reduced features.`);
+                return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+            }
+            if (poll.status === "failed") {
+                return { content: [{ type: "text", text: `datasets(reduce_spectral) job ${reduceJobId} failed: ${poll.error ?? "unknown error"}` }] };
+            }
+            return { content: [{ type: "text", text: `datasets(reduce_spectral) job ${reduceJobId} submitted. Poll with jobs(action=status, job_id="${reduceJobId}").` }] };
+        }
         if (action === "subset") {
             if (!dataset_id)
                 throw new Error("datasets(subset) requires dataset_id");

package/dist/tools/inference.js

@@ -1,46 +1,100 @@
 import { z } from "zod";
 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. */
+export function formatPredictPreviewLines(summary) {
+    const nRows = Number(summary.n_rows ?? 0);
+    if (nRows < 1 || nRows > PREDICT_PREVIEW_ROW_CAP)
+        return [];
+    const preview = summary.predictions_preview;
+    if (!Array.isArray(preview) || preview.length === 0)
+        return [];
+    const lines = ["Per-row summary (same columns as predictions.csv):"];
+    for (const raw of preview) {
+        const p = raw;
+        const rid = String(p.row_id ?? "?");
+        const bx = p.bmu_x !== undefined ? Number(p.bmu_x).toFixed(2) : "?";
+        const by = p.bmu_y !== undefined ? Number(p.bmu_y).toFixed(2) : "?";
+        const node = p.bmu_node_index ?? "?";
+        const cl = p.cluster_id ?? "?";
+        if (p.quantization_error !== undefined) {
+            const qe = Number(p.quantization_error).toFixed(4);
+            const anom = p.potential_anomaly === true ? "yes" : "no";
+            lines.push(`  row ${rid}: BMU (${bx},${by}) node=${node} cluster=${cl} QE=${qe} anomaly=${anom}`);
+        }
+        else {
+            // regime=training: QE columns are intentionally omitted (training-set fit, not generalisation)
+            lines.push(`  row ${rid}: BMU (${bx},${by}) node=${node} cluster=${cl}`);
+        }
+    }
+    return lines;
+}
 export function registerInferenceTool(server) {
-    server.tool("inference", `Use a trained map as a persistent inference artifact — score new data, enrich the training CSV, compare datasets, or generate a PDF report.
+    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.
 
 | Action | Use when | Timing |
 |--------|----------|--------|
-| predict | Scoring new/unseen observations against the trained map | 5–120s |
-| enrich | Appending BMU coordinates + cluster_id to the original training CSV | 5–60s |
+| predict | Scoring rows against the trained map (new data OR the training set itself) | 5–120s |
+| impute_column | Fill a numeric column (not used in training) by pooling observed values on the BMU plus topology neighbors (typically 6 on hex; periodic maps wrap) | 5–120s |
 | compare | Comparing hit distributions of a second dataset against training (drift, A/B) | 30–120s |
 | project_columns | Project one or more dataset columns onto the map (component planes); dataset can be training set or partial-feature set | 10–90s |
 | report | Get a report manifest (artifact keys + URLs) to build your own report in Quarto/Notebook/script | Immediate (sync) |
 
-Sync/async: predict, enrich, and compare are all async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
-Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict → predictions.csv; enrich → enriched.csv; compare → density-diff figure (e.g. density_diff.png).
+Sync/async: predict, impute_column, and compare are async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
+Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict (output="compact") → predictions.csv; predict (output="annotated") → annotated.csv; impute_column → imputed.csv; compare → density-diff figure (e.g. density_diff.png).
 report is the only synchronous inference action — returns manifest immediately; no job to poll.
 NOT FOR: Retraining or changing the map — all actions treat the trained map as frozen.
 ESCALATION: If any action returns "missing column", verify column names with datasets(action=preview). Column names are case-sensitive and must match the training feature set exactly.
 
-action=predict: Returns predictions.csv with row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly (true when QE > 95th percentile; summary includes qe_p95 for the threshold). Use potential_anomaly for downstream anomaly filtering.
-  Dataset/batch rows must use the same schema as training (including cyclic-expanded columns, e.g. key_cos, key_sin not raw key). For a single inline row only, the proxy can use the stateless model endpoint instead: raw categorical strings are allowed for baseline categorical_features models, and raw cyclic inputs are expanded from training config. High QE = row is far from its nearest prototype = potential anomaly. Accepts dataset_id OR inline rows (≤500).
-action=enrich: Uses the job's training dataset; do not pass dataset_id. Returns enriched.csv — original training CSV + bmu_x, bmu_y, bmu_node_index, cluster_id. When complete, get enriched.csv via results(action=download, job_id=<returned_enrich_job_id>). Filename: enriched.csv.
-action=compare: dataset_id must refer to a dataset with the same feature set as the training data (same column names and preprocessing, including cyclic expansion). A = training dataset (the map was trained on it). B = cohort to compare (the dataset_id you pass). Density-diff: positive = B gained vs A; negative = A had more. Using the same dataset as A and B yields a flat diff. Returns density-diff heatmap (e.g. density_diff.png).
+action=predict: Score rows against the trained map.
+  Inputs (one of):
+    - dataset_id (default = parent training job's dataset). Use a different dataset for new/unseen data; omit it (or pass the training dataset_id) to score the training set itself.
+    - rows (≤500 inline). Always treated as new data.
+  Output style (output param, default "compact"):
+    - "compact"   → predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id [, quantization_error, potential_anomaly]).
+    - "annotated" → annotated.csv (full source CSV with bmu_x, bmu_y, bmu_node_index, cluster_id appended). Requires a dataset (no inline rows).
+  Regime auto-detected:
+    - If the resolved dataset matches the parent training dataset, regime="training" and QE / qe_p95 / potential_anomaly fields are omitted from the compact output. QE on training data is fitting error, not a generalisation metric, and the p95 anomaly flag would be circular. Use a held-out dataset for quality assessment.
+    - Otherwise regime="new" and the full QE columns are returned.
+  Schema rules: dataset / batch rows must match the trained feature set including cyclic-expanded columns (e.g. key_cos, key_sin, not raw key). For a single inline row, the proxy uses the stateless model endpoint — raw categorical strings are allowed for baseline categorical_features models, and raw cyclic inputs are expanded from training config.
+  Routing: prefer dataset_id for many rows or whenever the map uses irregular SIOM / GeneralTopology layouts — the async worker path is the supported batch scorer. Single-row rows take a fast stateless path that may return invalid_inference_input on some topologies; if so, retry with dataset_id (a one-row dataset is fine). FLooP-SIOM: use dataset_id predict first.
+  When the scored set has at most ${PREDICT_PREVIEW_ROW_CAP} rows, completed responses include a short per-line preview in the tool text for chat agents.
+
+action=impute_column: Map-local imputation as read-only post-processing (the trained map is frozen; not a held-out validity claim). Requires dataset_id + target_column. The dataset must contain all training features (same names and cyclic expansion as predict) plus the target column. target_column must NOT have been in jobs(train_map) columns — train without it, then impute. Pools finite target values from rows whose BMUs lie on this row's BMU and its topology neighbors (BMU + neighbors, often 7 nodes on hex interior; fewer on borders if the parent map is non-periodic; periodic hex wraps), aggregated neighbourhood-distance-weighted by default (weighting="distance" — closer nodes count more; weighting="uniform" for a flat pool). Excludes the current row from its own pool. only_missing (default true): keep observed values. impute_aggregation: mean or median of the pool. Optional cv_folds (2-20) writes quality.csv (held-out MAE/RMSE/R2); target_column_kind handles categorical (mode) / cumulative (warns). Output imputed.csv: row_id, target_original, target_imputed, impute_source (observed | imputed | insufficient_data), bmu_node_index, n_patch_nodes, n_pool_rows, pool_std, pool_p5, pool_p95.
+
+action=compare: dataset_id must refer to a dataset with the same feature set as training (same column names and preprocessing, including cyclic expansion). A = training dataset; B = cohort to compare. Density-diff: positive = B gained vs A; negative = A had more. Returns density-diff heatmap (e.g. density_diff.png).
 action=project_columns: Project one or more columns from a dataset onto the trained map. Pass dataset_id (the dataset containing the columns) and columns (array of column names). Uses cached BMUs when dataset is the training set; supports partial-feature mapping when dataset has only a subset of training features. Returns one component plane image per column. Get files via results(action=download, job_id=<returned_job_id>).
-action=report: Returns a report manifest for the given job_id (job must be completed). Includes figure_manifest (logical names → filenames), download_urls for all artifacts, cluster_summary when available, and summary metrics. Stakeholder report PDF (if generated) is available via results(action=download, job_id=<training_job_id>), filename e.g. report.pdf. Use results(action=get) and this manifest to fetch figures/data and render your own PDF (e.g. Quarto, Jupyter). See docs: BUILD_YOUR_OWN_REPORT.md.`, {
+action=report: Returns a report manifest for the given job_id (job must be completed). Includes figure_manifest (logical names → filenames), download_urls for all artifacts, cluster_summary when available, and summary metrics. Stakeholder report PDF (if generated) is available via results(action=download, job_id=<training_job_id>), filename e.g. report.pdf.`, {
         action: z
-            .enum(["predict", "enrich", "compare", "project_columns", "report"])
-            .describe("predict: score new data; enrich: annotate training CSV with BMU coords; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report"),
+            .enum(["predict", "impute_column", "compare", "project_columns", "report"])
+            .describe("predict: score rows; impute_column: topology-neighbor pool imputation for a column not in training; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report."),
         job_id: z.string().describe("Job ID of a completed map training job"),
-        dataset_id: z.string().optional().describe("action=predict/compare/project_columns: Dataset ID. predict=input data to score; compare=dataset B; project_columns=dataset with columns to project."),
+        dataset_id: z.string().optional().describe("action=predict/impute_column/compare/project_columns: Dataset ID. predict=data to score (defaults to the training dataset when omitted); impute_column=dataset with training features + target_column; compare=dataset B; project_columns=dataset with columns to project."),
         columns: z.array(z.string()).optional().describe("action=project_columns: column names to project onto the map (must exist in the dataset)."),
         rows: z.array(z.record(z.string(), z.union([z.number(), z.string()]))).optional().describe("action=predict: inline rows to score (max 500). For a single inline row, raw categorical strings are allowed for baseline categorical_features models. Batch rows should remain numeric and match the training schema."),
+        output: z.enum(["compact", "annotated"]).optional().default("compact").describe("action=predict: output style. compact = predictions.csv (default); annotated = annotated.csv (original rows plus bmu_x, bmu_y, bmu_node_index, cluster_id)."),
         colormap: z.string().optional().describe("action=compare: colormap for diff heatmap (default: balance). action=report: n/a."),
         output_format: z.enum(["png", "pdf", "svg"]).optional().default("png").describe("action=compare: output format for heatmap (default: png)"),
         output_dpi: z.enum(["standard", "retina", "print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x, default), print (4x)"),
         top_n: z.number().int().min(1).max(50).optional().default(10).describe("action=compare: number of top gained/lost nodes to report (default: 10)"),
-    }, async ({ action, job_id, dataset_id, columns, rows, colormap, output_format, output_dpi, top_n }) => {
+        target_column: z.string().optional().describe("action=impute_column: numeric column to impute (must not be a training feature)."),
+        only_missing: z.boolean().optional().default(true).describe("action=impute_column: if true, leave observed values unchanged."),
+        impute_aggregation: z.enum(["mean", "median"]).optional().default("mean").describe("action=impute_column: aggregation over pooled neighbor rows."),
+        cv_folds: z.number().int().min(2).max(20).optional().describe("action=impute_column: if set (2-20), run k-fold cross-validation on observed target cells and emit quality.csv with MAE / RMSE / R2 (held-out). Omit to skip."),
+        target_column_kind: z.enum(["instantaneous", "cumulative", "categorical"]).optional()
+            .describe("action=impute_column: instantaneous (default) = pool mean/median; categorical = pool mode; cumulative = monotonic-counter (pool aggregation is rough; warns). A monotonic-counter warning is emitted automatically regardless."),
+        weighting: z.enum(["distance", "uniform"]).optional()
+            .describe("action=impute_column: distance (default) weights pooled values by map-neighbourhood proximity (closer BMU nodes count more); uniform is a flat pool."),
+    }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n, target_column, only_missing, impute_aggregation, cv_folds, target_column_kind, weighting }) => {
         const dpiMap = { standard: 1, retina: 2, print: 4 };
         const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
         if (action === "predict") {
-            if (!dataset_id && !rows)
-                throw new Error("inference(predict) requires dataset_id or rows");
-            if (!dataset_id && rows && rows.length === 1) {
+            const outputStyle = output ?? "compact";
+            if (outputStyle === "annotated" && rows) {
+                throw new Error("inference(predict, output=\"annotated\") requires a dataset (not inline rows). Either omit rows and pass dataset_id, or use output=\"compact\".");
+            }
+            // Stateless single-row fast path: only valid for compact output and inline rows.
+            if (!dataset_id && rows && rows.length === 1 && outputStyle === "compact") {
                 const row = rows[0];
                 const data = (await apiCall("POST", `/v1/models/${job_id}/project`, { features: row }));
                 return {
@@ -62,49 +116,90 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                     throw new Error("Batch inline predict rows must remain numeric. For baseline categorical inference, submit a single inline row so the proxy can use the stateless model endpoint.");
                 }
             }
-            const body = {};
+            const body = { output_style: outputStyle };
             if (dataset_id)
                 body.dataset_id = dataset_id;
             if (rows)
                 body.rows = rows;
             const data = (await apiCall("POST", `/v1/results/${job_id}/predict`, body));
             const predictJobId = data.id;
+            // annotated runs over the full dataset; allow up to 120s like compact
             const poll = await pollUntilComplete(predictJobId, 120_000);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${predictJobId}`));
                 const summary = (results.summary ?? {});
                 const urls = (results.download_urls ?? {});
+                const previewLines = formatPredictPreviewLines(summary);
+                const regime = String(summary.regime ?? "new");
+                const effectiveStyle = String(summary.output_style ?? outputStyle);
+                const isAnnotated = effectiveStyle === "annotated";
+                const artifactName = isAnnotated ? "annotated.csv" : "predictions.csv";
+                const headerLine = isAnnotated
+                    ? `Annotated dataset ready — job: ${predictJobId}`
+                    : `Predictions complete — job: ${predictJobId}`;
+                const trainingCaveat = regime === "training"
+                    ? `Training-set BMU lookup. QE on training data is not a generalisation metric; the QE / qe_p95 / potential_anomaly columns are intentionally omitted. Use a held-out dataset (different dataset_id) for quality assessment.`
+                    : "";
+                const metricsLine = (regime !== "training" && !isAnnotated)
+                    ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
+                    : "";
+                const outputLine = isAnnotated
+                    ? `Output: annotated.csv (original CSV + bmu_x, bmu_y, bmu_node_index, cluster_id appended). Clusters: ${summary.n_clusters ?? Object.keys(summary.cluster_counts ?? {}).length}.`
+                    : (regime === "training"
+                        ? `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id). Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`
+                        : `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly). Summary includes mean_qe, max_qe, qe_p95. Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`);
                 return { content: [{ type: "text", text: [
-                                `Predictions complete — job: ${predictJobId}`,
+                                headerLine,
+                                `Regime: ${regime}${regime === "training" ? " (scored against the training set)" : ""} | Style: ${effectiveStyle}`,
                                 `Rows scored: ${summary.n_rows ?? "?"}`,
-                                `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"}`,
-                                `Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}`,
-                                `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly). Summary includes mean_qe, max_qe, qe_p95.`,
-                                urls["predictions.csv"] ? `Download: ${urls["predictions.csv"]}` : "",
+                                metricsLine,
+                                outputLine,
+                                urls[artifactName] ? `Download: ${urls[artifactName]}` : "",
+                                trainingCaveat,
+                                ...previewLines,
                             ].filter(Boolean).join("\n") }] };
             }
             if (poll.status === "failed")
                 return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} failed: ${poll.error ?? "unknown error"}` }] };
             return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} submitted. Poll with jobs(action=status, job_id="${predictJobId}").` }] };
         }
-        if (action === "enrich") {
-            const data = (await apiCall("POST", `/v1/results/${job_id}/enrich_dataset`, {}));
-            const enrichJobId = data.id;
-            const poll = await pollUntilComplete(enrichJobId, 60_000);
+        if (action === "impute_column") {
+            if (!dataset_id)
+                throw new Error("inference(impute_column) requires dataset_id");
+            if (!target_column?.trim())
+                throw new Error("inference(impute_column) requires target_column");
+            const body = {
+                dataset_id,
+                target_column: target_column.trim(),
+                only_missing: only_missing ?? true,
+                aggregation: impute_aggregation ?? "mean",
+            };
+            if (cv_folds !== undefined)
+                body.cv_folds = cv_folds;
+            if (target_column_kind !== undefined)
+                body.target_column_kind = target_column_kind;
+            if (weighting !== undefined)
+                body.weighting = weighting;
+            const data = (await apiCall("POST", `/v1/results/${job_id}/impute_column`, body));
+            const imputeJobId = data.id;
+            const poll = await pollUntilComplete(imputeJobId, 120_000);
             if (poll.status === "completed") {
-                const results = (await apiCall("GET", `/v1/results/${enrichJobId}`));
+                const results = (await apiCall("GET", `/v1/results/${imputeJobId}`));
                 const summary = (results.summary ?? {});
                 const urls = (results.download_urls ?? {});
                 return { content: [{ type: "text", text: [
-                                `Enriched dataset ready — job: ${enrichJobId}`,
-                                `Rows: ${summary.n_rows ?? "?"} | Clusters: ${summary.n_clusters ?? "?"}`,
-                                `Appended: bmu_x, bmu_y, bmu_node_index, cluster_id`,
-                                urls["enriched.csv"] ? `Download: ${urls["enriched.csv"]}` : "",
-                            ].filter(Boolean).join("\n") }] };
+                                `Impute column complete — job: ${imputeJobId}`,
+                                `Target: ${summary.target_column ?? target_column} | aggregation: ${summary.aggregation ?? impute_aggregation} | only_missing: ${summary.only_missing ?? only_missing}`,
+                                `Rows: ${summary.n_rows ?? "?"} | imputed rows (source=imputed): ${summary.n_imputed ?? "?"} | insufficient_data: ${summary.n_insufficient ?? "?"}`,
+                                `Mean patch nodes: ${summary.mean_patch_nodes !== undefined ? Number(summary.mean_patch_nodes).toFixed(2) : "N/A"} (BMU + neighbors; hex interior often ~7).`,
+                                urls["imputed.csv"] ? `Download imputed.csv: ${urls["imputed.csv"]}` : "Use results(action=get, download) for URLs.",
+                                "",
+                                "Map-local estimates only — not a substitute for held-out validation.",
+                            ].join("\n") }] };
             }
             if (poll.status === "failed")
-                return { content: [{ type: "text", text: `inference(enrich) job ${enrichJobId} failed: ${poll.error ?? "unknown error"}` }] };
-            return { content: [{ type: "text", text: `inference(enrich) job ${enrichJobId} submitted. Poll with jobs(action=status, job_id="${enrichJobId}").` }] };
+                return { content: [{ type: "text", text: `inference(impute_column) job ${imputeJobId} failed: ${poll.error ?? "unknown error"}` }] };
+            return { content: [{ type: "text", text: `inference(impute_column) job ${imputeJobId} submitted. Poll with jobs(action=status, job_id="${imputeJobId}").` }] };
         }
         if (action === "compare") {
             if (!dataset_id)

package/dist/tools/jobs.js

@@ -5,7 +5,7 @@ export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs.
 | Action | Use when |
 |--------|----------|
 | status | Polling after any async job submission — call every 10–15s |
-| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters. Response includes job_type (train_map, enrich, report, recolor, project, transition_flow, compare, predict) to filter or display. |
+| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters. Response includes job_type (train_map, report, recolor, project, transition_flow, compare, predict, impute_column, annotated_dataset, reduce_spectral) to filter or display. |
 | compare | Picking the best training run from a set of completed jobs |
 | train_map | Submitting a new map training job — returns job_id for polling |
 | train_siom_map | Submitting a self-interacting map training job — same map flow with SIOM coverage control |
@@ -35,18 +35,118 @@ action=train_map / train_siom_map: Submits a grid-map training job. Returns job_
   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.
   categorical_features: optional baseline categorical support using explicit weighted one-hot encoding. Provide the raw column name, allowed categories, and a weight. Advanced categorical embeddings are intentionally outside this default tool surface.
+  label (optional, ≤120 chars): user-supplied run name; appears in jobs(list) and jobs(compare) output. Strongly recommended for sweeps so compare rows stay readable.
   train_siom_map only: siom_feature_geometry l2 (default) | mixed | auto — torus distance on cyclic (cos,sin) pairs when mixed or auto with cyclic encodings. siom_qe_backend cpu|cuda|auto and siom_qe_batch_size align siom_qe with training geometry when mixed.
 action=train_floop_siom (preferred) or train_floop_chain (deprecated alias): Submits FLooP-SIOM — a growing node-budget manifold instead of a fixed hex grid. **Only if the API key’s plan includes all_algorithms** (Premium or Enterprise); otherwise the API returns a clear upgrade message. Default topology is free (CHL dynamic graph); topology=chain is optional for a strict 1D linked-list backbone.
   Key params: topology (default free), max_nodes, effort, gamma, siom_decay.
   max_nodes is a total node budget, not a grid width or area. If omitted, the backend uses a dataset-size heuristic (roughly 2*sqrt(n_samples), capped for stability).
   effort controls passes only: quick≈15, standard≈30, thorough≈60. If coverage collapses, reduce max_nodes before increasing effort.
-action=compare: Returns a metrics table (QE, TE, explained variance, silhouette) for 2+ jobs.
+action=compare: Returns a metrics table (QE, TE, explained variance, silhouette) for 2+ jobs. The table only shows hyperparameter columns that actually differ across the compared runs (preset, backend, batch_size, normalize, periodic, n_features, etc.) so multi-run sweeps stay readable. Tip: pass label="sweep_a" / "sweep_b" on train_map to make rows self-explanatory.
 action=cancel: Not instant — worker checks between phases. Expect up to 30s delay.
 action=delete: WARNING — job ID will no longer work with results or any other tool.`;
 export async function fetchTrainingPresets() {
     const configData = (await apiCall("GET", "/v1/training/config"));
     return configData?.presets || {};
 }
+/**
+ * Render the jobs(compare) markdown table. Strategy: always show job_id (or label
+ * if present) + the four core metrics (QE, TE, Expl.Var, Silhouette); add any
+ * hyperparameter column iff at least two compared jobs differ on it. Keeps
+ * multi-run sweeps readable by hiding columns that are identical across runs.
+ *
+ * Error rows (job not completed / not found) are preserved as a single error cell.
+ */
+export function renderCompareTable(comparisons) {
+    if (comparisons.length === 0)
+        return "(no comparisons)";
+    const ok = comparisons.filter((c) => !c.error);
+    const fmt = (v) => (v !== null && v !== undefined ? Number(v).toFixed(4) : "—");
+    const fmtAny = (v) => {
+        if (v === null || v === undefined)
+            return "—";
+        if (Array.isArray(v))
+            return v.map((x) => String(x)).join(",");
+        if (typeof v === "boolean")
+            return v ? "true" : "false";
+        return String(v);
+    };
+    const renderGrid = (g) => {
+        if (Array.isArray(g) && g.length >= 2)
+            return `${g[0]}×${g[1]}`;
+        return "—";
+    };
+    const renderEpochs = (e) => {
+        if (Array.isArray(e) && e.length >= 2)
+            return `${e[0]}+${e[1]}`;
+        if (typeof e === "number")
+            return String(e);
+        return "—";
+    };
+    // Candidate hyperparameter columns considered for inclusion when they vary.
+    const candidates = [
+        { key: "grid", label: "Grid", render: renderGrid },
+        { key: "epochs", label: "Epochs", render: renderEpochs },
+        { key: "model", label: "Model", render: fmtAny },
+        { key: "periodic", label: "Periodic", render: fmtAny },
+        { key: "backend", label: "Backend", render: fmtAny },
+        { key: "batch_size", label: "Batch", render: fmtAny },
+        { key: "normalize", label: "Normalize", render: fmtAny },
+        { key: "quality_metrics", label: "QualMetrics", render: fmtAny },
+        { key: "n_features", label: "Features", render: fmtAny },
+        { key: "n_samples", label: "Samples", render: fmtAny },
+    ];
+    // Include a candidate iff completed jobs disagree on it.
+    const varying = candidates.filter((col) => {
+        const seen = new Set();
+        for (const c of ok) {
+            seen.add(JSON.stringify(c[col.key] ?? null));
+            if (seen.size > 1)
+                return true;
+        }
+        return false;
+    });
+    const anyLabel = ok.some((c) => c.label != null && String(c.label) !== "");
+    const idHeader = anyLabel ? "Run" : "Job ID";
+    const idCell = (c) => {
+        const lbl = c.label != null && String(c.label) !== "" ? String(c.label) : "";
+        const idShort = `${c.job_id.slice(0, 8)}...`;
+        return lbl ? `${lbl} (${idShort})` : idShort;
+    };
+    // Always include job_id/label + four core metrics. Add varying columns in between.
+    const metrics = [
+        { key: "quantization_error", label: "QE", render: fmt },
+        { key: "topographic_error", label: "TE", render: fmt },
+        { key: "explained_variance", label: "Expl.Var", render: fmt },
+        { key: "silhouette", label: "Silhouette", render: fmt },
+    ];
+    const headerCols = [idHeader, ...varying.map((c) => c.label), ...metrics.map((m) => m.label)];
+    const lines = [
+        `| ${headerCols.join(" | ")} |`,
+        `|${headerCols.map(() => "---").join("|")}|`,
+    ];
+    for (const c of comparisons) {
+        if (c.error) {
+            const filler = Array(varying.length + metrics.length - 1).fill("—").join(" | ");
+            lines.push(`| ${idCell(c)} | ${c.error} | ${filler} |`);
+            continue;
+        }
+        const cells = [
+            idCell(c),
+            ...varying.map((col) => col.render(c[col.key])),
+            ...metrics.map((m) => m.render(c[m.key])),
+        ];
+        lines.push(`| ${cells.join(" | ")} |`);
+    }
+    if (varying.length === 0 && ok.length >= 2) {
+        lines.push("");
+        lines.push("(All hyperparameters identical across compared jobs — only metrics shown. Pass label=\"…\" on train_map for readable run names.)");
+    }
+    else if (!anyLabel && ok.length >= 2) {
+        lines.push("");
+        lines.push("Tip: pass label=\"sweep_xyz\" on train_map / train_siom_map / train_floop_siom to make compare rows readable.");
+    }
+    return lines.join("\n");
+}
 export function buildTrainMapParams(args, presets) {
     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, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, } = args;
     const p = preset ? presets[preset] : undefined;
@@ -145,9 +245,15 @@ export function registerJobsTool(server, description) {
             .string()
             .optional()
             .describe("Required for action=train_map. For action=list, filter jobs by this dataset ID."),
+        label: z
+            .string()
+            .max(120)
+            .optional()
+            .describe("Optional run label (≤120 chars) for train_map / train_siom_map / train_floop_siom — appears in jobs(list) and the jobs(compare) table; sanitized server-side. Useful for sweeps (e.g. label=\"sweep_periodic_true\")."),
         preset: z.enum(["quick", "standard", "refined", "high_res"]).optional(),
-        grid_x: z.number().int().optional(),
-        grid_y: z.number().int().optional(),
+        grid_x: z.number().int().optional()
+            .describe("Grid width. Omit grid_x AND grid_y (and preset) to auto-size the map (~5·√√n per side); the result reports hit_stats.active_node_fraction and a grid_suggestion when too many nodes are dead."),
+        grid_y: z.number().int().optional().describe("Grid height. See grid_x for auto-sizing."),
         epochs: z.preprocess((v) => {
             if (v === undefined || v === null)
                 return v;
@@ -256,7 +362,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") {
-            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, } = 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, } = args;
             let PRESETS = {};
             try {
                 PRESETS = await fetchTrainingPresets();
@@ -304,7 +410,10 @@ export function registerJobsTool(server, description) {
                 totalRows = Number(preview?.total_rows ?? 0);
             }
             catch { /* ignore */ }
-            const data = (await apiCall("POST", "/v1/jobs", { dataset_id, params }));
+            const submitBody = { dataset_id, params };
+            if (label && label.trim() !== "")
+                submitBody.label = label;
+            const data = (await apiCall("POST", "/v1/jobs", submitBody));
             const newJobId = data.id;
             const variantPrefix = action === "train_siom_map" ? "variant=siom" : "variant=som";
             data.effective_params = `${variantPrefix}, ${paramSummary}`;
@@ -335,7 +444,7 @@ export function registerJobsTool(server, description) {
             return textResult(data);
         }
         if (action === "train_floop_siom" || action === "train_floop_chain") {
-            const { columns, cyclic_features, temporal_features, feature_weights, transforms, auto_log_transforms, normalize, row_range, output_format, output_dpi, colormap, topology, max_nodes, effort, n_initial, n_passes, growth_interval, neighborhood_size, edge_max_age, max_degree, gamma, siom_decay, siom_penalty, penalty_alpha, error_threshold, error_decay, ring_close_threshold, sigma_0, sigma_f, eta_0, eta_f, elastic_lambda, elastic_mu, elastic_anchor, anchor_percentile, } = args;
+            const { columns, cyclic_features, temporal_features, feature_weights, transforms, auto_log_transforms, normalize, row_range, output_format, output_dpi, colormap, topology, max_nodes, effort, n_initial, n_passes, growth_interval, neighborhood_size, edge_max_age, max_degree, gamma, siom_decay, siom_penalty, penalty_alpha, error_threshold, error_decay, ring_close_threshold, sigma_0, sigma_f, eta_0, eta_f, elastic_lambda, elastic_mu, elastic_anchor, anchor_percentile, label, } = args;
             if (!dataset_id)
                 throw new Error("jobs(train_floop_siom) requires dataset_id");
             const params = {
@@ -408,7 +517,10 @@ export function registerJobsTool(server, description) {
                 params.elastic_anchor = elastic_anchor;
             if (anchor_percentile !== undefined)
                 params.anchor_percentile = anchor_percentile;
-            const data = (await apiCall("POST", "/v1/jobs", { dataset_id, params }));
+            const submitBody = { dataset_id, params };
+            if (label && label.trim() !== "")
+                submitBody.label = label;
+            const data = (await apiCall("POST", "/v1/jobs", submitBody));
             const newJobId = data.id;
             const maxNodeSummary = max_nodes === undefined ? "max_nodes=auto(~2*sqrt(n_samples))" : `max_nodes=${max_nodes}`;
             const paramSummary = [
@@ -465,21 +577,7 @@ export function registerJobsTool(server, description) {
             const ids = job_ids.join(",");
             const data = (await apiCall("GET", `/v1/jobs/compare?ids=${ids}`));
             const comparisons = (data.comparisons ?? []);
-            const lines = [
-                "| Job ID | Grid | Epochs | Model | QE | TE | Expl.Var | Silhouette |",
-                "|--------|------|--------|-------|----|----|----------|------------|",
-            ];
-            for (const c of comparisons) {
-                if (c.error) {
-                    lines.push(`| ${c.job_id.slice(0, 8)}... | — | — | — | ${c.error} | — | — | — |`);
-                    continue;
-                }
-                const g = c.grid;
-                const ep = c.epochs;
-                const fmt = (v) => v !== null && v !== undefined ? Number(v).toFixed(4) : "—";
-                lines.push(`| ${c.job_id.slice(0, 8)}... | ${g ? `${g[0]}×${g[1]}` : "—"} | ${ep ? `${ep[0]}+${ep[1]}` : "—"} | ${c.model ?? "—"} | ${fmt(c.quantization_error)} | ${fmt(c.topographic_error)} | ${fmt(c.explained_variance)} | ${fmt(c.silhouette)} |`);
-            }
-            return { content: [{ type: "text", text: lines.join("\n") }] };
+            return { content: [{ type: "text", text: renderCompareTable(comparisons) }] };
         }
         if (action === "cancel") {
             if (!job_id)

package/dist/tools/results.js

@@ -17,7 +17,7 @@ ONLY call this after jobs(action=status) returns "completed".
 ESCALATION: If job not found, verify job_id. If "job not complete", poll with jobs(action=status).
 
 action=get: Returns text summary with quality metrics and inline images.
-  - figures: omit = combined only. "all" = all plots. Array = specific logical names (combined, umatrix, hit_histogram, learning_curve, correlation, component_1..N).
+  - figures: omit = combined only. "all" = all plots. "none" = metrics text only, no images (recommended for sweeps and LLM clients to keep tool payloads small). Array = specific logical names (combined, umatrix, hit_histogram, learning_curve, correlation, component_1..N).
   - include_individual: if true (and figures omitted), inlines every component plane.
   - After recolor or project, use the job_id returned by that operation to get the new artifacts, not the original training job_id.
   - After showing results, guide the user: QE interpretation, whether to retrain, which features to explore.
@@ -29,7 +29,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). If job has a label, a named subfolder may be created.
+  - 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).
   - figures: "all" (default) or array of filenames.
   - include_json: also save summary.json.
 
@@ -48,9 +48,9 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             .describe("get: inline results + metrics; recolor: new colormap/format (async); download: save to disk; export: structured data (training_log/weights/nodes); transition_flow: temporal dynamics (async)"),
         job_id: z.string().describe("Job ID of a completed job"),
         figures: z
-            .union([z.enum(["default", "combined_only", "all", "images"]), z.array(z.string())])
+            .union([z.enum(["default", "combined_only", "all", "images", "none"]), z.array(z.string())])
             .optional()
-            .describe("action=get: omit=combined only; 'all'=all plots; array=specific (combined,umatrix,hit_histogram,learning_curve,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),
+            .describe("action=get: omit=combined only; 'all'=all plots; 'none'=metrics text only (no images, ideal for sweeps and LLM clients); array=specific (combined,umatrix,hit_histogram,learning_curve,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),
         include_individual: z
             .boolean()
             .optional()
@@ -64,7 +64,7 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
         folder: z
             .string()
             .optional()
-            .describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to the client's current working directory (or workspace)."),
+            .describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to the client's current working directory (or workspace). Files land in a per-job subfolder (job label or job_id) under this path."),
         colormap: z
             .string()
             .optional()
@@ -202,23 +202,75 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 }
             }
             else if (jobType === "enrich_dataset") {
+                // Older exports: summary.job_type from stored results (read-only display).
                 const files = summary.files ?? [];
+                const csvArtifact = files.find((f) => typeof f === "string" && f.endsWith(".csv")) ?? "artifact.csv";
                 content.push({ type: "text", text: [
-                        `Enrich Dataset — ${resultsHeader}`,
-                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Samples: ${summary.n_samples ?? 0}`,
+                        `Annotated dataset (older export) — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Rows: ${summary.n_rows ?? summary.n_samples ?? 0}`,
                         `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
-                        `Use results(action=download, job_id="${job_id}") to save enriched.csv.`,
+                        `Use results(action=download, job_id="${job_id}") to save ${csvArtifact}.`,
                     ].join("\n") });
             }
             else if (jobType === "predict") {
                 const files = summary.files ?? [];
+                const regime = String(summary.regime ?? "new");
+                const outputStyle = String(summary.output_style ?? "compact");
+                const isAnnotated = outputStyle === "annotated";
+                const headerLabel = isAnnotated ? "Predict (annotated)" : "Predict";
+                const trainingCaveat = (regime === "training" && !isAnnotated)
+                    ? "QE columns intentionally omitted: regime=training (fitting error, not generalisation). Score a held-out dataset for quality assessment."
+                    : "";
+                const metricsLine = (regime !== "training" && !isAnnotated)
+                    ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
+                    : "";
+                const downloadName = isAnnotated ? "annotated.csv" : "predictions.csv";
                 content.push({ type: "text", text: [
-                        `Predict — ${resultsHeader}`,
-                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Samples: ${summary.n_samples ?? 0}`,
+                        `${headerLabel} — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Regime: ${regime} | Style: ${outputStyle}`,
+                        `Rows: ${summary.n_rows ?? summary.n_samples ?? 0}`,
+                        metricsLine,
                         `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
-                        `Use results(action=download, job_id="${job_id}") to save predictions.csv.`,
+                        `Use results(action=download, job_id="${job_id}") to save ${downloadName}.`,
+                        trainingCaveat,
+                    ].filter(Boolean).join("\n") });
+            }
+            else if (jobType === "impute_column") {
+                const files = summary.files ?? [];
+                content.push({ type: "text", text: [
+                        `Impute column — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Target: ${summary.target_column ?? "?"} | Rows: ${summary.n_rows ?? "?"}`,
+                        `Aggregation: ${summary.aggregation ?? "?"} | only_missing: ${summary.only_missing ?? "?"} | imputed: ${summary.n_imputed ?? "?"} | insufficient: ${summary.n_insufficient ?? "?"}`,
+                        `Mean patch nodes: ${summary.mean_patch_nodes !== undefined ? Number(summary.mean_patch_nodes).toFixed(2) : "N/A"}`,
+                        `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
+                        `Use results(action=download, job_id="${job_id}") to save imputed.csv.`,
+                        "Map-local pool estimates — not held-out validated predictions.",
                     ].join("\n") });
             }
+            else if (jobType === "reduce_spectral") {
+                const method = String(summary.method ?? "?");
+                const sourceCols = summary.source_columns ?? [];
+                const outCols = summary.output_columns ?? [];
+                const lines = [
+                    `Reduce Spectral — ${resultsHeader}`,
+                    `Method: ${method} | Source columns: ${sourceCols.length} | Output columns: ${outCols.length}`,
+                    `Source: ${sourceCols.length <= 10 ? sourceCols.join(", ") : sourceCols.slice(0, 5).join(", ") + ", … " + sourceCols.slice(-3).join(", ")}`,
+                    `Output: ${outCols.join(", ")}`,
+                ];
+                if (method === "pca") {
+                    const ev = summary.explained_variance_ratio;
+                    const evTotal = summary.explained_variance_total;
+                    if (ev)
+                        lines.push(`Explained variance per component: [${ev.map((v) => v.toFixed(3)).join(", ")}] | total: ${evTotal !== undefined ? evTotal.toFixed(3) : "N/A"}`);
+                }
+                else if (method === "log_sample" || method === "uniform_sample") {
+                    const idxs = summary.selected_indices;
+                    if (idxs)
+                        lines.push(`Selected indices: [${idxs.join(", ")}]`);
+                }
+                lines.push(`The new columns are appended to the source dataset and ready to use in jobs(action=train_map, columns=[..., "${outCols[0] ?? "feat_1"}", …]).`);
+                content.push({ type: "text", text: lines.join("\n") });
+            }
             else if (jobType === "train_floop_siom") {
                 const siom = summary.siom ?? {};
                 const coverage = summary.coverage_assessment ?? {};
@@ -357,24 +409,29 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             const jobType2 = summary.job_type ?? "train_som";
             const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
             const hasExportableJson = files.some((f) => f.endsWith(".json") && f !== "summary.json");
-            for (const fname of files) {
-                if (isImage(fname) && !inlinedImages.has(fname)) {
-                    const cap = getCaptionForImage(fname);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, fname);
+            // figures="none": metrics-only mode. Skip any further image attaches and the
+            // "Available figures…" hint; keep the structured-data export hint since it
+            // points at non-image artifacts.
+            if (figures !== "none") {
+                for (const fname of files) {
+                    if (isImage(fname) && !inlinedImages.has(fname)) {
+                        const cap = getCaptionForImage(fname);
+                        if (cap)
+                            content.push({ type: "text", text: cap });
+                        await tryAttachImage(content, job_id, fname);
+                    }
                 }
             }
             if (hasExportableJson && (jobType2 === "train_som" || jobType2 === "train_siom" || jobType2 === "render_variant")) {
                 content.push({ type: "text", text: `Structured data: results(action=export, export_type=weights|nodes|training_log)` });
             }
             const featuresForLog = summary.features ?? [];
-            const showAvailable = files.length > 0 && !(figures === "all" || figures === "images");
+            const showAvailable = files.length > 0 && !(figures === "all" || figures === "images" || figures === "none");
             if (showAvailable) {
                 const logicalNames = jobType2 === "train_som" || jobType2 === "train_siom" || jobType2 === "render_variant"
                     ? `Logical names: combined, umatrix, hit_histogram, correlation, ${featuresForLog.map((_, i) => `component_${i + 1}`).join(", ")}. `
                     : "";
-                content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots or results(action=get, figures=all) for all plots.` });
+                content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots, figures=all for everything, or figures="none" for metrics-only.` });
             }
             return { content };
         }
@@ -506,7 +563,7 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
             const files = summary.files ?? [];
             const jobType = summary.job_type ?? "train_som";
-            const needsAllFiles = ["enrich_dataset", "predict", "compare_datasets"].includes(jobType);
+            const needsAllFiles = ["enrich_dataset", "predict", "impute_column", "compare_datasets"].includes(jobType);
             const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
             let toDownload;
             if (figures === "all" || figures === "images" || figures === undefined) {
@@ -521,9 +578,11 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 toDownload = files.filter(isImage);
             }
             let resolvedDir = sandboxPath(folder, await getWorkspaceRootAsync(server));
-            if (jobLabel && (folder === "." || folder === "./results" || folder === "results")) {
-                resolvedDir = path.join(resolvedDir, jobLabel);
-            }
+            // 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, "_");
+            resolvedDir = path.join(resolvedDir, jobSubfolder);
             if (jobType === "render_variant" && summary.colormap) {
                 const colormapDir = String(summary.colormap).replace(/[^a-zA-Z0-9_-]/g, "_");
                 resolvedDir = path.join(resolvedDir, colormapDir);
@@ -538,7 +597,8 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 }
                 catch { /* skip missing files */ }
             }
-            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${folder}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
+            const savedDir = path.join(folder, jobSubfolder);
+            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
         }
         if (action === "recolor") {
             if (!colormap)

package/package.json

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