npm - @barivia/barsom-mcp - Versions diffs - 0.5.0 → 0.5.1 - Mend

@barivia/barsom-mcp 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +9 -11
package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/dist/views/src/views/map-explorer/index.html +288 -0
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -44,18 +44,16 @@ SOP dispatch. Call this first if unsure of the workflow. No parameters.
 | Action | Use when |
 |--------|----------|
 | `upload` | Adding a new CSV — returns dataset_id |
-| `preview` | Before train_som — inspect columns, stats, cyclic/datetime hints |
+| `preview` | Before jobs(action=train_map) — inspect columns, stats, cyclic/datetime hints |
 | `list` | Finding dataset IDs |
 | `subset` | Creating a filtered/sliced copy (row_range, filter conditions) |
 | `delete` | Removing a dataset |
-### `train_som`
-Submit a SOM training job. Full control: model type (SOM/RSOM/SOM-SOFT/RSOM-SOFT), grid, epochs, cyclic encoding, temporal features, feature weights, transforms. Returns a `job_id` — always poll with `jobs(action=status)`.
 ### `jobs(action)`
 | Action | Use when |
 |--------|----------|
+| `train_map` | Submitting a new map training job — full control: model type, grid, epochs, cyclic/temporal features, transforms. Returns `job_id`; poll with `jobs(action=status, job_id=...)`. |
 | `status` | Polling after any async job — every 10–15s |
 | `list` | Finding job IDs, checking pipeline state |
 | `compare` | Picking the best run from a set (QE, TE, silhouette table) |
@@ -79,11 +77,11 @@ Submit a SOM training job. Full control: model type (SOM/RSOM/SOM-SOFT/RSOM-SOFT
 | Action | Use when |
 |--------|----------|
-| `expression` | Computing a derived variable from a formula (`revenue / cost`, `diff(temp)`, rolling stats) — add to dataset or project onto SOM |
-| `values` | Projecting a pre-computed external array (anomaly scores, labels from another system) onto the SOM |
+| `expression` | Computing a derived variable from a formula (`revenue / cost`, `diff(temp)`, rolling stats) — add to dataset or project onto the map |
+| `values` | Projecting a pre-computed external array (anomaly scores, labels from another system) onto the map |
 ### `inference(action)`
-All actions use a frozen trained SOM — no retraining. All are async.
+All actions use a frozen trained map — no retraining. All are async.
 | Action | Output | Timing |
 |--------|--------|--------|
@@ -103,11 +101,11 @@ All actions use a frozen trained SOM — no retraining. All are async.
 | `history` | Viewing recent compute usage and spend |
 | `add_funds` | Getting instructions to add credits |
-### `explore_som` (MCP App)
-Interactive inline SOM explorer — clickable nodes, feature toggles, export controls.
+### `explore_map` (MCP App)
+Interactive inline map explorer — clickable nodes, feature toggles, export controls.
 ### `send_feedback`
-Submit feedback or feature requests (max 190 words).
+Submit feedback or feature requests (max 1400 characters, ~190 words).
 ## Tool Design Guidelines
@@ -120,7 +118,7 @@ When adding or refining tools, follow [MCP best practices](https://modelcontextp
 ## Data preparation
-To train on a subset of your data (e.g. first 2000 rows, or rows where region=Europe) without re-uploading: use **datasets(action=subset)** with `row_range` and/or `filter` to create a new dataset, then **train_som** on the new dataset_id; or pass **row_range** in **train_som** params for a one-off training slice.
+To train on a subset of your data (e.g. first 2000 rows, or rows where region=Europe) without re-uploading: use **datasets(action=subset)** with `row_range` and/or `filter` to create a new dataset, then **jobs(action=train_map, dataset_id=...)** on the new dataset_id; or pass **row_range** in **jobs(action=train_map)** params for a one-off training slice.
 ## How It Works

package/dist/index.js CHANGED Viewed

@@ -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{registerAppResource as a,registerAppTool as n,RESOURCE_MIME_TYPE as r}from"@modelcontextprotocol/ext-apps/server";import i from"node:fs/promises";import s from"node:path";const l=process.env.BARIVIA_API_URL??process.env.BARSOM_API_URL??"https://api.barivia.se",c=process.env.BARIVIA_API_KEY??process.env.BARSOM_API_KEY??"";c||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const d=parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS??"30000",10),u=new Set([502,503,504]);function p(e,t){return!(void 0===t||!u.has(t))||(e instanceof DOMException&&"AbortError"===e.name||e instanceof TypeError)}async function m(e,t,o=d){const a=new AbortController,n=setTimeout(()=>a.abort(),o);try{return await fetch(e,{...t,signal:a.signal})}finally{clearTimeout(n)}}async function f(e,t,o,a){const n=`${l}${t}`,r=a?.["Content-Type"]??"application/json",i=Math.random().toString(36).slice(2,10),s={Authorization:`Bearer ${c}`,"Content-Type":r,"X-Request-ID":i,...a};let d,u;void 0!==o&&(d="application/json"===r?JSON.stringify(o):String(o));for(let t=0;t<=2;t++)try{const o=await m(n,{method:e,headers:s,body:d}),a=await o.text();if(!o.ok){if(t<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}const e=(()=>{try{return JSON.parse(a)}catch{return null}})(),n=e?.error??a,r=400===o.status?" Check parameter types and required fields.":404===o.status?" The resource may not exist or may have been deleted.":409===o.status?" The job may not be in the expected state.":429===o.status?" Rate limit exceeded — wait a moment and retry.":"";throw new Error(`${n}${r}`)}return JSON.parse(a)}catch(e){if(u=e,t<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}throw e}throw u}async function g(e){const t=`${l}${e}`;let o;for(let a=0;a<=2;a++)try{const o=await m(t,{method:"GET",headers:{Authorization:`Bearer ${c}`}});if(!o.ok){if(a<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**a));continue}throw new Error(`API GET ${e} returned ${o.status}`)}const n=await o.arrayBuffer();return{data:Buffer.from(n),contentType:o.headers.get("content-type")??"application/octet-stream"}}catch(e){if(o=e,a<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**a));continue}throw e}throw o}function h(e){return{content:[{type:"text",text:JSON.stringify(e,null,2)}]}}async function b(e,t=3e4,o=1e3){const a=Date.now();for(;Date.now()-a<t;){const t=await f("GET",`/v1/jobs/${e}`),a=t.status;if("completed"===a||"failed"===a||"cancelled"===a)return{status:a,result_ref:t.result_ref,error:t.error};await new Promise(e=>setTimeout(e,o))}return{status:"timeout"}}const _=new e({name:"analytics-engine",version:"0.4.1",instructions:"# Barivia barSOM Analytics Engine\n\nYou have access to a Self-Organizing Map (SOM) analytics platform. SOMs are unsupervised neural networks that project high-dimensional data onto a 2D grid, revealing clusters, gradients, and anomalies in the structure of the data.\n\n## Typical workflow\n\n1. **Upload** → `datasets(action=upload)` — ingest a CSV\n2. **Preview** → `datasets(action=preview)` — inspect columns, detect cyclics/datetimes\n3. **Train** → `train_som` — returns a job_id; poll `get_job_status` until completed\n4. **Analyze** → `get_results` + `analyze` — visualize and interpret the map\n5. **Export / Inference** → `enrich_dataset`, `predict`, `compare_datasets`, `generate_report`\n\n## Tool categories\n\n| Category | Tools |\n|----------|-------|\n| Data management | `datasets` (upload/preview/list/subset/delete) |\n| Training | `train_som` |\n| Jobs & status | `jobs` (status/list/compare/cancel/delete) |\n| Results | `results` (get/recolor/download/export/transition_flow), `analyze` |\n| Projection | `project` (expression/values) |\n| Inference & export | `inference` (predict/enrich/compare/report) |\n| Account | `account` (status/request_compute/compute_status/release_compute/history/add_funds) |\n| Utility | `guide_barsom_workflow`, `explore_som`, `send_feedback` |\n\n## Async job pattern\n\nMost operations are async. Every tool that submits a job either:\n- **Auto-polls** (project, 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** (train_som) — always requires manual `jobs(action=status)` polling\n\n**Do not tell the user a job failed because it is still running.** If a tool returns a job_id, poll `get_job_status` every 10–15 seconds. SOM training takes 30s–10min depending on grid size and dataset.\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- Column names are case-sensitive; always match exactly what `datasets(action=preview)` returns\n- Numeric columns only (SOMs do not support text/categorical directly — encode first)\n- `predict` input columns must exactly match the features used during training"}),w=import.meta.dirname??s.dirname(new URL(import.meta.url).pathname);async function v(e){const t=[s.join(w,"views","src","views",e,"index.html"),s.join(w,"views",e,"index.html"),s.join(w,"..","dist","views","src","views",e,"index.html")];for(const e of t)try{return await i.readFile(e,"utf-8")}catch{continue}return null}const y="ui://barsom/som-explorer",$="ui://barsom/data-preview",x="ui://barsom/training-monitor";function j(e,t,o,a){const n=t.output_format??"pdf";if("transition_flow"===e){return[`transition_flow_lag${t.lag??1}.${n}`]}if("project_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${n}`]}if("derive_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${n}`]}const r=t.features??[],i=`combined.${n}`,s=`umatrix.${n}`,l=`hit_histogram.${n}`,c=`correlation.${n}`,d=r.map((e,t)=>`component_${t+1}_${e.replace(/[^a-zA-Z0-9_]/g,"_")}.${n}`),u=[i,s,l,c,...d];if(void 0===o||"default"===o)return a?u:[i];if("combined_only"===o)return[i];if("all"===o)return u;if(Array.isArray(o)){const e={combined:i,umatrix:s,hit_histogram:l,correlation:c};return r.forEach((t,o)=>{e[`component_${o+1}`]=d[o]}),o.map(t=>{const o=t.trim().toLowerCase();return e[o]?e[o]:t.includes(".")?t:null}).filter(e=>null!=e)}return[i]}function S(e){return e.endsWith(".pdf")?"application/pdf":e.endsWith(".svg")?"image/svg+xml":"image/png"}async function E(e,t,o){if(o.endsWith(".pdf")||o.endsWith(".svg"))e.push({type:"text",text:`${o} is ready (vector format — not inlineable). Use get_result_image(job_id="${t}", filename="${o}") to download it.`});else try{const{data:a}=await g(`/v1/results/${t}/image/${o}`);e.push({type:"image",data:a.toString("base64"),mimeType:S(o),annotations:{audience:["user"],priority:.8}})}catch{e.push({type:"text",text:`(${o} not available for inline display)`})}}a(_,y,y,{mimeType:r},async()=>{const e=await v("som-explorer");return{contents:[{uri:y,mimeType:r,text:e??"<html><body>SOM Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),a(_,$,$,{mimeType:r},async()=>{const e=await v("data-preview");return{contents:[{uri:$,mimeType:r,text:e??"<html><body>Data Preview view not built yet.</body></html>"}]}}),a(_,x,x,{mimeType:r},async()=>{const e=await v("training-monitor");return{contents:[{uri:x,mimeType:r,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),n(_,"explore_som",{title:"Explore SOM",description:"Interactive SOM explorer dashboard. Opens an inline visualization where you can toggle features, click nodes, and export figures. Use this after get_results for a richer, interactive exploration experience. Falls back to text+image on hosts that don't support MCP Apps.",inputSchema:{job_id:o.string().describe("Job ID of a completed SOM training job")},_meta:{ui:{resourceUri:y}}},async({job_id:e})=>{const t=await f("GET",`/v1/results/${e}`),o=t.summary??{},a=[];a.push({type:"text",text:JSON.stringify({job_id:e,summary:o,download_urls:t.download_urls})});const n=o.output_format??"pdf";return await E(a,e,`combined.${n}`),{content:a}}),_.tool("guide_barsom_workflow","Retrieve the Standard Operating Procedure (SOP) for the barSOM analysis pipeline.\nALWAYS call this tool first if you are unsure of the steps to execute a complete Self-Organizing Map analysis.\nThe workflow explains the exact sequence of tool calls needed: Upload → Preprocess → Train → Wait → Analyze.",{},async()=>({content:[{type:"text",text:"barSOM Standard Operating Procedure (SOP)\n\nStep 1: Upload Data\n- Use `datasets(action=upload)` with a local `file_path` to your CSV.\n- BEFORE UPLOADING: Clean the dataset to remove NaNs or malformed data.\n- Capture the `dataset_id` returned.\n\nStep 2: Preview & Preprocess\n- Use `datasets(action=preview)` to inspect columns, ranges, and types.\n- Check for skewed columns requiring 'log' or 'sqrt' transforms.\n- Check for cyclical or temporal features (hours, days) requiring `cyclic_features` or `temporal_features` during training.\n\nStep 3: Train the SOM\n- Call `train_som` with the `dataset_id`.\n- Carefully select columns to include (start with 5-10).\n- Assign `feature_weights` (especially for categorical data with natural hierarchies).\n- Wait for the returned `job_id`.\n\nStep 4: Wait for Completion (ASYNC POLLING)\n- Use `get_job_status` every 10-15 seconds.\n- Wait until status is \"completed\". DO NOT assume failure before 3 minutes (or longer for large grids).\n- If it fails, read the error message and adjust parameters (e.g., reduce grid size, fix column names).\n\nStep 5: Analyze and Export\n- Once completed, use `analyze(type=component_planes)` or `analyze(type=clusters)` to interpret the results.\n- Call `get_results` to get the final metrics (Quantization Error, Topographic Error)."}]})),_.tool("datasets",'Manage datasets: upload, preview, list, subset, or delete.\n\n| Action | Use when |\n|--------|----------|\n| upload | You have a CSV file to add — do this first |\n| preview | Before train_som — always preview an unfamiliar dataset to spot cyclics, nulls, column types |\n| list | Finding dataset IDs for train_som, preview, or subset — see all available datasets |\n| subset | Creating a filtered/sliced view without re-uploading the full CSV |\n| delete | Cleaning up after experiments or freeing the dataset slot |\n\naction=upload: Prefer file_path over csv_data so the MCP reads the file directly. Returns dataset ID. Then use datasets(action=preview) before train_som.\nBEFORE UPLOADING: Ensure data has no NaNs, missing values, or formats that can\'t be handled. Categorical features should be numerically encoded or weighted.\naction=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train_som on an unfamiliar dataset.\naction=list: List all datasets belonging to the organisation with IDs, names, row/col counts.\naction=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range or filters.\n  - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)\n  - filters: array of conditions, ALL must match (AND logic). Each: { column, op, value }.\n    Operators: eq, ne, in, gt, lt, gte, lte, between\n    Examples: { column: "region", op: "eq", value: "Europe" } | { column: "age", op: "between", value: [18, 65] }\n  - Combine row_range + filters to slice both rows and values.\n  - Single filter object is also accepted (auto-wrapped).\naction=delete: Remove a dataset and all S3 data permanently.\n\nBEST FOR: Tabular numeric data. CSV with header required.\nNOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.\nESCALATION: 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:o.enum(["upload","preview","list","subset","delete"]).describe("upload: add CSV; preview: inspect columns/stats; list: see all datasets; subset: create filtered subset; delete: remove dataset"),name:o.string().optional().describe("Dataset name (required for action=upload and subset)"),file_path:o.string().optional().describe("Path to local CSV (for upload; prefer over csv_data)"),csv_data:o.string().optional().describe("Inline CSV string (for upload; use for small data)"),dataset_id:o.string().optional().describe("Dataset ID (required for preview, subset, and delete)"),n_rows:o.number().int().optional().default(5).describe("Sample rows to return (preview only)"),row_range:o.tuple([o.number().int(),o.number().int()]).optional().describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),filters:o.preprocess(e=>null==e||Array.isArray(e)?e:"object"==typeof e&&null!==e&&"column"in e?[e]:e,o.array(o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])})).optional().describe("For subset: filter conditions (AND logic). Single object or array. ops: eq, ne, in, gt, lt, gte, lte, between. Examples: { column: 'temp', op: 'between', value: [15, 30] }, { column: 'region', op: 'eq', value: 'Europe' }")),filter:o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])}).optional().describe("Deprecated — use filters instead. Single filter condition.")},async({action:e,name:t,file_path:o,csv_data:a,dataset_id:n,n_rows:r,row_range:l,filters:c,filter:d})=>{if("upload"===e){if(!t)throw new Error("datasets(upload) requires name");let e;if(o){const t=s.resolve(o);try{e=await i.readFile(t,"utf-8")}catch(e){const o=e instanceof Error?e.message:String(e);throw new Error(`Cannot read file "${t}": ${o}`)}}else{if(!(a&&a.length>0))throw new Error("datasets(upload) requires file_path or csv_data");e=a}return h(await f("POST","/v1/datasets",e,{"X-Dataset-Name":t,"Content-Type":"text/csv"}))}if("preview"===e){if(!n)throw new Error("datasets(preview) requires dataset_id");const e=await f("GET",`/v1/datasets/${n}/preview?n_rows=${r??5}`),t=e.columns??[],o=e.column_stats??[],a=e.cyclic_hints??[],i=e.sample_rows??[],s=e.datetime_columns??[],l=e.temporal_suggestions??[],c=e=>null==e?"—":Number(e).toFixed(3),d=[`Dataset: ${e.name} (${e.dataset_id})`,`${e.total_rows} rows × ${e.total_cols} columns`,"","Column Statistics:","| Column | Min | Max | Mean | Std | Nulls | Numeric |","|--------|-----|-----|------|-----|-------|---------|"];for(const e of o)d.push(`| ${e.column} | ${c(e.min)} | ${c(e.max)} | ${c(e.mean)} | ${c(e.std)} | ${e.null_count??0} | ${!1!==e.is_numeric?"yes":"no"} |`);if(a.length>0){d.push("","Detected Cyclic Feature Hints:");for(const e of a)d.push(`  • ${e.column} — period=${e.period} (${e.reason})`)}if(s.length>0){d.push("","Detected Datetime Columns:");for(const e of s){const t=(e.detected_formats??[]).map(e=>`${e.format} — ${e.description} (${(100*e.match_rate).toFixed(0)}% match)`).join("; ");d.push(`  • ${e.column}: sample="${e.sample}" → ${t}`)}}if(l.length>0){d.push("","Temporal Feature Suggestions (require user approval):");for(const e of l)d.push(`  • Columns: ${e.columns.join(" + ")} → format: "${e.format}"`),d.push(`    Available components: ${e.available_components.join(", ")}`)}if(i.length>0){d.push("",`Sample Rows (first ${i.length}):`),d.push(`| ${t.join(" | ")} |`),d.push(`| ${t.map(()=>"---").join(" | ")} |`);for(const e of i)d.push(`| ${t.map(t=>String(e[t]??"")).join(" | ")} |`)}return{content:[{type:"text",text:d.join("\n")}]}}if("subset"===e){if(!n)throw new Error("datasets(subset) requires dataset_id");if(!t)throw new Error("datasets(subset) requires name");const e=c??(d?[d]:void 0);if(void 0===l&&void 0===e)throw new Error("datasets(subset) requires at least one of row_range or filters");const o={name:t};void 0!==l&&(o.row_range=l),void 0!==e&&(o.filters=e);return h(await f("POST",`/v1/datasets/${n}/subset`,o))}if("list"===e){return h(await f("GET","/v1/datasets"))}if("delete"===e){if(!n)throw new Error("datasets(delete) requires dataset_id");return h(await f("DELETE",`/v1/datasets/${n}`))}throw new Error("Invalid action")}),_.tool("train_som","Train a Self-Organizing Map on the dataset. Returns a job_id for polling.\n\nBEST FOR: Exploratory analysis of multivariate numeric data — clustering, regime\ndetection, process monitoring, anomaly visualization, dimensionality reduction.\nNOT FOR: Time-series forecasting, classification, or text/image data.\n\nASYNC POLLING PROTOCOL:\n- This tool returns a job_id. You MUST poll get_job_status to check completion.\n- Poll every 10-15 seconds.\n- Wait for status \"completed\" before calling analyze() or get_results().\n\nBEFORE calling, ask the user:\n1. Which columns to include? (use 'columns' to restrict)\n2. Any cyclic features?\n3. Any skewed columns? (suggest transforms)\n4. Feature weights?\n5. Quick exploration or refined map?\n\nESCALATION LADDER (If this tool fails):\n- Error mentions temporal validation: The dataset likely has datetime formatting issues. Use datasets(action=preview).\n- Error mentions column not found: Use datasets(action=preview) to verify exact column names (case-sensitive).\n- Error mentions NaNs or missing data: The user must clean the dataset.\n\nSee docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.",{dataset_id:o.string().describe("Dataset ID from datasets(action=upload) or list(type=datasets)"),preset:o.enum(["quick","standard","refined","high_res"]).optional().describe("Training preset — sets sensible defaults for grid, epochs, and batch_size. Explicit params override preset values. quick: 15×15, [15,5], batch=48. standard: 25×25, [30,15], batch=48, best with GPU. refined: 40×40, [50,25], batch=32, best with GPU. high_res: 60×60, [60,40], batch=32, best with GPU. NOTE: GPU acceleration benefits grids >= 40x40 with large datasets (>10k rows). For smaller grids, CPU is faster due to CUDA kernel launch overhead."),grid_x:o.number().int().optional().describe("Grid width (omit for auto from data size)"),grid_y:o.number().int().optional().describe("Grid height (omit for auto from data size)"),epochs:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseInt(e,10);if(!Number.isNaN(t))return t;const o=e.match(/^\[\s*(\d+)\s*,\s*(\d+)\s*\]$/);if(o)return[parseInt(o[1],10),parseInt(o[2],10)]}return e},o.union([o.number().int(),o.array(o.number().int()).length(2)]).optional().describe("epochs: integer or [ordering, convergence] array, not a string. Example: 40 or [40, 20]. Set convergence=0 to skip phase 2 (e.g. [15, 0]).")),model:o.enum(["SOM","RSOM","SOM-SOFT","RSOM-SOFT"]).optional().default("SOM").describe("SOM model type. SOM=standard, SOM-SOFT=GTM-style soft responsibilities, RSOM=recurrent (time-series), RSOM-SOFT=recurrent+soft."),periodic:o.boolean().optional().default(!0).describe("Use periodic (toroidal) boundaries"),columns:o.array(o.string()).optional().describe("Subset of CSV column names to train on. Omit to use all columns. Useful to exclude irrelevant features."),cyclic_features:o.array(o.object({feature:o.string().describe("Column name (e.g., 'weekday')"),period:o.number().describe("Period (e.g., 7 for weekday, 24 for hour, 360 for angle)")})).optional().describe("Features to encode as cyclic (cos, sin) pairs"),temporal_features:o.array(o.object({columns:o.array(o.string()).describe("Column name(s) containing datetime strings, combined in order (e.g. ['Date', 'Time'])"),format:o.string().describe("Julia Dates format string from the whitelist (e.g. 'dd.mm.yyyy HH:MM'). Must match the combined column values."),extract:o.array(o.enum(["hour_of_day","day_of_year","month","day_of_week","minute_of_hour"])).describe("Which temporal components to extract"),cyclic:o.boolean().default(!0).describe("Encode extracted components as cyclic sin/cos pairs (default true)"),separator:o.string().optional().describe("Separator when combining multiple columns (default ' '). Use 'T' for ISO 8601.")})).optional().describe("Temporal feature extraction from datetime columns. Parses dates/times and extracts components. NEVER add this without user approval."),feature_weights:o.record(o.number()).optional().describe("Per-feature importance weights as {column_name: weight}. Applied after normalization (column *= sqrt(weight)). weight=0 disables, >1 emphasizes, <1 de-emphasizes. Cyclic shorthand: {'day_of_year': 2.0} auto-expands to both _cos and _sin. Categorical features should be weighted by the LLM if there is any natural hierarchy applicable that could be constructive."),transforms:o.record(o.enum(["log","log1p","log10","sqrt","square","abs","invert","rank","none"])).optional().describe("Per-column preprocessing applied BEFORE normalization. Example: {revenue: 'log', pressure: 'sqrt'}. 'log' = natural log (fails on <=0), 'log1p' = log(1+x) (safe for zeros), 'sqrt' = square root, 'rank' = replace with rank order, 'invert' = 1/x. Suggest log/log1p for right-skewed distributions (prices, volumes, counts)."),normalize:o.union([o.enum(["all","auto"]),o.array(o.string())]).optional().default("auto").describe("Normalization mode. 'auto' skips already-cyclic features."),sigma_f:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseFloat(e);if(!Number.isNaN(t))return t}return e},o.number().optional().describe("Final neighborhood radius at end of ordering phase (default 1.0). Lower values (0.5–0.7) produce sharper cluster boundaries.")),learning_rate:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseFloat(e);if(!Number.isNaN(t))return t}return e},o.union([o.number(),o.object({ordering:o.tuple([o.number(),o.number()]),convergence:o.tuple([o.number(),o.number()])})]).optional().describe("Learning rate control. Number = sets ordering final rate (e.g. 0.05). Object = full control: {ordering: [eta_0, eta_f], convergence: [eta_0, eta_f]}. Default: ordering 0.1→0.01, convergence 0.01→0.001.")),batch_size:o.number().int().optional().describe("Training batch size (default: auto ≈ n_samples/100, clamped to 16–64). Smaller batches (16-64) often produce significantly better maps (higher explained variance, lower QE) at a modest time cost. Do not use huge batches like 2048 even for 100k+ rows, as they result in undertrained maps."),quality_metrics:o.union([o.enum(["fast","standard","full"]),o.array(o.string())]).optional().describe("Which quality metrics to compute after training. Presets:\n| Preset     | Metrics (count) | Cost   | Best for                                |\n|------------|-----------------|--------|-----------------------------------------|\n| `fast`     | QE, TE, EV, qe_quantiles, silhouette, davies_bouldin, calinski_harabasz (7) | O(n)   | Quick iteration, large datasets         |\n| `standard` | fast + distortion, kaski_lagus_error (9) | O(n)+O(K²) | Default — good balance of cost and insight |\n| `full`     | standard + neighborhood_preservation, trustworthiness, topographic_product (12) | O(n²)  | Topology preservation analysis          |\nDefault: 'standard'. Omit for default. The O(n²) metrics (neighborhood_preservation, trustworthiness) are expensive for large datasets. They are always available on-demand via analyze(job_id, 'quality_report') without retraining. Or pass an array of metric names for fine-grained control: ['quantization_error','topographic_error','explained_variance','qe_quantiles','distortion','kaski_lagus_error','topographic_product','neighborhood_preservation','trustworthiness','silhouette','davies_bouldin','calinski_harabasz']."),backend:o.enum(["auto","cpu","cuda","cuda_graphs"]).optional().default("auto").describe("Compute backend. 'auto' uses CUDA if GPU is available (recommended). 'cpu' forces CPU. 'cuda_graphs' uses CUDA graph capture for maximum GPU throughput."),output_format:o.enum(["png","pdf","svg"]).optional().default("png").describe("Image output format. PNG (default) for inline viewing in chat/console, PDF for publication-quality vector graphics and downloads, SVG for web embedding."),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution for PNG output: standard (1x), retina (2x, default), print (4x). Ignored for PDF/SVG."),colormap:o.string().optional().describe("Override default colormap (coolwarm) for component planes and hit histogram. Examples: viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix always uses grays, cyclic features use twilight."),row_range:o.tuple([o.number().int().min(1),o.number().int().min(1)]).optional().describe("Train on a subset of rows only: [start, end] 1-based inclusive. Alternative to creating a subset dataset with datasets(action=subset).")},async({dataset_id:e,preset:t,grid_x:o,grid_y:a,epochs:n,model:r,periodic:i,columns:s,transforms:l,cyclic_features:c,temporal_features:d,feature_weights:u,normalize:p,sigma_f:m,learning_rate:g,batch_size:b,quality_metrics:_,backend:w,output_format:v,output_dpi:y,colormap:$,row_range:x})=>{let j={};try{const e=await f("GET","/v1/training/config");j=e?.presets||{}}catch(e){if(t&&!o&&!n)throw new Error("Could not fetch training config from server, and missing explicit grid/epochs.")}const S=t?j[t]:void 0,E={model:r,periodic:i,normalize:p};void 0!==o&&void 0!==a?E.grid=[o,a]:S&&(E.grid=S.grid),void 0!==n?E.epochs=n:S&&(E.epochs=S.epochs),c&&c.length>0&&(E.cyclic_features=c),s&&s.length>0&&(E.columns=s),l&&Object.keys(l).length>0&&(E.transforms=l),d&&d.length>0&&(E.temporal_features=d),u&&Object.keys(u).length>0&&(E.feature_weights=u),void 0!==m&&(E.sigma_f=m),void 0!==g&&(E.learning_rate=g),void 0!==b?E.batch_size=b:S&&(E.batch_size=S.batch_size),void 0!==_&&(E.quality_metrics=_),void 0!==w&&"auto"!==w?E.backend=w:S?.backend&&(E.backend=S.backend),E.output_format=v??"png";const T={standard:1,retina:2,print:4};y&&"retina"!==y&&(E.output_dpi=T[y]??2),$&&(E.colormap=$),x&&x.length>=2&&x[0]<=x[1]&&(E.row_range=x);const O=await f("POST","/v1/jobs",{dataset_id:e,params:E});try{const e=await f("GET","/v1/system/info"),t=Number(e.status?.pending_jobs??e.pending_jobs??0),o=Number(e.training_time_estimates_seconds?.total??(e.gpu_available?45:120)),a=Math.round(t*o/60);a>1?(O.estimated_wait_minutes=a,O.message=`Job submitted. You are #${t+1} in queue. Estimated wait before start: ~${a} min.`):O.message="Job submitted. Should start momentarily."}catch(e){}return h(O)}),_.tool("jobs",'Manage and inspect jobs.\n\n| Action | Use when |\n|--------|----------|\n| status | Polling after any async job submission — call every 10–15s |\n| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters |\n| compare | Picking the best training run from a set of completed jobs |\n| cancel | Stopping a running or pending job to free the worker |\n| delete | Permanently removing a job and all its S3 result files |\n\nASYNC POLLING PROTOCOL (action=status):\n- Poll every 10-15 seconds. Do NOT poll faster — it wastes context.\n- For large grids (40×40+), do not assume failure before 3 minutes on CPU.\n- Wait for status "completed" before calling results(action=get).\n- SOM training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.\n\nESCALATION (action=status):\n- completed → call results(action=get) to retrieve the map and metrics\n- failed → extract the error message:\n  - memory/allocation error: reduce batch_size or grid size and retrain\n  - column missing: verify with datasets(action=preview)\n  - NaN error: user must clean the dataset\n\naction=compare: Returns a metrics table (QE, TE, explained variance, silhouette) for 2+ jobs.\nUse to evaluate hyperparameter choices. After comparing, ask the user which job best fits their goal.\n- Visualization clarity → low TE (<0.1)\n- Tight clusters → low QE + high silhouette\n- Dimensionality reduction → high explained variance (>0.8)\n\naction=cancel: Not instant — worker checks between phases. Expect up to 30s delay.\naction=delete: WARNING — job ID will no longer work with results or any other tool.\nNOT FOR: Submitting new jobs — use train_som for that.',{action:o.enum(["status","list","compare","cancel","delete"]).describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files"),job_id:o.string().optional().describe("Job ID — required for action=status, cancel, delete"),job_ids:o.array(o.string()).optional().describe("Array of job IDs — required for action=compare (minimum 2)"),dataset_id:o.string().optional().describe("Filter jobs by dataset ID — only used for action=list")},async({action:e,job_id:t,job_ids:o,dataset_id:a})=>{if("status"===e){if(!t)throw new Error("jobs(status) requires job_id");const e=await f("GET",`/v1/jobs/${t}`),o=e.status,a=100*(e.progress??0),n=null!=e.label&&""!==e.label?String(e.label):null;let r=`${n?`Job ${n} (id: ${t})`:`Job ${t}`}: ${o} (${a.toFixed(1)}%)`;return"completed"===o?r+=` | Results ready. Use results(action=get, job_id="${t}") to retrieve.`:"failed"===o&&(r+=` | Error: ${e.error??"unknown"}`),{content:[{type:"text",text:r}]}}if("list"===e){const e=a?`/v1/jobs?dataset_id=${a}`:"/v1/jobs",t=await f("GET",e);if(Array.isArray(t)){const e=t.map(e=>{const t=String(e.id??""),o=String(e.status??""),a=null!=e.label&&""!==e.label?String(e.label):null;return a?`${a} (id: ${t}) — ${o}`:`id: ${t} — ${o}`});return{content:[{type:"text",text:e.length>0?e.join("\n"):"No jobs found."}]}}return h(t)}if("compare"===e){if(!o||o.length<2)throw new Error("jobs(compare) requires at least 2 job_ids");const e=o.join(","),t=(await f("GET",`/v1/jobs/compare?ids=${e}`)).comparisons??[],a=["| Job ID | Grid | Epochs | Model | QE | TE | Expl.Var | Silhouette |","|--------|------|--------|-------|----|----|----------|------------|"];for(const e of t){if(e.error){a.push(`| ${e.job_id.slice(0,8)}... | — | — | — | ${e.error} | — | — | — |`);continue}const t=e.grid,o=e.epochs,n=e=>null!=e?Number(e).toFixed(4):"—";a.push(`| ${e.job_id.slice(0,8)}... | ${t?`${t[0]}×${t[1]}`:"—"} | ${o?`${o[0]}+${o[1]}`:"—"} | ${e.model??"—"} | ${n(e.quantization_error)} | ${n(e.topographic_error)} | ${n(e.explained_variance)} | ${n(e.silhouette)} |`)}return{content:[{type:"text",text:a.join("\n")}]}}if("cancel"===e){if(!t)throw new Error("jobs(cancel) requires job_id");return h(await f("POST",`/v1/jobs/${t}/cancel`))}if("delete"===e){if(!t)throw new Error("jobs(delete) requires job_id");return h(await f("DELETE",`/v1/jobs/${t}`))}throw new Error("Invalid action")}),_.tool("results",'Retrieve, recolor, download, export, or run temporal flow on a completed SOM job.\n\n| Action | Use when | Sync/Async |\n|--------|----------|------------|\n| get | First look after training — combined view + quality metrics | instant |\n| export | Learning curve, raw weights, or per-node stats | instant |\n| download | Saving figures to a local folder | instant |\n| recolor | Changing colormap or output format without retraining | async (~10–30s) |\n| transition_flow | Temporal dynamics on time-ordered data | async (~30–60s) |\n\nONLY call this after jobs(action=status) returns "completed".\nESCALATION: If job not found, verify job_id. If "job not complete", poll with jobs(action=status).\n\naction=get: Returns text summary with quality metrics and inline images.\n  - figures: omit = combined only. "all" = all plots. Array = specific logical names (combined, umatrix, hit_histogram, correlation, component_1..N).\n  - include_individual: if true (and figures omitted), inlines every component plane.\n  - After showing results, guide the user: QE interpretation, whether to retrain, which features to explore.\n  - METRIC INTERPRETATION: QE<1.5 good | TE<0.1 good | Explained variance>0.7 good | Silhouette higher=better.\n\naction=export: Structured data exports.\n  - export=training_log: learning curve sparklines + plot. Diagnose convergence/plateau/divergence.\n  - export=weights: full weight matrix + normalization stats. For external analysis or custom viz.\n  - export=nodes: per-node hit count + feature stats. Profile clusters and operating modes.\n\naction=download: Save figures to disk. Use so user can open, share, or version files locally.\n  - folder: e.g. "." or "./results". If job has a label, a named subfolder may be created.\n  - figures: "all" (default) or array of filenames.\n  - include_json: also save summary.json.\n\naction=recolor: Change colormap or output format — no retraining. Returns a new job_id; auto-polls 60s.\n  AFTER: use results(action=get, job_id=NEW_JOB_ID).\n  Colormaps: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, balance, RdBu, Spectral.\n\naction=transition_flow: Temporal state transition arrows on the SOM grid. Requires time-ordered data.\n  - lag=1 (default): immediate next-step | lag=N: N-step horizon (e.g. 24 for daily cycles in hourly data).\n  - min_transitions: filter noisy arrows. Increase for large datasets.\n  BEFORE calling: confirm rows are in chronological order.\nNOT FOR: Jobs that haven\'t completed. Use jobs(action=status) to check first.',{action:o.enum(["get","recolor","download","export","transition_flow"]).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:o.string().describe("Job ID of a completed job"),figures:o.union([o.enum(["default","combined_only","all","images"]),o.array(o.string())]).optional().describe("action=get: omit=combined only; 'all'=all plots; array=specific (combined,umatrix,hit_histogram,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),include_individual:o.boolean().optional().default(!1).describe("action=get only: if true and figures omitted, inline each component plane, umatrix, hit histogram"),include_json:o.boolean().optional().default(!1).describe("action=download only: also save summary.json and JSON artifacts"),folder:o.string().optional().describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to MCP working directory."),colormap:o.string().optional().describe("action=recolor: colormap name (default: coolwarm). action=transition_flow: U-matrix background colormap (default: grays). Examples: viridis, plasma, balance, RdBu."),output_format:o.enum(["png","pdf","svg"]).optional().default("png").describe("action=recolor / transition_flow: output image format (default: png)"),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x, default), print (4x)"),recolor_figures:o.array(o.string()).optional().describe("action=recolor: which figures to re-render (default: [combined]). Options: combined, umatrix, hit_histogram, correlation, component_1..N"),export:o.enum(["training_log","weights","nodes"]).optional().describe("action=export: training_log=learning curve+sparklines; weights=full weight matrix; nodes=per-node stats"),lag:o.number().int().min(1).optional().default(1).describe("action=transition_flow: step lag (default 1 = consecutive rows). Use larger for periodic analysis (e.g. 24 for daily in hourly data)."),min_transitions:o.number().int().min(1).optional().describe("action=transition_flow: minimum transition count to draw an arrow (default: auto). Increase to filter noise."),top_k:o.number().int().min(1).optional().default(10).describe("action=transition_flow: number of top-flow nodes in statistics (default 10)")},async({action:e,job_id:t,figures:o,include_individual:a,include_json:n,folder:r,colormap:l,output_format:c,output_dpi:d,recolor_figures:u,export:p,lag:m,min_transitions:h,top_k:_})=>{const w={standard:1,retina:2,print:4};if("get"===e){const e=await f("GET",`/v1/results/${t}`),n=e.summary??{},r=null!=e.label&&""!==e.label?String(e.label):null,i=r?`Results for ${r} (job_id: ${t})`:`Results for job_id: ${t}`,s=[],l=new Set,c=n.job_type??"train_som";n.output_format;if("transition_flow"===c){const e=n.lag??1,r=n.flow_stats??{};s.push({type:"text",text:[`Transition Flow ${i}`,`Parent SOM: ${n.parent_job_id??"N/A"} | Lag: ${e} | Samples: ${n.n_samples??0}`,"","Flow Statistics:",`  Mean flow magnitude: ${void 0!==r.mean_magnitude?Number(r.mean_magnitude).toFixed(4):"N/A"}`,`  Max flow magnitude:  ${void 0!==r.max_magnitude?Number(r.max_magnitude).toFixed(4):"N/A"}`,`  Nodes with flow:     ${r.n_nodes_with_flow??"N/A"}`,"","Arrows show net directional drift. Long/bright = frequent transitions. Short = stable states.","Background = U-matrix. Use results(action=transition_flow, lag=N) with larger N for longer-term structure."].join("\n")});for(const e of j(c,n,o,a))await E(s,t,e),l.add(e)}else if("project_variable"===c){const e=n.variable_name??"variable",r=n.aggregation??"mean",d=n.variable_stats??{};s.push({type:"text",text:[`Projected Variable: ${e} (${r}) — ${i}`,`Parent SOM: ${n.parent_job_id??"N/A"} | Samples: ${n.n_samples??0}`,"",`Variable Statistics (per-node ${r}):`,`  Min: ${void 0!==d.min?Number(d.min).toFixed(3):"N/A"}`,`  Max: ${void 0!==d.max?Number(d.max).toFixed(3):"N/A"}`,`  Mean: ${void 0!==d.mean?Number(d.mean).toFixed(3):"N/A"}`,`  Nodes with data: ${d.n_nodes_with_data??"N/A"}`].join("\n")});for(const e of j(c,n,o,a))await E(s,t,e),l.add(e)}else{const e=n.grid??[0,0],r=n.features??[],d=n.epochs,u=Array.isArray(d)?0===d[1]?`${d[0]} ordering only`:`${d[0]} ordering + ${d[1]} convergence`:String(d??"N/A"),p=e=>null!=e?Number(e).toFixed(4):"N/A",m=n.training_duration_seconds,f=n.ordering_errors,g=[`SOM Training ${i}`,`Grid: ${e[0]}×${e[1]} | Features: ${n.n_features??0} | Samples: ${n.n_samples??0}`,`Model: ${n.model??"SOM"} | Epochs: ${u}`,`Periodic: ${n.periodic??!0} | Normalize: ${n.normalize??"auto"}`,void 0!==n.sigma_f?`Sigma_f: ${n.sigma_f}`:"",void 0!==m?`Training duration: ${m}s`:"","","Quality Metrics:",`  Quantization Error: ${p(n.quantization_error)}  (lower is better)`,`  Topographic Error:  ${p(n.topographic_error)}   (<0.1 is good)`,`  Explained Variance: ${p(n.explained_variance)}  (>0.7 is good)`,`  Silhouette Score:   ${p(n.silhouette)}          (higher is better)`,`  Davies-Bouldin:     ${p(n.davies_bouldin)}      (lower is better)`,`  Calinski-Harabasz:  ${p(n.calinski_harabasz)}   (higher is better)`,f&&f.length>0?`  Final ordering QE: ${f.at(-1)?.toFixed(4)} (use results(action=export, export=training_log) for full curve)`:"","",`Features: ${r.join(", ")}`,n.selected_columns?`Selected columns: ${n.selected_columns.join(", ")}`:"",n.transforms?`Transforms: ${Object.entries(n.transforms).map(([e,t])=>`${e}=${t}`).join(", ")}`:"","","Next: analyze(job_id) for deeper insights. results(action=export, export=training_log) for learning curve."].filter(e=>""!==e).join("\n");s.push({type:"text",text:g});const h=j(c,n,o,a);for(const e of h)await E(s,t,e),l.add(e)}const d=n.files??[],u=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");for(const e of d)if(u(e)&&!l.has(e))await E(s,t,e);else if(e.endsWith(".json")&&"summary.json"!==e){const t="weights.json"===e?"Use results(action=export, export=weights) for full weight matrix.":"node_stats.json"===e?"Use results(action=export, export=nodes) for per-node statistics.":"Use results(action=export) for structured data.";s.push({type:"text",text:`${e}: ${t}`})}const p=n.features??[],m=n.job_type??"train_som";if(d.length>0){const e="train_som"===m||"render_variant"===m?`Logical names: combined, umatrix, hit_histogram, correlation, ${p.map((e,t)=>`component_${t+1}`).join(", ")}. `:"";s.push({type:"text",text:`Available: ${d.join(", ")}. ${e}Use results(action=get, figures=[...]) for specific plots or analyze(job_id) for analysis views.`})}return{content:s}}if("export"===e){if(!p)throw new Error("results(export) requires export param: training_log, weights, or nodes");if("training_log"===p){const e=await f("GET",`/v1/results/${t}/training-log`),o=e.ordering_errors??[],a=e.convergence_errors??[],n=e.training_duration_seconds,r=e.epochs,i=e=>{if(0===e.length)return"(no data)";const t=Math.min(...e),o=Math.max(...e)-t||1;return e.map(e=>"▁▂▃▄▅▆▇█"[Math.min(7,Math.floor((e-t)/o*7))]).join("")},s=[`Training Log — Job ${t}`,`Grid: ${JSON.stringify(e.grid)} | Model: ${e.model??"SOM"}`,"Epochs: "+(r?`[${r[0]} ordering, ${r[1]} convergence]`:"N/A"),"Duration: "+(null!=n?`${n}s`:"N/A"),`Features: ${e.n_features??"?"} | Samples: ${e.n_samples??"?"}`,"",`Ordering Phase (${o.length} epochs):`,`  Start QE: ${o[0]?.toFixed(4)??"—"}  →  End QE: ${o.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(o)}`];a.length>0?s.push("",`Convergence Phase (${a.length} epochs):`,`  Start QE: ${a[0]?.toFixed(4)??"—"}  →  End QE: ${a.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(a)}`):0===(r?.[1]??0)&&s.push("","Convergence phase: skipped (epochs[1]=0)");const l=e.quantization_error,c=e.explained_variance;null!=l&&s.push("",`Final QE: ${l.toFixed(4)} | Explained Variance: ${(c??0).toFixed(4)}`);const d=[{type:"text",text:s.join("\n")}];let u=!1;for(const e of["png","pdf","svg"])try{const{data:o}=await g(`/v1/results/${t}/image/learning_curve.${e}`);d.push({type:"image",data:o.toString("base64"),mimeType:S(`learning_curve.${e}`),annotations:{audience:["user"],priority:.8}}),u=!0;break}catch{continue}return u||d.push({type:"text",text:"(learning curve plot not available)"}),{content:d}}if("weights"===p){const e=await f("GET",`/v1/results/${t}/weights`),o=e.features??[],a=e.n_nodes??0,n=e.grid??[0,0],r=[`SOM Weights — Job ${t}`,`Grid: ${n[0]}×${n[1]} | Nodes: ${a} | Features: ${o.length}`,`Features: ${o.join(", ")}`,"","Normalization Stats:"],i=e.normalization_stats??{};for(const[e,t]of Object.entries(i))r.push(`  ${e}: mean=${t.mean?.toFixed(4)}, std=${t.std?.toFixed(4)}`);return r.push("","Full weight matrix in JSON below. Use denormalized_weights for original-scale values."),{content:[{type:"text",text:r.join("\n")},{type:"text",text:JSON.stringify(e,null,2)}]}}const e=await f("GET",`/v1/results/${t}/nodes`),o=[...e].sort((e,t)=>(t.hit_count??0)-(e.hit_count??0)).slice(0,10),a=e.filter(e=>0===e.hit_count).length,n=e.reduce((e,t)=>e+(t.hit_count??0),0),r=[`Node Statistics — Job ${t}`,`Total nodes: ${e.length} | Active: ${e.length-a} | Empty: ${a} | Total hits: ${n}`,"","Top 10 Most Populated Nodes:","| Node | Coords | Hits | Hit% |","|------|--------|------|------|"];for(const e of o){if(0===e.hit_count)break;const t=e.coords,o=(e.hit_count/n*100).toFixed(1);r.push(`| ${e.node_index} | (${t?.[0]?.toFixed(1)}, ${t?.[1]?.toFixed(1)}) | ${e.hit_count} | ${o}% |`)}return{content:[{type:"text",text:r.join("\n")},{type:"text",text:`\nFull node statistics JSON:\n${JSON.stringify(e,null,2)}`}]}}if("download"===e){if(!r)throw new Error("results(download) requires folder");const e=await f("GET",`/v1/results/${t}`),a=e.summary??{},l=null!=e.label&&""!==e.label?String(e.label):null,c=a.files??[],d=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");let u;"all"===o||"images"===o||void 0===o?u=n?c:c.filter(d):Array.isArray(o)?(u=o,n&&!u.includes("summary.json")&&(u=[...u,"summary.json"])):u=c.filter(d);let p=s.resolve(r);!l||"."!==r&&"./results"!==r&&"results"!==r||(p=s.join(p,l)),await i.mkdir(p,{recursive:!0});const m=[];for(const e of u)try{const{data:o}=await g(`/v1/results/${t}/image/${e}`);await i.writeFile(s.join(p,e),o),m.push(e)}catch{}return{content:[{type:"text",text:m.length>0?`Saved ${m.length} file(s) to ${p}: ${m.join(", ")}`:"No files saved. Check job_id and that the job is completed."}]}}if("recolor"===e){if(!l)throw new Error("results(recolor) requires colormap");const e={colormap:l,figures:u??["combined"],output_format:c??"png",output_dpi:w[d??"retina"]??2},o=(await f("POST",`/v1/results/${t}/render`,e)).id;if("completed"===(await b(o,6e4)).status){const e=[{type:"text",text:`Re-rendered with colormap "${l}". New job_id: ${o}.`}];for(const t of u??["combined"]){const a=c??"png",n=t.includes(".")?t:`${t}.${a}`;await E(e,o,n)}return{content:e}}return{content:[{type:"text",text:`Recolor job ${o} submitted. Poll with jobs(action=status, job_id="${o}"), then results(action=get, job_id="${o}").`}]}}if("transition_flow"===e){const e={lag:m??1,output_format:c??"png"};void 0!==h&&(e.min_transitions=h),void 0!==_&&(e.top_k=_),void 0!==l&&(e.colormap=l),d&&"retina"!==d&&(e.output_dpi=w[d]??2);const o=(await f("POST",`/v1/results/${t}/transition-flow`,e)).id,a=await b(o,12e4);if("completed"===a.status){const e=((await f("GET",`/v1/results/${o}`)).summary??{}).flow_stats??{},a=[{type:"text",text:[`Transition Flow (job: ${o}) | Parent SOM: ${t} | Lag: ${m??1}`,`Active flow nodes: ${e.active_flow_nodes??"N/A"} | Total transitions: ${e.total_transitions??"N/A"}`,`Mean magnitude: ${void 0!==e.mean_magnitude?Number(e.mean_magnitude).toFixed(4):"N/A"}`].join("\n")}];return await E(a,o,`transition_flow_lag${m??1}.${c??"png"}`),{content:a}}return"failed"===a.status?{content:[{type:"text",text:`Transition flow job ${o} failed: ${a.error??"unknown error"}`}]}:{content:[{type:"text",text:`Transition flow job ${o} submitted. Poll with jobs(action=status, job_id="${o}"), retrieve with results(action=get, job_id="${o}").`}]}}throw new Error("Invalid action")}),_.tool("project",'Project variables onto a trained SOM — either from a formula expression or a pre-computed values array.\n\n| Action | Use when | Input |\n|--------|----------|-------|\n| expression | Variable can be computed from existing dataset columns (ratio, diff, log-transform, rolling stat) | dataset_id + expression string |\n| values | Variable is externally computed (e.g. revenue from a CRM, anomaly scores from another model) | job_id + values array |\n\nMODES for action=expression:\n- Default (no project_onto_job): add the derived column to the dataset CSV. Available for future train_som calls.\n- With project_onto_job: compute the column and project it onto the SOM — returns a visualization.\n\nCOMMON EXPRESSIONS:\n- Ratio:       "revenue / cost"\n- Difference:  "US10Y - US3M"\n- Log return:  "log(close) - log(open)"\n- Z-score:     "(volume - rolling_mean(volume, 20)) / rolling_std(volume, 20)"\n- First diff:  "diff(consumption)"\n\nSUPPORTED FUNCTIONS: +, -, *, /, ^, log, sqrt, abs, exp, sin, cos, diff(col), rolling_mean(col, w), rolling_std(col, w)\nUse underscore-normalized column names (spaces → underscores: e.g. fixed_acidity not "fixed acidity").\n\nCOMMON MISTAKES:\n- action=values: values array must be exactly n_samples long (same count as training CSV rows)\n- action=expression: division by zero → set options.missing="skip"\n- Rolling functions produce NaN for the first (window-1) rows\n\nNOT FOR: Re-training. NOT FOR: Text/categorical data.\nAFTER projecting: use results(action=get) to view the projection plot if a new job_id was returned.',{action:o.enum(["expression","values"]).describe("expression: compute formula from dataset columns (add to dataset or project onto SOM); values: project a pre-computed numeric array onto the SOM"),name:o.string().describe("Name for the variable (used in column header and visualization label)"),dataset_id:o.string().optional().describe("action=expression: Dataset ID (source of column data). Required unless project_onto_job handles the dataset."),expression:o.string().optional().describe("action=expression: Math expression referencing column names. Examples: 'revenue / cost', 'log(price)', 'rolling_mean(volume, 20)', 'diff(temperature)'"),project_onto_job:o.string().optional().describe("action=expression: If provided, project the derived variable onto this completed train_som job instead of adding to dataset"),options:o.object({missing:o.enum(["skip","zero","interpolate"]).optional().default("skip").describe("Handle NaN/missing values (default: skip)"),window:o.number().int().optional().describe("Default rolling window size (default 20)"),description:o.string().optional().describe("Human-readable description of the variable")}).optional().describe("action=expression: evaluation options"),job_id:o.string().optional().describe("action=values: Job ID of a completed train_som job to project onto"),variable_name:o.string().optional().describe("action=values: Display name for the variable (alias for name; name takes precedence)"),values:o.array(o.number()).optional().describe("action=values: Pre-computed values — one per training sample, in original CSV row order. Length must match n_samples exactly."),aggregation:o.enum(["mean","median","sum","min","max","std","count"]).optional().default("mean").describe("How to aggregate values per SOM node when projecting (default: mean). Use sum for totals, max for peaks, count for frequencies."),output_format:o.enum(["png","pdf","svg"]).optional().default("png"),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina"),colormap:o.string().optional().describe("Colormap for projection plot (default: coolwarm). Examples: viridis, plasma, RdBu, Spectral.")},async({action:e,name:t,dataset_id:o,expression:a,project_onto_job:n,options:r,job_id:i,variable_name:s,values:l,aggregation:c,output_format:d,output_dpi:u,colormap:p})=>{const m={standard:1,retina:2,print:4},g=t||s||"variable";if("values"===e){if(!i)throw new Error("project(values) requires job_id");if(!l||0===l.length)throw new Error("project(values) requires values array");const e={variable_name:g,values:l,aggregation:c??"mean",output_format:d??"png"};u&&"retina"!==u&&(e.output_dpi=m[u]??2),p&&(e.colormap=p);const t=(await f("POST",`/v1/results/${i}/project`,e)).id,o=await b(t);if("completed"===o.status){const e=(await f("GET",`/v1/results/${t}`)).summary??{},o=e.variable_stats??{},a=[{type:"text",text:[`Projected Variable: ${g} (${c??"mean"}) — job: ${t}`,`Parent SOM: ${i} | Samples: ${e.n_samples??0}`,`Min: ${void 0!==o.min?Number(o.min).toFixed(3):"N/A"} | Max: ${void 0!==o.max?Number(o.max).toFixed(3):"N/A"} | Mean: ${void 0!==o.mean?Number(o.mean).toFixed(3):"N/A"}`,`Nodes with data: ${o.n_nodes_with_data??"N/A"}`].join("\n")}];return await E(a,t,`projected_${g.replace(/[^a-zA-Z0-9_]/g,"_")}.${e.output_format??d??"png"}`),{content:a}}return"failed"===o.status?{content:[{type:"text",text:`project(values) job ${t} failed: ${o.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(values) job ${t} submitted. Poll with jobs(action=status, job_id="${t}"), retrieve with results(action=get, job_id="${t}").`}]}}if(!a)throw new Error("project(expression) requires expression");if(n){const e={name:g,expression:a,aggregation:c??"mean",output_format:d??"png"};o&&(e.dataset_id=o),r&&(e.options=r),u&&"retina"!==u&&(e.output_dpi=m[u]??2),p&&(e.colormap=p);const t=(await f("POST",`/v1/results/${n}/derive`,e)).id,i=await b(t);if("completed"===i.status){const e=(await f("GET",`/v1/results/${t}`)).summary??{},o=e.variable_stats??{},r=[{type:"text",text:[`Derived Variable Projected: ${g} — job: ${t}`,`Expression: ${a} | Parent SOM: ${n} | Aggregation: ${c??"mean"}`,`Min: ${void 0!==o.min?Number(o.min).toFixed(3):"N/A"} | Max: ${void 0!==o.max?Number(o.max).toFixed(3):"N/A"} | Mean: ${void 0!==o.mean?Number(o.mean).toFixed(3):"N/A"}`,`Nodes with data: ${o.n_nodes_with_data??"N/A"}`,e.nan_count?`NaN values: ${e.nan_count}`:""].filter(Boolean).join("\n")}];return await E(r,t,`projected_${g.replace(/[^a-zA-Z0-9_]/g,"_")}.${e.output_format??d??"pdf"}`),{content:r}}return"failed"===i.status?{content:[{type:"text",text:`project(expression) job ${t} failed: ${i.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(expression) job ${t} submitted. Poll with jobs(action=status, job_id="${t}"), retrieve with results(action=get, job_id="${t}").`}]}}if(!o)throw new Error("project(expression) without project_onto_job requires dataset_id");const h={name:g,expression:a};r&&(h.options=r);const _=(await f("POST",`/v1/datasets/${o}/derive`,h)).id,w=await b(_);if("completed"===w.status){const e=(await f("GET",`/v1/results/${_}`)).summary??{};return{content:[{type:"text",text:[`Derived column "${g}" added to dataset ${o}`,`Expression: ${a} | Rows: ${e.n_rows??"?"}`,e.nan_count?`NaN values: ${e.nan_count}`:"",`Min: ${e.min??"?"} | Max: ${e.max??"?"} | Mean: ${e.mean??"?"}`,"Column now available. Use datasets(action=preview) to verify, or include in train_som via the 'columns' parameter."].filter(Boolean).join("\n")}]}}return"failed"===w.status?{content:[{type:"text",text:`project(expression) job ${_} failed: ${w.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(expression) job ${_} submitted. Poll with jobs(action=status, job_id="${_}").`}]}}),_.tool("account","Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.\n\n| Action | Use when |\n|--------|----------|\n| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |\n| request_compute | Upgrading to cloud burst (required for large grids or GPU). Leave tier blank to list options. |\n| compute_status | Checking if a burst lease is active and how much time remains |\n| release_compute | Manually terminating an active lease to stop billing |\n| history | Viewing recent compute leases and credit spend |\n| add_funds | Getting instructions to add credits |\n\naction=status: Returns plan tier, compute class (CPU/GPU), usage limits, live queue state, training time estimates, and credit balance.\n  Use BEFORE large jobs to check GPU availability and estimate wait time.\naction=request_compute: Provisions an ephemeral cloud burst EC2 instance. Data is in shared R2 — no re-upload needed. Wait ~3 min after requesting before submitting jobs.\nNOT FOR: Training itself — use train_som. This tool only manages the account and compute lease.",{action:o.enum(["status","request_compute","compute_status","release_compute","history","add_funds"]).describe("status: plan/license/queue info; request_compute: provision burst; compute_status: check active lease; release_compute: stop lease; history: recent compute usage; add_funds: instructions"),tier:o.string().optional().describe("action=request_compute: tier ID (e.g. cpu-8, gpu-t4). Omit to list options."),duration_minutes:o.number().optional().describe("action=request_compute: lease duration in minutes (default: 60)"),limit:o.number().optional().describe("action=history: number of records to return (default: 10)")},async({action:e,tier:t,duration_minutes:o,limit:a})=>{if("status"===e){const e=await f("GET","/v1/system/info"),t=e.plan??{},o=e.backend??{},a=e.status??{},n=e.training_time_estimates_seconds??{},r=e.worker_topology??{},i=t.gpu_enabled??e.gpu_available??!1?o.gpu_model?`GPU (${o.gpu_model}${o.gpu_vram_gb?`, ${o.gpu_vram_gb}GB`:""})`:"GPU":"CPU only",s=e=>-1===e||"-1"===e?"unlimited":String(e??"?"),l=await f("GET","/v1/compute/history?limit=5").catch(()=>null),c=await f("GET","/v1/compute/lease").catch(()=>null),d=[`Plan: ${String(t.tier??"unknown").charAt(0).toUpperCase()}${String(t.tier??"unknown").slice(1)} | Compute: ${i}`,`  Concurrency: ${t.max_concurrent_jobs??"?"} jobs | Datasets: ${s(t.max_datasets)} (${s(t.max_dataset_rows)} rows each)`,`  Monthly Jobs: ${s(t.max_monthly_jobs)} | Grid Size: ${s(t.max_grid_size)} | Features: ${s(t.max_features)}`];l&&d.push(`  Credits: $${(l.credit_balance_cents/100).toFixed(2)} remaining`),o.memory_gb&&d.push(`  Backend Memory: ${o.memory_gb} GB`),c&&c.lease_id&&d.push("",`Active Burst Lease: ${c.tier} | ${Math.round(c.time_remaining_ms/6e4)} min left`);const u=Number(a.running_jobs??e.running_jobs??0),p=Number(a.pending_jobs??e.pending_jobs??0),m=Number(n?.total||0);if(d.push("",`Live Queue: ${u} running | ${p} pending | ~${Math.round((p+1)*m/60)} min wait`),void 0!==r.num_workers&&d.push(`Workers: ${r.num_workers}×${r.threads_per_worker} threads`),Object.keys(n).length>0){d.push("","Training Time Estimates:");for(const[e,t]of Object.entries(n))"formula"!==e&&d.push(`  ${e}: ~${t}s`)}return{content:[{type:"text",text:d.join("\n")}]}}if("request_compute"===e){if(!t)return{content:[{type:"text",text:"Available Compute Tiers:\nCPU Tiers:\n  cpu-8: 16 vCPUs, 32 GB RAM (~$0.20/hr)\n  cpu-16: 32 vCPUs, 64 GB RAM (~$0.20/hr)\n  cpu-24: 48 vCPUs, 96 GB RAM (~$0.28/hr)\n  cpu-32: 64 vCPUs, 128 GB RAM (~$0.42/hr)\n  cpu-48: 96 vCPUs, 192 GB RAM (~$0.49/hr)\nGPU Tiers:\n  gpu-t4: 8 vCPUs, 32 GB, T4 16GB VRAM (~$0.22/hr)\n  gpu-t4x: 16 vCPUs, 64 GB, T4 16GB VRAM (~$0.36/hr)\n  gpu-t4xx: 32 vCPUs, 128 GB, T4 16GB VRAM (~$0.27/hr)\n  gpu-l4: 8 vCPUs, 32 GB, L4 24GB VRAM (~$0.41/hr)\n  gpu-l4x: 16 vCPUs, 64 GB, L4 24GB VRAM (~$0.37/hr)\n  gpu-a10: 8 vCPUs, 32 GB, A10G 24GB VRAM (~$0.51/hr)\n  gpu-a10x: 16 vCPUs, 64 GB, A10G 24GB VRAM (~$0.52/hr)"}]};const e=await f("POST","/v1/compute/lease",{tier:t,duration_minutes:o}),a="postpaid"===e.billing_mode?`Billing: Postpaid (usage logged, billed retrospectively)\nAccrued Balance: $${(e.credit_balance_cents/100).toFixed(2)}`:`Credits Remaining After Reserve: $${(e.credit_balance_cents/100).toFixed(2)}`;return{content:[{type:"text",text:`Compute Lease Requested:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nEstimated Wait: ${e.estimated_wait_minutes} minutes\nEstimated Cost: $${(e.estimated_cost_cents/100).toFixed(2)}\n${a}\n\nIMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.`}]}}if("compute_status"===e){const e=await f("GET","/v1/compute/lease");return"none"!==e.status&&e.lease_id?{content:[{type:"text",text:`Active Compute Lease:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nTier: ${e.tier} (${e.instance_type})\nTime Remaining: ${Math.round(e.time_remaining_ms/6e4)} minutes`}]}:{content:[{type:"text",text:"No active lease -- running on default Primary Server."}]}}if("release_compute"===e){const e=await f("DELETE","/v1/compute/lease"),t="postpaid"===e.billing_mode?`Cost Logged: $${(e.cost_cents/100).toFixed(2)} (postpaid — billed retrospectively)`:`Credits Deducted: $${((e.credits_deducted||e.cost_cents)/100).toFixed(2)}`;return{content:[{type:"text",text:`Compute Released:\nDuration Billed: ${e.duration_minutes} minutes\n${t}\nBalance: $${(e.final_balance_cents/100).toFixed(2)}\n\nRouting reverted to default Primary Server.`}]}}if("history"===e){const e=await f("GET",`/v1/compute/history?limit=${a||10}`),t=e.history.map(e=>`- ${e.started_at} | ${e.tier} | ${e.duration_minutes} min | $${(e.credits_charged/100).toFixed(2)}`).join("\n");return{content:[{type:"text",text:`Credit Balance: $${(e.credit_balance_cents/100).toFixed(2)}\n\nRecent Usage:\n${t}`}]}}return"add_funds"===e?{content:[{type:"text",text:"To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:\nbash scripts/manage-credits.sh add <org_id> <amount_usd>"}]}:{content:[{type:"text",text:`Unknown action: ${e}. Valid: status, request_compute, compute_status, release_compute, history, add_funds.`}]}}),_.prompt("info","Overview of the Barivia SOM 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 Self-Organizing Map (SOM) analytics engine. SOMs learn a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.","","**Core workflow:**","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** — `train_som` with grid size, epochs, model type, and preprocessing options. Use `preset=quick|standard|refined|high_res` for sensible defaults","5. **Monitor** — `get_job_status` to track progress; `get_results` to retrieve figures when complete","6. **Analyze** — `analyze` with various analysis types (see below)","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, `project(action=values)` to overlay new variables","","**Analysis types** (via `analyze`):","- `u_matrix` — cluster boundary distances","- `component_planes` — per-feature heatmaps","- `clusters` — automatic cluster detection and statistics","- `quality_report` — QE, TE, explained variance, trustworthiness, neighborhood preservation","- `hit_histogram` — data density across the map","- `transition_flow` — temporal flow patterns (requires time-ordered data)","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `project(action=expression)` — create computed columns from expressions (ratios, differences, etc.) or project onto SOM","- `project(action=values)` — overlay a pre-computed array onto a trained SOM","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, etc.) can be set at training or changed later via recolor_som.","","**Key tools:** datasets, train_som, jobs, results, analyze, project, inference, account, guide_barsom_workflow, explore_som.","","**Tips:**","- 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")}}]})),_.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling train_som. 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}") first, then call train_som with appropriate parameters or preset.`;try{const o=await f("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}}),_.tool("inference",'Use a trained SOM as a persistent inference artifact — score new data, enrich the training CSV, compare datasets, or generate a PDF report.\n\n| Action | Use when | Timing |\n|--------|----------|--------|\n| predict | Scoring new/unseen observations against the trained map | 5–120s |\n| enrich | Appending BMU coordinates + cluster_id to the original training CSV | 5–60s |\n| compare | Comparing hit distributions of a second dataset against training (drift, A/B) | 30–120s |\n| report | Generating a comprehensive PDF report for stakeholders | 30–180s |\n\nAll actions are async. Auto-polls to the action-specific timeout; returns a job_id if still running.\nNOT FOR: Retraining or changing the map — all actions treat the trained SOM as frozen.\nESCALATION: 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.\n\naction=predict: Returns predictions.csv with row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error.\n  High QE = row is far from its nearest prototype = potential anomaly. Accepts dataset_id OR inline rows (≤500).\naction=enrich: Returns enriched.csv — original training CSV + bmu_x, bmu_y, bmu_node_index, cluster_id.\n  Flows into pandas/SQL/BI. Download URL in response, expires 15 min.\naction=compare: Returns density-diff heatmap (positive = B gained, negative = lost).\n  Positive nodes: dataset_b has more density here. Negative: training had more. Near-zero: minimal drift.\naction=report: Returns report.pdf — not inlineable. Includes quality metrics, combined view, component planes, cluster table, learning curve. Share download URL with user promptly.',{action:o.enum(["predict","enrich","compare","report"]).describe("predict: score new data; enrich: annotate training CSV with BMU coords; compare: drift/cohort diff heatmap; report: comprehensive PDF"),job_id:o.string().describe("Job ID of a completed SOM training job"),dataset_id:o.string().optional().describe("action=predict/compare: Dataset ID. predict=input data to score; compare=dataset B to compare against training."),rows:o.array(o.record(o.string(),o.number())).optional().describe("action=predict: inline rows to score (max 500). Each object maps feature name → value."),colormap:o.string().optional().describe("action=compare: colormap for diff heatmap (default: balance). action=report: n/a."),output_format:o.enum(["png","pdf","svg"]).optional().default("png").describe("action=compare: output format for heatmap (default: png)"),output_dpi:o.number().int().min(1).max(4).optional().default(2).describe("action=compare: DPI scale (default: 2)"),top_n:o.number().int().min(1).max(50).optional().default(10).describe("action=compare: number of top gained/lost nodes to report (default: 10)")},async({action:e,job_id:t,dataset_id:o,rows:a,colormap:n,output_format:r,output_dpi:i,top_n:s})=>{if("predict"===e){if(!o&&!a)throw new Error("inference(predict) requires dataset_id or rows");const e={};o&&(e.dataset_id=o),a&&(e.rows=a);const n=(await f("POST",`/v1/results/${t}/predict`,e)).id,r=await b(n,12e4);if("completed"===r.status){const e=await f("GET",`/v1/results/${n}`),t=e.summary??{},o=e.download_urls??{};return{content:[{type:"text",text:[`Predictions complete — job: ${n}`,`Rows scored: ${t.n_rows??"?"}`,`Mean QE: ${void 0!==t.mean_qe?Number(t.mean_qe).toFixed(4):"N/A"} | Max QE: ${void 0!==t.max_qe?Number(t.max_qe).toFixed(4):"N/A"}`,`Clusters: ${Object.keys(t.cluster_counts??{}).length}`,"Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error)",o["predictions.csv"]?`Download: ${o["predictions.csv"]}`:""].filter(Boolean).join("\n")}]}}return"failed"===r.status?{content:[{type:"text",text:`inference(predict) job ${n} failed: ${r.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(predict) job ${n} submitted. Poll with jobs(action=status, job_id="${n}").`}]}}if("enrich"===e){const e=(await f("POST",`/v1/results/${t}/enrich_dataset`,{})).id,o=await b(e,6e4);if("completed"===o.status){const t=await f("GET",`/v1/results/${e}`),o=t.summary??{},a=t.download_urls??{};return{content:[{type:"text",text:[`Enriched dataset ready — job: ${e}`,`Rows: ${o.n_rows??"?"} | Clusters: ${o.n_clusters??"?"}`,"Appended: bmu_x, bmu_y, bmu_node_index, cluster_id",a["enriched.csv"]?`Download: ${a["enriched.csv"]}`:""].filter(Boolean).join("\n")}]}}return"failed"===o.status?{content:[{type:"text",text:`inference(enrich) job ${e} failed: ${o.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(enrich) job ${e} submitted. Poll with jobs(action=status, job_id="${e}").`}]}}if("compare"===e){if(!o)throw new Error("inference(compare) requires dataset_id (dataset B)");const e={dataset_id:o,output_format:r,output_dpi:i,top_n:s};n&&(e.colormap=n);const a=(await f("POST",`/v1/results/${t}/compare_datasets`,e)).id,l=await b(a,12e4);if("completed"===l.status){const e=(await f("GET",`/v1/results/${a}`)).summary??{},t=e.top_gained_nodes??[],o=e.top_lost_nodes??[],n=e=>`  node ${e.bmu_node_index??"?"} [${(e.coords??[0,0]).map(e=>Number(e).toFixed(1)).join(",")}] Δ=${Number(e.density_diff??0).toFixed(4)}`,i=[{type:"text",text:[`Dataset comparison — job: ${a}`,`Dataset A rows: ${e.n_rows_a??"?"} | Dataset B rows: ${e.n_rows_b??"?"}`,"Top gained (B > A):",...t.slice(0,5).map(n),"Top lost (A > B):",...o.slice(0,5).map(n)].join("\n")}];return await E(i,a,`density_diff.${e.output_format??r??"png"}`),{content:i}}return"failed"===l.status?{content:[{type:"text",text:`inference(compare) job ${a} failed: ${l.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(compare) job ${a} submitted. Poll with jobs(action=status, job_id="${a}").`}]}}const l=(await f("POST",`/v1/results/${t}/generate_report`,{})).id,c=await b(l,18e4);if("completed"===c.status){const e=await f("GET",`/v1/results/${l}`),t=e.summary??{},o=e.download_urls??{},a=[];return await E(a,l,"report.pdf"),a.push({type:"text",text:[`Report generated — job: ${l}`,`Clusters: ${t.n_clusters??"?"} | Features: ${t.n_features??"?"}`,o["report.pdf"]?`Download PDF: ${o["report.pdf"]}`:""].filter(Boolean).join("\n")}),{content:a}}return"failed"===c.status?{content:[{type:"text",text:`inference(report) job ${l} failed: ${c.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(report) job ${l} submitted. Poll with jobs(action=status, job_id="${l}").`}]}});const T=new t;_.tool("send_feedback","Send brief feedback or feature requests to Barivia developers (max 190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.",{feedback:o.string().max(1330).describe("Feedback text")},async({feedback:e})=>h(await f("POST","/v1/feedback",{feedback:e}))),async function(){await _.connect(T)}().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{registerAppResource as n,registerAppTool as a,RESOURCE_MIME_TYPE as r}from"@modelcontextprotocol/ext-apps/server";import i from"node:fs/promises";import s from"node:path";const l=process.env.BARIVIA_API_URL??process.env.BARSOM_API_URL??"https://api.barivia.se",c=process.env.BARIVIA_API_KEY??process.env.BARSOM_API_KEY??"";c||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const u=parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS??"30000",10),d=new Set([502,503,504]);function p(e,t){return!(void 0===t||!d.has(t))||(e instanceof DOMException&&"AbortError"===e.name||e instanceof TypeError)}async function m(e,t,o=u){const n=new AbortController,a=setTimeout(()=>n.abort(),o);try{return await fetch(e,{...t,signal:n.signal})}finally{clearTimeout(a)}}async function f(e,t,o,n){const a=`${l}${t}`,r=n?.["Content-Type"]??"application/json",i=Math.random().toString(36).slice(2,10),s={Authorization:`Bearer ${c}`,"Content-Type":r,"X-Request-ID":i,...n};let u,d;void 0!==o&&(u="application/json"===r?JSON.stringify(o):String(o));for(let t=0;t<=2;t++)try{const o=await m(a,{method:e,headers:s,body:u}),n=await o.text();if(!o.ok){if(t<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}const e=(()=>{try{return JSON.parse(n)}catch{return null}})(),a=e?.error??n,r=400===o.status?" Check parameter types and required fields.":404===o.status?" The resource may not exist or may have been deleted.":409===o.status?" The job may not be in the expected state.":429===o.status?" Rate limit exceeded — wait a moment and retry.":"",i=e?.error_code?` (error_code: ${e.error_code})`:"";throw new Error(`${a}${i}${r}`)}return JSON.parse(n)}catch(e){if(d=e,t<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}throw e}throw d}async function g(e){const t=`${l}${e}`;let o;for(let n=0;n<=2;n++)try{const o=await m(t,{method:"GET",headers:{Authorization:`Bearer ${c}`}});if(!o.ok){if(n<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**n));continue}throw new Error(`API GET ${e} returned ${o.status}`)}const a=await o.arrayBuffer();return{data:Buffer.from(a),contentType:o.headers.get("content-type")??"application/octet-stream"}}catch(e){if(o=e,n<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**n));continue}throw e}throw o}function _(e){return{content:[{type:"text",text:JSON.stringify(e,null,2)}]}}async function b(e,t=3e4,o=1e3){const n=Date.now();for(;Date.now()-n<t;){const t=await f("GET",`/v1/jobs/${e}`),n=t.status;if("completed"===n||"failed"===n||"cancelled"===n)return{status:n,result_ref:t.result_ref,error:t.error};await new Promise(e=>setTimeout(e,o))}return{status:"timeout"}}const h=new e({name:"analytics-engine",version:"0.4.1",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\n3. **Train** → `jobs(action=train_map, dataset_id=...)` — returns a job_id; poll `jobs(action=status, job_id=...)` until completed\n4. **Analyze** → `results(action=get)` + `analyze` — visualize and interpret the map\n5. **Export / Inference** → `inference` (predict/enrich/compare/report)\n\n## Tool categories\n\n| Category | Tools |\n|----------|-------|\n| Data management | `datasets` (upload/preview/list/subset/delete) |\n| Jobs & training | `jobs` (train_map/status/list/compare/cancel/delete) |\n| Results | `results` (get/recolor/download/export/transition_flow), `analyze` |\n| Projection | `project` (expression/values) |\n| Inference & export | `inference` (predict/enrich/compare/report) |\n| Account | `account` (status/request_compute/compute_status/release_compute/history/add_funds) |\n| Utility | `guide_barsom_workflow`, `explore_map`, `send_feedback` |\n\n## Async job pattern\n\nMost operations are async. Every tool that submits a job either:\n- **Auto-polls** (project, 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)) — always requires manual `jobs(action=status, job_id=...)` polling\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. Map training takes 30s–10min depending on grid size and dataset.\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- Column names are case-sensitive; always match exactly what `datasets(action=preview)` returns\n- Numeric columns only (maps do not support text/categorical directly — encode first)\n- `predict` input columns must exactly match the features used during training"}),w=import.meta.dirname??s.dirname(new URL(import.meta.url).pathname);async function y(e){const t=[s.join(w,"views","src","views",e,"index.html"),s.join(w,"views",e,"index.html"),s.join(w,"..","dist","views","src","views",e,"index.html")];for(const e of t)try{return await i.readFile(e,"utf-8")}catch{continue}return null}const v="ui://barsom/map-explorer",$="ui://barsom/data-preview",x="ui://barsom/training-monitor";function j(e,t,o,n){const a=t.output_format??"pdf";if("transition_flow"===e){return[`transition_flow_lag${t.lag??1}.${a}`]}if("project_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${a}`]}if("derive_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${a}`]}const r=t.features??[],i=`combined.${a}`,s=`umatrix.${a}`,l=`hit_histogram.${a}`,c=`correlation.${a}`,u=r.map((e,t)=>`component_${t+1}_${e.replace(/[^a-zA-Z0-9_]/g,"_")}.${a}`),d=[i,s,l,c,...u];if(void 0===o||"default"===o)return n?d:[i];if("combined_only"===o)return[i];if("all"===o)return d;if(Array.isArray(o)){const e={combined:i,umatrix:s,hit_histogram:l,correlation:c};return r.forEach((t,o)=>{e[`component_${o+1}`]=u[o]}),o.map(t=>{const o=t.trim().toLowerCase();return e[o]?e[o]:t.includes(".")?t:null}).filter(e=>null!=e)}return[i]}function E(e){return e.endsWith(".pdf")?"application/pdf":e.endsWith(".svg")?"image/svg+xml":"image/png"}async function S(e,t,o){if(o.endsWith(".pdf")||o.endsWith(".svg"))e.push({type:"text",text:`${o} is ready (vector format — not inlineable). Use get_result_image(job_id="${t}", filename="${o}") to download it.`});else try{const{data:n}=await g(`/v1/results/${t}/image/${o}`);e.push({type:"image",data:n.toString("base64"),mimeType:E(o),annotations:{audience:["user"],priority:.8}})}catch{e.push({type:"text",text:`(${o} not available for inline display)`})}}n(h,v,v,{mimeType:r},async()=>{const e=await y("map-explorer");return{contents:[{uri:v,mimeType:r,text:e??"<html><body>Map Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(h,$,$,{mimeType:r},async()=>{const e=await y("data-preview");return{contents:[{uri:$,mimeType:r,text:e??"<html><body>Data Preview view not built yet.</body></html>"}]}}),n(h,x,x,{mimeType:r},async()=>{const e=await y("training-monitor");return{contents:[{uri:x,mimeType:r,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),a(h,"explore_map",{title:"Explore Map",description:"Interactive map explorer dashboard. Opens an inline visualization where you can toggle features, click nodes, and export figures. Use this after results(action=get) for a richer, interactive exploration experience. Falls back to text+image on hosts that don't support MCP Apps.",inputSchema:{job_id:o.string().describe("Job ID of a completed map training job")},_meta:{ui:{resourceUri:v}}},async({job_id:e})=>{const t=await f("GET",`/v1/results/${e}`),o=t.summary??{},n=[];n.push({type:"text",text:JSON.stringify({job_id:e,summary:o,download_urls:t.download_urls})});const a=o.output_format??"pdf";return await S(n,e,`combined.${a}`),{content:n}}),h.tool("guide_barsom_workflow","Retrieve the Standard Operating Procedure (SOP) for the mapping analysis pipeline.\nALWAYS call this tool first if you are unsure of the steps to execute a complete mapping analysis.\nThe workflow explains the exact sequence of tool calls needed: Upload → Preprocess → Train → Wait → Analyze.",{},async()=>({content:[{type:"text",text:"Mapping Analysis Standard Operating Procedure (SOP)\n\nStep 1: Upload Data\n- Use `datasets(action=upload)` with a local `file_path` to your CSV.\n- BEFORE UPLOADING: Clean the dataset to remove NaNs or malformed data.\n- Capture the `dataset_id` returned.\n\nStep 2: Preview & Preprocess\n- Use `datasets(action=preview)` to inspect columns, ranges, and types.\n- Check for skewed columns requiring 'log' or 'sqrt' transforms.\n- Check for cyclical or temporal features (hours, days) requiring `cyclic_features` or `temporal_features` during training.\n\nStep 3: Train the map\n- Call `jobs(action=train_map, dataset_id=...)` with the `dataset_id`.\n- Carefully select columns to include (start with 5-10).\n- Assign `feature_weights` (especially for categorical data with natural hierarchies).\n- Wait for the returned `job_id`.\n\nStep 4: Wait for Completion (ASYNC POLLING)\n- Use `jobs(action=status, job_id=...)` every 10-15 seconds.\n- Wait until status is \"completed\". DO NOT assume failure before 3 minutes (or longer for large grids).\n- If it fails, read the error message and adjust parameters (e.g., reduce grid size, fix column names).\n\nStep 5: Analyze and Export\n- Once completed, use `analyze(type=component_planes)` or `analyze(type=clusters)` to interpret the results.\n- Call `get_results` to get the final metrics (Quantization Error, Topographic Error)."}]})),h.tool("datasets",'Manage datasets: upload, preview, list, subset, or delete.\n\n| Action | Use when |\n|--------|----------|\n| upload | You have a CSV file to add — do this first |\n| preview | Before jobs(action=train_map) — always preview an unfamiliar dataset to spot cyclics, nulls, column types |\n| list | Finding dataset IDs for train_map, preview, or subset — see all available datasets |\n| subset | Creating a filtered/sliced view without re-uploading the full CSV |\n| delete | Cleaning up after experiments or freeing the dataset slot |\n\naction=upload: Prefer file_path over csv_data so the MCP reads the file directly. Returns dataset ID. Then use datasets(action=preview) before jobs(action=train_map).\nBEFORE UPLOADING: Ensure data has no NaNs, missing values, or formats that can\'t be handled. Categorical features should be numerically encoded or weighted.\naction=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before jobs(action=train_map) on an unfamiliar dataset.\naction=list: List all datasets belonging to the organisation with IDs, names, row/col counts.\naction=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range or filters.\n  - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)\n  - filters: array of conditions, ALL must match (AND logic). Each: { column, op, value }.\n    Operators: eq, ne, in, gt, lt, gte, lte, between\n    Examples: { column: "region", op: "eq", value: "Europe" } | { column: "age", op: "between", value: [18, 65] }\n  - Combine row_range + filters to slice both rows and values.\n  - Single filter object is also accepted (auto-wrapped).\naction=delete: Remove a dataset and all S3 data permanently.\n\nBEST FOR: Tabular numeric data. CSV with header required.\nNOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.\nESCALATION: 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:o.enum(["upload","preview","list","subset","delete"]).describe("upload: add CSV; preview: inspect columns/stats; list: see all datasets; subset: create filtered subset; delete: remove dataset"),name:o.string().optional().describe("Dataset name (required for action=upload and subset)"),file_path:o.string().optional().describe("Path to local CSV (for upload; prefer over csv_data)"),csv_data:o.string().optional().describe("Inline CSV string (for upload; use for small data)"),dataset_id:o.string().optional().describe("Dataset ID (required for preview, subset, and delete)"),n_rows:o.number().int().optional().default(5).describe("Sample rows to return (preview only)"),row_range:o.tuple([o.number().int(),o.number().int()]).optional().describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),filters:o.preprocess(e=>null==e||Array.isArray(e)?e:"object"==typeof e&&null!==e&&"column"in e?[e]:e,o.array(o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])})).optional().describe("For subset: filter conditions (AND logic). Single object or array. ops: eq, ne, in, gt, lt, gte, lte, between. Examples: { column: 'temp', op: 'between', value: [15, 30] }, { column: 'region', op: 'eq', value: 'Europe' }")),filter:o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])}).optional().describe("Deprecated — use filters instead. Single filter condition.")},async({action:e,name:t,file_path:o,csv_data:n,dataset_id:a,n_rows:r,row_range:l,filters:c,filter:u})=>{if("upload"===e){if(!t)throw new Error("datasets(upload) requires name");let e;if(o){const t=s.resolve(o);try{e=await i.readFile(t,"utf-8")}catch(e){const o=e instanceof Error?e.message:String(e);throw new Error(`Cannot read file "${t}": ${o}`)}}else{if(!(n&&n.length>0))throw new Error("datasets(upload) requires file_path or csv_data");e=n}return _(await f("POST","/v1/datasets",e,{"X-Dataset-Name":t,"Content-Type":"text/csv"}))}if("preview"===e){if(!a)throw new Error("datasets(preview) requires dataset_id");const e=await f("GET",`/v1/datasets/${a}/preview?n_rows=${r??5}`),t=e.columns??[],o=e.column_stats??[],n=e.cyclic_hints??[],i=e.sample_rows??[],s=e.datetime_columns??[],l=e.temporal_suggestions??[],c=e=>null==e?"—":Number(e).toFixed(3),u=[`Dataset: ${e.name} (${e.dataset_id})`,`${e.total_rows} rows × ${e.total_cols} columns`,"","Column Statistics:","| Column | Min | Max | Mean | Std | Nulls | Numeric |","|--------|-----|-----|------|-----|-------|---------|"];for(const e of o)u.push(`| ${e.column} | ${c(e.min)} | ${c(e.max)} | ${c(e.mean)} | ${c(e.std)} | ${e.null_count??0} | ${!1!==e.is_numeric?"yes":"no"} |`);if(n.length>0){u.push("","Detected Cyclic Feature Hints:");for(const e of n)u.push(`  • ${e.column} — period=${e.period} (${e.reason})`)}if(s.length>0){u.push("","Detected Datetime Columns:");for(const e of s){const t=(e.detected_formats??[]).map(e=>`${e.format} — ${e.description} (${(100*e.match_rate).toFixed(0)}% match)`).join("; ");u.push(`  • ${e.column}: sample="${e.sample}" → ${t}`)}}if(l.length>0){u.push("","Temporal Feature Suggestions (require user approval):");for(const e of l)u.push(`  • Columns: ${e.columns.join(" + ")} → format: "${e.format}"`),u.push(`    Available components: ${e.available_components.join(", ")}`)}if(i.length>0){u.push("",`Sample Rows (first ${i.length}):`),u.push(`| ${t.join(" | ")} |`),u.push(`| ${t.map(()=>"---").join(" | ")} |`);for(const e of i)u.push(`| ${t.map(t=>String(e[t]??"")).join(" | ")} |`)}return{content:[{type:"text",text:u.join("\n")}]}}if("subset"===e){if(!a)throw new Error("datasets(subset) requires dataset_id");if(!t)throw new Error("datasets(subset) requires name");const e=c??(u?[u]:void 0);if(void 0===l&&void 0===e)throw new Error("datasets(subset) requires at least one of row_range or filters");const o={name:t};void 0!==l&&(o.row_range=l),void 0!==e&&(o.filters=e);return _(await f("POST",`/v1/datasets/${a}/subset`,o))}if("list"===e){return _(await f("GET","/v1/datasets"))}if("delete"===e){if(!a)throw new Error("datasets(delete) requires dataset_id");return _(await f("DELETE",`/v1/datasets/${a}`))}throw new Error("Invalid action")}),h.tool("jobs",'Manage and inspect jobs.\n\n| Action | Use when |\n|--------|----------|\n| status | Polling after any async job submission — call every 10–15s |\n| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters |\n| compare | Picking the best training run from a set of completed jobs |\n| train_map | Submitting a new map training job — returns job_id for polling |\n| cancel | Stopping a running or pending job to free the worker |\n| delete | Permanently removing a job and all its S3 result files |\n\nASYNC POLLING PROTOCOL (action=status):\n- Poll every 10-15 seconds. Do NOT poll faster — it wastes context.\n- For large grids (40×40+), do not assume failure before 3 minutes on CPU.\n- Wait for status "completed" before calling results(action=get).\n- Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.\n\nESCALATION (action=status):\n- completed → call results(action=get) to retrieve the map and metrics\n- failed → extract the error message:\n  - memory/allocation error: reduce batch_size or grid size and retrain\n  - column missing: verify with datasets(action=preview)\n  - NaN error: user must clean the dataset\n\naction=train_map: Submits a training job. Returns job_id — poll with jobs(action=status, job_id=...).\naction=compare: Returns a metrics table (QE, TE, explained variance, silhouette) for 2+ jobs.\naction=cancel: Not instant — worker checks between phases. Expect up to 30s delay.\naction=delete: WARNING — job ID will no longer work with results or any other tool.',{action:o.enum(["status","list","compare","cancel","delete","train_map"]).describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files; train_map: submit new training job"),job_id:o.string().optional().describe("Job ID — required for action=status, cancel, delete"),job_ids:o.array(o.string()).optional().describe("Array of job IDs — required for action=compare (minimum 2)"),dataset_id:o.string().optional().describe("Required for action=train_map. For action=list, filter jobs by this dataset ID."),preset:o.enum(["quick","standard","refined","high_res"]).optional(),grid_x:o.number().int().optional(),grid_y:o.number().int().optional(),epochs:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseInt(e,10);if(!Number.isNaN(t))return t;const o=e.match(/^\[\s*(\d+)\s*,\s*(\d+)\s*\]$/);if(o)return[parseInt(o[1],10),parseInt(o[2],10)]}return e},o.union([o.number().int(),o.array(o.number().int()).length(2)]).optional()),model:o.enum(["SOM","RSOM","SOM-SOFT","RSOM-SOFT"]).optional().default("SOM"),periodic:o.boolean().optional().default(!0),columns:o.array(o.string()).optional(),cyclic_features:o.array(o.object({feature:o.string(),period:o.number()})).optional(),temporal_features:o.array(o.object({columns:o.array(o.string()),format:o.string(),extract:o.array(o.enum(["hour_of_day","day_of_year","month","day_of_week","minute_of_hour"])),cyclic:o.boolean().default(!0),separator:o.string().optional()})).optional(),feature_weights:o.record(o.number()).optional(),transforms:o.record(o.enum(["log","log1p","log10","sqrt","square","abs","invert","rank","none"])).optional(),normalize:o.union([o.enum(["all","auto"]),o.array(o.string())]).optional().default("auto"),sigma_f:o.preprocess(e=>null!=e&&"string"==typeof e?parseFloat(e):e,o.number().optional()),learning_rate:o.preprocess(e=>null!=e&&"string"==typeof e?parseFloat(e):e,o.union([o.number(),o.object({ordering:o.tuple([o.number(),o.number()]),convergence:o.tuple([o.number(),o.number()])})]).optional()),batch_size:o.number().int().optional(),quality_metrics:o.union([o.enum(["fast","standard","full"]),o.array(o.string())]).optional(),backend:o.enum(["auto","cpu","cuda","cuda_graphs"]).optional().default("auto"),output_format:o.enum(["png","pdf","svg"]).optional().default("png"),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina"),colormap:o.string().optional(),row_range:o.tuple([o.number().int().min(1),o.number().int().min(1)]).optional()},async e=>{const{action:t,job_id:o,job_ids:n,dataset_id:a}=e;if("train_map"===t){if(!a)throw new Error("jobs(train_map) requires dataset_id");const{preset:t,grid_x:o,grid_y:n,epochs:r,model:i,periodic:s,columns:l,cyclic_features:c,temporal_features:u,feature_weights:d,transforms:p,normalize:m,sigma_f:g,learning_rate:b,batch_size:h,quality_metrics:w,backend:y,output_format:v,output_dpi:$,colormap:x,row_range:j}=e;let E={};try{const e=await f("GET","/v1/training/config");E=e?.presets||{}}catch{if(t&&void 0===o&&void 0===r)throw new Error("Could not fetch training config from server, and missing explicit grid/epochs.")}const S=t?E[t]:void 0,T={model:i,periodic:s,normalize:m};void 0!==o&&void 0!==n?T.grid=[o,n]:S&&(T.grid=S.grid),void 0!==r?T.epochs=r:S&&(T.epochs=S.epochs),c?.length&&(T.cyclic_features=c),l?.length&&(T.columns=l),p&&Object.keys(p).length>0&&(T.transforms=p),u?.length&&(T.temporal_features=u),d&&Object.keys(d).length>0&&(T.feature_weights=d),void 0!==g&&(T.sigma_f=g),void 0!==b&&(T.learning_rate=b),void 0!==h?T.batch_size=h:S&&(T.batch_size=S.batch_size),void 0!==w&&(T.quality_metrics=w),void 0!==y&&"auto"!==y?T.backend=y:S?.backend&&(T.backend=S.backend),T.output_format=v??"png";const N={standard:1,retina:2,print:4};$&&"retina"!==$&&(T.output_dpi=N[$]??2),x&&(T.colormap=x),j&&j.length>=2&&j[0]<=j[1]&&(T.row_range=j);const A=await f("POST","/v1/jobs",{dataset_id:a,params:T}),P=A.id;try{const e=await f("GET","/v1/system/info"),t=Number(e.status?.pending_jobs??e.pending_jobs??0),o=Number(e.training_time_estimates_seconds?.total??(e.gpu_available?45:120)),n=Math.round(t*o/60);A.message=n>1?`Job submitted. You are #${t+1} in queue. Estimated wait: ~${n} min. Poll with jobs(action=status, job_id="${P}").`:`Job submitted. Poll with jobs(action=status, job_id="${P}").`}catch{A.message=`Job submitted. Poll with jobs(action=status, job_id="${P}").`}return _(A)}if("status"===t){if(!o)throw new Error("jobs(status) requires job_id");const e=await f("GET",`/v1/jobs/${o}`),t=e.status,n=100*(e.progress??0),a=null!=e.label&&""!==e.label?String(e.label):null;let r=`${a?`Job ${a} (id: ${o})`:`Job ${o}`}: ${t} (${n.toFixed(1)}%)`;return"completed"===t?r+=` | Results ready. Use results(action=get, job_id="${o}") to retrieve.`:"failed"===t&&(r+=` | Error: ${e.error??"unknown"}`),{content:[{type:"text",text:r}]}}if("list"===t){const e=a?`/v1/jobs?dataset_id=${a}`:"/v1/jobs",t=await f("GET",e);if(Array.isArray(t)){const e=t.map(e=>{const t=String(e.id??""),o=String(e.status??""),n=null!=e.label&&""!==e.label?String(e.label):null;return n?`${n} (id: ${t}) — ${o}`:`id: ${t} — ${o}`});return{content:[{type:"text",text:e.length>0?e.join("\n"):"No jobs found."}]}}return _(t)}if("compare"===t){if(!n||n.length<2)throw new Error("jobs(compare) requires at least 2 job_ids");const e=n.join(","),t=(await f("GET",`/v1/jobs/compare?ids=${e}`)).comparisons??[],o=["| Job ID | Grid | Epochs | Model | QE | TE | Expl.Var | Silhouette |","|--------|------|--------|-------|----|----|----------|------------|"];for(const e of t){if(e.error){o.push(`| ${e.job_id.slice(0,8)}... | — | — | — | ${e.error} | — | — | — |`);continue}const t=e.grid,n=e.epochs,a=e=>null!=e?Number(e).toFixed(4):"—";o.push(`| ${e.job_id.slice(0,8)}... | ${t?`${t[0]}×${t[1]}`:"—"} | ${n?`${n[0]}+${n[1]}`:"—"} | ${e.model??"—"} | ${a(e.quantization_error)} | ${a(e.topographic_error)} | ${a(e.explained_variance)} | ${a(e.silhouette)} |`)}return{content:[{type:"text",text:o.join("\n")}]}}if("cancel"===t){if(!o)throw new Error("jobs(cancel) requires job_id");return _(await f("POST",`/v1/jobs/${o}/cancel`))}if("delete"===t){if(!o)throw new Error("jobs(delete) requires job_id");return _(await f("DELETE",`/v1/jobs/${o}`))}throw new Error("Invalid action")}),h.tool("results",'Retrieve, recolor, download, export, or run temporal flow on a completed map job.\n\n| Action | Use when | Sync/Async |\n|--------|----------|------------|\n| get | First look after training — combined view + quality metrics | instant |\n| export | Learning curve, raw weights, or per-node stats | instant |\n| download | Saving figures to a local folder | instant |\n| recolor | Changing colormap or output format without retraining | async (~10–30s) |\n| transition_flow | Temporal dynamics on time-ordered data | async (~30–60s) |\n\nONLY call this after jobs(action=status) returns "completed".\nESCALATION: If job not found, verify job_id. If "job not complete", poll with jobs(action=status).\n\naction=get: Returns text summary with quality metrics and inline images.\n  - figures: omit = combined only. "all" = all plots. Array = specific logical names (combined, umatrix, hit_histogram, correlation, component_1..N).\n  - include_individual: if true (and figures omitted), inlines every component plane.\n  - After showing results, guide the user: QE interpretation, whether to retrain, which features to explore.\n  - METRIC INTERPRETATION: QE<1.5 good | TE<0.1 good | Explained variance>0.7 good | Silhouette higher=better.\n\naction=export: Structured data exports.\n  - export=training_log: learning curve sparklines + plot. Diagnose convergence/plateau/divergence.\n  - export=weights: full weight matrix + normalization stats. For external analysis or custom viz.\n  - export=nodes: per-node hit count + feature stats. Profile clusters and operating modes.\n\naction=download: Save figures to disk. Use so user can open, share, or version files locally.\n  - folder: e.g. "." or "./results". If job has a label, a named subfolder may be created.\n  - figures: "all" (default) or array of filenames.\n  - include_json: also save summary.json.\n\naction=recolor: Change colormap or output format — no retraining. Returns a new job_id; auto-polls 60s.\n  AFTER: use results(action=get, job_id=NEW_JOB_ID).\n  Colormaps: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, balance, RdBu, Spectral.\n\naction=transition_flow: Temporal state transition arrows on the map grid. Requires time-ordered data.\n  - lag=1 (default): immediate next-step | lag=N: N-step horizon (e.g. 24 for daily cycles in hourly data).\n  - min_transitions: filter noisy arrows. Increase for large datasets.\n  BEFORE calling: confirm rows are in chronological order.\nNOT FOR: Jobs that haven\'t completed. Use jobs(action=status) to check first.',{action:o.enum(["get","recolor","download","export","transition_flow"]).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:o.string().describe("Job ID of a completed job"),figures:o.union([o.enum(["default","combined_only","all","images"]),o.array(o.string())]).optional().describe("action=get: omit=combined only; 'all'=all plots; array=specific (combined,umatrix,hit_histogram,correlation,component_1..N). action=download: 'all'=all image files; array=specific filenames."),include_individual:o.boolean().optional().default(!1).describe("action=get only: if true and figures omitted, inline each component plane, umatrix, hit histogram"),include_json:o.boolean().optional().default(!1).describe("action=download only: also save summary.json and JSON artifacts"),folder:o.string().optional().describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to MCP working directory."),colormap:o.string().optional().describe("action=recolor: colormap name (default: coolwarm). action=transition_flow: U-matrix background colormap (default: grays). Examples: viridis, plasma, balance, RdBu."),output_format:o.enum(["png","pdf","svg"]).optional().default("png").describe("action=recolor / transition_flow: output image format (default: png)"),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x, default), print (4x)"),recolor_figures:o.array(o.string()).optional().describe("action=recolor: which figures to re-render (default: [combined]). Options: combined, umatrix, hit_histogram, correlation, component_1..N"),export:o.enum(["training_log","weights","nodes"]).optional().describe("action=export: training_log=learning curve+sparklines; weights=full weight matrix; nodes=per-node stats"),lag:o.number().int().min(1).optional().default(1).describe("action=transition_flow: step lag (default 1 = consecutive rows). Use larger for periodic analysis (e.g. 24 for daily in hourly data)."),min_transitions:o.number().int().min(1).optional().describe("action=transition_flow: minimum transition count to draw an arrow (default: auto). Increase to filter noise."),top_k:o.number().int().min(1).optional().default(10).describe("action=transition_flow: number of top-flow nodes in statistics (default 10)")},async({action:e,job_id:t,figures:o,include_individual:n,include_json:a,folder:r,colormap:l,output_format:c,output_dpi:u,recolor_figures:d,export:p,lag:m,min_transitions:_,top_k:h})=>{const w={standard:1,retina:2,print:4};if("get"===e){const e=await f("GET",`/v1/results/${t}`),a=e.summary??{},r=null!=e.label&&""!==e.label?String(e.label):null,i=r?`Results for ${r} (job_id: ${t})`:`Results for job_id: ${t}`,s=[],l=new Set,c=a.job_type??"train_som";a.output_format;if("transition_flow"===c){const e=a.lag??1,r=a.flow_stats??{};s.push({type:"text",text:[`Transition Flow ${i}`,`Parent map job: ${a.parent_job_id??"N/A"} | Lag: ${e} | Samples: ${a.n_samples??0}`,"","Flow Statistics:",`  Mean flow magnitude: ${void 0!==r.mean_magnitude?Number(r.mean_magnitude).toFixed(4):"N/A"}`,`  Max flow magnitude:  ${void 0!==r.max_magnitude?Number(r.max_magnitude).toFixed(4):"N/A"}`,`  Nodes with flow:     ${r.n_nodes_with_flow??"N/A"}`,"","Arrows show net directional drift. Long/bright = frequent transitions. Short = stable states.","Background = U-matrix. Use results(action=transition_flow, lag=N) with larger N for longer-term structure."].join("\n")});for(const e of j(c,a,o,n))await S(s,t,e),l.add(e)}else if("project_variable"===c){const e=a.variable_name??"variable",r=a.aggregation??"mean",u=a.variable_stats??{};s.push({type:"text",text:[`Projected Variable: ${e} (${r}) — ${i}`,`Parent map job: ${a.parent_job_id??"N/A"} | Samples: ${a.n_samples??0}`,"",`Variable Statistics (per-node ${r}):`,`  Min: ${void 0!==u.min?Number(u.min).toFixed(3):"N/A"}`,`  Max: ${void 0!==u.max?Number(u.max).toFixed(3):"N/A"}`,`  Mean: ${void 0!==u.mean?Number(u.mean).toFixed(3):"N/A"}`,`  Nodes with data: ${u.n_nodes_with_data??"N/A"}`].join("\n")});for(const e of j(c,a,o,n))await S(s,t,e),l.add(e)}else{const e=a.grid??[0,0],r=a.features??[],u=a.epochs,d=Array.isArray(u)?0===u[1]?`${u[0]} ordering only`:`${u[0]} ordering + ${u[1]} convergence`:String(u??"N/A"),p=e=>null!=e?Number(e).toFixed(4):"N/A",m=a.training_duration_seconds,f=a.ordering_errors,g=[`Map training ${i}`,`Grid: ${e[0]}×${e[1]} | Features: ${a.n_features??0} | Samples: ${a.n_samples??0}`,`Model: ${a.model??"SOM"} | Epochs: ${d}`,`Periodic: ${a.periodic??!0} | Normalize: ${a.normalize??"auto"}`,void 0!==a.sigma_f?`Sigma_f: ${a.sigma_f}`:"",void 0!==m?`Training duration: ${m}s`:"","","Quality Metrics:",`  Quantization Error: ${p(a.quantization_error)}  (lower is better)`,`  Topographic Error:  ${p(a.topographic_error)}   (<0.1 is good)`,`  Explained Variance: ${p(a.explained_variance)}  (>0.7 is good)`,`  Silhouette Score:   ${p(a.silhouette)}          (higher is better)`,`  Davies-Bouldin:     ${p(a.davies_bouldin)}      (lower is better)`,`  Calinski-Harabasz:  ${p(a.calinski_harabasz)}   (higher is better)`,f&&f.length>0?`  Final ordering QE: ${f.at(-1)?.toFixed(4)} (use results(action=export, export=training_log) for full curve)`:"","",`Features: ${r.join(", ")}`,a.selected_columns?`Selected columns: ${a.selected_columns.join(", ")}`:"",a.transforms?`Transforms: ${Object.entries(a.transforms).map(([e,t])=>`${e}=${t}`).join(", ")}`:"","","Next: analyze(job_id) for deeper insights. results(action=export, export=training_log) for learning curve."].filter(e=>""!==e).join("\n");s.push({type:"text",text:g});const _=j(c,a,o,n);for(const e of _)await S(s,t,e),l.add(e)}const u=a.files??[],d=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");for(const e of u)if(d(e)&&!l.has(e))await S(s,t,e);else if(e.endsWith(".json")&&"summary.json"!==e){const t="weights.json"===e?"Use results(action=export, export=weights) for full weight matrix.":"node_stats.json"===e?"Use results(action=export, export=nodes) for per-node statistics.":"Use results(action=export) for structured data.";s.push({type:"text",text:`${e}: ${t}`})}const p=a.features??[],m=a.job_type??"train_som";if(u.length>0){const e="train_som"===m||"render_variant"===m?`Logical names: combined, umatrix, hit_histogram, correlation, ${p.map((e,t)=>`component_${t+1}`).join(", ")}. `:"";s.push({type:"text",text:`Available: ${u.join(", ")}. ${e}Use results(action=get, figures=[...]) for specific plots or analyze(job_id) for analysis views.`})}return{content:s}}if("export"===e){if(!p)throw new Error("results(export) requires export param: training_log, weights, or nodes");if("training_log"===p){const e=await f("GET",`/v1/results/${t}/training-log`),o=e.ordering_errors??[],n=e.convergence_errors??[],a=e.training_duration_seconds,r=e.epochs,i=e=>{if(0===e.length)return"(no data)";const t=Math.min(...e),o=Math.max(...e)-t||1;return e.map(e=>"▁▂▃▄▅▆▇█"[Math.min(7,Math.floor((e-t)/o*7))]).join("")},s=[`Training Log — Job ${t}`,`Grid: ${JSON.stringify(e.grid)} | Model: ${e.model??"SOM"}`,"Epochs: "+(r?`[${r[0]} ordering, ${r[1]} convergence]`:"N/A"),"Duration: "+(null!=a?`${a}s`:"N/A"),`Features: ${e.n_features??"?"} | Samples: ${e.n_samples??"?"}`,"",`Ordering Phase (${o.length} epochs):`,`  Start QE: ${o[0]?.toFixed(4)??"—"}  →  End QE: ${o.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(o)}`];n.length>0?s.push("",`Convergence Phase (${n.length} epochs):`,`  Start QE: ${n[0]?.toFixed(4)??"—"}  →  End QE: ${n.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(n)}`):0===(r?.[1]??0)&&s.push("","Convergence phase: skipped (epochs[1]=0)");const l=e.quantization_error,c=e.explained_variance;null!=l&&s.push("",`Final QE: ${l.toFixed(4)} | Explained Variance: ${(c??0).toFixed(4)}`);const u=[{type:"text",text:s.join("\n")}];let d=!1;for(const e of["png","pdf","svg"])try{const{data:o}=await g(`/v1/results/${t}/image/learning_curve.${e}`);u.push({type:"image",data:o.toString("base64"),mimeType:E(`learning_curve.${e}`),annotations:{audience:["user"],priority:.8}}),d=!0;break}catch{continue}return d||u.push({type:"text",text:"(learning curve plot not available)"}),{content:u}}if("weights"===p){const e=await f("GET",`/v1/results/${t}/weights`),o=e.features??[],n=e.n_nodes??0,a=e.grid??[0,0],r=[`Map weights — Job ${t}`,`Grid: ${a[0]}×${a[1]} | Nodes: ${n} | Features: ${o.length}`,`Features: ${o.join(", ")}`,"","Normalization Stats:"],i=e.normalization_stats??{};for(const[e,t]of Object.entries(i))r.push(`  ${e}: mean=${t.mean?.toFixed(4)}, std=${t.std?.toFixed(4)}`);return r.push("","Full weight matrix in JSON below. Use denormalized_weights for original-scale values."),{content:[{type:"text",text:r.join("\n")},{type:"text",text:JSON.stringify(e,null,2)}]}}const e=await f("GET",`/v1/results/${t}/nodes`),o=[...e].sort((e,t)=>(t.hit_count??0)-(e.hit_count??0)).slice(0,10),n=e.filter(e=>0===e.hit_count).length,a=e.reduce((e,t)=>e+(t.hit_count??0),0),r=[`Node Statistics — Job ${t}`,`Total nodes: ${e.length} | Active: ${e.length-n} | Empty: ${n} | Total hits: ${a}`,"","Top 10 Most Populated Nodes:","| Node | Coords | Hits | Hit% |","|------|--------|------|------|"];for(const e of o){if(0===e.hit_count)break;const t=e.coords,o=(e.hit_count/a*100).toFixed(1);r.push(`| ${e.node_index} | (${t?.[0]?.toFixed(1)}, ${t?.[1]?.toFixed(1)}) | ${e.hit_count} | ${o}% |`)}return{content:[{type:"text",text:r.join("\n")},{type:"text",text:`\nFull node statistics JSON:\n${JSON.stringify(e,null,2)}`}]}}if("download"===e){if(!r)throw new Error("results(download) requires folder");const e=await f("GET",`/v1/results/${t}`),n=e.summary??{},l=null!=e.label&&""!==e.label?String(e.label):null,c=n.files??[],u=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");let d;"all"===o||"images"===o||void 0===o?d=a?c:c.filter(u):Array.isArray(o)?(d=o,a&&!d.includes("summary.json")&&(d=[...d,"summary.json"])):d=c.filter(u);let p=s.resolve(r);!l||"."!==r&&"./results"!==r&&"results"!==r||(p=s.join(p,l)),await i.mkdir(p,{recursive:!0});const m=[];for(const e of d)try{const{data:o}=await g(`/v1/results/${t}/image/${e}`);await i.writeFile(s.join(p,e),o),m.push(e)}catch{}return{content:[{type:"text",text:m.length>0?`Saved ${m.length} file(s) to ${p}: ${m.join(", ")}`:"No files saved. Check job_id and that the job is completed."}]}}if("recolor"===e){if(!l)throw new Error("results(recolor) requires colormap");const e={colormap:l,figures:d??["combined"],output_format:c??"png",output_dpi:w[u??"retina"]??2},o=(await f("POST",`/v1/results/${t}/render`,e)).id;if("completed"===(await b(o,6e4)).status){const e=[{type:"text",text:`Re-rendered with colormap "${l}". New job_id: ${o}.`}];for(const t of d??["combined"]){const n=c??"png",a=t.includes(".")?t:`${t}.${n}`;await S(e,o,a)}return{content:e}}return{content:[{type:"text",text:`Recolor job ${o} submitted. Poll with jobs(action=status, job_id="${o}"), then results(action=get, job_id="${o}").`}]}}if("transition_flow"===e){const e={lag:m??1,output_format:c??"png"};void 0!==_&&(e.min_transitions=_),void 0!==h&&(e.top_k=h),void 0!==l&&(e.colormap=l),u&&"retina"!==u&&(e.output_dpi=w[u]??2);const o=(await f("POST",`/v1/results/${t}/transition-flow`,e)).id,n=await b(o,12e4);if("completed"===n.status){const e=((await f("GET",`/v1/results/${o}`)).summary??{}).flow_stats??{},n=[{type:"text",text:[`Transition Flow (job: ${o}) | Parent map: ${t} | Lag: ${m??1}`,`Active flow nodes: ${e.active_flow_nodes??"N/A"} | Total transitions: ${e.total_transitions??"N/A"}`,`Mean magnitude: ${void 0!==e.mean_magnitude?Number(e.mean_magnitude).toFixed(4):"N/A"}`].join("\n")}];return await S(n,o,`transition_flow_lag${m??1}.${c??"png"}`),{content:n}}return"failed"===n.status?{content:[{type:"text",text:`Transition flow job ${o} failed: ${n.error??"unknown error"}`}]}:{content:[{type:"text",text:`Transition flow job ${o} submitted. Poll with jobs(action=status, job_id="${o}"), retrieve with results(action=get, job_id="${o}").`}]}}throw new Error("Invalid action")}),h.tool("project",'Project variables onto a trained map — either from a formula expression or a pre-computed values array.\n\n| Action | Use when | Input |\n|--------|----------|-------|\n| expression | Variable can be computed from existing dataset columns (ratio, diff, log-transform, rolling stat) | dataset_id + expression string |\n| values | Variable is externally computed (e.g. revenue from a CRM, anomaly scores from another model) | job_id + values array |\n\nMODES for action=expression:\n- Default (no project_onto_job): add the derived column to the dataset CSV. Available for future jobs(action=train_map) calls.\n- With project_onto_job: compute the column and project it onto the map — returns a visualization.\n\nCOMMON EXPRESSIONS:\n- Ratio:       "revenue / cost"\n- Difference:  "US10Y - US3M"\n- Log return:  "log(close) - log(open)"\n- Z-score:     "(volume - rolling_mean(volume, 20)) / rolling_std(volume, 20)"\n- First diff:  "diff(consumption)"\n\nSUPPORTED FUNCTIONS: +, -, *, /, ^, log, sqrt, abs, exp, sin, cos, diff(col), rolling_mean(col, w), rolling_std(col, w)\nUse underscore-normalized column names (spaces → underscores: e.g. fixed_acidity not "fixed acidity").\n\nCOMMON MISTAKES:\n- action=values: values array must be exactly n_samples long (same count as training CSV rows)\n- action=expression: division by zero → set options.missing="skip"\n- Rolling functions produce NaN for the first (window-1) rows\n\nNOT FOR: Re-training. NOT FOR: Text/categorical data.\nAFTER projecting: use results(action=get) to view the projection plot if a new job_id was returned.',{action:o.enum(["expression","values"]).describe("expression: compute formula from dataset columns (add to dataset or project onto map); values: project a pre-computed numeric array onto the map"),name:o.string().describe("Name for the variable (used in column header and visualization label)"),dataset_id:o.string().optional().describe("action=expression: Dataset ID (source of column data). Required unless project_onto_job handles the dataset."),expression:o.string().optional().describe("action=expression: Math expression referencing column names. Examples: 'revenue / cost', 'log(price)', 'rolling_mean(volume, 20)', 'diff(temperature)'"),project_onto_job:o.string().optional().describe("action=expression: If provided, project the derived variable onto this completed map training job instead of adding to dataset"),options:o.object({missing:o.enum(["skip","zero","interpolate"]).optional().default("skip").describe("Handle NaN/missing values (default: skip)"),window:o.number().int().optional().describe("Default rolling window size (default 20)"),description:o.string().optional().describe("Human-readable description of the variable")}).optional().describe("action=expression: evaluation options"),job_id:o.string().optional().describe("action=values: Job ID of a completed map training job to project onto"),variable_name:o.string().optional().describe("action=values: Display name for the variable (alias for name; name takes precedence)"),values:o.array(o.number()).optional().describe("action=values: Pre-computed values — one per training sample, in original CSV row order. Length must match n_samples exactly."),aggregation:o.enum(["mean","median","sum","min","max","std","count"]).optional().default("mean").describe("How to aggregate values per map node when projecting (default: mean). Use sum for totals, max for peaks, count for frequencies."),output_format:o.enum(["png","pdf","svg"]).optional().default("png"),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina"),colormap:o.string().optional().describe("Colormap for projection plot (default: coolwarm). Examples: viridis, plasma, RdBu, Spectral.")},async({action:e,name:t,dataset_id:o,expression:n,project_onto_job:a,options:r,job_id:i,variable_name:s,values:l,aggregation:c,output_format:u,output_dpi:d,colormap:p})=>{const m={standard:1,retina:2,print:4},g=t||s||"variable";if("values"===e){if(!i)throw new Error("project(values) requires job_id");if(!l||0===l.length)throw new Error("project(values) requires values array");const e={variable_name:g,values:l,aggregation:c??"mean",output_format:u??"png"};d&&"retina"!==d&&(e.output_dpi=m[d]??2),p&&(e.colormap=p);const t=(await f("POST",`/v1/results/${i}/project`,e)).id,o=await b(t);if("completed"===o.status){const e=(await f("GET",`/v1/results/${t}`)).summary??{},o=e.variable_stats??{},n=[{type:"text",text:[`Projected Variable: ${g} (${c??"mean"}) — job: ${t}`,`Parent map: ${i} | Samples: ${e.n_samples??0}`,`Min: ${void 0!==o.min?Number(o.min).toFixed(3):"N/A"} | Max: ${void 0!==o.max?Number(o.max).toFixed(3):"N/A"} | Mean: ${void 0!==o.mean?Number(o.mean).toFixed(3):"N/A"}`,`Nodes with data: ${o.n_nodes_with_data??"N/A"}`].join("\n")}];return await S(n,t,`projected_${g.replace(/[^a-zA-Z0-9_]/g,"_")}.${e.output_format??u??"png"}`),{content:n}}return"failed"===o.status?{content:[{type:"text",text:`project(values) job ${t} failed: ${o.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(values) job ${t} submitted. Poll with jobs(action=status, job_id="${t}"), retrieve with results(action=get, job_id="${t}").`}]}}if(!n)throw new Error("project(expression) requires expression");if(a){const e={name:g,expression:n,aggregation:c??"mean",output_format:u??"png"};o&&(e.dataset_id=o),r&&(e.options=r),d&&"retina"!==d&&(e.output_dpi=m[d]??2),p&&(e.colormap=p);const t=(await f("POST",`/v1/results/${a}/derive`,e)).id,i=await b(t);if("completed"===i.status){const e=(await f("GET",`/v1/results/${t}`)).summary??{},o=e.variable_stats??{},r=[{type:"text",text:[`Derived Variable Projected: ${g} — job: ${t}`,`Expression: ${n} | Parent map: ${a} | Aggregation: ${c??"mean"}`,`Min: ${void 0!==o.min?Number(o.min).toFixed(3):"N/A"} | Max: ${void 0!==o.max?Number(o.max).toFixed(3):"N/A"} | Mean: ${void 0!==o.mean?Number(o.mean).toFixed(3):"N/A"}`,`Nodes with data: ${o.n_nodes_with_data??"N/A"}`,e.nan_count?`NaN values: ${e.nan_count}`:""].filter(Boolean).join("\n")}];return await S(r,t,`projected_${g.replace(/[^a-zA-Z0-9_]/g,"_")}.${e.output_format??u??"pdf"}`),{content:r}}return"failed"===i.status?{content:[{type:"text",text:`project(expression) job ${t} failed: ${i.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(expression) job ${t} submitted. Poll with jobs(action=status, job_id="${t}"), retrieve with results(action=get, job_id="${t}").`}]}}if(!o)throw new Error("project(expression) without project_onto_job requires dataset_id");const _={name:g,expression:n};r&&(_.options=r);const h=(await f("POST",`/v1/datasets/${o}/derive`,_)).id,w=await b(h);if("completed"===w.status){const e=(await f("GET",`/v1/results/${h}`)).summary??{};return{content:[{type:"text",text:[`Derived column "${g}" added to dataset ${o}`,`Expression: ${n} | Rows: ${e.n_rows??"?"}`,e.nan_count?`NaN values: ${e.nan_count}`:"",`Min: ${e.min??"?"} | Max: ${e.max??"?"} | Mean: ${e.mean??"?"}`,"Column now available. Use datasets(action=preview) to verify, or include in jobs(action=train_map) via the 'columns' parameter."].filter(Boolean).join("\n")}]}}return"failed"===w.status?{content:[{type:"text",text:`project(expression) job ${h} failed: ${w.error??"unknown error"}`}]}:{content:[{type:"text",text:`project(expression) job ${h} submitted. Poll with jobs(action=status, job_id="${h}").`}]}}),h.tool("account","Manage your Barivia account — check plan/license info, request cloud burst compute, view billing history.\n\n| Action | Use when |\n|--------|----------|\n| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |\n| request_compute | Upgrading to cloud burst (required for large grids or GPU). Leave tier blank to list options. |\n| compute_status | Checking if a burst lease is active and how much time remains |\n| release_compute | Manually terminating an active lease to stop billing |\n| history | Viewing recent compute leases and credit spend |\n| add_funds | Getting instructions to add credits |\n\naction=status: Returns plan tier, compute class (CPU/GPU), usage limits, live queue state, training time estimates, and credit balance.\n  Use BEFORE large jobs to check GPU availability and estimate wait time.\naction=request_compute: Provisions an ephemeral cloud burst EC2 instance. Data is in shared R2 — no re-upload needed. Wait ~3 min after requesting before submitting jobs.\nNOT FOR: Training itself — use jobs(action=train_map). This tool only manages the account and compute lease.",{action:o.enum(["status","request_compute","compute_status","release_compute","history","add_funds"]).describe("status: plan/license/queue info; request_compute: provision burst; compute_status: check active lease; release_compute: stop lease; history: recent compute usage; add_funds: instructions"),tier:o.string().optional().describe("action=request_compute: tier ID (e.g. cpu-8, gpu-t4). Omit to list options."),duration_minutes:o.number().optional().describe("action=request_compute: lease duration in minutes (default: 60)"),limit:o.number().optional().describe("action=history: number of records to return (default: 10)")},async({action:e,tier:t,duration_minutes:o,limit:n})=>{if("status"===e){const e=await f("GET","/v1/system/info"),t=e.plan??{},o=e.backend??{},n=e.status??{},a=e.training_time_estimates_seconds??{},r=e.worker_topology??{},i=t.gpu_enabled??e.gpu_available??!1?o.gpu_model?`GPU (${o.gpu_model}${o.gpu_vram_gb?`, ${o.gpu_vram_gb}GB`:""})`:"GPU":"CPU only",s=e=>-1===e||"-1"===e?"unlimited":String(e??"?"),l=await f("GET","/v1/compute/history?limit=5").catch(()=>null),c=await f("GET","/v1/compute/lease").catch(()=>null),u=[`Plan: ${String(t.tier??"unknown").charAt(0).toUpperCase()}${String(t.tier??"unknown").slice(1)} | Compute: ${i}`,`  Concurrency: ${t.max_concurrent_jobs??"?"} jobs | Datasets: ${s(t.max_datasets)} (${s(t.max_dataset_rows)} rows each)`,`  Monthly Jobs: ${s(t.max_monthly_jobs)} | Grid Size: ${s(t.max_grid_size)} | Features: ${s(t.max_features)}`];l&&u.push(`  Credits: $${(l.credit_balance_cents/100).toFixed(2)} remaining`),o.memory_gb&&u.push(`  Backend Memory: ${o.memory_gb} GB`),c&&c.lease_id&&u.push("",`Active Burst Lease: ${c.tier} | ${Math.round(c.time_remaining_ms/6e4)} min left`);const d=Number(n.running_jobs??e.running_jobs??0),p=Number(n.pending_jobs??e.pending_jobs??0),m=Number(a?.total||0);if(u.push("",`Live Queue: ${d} running | ${p} pending | ~${Math.round((p+1)*m/60)} min wait`),void 0!==r.num_workers&&u.push(`Workers: ${r.num_workers}×${r.threads_per_worker} threads`),Object.keys(a).length>0){u.push("","Training Time Estimates:");for(const[e,t]of Object.entries(a))"formula"!==e&&u.push(`  ${e}: ~${t}s`)}return{content:[{type:"text",text:u.join("\n")}]}}if("request_compute"===e){if(!t)return{content:[{type:"text",text:"Available Compute Tiers:\nCPU Tiers:\n  cpu-8: 16 vCPUs, 32 GB RAM (~$0.20/hr)\n  cpu-16: 32 vCPUs, 64 GB RAM (~$0.20/hr)\n  cpu-24: 48 vCPUs, 96 GB RAM (~$0.28/hr)\n  cpu-32: 64 vCPUs, 128 GB RAM (~$0.42/hr)\n  cpu-48: 96 vCPUs, 192 GB RAM (~$0.49/hr)\nGPU Tiers:\n  gpu-t4: 8 vCPUs, 32 GB, T4 16GB VRAM (~$0.22/hr)\n  gpu-t4x: 16 vCPUs, 64 GB, T4 16GB VRAM (~$0.36/hr)\n  gpu-t4xx: 32 vCPUs, 128 GB, T4 16GB VRAM (~$0.27/hr)\n  gpu-l4: 8 vCPUs, 32 GB, L4 24GB VRAM (~$0.41/hr)\n  gpu-l4x: 16 vCPUs, 64 GB, L4 24GB VRAM (~$0.37/hr)\n  gpu-a10: 8 vCPUs, 32 GB, A10G 24GB VRAM (~$0.51/hr)\n  gpu-a10x: 16 vCPUs, 64 GB, A10G 24GB VRAM (~$0.52/hr)"}]};const e=await f("POST","/v1/compute/lease",{tier:t,duration_minutes:o}),n="postpaid"===e.billing_mode?`Billing: Postpaid (usage logged, billed retrospectively)\nAccrued Balance: $${(e.credit_balance_cents/100).toFixed(2)}`:`Credits Remaining After Reserve: $${(e.credit_balance_cents/100).toFixed(2)}`;return{content:[{type:"text",text:`Compute Lease Requested:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nEstimated Wait: ${e.estimated_wait_minutes} minutes\nEstimated Cost: $${(e.estimated_cost_cents/100).toFixed(2)}\n${n}\n\nIMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.`}]}}if("compute_status"===e){const e=await f("GET","/v1/compute/lease");return"none"!==e.status&&e.lease_id?{content:[{type:"text",text:`Active Compute Lease:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nTier: ${e.tier} (${e.instance_type})\nTime Remaining: ${Math.round(e.time_remaining_ms/6e4)} minutes`}]}:{content:[{type:"text",text:"No active lease -- running on default Primary Server."}]}}if("release_compute"===e){const e=await f("DELETE","/v1/compute/lease"),t="postpaid"===e.billing_mode?`Cost Logged: $${(e.cost_cents/100).toFixed(2)} (postpaid — billed retrospectively)`:`Credits Deducted: $${((e.credits_deducted||e.cost_cents)/100).toFixed(2)}`;return{content:[{type:"text",text:`Compute Released:\nDuration Billed: ${e.duration_minutes} minutes\n${t}\nBalance: $${(e.final_balance_cents/100).toFixed(2)}\n\nRouting reverted to default Primary Server.`}]}}if("history"===e){const e=await f("GET",`/v1/compute/history?limit=${n||10}`),t=e.history.map(e=>`- ${e.started_at} | ${e.tier} | ${e.duration_minutes} min | $${(e.credits_charged/100).toFixed(2)}`).join("\n");return{content:[{type:"text",text:`Credit Balance: $${(e.credit_balance_cents/100).toFixed(2)}\n\nRecent Usage:\n${t}`}]}}return"add_funds"===e?{content:[{type:"text",text:"To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:\nbash scripts/manage-credits.sh add <org_id> <amount_usd>"}]}:{content:[{type:"text",text:`Unknown action: ${e}. Valid: status, request_compute, compute_status, release_compute, history, add_funds.`}]}}),h.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.","","**Core workflow:**","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** — `jobs(action=train_map, dataset_id=...)` with grid size, epochs, model type, and preprocessing options. Use `preset=quick|standard|refined|high_res` for sensible defaults","5. **Monitor** — `get_job_status` to track progress; `get_results` to retrieve figures when complete","6. **Analyze** — `analyze` with various analysis types (see below)","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, `project(action=values)` to overlay new variables","","**Analysis types** (via `analyze`):","- `u_matrix` — cluster boundary distances","- `component_planes` — per-feature heatmaps","- `clusters` — automatic cluster detection and statistics","- `quality_report` — QE, TE, explained variance, trustworthiness, neighborhood preservation","- `hit_histogram` — data density across the map","- `transition_flow` — temporal flow patterns (requires time-ordered data)","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `project(action=expression)` — create computed columns from expressions (ratios, differences, etc.) or project onto the map","- `project(action=values)` — overlay a pre-computed array onto a trained map","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, etc.) can be set at training or changed later via recolor_som.","","**Key tools:** datasets, jobs (train_map/status/list/...), results, analyze, project, inference, account, guide_barsom_workflow, explore_map.","","**Tips:**","- 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")}}]})),h.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling jobs(action=train_map). 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}") first, then call jobs(action=train_map, dataset_id="${e}", ...) with appropriate parameters or preset.`;try{const o=await f("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}}),h.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.\n\n| Action | Use when | Timing |\n|--------|----------|--------|\n| predict | Scoring new/unseen observations against the trained map | 5–120s |\n| enrich | Appending BMU coordinates + cluster_id to the original training CSV | 5–60s |\n| compare | Comparing hit distributions of a second dataset against training (drift, A/B) | 30–120s |\n| report | Get a report manifest (artifact keys + URLs) to build your own report in Quarto/Notebook/script | Immediate |\n\npredict/enrich/compare are async; auto-polls to the action-specific timeout; returns a job_id if still running.\nreport is synchronous: returns a manifest of primitives (figures, cluster_summary, metrics) and presigned URLs so the client composes and renders the report. No fixed PDF template.\nNOT FOR: Retraining or changing the map — all actions treat the trained map as frozen.\nESCALATION: 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.\n\naction=predict: Returns predictions.csv with row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error.\n  High QE = row is far from its nearest prototype = potential anomaly. Accepts dataset_id OR inline rows (≤500).\naction=enrich: Returns enriched.csv — original training CSV + bmu_x, bmu_y, bmu_node_index, cluster_id.\n  Flows into pandas/SQL/BI. Download URL in response, expires 15 min.\naction=compare: Returns density-diff heatmap (positive = B gained, negative = lost).\n  Positive nodes: dataset_b has more density here. Negative: training had more. Near-zero: minimal drift.\naction=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. 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:o.enum(["predict","enrich","compare","report"]).describe("predict: score new data; enrich: annotate training CSV with BMU coords; compare: drift/cohort diff heatmap; report: manifest of primitives for custom report"),job_id:o.string().describe("Job ID of a completed map training job"),dataset_id:o.string().optional().describe("action=predict/compare: Dataset ID. predict=input data to score; compare=dataset B to compare against training."),rows:o.array(o.record(o.string(),o.number())).optional().describe("action=predict: inline rows to score (max 500). Each object maps feature name → value."),colormap:o.string().optional().describe("action=compare: colormap for diff heatmap (default: balance). action=report: n/a."),output_format:o.enum(["png","pdf","svg"]).optional().default("png").describe("action=compare: output format for heatmap (default: png)"),output_dpi:o.number().int().min(1).max(4).optional().default(2).describe("action=compare: DPI scale (default: 2)"),top_n:o.number().int().min(1).max(50).optional().default(10).describe("action=compare: number of top gained/lost nodes to report (default: 10)")},async({action:e,job_id:t,dataset_id:o,rows:n,colormap:a,output_format:r,output_dpi:i,top_n:s})=>{if("predict"===e){if(!o&&!n)throw new Error("inference(predict) requires dataset_id or rows");const e={};o&&(e.dataset_id=o),n&&(e.rows=n);const a=(await f("POST",`/v1/results/${t}/predict`,e)).id,r=await b(a,12e4);if("completed"===r.status){const e=await f("GET",`/v1/results/${a}`),t=e.summary??{},o=e.download_urls??{};return{content:[{type:"text",text:[`Predictions complete — job: ${a}`,`Rows scored: ${t.n_rows??"?"}`,`Mean QE: ${void 0!==t.mean_qe?Number(t.mean_qe).toFixed(4):"N/A"} | Max QE: ${void 0!==t.max_qe?Number(t.max_qe).toFixed(4):"N/A"}`,`Clusters: ${Object.keys(t.cluster_counts??{}).length}`,"Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error)",o["predictions.csv"]?`Download: ${o["predictions.csv"]}`:""].filter(Boolean).join("\n")}]}}return"failed"===r.status?{content:[{type:"text",text:`inference(predict) job ${a} failed: ${r.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(predict) job ${a} submitted. Poll with jobs(action=status, job_id="${a}").`}]}}if("enrich"===e){const e=(await f("POST",`/v1/results/${t}/enrich_dataset`,{})).id,o=await b(e,6e4);if("completed"===o.status){const t=await f("GET",`/v1/results/${e}`),o=t.summary??{},n=t.download_urls??{};return{content:[{type:"text",text:[`Enriched dataset ready — job: ${e}`,`Rows: ${o.n_rows??"?"} | Clusters: ${o.n_clusters??"?"}`,"Appended: bmu_x, bmu_y, bmu_node_index, cluster_id",n["enriched.csv"]?`Download: ${n["enriched.csv"]}`:""].filter(Boolean).join("\n")}]}}return"failed"===o.status?{content:[{type:"text",text:`inference(enrich) job ${e} failed: ${o.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(enrich) job ${e} submitted. Poll with jobs(action=status, job_id="${e}").`}]}}if("compare"===e){if(!o)throw new Error("inference(compare) requires dataset_id (dataset B)");const e={dataset_id:o,output_format:r,output_dpi:i,top_n:s};a&&(e.colormap=a);const n=(await f("POST",`/v1/results/${t}/compare_datasets`,e)).id,l=await b(n,12e4);if("completed"===l.status){const e=(await f("GET",`/v1/results/${n}`)).summary??{},t=e.top_gained_nodes??[],o=e.top_lost_nodes??[],a=e=>`  node ${e.bmu_node_index??"?"} [${(e.coords??[0,0]).map(e=>Number(e).toFixed(1)).join(",")}] Δ=${Number(e.density_diff??0).toFixed(4)}`,i=[{type:"text",text:[`Dataset comparison — job: ${n}`,`Dataset A rows: ${e.n_rows_a??"?"} | Dataset B rows: ${e.n_rows_b??"?"}`,"Top gained (B > A):",...t.slice(0,5).map(a),"Top lost (A > B):",...o.slice(0,5).map(a)].join("\n")}];return await S(i,n,`density_diff.${e.output_format??r??"png"}`),{content:i}}return"failed"===l.status?{content:[{type:"text",text:`inference(compare) job ${n} failed: ${l.error??"unknown error"}`}]}:{content:[{type:"text",text:`inference(compare) job ${n} submitted. Poll with jobs(action=status, job_id="${n}").`}]}}const l=await f("GET",`/v1/results/${t}`),c=(l.summary,l.download_urls??{}),u=l.figure_manifest??[],d=l.cluster_summary;return{content:[{type:"text",text:[`Report manifest — job: ${t}`,`Use these artifacts to build your own report (Quarto, Jupyter, script). URLs expire in ${l.expires_in??900}s.`,"","Figures (figure_manifest → download_urls):",...u.slice(0,12).map(e=>`  ${e.logical_name} → ${e.filename}`),u.length>12?`  ... and ${u.length-12} more`:"","","Key download URLs (use get_result_image or download_urls from results(action=get)):",...Object.keys(c).filter(e=>!e.endsWith(".json")||"cluster_summary.json"===e).slice(0,8).map(e=>`  ${e}: ${c[e]?.slice(0,60)}...`),"",d?.length?`Cluster summary: ${d.length} clusters (in response or GET .../cluster_summary).`:"Cluster summary: not available for this job (train with current worker to get it).","","Metrics: in summary (quantization_error, topographic_error, explained_variance, silhouette, etc.) or GET .../quality-report."].filter(Boolean).join("\n")},{type:"text",text:"Structured manifest (for automation): "+JSON.stringify({job_id:t,figure_manifest:u,has_cluster_summary:!!d?.length,download_url_keys:Object.keys(c)})}]}});const T=new t;h.tool("send_feedback","Send feedback or feature requests to Barivia developers (max 1400 characters, ~190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare some feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.",{feedback:o.string().max(1400).describe("Feedback text (max 1400 characters)")},async({feedback:e})=>_(await f("POST","/v1/feedback",{feedback:e}))),async function(){await h.connect(T)}().catch(console.error);