@barivia/barsom-mcp 0.22.1 → 0.22.2

package/README.md

@@ -163,12 +163,11 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 | Action | Use when |
 |--------|----------|
 | `status` | Before large jobs — plan tier, GPU availability, queue depth, credit balance, training time estimates |
-| `request_compute` | Upgrading to cloud burst. Leave tier blank to list options. |
-| `compute_status` | Checking active lease time remaining |
-| `release_compute` | Manually stopping a lease to stop billing |
 | `history` | Viewing recent compute usage and spend |
 | `add_funds` | Getting instructions to add credits |
 
+Capacity is shared LOCAL/GKE worker pools (no per-key cloud burst lease).
+
 ### MCP App tools (optional UIs)
 
 | Tool | Role |
@@ -191,6 +190,10 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 
 ### Migration notes
 
+- **Account surface (0.22.0, breaking):** `account(request_compute|compute_status|release_compute)` removed — AWS cloud burst leases are gone. Use `account(status|history|add_funds)`. Capacity is shared LOCAL/GKE pools.
+- **Structured results + train hints (0.21.x, non-breaking):**
+  - **`results(action=get)`** returns **`structuredContent`** (job id/type, label, summary metrics, file list) alongside the text summary — same pattern as `training_monitor` / `results_explorer`. Agent hosts can read fields without parsing prose.
+  - **`train`** submit responses may include a **`results_hint`** string pointing agents to the next post-train step.
 - **Fixed-panel live TE (0.20.4):** mid-training TE curves use a fixed evaluation panel (`te_panel_size` on `train`). Monitors show **Panel TE** and **Map TE** separately; curve tail no longer snaps to map TE.
 - **Features (0.20.0, non-breaking):**
   - **FLooP-SIOM maps are now projectable.** `inference(action=project_columns)`, `inference(action=predict)`, and `datasets(action=add_expression, project_onto_job=<floop_job>)` work on FLooP-SIOM (free/chain) maps — values render onto the FLooP Voronoi layout instead of failing. Grid-only ops (`inference(action=transition_flow | impute_column | render_variant)`) return a clear `unsupported_topology_for_inference` message; use a fixed-grid SOM/SIOM for those. No client change required.

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 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`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, 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);
+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{resolvePrepareTrainingPrompt 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, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, 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})=>{const t=await M(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});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_status_format.js

@@ -70,6 +70,17 @@ export function formatJobStatusText(job_id, data) {
         if (epoch != null && totalEpochs != null && totalEpochs > 0) {
             parts.push(`epoch ${epoch}/${totalEpochs}`);
         }
+        const panelTe = data.panel_te != null && !Number.isNaN(Number(data.panel_te))
+            ? Number(data.panel_te)
+            : data.panel_topographic_error != null && !Number.isNaN(Number(data.panel_topographic_error))
+                ? Number(data.panel_topographic_error)
+                : null;
+        if (panelTe != null) {
+            parts.push(`panel_te: ${panelTe.toFixed(4)}`);
+        }
+        if (data.kernel_complete === true) {
+            parts.push("kernel_complete");
+        }
     }
     const datasetRows = data.dataset_rows != null ? Number(data.dataset_rows) : null;
     const datasetName = data.dataset_name != null ? String(data.dataset_name) : null;
@@ -120,6 +131,18 @@ export function formatJobStatusText(job_id, data) {
     else if (status === "cancelled") {
         parts.push(`Cancelled. Poll again to confirm; dataset and partial worker state are unchanged.`);
     }
+    const suggested = data.suggested_next_step != null && String(data.suggested_next_step) !== ""
+        ? String(data.suggested_next_step)
+        : status === "completed"
+            ? `results(action=get, job_id="${job_id}") then results_explorer(job_id="${job_id}")`
+            : status === "failed"
+                ? `Inspect failure_stage/error; fix data or params; resubmit train or jobs.`
+                : status === "running" || status === "pending"
+                    ? `jobs(action=status, job_id="${job_id}") again in 10–15s (or training_monitor).`
+                    : null;
+    if (suggested) {
+        parts.push(`suggested_next_step: ${suggested}`);
+    }
     return parts.join(" | ");
 }
 export function formatJobCancelText(job_id, data) {

package/dist/prepare_training_prompt.js

@@ -1,4 +1,5 @@
 import { apiCall } from "./shared.js";
+export const PREPARE_TRAINING_FALLBACK_VERSION = "2026.07-offline";
 const FALLBACK_LINES = [
     "Before upload: for train(action=map) ensure training columns have no NaNs; for train(action=impute) missing cells in training columns are OK (plain numeric only).",
     'Please run datasets(action=preview, dataset_id="{id}") to inspect columns, then datasets(action=analyze, dataset_id="{id}") to see which columns and temporal periods are most informative.',
@@ -9,16 +10,24 @@ const FALLBACK_LINES = [
     '- train(action=floop_siom, dataset_id="{id}", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain)',
 ];
 /** Used by the `prepare_training` MCP prompt; prefers tier-scoped text from the API when online. */
-export async function resolvePrepareTrainingPromptText(datasetId) {
-    let promptText = FALLBACK_LINES.join("\n").replaceAll("{id}", datasetId);
+export async function resolvePrepareTrainingPrompt(datasetId) {
+    const fallbackText = FALLBACK_LINES.join("\n").replaceAll("{id}", datasetId);
     try {
         const data = (await apiCall("GET", `/v1/docs/prepare_training?dataset_id=${datasetId}`));
         if (typeof data.prompt === "string" && data.prompt.trim()) {
-            promptText = data.prompt.trim();
+            return { text: data.prompt.trim(), used_fallback: false, fallback_version: null };
         }
     }
     catch {
-        // fallback
+        // fall through
     }
-    return promptText;
+    return {
+        text: fallbackText,
+        used_fallback: true,
+        fallback_version: PREPARE_TRAINING_FALLBACK_VERSION,
+    };
+}
+/** @deprecated Prefer resolvePrepareTrainingPrompt for structured fallback metadata. */
+export async function resolvePrepareTrainingPromptText(datasetId) {
+    return (await resolvePrepareTrainingPrompt(datasetId)).text;
 }

package/dist/shared.js

@@ -35,7 +35,7 @@ function newRequestId() {
  * 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.22.1";
+export const CLIENT_VERSION = "0.22.2";
 /** 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). */

package/dist/tools/account.js

@@ -2,28 +2,23 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall } from "../shared.js";
 export function registerAccountTool(server) {
-    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, add funds.
 
 | Action | Use when |
 |--------|----------|
 | status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |
-| request_compute | Upgrading to cloud burst (required for large grids or GPU). Leave tier blank to list options. |
-| compute_status | Checking if a burst lease is active and how much time remains |
-| release_compute | Manually terminating an active lease to stop billing |
-| history | Viewing recent compute leases and credit spend |
+| history | Viewing recent compute usage and credit spend |
 | add_funds | Getting instructions to add credits |
 
 action=status: Returns plan tier, compute class (CPU/GPU), usage limits, live queue state, training time estimates, and credit balance.
   Use BEFORE large jobs to check GPU availability and estimate wait time.
-action=request_compute: Provisions an ephemeral cloud burst EC2 instance. Data is in shared R2 — no re-upload needed. Wait ~3 min after requesting before submitting jobs.
-NOT FOR: Training itself — use train(action=map). This tool only manages the account and compute lease.`, {
+Capacity is shared LOCAL/GKE worker pools — there is no per-key cloud burst lease.
+NOT FOR: Training itself — use train(action=map). This tool only manages the account.`, {
         action: z
-            .enum(["status", "request_compute", "compute_status", "release_compute", "history", "add_funds"])
-            .describe("status: plan/license/queue info; request_compute: provision burst; compute_status: check active lease; release_compute: stop lease; history: recent compute usage; add_funds: instructions"),
-        tier: z.string().optional().describe("action=request_compute: tier ID — CPU: cpu-mini, cpu-2, cpu-8..cpu-48 (C7i); GPU: gpu-t4-small, gpu-t4..gpu-t4xxx, gpu-t4-12x (G4dn), gpu-p4d (P4d), gpu-l4, gpu-a10. Omit to list options."),
-        duration_minutes: z.number().optional().describe("action=request_compute: lease duration in minutes (default: 60)"),
+            .enum(["status", "history", "add_funds"])
+            .describe("status: plan/license/queue info; history: recent compute usage; add_funds: instructions"),
         limit: z.number().optional().describe("action=history: number of records to return (default: 10)"),
-    }, async ({ action, tier, duration_minutes, limit }) => {
+    }, async ({ action, limit }) => {
         if (action === "status") {
             const data = (await apiCall("GET", "/v1/system/info"));
             const plan = data.plan ?? {};
@@ -35,7 +30,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             const computeDesc = gpuEnabled ? (backend.gpu_model ? `GPU (${backend.gpu_model}${backend.gpu_vram_gb ? `, ${backend.gpu_vram_gb}GB` : ""})` : "GPU") : "CPU only";
             const fmtLimit = (v) => v === -1 || v === "-1" ? "unlimited" : String(v ?? "?");
             const historyData = await apiCall("GET", "/v1/compute/history?limit=5").catch(() => null);
-            const leaseData = await apiCall("GET", "/v1/compute/lease").catch(() => null);
             const algoNames = {
                 train_som: "SOM",
                 train_impute: "Imputation",
@@ -62,7 +56,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                     lines.push(`  Credits: $${(historyData.credit_balance_cents / 100).toFixed(2)} remaining`);
                 }
                 else {
-                    // Unknown billing mode: avoid misleading $0.00 for postpaid accounts
                     const cents = historyData.credit_balance_cents ?? 0;
                     if (cents === 0) {
                         lines.push(`  Credits: N/A (postpaid or zero balance — check plan)`);
@@ -74,9 +67,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             }
             if (backend.memory_gb)
                 lines.push(`  Backend Memory: ${backend.memory_gb} GB`);
-            if (leaseData && leaseData.lease_id) {
-                lines.push(``, `Active Burst Lease: ${leaseData.tier} | ${Math.round(leaseData.time_remaining_ms / 60000)} min left`);
-            }
             const running = Number(status.running_jobs ?? data.running_jobs ?? 0);
             const pending = Number(status.pending_jobs ?? data.pending_jobs ?? 0);
             const compute_eta = Number(estimates?.total || 0);
@@ -92,63 +82,6 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
             }
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
-        if (action === "request_compute") {
-            if (!tier) {
-                try {
-                    const tiersData = await apiCall("GET", "/v1/compute/tiers");
-                    const lines = ["Available Compute Tiers:"];
-                    for (const [tId, tData] of Object.entries(tiersData.tiers)) {
-                        lines.push(`  ${tId}: ${tData.desc}`);
-                    }
-                    return { content: [{ type: "text", text: lines.join("\n") }] };
-                }
-                catch (err) {
-                    const msg = err?.message ?? "Failed to fetch compute tiers. Ensure you have burst access enabled.";
-                    return { content: [{ type: "text", text: msg }] };
-                }
-            }
-            const data = await apiCall("POST", "/v1/compute/lease", { tier, duration_minutes });
-            const billingLine = data.billing_mode === "postpaid"
-                ? `Billing: Postpaid (usage logged, billed retrospectively)\nAccrued Balance: $${(data.credit_balance_cents / 100).toFixed(2)}`
-                : `Credits Remaining After Reserve: $${(data.credit_balance_cents / 100).toFixed(2)}`;
-            return {
-                content: [{ type: "text", text: `Compute Lease Requested:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Estimated Wait: ${data.estimated_wait_minutes} minutes
-Estimated Cost: $${(data.estimated_cost_cents / 100).toFixed(2)}
-${billingLine}
-
-IMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.` }]
-            };
-        }
-        if (action === "compute_status") {
-            const data = await apiCall("GET", "/v1/compute/lease");
-            if (data.status === "none" || !data.lease_id) {
-                return { content: [{ type: "text", text: "No active lease -- running on default Primary Server." }] };
-            }
-            return {
-                content: [{ type: "text", text: `Active Compute Lease:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Tier: ${data.tier} (${data.instance_type})
-Time Remaining: ${Math.round(data.time_remaining_ms / 60000)} minutes` }]
-            };
-        }
-        if (action === "release_compute") {
-            const data = await apiCall("DELETE", "/v1/compute/lease");
-            const costLine = data.billing_mode === "postpaid"
-                ? `Cost Logged: $${(data.cost_cents / 100).toFixed(2)} (postpaid — billed retrospectively)`
-                : `Credits Deducted: $${((data.credits_deducted || data.cost_cents) / 100).toFixed(2)}`;
-            return {
-                content: [{ type: "text", text: `Compute Released:
-Duration Billed: ${data.duration_minutes} minutes
-${costLine}
-Balance: $${(data.final_balance_cents / 100).toFixed(2)}
-
-Routing reverted to default Primary Server.` }]
-            };
-        }
         if (action === "history") {
             const data = await apiCall("GET", `/v1/compute/history?limit=${limit || 10}`);
             const history = data.history.map((h) => `- ${h.started_at} | ${h.tier} | ${h.duration_minutes} min | $${(h.credits_charged / 100).toFixed(2)}`).join("\n");
@@ -159,11 +92,11 @@ Routing reverted to default Primary Server.` }]
         if (action === "add_funds") {
             return {
                 content: [{ type: "text", text: `To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:
-bash scripts/manage-credits.sh add <org_id> <amount_usd>` }]
+bash scripts/billing/manage-credits.sh add <org_id> <amount_usd>` }]
             };
         }
         return {
-            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, request_compute, compute_status, release_compute, history, add_funds.` }]
+            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, add_funds.` }]
         };
     });
 }

package/dist/tools/datasets.js

@@ -4,7 +4,7 @@ import { gzipSync } from "node:zlib";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, POLL_ANALYZE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestDatasetPreview, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, structuredTextResult, pollUntilComplete, POLL_DERIVE_MAX_MS, POLL_ANALYZE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../job_status_format.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
@@ -481,10 +481,20 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     throw new Error("analyze did not return a job id");
                 const poll = await pollUntilComplete(jobId, POLL_ANALYZE_MAX_MS);
                 if (poll.status === "failed") {
-                    return { content: [{ type: "text", text: `datasets(analyze) job ${jobId} failed: ${poll.error ?? "unknown error"}` }] };
+                    const rid = poll.request_id;
+                    const errText = `datasets(analyze) job ${jobId} failed: ${poll.error ?? "unknown error"}`;
+                    return structuredTextResult({
+                        error: true,
+                        action: "analyze",
+                        job_id: jobId,
+                        request_id: rid ?? null,
+                        message: errText,
+                        suggested_next_step: "If the dataset is very large, try datasets(action=subset, sample_n=10000) then analyze again.",
+                    }, errText + (rid ? ` (request_id=${rid})` : ""));
                 }
                 if (poll.status !== "completed") {
-                    return { content: [{ type: "text", text: `datasets(analyze) job ${jobId} is still running. Poll with jobs(action=status, job_id="${jobId}") then results(action=get, job_id="${jobId}").` }] };
+                    const text = `datasets(analyze) job ${jobId} is still running. Poll with jobs(action=status, job_id="${jobId}") then results(action=get, job_id="${jobId}").`;
+                    return structuredTextResult({ error: false, action: "analyze", job_id: jobId, status: poll.status, message: text }, text);
                 }
                 const results = (await apiCall("GET", `/v1/results/${jobId}`));
                 data = (results.summary ?? results);

package/package.json

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