@barivia/barsom-mcp 0.7.13 → 0.8.0

package/README.md

@@ -1,6 +1,8 @@
 # @barivia/barsom-mcp
 
-MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. **`guide_barsom_workflow`** is the canonical bootstrap: it fetches **`GET /v1/docs/workflow`** (authenticated) and returns tier-scoped text — proxy model, tool map, async rules, training modes allowed for your key, and step-by-step SOP. If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `jobs` (`train_map`, `train_siom_map`, `train_floop_siom` where entitled; `train_floop_chain` is deprecated), `results`, and `inference`. **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer` / `explore_map`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results.
+MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. The npm package is **`@barivia/barsom-mcp`**; many configs label the server **`analytics-engine`** (the MCP server name in the client JSON). **`guide_barsom_workflow`** is the canonical bootstrap: it loads plan-scoped workflow text from the Barivia API when online (tool map, async rules, training modes, SOP). If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `jobs` (`train_map`, `train_siom_map`, `train_floop_siom` where entitled; `train_floop_chain` is deprecated), `results`, and `inference`. **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results.
+
+**Pre-training help (pick one):** **`prepare_training`** prompt = narrative checklist (tier-scoped from the API when online); **`training_guidance`** tool = structured presets and parameter hints; **`training_prep`** tool = interactive UI plus **`submit_prepared_training`**.
 
 ## Installation
 
@@ -27,6 +29,8 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 
 **Also available:** hosted HTTP MCP at **`https://mcp.barivia.se/mcp`** (same API key; no npm) for clients that support remote MCP.
 
+**Cursor / multi-account note:** Cursor's tool dispatcher resolves tools under a `serverIdentifier` (e.g. `user-barivia-bbb-maps`), which can differ from the key you wrote in `mcp.json` (e.g. `barivia-bbb-maps`). If a tool call fails with **"server does not exist"** or similar, list the resolved identifier with your client's tool inspector (`mcp.list-tools` or equivalent) and use that identifier — not the `mcp.json` key.
+
 **Future:** A **private npm org** scoped package is an option later (paid npm teams/orgs; users authenticate with npm, usually simpler than GitHub Packages for pure npm consumers).
 
 ## Environment Variables
@@ -38,19 +42,43 @@ MCP clients typically run it with **`npx`** (downloads on first use):
 | `BARIVIA_WORKSPACE_ROOT` | No | `process.cwd()` or `PWD` | Directory for relative `file_path` and `save_to_disk`. In Cursor MCP, `process.cwd()` is often the MCP install dir — add `BARIVIA_WORKSPACE_ROOT` to your MCP config `env` with your project path (e.g. `/home/user/myproject`). Absolute paths and `file://` URIs work without it. |
 | `BARIVIA_FETCH_TIMEOUT_MS` | No | `30000` | Per-request HTTP timeout (ms) to the API. Increase (e.g. `120000`) on slow networks or when the API does long-running work. Large dataset uploads use a separate longer timeout internally. |
 | `BARIVIA_VIZ_PORT` | No | OS-assigned | When the client has no MCP Apps support, the proxy may start a local viz server on `127.0.0.1`; set a fixed port if you need stable bookmark URLs. |
+| `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | No | `1` (enabled) | File uploads are constrained to the MCP workspace root by default. Set to `0` or `false` to allow absolute paths anywhere on the machine (high trust). **Changed in v0.x:** previously defaulted to off; now on for security. If uploads fail with "paths outside the workspace are disabled", either set `BARIVIA_WORKSPACE_ROOT` to cover your data directory, or opt out with `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0`. |
 
 Legacy `BARSOM_API_KEY` / `BARSOM_API_URL` / `BARSOM_WORKSPACE_ROOT` are also accepted as fallbacks.
 
+### Trust model (who are we trusting?)
+
+- **API key** — Anyone with your key can access your tenant on the Barivia API like any other HTTP client. The proxy does not add a separate authorization layer.
+- **Local machine** — The process runs with **your** OS user. File uploads are now sandboxed to the workspace root by default (`BARIVIA_ENFORCE_WORKSPACE_SANDBOX=1`). Set `BARIVIA_WORKSPACE_ROOT` to your project directory; use `BARIVIA_ENFORCE_WORKSPACE_SANDBOX=0` only if you need unrestricted absolute-path access.
+- **Logs** — stderr may include API paths and tool activity; do not log secrets in MCP client configs.
+
 **Supported stack:** Node **18+** (see `engines` in `package.json`). Built with `@modelcontextprotocol/sdk` **^1.x** — if a major MCP client upgrade breaks tools, check SDK release notes alongside this package version.
 
 **Local viz fallback:** If the IDE does not advertise MCP Apps, the proxy starts an HTTP server bound to **127.0.0.1** only (not exposed to the LAN). It serves built-in HTML for training prep / monitor / results explorer and proxies read-only API calls with your existing API key. Responses may include `http://127.0.0.1:<port>/viz/...` links. Browser `Access-Control-Allow-Origin: *` applies only to that localhost origin so the embedded pages can load data.
 
-## Tools (14 registrations)
+## Tools and prompts (15 tools + 2 prompts)
+
+All multi-action tools follow the `datasets` / `jobs` / `results` / `inference` / `account` pattern: a required `action` enum routes to the correct operation.
+
+**Prompts (not tools):** `info` (short orientation; prefer `guide_barsom_workflow` for depth), `prepare_training` (requires `dataset_id`; checklist text from API when online).
+
+### Flattened catalog (optional grouping in UIs)
 
-All multi-action tools follow the `datasets` pattern: a required `action` enum routes to the correct operation.
+| Section | Items |
+|--------|--------|
+| Bootstrap | `guide_barsom_workflow`, prompts `info`, `prepare_training` |
+| Data | `datasets` |
+| Train & poll | `jobs`, `submit_prepared_training` (after `training_prep`), `training_monitor` (optional) |
+| Results | `results`, `results_explorer` (optional) |
+| Inference | `inference` |
+| Account | `account` |
+| Optional UI | `training_prep`, `training_monitor`, `results_explorer` |
+| Advanced / legacy | `training_guidance`, `explore_map` (deprecated alias) |
+
+Agents should not call **`_fetch_figure`** from chat; it exists for the Results Explorer MCP App host. Use `results(action=get)` or `results_explorer` instead.
 
 ### `guide_barsom_workflow`
-Call at the **start of mapping work** (or when the user asks what the MCP can do). Loads full orientation from the API (`GET /v1/docs/workflow`); content reflects **your plan** (`allowed_job_types`). No parameters. **`training_guidance`** uses `GET /v1/training/config` with the same entitlement filtering.
+Call at the **start of mapping work** (or when the user asks what the MCP can do). Returns plan-scoped orientation from the Barivia API when online. No parameters. **`training_guidance`** returns JSON presets and hints with the same entitlement filtering.
 
 ### `datasets(action)`
 
@@ -62,6 +90,7 @@ Call at the **start of mapping work** (or when the user asks what the MCP can do
 | `list` | Finding dataset IDs |
 | `subset` | Creating a filtered/sliced copy (row_range, filter conditions) |
 | `add_expression` | Add a derived column from an expression (formula → new column on the dataset) |
+| `reduce_spectral` | Pre-training reducer for long ordered numeric blocks (spectra, time series, sensor fingerprints, gene panels). Methods: **pca** (top-k principal components), **log_sample** (k columns at log-spaced indices — scattering, audio bands), **uniform_sample** (k columns at evenly-spaced indices — regularly-sampled time series), **stats** (6 fixed per-row summary columns). All produce one feature vector per row; appends derived columns to the dataset. |
 | `delete` | Removing a dataset |
 
 ### `jobs(action)`
@@ -97,11 +126,10 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 | Action | Output | Timing |
 |--------|--------|--------|
-| `predict` | predictions.csv: per-row bmu_x/y, cluster_id, quantization_error, potential_anomaly (QE > 95th pct); summary includes qe_p95 | 5–120s |
-| `enrich` | enriched.csv: training data + bmu_x/y/node_index/cluster_id | 5–60s |
+| `predict` | Score rows against the trained map. **Inputs:** `dataset_id` (defaults to the parent training dataset) **or** inline `rows` (≤500). **Output style** (`output` param): `"compact"` → `predictions.csv` (row_id, bmu_x/y, bmu_node_index, cluster_id [+ QE / qe_p95 / potential_anomaly when scoring **new** data]); `"annotated"` → `enriched.csv` (original CSV + BMU columns appended). **Regime auto-detected:** when the resolved dataset matches the training dataset, QE columns are intentionally omitted in compact output (training-set fit ≠ generalisation; the p95 anomaly flag would be circular). Prefer `dataset_id` for batches and SIOM/irregular maps. | 5–120s |
 | `compare` | density-diff heatmap + top gained/lost nodes — drift, A/B, cohort | 30–120s |
 | `project_columns` | Project one or more dataset columns onto the trained map (component planes) | async |
-| `report` | comprehensive PDF: metrics, views, component grid, cluster table | 30–180s |
+| `report` | Report **manifest** (figure names, download URLs, metrics, cluster summary) — sync; use with `results(download)` on the training `job_id` for `report.pdf` when present; build custom PDFs in Quarto/Jupyter | immediate |
 
 ### `account(action)`
 
@@ -118,14 +146,31 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 | Tool | Role |
 |------|------|
-| `training_prep` | Review variables, transforms, hyperparameters before submit; use with `submit_prepared_training` |
+| `training_prep` | Review variables, transforms, hyperparameters before submit |
+| `submit_prepared_training` | Submit the reviewed prep (`review_token` + `explicit_confirm=true`) |
 | `training_monitor` | Visual progress for a `job_id`; optional — `jobs(action=status)` is enough |
 | `results_explorer` | Browse metrics and figures after training completes |
-| `explore_map` | Legacy alias of `results_explorer` |
-| `_fetch_figure` | Internal helper for Results Explorer (single figure as image) |
+| `explore_map` | **Deprecated** — alias of `results_explorer`; migrate configs to `results_explorer` |
+| `_fetch_figure` | **Host / App only** — Results Explorer invokes this for one raster figure; not for agent chat |
 
 When the client does not advertise MCP Apps support, the proxy starts **`viz-server`** on **`127.0.0.1`** (localhost-only). Tool responses can include `http://127.0.0.1:PORT/viz/...` links. See **Local viz fallback** under Environment Variables.
 
+#### Choosing where to view results
+
+The right viewer depends on **(MCP App support)** **and** **(can the human reach the proxy's `127.0.0.1`)** — not on whether the agent is "text" or "GUI".
+
+| Path | When to use | Caveats |
+|------|-------------|---------|
+| **Embedded MCP App** (`ui://barsom/results-explorer`) | Client supports MCP Apps (Cursor, Claude Desktop with App support). Preferred default. | None of the topology issues below — transported over the MCP channel. Works for local proxy, remote SSH proxy, or container. |
+| **Localhost `viz-server` link** | MCP Apps unsupported AND the human user is on the same host as the proxy (typical local Cursor + local stdio proxy). | Ephemeral port (lost on proxy restart). **Unreachable** when the proxy runs on a remote SSH host while the user is elsewhere, in a container with no port forwarding, or behind a strict host firewall. Pure text agents on the same host CAN use this path — the user just clicks the link. |
+| **`results(action=get)` text-only path** | Always works. Use when (a) the agent is headless / autonomous (no human to click anything) or (b) proxy and user are on different hosts and MCP Apps is unsupported. With **`figures="none"`** it's also the leanest path for parameter sweeps and LLM clients (no image payloads). | Returns metrics text and inline images via MCP content; never starts a server. |
+
+### Migration notes
+
+- **`explore_map` → `results_explorer`:** Update Cursor, Claude Desktop, or other MCP configs that still reference `explore_map`. The alias remains for backward compatibility.
+- **`inference(action=enrich)` → `inference(action=predict, output="annotated")`:** the `enrich` action has been removed in favor of regime-aware `predict`. Calling `predict` with `output="annotated"` (and the default training dataset) returns the same `enriched.csv` artifact. Calling `predict` on the training dataset with the default `output="compact"` now correctly omits QE / `qe_p95` / `potential_anomaly` fields — those are fitting errors on training data, not generalisation metrics.
+- **Shorter `info` prompt:** Clients that relied on the old long `info` text should use **`guide_barsom_workflow`** or server **instructions** for the full story.
+
 ### `send_feedback`
 Submit feedback or feature requests (max 1400 characters, ~190 words).
 
@@ -168,8 +213,11 @@ cd apps/mcp-proxy
 npm install
 npm run dev      # Run with tsx (hot reload)
 npm run build    # Compile to dist/
+npm test         # Vitest
 ```
 
+**Post-change spot-check (real MCP client):** confirm `guide_barsom_workflow` appears near the top of the tool list, `explore_map` still works as an alias of `results_explorer`, and Results Explorer can still load figures (it uses `_fetch_figure` internally — agents should rely on `results` / `results_explorer`).
+
 For local development against a local API stack:
 
 ```bash
@@ -199,7 +247,7 @@ From the platform root:
 
 ```bash
 cd barivia-platform
-bash scripts/check-mcp-proxy-publish.sh
+bash scripts/checks/check-mcp-proxy-publish.sh
 ```
 
 Compares local `build:publish` output to the tarball on **public npm**. Exit 0 = match; exit 1 = diff. `VERBOSE=1` for a full `dist/` diff.

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 a,registerAppResource as i,RESOURCE_MIME_TYPE as r}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as s,apiCall as l,apiRawCall as c,loadViewHtml as p,setVizPort as d,setClientSupportsMcpApps as m}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as f,JOBS_DESCRIPTION_BASE as g}from"./tools/jobs.js";import{registerResultsTool as h}from"./tools/results.js";import{registerExploreMapTool as _,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as y}from"./tools/account.js";import{registerInferenceTool as w}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as k}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as P}from"./tools/training_monitor.js";s||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const O=new e({name:"analytics-engine",version:"0.7.10",instructions:"# Barivia Mapping Analytics Engine\n\nYou have access to a mapping (Self-Organizing Map) analytics platform that projects high-dimensional data onto a 2D grid, revealing clusters, gradients, and anomalies.\n\n## Typical workflow\n\n1. **Upload** → `datasets(action=upload)` — ingest a CSV\n2. **Preview** → `datasets(action=preview)` — inspect columns, detect cyclics/datetimes; add derived columns with `datasets(action=add_expression)` if needed\n3. **Train** → choose one:\n   - `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM\n   - `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization\n   - `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM when the plan includes all_algorithms (Premium or Enterprise; default topology=free / CHL; optional topology=chain)\n   Returns a job_id; poll `jobs(action=status, job_id=...)` until completed\n4. **Analyze** → `results(action=get)` — view metrics and figures (grid-map or FLooP-specific; no separate analyze tool)\n5. **Compare / Export / Inference** → `jobs(action=compare)`, `results(download)`, `inference` (predict/enrich/compare/report)\n\nFor **proxy model, full tool map, async rules, training modes (tier-scoped), and optional MCP App UIs**, call `guide_barsom_workflow` first—it loads the ground-truth bootstrap from the API (`GET /v1/docs/workflow`; this section stays short on purpose).\n\n## Tool categories\n\n| Category | Tools |\n|----------|-------|\n| Data management | `datasets` (upload/preview/list/subset/delete/add_expression) |\n| Jobs & training | `jobs` (train_map/train_siom_map/train_floop_siom/status/list/compare/cancel/delete/batch_predict; deprecated alias train_floop_chain) |\n| Results | `results` (get/recolor/download/export/transition_flow) |\n| Inference & export | `inference` (predict/enrich/compare/report/project_columns) |\n| Account | `account` (status/request_compute/compute_status/release_compute/history/add_funds) |\n| Utility | `guide_barsom_workflow`, `training_guidance`, `training_prep`, `results_explorer`, `training_monitor`, `send_feedback` |\n\n## Optional rich UI (MCP Apps)\n\n**None of these are required** to train, poll, or read results—`jobs` + `results` + text output are enough. **Recommended** for learning: `training_prep` (preparation), `results_explorer` (postprocessing). **Optional:** `training_monitor(job_id)` for visual progress; `jobs(action=status)` is sufficient without it.\n\n## Async job pattern\n\nMost operations are async. Every tool that submits a job either:\n- **Auto-polls** (results(recolor/transition_flow), inference) — waits up to the action-specific timeout then returns or gives a job_id for manual polling\n- **Returns immediately** (jobs(action=train_map/train_siom_map/train_floop_siom)) — always requires manual `jobs(action=status, job_id=...)` polling (`train_floop_chain` is a deprecated alias for `train_floop_siom`)\n\n**Do not tell the user a job failed because it is still running.** If a tool returns a job_id, poll `jobs(action=status)` every 10–15 seconds. Grid-map training takes 30s–10min depending on grid size and dataset; FLooP-SIOM jobs can also take several minutes for larger `max_nodes` or `thorough` runs.\nFor FLooP-SIOM, `max_nodes` is a total node budget, not a grid side length. If omitted, the backend uses a dataset-size heuristic; reduce `max_nodes` before increasing `effort` when coverage looks collapsed.\n\n## Credit and cost\n\nJobs consume compute credits. Inference jobs are priced the same as projection jobs. Check `account(action=status)` to see the remaining balance and queue depth before starting large jobs.\n\n## Key constraints\n\n- For parameter guidance (grid, epochs, presets, when to use standard SOM vs SIOM vs FLooP-SIOM), use `training_guidance` or `prepare_training` — do not guess.\n- Column names are case-sensitive; always match exactly what `datasets(action=preview)` returns\n- Uploads may include text/categorical columns, but the default training path is still numeric/cyclic/temporal. If a categorical column truly matters, use explicit `categorical_features` for simple baseline encoding.\n- `predict` input must match the model's supported inference contract. Numeric/batch predict expects the training feature set; single-row stateless inference can also accept raw categorical strings for baseline `categorical_features` models."});i(O,b,b,{mimeType:r},async()=>{const e=await p("results-explorer");return{contents:[{uri:b,mimeType:r,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),i(O,k,k,{mimeType:r},async()=>{const e=await p("training-prep");return{contents:[{uri:k,mimeType:r,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),i(O,P,P,{mimeType:r},async()=>{const e=await p("training-monitor");return{contents:[{uri:P,mimeType:r,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),_(O),I(O),M(O),j(O),u(O),f(O,g),h(O),y(O),w(O),v(O),x(O),O.prompt("info","Overview of the Barivia Mapping MCP: capabilities, workflow, tools, analysis types, and tips. Use when the user asks what this MCP can do, how to get started, or what the process is.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Inform the user using this overview:","","**What it is:** Barivia MCP connects you to a mapping analytics engine that learns a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.","","**Orientation:** Call `guide_barsom_workflow` first for proxy model, full tool list, async rules, training modes, and optional MCP App UIs (defer long-form detail there).","","**Core workflow:**","0. **Prepare** — CSV with header; no NaNs in used columns; numeric and datetime columns are the default training path; raw categoricals can stay in the CSV but should usually be excluded unless you explicitly use simple `categorical_features` encoding","1. **Upload** — `datasets(action=upload)` with a CSV file path or inline data","2. **Preview** — `datasets(action=preview)` to inspect columns, stats, and detect cyclic/datetime fields","3. **Prepare** — use the `prepare_training` prompt for a guided checklist (column selection, transforms, cyclic encoding, feature weights, grid sizing)","4. **Train** — choose one: `jobs(action=train_map, dataset_id=...)` for a standard fixed-grid SOM, `jobs(action=train_siom_map, dataset_id=...)` for a fixed-grid SIOM with coverage regularization, or `jobs(action=train_floop_siom, dataset_id=...)` for FLooP-SIOM only on Premium / Enterprise (`all_algorithms`; default topology=free / CHL; optional topology=chain). Use `preset=quick|standard|refined|high_res` for standard or SIOM map defaults","5. **Monitor** — `jobs(action=status, job_id=...)` every 10–15s until complete (required path). Optional: `training_monitor(job_id=...)` for a visual panel—not required.","6. **View and interpret** — `results(action=get)` returns metrics and figures. Grid-map jobs show U-matrix, component planes, and clusters; FLooP-SIOM jobs show structure/coverage, occupation/profile views, and metrics. Optional: `results_explorer(job_id=...)` for interactive browsing; `results(action=get)` alone is enough.","7. **Feedback** — Ask the user if they'd like to submit feedback via `send_feedback` based on their experience.","8. **Iterate** — `results(action=recolor)` to change colormap, `jobs(action=compare)` to compare hyperparameters, `inference(action=project_columns)` to overlay dataset columns onto the map","","All visualizations and metrics come from `results(action=get)`; use figures=all or export_type=... for more.","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `datasets(action=add_expression)` — create computed columns from expressions (ratios, differences, etc.)","- `inference(action=project_columns)` — overlay one or more dataset columns onto a trained map (component planes)","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, hsv, twilight, etc.) can be set at training or changed later via results(action=recolor).","","**Key tools:** datasets, jobs (train_map/train_siom_map/train_floop_siom/status/list/...), results, inference (predict/enrich/compare/project_columns/report), account, guide_barsom_workflow, training_guidance, training_prep, results_explorer, training_monitor.","","**Optional rich UI:** `training_prep` and `results_explorer` are recommended for prep and postprocessing; `training_monitor` is optional. None are required—`jobs` + `results` complete the workflow.","","**Tips:**","- For the full step-by-step SOP and capabilities text (from the API, scoped to your plan), use the `guide_barsom_workflow` tool","- Always `datasets(action=preview)` before training to understand your data","- Use `account(action=status)` to check GPU availability, queue depth, and plan limits before large jobs","- Start with `preset=quick` for fast iteration, then `refined` for publication quality","- For time-series data, consider `transition_flow` after training","","Keep the reply scannable with headers and bullet points."].join("\n")}}]})),O.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling jobs(action=train_map), jobs(action=train_siom_map), or jobs(action=train_floop_siom) when entitled. Walks through data inspection, column selection, transforms, cyclic/temporal features, weighting, subsetting, and grid sizing.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{let t=`Please run datasets(action=preview, dataset_id="${e}") to inspect columns, then datasets(action=analyze, dataset_id="${e}") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id="${e}", ...) for a standard fixed-grid SOM, jobs(action=train_siom_map, dataset_id="${e}", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id="${e}", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).`;try{const o=await l("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}});const C=new t;(async function(){try{const e=await n(l,c,p);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=O.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=a(t);m(!!o?.mimeTypes?.includes(r))},await O.connect(C)})().catch(console.error);
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as n,RESOURCE_MIME_TYPE as a}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as s}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as f,JOBS_DESCRIPTION_BASE as g}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as w}from"./tools/account.js";import{registerInferenceTool as y}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as P}from"./tools/feedback.js";import{registerTrainingPrepTools as x,TRAINING_PREP_URI as I}from"./tools/training_prep.js";import{registerTrainingMonitorTool as k,TRAINING_MONITOR_URI as M}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as O}from"./prepare_training_prompt.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const S=new e({name:"analytics-engine",version:"0.8.0",instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `jobs(train_map)`, `jobs(train_siom_map)`, or `jobs(train_floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool). Then `jobs(compare)`, `results(download/recolor/transition_flow)`, or `inference` as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool map (compact)\n\n| Area | Tool | Notes |\n|------|------|--------|\n| Data | `datasets` | upload, preview, analyze, list, subset, add_expression, reduce_spectral (pca/log_sample/uniform_sample/stats for long ordered numeric blocks), delete |\n| Jobs | `jobs` | train_map, train_siom_map, train_floop_siom (entitled), status, list, compare, cancel, delete, batch_predict, run_baseline_study; `train_floop_chain` = deprecated alias for train_floop_siom |\n| Results | `results` | get (figures="none" for metrics-only), export, download, recolor (async), transition_flow (async; time-ordered rows only) |\n| Inference | `inference` | predict (regime-aware; output="compact"|"annotated"; "annotated" replaces the removed `enrich`), compare, project_columns, report |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow` | orientation + SOP |\n| Parameters | `training_guidance` | presets and field hints (API-scoped) |\n| Prep | `prepare_training` prompt, `training_prep` + `submit_prepared_training` | checklist / interactive UI |\n| Explore | `results_explorer`, `training_monitor` | optional MCP Apps; `explore_map` = deprecated alias of `results_explorer`; `jobs(status)` and `results(get)` suffice without them |\n| Other | `send_feedback` | only after user agrees |\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions, `results(recolor)`, `results(transition_flow)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Slow networks: users can raise `BARIVIA_FETCH_TIMEOUT_MS`.\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints; `training_prep` = UI + guarded submit. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `recolor`, `transition_flow`, or `project_columns`, use the **new** `job_id` returned for follow-up `results` if applicable.'});n(S,b,b,{mimeType:a},async()=>{const e=await c("results-explorer");return{contents:[{uri:b,mimeType:a,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(S,I,I,{mimeType:a},async()=>{const e=await c("training-prep");return{contents:[{uri:I,mimeType:a,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(S,M,M,{mimeType:a},async()=>{const e=await c("training-monitor");return{contents:[{uri:M,mimeType:a,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),j(S),h(S),x(S),k(S),u(S),f(S,g),_(S),w(S),y(S),v(S),P(S),S.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool).","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `jobs` (train/poll/compare/…; train_map accepts an optional `label` for readable compare rows), `results` (get/download/export/recolor/transition_flow; figures="none" for metrics-only), `inference` (predict regime-aware with output="compact"|"annotated"; replaces enrich, compare, project_columns, report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints) · `training_prep` + `submit_prepared_training` (interactive UI).","","**Optional UI:** `results_explorer`, `training_monitor` — nice for browsing; not required if you use `results` + `jobs(status)`.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `transition_flow` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),S.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints; training_prep tool = interactive UI + submit_prepared_training.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await O(e)}}]}));const A=new t;(async function(){try{const e=await s(l,p,c);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=S.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(a))},await S.connect(A)})().catch(console.error);

package/dist/prepare_training_prompt.js

@@ -0,0 +1,16 @@
+import { apiCall } from "./shared.js";
+const FALLBACK_PREFIX = "Please run datasets(action=preview, dataset_id=\"{id}\") to inspect columns, then datasets(action=analyze, dataset_id=\"{id}\") to see which columns and temporal periods are most informative. Then choose the training path: jobs(action=train_map, dataset_id=\"{id}\", ...) for a standard fixed-grid SOM, jobs(action=train_siom_map, dataset_id=\"{id}\", ...) for a fixed-grid SIOM, or jobs(action=train_floop_siom, dataset_id=\"{id}\", ...) for FLooP-SIOM (default topology=free / CHL; optional topology=chain).";
+/** Used by the `prepare_training` MCP prompt; prefers tier-scoped text from the API when online. */
+export async function resolvePrepareTrainingPromptText(datasetId) {
+    let promptText = FALLBACK_PREFIX.replaceAll("{id}", datasetId);
+    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();
+        }
+    }
+    catch {
+        // fallback
+    }
+    return promptText;
+}

package/dist/shared.js

@@ -104,10 +104,17 @@ export function sandboxPath(userPath, root) {
     }
     return resolved;
 }
+function enforceWorkspaceSandboxUpload() {
+    const v = process.env.BARIVIA_ENFORCE_WORKSPACE_SANDBOX ?? "1";
+    if (v === "0" || v.toLowerCase() === "false")
+        return false;
+    return true;
+}
 /**
  * Resolves file_path for dataset upload. Security: auth before read, generic errors, reject "..".
  * Accepts: absolute paths, file:// URIs, relative paths (resolved against workspace root).
  * Pre-security-patch behavior: absolute paths worked without BARIVIA_WORKSPACE_ROOT.
+ * Set BARIVIA_ENFORCE_WORKSPACE_SANDBOX=1 to require absolute paths to lie under the resolved workspace root.
  */
 export async function resolveFilePathForUpload(filePath, mcpServer) {
     const trimmed = filePath.trim();
@@ -120,15 +127,52 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
             if (url.protocol !== "file:" || (url.hostname && url.hostname !== "localhost")) {
                 throw new Error("Only local file:// URIs are allowed (no remote hosts).");
             }
-            return fileURLToPath(trimmed);
+            const p = fileURLToPath(trimmed);
+            if (enforceWorkspaceSandboxUpload()) {
+                const root = await getWorkspaceRootAsync(mcpServer);
+                const real = await fs.realpath(p);
+                const realRoot = await fs.realpath(root);
+                if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+                    throw new Error(`file:// paths outside the workspace are disabled (BARIVIA_ENFORCE_WORKSPACE_SANDBOX). Workspace: ${realRoot}`);
+                }
+                const stat = await fs.stat(real);
+                if (!stat.isFile()) {
+                    throw new Error("Path must be a regular file, not a directory.");
+                }
+                return real;
+            }
+            return p;
         }
         catch (err) {
             if (err instanceof Error && err.message.includes("remote hosts"))
                 throw err;
+            if (err instanceof Error && err.message.includes("BARIVIA_ENFORCE_WORKSPACE_SANDBOX"))
+                throw err;
+            if (err instanceof Error && err.message.includes("regular file"))
+                throw err;
             throw new Error("Invalid file:// URI. Use a path like file:///path/to/your/file.csv");
         }
     }
     if (path.isAbsolute(trimmed)) {
+        if (enforceWorkspaceSandboxUpload()) {
+            const root = await getWorkspaceRootAsync(mcpServer);
+            let real;
+            try {
+                real = await fs.realpath(trimmed);
+            }
+            catch {
+                throw new Error(`File not accessible at absolute path. With BARIVIA_ENFORCE_WORKSPACE_SANDBOX, use a path under the workspace root (${root}).`);
+            }
+            const realRoot = await fs.realpath(root);
+            if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+                throw new Error(`Absolute paths outside the workspace are disabled (BARIVIA_ENFORCE_WORKSPACE_SANDBOX). Workspace root: ${realRoot}`);
+            }
+            const stat = await fs.stat(real);
+            if (!stat.isFile()) {
+                throw new Error("Path must be a regular file, not a directory.");
+            }
+            return real;
+        }
         return trimmed;
     }
     const root = await getWorkspaceRootAsync(mcpServer);
@@ -183,10 +227,16 @@ export function formatApiErrorMessage(status, bodyText, requestId) {
                         : status === 409
                             ? " The job may not be in the expected state."
                             : status === 429
-                                ? " Rate limit exceeded — wait a moment and retry."
-                                : status >= 500
-                                    ? " Server error — retry later."
-                                    : "";
+                                ? " Plan limit (e.g. dataset cap) or rate limit — read the error above; delete unused datasets or wait and retry."
+                                : status === 502
+                                    ? " Object storage (R2/S3) error from API — retry later."
+                                    : status === 503
+                                        ? parsed?.error_code === "system_info_unavailable"
+                                            ? " System info (plan/queue) temporarily unavailable — retry later."
+                                            : " API or database temporarily unavailable — retry later."
+                                        : status >= 500
+                                            ? " Server error — retry later."
+                                            : "";
     const rid = ` (request id: ${requestId} — include if contacting support)`;
     return `${detail}${code}${hint}${rid}`;
 }
@@ -460,6 +510,9 @@ export async function tryAttachImage(content, jobId, filename) {
 }
 /** Resolve get_results figures param to list of image filenames to fetch. */
 export function getResultsImagesToFetch(jobType, summary, figures, includeIndividual) {
+    // Metrics-only mode: skip every image fetch (sweeps and LLM clients).
+    if (figures === "none")
+        return [];
     const ext = summary.output_format ?? "pdf";
     if (jobType === "transition_flow") {
         const lag = summary.lag ?? 1;

package/dist/tools/datasets.js

@@ -13,6 +13,7 @@ export function registerDatasetsTool(server) {
 | list | Finding dataset IDs for train_map, preview, or subset — see all available datasets |
 | subset | Creating a filtered/sliced view without re-uploading the full CSV |
 | add_expression | Add a computed column from an expression (same as project(expression) without project_onto_job) — dataset_id + name + expression |
+| reduce_spectral | Collapse a long ordered numeric block (e.g. 1000-point spectrum, time series, sensor fingerprint) into a small per-row feature set so the SOM can train on signal-dense features. Methods: pca, log_sample, uniform_sample, stats. |
 | delete | Cleaning up after experiments or freeing the dataset slot |
 
 action=upload: PREFER file_path — server reads from workspace root (token-efficient; no file content in context). Use csv_data only for small inline pastes (e.g. <10KB). Returns dataset ID. Then use datasets(action=preview) before jobs(action=train_map).
@@ -30,14 +31,20 @@ action=subset: Create a new dataset from a subset of an existing one. Requires n
     Examples: { column: "region", op: "eq", value: "Europe" } | { column: "age", op: "between", value: [18, 65] }
   - Combine row_range + filters to slice both rows and values.
   - Single filter object is also accepted (auto-wrapped).
+action=reduce_spectral: Run a pre-training reducer over an ordered block of numeric columns. All four methods produce one feature vector per row (rows in = rows out; only the column dimension is collapsed) and append derived columns to the dataset. Choose by data shape:
+  - pca:            top-k principal components — general first try when many columns are correlated (spectroscopy, gene panels, sensor arrays). Returns explained_variance_ratio.
+  - log_sample:     keep k columns at log-spaced indices — SAXS/scattering, audio frequency bands, attenuation curves (anywhere the index axis is logarithmically informative).
+  - uniform_sample: keep k columns at evenly-spaced indices — regularly-sampled time series, frame-by-frame features, evenly-binned histograms.
+  - stats:          6 fixed per-row statistics (mean, std, min, max, skew, integral) — cheap baseline for any sequenced numeric block; k is ignored.
+  Required params: name (prefix for derived columns), method, columns_block (ordered source column names ≥ 2), k (≥ 1, < length(columns_block); ignored for stats).
 action=delete: Remove a dataset and all S3 data permanently.
 
 BEST FOR: Tabular numeric data. CSV with header required.
 NOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.
 ESCALATION: If upload fails with column errors, open the file locally and verify the header row. If preview shows unexpected nulls, the user must clean the CSV before training.`, {
         action: z
-            .enum(["upload", "preview", "analyze", "list", "subset", "delete", "add_expression"])
-            .describe("upload: add CSV; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression"),
+            .enum(["upload", "preview", "analyze", "list", "subset", "delete", "add_expression", "reduce_spectral"])
+            .describe("upload: add CSV; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression; reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
         name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
         file_path: z.string().optional().describe("Path to local CSV (PREFERRED): absolute path, file:// URI, or relative to workspace root. Token-efficient; server reads file."),
         csv_data: z.string().optional().describe("Inline CSV string for small pastes only (<10KB). Avoid for large files — use file_path instead to avoid token explosion."),
@@ -81,7 +88,21 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
         })
             .optional()
             .describe("action=add_expression: evaluation options (missing, window for rolling)"),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options }) => {
+        method: z
+            .enum(["pca", "log_sample", "uniform_sample", "stats"])
+            .optional()
+            .describe("action=reduce_spectral: pca = top-k principal components (general first try); log_sample = k columns at log-spaced indices (scattering, audio bands, attenuation); uniform_sample = k columns at evenly-spaced indices (regularly-sampled time series); stats = 6 fixed per-row summary columns (mean, std, min, max, skew, integral; k ignored)"),
+        columns_block: z
+            .array(z.string())
+            .optional()
+            .describe("action=reduce_spectral: ordered list of source column names representing the block (≥ 2; ≥ k+1 for non-stats methods)"),
+        k: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("action=reduce_spectral: output dimensionality. Required for pca/log_sample/uniform_sample; ignored for stats."),
+    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, method, columns_block, k }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("datasets(upload) requires name");
@@ -93,10 +114,17 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 if (ext !== ".csv" && ext !== ".tsv") {
                     throw new Error("Only .csv and .tsv files can be uploaded as datasets.");
                 }
+                const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
                 try {
+                    const stat = await fs.stat(resolved);
+                    if (stat.size > MAX_UPLOAD_BYTES) {
+                        throw new Error(`File too large (${(stat.size / 1024 / 1024).toFixed(1)} MB). Maximum upload size is ${MAX_UPLOAD_BYTES / 1024 / 1024} MB.`);
+                    }
                     body = await fs.readFile(resolved, "utf-8");
                 }
-                catch {
+                catch (err) {
+                    if (err instanceof Error && err.message.includes("too large"))
+                        throw err;
                     throw new Error(`File not accessible at resolved path. file_path is relative to workspace root. ` +
                         `Set BARIVIA_WORKSPACE_ROOT in your MCP config env if needed (current: ${await getWorkspaceRootAsync(server)}).`);
                 }
@@ -265,7 +293,8 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const periodicStrong = periodicity.filter((p) => p.dominant_score > 0.4);
             if (periodicStrong.length > 0) {
                 const lags = [...new Set(periodicStrong.map((p) => p.dominant_lag))].sort((a, b) => a - b);
-                nextSteps.push(`Columns show periodic behavior at lags ${lags.join(", ")}. Consider cyclic_features or temporal_features with matching periods.`);
+                nextSteps.push(`Note: periodicity is computed on row order. If your CSV is not sorted by time, ignore lag-based suggestions; only use cyclic_features when the column is genuinely cyclic (e.g. hour, month, angle).`);
+                nextSteps.push(`Columns show periodic behavior at lags ${lags.join(", ")} (assuming row order is meaningful). Consider cyclic_features or temporal_features with matching periods.`);
                 nextSteps.push(`For datetime columns: run datasets(action=preview) for temporal_suggestions; match lags (e.g. 365→day_of_year, 12→month, 7→day_of_week, 24→hour_of_day) to choose which temporal components to extract.`);
             }
             nextSteps.push(`Then call jobs(action=train_map, dataset_id=${dataset_id}, columns=[...], ...).`);
@@ -311,6 +340,58 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 content: [{ type: "text", text: `datasets(add_expression) job ${deriveJobId} submitted. Poll with jobs(action=status, job_id="${deriveJobId}").` }],
             };
         }
+        if (action === "reduce_spectral") {
+            if (!dataset_id)
+                throw new Error("datasets(reduce_spectral) requires dataset_id");
+            if (!name)
+                throw new Error("datasets(reduce_spectral) requires name (prefix for derived columns)");
+            if (!method)
+                throw new Error("datasets(reduce_spectral) requires method: pca | log_sample | uniform_sample | stats");
+            if (!columns_block || columns_block.length < 2) {
+                throw new Error("datasets(reduce_spectral) requires columns_block: ordered array of ≥ 2 source column names");
+            }
+            if (method !== "stats" && (k === undefined || k < 1)) {
+                throw new Error(`datasets(reduce_spectral) requires k ≥ 1 for method '${method}'`);
+            }
+            if (method !== "stats" && k !== undefined && k >= columns_block.length) {
+                throw new Error(`datasets(reduce_spectral) requires k < length(columns_block); got k=${k}, columns_block=${columns_block.length}`);
+            }
+            const body = { name, method, columns: columns_block };
+            if (method !== "stats")
+                body.k = k;
+            const data = (await apiCall("POST", `/v1/datasets/${dataset_id}/reduce_spectral`, body));
+            const reduceJobId = data.id;
+            const poll = await pollUntilComplete(reduceJobId, 120_000);
+            if (poll.status === "completed") {
+                const results = (await apiCall("GET", `/v1/results/${reduceJobId}`));
+                const summary = (results.summary ?? {});
+                const outCols = summary.output_columns ?? [];
+                const sourceCols = summary.source_columns ?? [];
+                const lines = [
+                    `Spectral reduction complete (${method}) — job: ${reduceJobId}`,
+                    `Source: ${sourceCols.length} columns → Output: ${outCols.length} columns appended to dataset ${dataset_id}`,
+                    `New columns: ${outCols.join(", ")}`,
+                ];
+                if (method === "pca") {
+                    const ev = summary.explained_variance_ratio;
+                    const evTotal = summary.explained_variance_total;
+                    if (ev)
+                        lines.push(`Explained variance per component: [${ev.map((v) => v.toFixed(3)).join(", ")}] | total: ${evTotal !== undefined ? evTotal.toFixed(3) : "N/A"}`);
+                }
+                else if (method === "log_sample" || method === "uniform_sample") {
+                    const idxs = summary.selected_indices;
+                    if (idxs) {
+                        lines.push(`Selected source-column indices (1-based): [${idxs.join(", ")}]`);
+                    }
+                }
+                lines.push(`Use datasets(action=preview, dataset_id=${dataset_id}) to inspect the new columns, then jobs(action=train_map, dataset_id=${dataset_id}, columns=[..., "${outCols[0] ?? ""}", …]) to train on the reduced features.`);
+                return { content: [{ type: "text", text: lines.filter(Boolean).join("\n") }] };
+            }
+            if (poll.status === "failed") {
+                return { content: [{ type: "text", text: `datasets(reduce_spectral) job ${reduceJobId} failed: ${poll.error ?? "unknown error"}` }] };
+            }
+            return { content: [{ type: "text", text: `datasets(reduce_spectral) job ${reduceJobId} submitted. Poll with jobs(action=status, job_id="${reduceJobId}").` }] };
+        }
         if (action === "subset") {
             if (!dataset_id)
                 throw new Error("datasets(subset) requires dataset_id");

package/dist/tools/explore_map.js

@@ -168,9 +168,9 @@ export function registerExploreMapTool(server) {
     registerAppTool(server, "explore_map", {
         ...toolConfig,
         title: "Results Explorer",
-        description: `${toolConfig.description} This legacy alias remains for compatibility.`,
+        description: `${toolConfig.description} Deprecated alias for results_explorer — migrate configs to results_explorer.`,
     }, async ({ job_id }) => handleResultsExplorer(job_id));
-    server.tool("_fetch_figure", "Internal: fetch a single results figure as base64 image. Used by the Results Explorer view.", {
+    server.tool("_fetch_figure", "Host / MCP App use only — do NOT invoke from agent chat. Results Explorer calls this to load one raster figure as base64; agents should use results(action=get) or results_explorer instead.", {
         job_id: z.string(),
         filename: z.string(),
     }, async ({ job_id, filename }) => {

package/dist/tools/guide_barsom.js

@@ -8,10 +8,10 @@ Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guid
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {
-    server.tool("guide_barsom_workflow", "Ground-truth orientation for this MCP: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online (tier-scoped to allowed_job_types). Call at the start of mapping work. Offline: returns a short stub. For field-level training parameters, use training_guidance or prepare_training.", {}, async () => {
+    server.tool("guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt or training_prep.", {}, async () => {
         const md = await fetchWorkflowGuideFromApi();
         if (md) {
-            const text = "Source: Barivia API (`GET /v1/docs/workflow`). Text below is scoped to your API key / plan.\n\n" + md;
+            const text = "Plan-scoped workflow (from Barivia API). Text below reflects your API key / plan.\n\n" + md;
             return { content: [{ type: "text", text }] };
         }
         return { content: [{ type: "text", text: OFFLINE_STUB }] };

package/dist/tools/inference.js

@@ -1,46 +1,89 @@
 import { z } from "zod";
 import { apiCall, pollUntilComplete, tryAttachImage } from "../shared.js";
+const PREDICT_PREVIEW_ROW_CAP = 10;
+/** One line per scored row when worker embedded `predictions_preview` (n_rows ≤ cap). Exported for tests. */
+export function formatPredictPreviewLines(summary) {
+    const nRows = Number(summary.n_rows ?? 0);
+    if (nRows < 1 || nRows > PREDICT_PREVIEW_ROW_CAP)
+        return [];
+    const preview = summary.predictions_preview;
+    if (!Array.isArray(preview) || preview.length === 0)
+        return [];
+    const lines = ["Per-row summary (same columns as predictions.csv):"];
+    for (const raw of preview) {
+        const p = raw;
+        const rid = String(p.row_id ?? "?");
+        const bx = p.bmu_x !== undefined ? Number(p.bmu_x).toFixed(2) : "?";
+        const by = p.bmu_y !== undefined ? Number(p.bmu_y).toFixed(2) : "?";
+        const node = p.bmu_node_index ?? "?";
+        const cl = p.cluster_id ?? "?";
+        if (p.quantization_error !== undefined) {
+            const qe = Number(p.quantization_error).toFixed(4);
+            const anom = p.potential_anomaly === true ? "yes" : "no";
+            lines.push(`  row ${rid}: BMU (${bx},${by}) node=${node} cluster=${cl} QE=${qe} anomaly=${anom}`);
+        }
+        else {
+            // regime=training: QE columns are intentionally omitted (training-set fit, not generalisation)
+            lines.push(`  row ${rid}: BMU (${bx},${by}) node=${node} cluster=${cl}`);
+        }
+    }
+    return lines;
+}
 export function registerInferenceTool(server) {
-    server.tool("inference", `Use a trained map as a persistent inference artifact — score new data, enrich the training CSV, compare datasets, or generate a PDF report.
+    server.tool("inference", `Use a trained map as a persistent inference artifact — score data, annotate the source CSV, compare datasets, project columns, or generate a report manifest.
 
 | Action | Use when | Timing |
 |--------|----------|--------|
-| predict | Scoring new/unseen observations against the trained map | 5–120s |
-| enrich | Appending BMU coordinates + cluster_id to the original training CSV | 5–60s |
+| predict | Scoring rows against the trained map (new data OR the training set itself) | 5–120s |
 | compare | Comparing hit distributions of a second dataset against training (drift, A/B) | 30–120s |
 | project_columns | Project one or more dataset columns onto the map (component planes); dataset can be training set or partial-feature set | 10–90s |
 | report | Get a report manifest (artifact keys + URLs) to build your own report in Quarto/Notebook/script | Immediate (sync) |
 
-Sync/async: predict, enrich, and compare are all async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
-Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict → predictions.csv; enrich → enriched.csv; compare → density-diff figure (e.g. density_diff.png).
+Sync/async: predict and compare are async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
+Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict (output="compact") → predictions.csv; predict (output="annotated") → enriched.csv; compare → density-diff figure (e.g. density_diff.png).
 report is the only synchronous inference action — returns manifest immediately; no job to poll.
 NOT FOR: Retraining or changing the map — all actions treat the trained map as frozen.
 ESCALATION: If any action returns "missing column", verify column names with datasets(action=preview). Column names are case-sensitive and must match the training feature set exactly.
 
-action=predict: Returns predictions.csv with row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly (true when QE > 95th percentile; summary includes qe_p95 for the threshold). Use potential_anomaly for downstream anomaly filtering.
-  Dataset/batch rows must use the same schema as training (including cyclic-expanded columns, e.g. key_cos, key_sin not raw key). For a single inline row only, the proxy can use the stateless model endpoint instead: raw categorical strings are allowed for baseline categorical_features models, and raw cyclic inputs are expanded from training config. High QE = row is far from its nearest prototype = potential anomaly. Accepts dataset_id OR inline rows (≤500).
-action=enrich: Uses the job's training dataset; do not pass dataset_id. Returns enriched.csv — original training CSV + bmu_x, bmu_y, bmu_node_index, cluster_id. When complete, get enriched.csv via results(action=download, job_id=<returned_enrich_job_id>). Filename: enriched.csv.
-action=compare: dataset_id must refer to a dataset with the same feature set as the training data (same column names and preprocessing, including cyclic expansion). A = training dataset (the map was trained on it). B = cohort to compare (the dataset_id you pass). Density-diff: positive = B gained vs A; negative = A had more. Using the same dataset as A and B yields a flat diff. Returns density-diff heatmap (e.g. density_diff.png).
+action=predict: Score rows against the trained map.
+  Inputs (one of):
+    - dataset_id (default = parent training job's dataset). Use a different dataset for new/unseen data; omit it (or pass the training dataset_id) to score the training set itself.
+    - rows (≤500 inline). Always treated as new data.
+  Output style (output param, default "compact"):
+    - "compact"   → predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id [, quantization_error, potential_anomaly]).
+    - "annotated" → enriched.csv (the full source CSV with bmu_x, bmu_y, bmu_node_index, cluster_id appended). Requires a dataset (no inline rows). Replaces the previous inference(action=enrich) — migrate by passing output="annotated".
+  Regime auto-detected:
+    - If the resolved dataset matches the parent training dataset, regime="training" and QE / qe_p95 / potential_anomaly fields are omitted from the compact output. QE on training data is fitting error, not a generalisation metric, and the p95 anomaly flag would be circular. Use a held-out dataset for quality assessment.
+    - Otherwise regime="new" and the full QE columns are returned.
+  Schema rules: dataset / batch rows must match the trained feature set including cyclic-expanded columns (e.g. key_cos, key_sin, not raw key). For a single inline row, the proxy uses the stateless model endpoint — raw categorical strings are allowed for baseline categorical_features models, and raw cyclic inputs are expanded from training config.
+  Routing: prefer dataset_id for many rows or whenever the map uses irregular SIOM / GeneralTopology layouts — the async worker path is the supported batch scorer. Single-row rows take a fast stateless path that may return invalid_inference_input on some topologies; if so, retry with dataset_id (a one-row dataset is fine). FLooP-SIOM: use dataset_id predict first.
+  When the scored set has at most ${PREDICT_PREVIEW_ROW_CAP} rows, completed responses include a short per-line preview in the tool text for chat agents.
+
+action=compare: dataset_id must refer to a dataset with the same feature set as training (same column names and preprocessing, including cyclic expansion). A = training dataset; B = cohort to compare. Density-diff: positive = B gained vs A; negative = A had more. Returns density-diff heatmap (e.g. density_diff.png).
 action=project_columns: Project one or more columns from a dataset onto the trained map. Pass dataset_id (the dataset containing the columns) and columns (array of column names). Uses cached BMUs when dataset is the training set; supports partial-feature mapping when dataset has only a subset of training features. Returns one component plane image per column. Get files via results(action=download, job_id=<returned_job_id>).
-action=report: Returns a report manifest for the given job_id (job must be completed). Includes figure_manifest (logical names → filenames), download_urls for all artifacts, cluster_summary when available, and summary metrics. Stakeholder report PDF (if generated) is available via results(action=download, job_id=<training_job_id>), filename e.g. report.pdf. Use results(action=get) and this manifest to fetch figures/data and render your own PDF (e.g. Quarto, Jupyter). See docs: BUILD_YOUR_OWN_REPORT.md.`, {
+action=report: Returns a report manifest for the given job_id (job must be completed). Includes figure_manifest (logical names → filenames), download_urls for all artifacts, cluster_summary when available, and summary metrics. Stakeholder report PDF (if generated) is available via results(action=download, job_id=<training_job_id>), filename e.g. report.pdf.`, {
         action: z
-            .enum(["predict", "enrich", "compare", "project_columns", "report"])
-            .describe("predict: score new data; enrich: annotate training CSV with BMU coords; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report"),
+            .enum(["predict", "compare", "project_columns", "report"])
+            .describe("predict: score rows; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report. (Note: the previous 'enrich' action is now predict with output=\"annotated\".)"),
         job_id: z.string().describe("Job ID of a completed map training job"),
-        dataset_id: z.string().optional().describe("action=predict/compare/project_columns: Dataset ID. predict=input data to score; compare=dataset B; project_columns=dataset with columns to project."),
+        dataset_id: z.string().optional().describe("action=predict/compare/project_columns: Dataset ID. predict=data to score (defaults to the training dataset when omitted); compare=dataset B; project_columns=dataset with columns to project."),
         columns: z.array(z.string()).optional().describe("action=project_columns: column names to project onto the map (must exist in the dataset)."),
         rows: z.array(z.record(z.string(), z.union([z.number(), z.string()]))).optional().describe("action=predict: inline rows to score (max 500). For a single inline row, raw categorical strings are allowed for baseline categorical_features models. Batch rows should remain numeric and match the training schema."),
+        output: z.enum(["compact", "annotated"]).optional().default("compact").describe("action=predict: output style. compact = predictions.csv (default); annotated = enriched.csv (original CSV + BMU columns). Use annotated to get the training set with BMU labels appended (the former inference(action=enrich) workflow)."),
         colormap: z.string().optional().describe("action=compare: colormap for diff heatmap (default: balance). action=report: n/a."),
         output_format: z.enum(["png", "pdf", "svg"]).optional().default("png").describe("action=compare: output format for heatmap (default: png)"),
         output_dpi: z.enum(["standard", "retina", "print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x, default), print (4x)"),
         top_n: z.number().int().min(1).max(50).optional().default(10).describe("action=compare: number of top gained/lost nodes to report (default: 10)"),
-    }, async ({ action, job_id, dataset_id, columns, rows, colormap, output_format, output_dpi, top_n }) => {
+    }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n }) => {
         const dpiMap = { standard: 1, retina: 2, print: 4 };
         const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
         if (action === "predict") {
-            if (!dataset_id && !rows)
-                throw new Error("inference(predict) requires dataset_id or rows");
-            if (!dataset_id && rows && rows.length === 1) {
+            const outputStyle = output ?? "compact";
+            if (outputStyle === "annotated" && rows) {
+                throw new Error("inference(predict, output=\"annotated\") requires a dataset (not inline rows). Either omit rows and pass dataset_id, or use output=\"compact\".");
+            }
+            // Stateless single-row fast path: only valid for compact output and inline rows.
+            if (!dataset_id && rows && rows.length === 1 && outputStyle === "compact") {
                 const row = rows[0];
                 const data = (await apiCall("POST", `/v1/models/${job_id}/project`, { features: row }));
                 return {
@@ -62,50 +105,53 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                     throw new Error("Batch inline predict rows must remain numeric. For baseline categorical inference, submit a single inline row so the proxy can use the stateless model endpoint.");
                 }
             }
-            const body = {};
+            const body = { output_style: outputStyle };
             if (dataset_id)
                 body.dataset_id = dataset_id;
             if (rows)
                 body.rows = rows;
             const data = (await apiCall("POST", `/v1/results/${job_id}/predict`, body));
             const predictJobId = data.id;
+            // annotated runs over the full dataset; allow up to 120s like compact
             const poll = await pollUntilComplete(predictJobId, 120_000);
             if (poll.status === "completed") {
                 const results = (await apiCall("GET", `/v1/results/${predictJobId}`));
                 const summary = (results.summary ?? {});
                 const urls = (results.download_urls ?? {});
+                const previewLines = formatPredictPreviewLines(summary);
+                const regime = String(summary.regime ?? "new");
+                const effectiveStyle = String(summary.output_style ?? outputStyle);
+                const isAnnotated = effectiveStyle === "annotated";
+                const artifactName = isAnnotated ? "enriched.csv" : "predictions.csv";
+                const headerLine = isAnnotated
+                    ? `Annotated dataset ready — job: ${predictJobId}`
+                    : `Predictions complete — job: ${predictJobId}`;
+                const trainingCaveat = regime === "training"
+                    ? `Training-set BMU lookup. QE on training data is not a generalisation metric; the QE / qe_p95 / potential_anomaly columns are intentionally omitted. Use a held-out dataset (different dataset_id) for quality assessment.`
+                    : "";
+                const metricsLine = (regime !== "training" && !isAnnotated)
+                    ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
+                    : "";
+                const outputLine = isAnnotated
+                    ? `Output: enriched.csv (original CSV + bmu_x, bmu_y, bmu_node_index, cluster_id appended). Clusters: ${summary.n_clusters ?? Object.keys(summary.cluster_counts ?? {}).length}.`
+                    : (regime === "training"
+                        ? `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id). Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`
+                        : `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly). Summary includes mean_qe, max_qe, qe_p95. Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`);
                 return { content: [{ type: "text", text: [
-                                `Predictions complete — job: ${predictJobId}`,
+                                headerLine,
+                                `Regime: ${regime}${regime === "training" ? " (scored against the training set)" : ""} | Style: ${effectiveStyle}`,
                                 `Rows scored: ${summary.n_rows ?? "?"}`,
-                                `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"}`,
-                                `Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}`,
-                                `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly). Summary includes mean_qe, max_qe, qe_p95.`,
-                                urls["predictions.csv"] ? `Download: ${urls["predictions.csv"]}` : "",
+                                metricsLine,
+                                outputLine,
+                                urls[artifactName] ? `Download: ${urls[artifactName]}` : "",
+                                trainingCaveat,
+                                ...previewLines,
                             ].filter(Boolean).join("\n") }] };
             }
             if (poll.status === "failed")
                 return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} failed: ${poll.error ?? "unknown error"}` }] };
             return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} submitted. Poll with jobs(action=status, job_id="${predictJobId}").` }] };
         }
-        if (action === "enrich") {
-            const data = (await apiCall("POST", `/v1/results/${job_id}/enrich_dataset`, {}));
-            const enrichJobId = data.id;
-            const poll = await pollUntilComplete(enrichJobId, 60_000);
-            if (poll.status === "completed") {
-                const results = (await apiCall("GET", `/v1/results/${enrichJobId}`));
-                const summary = (results.summary ?? {});
-                const urls = (results.download_urls ?? {});
-                return { content: [{ type: "text", text: [
-                                `Enriched dataset ready — job: ${enrichJobId}`,
-                                `Rows: ${summary.n_rows ?? "?"} | Clusters: ${summary.n_clusters ?? "?"}`,
-                                `Appended: bmu_x, bmu_y, bmu_node_index, cluster_id`,
-                                urls["enriched.csv"] ? `Download: ${urls["enriched.csv"]}` : "",
-                            ].filter(Boolean).join("\n") }] };
-            }
-            if (poll.status === "failed")
-                return { content: [{ type: "text", text: `inference(enrich) job ${enrichJobId} failed: ${poll.error ?? "unknown error"}` }] };
-            return { content: [{ type: "text", text: `inference(enrich) job ${enrichJobId} submitted. Poll with jobs(action=status, job_id="${enrichJobId}").` }] };
-        }
         if (action === "compare") {
             if (!dataset_id)
                 throw new Error("inference(compare) requires dataset_id (dataset B)");

package/dist/tools/jobs.js

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

package/dist/tools/results.js

@@ -17,7 +17,7 @@ ONLY call this after jobs(action=status) returns "completed".
 ESCALATION: If job not found, verify job_id. If "job not complete", poll with jobs(action=status).
 
 action=get: Returns text summary with quality metrics and inline images.
-  - figures: omit = combined only. "all" = all plots. Array = specific logical names (combined, umatrix, hit_histogram, learning_curve, correlation, component_1..N).
+  - figures: omit = combined only. "all" = all plots. "none" = metrics text only, no images (recommended for sweeps and LLM clients to keep tool payloads small). Array = specific logical names (combined, umatrix, hit_histogram, learning_curve, correlation, component_1..N).
   - include_individual: if true (and figures omitted), inlines every component plane.
   - After recolor or project, use the job_id returned by that operation to get the new artifacts, not the original training job_id.
   - After showing results, guide the user: QE interpretation, whether to retrain, which features to explore.
@@ -48,9 +48,9 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             .describe("get: inline results + metrics; recolor: new colormap/format (async); download: save to disk; export: structured data (training_log/weights/nodes); transition_flow: temporal dynamics (async)"),
         job_id: z.string().describe("Job ID of a completed job"),
         figures: z
-            .union([z.enum(["default", "combined_only", "all", "images"]), z.array(z.string())])
+            .union([z.enum(["default", "combined_only", "all", "images", "none"]), z.array(z.string())])
             .optional()
-            .describe("action=get: omit=combined only; 'all'=all plots; array=specific (combined,umatrix,hit_histogram,learning_curve,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),
+            .describe("action=get: omit=combined only; 'all'=all plots; 'none'=metrics text only (no images, ideal for sweeps and LLM clients); array=specific (combined,umatrix,hit_histogram,learning_curve,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),
         include_individual: z
             .boolean()
             .optional()
@@ -202,22 +202,65 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 }
             }
             else if (jobType === "enrich_dataset") {
+                // Historical job kind: pre-merge `enrich_dataset` worker output. New jobs
+                // never produce this — they use predict with output_style="annotated"
+                // (job_type="predict"). Kept as a read-only display path so old completed
+                // jobs remain reviewable.
                 const files = summary.files ?? [];
                 content.push({ type: "text", text: [
-                        `Enrich Dataset — ${resultsHeader}`,
-                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Samples: ${summary.n_samples ?? 0}`,
+                        `Annotated Dataset (legacy enrich_dataset job) — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Rows: ${summary.n_rows ?? summary.n_samples ?? 0}`,
                         `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
                         `Use results(action=download, job_id="${job_id}") to save enriched.csv.`,
+                        `(For new jobs, use inference(action=predict, output="annotated").)`,
                     ].join("\n") });
             }
             else if (jobType === "predict") {
                 const files = summary.files ?? [];
+                const regime = String(summary.regime ?? "new");
+                const outputStyle = String(summary.output_style ?? "compact");
+                const isAnnotated = outputStyle === "annotated";
+                const headerLabel = isAnnotated ? "Predict (annotated)" : "Predict";
+                const trainingCaveat = (regime === "training" && !isAnnotated)
+                    ? "QE columns intentionally omitted: regime=training (fitting error, not generalisation). Score a held-out dataset for quality assessment."
+                    : "";
+                const metricsLine = (regime !== "training" && !isAnnotated)
+                    ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
+                    : "";
+                const downloadName = isAnnotated ? "enriched.csv" : "predictions.csv";
                 content.push({ type: "text", text: [
-                        `Predict — ${resultsHeader}`,
-                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Samples: ${summary.n_samples ?? 0}`,
+                        `${headerLabel} — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Regime: ${regime} | Style: ${outputStyle}`,
+                        `Rows: ${summary.n_rows ?? summary.n_samples ?? 0}`,
+                        metricsLine,
                         `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
-                        `Use results(action=download, job_id="${job_id}") to save predictions.csv.`,
-                    ].join("\n") });
+                        `Use results(action=download, job_id="${job_id}") to save ${downloadName}.`,
+                        trainingCaveat,
+                    ].filter(Boolean).join("\n") });
+            }
+            else if (jobType === "reduce_spectral") {
+                const method = String(summary.method ?? "?");
+                const sourceCols = summary.source_columns ?? [];
+                const outCols = summary.output_columns ?? [];
+                const lines = [
+                    `Reduce Spectral — ${resultsHeader}`,
+                    `Method: ${method} | Source columns: ${sourceCols.length} | Output columns: ${outCols.length}`,
+                    `Source: ${sourceCols.length <= 10 ? sourceCols.join(", ") : sourceCols.slice(0, 5).join(", ") + ", … " + sourceCols.slice(-3).join(", ")}`,
+                    `Output: ${outCols.join(", ")}`,
+                ];
+                if (method === "pca") {
+                    const ev = summary.explained_variance_ratio;
+                    const evTotal = summary.explained_variance_total;
+                    if (ev)
+                        lines.push(`Explained variance per component: [${ev.map((v) => v.toFixed(3)).join(", ")}] | total: ${evTotal !== undefined ? evTotal.toFixed(3) : "N/A"}`);
+                }
+                else if (method === "log_sample" || method === "uniform_sample") {
+                    const idxs = summary.selected_indices;
+                    if (idxs)
+                        lines.push(`Selected indices: [${idxs.join(", ")}]`);
+                }
+                lines.push(`The new columns are appended to the source dataset and ready to use in jobs(action=train_map, columns=[..., "${outCols[0] ?? "feat_1"}", …]).`);
+                content.push({ type: "text", text: lines.join("\n") });
             }
             else if (jobType === "train_floop_siom") {
                 const siom = summary.siom ?? {};
@@ -357,24 +400,29 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             const jobType2 = summary.job_type ?? "train_som";
             const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
             const hasExportableJson = files.some((f) => f.endsWith(".json") && f !== "summary.json");
-            for (const fname of files) {
-                if (isImage(fname) && !inlinedImages.has(fname)) {
-                    const cap = getCaptionForImage(fname);
-                    if (cap)
-                        content.push({ type: "text", text: cap });
-                    await tryAttachImage(content, job_id, fname);
+            // figures="none": metrics-only mode. Skip any further image attaches and the
+            // "Available figures…" hint; keep the structured-data export hint since it
+            // points at non-image artifacts.
+            if (figures !== "none") {
+                for (const fname of files) {
+                    if (isImage(fname) && !inlinedImages.has(fname)) {
+                        const cap = getCaptionForImage(fname);
+                        if (cap)
+                            content.push({ type: "text", text: cap });
+                        await tryAttachImage(content, job_id, fname);
+                    }
                 }
             }
             if (hasExportableJson && (jobType2 === "train_som" || jobType2 === "train_siom" || jobType2 === "render_variant")) {
                 content.push({ type: "text", text: `Structured data: results(action=export, export_type=weights|nodes|training_log)` });
             }
             const featuresForLog = summary.features ?? [];
-            const showAvailable = files.length > 0 && !(figures === "all" || figures === "images");
+            const showAvailable = files.length > 0 && !(figures === "all" || figures === "images" || figures === "none");
             if (showAvailable) {
                 const logicalNames = jobType2 === "train_som" || jobType2 === "train_siom" || jobType2 === "render_variant"
                     ? `Logical names: combined, umatrix, hit_histogram, correlation, ${featuresForLog.map((_, i) => `component_${i + 1}`).join(", ")}. `
                     : "";
-                content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots or results(action=get, figures=all) for all plots.` });
+                content.push({ type: "text", text: `Available: ${files.join(", ")}. ${logicalNames}Use results(action=get, figures=[...]) for specific plots, figures=all for everything, or figures="none" for metrics-only.` });
             }
             return { content };
         }

package/dist/tools/training_guidance.js

@@ -1,6 +1,6 @@
 import { fetchTrainingGuidanceFromApi } from "../shared.js";
 export function registerTrainingGuidanceTool(server) {
-    server.tool("training_guidance", "Returns parameter guidance for training jobs (grid, epochs, batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Domain knowledge is served from GET /v1/training/config and filtered to your allowed_job_types; requires valid API key. For full proxy orientation and SOP, call guide_barsom_workflow (loads GET /v1/docs/workflow). Optional visual workflows: training_prep (prep), results_explorer (postprocess)—not required; jobs + results are sufficient.", {}, async () => {
+    server.tool("training_guidance", "Structured parameter guidance for training (presets, grid/epochs/batch, model, periodic, SIOM/FLooP fields where your plan allows, categorical baselines). Served from the API and filtered to allowed_job_types. Prep ladder: prepare_training prompt = narrative checklist; this tool = JSON/hints; training_prep = interactive UI + submit_prepared_training. For full orientation and SOP, call guide_barsom_workflow first. Optional UIs: training_prep, results_explorer—not required; jobs + results suffice.", {}, async () => {
         const text = await fetchTrainingGuidanceFromApi();
         return { content: [{ type: "text", text }] };
     });

package/dist/tools/training_prep.js

@@ -321,7 +321,7 @@ export function registerTrainingPrepTools(server) {
     };
     registerAppTool(server, "training_prep", {
         title: "Training Preparation",
-        description: "Prepare a training job before submission. Opens an inline review UI showing variables, transforms, encodings, and effective hyperparameters with a guarded submit step.",
+        description: "Interactive training prep UI + guarded submit (submit_prepared_training). Prep ladder: prepare_training prompt = narrative checklist; training_guidance tool = JSON/presets; this tool = visual review. Opens inline review of variables, transforms, encodings, and hyperparameters.",
         inputSchema: trainPrepSchema,
         _meta: { ui: { resourceUri: TRAINING_PREP_URI } },
     }, async ({ dataset_id, ...args }) => {

package/package.json

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