@barivia/barsom-mcp 0.19.0 → 0.20.1

package/README.md

@@ -180,6 +180,10 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 
 ### Migration notes
 
+- **Features (0.20.0, non-breaking):**
+  - **FLooP-SIOM maps are now projectable.** `inference(action=project_columns)`, `inference(action=predict)`, and `datasets(action=add_expression, project_onto_job=<floop_job>)` work on FLooP-SIOM (free/chain) maps — values render onto the FLooP Voronoi layout instead of failing. Grid-only ops (`inference(action=transition_flow | impute_column | render_variant)`) return a clear `unsupported_topology_for_inference` message; use a fixed-grid SOM/SIOM for those. No client change required.
+  - **`datasets(action=reduce_spectral)` column selectors.** New optional `columns_range` (`[first, last]`, the server expands the inclusive numeric block — preferred for wide spectra over sending thousands of names) and `columns_except` (drop non-frequency columns like id/label/target from the block, or use alone for "all numeric except these"). `columns_except` composes with `columns_block` or `columns_range`; `columns_block` and `columns_range` are mutually exclusive. Existing `columns_block` callers are unaffected.
+  - Minimum dataset size for train/analyze relaxed from 50 to **10 rows** (10–49 allowed with a small-N stability caveat).
 - **Surface cleanup (0.19.0, breaking):**
   - `training_prep` and `submit_prepared_training` **removed**. The interactive prep UI is retired; for pre-train help use the `prepare_training` prompt (narrative checklist) or `training_guidance` (presets + resolved per-column normalization), then submit directly with `train(action=map | siom_map | impute | floop_siom)`.
   - The unused `data-preview` and `map-explorer` view scaffolds were deleted (they were never wired to a tool). The two shipped MCP App UIs are now `training_monitor` and `results_explorer`, both enhanced (auto-resize, earlier render, and silent model-context sync of what the user is viewing).
@@ -227,7 +231,7 @@ MCP Client (Cursor/Claude) ←stdio→ @barivia/barsom-mcp ←HTTPS→ api.bariv
 | `401` / invalid key | `BARIVIA_API_KEY` in MCP config; check your email or manage your key in the [account dashboard](https://barivia.se/dashboard). Error text includes a **request id** for support. |
 | Request timed out | Raise `BARIVIA_FETCH_TIMEOUT_MS` (e.g. `120000`). Large uploads already use an extended timeout; `datasets(analyze)` is async (auto-polled). Timeouts are not auto-retried, so re-running a timed-out upload is safe — an idempotency key reconciles it to the original dataset instead of duplicating. |
 | `Path must be within the workspace` / upload can’t find file | Set `BARIVIA_WORKSPACE_ROOT` to your project directory, or use an absolute path / `file:///...` URI. |
-| Job stuck “running” | Poll `jobs(action=status)` every 10–15s; large grids or FLooP-SIOM can take several minutes—not an MCP error. Staged datasets enqueue **`prepare_training_matrix`** (or impute prepare) first — train submit returns `prepare_job_id`; MCP auto-polls prepare when present. CFD mesh submit may return `prepare_job_id` for **`cfd_prepare`** (barmesh auto-polls). |
+| Job stuck “running” | Poll `jobs(action=status)` every 10–15s; large grids or FLooP-SIOM can take several minutes—not an MCP error. Staged datasets enqueue **`prepare_training_matrix`** (or impute prepare) first — train submit returns `prepare_job_id`; MCP auto-polls prepare when present. CFD mesh submit may return `prepare_job_id` for **`prepare_training_matrix`** (barmesh auto-polls). |
 | `429` | Rate limit—wait and retry. |
 | Standalone `…/viz/…` page stuck at "running 0%" or "Loading…" | The link is stale: the viz port is assigned per MCP session and changes when the proxy restarts. Re-run `training_monitor` / `results_explorer` for a fresh URL, or set `BARIVIA_VIZ_PORT` for a persistent port. Confirm with `GET /api/health?job_id=<id>`. |
 | Embedded results explorer: switching figures shows nothing | Fixed in `0.18.0` — earlier versions pointed embedded figures at a localhost URL the webview can't load. Update the package; the embedded view now lazy-loads figures over the MCP App bridge. |

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 s,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as i}from"./viz-server.js";import{API_KEY as a,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as m,setClientSupportsMcpApps as d,CLIENT_VERSION as u}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as h,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as w,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as j}from"./tools/account.js";import{registerInferenceTool as v}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as k}from"./tools/feedback.js";import{registerTrainingMonitorTool as I,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 M=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 `train(action=map)`, `train(action=siom_map)`, or `train(action=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 `results_explorer(job_id)` to browse the figures interactively. Then `jobs(compare)`, `results(download/recolor)`, or `inference` (predict / compare / project_columns / impute_column / transition_flow) 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 taxonomy (one tool per stage — do not mix)\n\n| Stage | Tool(s) | Contract |\n|-------|---------|----------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete — ingest + feature engineering, no map |\n| Train submit | `train` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list, compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (figures="none" for metrics-only), export, download, recolor (async). Read/render completed jobs |\n| Frozen-map ops | `inference` | predict (regime-aware; "compact"|"annotated"), batch_predict, impute_column (neighbor-pool fill for a non-training column), compare (cohort density-diff), project_columns, transition_flow (time-ordered rows only), report. No weight updates |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `training_guidance`, `prepare_training` prompt | orientation, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics table across **training runs** (pick best in a sweep). `inference(compare)` = density-diff of one map vs a **second dataset** (drift/cohort). Different tools.\n- Post-training map analysis (predict, compare, project_columns, impute_column, **transition_flow**) is all **inference** — not `results`. `results` is presentation/artifacts only (`recolor` stays here: it re-renders, it doesn\'t touch data).\n- Project a quantity onto the map: existing columns → `inference(project_columns)`; a formula → `datasets(add_expression, project_onto_job=<job>)`.\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 (incl. `transition_flow`) and `results(recolor)` 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. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. 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 `results(recolor)`, `inference(transition_flow)`, or `inference(project_columns)`, use the **new** `job_id` returned for follow-up `results` if applicable.'});s(M,y,y,{mimeType:n},async()=>{const e=await p("results-explorer");return{contents:[{uri:y,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(M,A,A,{mimeType:n},async()=>{const e=await p("training-monitor");return{contents:[{uri:A,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(M),w(M),I(M),f(M),g(M),h(M,_),b(M),j(M),v(M),P(M),k(M),M.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) → `results_explorer(job_id)` to browse figures.","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map/siom_map/impute/floop_siom; pass `label` for readable compare rows; preset=quick for a fast first map), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/download/export/recolor; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; transition_flow; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints + resolved normalization/params) — review, then submit with `train`.","","**Browse results:** `results_explorer(job_id)` is the preferred way to explore figures after a first `results(get)` glance; `training_monitor` shows live progress. Both optional — `results` + `jobs(status)` suffice headless.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `inference(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")}}]})),M.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. Review, then submit with train.",{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 S=new t;(async function(){try{const e=await i(l,c,p);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=M.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(n))},await M.connect(S)})().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 s,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as i}from"./viz-server.js";import{API_KEY as a,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as m,setClientSupportsMcpApps as u,CLIENT_VERSION as d}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as h,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as w,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as j}from"./tools/account.js";import{registerInferenceTool as v}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as k}from"./tools/feedback.js";import{registerTrainingMonitorTool as I,TRAINING_MONITOR_URI as A}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as M}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 T=new e({name:"analytics-engine",version:d,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 `train(action=map)`, `train(action=siom_map)`, or `train(action=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 `results_explorer(job_id)` to browse the figures interactively. Then `jobs(compare)`, `results(download/recolor)`, or `inference` (predict / compare / project_columns / impute_column / transition_flow) 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 taxonomy (one tool per stage — do not mix)\n\n| Stage | Tool(s) | Contract |\n|-------|---------|----------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete — ingest + feature engineering, no map |\n| Train submit | `train` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list, compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (default=combined only; figures="none" for metrics-only sweeps; figures="all" or results_explorer/download for every plot), export, download, recolor (async). Read/render completed jobs |\n| Frozen-map ops | `inference` | predict (regime-aware; "compact"|"annotated"), batch_predict, impute_column (neighbor-pool fill for a non-training column), compare (cohort density-diff), project_columns, transition_flow (time-ordered rows only), report. No weight updates |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `training_guidance`, `prepare_training` prompt | orientation, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics table across **training runs** (pick best in a sweep). `inference(compare)` = density-diff of one map vs a **second dataset** (drift/cohort). Different tools.\n- Post-training map analysis (predict, compare, project_columns, impute_column, **transition_flow**) is all **inference** — not `results`. `results` is presentation/artifacts only (`recolor` stays here: it re-renders, it doesn\'t touch data).\n- Project a quantity onto the map: existing columns → `inference(project_columns)`; a formula → `datasets(add_expression, project_onto_job=<job>)`.\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 (incl. `transition_flow`) and `results(recolor)` 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. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. 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 `results(recolor)`, `inference(transition_flow)`, or `inference(project_columns)`, use the **new** `job_id` returned for follow-up `results` if applicable.\n- **Large results / MCP timeouts:** For sweeps, `jobs(compare)`, or metrics-only reads use `results(action=get, figures="none")`. Default `get` inlines combined only. For every plot use `results_explorer` or `results(action=download)`, not `figures="all"` in chat unless the user wants all images inline.'});s(T,y,y,{mimeType:n},async()=>{const e=await p("results-explorer");return{contents:[{uri:y,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(T,A,A,{mimeType:n},async()=>{const e=await p("training-monitor");return{contents:[{uri:A,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(T),w(T),I(T),f(T),g(T),h(T,_),b(T),j(T),v(T),P(T),k(T),T.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) → `results_explorer(job_id)` to browse figures.","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map/siom_map/impute/floop_siom; pass `label` for readable compare rows; preset=quick for a fast first map), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/download/export/recolor; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; transition_flow; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints + resolved normalization/params) — review, then submit with `train`.","","**Browse results:** `results_explorer(job_id)` is the preferred way to explore figures after a first `results(get)` glance; `training_monitor` shows live progress. Both optional — `results` + `jobs(status)` suffice headless.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `inference(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")}}]})),T.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. Review, then submit with train.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await M(e)}}]}));const S=new t;(async function(){try{const e=await i(l,c,p);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=T.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);u(!!o?.mimeTypes?.includes(n))},await T.connect(S)})().catch(console.error);

package/dist/job_monitor.js

@@ -0,0 +1,230 @@
+/**
+ * Server-side job monitor for barsom async training workflows.
+ * Polls GET /v1/jobs/:id until terminal (or block_until timeout) and emits
+ * compact throttled snapshots so agents avoid manual status poll loops.
+ */
+import { apiCall, textResult } from "./shared.js";
+import { formatJobStatusText } from "./job_status_format.js";
+import { pollFinalizeIfPresent, refreshJobAfterFinalize } from "./train_finalize.js";
+export const DEFAULT_BLOCK_UNTIL_SEC = 900;
+export const DEFAULT_POLL_INTERVAL_SEC = 5;
+export const MIN_POLL_INTERVAL_SEC = 5;
+export const HEARTBEAT_POLLS = 1;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function num(data, key) {
+    const v = data[key];
+    if (v == null || Number.isNaN(Number(v)))
+        return undefined;
+    return Number(v);
+}
+function str(data, key) {
+    const v = data[key];
+    if (v == null || String(v) === "")
+        return undefined;
+    return String(v);
+}
+function tailOrderingErrors(data, n = 4) {
+    const raw = data.ordering_errors;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.slice(-n).map((x) => Number(x)).filter((x) => !Number.isNaN(x));
+}
+export function snapshotFromJob(data, elapsedSec, note) {
+    const status = String(data.status ?? "unknown");
+    const progress_pct = (data.progress ?? 0) * 100;
+    const snap = {
+        elapsed_sec: elapsedSec,
+        status,
+        progress_pct: Math.round(progress_pct * 10) / 10,
+    };
+    const phase = str(data, "progress_phase");
+    if (phase)
+        snap.phase = phase;
+    const epoch = num(data, "epoch");
+    const total = num(data, "total_epochs");
+    if (epoch != null)
+        snap.epoch = epoch;
+    if (total != null)
+        snap.total_epochs = total;
+    const qe = num(data, "quantization_error");
+    const te = num(data, "topographic_error");
+    if (qe != null)
+        snap.qe = Math.round(qe * 10_000) / 10_000;
+    if (te != null)
+        snap.te = Math.round(te * 10_000) / 10_000;
+    const eta = num(data, "training_eta_sec");
+    if (eta != null && eta > 0)
+        snap.eta_sec = Math.round(eta);
+    const tail = tailOrderingErrors(data);
+    if (tail && tail.length > 0)
+        snap.ordering_errors_tail = tail;
+    if (note)
+        snap.note = note;
+    return snap;
+}
+/** True when a new snapshot is worth recording (phase/epoch/progress/status change). */
+export function shouldRecordSnapshot(prev, next) {
+    if (!prev)
+        return true;
+    if (prev.status !== next.status)
+        return true;
+    if (next.note)
+        return true;
+    if (prev.phase !== next.phase)
+        return true;
+    if (prev.epoch !== next.epoch)
+        return true;
+    if (Math.abs(prev.progress_pct - next.progress_pct) >= 1)
+        return true;
+    if (prev.qe !== next.qe || prev.te !== next.te)
+        return true;
+    return false;
+}
+export function formatSnapshotLine(s) {
+    const parts = [`[+${s.elapsed_sec}s] ${s.status} ${s.progress_pct.toFixed(1)}%`];
+    if (s.phase)
+        parts.push(`phase ${s.phase}`);
+    if (s.epoch != null && s.total_epochs != null)
+        parts.push(`epoch ${s.epoch}/${s.total_epochs}`);
+    if (s.qe != null)
+        parts.push(`QE ${s.qe.toFixed(4)}`);
+    if (s.te != null)
+        parts.push(`TE ${s.te.toFixed(4)}`);
+    if (s.eta_sec != null)
+        parts.push(`ETA ~${s.eta_sec}s`);
+    if (s.ordering_errors_tail?.length) {
+        parts.push(`ordering_errors tail [${s.ordering_errors_tail.map((x) => x.toFixed(4)).join(", ")}]`);
+    }
+    if (s.note)
+        parts.push(s.note);
+    return parts.join(" | ");
+}
+export function formatMonitorText(result, opts) {
+    const lines = [
+        `Job ${result.job_id} monitor (block_until=${opts.block_until_sec}s, poll=${opts.poll_interval_sec}s):`,
+    ];
+    for (const s of result.snapshots)
+        lines.push(formatSnapshotLine(s));
+    lines.push("");
+    if (result.timed_out) {
+        lines.push(`Timed out before terminal state. Last status: ${result.status_text}`);
+        lines.push(`Re-run jobs(action=monitor, job_id="${result.job_id}") or training_monitor(job_id="${result.job_id}").`);
+    }
+    else {
+        lines.push(`Terminal: ${result.status_text}`);
+    }
+    lines.push(result.suggested_next_step);
+    return lines.join("\n");
+}
+function suggestedNextStep(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status === "completed") {
+        const finalizeId = str(data, "finalize_job_id");
+        if (finalizeId) {
+            return `Compute done; finalize_training may still be running. Re-run jobs(action=monitor, job_id="${job_id}") with wait_finalize=true, then results(action=get, job_id="${job_id}").`;
+        }
+        return `Next: results(action=get, job_id="${job_id}") or results_explorer(job_id="${job_id}").`;
+    }
+    if (status === "failed") {
+        const stage = str(data, "failure_stage");
+        return `Job failed${stage ? ` at ${stage}` : ""}. Read the error above before retrying.`;
+    }
+    if (status === "cancelled")
+        return `Job cancelled. Confirm with jobs(action=status, job_id="${job_id}").`;
+    return `Still running — re-run jobs(action=monitor, job_id="${job_id}") to continue waiting.`;
+}
+async function fetchTrainingLogHint(job_id, data) {
+    const status = String(data.status ?? "");
+    if (status !== "completed" && status !== "failed")
+        return undefined;
+    try {
+        await apiCall("GET", `/v1/results/${job_id}/training-log`);
+        return `Training log available at GET /v1/results/${job_id}/training-log.`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function monitorJob(job_id, options = {}) {
+    const block_until_sec = Math.max(30, options.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC);
+    const poll_interval_sec = Math.max(MIN_POLL_INTERVAL_SEC, options.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC);
+    const wait_finalize = options.wait_finalize !== false;
+    const blockMs = block_until_sec * 1000;
+    const pollMs = poll_interval_sec * 1000;
+    const start = Date.now();
+    const snapshots = [];
+    let lastSnap = null;
+    let data = {};
+    let heartbeat = 0;
+    while (Date.now() - start < blockMs) {
+        data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        const snap = snapshotFromJob(data, elapsedSec);
+        heartbeat += 1;
+        const heartbeatDue = heartbeat >= HEARTBEAT_POLLS;
+        if (shouldRecordSnapshot(lastSnap, snap) || heartbeatDue) {
+            snapshots.push(snap);
+            lastSnap = snap;
+            heartbeat = 0;
+        }
+        const status = String(data.status ?? "");
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            break;
+        }
+        await sleep(pollMs);
+    }
+    const status = String(data.status ?? "");
+    const terminal = status === "completed" || status === "failed" || status === "cancelled";
+    const timed_out = !terminal;
+    if (terminal && status === "completed" && wait_finalize && data.finalize_job_id) {
+        const finalizeId = String(data.finalize_job_id);
+        const elapsedSec = Math.round((Date.now() - start) / 1000);
+        snapshots.push(snapshotFromJob(data, elapsedSec, `finalize_training ${finalizeId} started — waiting for figure render`));
+        try {
+            const { note } = await pollFinalizeIfPresent(job_id, data, Math.max(0, blockMs - (Date.now() - start)));
+            data = await refreshJobAfterFinalize(job_id);
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), note ?? `finalize_training ${finalizeId} completed`));
+        }
+        catch (err) {
+            snapshots.push(snapshotFromJob(data, Math.round((Date.now() - start) / 1000), `finalize_training failed: ${err.message}`));
+        }
+    }
+    const statusText = formatJobStatusText(job_id, data);
+    const logHint = terminal ? await fetchTrainingLogHint(job_id, data) : undefined;
+    let suggested = suggestedNextStep(job_id, data);
+    if (logHint)
+        suggested += ` ${logHint}`;
+    return {
+        job_id,
+        terminal,
+        timed_out,
+        snapshots,
+        status_text: statusText,
+        data,
+        suggested_next_step: suggested,
+    };
+}
+export async function runJobMonitor(args) {
+    const block_until_sec = args.block_until_sec ?? DEFAULT_BLOCK_UNTIL_SEC;
+    const poll_interval_sec = args.poll_interval_sec ?? DEFAULT_POLL_INTERVAL_SEC;
+    const result = await monitorJob(args.job_id, {
+        block_until_sec,
+        poll_interval_sec,
+        wait_finalize: args.wait_finalize,
+    });
+    const text = formatMonitorText(result, { block_until_sec, poll_interval_sec });
+    return textResult({
+        ...result.data,
+        monitor: {
+            job_id: result.job_id,
+            terminal: result.terminal,
+            timed_out: result.timed_out,
+            snapshots: result.snapshots,
+            status_text: result.status_text,
+            suggested_next_step: result.suggested_next_step,
+        },
+        status_text: text,
+    });
+}

package/dist/shared.js

@@ -26,7 +26,7 @@ export const RETRYABLE_STATUS = new Set([502, 503, 504]);
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.19.0";
+export const CLIENT_VERSION = "0.20.1";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -611,6 +611,19 @@ export function getCaptionForImage(filename) {
         return "Projected variable — per-node aggregation on the map.";
     return "";
 }
+export const MAX_INLINE_BYTES = parseInt(process.env.BARIVIA_MAX_INLINE_BYTES ?? "8000000", 10);
+let _inlineAttachBytesUsed = 0;
+/** Reset inline image byte budget (call at the start of each MCP tool response). */
+export function resetInlineAttachBudget() {
+    _inlineAttachBytesUsed = 0;
+}
+export function inlineAttachBytesUsed() {
+    return _inlineAttachBytesUsed;
+}
+/** When true, results(get) should attach every image in summary.files not already inlined. */
+export function shouldFetchAllRemainingFigures(figures) {
+    return figures === "all" || figures === "images";
+}
 export async function tryAttachImage(content, jobId, filename) {
     // MCP image content only supports raster MIME types (png/jpeg/gif/webp).
     // PDF and SVG must be retrieved out-of-band via get_result_image.
@@ -624,6 +637,16 @@ export async function tryAttachImage(content, jobId, filename) {
     }
     try {
         const { data: imgBuf } = await apiRawCall(`/v1/results/${jobId}/image/${filename}`);
+        const nextTotal = _inlineAttachBytesUsed + imgBuf.length;
+        if (nextTotal > MAX_INLINE_BYTES) {
+            content.push({
+                type: "text",
+                text: `Skipped inline ${filename} (${imgBuf.length} bytes would exceed inline budget). ` +
+                    `Use results(action=download, job_id="${jobId}") or results_explorer(job_id="${jobId}").`,
+            });
+            return;
+        }
+        _inlineAttachBytesUsed = nextTotal;
         content.push({
             type: "image",
             data: imgBuf.toString("base64"),

package/dist/tools/datasets.js

@@ -166,7 +166,7 @@ action=reduce_spectral: Run a pre-training reducer over an ordered block of nume
   - 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).
+  Required params: name (prefix for derived columns), method, a column selector, k (≥ 1, < #columns; ignored for stats). Column selector — pick a base block then optionally exclude non-frequency columns: base = columns_block (explicit ordered names ≥ 2) OR columns_range ([first, last], server expands the inclusive numeric block — preferred for wide spectra); columns_except removes columns that are NOT frequency data (id/label/target/metadata) from that block (combine with a base), or used alone means "all numeric columns except these". Only frequency columns are reduced; excluded columns remain in the dataset.
 action=delete: Remove a dataset and all S3 data permanently.
 
 BEST FOR: Tabular numeric data. CSV with header required.
@@ -237,7 +237,16 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
         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)"),
+            .describe("action=reduce_spectral: explicit ordered list of source frequency/spectral column names (≥ 2; ≥ k+1 for non-stats methods). For a large contiguous block prefer columns_range to avoid sending thousands of names. Mutually exclusive with columns_range."),
+        columns_range: z
+            .array(z.string())
+            .length(2)
+            .optional()
+            .describe("action=reduce_spectral: [first_column, last_column] — server expands to the inclusive block of numeric columns in dataset order (e.g. [\"wl_188\", \"wl_441\"]). Mutually exclusive with columns_block. If non-frequency columns (id/label/target) fall inside the range, drop them with columns_except."),
+        columns_except: z
+            .array(z.string())
+            .optional()
+            .describe("action=reduce_spectral: column names to EXCLUDE from the reduction — the non-frequency columns (id/label/target/metadata) that must NOT be dimensionally reduced. Combine with columns_block or columns_range to subtract them from the block, or use alone to mean 'all numeric columns except these'. Excluded columns stay in the dataset untouched."),
         k: z
             .number()
             .int()
@@ -255,7 +264,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             .int()
             .optional()
             .describe("action=subset: RNG seed for sample_n (default 42; same seed + dataset reproduces the same sample)."),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, k, sample_n, sample_seed }) => {
+    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, columns_range, columns_except, k, sample_n, sample_seed }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("datasets(upload) requires name");
@@ -569,16 +578,34 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 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");
+            // Base selector: columns_block OR columns_range (mutually exclusive).
+            // columns_except is an independent filter that removes non-frequency
+            // columns (id/label/target/metadata) from the base block, so it may be
+            // combined with either base — or used alone to mean "all numeric except".
+            if (columns_block && columns_range) {
+                throw new Error("datasets(reduce_spectral): provide either columns_block or columns_range, not both");
+            }
+            if (!columns_block && !columns_range && !columns_except) {
+                throw new Error("datasets(reduce_spectral) requires a column selector: columns_block (ordered names ≥ 2), columns_range ([first, last]), and/or columns_except (drop non-frequency columns; alone = all numeric except these)");
+            }
+            if (columns_block && columns_block.length < 2) {
+                throw new Error("datasets(reduce_spectral) columns_block must list ≥ 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) {
+            // Upper bound on k (k < #columns) is enforced server-side after range/except
+            // resolution; for an explicit columns_block with no exclusion we can also check locally.
+            if (method !== "stats" && k !== undefined && columns_block && !columns_except && 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 };
+            const body = { name, method };
+            if (columns_block)
+                body.columns = columns_block;
+            if (columns_range)
+                body.column_range = columns_range;
+            if (columns_except)
+                body.columns_except = columns_except;
             if (method !== "stats")
                 body.k = k;
             const data = (await apiCall("POST", `/v1/datasets/${dataset_id}/reduce_spectral`, body));

package/dist/tools/jobs.js

@@ -2,12 +2,13 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { formatJobCancelText, formatJobStatusText } from "../job_status_format.js";
-import { pollFinalizeIfPresent, refreshJobAfterFinalize } from "../train_finalize.js";
+import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, runJobMonitor } from "../job_monitor.js";
 export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle only).
 
 | Action | Use when |
 |--------|----------|
-| status | Polling after any async submission — call every 10–15s |
+| monitor | After async submit — blocks server-side with 5s snapshots until terminal (preferred for agents) |
+| status | One-shot progress check (manual poll every 10–15s if not using monitor) |
 | list | Finding job IDs / reviewing pipeline state (optionally filter by dataset_id) |
 | compare | Picking the best TRAINING run from a set (metrics table). NOT inference(compare), which diffs one dataset's distribution against the training set. |
 | cancel | Stopping a running or pending job to free the worker |
@@ -15,8 +16,13 @@ export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle only).
 
 To SUBMIT training, use the **train** tool (train(action=map | siom_map | impute | floop_siom)); to score data or run post-training map operations (predict, batch_predict, compare, project_columns, impute_column, transition_flow), use **inference**.
 
+ASYNC POLLING PROTOCOL (action=monitor):
+- Preferred after train/inference submit: one call blocks until completed/failed or block_until timeout (default ${DEFAULT_BLOCK_UNTIL_SEC}s, poll every ${DEFAULT_POLL_INTERVAL_SEC}s).
+- Snapshots include phase, epoch/total, QE/TE, ETA, ordering_errors tail when live; waits for finalize_training by default.
+- Optional UI: training_monitor(job_id) for embedded charts; jobs(action=monitor) is the headless equivalent.
+
 ASYNC POLLING PROTOCOL (action=status):
-- Poll every 10-15 seconds. Do NOT poll faster — it wastes context.
+- One-shot check only. If not using monitor, poll every 10-15 seconds manually.
 - Progress increases through phases (ordering then convergence for map training); other job types differ.
 - For large grids (40×40+), do not assume failure before 3 minutes on CPU.
 - Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.
@@ -137,12 +143,28 @@ export function renderCompareTable(comparisons) {
 export function registerJobsTool(server, description) {
     registerAuditedTool(server, "jobs", description, {
         action: z
-            .enum(["status", "list", "compare", "cancel", "delete"])
-            .describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files. (Training is submitted via the train tool; scoring / post-training map ops via inference.)"),
+            .enum(["status", "monitor", "list", "compare", "cancel", "delete"])
+            .describe("status: one-shot check; monitor: block until terminal with snapshots; list/compare/cancel/delete as labeled. (Training via train; scoring via inference.)"),
         job_id: z
             .string()
             .optional()
-            .describe("Job ID — required for action=status, cancel, delete."),
+            .describe("Job ID — required for action=status, monitor, cancel, delete."),
+        block_until_sec: z
+            .number()
+            .int()
+            .min(30)
+            .optional()
+            .describe(`action=monitor only: max wait seconds (default ${DEFAULT_BLOCK_UNTIL_SEC})`),
+        poll_interval_sec: z
+            .number()
+            .int()
+            .min(5)
+            .optional()
+            .describe(`action=monitor only: poll interval seconds (default ${DEFAULT_POLL_INTERVAL_SEC})`),
+        wait_finalize: z
+            .boolean()
+            .optional()
+            .describe("action=monitor only: wait for finalize_training (default true)"),
         job_ids: z
             .array(z.string())
             .optional()
@@ -152,24 +174,17 @@ export function registerJobsTool(server, description) {
             .optional()
             .describe("action=list: filter jobs by this dataset ID."),
     }, async (args) => {
-        const { action, job_id, job_ids, dataset_id } = args;
+        const { action, job_id, job_ids, dataset_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
         // ---- Lifecycle ----
+        if (action === "monitor") {
+            if (!job_id)
+                throw new Error("jobs(monitor) requires job_id");
+            return runJobMonitor({ job_id, block_until_sec, poll_interval_sec, wait_finalize });
+        }
         if (action === "status") {
             if (!job_id)
                 throw new Error("jobs(status) requires job_id");
-            let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
-            const status = String(data.status ?? "");
-            if (status === "completed" && data.finalize_job_id) {
-                const { note } = await pollFinalizeIfPresent(job_id, data);
-                data = await refreshJobAfterFinalize(job_id);
-                const text = formatJobStatusText(job_id, data);
-                return {
-                    content: [{
-                            type: "text",
-                            text: note ? `${text}\n${note}` : text,
-                        }],
-                };
-            }
+            const data = (await apiCall("GET", `/v1/jobs/${job_id}`));
             return { content: [{ type: "text", text: formatJobStatusText(job_id, data) }] };
         }
         if (action === "list") {

package/dist/tools/results.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, getResultsImagesToFetch, getCaptionForImage, mimeForFilename, } from "../shared.js";
+import { apiCall, apiRawCall, getWorkspaceRootAsync, sandboxPath, pollUntilComplete, tryAttachImage, resetInlineAttachBudget, getResultsImagesToFetch, getCaptionForImage, shouldFetchAllRemainingFigures, mimeForFilename, } from "../shared.js";
 export function registerResultsTool(server) {
     registerAuditedTool(server, "results", `Retrieve, recolor, download, or export figures and metrics for a completed map job. Presentation and artifact access only — operations on the frozen map (predict, compare, project, impute_column, transition_flow) live in **inference**.
 
@@ -87,6 +87,7 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
     }, async ({ action, job_id, figures, include_individual, include_json, folder, colormap, output_format, output_dpi, recolor_figures, export_type: exportType }) => {
         const dpiMap = { standard: 1, retina: 2, print: 4 };
         if (action === "get") {
+            resetInlineAttachBudget();
             const data = (await apiCall("GET", `/v1/results/${job_id}`));
             const summary = (data.summary ?? {});
             const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
@@ -453,13 +454,14 @@ NOT FOR: Jobs that haven't completed (use jobs(action=status) first), or tempora
             // 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") {
+            if (shouldFetchAllRemainingFigures(figures)) {
                 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);
+                        inlinedImages.add(fname);
                     }
                 }
             }

package/dist/tools/training_monitor.js

@@ -54,7 +54,7 @@ async function enrichWithTrainingLog(job_id, data) {
 export function registerTrainingMonitorTool(server) {
     registerAppTool(server, "training_monitor", {
         title: "Training Monitor",
-        description: "Optional embedded or standalone view of training progress for a job_id. When embedded in a client that supports MCP Apps, the panel auto-refreshes every 5s until the job completes: live QE/TE learning curves plus a per-epoch hit-distribution heatmap (sampled BMU counts across the map, showing where observations are landing as training proceeds). A standalone browser URL is also available — its localhost port is per MCP session and goes stale if the proxy restarts (set BARIVIA_VIZ_PORT for a persistent port; re-run this tool for a fresh link). The same scalar fields are available via jobs(action=status)—not required to complete training or read results.",
+        description: "Optional embedded or standalone view of training progress for a job_id. When embedded in a client that supports MCP Apps, the panel auto-refreshes every 5s until the job completes: live QE/TE learning curves (uniformly subsampled to ≤1000 batch samples per phase, not one point per epoch) plus a per-epoch hit-distribution heatmap (sampled BMU counts across the map, showing where observations are landing as training proceeds). A standalone browser URL is also available — its localhost port is per MCP session and goes stale if the proxy restarts (set BARIVIA_VIZ_PORT for a persistent port; re-run this tool for a fresh link). The same scalar fields are available via jobs(action=status)—not required to complete training or read results.",
         inputSchema: {
             job_id: z.string().describe("Training job ID to monitor"),
             fetch_training_log: z

package/dist/training_monitor_curve.js

@@ -0,0 +1,30 @@
+/** Batch-sample x-axis helpers for the training_monitor MCP App chart. */
+export function batchSampleAxis(n, offset = 0) {
+    if (n <= 0)
+        return [];
+    return Array.from({ length: n }, (_, i) => offset + i + 1);
+}
+export function combinedBatchAxis(nOrd, nConv) {
+    if (nOrd <= 0 && nConv <= 0)
+        return [];
+    return [...batchSampleAxis(nOrd, 0), ...batchSampleAxis(nConv, nOrd)];
+}
+export function formatCurveSourceNote(data) {
+    const src = data.training_curve_source_batches;
+    if (!src)
+        return null;
+    const parts = [];
+    const ordTotal = typeof src.ordering === "number" ? src.ordering : null;
+    const convTotal = typeof src.convergence === "number" ? src.convergence : null;
+    const ordShown = Array.isArray(data.ordering_errors) ? data.ordering_errors.length : 0;
+    const convShown = Array.isArray(data.convergence_errors) ? data.convergence_errors.length : 0;
+    if (ordTotal != null && ordTotal > ordShown) {
+        parts.push(`${ordShown} of ${ordTotal.toLocaleString()} ordering batch samples`);
+    }
+    if (convTotal != null && convTotal > convShown) {
+        parts.push(`${convShown} of ${convTotal.toLocaleString()} convergence batch samples`);
+    }
+    if (parts.length === 0)
+        return null;
+    return `Displaying uniformly subsampled curves (≤1000 points/phase): ${parts.join("; ")}.`;
+}