@barivia/barsom-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,2111 @@
+#!/usr/bin/env node
+/**
+ * @barivia/barsom-mcp
+ *
+ * Thin MCP proxy: implements stdio MCP locally and forwards every tool call
+ * to the Barivia cloud REST API. Users configure BARIVIA_API_KEY and
+ * BARIVIA_API_URL as environment variables.
+ *
+ * Usage (in MCP client config, e.g. Cursor / Claude Desktop):
+ *
+ *   {
+ *     "mcpServers": {
+ *       "analytics-engine": {
+ *         "command": "npx",
+ *         "args": ["-y", "@barivia/barsom-mcp"],
+ *         "env": {
+ *           "BARIVIA_API_KEY": "bv_live_xxxx",
+ *           "BARIVIA_API_URL": "https://api.barivia.se"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import fs from "node:fs/promises";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const API_URL = process.env.BARIVIA_API_URL ??
+    process.env.BARSOM_API_URL ??
+    "https://api.barivia.se";
+const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY ?? "";
+if (!API_KEY) {
+    console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config.");
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "30000", 10);
+const MAX_RETRIES = 2;
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+function isTransientError(err, status) {
+    if (status !== undefined && RETRYABLE_STATUS.has(status))
+        return true;
+    if (err instanceof DOMException && err.name === "AbortError")
+        return true;
+    if (err instanceof TypeError)
+        return true; // network-level fetch failure
+    return false;
+}
+async function fetchWithTimeout(url, init, timeoutMs = FETCH_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function apiCall(method, path, body, extraHeaders) {
+    const url = `${API_URL}${path}`;
+    const contentType = extraHeaders?.["Content-Type"] ?? "application/json";
+    const requestId = Math.random().toString(36).slice(2, 10);
+    const headers = {
+        Authorization: `Bearer ${API_KEY}`,
+        "Content-Type": contentType,
+        "X-Request-ID": requestId,
+        ...extraHeaders,
+    };
+    let serializedBody;
+    if (body !== undefined) {
+        serializedBody =
+            contentType === "application/json" ? JSON.stringify(body) : String(body);
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const resp = await fetchWithTimeout(url, {
+                method,
+                headers,
+                body: serializedBody,
+            });
+            const text = await resp.text();
+            if (!resp.ok) {
+                if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
+                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    continue;
+                }
+                const errBody = (() => { try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return null;
+                } })();
+                const detail = errBody?.error ?? text;
+                const hint = resp.status === 400 ? " Check parameter types and required fields."
+                    : resp.status === 404 ? " The resource may not exist or may have been deleted."
+                        : resp.status === 409 ? " The job may not be in the expected state."
+                            : resp.status === 429 ? " Rate limit exceeded — wait a moment and retry."
+                                : "";
+                throw new Error(`${detail}${hint}`);
+            }
+            return JSON.parse(text);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < MAX_RETRIES && isTransientError(err)) {
+                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+/** Fetch raw bytes from the API (for image downloads). */
+async function apiRawCall(path) {
+    const url = `${API_URL}${path}`;
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const resp = await fetchWithTimeout(url, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${API_KEY}` },
+            });
+            if (!resp.ok) {
+                if (attempt < MAX_RETRIES && isTransientError(null, resp.status)) {
+                    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                    continue;
+                }
+                throw new Error(`API GET ${path} returned ${resp.status}`);
+            }
+            const arrayBuf = await resp.arrayBuffer();
+            return {
+                data: Buffer.from(arrayBuf),
+                contentType: resp.headers.get("content-type") ?? "application/octet-stream",
+            };
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < MAX_RETRIES && isTransientError(err)) {
+                await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+function textResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+async function pollUntilComplete(jobId, maxWaitMs = 30_000, intervalMs = 1000) {
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        const data = (await apiCall("GET", `/v1/jobs/${jobId}`));
+        const status = data.status;
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            return {
+                status,
+                result_ref: data.result_ref,
+                error: data.error,
+            };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return { status: "timeout" };
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "analytics-engine",
+    version: "0.4.0",
+});
+// ---------------------------------------------------------------------------
+// MCP Apps: Register UI resources for interactive dashboards
+// ---------------------------------------------------------------------------
+const BASE_DIR = import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname);
+async function loadViewHtml(viewName) {
+    const candidates = [
+        path.join(BASE_DIR, "views", "src", "views", viewName, "index.html"),
+        path.join(BASE_DIR, "views", viewName, "index.html"),
+        path.join(BASE_DIR, "..", "dist", "views", "src", "views", viewName, "index.html"),
+    ];
+    for (const p of candidates) {
+        try {
+            return await fs.readFile(p, "utf-8");
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+const SOM_EXPLORER_URI = "ui://barsom/som-explorer";
+const DATA_PREVIEW_URI = "ui://barsom/data-preview";
+const TRAINING_MONITOR_URI = "ui://barsom/training-monitor";
+registerAppResource(server, SOM_EXPLORER_URI, SOM_EXPLORER_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+    const html = await loadViewHtml("som-explorer");
+    return {
+        contents: [
+            {
+                uri: SOM_EXPLORER_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: html ?? "<html><body>SOM Explorer view not built yet. Run: npm run build:views</body></html>",
+            },
+        ],
+    };
+});
+registerAppResource(server, DATA_PREVIEW_URI, DATA_PREVIEW_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+    const html = await loadViewHtml("data-preview");
+    return {
+        contents: [{
+                uri: DATA_PREVIEW_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: html ?? "<html><body>Data Preview view not built yet.</body></html>",
+            }],
+    };
+});
+registerAppResource(server, TRAINING_MONITOR_URI, TRAINING_MONITOR_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+    const html = await loadViewHtml("training-monitor");
+    return {
+        contents: [{
+                uri: TRAINING_MONITOR_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: html ?? "<html><body>Training Monitor view not built yet.</body></html>",
+            }],
+    };
+});
+// ---- explore_som (MCP App) ----
+registerAppTool(server, "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: z.string().describe("Job ID of a completed SOM training job"),
+    },
+    _meta: { ui: { resourceUri: SOM_EXPLORER_URI } },
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const summary = (data.summary ?? {});
+    const content = [];
+    content.push({
+        type: "text",
+        text: JSON.stringify({
+            job_id,
+            summary,
+            download_urls: data.download_urls,
+        }),
+    });
+    const imgExt = summary.output_format ?? "png";
+    await tryAttachImage(content, job_id, `combined.${imgExt}`);
+    return { content };
+});
+// ---- upload_dataset ----
+server.tool("upload_dataset", `Upload a CSV dataset for SOM analysis. Returns dataset metadata including ID.
+
+BEST FOR: Tabular data with numeric columns (sensor readings, financial data, process
+measurements, survey results). CSV with header row required.
+NOT FOR: Images, text documents, or pre-trained embeddings.
+
+TIMING: Upload is near-instant for datasets under 100MB.
+
+AFTER uploading, ask the user these questions to guide the analysis:
+1. "What are you trying to discover in this data?" (clustering, anomalies, temporal patterns)
+2. "Are any columns cyclic/periodic?" (hour=24, weekday=7, wind direction=360)
+3. "Are any columns irrelevant or should be excluded?"
+4. "Should any features be weighted more heavily?"
+5. "Do any columns have very skewed distributions?" (suggest transforms)
+
+COMMON MISTAKES:
+- Uploading without previewing first — always use preview_dataset before train_som
+- Including ID columns or row indices — these add noise without meaning
+- Forgetting to check for datetime columns that could provide temporal features
+
+Show the column names from the response so the user can identify features.
+TIP: Use the prepare_training prompt for a structured preprocessing checklist.`, {
+    name: z.string().describe("Human-readable dataset name"),
+    csv_data: z.string().describe("CSV data with header row"),
+}, async ({ name, csv_data }) => {
+    const data = await apiCall("POST", "/v1/datasets", csv_data, {
+        "X-Dataset-Name": name,
+        "Content-Type": "text/csv",
+    });
+    return textResult(data);
+});
+// ---- train_som ----
+server.tool("train_som", `Train a Self-Organizing Map on the dataset. Returns a job_id for polling.
+
+BEST FOR: Exploratory analysis of multivariate numeric data — clustering, regime
+detection, process monitoring, anomaly visualization, dimensionality reduction.
+NOT FOR: Time-series forecasting, classification, or text/image data.
+
+TIMING (8700 samples, CPU):
+- 10x10 grid, 10 epochs: ~30s
+- 20x20 grid, 30 epochs: ~3–5 min
+- 40x40 grid, 60 epochs: ~15–30 min
+GPU cuts these by 3–5x. Check system_info for available resources.
+
+BEFORE calling, ask the user:
+1. Which columns to include? (use 'columns' to restrict — start with 5–10 most relevant)
+2. Any cyclic features? (hour=24, weekday=7, angle=360 → cyclic_features)
+3. Any skewed columns? (suggest transforms: log, sqrt, rank)
+4. Feature weights? (weight > 1 emphasizes, 0 disables)
+5. Quick exploration or refined map?
+   Quick: 10x10, epochs=[10,0] | Standard: 20x20, epochs=[20,10] | Refined: 30x30, epochs=[40,20]
+
+TRAINING PHASES:
+- Ordering: large neighborhoods → global structure. sigma_f controls end-radius (default 1.0).
+- Convergence: small neighborhoods → fine-tuning. Skip with epochs=[N, 0].
+- sigma_f 0.5–0.7 → sharper clusters. sigma_f 1.0–2.0 → smoother transitions.
+
+TRANSFORMS: Per-column preprocessing before normalization.
+  transforms: {revenue: "log", volume: "log1p", pressure: "sqrt"}
+  Suggest when preview_dataset shows large value ranges or right-skewed distributions.
+
+TEMPORAL FEATURES: NEVER auto-apply. Always ask which components to extract.
+  temporal_features: [{columns: ['Date'], format: 'dd.mm.yyyy', extract: ['day_of_year'], cyclic: true}]
+
+MODEL TYPES: SOM (default), SOM-SOFT (uncertainty), RSOM (time-series), RSOM-SOFT (both).
+
+COMMON MISTAKES:
+- Too many features without column selection dilutes the map. Start with 5–10.
+- Forgetting cyclic encoding for periodic variables (hours, angles) causes topology artifacts.
+- Grid too small for the data → high QE. Grid too large → sparse nodes. Use sqrt(5*sqrt(N)).
+- Not log-transforming skewed columns → a few outliers dominate the normalization.
+- Using default batch_size for quality-sensitive work: set batch_size=32–64 for sharper maps.
+- Skipping convergence phase: ordering alone gives rough structure; convergence refines it.
+- Not checking get_training_log: if QE is still dropping, add more epochs.
+
+QUALITY TARGETS: QE < 1.5 good, TE < 0.05 good, explained variance > 0.8 good.
+If QE > 2 → more epochs or larger grid. If TE > 0.15 → larger grid or periodic=true.
+
+OUTPUT: format (png/pdf/svg), dpi (standard/retina/print), colormap (viridis/plasma/inferno).
+
+After training, use get_results → analyze(clusters) → component_planes → feature_correlation.
+See docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.`, {
+    dataset_id: z.string().describe("Dataset ID from upload_dataset"),
+    preset: z
+        .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, [10,0], batch=64. " +
+        "standard: 25×25, [20,10], batch=64, best with GPU. " +
+        "refined: 40×40, [40,20], batch=32, best with GPU. " +
+        "high_res: 60×60, [50,30], batch=32, best with GPU."),
+    grid_x: z
+        .number()
+        .int()
+        .optional()
+        .describe("Grid width (omit for auto from data size)"),
+    grid_y: z
+        .number()
+        .int()
+        .optional()
+        .describe("Grid height (omit for auto from data size)"),
+    epochs: z
+        .union([z.number().int(), z.array(z.number().int()).length(2)])
+        .optional()
+        .describe("Epochs: integer or [ordering, convergence]. Set convergence=0 to skip phase 2 (e.g. [15, 0])."),
+    model: z
+        .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: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Use periodic (toroidal) boundaries"),
+    columns: z
+        .array(z.string())
+        .optional()
+        .describe("Subset of CSV column names to train on. Omit to use all columns. Useful to exclude irrelevant features."),
+    cyclic_features: z
+        .array(z.object({
+        feature: z.string().describe("Column name (e.g., 'weekday')"),
+        period: z
+            .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: z
+        .array(z.object({
+        columns: z
+            .array(z.string())
+            .describe("Column name(s) containing datetime strings, combined in order (e.g. ['Date', 'Time'])"),
+        format: z
+            .string()
+            .describe("Julia Dates format string from the whitelist (e.g. 'dd.mm.yyyy HH:MM'). Must match the combined column values."),
+        extract: z
+            .array(z.enum([
+            "hour_of_day",
+            "day_of_year",
+            "month",
+            "day_of_week",
+            "minute_of_hour",
+        ]))
+            .describe("Which temporal components to extract"),
+        cyclic: z
+            .boolean()
+            .default(true)
+            .describe("Encode extracted components as cyclic sin/cos pairs (default true)"),
+        separator: z
+            .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: z
+        .record(z.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."),
+    transforms: z
+        .record(z.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: z
+        .union([z.enum(["all", "auto"]), z.array(z.string())])
+        .optional()
+        .default("auto")
+        .describe("Normalization mode. 'auto' skips already-cyclic features."),
+    sigma_f: z
+        .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: z
+        .union([
+        z.number(),
+        z.object({
+            ordering: z.tuple([z.number(), z.number()]),
+            convergence: z.tuple([z.number(), z.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: z
+        .number()
+        .int()
+        .optional()
+        .describe("Training batch size (default: auto ≈ n_samples/10, max 256). Smaller batches (e.g. 32–64) often sharpen features and can improve map quality (QE, explained variance) at the cost of more steps per epoch. Larger batches = faster epochs but coarser updates; try 64–256 for large datasets (>10k samples)."),
+    backend: z
+        .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: z
+        .enum(["png", "pdf", "svg"])
+        .optional()
+        .default("png")
+        .describe("Image output format. PNG for quick viewing (default), PDF for publication-quality vector graphics, SVG for web embedding."),
+    output_dpi: z
+        .enum(["standard", "retina", "print"])
+        .optional()
+        .default("retina")
+        .describe("Resolution for PNG output: standard (1x), retina (2x, default), print (4x). Ignored for PDF/SVG."),
+    colormap: z
+        .string()
+        .optional()
+        .describe("Override default colormap for component planes (e.g. viridis, plasma, inferno, coolwarm). U-matrix always uses grays, cyclic features use twilight."),
+}, async ({ dataset_id, preset, grid_x, grid_y, epochs, model, periodic, columns, transforms, cyclic_features, temporal_features, feature_weights, normalize, sigma_f, learning_rate, batch_size, backend, output_format, output_dpi, colormap, }) => {
+    const PRESETS = {
+        quick: { grid: [15, 15], epochs: [10, 0], batch_size: 64 },
+        standard: { grid: [25, 25], epochs: [20, 10], batch_size: 64, backend: "cuda" },
+        refined: { grid: [40, 40], epochs: [40, 20], batch_size: 32, backend: "cuda" },
+        high_res: { grid: [60, 60], epochs: [50, 30], batch_size: 32, backend: "cuda" },
+    };
+    const p = preset ? PRESETS[preset] : undefined;
+    const params = {
+        model,
+        periodic,
+        normalize,
+    };
+    if (grid_x !== undefined && grid_y !== undefined) {
+        params.grid = [grid_x, grid_y];
+    }
+    else if (p) {
+        params.grid = p.grid;
+    }
+    if (epochs !== undefined) {
+        params.epochs = epochs;
+    }
+    else if (p) {
+        params.epochs = p.epochs;
+    }
+    if (cyclic_features && cyclic_features.length > 0) {
+        params.cyclic_features = cyclic_features;
+    }
+    if (columns && columns.length > 0) {
+        params.columns = columns;
+    }
+    if (transforms && Object.keys(transforms).length > 0) {
+        params.transforms = transforms;
+    }
+    if (temporal_features && temporal_features.length > 0) {
+        params.temporal_features = temporal_features;
+    }
+    if (feature_weights && Object.keys(feature_weights).length > 0) {
+        params.feature_weights = feature_weights;
+    }
+    if (sigma_f !== undefined) {
+        params.sigma_f = sigma_f;
+    }
+    if (learning_rate !== undefined) {
+        params.learning_rate = learning_rate;
+    }
+    if (batch_size !== undefined) {
+        params.batch_size = batch_size;
+    }
+    else if (p) {
+        params.batch_size = p.batch_size;
+    }
+    if (backend !== undefined && backend !== "auto") {
+        params.backend = backend;
+    }
+    else if (p?.backend) {
+        params.backend = p.backend;
+    }
+    if (output_format && output_format !== "png") {
+        params.output_format = output_format;
+    }
+    const dpiMap = { standard: 1, retina: 2, print: 4 };
+    if (output_dpi && output_dpi !== "retina") {
+        params.output_dpi = dpiMap[output_dpi] ?? 2;
+    }
+    if (colormap) {
+        params.colormap = colormap;
+    }
+    const data = await apiCall("POST", "/v1/jobs", { dataset_id, params });
+    return textResult(data);
+});
+// ---- get_job_status ----
+server.tool("get_job_status", `Check status and progress of a training or analysis job.
+
+TIMING: Poll every 3–5s for small jobs, every 10–15s for large grids.
+Typical completion times (CPU, 8700 samples):
+  10x10, 10 epochs: ~30s | 20x20, 30 epochs: ~3–5 min | 40x40, 60 epochs: ~15–30 min
+
+When status is 'completed', call get_results to retrieve the map and metrics.
+When status is 'failed', show the error to the user and suggest parameter adjustments.`, {
+    job_id: z.string().describe("Job ID from train_som"),
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/jobs/${job_id}`));
+    const status = data.status;
+    const progress = (data.progress ?? 0) * 100;
+    let text = `Job ${job_id}: ${status} (${progress.toFixed(1)}%)`;
+    if (status === "completed") {
+        text += ` | Results ready. Use get_results(job_id="${job_id}") to retrieve.`;
+    }
+    else if (status === "failed") {
+        text += ` | Error: ${data.error ?? "unknown"}`;
+    }
+    return { content: [{ type: "text", text }] };
+});
+// ---- get_results ----
+server.tool("get_results", `Retrieve results of a completed SOM training, projection, or derived variable job.
+
+BEST FOR: Getting the first look at a trained SOM — combined visualization + quality metrics.
+TIMING: Near-instant (reads pre-computed results from S3).
+
+Returns: text summary with metrics, inline combined visualization, and resource download links.
+
+OPTIONS:
+- include_individual=true: shows each component plane, U-matrix, and hit histogram
+  as separate inline images. Best for side-by-side feature comparison.
+
+AFTER showing results, guide the user:
+1. "The U-matrix shows [N] distinct regions. Does this match expected groupings?"
+2. "QE=X, TE=Y — [assessment]. Would you like to retrain with different params?"
+3. "Which features show interesting patterns in the component planes?"
+4. If QE > 2: suggest more epochs or larger grid
+5. If TE > 0.15: suggest larger grid
+6. If explained variance < 0.7: suggest transforms, feature selection, or more training
+
+WORKFLOW: get_results → analyze(clusters) → component_planes → feature_correlation.
+Use get_training_log() for the learning curve (QE vs epoch — healthy=steady decline then plateau).
+Use quality_report() for extended metrics (trustworthiness, neighborhood preservation).
+
+METRIC INTERPRETATION:
+- QE < 1.5: good fit. QE > 2: consider more epochs, larger grid, or batch_size=32.
+- TE < 0.05: good topology. TE > 0.15: grid too small.
+- Explained variance > 0.8: good. < 0.7: try transforms, fewer features, or more training.`, {
+    job_id: z.string().describe("Job ID of a completed job"),
+    include_individual: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, inline each individual plot (component planes, u-matrix, hit histogram) separately instead of just the combined view. Useful for side-by-side feature comparison or publication-quality individual figures."),
+}, async ({ job_id, include_individual }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const summary = (data.summary ?? {});
+    const downloadUrls = (data.download_urls ?? {});
+    const content = [];
+    const jobType = summary.job_type ?? "train_som";
+    // ── Dispatch by job type ──────────────────────────────────────────────────
+    const fmtExt = summary.output_format ?? "png";
+    if (jobType === "transition_flow") {
+        const lag = summary.lag ?? 1;
+        const flowImg = `transition_flow_lag${lag}.${fmtExt}`;
+        const stats = summary.flow_stats ?? {};
+        content.push({
+            type: "text",
+            text: [
+                `Transition Flow Results (job: ${job_id})`,
+                `Parent SOM: ${summary.parent_job_id ?? "N/A"} | Lag: ${lag} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Flow Statistics:`,
+                `  Mean flow magnitude: ${stats.mean_magnitude !== undefined ? Number(stats.mean_magnitude).toFixed(4) : "N/A"}`,
+                `  Max flow magnitude:  ${stats.max_magnitude !== undefined ? Number(stats.max_magnitude).toFixed(4) : "N/A"}`,
+                `  Nodes with flow:     ${stats.n_nodes_with_flow ?? "N/A"}`,
+                ``,
+                `Arrows show net directional drift between consecutive BMU assignments.`,
+                `Long/bright arrows = frequent state transitions. Short arrows = stable states.`,
+                `Background = U-matrix (cluster boundaries). Arrows in dark regions = intra-cluster.`,
+                ``,
+                `Use transition_flow(lag=N) with larger N to reveal longer-term temporal structure.`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, flowImg);
+    }
+    else if (jobType === "project_variable") {
+        const varName = summary.variable_name ?? "variable";
+        const agg = summary.aggregation ?? "mean";
+        const stats = summary.variable_stats ?? {};
+        const projImg = `projected_${varName}.${fmtExt}`;
+        content.push({
+            type: "text",
+            text: [
+                `Projected Variable: ${varName} (${agg}) — job: ${job_id}`,
+                `Parent SOM: ${summary.parent_job_id ?? "N/A"} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Variable Statistics (per-node ${agg}):`,
+                `  Min:            ${stats.min !== undefined ? Number(stats.min).toFixed(3) : "N/A"}`,
+                `  Max:            ${stats.max !== undefined ? Number(stats.max).toFixed(3) : "N/A"}`,
+                `  Mean:           ${stats.mean !== undefined ? Number(stats.mean).toFixed(3) : "N/A"}`,
+                `  Nodes with data: ${stats.n_nodes_with_data ?? "N/A"} / ${(Number(stats.n_nodes_with_data ?? 0) + Number(stats.n_nodes_empty ?? 0))}`,
+                ``,
+                `Non-random spatial patterns indicate the variable correlates with the SOM's`,
+                `learned feature space, even if it wasn't used in training.`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, projImg);
+    }
+    else {
+        // ── Default: train_som results ──────────────────────────────────────────
+        const grid = summary.grid ?? [0, 0];
+        const features = summary.features ?? [];
+        const epochs = summary.epochs;
+        const epochStr = Array.isArray(epochs)
+            ? epochs[1] === 0
+                ? `${epochs[0]} ordering only`
+                : `${epochs[0]} ordering + ${epochs[1]} convergence`
+            : String(epochs ?? "N/A");
+        const fmt = (v) => v !== null && v !== undefined ? Number(v).toFixed(4) : "N/A";
+        const duration = summary.training_duration_seconds;
+        const ordErrors = summary.ordering_errors;
+        const textSummary = [
+            `SOM Training Results (job: ${job_id})`,
+            `Grid: ${grid[0]}×${grid[1]} | Features: ${summary.n_features ?? 0} | Samples: ${summary.n_samples ?? 0}`,
+            `Model: ${summary.model ?? "SOM"} | Epochs: ${epochStr}`,
+            `Periodic: ${summary.periodic ?? true} | Normalize: ${summary.normalize ?? "auto"}`,
+            summary.sigma_f !== undefined ? `Sigma_f: ${summary.sigma_f}` : "",
+            duration !== undefined ? `Training duration: ${duration}s` : "",
+            ``,
+            `Quality Metrics:`,
+            `  Quantization Error: ${fmt(summary.quantization_error)}  (lower is better)`,
+            `  Topographic Error:  ${fmt(summary.topographic_error)}   (lower is better, <0.1 is good)`,
+            `  Explained Variance: ${fmt(summary.explained_variance)}  (higher is better, >0.7 is good)`,
+            `  Silhouette Score:   ${fmt(summary.silhouette)}          (higher is better, [-1, 1])`,
+            `  Davies-Bouldin:     ${fmt(summary.davies_bouldin)}      (lower is better)`,
+            `  Calinski-Harabasz:  ${fmt(summary.calinski_harabasz)}   (higher is better)`,
+            ordErrors && ordErrors.length > 0
+                ? `  Final ordering QE: ${ordErrors.at(-1)?.toFixed(4)} (use get_training_log for full curve)`
+                : "",
+            ``,
+            `Features: ${features.join(", ")}`,
+            summary.selected_columns
+                ? `Selected columns: ${summary.selected_columns.join(", ")}`
+                : "",
+            summary.transforms
+                ? `Transforms: ${Object.entries(summary.transforms).map(([k, v]) => `${k}=${v}`).join(", ")}`
+                : "",
+            ``,
+            `Use analyze() for deeper insights, quality_report() for extended metrics, get_training_log() for learning curves.`,
+        ]
+            .filter((l) => l !== "")
+            .join("\n");
+        content.push({ type: "text", text: textSummary });
+        const imgExt = summary.output_format ?? "png";
+        await tryAttachImage(content, job_id, `combined.${imgExt}`);
+        if (include_individual) {
+            const feats = summary.features ?? [];
+            const imageNames = [
+                `umatrix.${imgExt}`,
+                `hit_histogram.${imgExt}`,
+                ...feats.map((f, i) => `component_${i + 1}_${f.replace(/[^a-zA-Z0-9_]/g, "_")}.${imgExt}`),
+            ];
+            const results = await Promise.allSettled(imageNames.map((name) => apiRawCall(`/v1/results/${job_id}/image/${name}`).then((r) => ({ name, ...r }))));
+            for (const r of results) {
+                if (r.status === "fulfilled") {
+                    content.push({
+                        type: "image",
+                        data: r.value.data.toString("base64"),
+                        mimeType: mimeForFilename(r.value.name),
+                        annotations: { audience: ["user"], priority: 0.8 },
+                    });
+                }
+            }
+        }
+    }
+    // Resource links for all files
+    const files = summary.files ?? [];
+    for (const fname of files) {
+        const url = downloadUrls[fname] ??
+            `${API_URL}/v1/results/${job_id}/image/${fname}`;
+        const mimeType = fname.endsWith(".json")
+            ? "application/json"
+            : fname.endsWith(".pdf")
+                ? "application/pdf"
+                : fname.endsWith(".svg")
+                    ? "image/svg+xml"
+                    : "image/png";
+        content.push({
+            type: "resource_link",
+            uri: url,
+            name: fname,
+            mimeType,
+        });
+    }
+    return { content };
+});
+// ---- analyze ----
+server.tool("analyze", `Run a specific analysis on SOM results. Use after get_results to drill into aspects.
+
+Available analysis types and when to use them:
+
+  u_matrix          — Cluster boundary map. Ask: "Do boundary regions match expected
+                      groupings? How many clusters do you see?"
+  component_planes  — Per-feature distributions. Ask: "Which features show similar
+                      spatial patterns? Those are correlated in your data."
+  bmu_hits          — Data density per node. Ask: "Are there dense hot-spots?
+                      Sparse regions may be interpolated or rare states."
+  clusters          — Quality assessment with recommendations. Always run this after
+                      get_results to decide whether to retrain.
+  feature_importance — Rank features by SOM contribution (component plane variance).
+                      Ask: "Does this ranking match your domain knowledge?"
+  feature_correlation — Compare all component planes side-by-side for correlation.
+                        Ask: "Which pairs of features move together? Are any redundant?"
+  transition_flow   — Temporal BMU transition patterns (best for time-series data).
+                      Ask: "Do you see cyclic or directional patterns in the transitions?"
+  local_density     — Identify cluster cores vs boundaries. Ask: "Where are the
+                      high-density regions? Do they correspond to known operating modes?"
+  feature_gradient  — Spatial rate of change per feature. Ask: "Where does this
+                      feature change most rapidly? Does it align with cluster boundaries?"
+
+WORKFLOW RECOMMENDATION:
+1. Start with clusters → check quality metrics and recommendations
+2. Then u_matrix → identify cluster boundaries (dark=cores, bright=boundaries)
+3. Then component_planes or feature_importance → understand feature roles
+   (similar spatial patterns in component planes = correlated features)
+4. Then feature_correlation → find redundant or linked features
+5. For time-series: add transition_flow and local_density
+
+INTERPRETATION TIPS:
+- U-matrix: count dark "basins" to estimate cluster count; bright bands are boundaries.
+- Component planes: compare side-by-side; similar patterns mean correlated features.
+- BMU hits: empty nodes suggest oversized grid or data gaps.
+- If quality is low, retrain with: larger grid, more epochs, smaller batch_size, or transforms.`, {
+    job_id: z.string().describe("Job ID of a completed job"),
+    analysis_type: z
+        .enum([
+        "u_matrix",
+        "component_planes",
+        "bmu_hits",
+        "clusters",
+        "feature_importance",
+        "feature_correlation",
+        "transition_flow",
+        "local_density",
+        "feature_gradient",
+    ])
+        .describe("Type of analysis to run"),
+    params: z
+        .record(z.unknown())
+        .optional()
+        .describe("Analysis-specific parameters. For component_planes/feature_gradient: {features: [col,...]} to restrict to specific columns."),
+}, async ({ job_id, analysis_type, params: extraParams }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}`));
+    const summary = (data.summary ?? {});
+    const features = summary.features ?? [];
+    const grid = summary.grid ?? [0, 0];
+    const ext = summary.output_format ?? "png";
+    const content = [];
+    if (analysis_type === "u_matrix") {
+        content.push({
+            type: "text",
+            text: [
+                `U-Matrix Analysis (job: ${job_id})`,
+                `Grid: ${grid[0]}×${grid[1]}`,
+                ``,
+                `The U-matrix shows average distances between neighboring nodes.`,
+                `  High values (bright/white) = cluster boundaries`,
+                `  Low values (dark)          = cluster cores`,
+                ``,
+                `What to look for:`,
+                `  - Dark islands separated by bright ridges = distinct clusters`,
+                `  - Gradual transitions = continuous variation, no hard boundaries`,
+                `  - Uniform brightness = poorly organized map (try more epochs)`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, `umatrix.${ext}`);
+    }
+    else if (analysis_type === "component_planes") {
+        const requested = extraParams?.features ?? features;
+        content.push({
+            type: "text",
+            text: [
+                `Component Planes (job: ${job_id})`,
+                `Features: ${requested.join(", ")}`,
+                ``,
+                `Each panel shows one feature's distribution across the SOM.`,
+                `  Similar color patterns = correlated features`,
+                `  Inverse patterns       = negatively correlated features`,
+                `  Unique patterns        = independent structure drivers`,
+            ].join("\n"),
+        });
+        for (let i = 0; i < features.length; i++) {
+            if (!requested.includes(features[i]))
+                continue;
+            const safeName = features[i].replace(/[^a-zA-Z0-9_]/g, "_");
+            await tryAttachImage(content, job_id, `component_${i + 1}_${safeName}.${ext}`);
+        }
+    }
+    else if (analysis_type === "bmu_hits") {
+        content.push({
+            type: "text",
+            text: [
+                `BMU Hit Histogram (job: ${job_id})`,
+                `Grid: ${grid[0]}×${grid[1]} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Shows data density per SOM node.`,
+                `  Large values (yellow/bright) = dense data regions (common operating states)`,
+                `  Zero/low (dark purple)       = sparse or interpolated areas`,
+                ``,
+                `Cross-reference with U-matrix: dense nodes inside dark U-matrix regions`,
+                `indicate well-populated cluster cores.`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, `hit_histogram.${ext}`);
+    }
+    else if (analysis_type === "clusters") {
+        const qe = summary.quantization_error;
+        const te = summary.topographic_error;
+        const ev = summary.explained_variance;
+        const sil = summary.silhouette;
+        const qeLabel = qe === undefined ? "N/A" :
+            qe < 0.5 ? "excellent" :
+                qe < 1.0 ? "good" :
+                    qe < 2.0 ? "fair" : "poor";
+        const teLabel = te === undefined ? "N/A" :
+            te < 0.05 ? "excellent" :
+                te < 0.10 ? "good" :
+                    te < 0.20 ? "fair" : "poor";
+        const fmt = (v) => v !== undefined ? v.toFixed(4) : "N/A";
+        const recommendations = [];
+        if (te !== undefined && te > 0.15) {
+            recommendations.push(`Topographic error ${(te * 100).toFixed(1)}% is high — try a larger grid or more epochs.`);
+        }
+        if (qe !== undefined && qe > 2.0) {
+            recommendations.push(`Quantization error ${qe.toFixed(3)} is high — try more epochs, a larger grid, or check for outliers.`);
+        }
+        if (ev !== undefined && ev < 0.7) {
+            recommendations.push(`Explained variance ${(ev * 100).toFixed(1)}% is low — try more epochs, a larger grid, or feature weighting.`);
+        }
+        if (sil !== undefined && sil < 0.1) {
+            recommendations.push(`Low silhouette score — clusters overlap. Try sigma_f=0.5 or more training.`);
+        }
+        if (recommendations.length === 0) {
+            recommendations.push(`Metrics look healthy. Proceed with component plane and feature analysis.`);
+        }
+        const gridStr = grid[0] > 0 ? `${grid[0]}×${grid[1]}` : "N/A";
+        content.push({
+            type: "text",
+            text: [
+                `Cluster Quality Assessment (job: ${job_id})`,
+                `Grid: ${gridStr} | Features: ${features.length} | Samples: ${summary.n_samples ?? "N/A"}`,
+                ``,
+                `Quantization Error:  ${fmt(qe)}  (${qeLabel})`,
+                `Topographic Error:   ${fmt(te)}  (${teLabel})`,
+                `Explained Variance:  ${fmt(ev)}`,
+                `Silhouette Score:    ${fmt(sil)}`,
+                `Davies-Bouldin:      ${fmt(summary.davies_bouldin)}`,
+                `Calinski-Harabasz:   ${fmt(summary.calinski_harabasz)}`,
+                ``,
+                `Recommendations:`,
+                ...recommendations.map((r) => `  - ${r}`),
+            ].join("\n"),
+        });
+    }
+    else if (analysis_type === "feature_importance") {
+        content.push({
+            type: "text",
+            text: [
+                `Feature Importance Analysis (job: ${job_id})`,
+                `Grid: ${grid[0]}×${grid[1]} | Features: ${features.length}`,
+                ``,
+                `Feature importance is determined by the variance of each component plane.`,
+                `Higher variance = feature contributes more to the SOM structure.`,
+                ``,
+                `Features analyzed: ${features.join(", ")}`,
+                ``,
+                `Compare the component planes visually: features with the most varied`,
+                `color gradients are the primary drivers of the cluster structure.`,
+                `Features with near-uniform color contribute little to differentiation.`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, `combined.${ext}`);
+    }
+    else if (analysis_type === "feature_correlation") {
+        content.push({
+            type: "text",
+            text: [
+                `Feature Correlation Analysis (job: ${job_id})`,
+                `Features: ${features.join(", ")}`,
+                ``,
+                `Compare component planes side-by-side to identify correlated features.`,
+                `  Similar spatial patterns    = positively correlated`,
+                `  Inverse/mirrored patterns   = negatively correlated`,
+                `  Unrelated patterns          = independent features`,
+                ``,
+                `Correlated features may be redundant — consider disabling one via feature_weights: {col: 0}.`,
+            ].join("\n"),
+        });
+        for (let i = 0; i < features.length; i++) {
+            const safeName = features[i].replace(/[^a-zA-Z0-9_]/g, "_");
+            await tryAttachImage(content, job_id, `component_${i + 1}_${safeName}.${ext}`);
+        }
+    }
+    else if (analysis_type === "transition_flow") {
+        content.push({
+            type: "text",
+            text: [
+                `Transition Flow Analysis (job: ${job_id})`,
+                `Grid: ${grid[0]}×${grid[1]} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Transition flow shows how data points move between SOM nodes in sequence.`,
+                `This reveals temporal patterns and state machine behavior.`,
+                ``,
+                `What to look for:`,
+                `  - Dense arrow clusters = frequent state transitions (common paths)`,
+                `  - Circular/cyclic flows = periodic behavior (daily/seasonal cycles)`,
+                `  - Long-range transitions = regime changes or anomalies`,
+                ``,
+                `Note: Full transition flow arrows require server-side support (planned).`,
+                `Currently showing U-matrix for cluster boundary context.`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, `umatrix.${ext}`);
+    }
+    else if (analysis_type === "local_density") {
+        content.push({
+            type: "text",
+            text: [
+                `Local Density & Cluster Analysis (job: ${job_id})`,
+                `Grid: ${grid[0]}×${grid[1]} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Local density = inverse of U-matrix values.`,
+                `  High density (low U-matrix) = cluster cores (similar neighbors)`,
+                `  Low density (high U-matrix) = cluster boundaries (dissimilar neighbors)`,
+                ``,
+                `Cross-reference hit histogram with U-matrix:`,
+                `  Dense hits + low U-matrix = populated cluster core (dominant operating mode)`,
+                `  Dense hits + high U-matrix = transition zone with many samples (worth investigating)`,
+                `  Sparse hits anywhere = rare state or interpolated region`,
+            ].join("\n"),
+        });
+        await tryAttachImage(content, job_id, `umatrix.${ext}`);
+        await tryAttachImage(content, job_id, `hit_histogram.${ext}`);
+    }
+    else if (analysis_type === "feature_gradient") {
+        const targetFeature = extraParams?.feature;
+        content.push({
+            type: "text",
+            text: [
+                `Feature Gradient Analysis (job: ${job_id})`,
+                `Target: ${targetFeature ?? "all features"}`,
+                `Grid: ${grid[0]}×${grid[1]}`,
+                ``,
+                `Feature gradients show where each feature changes most rapidly on the SOM.`,
+                `  High gradient = feature transitions rapidly (boundary region for this feature)`,
+                `  Low gradient  = feature is stable across this region`,
+                ``,
+                `Compare with U-matrix: if feature gradients align with U-matrix boundaries,`,
+                `this feature is a key driver of the cluster separation.`,
+            ].join("\n"),
+        });
+        if (targetFeature) {
+            const idx = features.indexOf(targetFeature);
+            if (idx >= 0) {
+                const safeName = targetFeature.replace(/[^a-zA-Z0-9_]/g, "_");
+                await tryAttachImage(content, job_id, `component_${idx + 1}_${safeName}.${ext}`);
+            }
+        }
+        else {
+            await tryAttachImage(content, job_id, `combined.${ext}`);
+        }
+        await tryAttachImage(content, job_id, `umatrix.${ext}`);
+    }
+    return { content };
+});
+// ---- compare_runs ----
+server.tool("compare_runs", `Compare metrics across multiple completed SOM training jobs.
+Returns a table of QE, TE, silhouette, and other metrics for each job.
+
+Use to evaluate hyperparameter choices: grid size, epochs, sigma_f, model type, feature selection.
+
+After comparing, ask the user:
+"Which job produced the best metrics for your goal?"
+- For visualization clarity: prioritize low topographic error (<0.1)
+- For tight clusters: prioritize low QE and high silhouette
+- For dimensionality reduction: prioritize high explained variance (>0.8)`, {
+    job_ids: z
+        .array(z.string())
+        .min(2)
+        .describe("Array of job IDs to compare (minimum 2)"),
+}, async ({ job_ids }) => {
+    const ids = job_ids.join(",");
+    const data = (await apiCall("GET", `/v1/jobs/compare?ids=${ids}`));
+    const comparisons = (data.comparisons ?? []);
+    const lines = [
+        "| Job ID | Grid | Epochs | Model | QE | TE | Expl.Var | Silhouette |",
+        "|--------|------|--------|-------|----|----|----------|------------|",
+    ];
+    for (const c of comparisons) {
+        if (c.error) {
+            lines.push(`| ${c.job_id.slice(0, 8)}... | — | — | — | ${c.error} | — | — | — |`);
+            continue;
+        }
+        const g = c.grid;
+        const gridStr = g ? `${g[0]}×${g[1]}` : "—";
+        const ep = c.epochs;
+        const epStr = ep
+            ? ep[1] === 0
+                ? `${ep[0]}+0`
+                : `${ep[0]}+${ep[1]}`
+            : "—";
+        const model = c.model ?? "—";
+        const fmt = (v) => v !== null && v !== undefined ? Number(v).toFixed(4) : "—";
+        lines.push(`| ${c.job_id.slice(0, 8)}... | ${gridStr} | ${epStr} | ${model} | ${fmt(c.quantization_error)} | ${fmt(c.topographic_error)} | ${fmt(c.explained_variance)} | ${fmt(c.silhouette)} |`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// ---- cancel_job ----
+server.tool("cancel_job", `Cancel a pending or running job.
+
+TIMING: Cancellation is not instant — the worker checks between training phases.
+Expect up to 30s delay for the job to actually stop.
+
+Use when a training run is too slow, wrong parameters were submitted, or you
+want to free the worker for a different job. Partial results are discarded.
+After cancelling, submit a new job with corrected parameters.`, {
+    job_id: z.string().describe("Job ID to cancel"),
+}, async ({ job_id }) => {
+    const data = await apiCall("POST", `/v1/jobs/${job_id}/cancel`);
+    return textResult(data);
+});
+// ---- delete_job ----
+server.tool("delete_job", `Delete a job and all its S3 result files.
+
+Use when:
+- Cleaning up old or failed jobs to free storage
+- Removing test runs before going to production
+- The job is cancelled and you no longer need the record
+
+WARNING: This permanently deletes all result files (images, weights, node stats).
+The job ID will no longer be usable with get_results or any other tools.`, {
+    job_id: z.string().describe("Job ID to delete"),
+}, async ({ job_id }) => {
+    const data = await apiCall("DELETE", `/v1/jobs/${job_id}`);
+    return textResult(data);
+});
+// ---- preview_dataset ----
+server.tool("preview_dataset", `Preview a dataset before training — shows columns, statistics, sample rows, and detections.
+
+BEST FOR: Understanding data structure before training. ALWAYS call this before train_som
+on an unfamiliar dataset.
+NOT FOR: Large data exploration (returns only sample rows). Use derive_variable for computations.
+
+TIMING: Near-instant (reads only header + sample rows from S3).
+
+This tool detects:
+1. Column types (numeric vs string) and basic stats (min/max/mean/std)
+2. Cyclic feature candidates (columns named hour, weekday, angle, direction, etc.)
+3. Datetime columns with format auto-detection
+4. Skewed distributions (large max/min ratios suggest log transforms)
+
+AFTER previewing, ask the user:
+- "Which columns are relevant?" → columns parameter in train_som
+- "I see cyclic candidates: [list]. Encode cyclically?" → cyclic_features
+- "Column X ranges 0.01–50,000. Log-transform?" → transforms: {X: "log"}
+- "Datetime columns found. Extract temporal features?" → temporal_features (NEVER auto-apply)
+- "Are any features more important than others?" → feature_weights
+
+COMMON MISTAKES:
+- Skipping preview and training on all columns (including IDs, timestamps, irrelevant features)
+- Not checking for datetime columns that could provide valuable cyclic features
+- Ignoring skewed distributions that will dominate normalization
+
+TIP: Use the prepare_training prompt for a structured walkthrough of all decisions.`, {
+    dataset_id: z.string().describe("Dataset ID to preview"),
+    n_rows: z
+        .number()
+        .int()
+        .optional()
+        .default(5)
+        .describe("Number of sample rows to return (default 5)"),
+}, async ({ dataset_id, n_rows }) => {
+    const data = (await apiCall("GET", `/v1/datasets/${dataset_id}/preview?n_rows=${n_rows ?? 5}`));
+    const cols = data.columns ?? [];
+    const stats = data.column_stats ?? [];
+    const hints = data.cyclic_hints ?? [];
+    const samples = data.sample_rows ?? [];
+    const dtCols = data.datetime_columns ?? [];
+    const temporalSugg = data.temporal_suggestions ?? [];
+    const fmt = (v) => v === null || v === undefined ? "—" : Number(v).toFixed(3);
+    const lines = [
+        `Dataset: ${data.name} (${data.dataset_id})`,
+        `${data.total_rows} rows × ${data.total_cols} columns`,
+        ``,
+        `Column Statistics:`,
+        `| Column | Min | Max | Mean | Std | Nulls | Numeric |`,
+        `|--------|-----|-----|------|-----|-------|---------|`,
+    ];
+    for (const s of stats) {
+        lines.push(`| ${s.column} | ${fmt(s.min)} | ${fmt(s.max)} | ${fmt(s.mean)} | ${fmt(s.std)} | ${s.null_count ?? 0} | ${s.is_numeric !== false ? "yes" : "no"} |`);
+    }
+    if (hints.length > 0) {
+        lines.push(``, `Detected Cyclic Feature Hints:`);
+        for (const h of hints) {
+            lines.push(`  • ${h.column} — period=${h.period} (${h.reason})`);
+        }
+    }
+    if (dtCols.length > 0) {
+        lines.push(``, `Detected Datetime Columns:`);
+        for (const dc of dtCols) {
+            const formats = dc.detected_formats ?? [];
+            const fmtStrs = formats
+                .map((f) => `${f.format} — ${f.description} (${(f.match_rate * 100).toFixed(0)}% match)`)
+                .join("; ");
+            lines.push(`  • ${dc.column}: sample="${dc.sample}" → ${fmtStrs}`);
+            if (formats.length > 1) {
+                lines.push(`    ⚠ AMBIGUOUS: multiple formats match. Ask user to clarify.`);
+            }
+        }
+    }
+    if (temporalSugg.length > 0) {
+        lines.push(``, `Temporal Feature Suggestions (require user approval):`);
+        for (const ts of temporalSugg) {
+            lines.push(`  • Columns: ${ts.columns.join(" + ")} → format: "${ts.format}"`);
+            lines.push(`    Available components: ${ts.available_components.join(", ")}`);
+            lines.push(`    ${ts.note}`);
+        }
+        lines.push(``, `To use temporal features in train_som, add:`, `  temporal_features: [{columns: [...], format: "...", extract: [...], cyclic: true}]`);
+    }
+    if (samples.length > 0) {
+        lines.push(``, `Sample Rows (first ${samples.length}):`);
+        lines.push(`| ${cols.join(" | ")} |`);
+        lines.push(`| ${cols.map(() => "---").join(" | ")} |`);
+        for (const row of samples) {
+            lines.push(`| ${cols.map((c) => String(row[c] ?? "")).join(" | ")} |`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// ---- delete_dataset ----
+server.tool("delete_dataset", "Delete a dataset and its stored data. Frees a dataset slot for new uploads.", {
+    dataset_id: z.string().describe("Dataset ID to delete"),
+}, async ({ dataset_id }) => {
+    const data = await apiCall("DELETE", `/v1/datasets/${dataset_id}`);
+    return textResult(data);
+});
+// ---- list_datasets ----
+server.tool("list_datasets", `List all datasets uploaded by the current organization.
+
+Use this to check what data is available before calling train_som,
+or to find dataset IDs for datasets that were uploaded previously.`, {}, async () => {
+    const data = await apiCall("GET", "/v1/datasets");
+    return textResult(data);
+});
+// ---- list_jobs ----
+server.tool("list_jobs", `List all SOM training jobs, optionally filtered by dataset.
+
+Shows status, params, and metrics for each job. Use this to:
+- Find job IDs for compare_runs
+- Check which jobs are completed vs pending
+- Review what hyperparameters were used in previous runs`, {
+    dataset_id: z
+        .string()
+        .optional()
+        .describe("Filter by dataset ID (omit to list all jobs)"),
+}, async ({ dataset_id }) => {
+    const path = dataset_id
+        ? `/v1/jobs?dataset_id=${dataset_id}`
+        : "/v1/jobs";
+    const data = await apiCall("GET", path);
+    return textResult(data);
+});
+// ---- get_training_log ----
+server.tool("get_training_log", `Retrieve the learning curve and training diagnostics for a completed job.
+
+Returns per-epoch quantization error arrays, ASCII sparklines, AND an inline
+learning curve plot (generated during training) showing QE vs epoch for both
+ordering and convergence phases.
+
+Use this to diagnose training quality:
+
+- **Healthy**: errors drop steadily, then plateau (converged)
+- **Still learning**: errors still dropping at end → try more epochs
+- **Diverged**: errors increase → learning rate too high, try lower values
+- **Flat from start**: poor initialization or tiny grid
+
+After showing the log, ask the user:
+- "The training shows [observation]. Would you like to adjust epochs or learning rate?"
+- If errors plateaued early: "Convergence was reached quickly. Consider a larger grid for more detail."
+- If errors were still falling: "Training was cut short. Add more epochs for a better map."
+
+Also shows training duration, which helps estimate time for future runs.
+
+BATCH SIZE EFFECT: Smaller batch sizes (32–64) produce more update steps per epoch,
+often yielding lower final QE and smoother convergence curves. If the learning curve
+plateaus early, try more epochs. If it's noisy, try a larger batch size for stability.`, {
+    job_id: z.string().describe("Job ID of a completed training job"),
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}/training-log`));
+    const ordErrors = data.ordering_errors ?? [];
+    const convErrors = data.convergence_errors ?? [];
+    const duration = data.training_duration_seconds;
+    const epochs = data.epochs;
+    const sparkline = (arr) => {
+        if (arr.length === 0)
+            return "(no data)";
+        const blocks = "▁▂▃▄▅▆▇█";
+        const min = Math.min(...arr);
+        const max = Math.max(...arr);
+        const range = max - min || 1;
+        return arr
+            .map((v) => blocks[Math.min(7, Math.floor(((v - min) / range) * 7))])
+            .join("");
+    };
+    const lines = [
+        `Training Log — Job ${job_id}`,
+        `Grid: ${JSON.stringify(data.grid)} | Model: ${data.model ?? "SOM"}`,
+        `Epochs: ${epochs ? `[${epochs[0]} ordering, ${epochs[1]} convergence]` : "N/A"}`,
+        `Duration: ${duration !== null && duration !== undefined ? `${duration}s` : "N/A"}`,
+        `Features: ${data.n_features ?? "?"} | Samples: ${data.n_samples ?? "?"}`,
+        ``,
+        `Ordering Phase (${ordErrors.length} epochs):`,
+        `  Start QE: ${ordErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${ordErrors.at(-1)?.toFixed(4) ?? "—"}`,
+        `  Curve:    ${sparkline(ordErrors)}`,
+    ];
+    if (convErrors.length > 0) {
+        lines.push(``, `Convergence Phase (${convErrors.length} epochs):`, `  Start QE: ${convErrors[0]?.toFixed(4) ?? "—"}  →  End QE: ${convErrors.at(-1)?.toFixed(4) ?? "—"}`, `  Curve:    ${sparkline(convErrors)}`);
+    }
+    else if ((epochs?.[1] ?? 0) === 0) {
+        lines.push(``, `Convergence phase: skipped (epochs[1]=0)`);
+    }
+    const finalQe = data.quantization_error;
+    const finalEv = data.explained_variance;
+    if (finalQe !== null && finalQe !== undefined) {
+        lines.push(``, `Final QE: ${finalQe.toFixed(4)} | Explained Variance: ${(finalEv ?? 0).toFixed(4)}`);
+    }
+    const content = [
+        { type: "text", text: lines.join("\n") },
+    ];
+    // Inline the pre-generated learning curve plot (worker saves it during training).
+    // Try png first (default), then pdf/svg in case the job used a different format.
+    let attached = false;
+    for (const lcExt of ["png", "pdf", "svg"]) {
+        try {
+            const { data: lcBuf } = await apiRawCall(`/v1/results/${job_id}/image/learning_curve.${lcExt}`);
+            content.push({
+                type: "image",
+                data: lcBuf.toString("base64"),
+                mimeType: mimeForFilename(`learning_curve.${lcExt}`),
+                annotations: { audience: ["user"], priority: 0.8 },
+            });
+            attached = true;
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!attached) {
+        content.push({ type: "text", text: "(learning curve plot not available)" });
+    }
+    return { content };
+});
+// ---- get_weights ----
+server.tool("get_weights", `Export the raw SOM weight matrix for a completed job.
+
+Returns a structured weight matrix with:
+- Per-node coordinates (for spatial mapping)
+- Normalized and denormalized weight values per feature
+- Normalization statistics (mean/std used during training)
+
+Use this to:
+- Export the trained model for external analysis
+- Visualize the weight space in custom tools
+- Compare weight structures between training runs
+- Build custom projections or classifications
+
+The weight matrix can be large for big grids. Consider filtering to specific
+features if you only need a subset.`, {
+    job_id: z.string().describe("Job ID of a completed training job"),
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}/weights`));
+    const features = data.features ?? [];
+    const nNodes = data.n_nodes ?? 0;
+    const grid = data.grid ?? [0, 0];
+    const lines = [
+        `SOM Weights — Job ${job_id}`,
+        `Grid: ${grid[0]}×${grid[1]} | Nodes: ${nNodes} | Features: ${features.length}`,
+        `Features: ${features.join(", ")}`,
+        ``,
+        `Normalization Stats:`,
+    ];
+    const normStats = data.normalization_stats ?? {};
+    for (const [feat, s] of Object.entries(normStats)) {
+        lines.push(`  ${feat}: mean=${s.mean?.toFixed(4)}, std=${s.std?.toFixed(4)}`);
+    }
+    lines.push(``, `Full weight matrix available in the response JSON.`, `Use the denormalized_weights array for original-scale values.`);
+    return {
+        content: [
+            { type: "text", text: lines.join("\n") },
+            { type: "text", text: JSON.stringify(data, null, 2) },
+        ],
+    };
+});
+// ---- get_node_data ----
+server.tool("get_node_data", `Get per-node statistics for a completed SOM job.
+
+Returns for each SOM node:
+- Hit count (how many data points map to this node)
+- Feature mean and std for all samples that map to this node
+
+This answers "what data lives in this cluster?" — enabling characterization
+of distinct operating modes, regimes, or behavioral groups.
+
+Use this to:
+- Profile each cluster by its feature distributions
+- Find dominant nodes (high hit count) vs rare nodes
+- Compare feature distributions between nodes
+- Identify the most "representative" state for each cluster
+
+After showing node data, ask the user:
+- "Do these cluster profiles match your domain knowledge?"
+- "Which nodes represent the most common operating states?"
+- "Are there any nodes with extreme feature values worth investigating?"`, {
+    job_id: z.string().describe("Job ID of a completed training job"),
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}/nodes`));
+    const topNodes = [...data]
+        .sort((a, b) => (b.hit_count ?? 0) - (a.hit_count ?? 0))
+        .slice(0, 10);
+    const emptyNodes = data.filter((n) => n.hit_count === 0).length;
+    const totalHits = data.reduce((sum, n) => sum + (n.hit_count ?? 0), 0);
+    const lines = [
+        `Node Statistics — Job ${job_id}`,
+        `Total nodes: ${data.length} | Active: ${data.length - emptyNodes} | Empty: ${emptyNodes}`,
+        `Total hits: ${totalHits}`,
+        ``,
+        `Top 10 Most Populated Nodes:`,
+        `| Node | Coords | Hits | Hit% |`,
+        `|------|--------|------|------|`,
+    ];
+    for (const n of topNodes) {
+        if (n.hit_count === 0)
+            break;
+        const coords = n.coords;
+        const pct = ((n.hit_count / totalHits) * 100).toFixed(1);
+        lines.push(`| ${n.node_index} | (${coords?.[0]?.toFixed(1)}, ${coords?.[1]?.toFixed(1)}) | ${n.hit_count} | ${pct}% |`);
+    }
+    return {
+        content: [
+            { type: "text", text: lines.join("\n") },
+            {
+                type: "text",
+                text: `\nFull node statistics JSON:\n${JSON.stringify(data, null, 2)}`,
+            },
+        ],
+    };
+});
+// ---- project_variable ----
+server.tool("project_variable", `Project a pre-computed variable onto a trained SOM without retraining.
+
+BEST FOR: Mapping external metrics (revenue, labels, anomaly scores) onto the
+trained SOM structure. Use derive_variable instead if you need to compute
+the variable from existing dataset columns via a formula.
+NOT FOR: Re-training or adding features to the map.
+
+TIMING: ~5–15s (loads cached SOM, computes per-node aggregation, renders plot).
+
+The values array must have exactly one value per training sample (same CSV row order).
+Aggregation controls how multiple samples per node are combined (mean/median/sum/max/count).
+
+BEFORE calling, ask:
+- "What variable? Is it from the original data or externally computed?"
+- "How to aggregate per node: mean (typical), sum (totals), max (peaks)?"
+
+COMMON MISTAKES:
+- Wrong number of values (must match n_samples from training)
+- Using mean aggregation for count data (use sum instead)
+- Not trying derive_variable first when the variable can be computed from columns
+
+TIP: If the variable is a formula over existing columns (e.g., revenue/cost),
+use derive_variable with project_onto_job instead — it handles the computation.`, {
+    job_id: z.string().describe("ID of the completed SOM training job"),
+    variable_name: z.string().describe("Name for this variable (used in visualization labels)"),
+    values: z
+        .array(z.number())
+        .describe("Array of values to project — one per training sample, in original CSV row order"),
+    aggregation: z
+        .enum(["mean", "median", "sum", "min", "max", "std", "count"])
+        .optional()
+        .default("mean")
+        .describe("How to aggregate values for nodes with multiple samples"),
+    output_format: z
+        .enum(["png", "pdf", "svg"])
+        .optional()
+        .default("png")
+        .describe("Image output format for the projection plot."),
+    output_dpi: z
+        .enum(["standard", "retina", "print"])
+        .optional()
+        .default("retina")
+        .describe("Resolution: standard (1x), retina (2x), print (4x)."),
+    colormap: z
+        .string()
+        .optional()
+        .describe("Override colormap for the projection plot (default: plasma)."),
+}, async ({ job_id, variable_name, values, aggregation, output_format, output_dpi, colormap }) => {
+    const dpiMap = { standard: 1, retina: 2, print: 4 };
+    const body = {
+        variable_name,
+        values,
+        aggregation: aggregation ?? "mean",
+    };
+    if (output_format && output_format !== "png")
+        body.output_format = output_format;
+    if (output_dpi && output_dpi !== "retina")
+        body.output_dpi = dpiMap[output_dpi] ?? 2;
+    if (colormap)
+        body.colormap = colormap;
+    const data = (await apiCall("POST", `/v1/results/${job_id}/project`, body));
+    const projJobId = data.id;
+    const poll = await pollUntilComplete(projJobId);
+    if (poll.status === "completed") {
+        const results = (await apiCall("GET", `/v1/results/${projJobId}`));
+        const summary = (results.summary ?? {});
+        const stats = (summary.variable_stats ?? {});
+        const content = [];
+        content.push({
+            type: "text",
+            text: [
+                `Projected Variable: ${variable_name} (${aggregation ?? "mean"}) — job: ${projJobId}`,
+                `Parent SOM: ${job_id} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Variable Statistics (per-node ${aggregation ?? "mean"}):`,
+                `  Min:  ${stats.min !== undefined ? Number(stats.min).toFixed(3) : "N/A"}`,
+                `  Max:  ${stats.max !== undefined ? Number(stats.max).toFixed(3) : "N/A"}`,
+                `  Mean: ${stats.mean !== undefined ? Number(stats.mean).toFixed(3) : "N/A"}`,
+                `  Nodes with data: ${stats.n_nodes_with_data ?? "N/A"}`,
+            ].join("\n"),
+        });
+        const safeName = variable_name.replace(/[^a-zA-Z0-9_]/g, "_");
+        const imgExt = summary.output_format ?? output_format ?? "png";
+        await tryAttachImage(content, projJobId, `projected_${safeName}.${imgExt}`);
+        return { content };
+    }
+    if (poll.status === "failed") {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Projection job ${projJobId} failed: ${poll.error ?? "unknown error"}`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: "text",
+                text: [
+                    `Variable projection job submitted but did not complete within 30s.`,
+                    `Projection job ID: ${projJobId}`,
+                    ``,
+                    `Poll with: get_job_status(job_id="${projJobId}")`,
+                    `Retrieve with: get_results(job_id="${projJobId}")`,
+                ].join("\n"),
+            }],
+    };
+});
+// ---- transition_flow ----
+server.tool("transition_flow", `Compute temporal transition flow for a trained SOM.
+
+Shows how data points move between SOM nodes over time — revealing directional
+patterns, cycles, and state machine behavior in sequential data.
+
+Best used for:
+- **Time-series data**: how does the system evolve over time?
+- **Cyclic processes**: daily/weekly patterns, recurring operating modes
+- **Process monitoring**: identify common transition paths between states
+- **Anomaly detection**: transitions that deviate from normal flow patterns
+
+The lag parameter controls how many steps ahead to look for transitions.
+lag=1 shows immediate next-step transitions.
+lag=N shows transitions N steps apart (useful for periodic analysis).
+
+BEFORE calling, ask the user:
+- "Is your data ordered in time? What is the time resolution of each row?"
+- "What lag should we use? lag=1 for immediate transitions, larger for longer-range patterns"
+- "Are there any breaks in the time series (missing intervals, separate sessions)?"
+
+Output options: output_format (png/pdf/svg), output_dpi (standard/retina/print).
+
+After showing results, ask:
+- "Do the flow arrows show expected directional patterns in your process?"
+- "Are there circular/cyclic regions? Do those match known periodic behavior?"
+- "Which nodes act as hubs (many transitions through them)?"`, {
+    job_id: z.string().describe("ID of the completed SOM training job"),
+    lag: z
+        .number()
+        .int()
+        .optional()
+        .default(1)
+        .describe("Step lag for transition pairs (default 1 = consecutive rows)"),
+    output_format: z
+        .enum(["png", "pdf", "svg"])
+        .optional()
+        .default("png")
+        .describe("Image output format for the flow plot."),
+    output_dpi: z
+        .enum(["standard", "retina", "print"])
+        .optional()
+        .default("retina")
+        .describe("Resolution: standard (1x), retina (2x), print (4x)."),
+}, async ({ job_id, lag, output_format, output_dpi }) => {
+    const dpiMap = { standard: 1, retina: 2, print: 4 };
+    const body = { lag: lag ?? 1 };
+    if (output_format && output_format !== "png")
+        body.output_format = output_format;
+    if (output_dpi && output_dpi !== "retina")
+        body.output_dpi = dpiMap[output_dpi] ?? 2;
+    const data = (await apiCall("POST", `/v1/results/${job_id}/transition-flow`, body));
+    const flowJobId = data.id;
+    const poll = await pollUntilComplete(flowJobId);
+    if (poll.status === "completed") {
+        const results = (await apiCall("GET", `/v1/results/${flowJobId}`));
+        const summary = (results.summary ?? {});
+        const stats = (summary.flow_stats ?? {});
+        const content = [];
+        content.push({
+            type: "text",
+            text: [
+                `Transition Flow Results (job: ${flowJobId})`,
+                `Parent SOM: ${job_id} | Lag: ${lag ?? 1} | Samples: ${summary.n_samples ?? 0}`,
+                ``,
+                `Flow Statistics:`,
+                `  Active flow nodes:  ${stats.active_flow_nodes ?? "N/A"}`,
+                `  Total transitions:  ${stats.total_transitions ?? "N/A"}`,
+                `  Mean magnitude:     ${stats.mean_magnitude !== undefined ? Number(stats.mean_magnitude).toFixed(4) : "N/A"}`,
+            ].join("\n"),
+        });
+        const imgExt = output_format ?? "png";
+        await tryAttachImage(content, flowJobId, `transition_flow_lag${lag ?? 1}.${imgExt}`);
+        return { content };
+    }
+    if (poll.status === "failed") {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Transition flow job ${flowJobId} failed: ${poll.error ?? "unknown error"}`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: "text",
+                text: [
+                    `Transition flow job submitted but did not complete within 30s.`,
+                    `Flow job ID: ${flowJobId}`,
+                    `Parent job: ${job_id} | Lag: ${lag ?? 1}`,
+                    ``,
+                    `Poll with: get_job_status(job_id="${flowJobId}")`,
+                    `Retrieve with: get_results(job_id="${flowJobId}")`,
+                ].join("\n"),
+            }],
+    };
+});
+// ---- derive_variable ----
+server.tool("derive_variable", `Create a derived variable from existing dataset columns using mathematical expressions.
+
+BEST FOR: Computing ratios, differences, log transforms, rolling statistics,
+or any combination of existing columns — either to enrich a dataset before
+training or to project a computed variable onto an existing SOM.
+
+TWO MODES:
+1. Add to dataset (default): computes the new column and appends it to the dataset CSV.
+   The column is then available for future train_som calls via the 'columns' parameter.
+2. Project onto SOM: computes the column from the training dataset and projects it
+   onto a trained SOM, returning the visualization. Use this to explore how
+   derived quantities distribute across the learned map structure.
+
+COMMON FORMULAS:
+- Ratio:       "revenue / cost"
+- Difference:  "US10Y - US3M"
+- Log return:  "log(close) - log(open)"
+- Z-score:     "(volume - rolling_mean(volume, 20)) / rolling_std(volume, 20)"
+- Magnitude:   "sqrt(x^2 + y^2)"
+- Unit convert: "temperature - 273.15"
+- First diff:  "diff(consumption)"
+
+SUPPORTED FUNCTIONS:
+- Arithmetic: +, -, *, /, ^
+- Math: log, log1p, log10, exp, sqrt, abs, sign, clamp, min, max
+- Trig: sin, cos, tan, asin, acos, atan
+- Rolling: rolling_mean(col, window), rolling_std(col, window), rolling_min, rolling_max
+- Temporal: diff(col), diff(col, n)
+- Constants: pi, numeric literals
+
+WORKFLOW: Ask the user what domain-specific variables they care about.
+Suggest derived variables based on the column names. For example, if
+the dataset has "revenue" and "cost", suggest "revenue - cost" as profit
+and "revenue / cost" as cost efficiency.
+
+COMMON MISTAKES:
+- Division by zero: if denominator column has zeros, use options.missing="skip"
+- Rolling functions produce NaN for the first (window-1) rows
+- diff() produces NaN for the first row
+- Column names with special characters are converted to underscores in expressions`, {
+    dataset_id: z.string().describe("Dataset ID (source of column data)"),
+    name: z.string().describe("Name for the derived variable (used in column header and visualization)"),
+    expression: z
+        .string()
+        .describe("Mathematical expression referencing column names. " +
+        "Examples: 'revenue / cost', 'log(price)', 'diff(temperature)', " +
+        "'sqrt(x^2 + y^2)', 'rolling_mean(volume, 20)'"),
+    project_onto_job: z
+        .string()
+        .optional()
+        .describe("If provided, project the derived variable onto this SOM job instead of adding to dataset. " +
+        "The job must be a completed train_som job."),
+    aggregation: z
+        .enum(["mean", "median", "sum", "min", "max", "std", "count"])
+        .optional()
+        .default("mean")
+        .describe("How to aggregate values per SOM node (only used when project_onto_job is set)"),
+    options: z
+        .object({
+        missing: z
+            .enum(["skip", "zero", "interpolate"])
+            .optional()
+            .default("skip")
+            .describe("How to handle NaN/missing values in the result"),
+        window: z
+            .number()
+            .int()
+            .optional()
+            .describe("Default window size for rolling functions (default 20)"),
+        description: z
+            .string()
+            .optional()
+            .describe("Human-readable description of what this variable represents"),
+    })
+        .optional()
+        .describe("Configuration for expression evaluation"),
+    output_format: z
+        .enum(["png", "pdf", "svg"])
+        .optional()
+        .default("png")
+        .describe("Image format for projection visualization (only when project_onto_job is set)"),
+    output_dpi: z
+        .enum(["standard", "retina", "print"])
+        .optional()
+        .default("retina")
+        .describe("Resolution for projection visualization"),
+    colormap: z
+        .string()
+        .optional()
+        .describe("Colormap for projection visualization (default: plasma)"),
+}, async ({ dataset_id, name, expression, project_onto_job, aggregation, options, output_format, output_dpi, colormap, }) => {
+    const dpiMap = { standard: 1, retina: 2, print: 4 };
+    if (project_onto_job) {
+        // Mode: project onto SOM
+        const body = {
+            name,
+            expression,
+            aggregation: aggregation ?? "mean",
+        };
+        if (options)
+            body.options = options;
+        if (output_format && output_format !== "png")
+            body.output_format = output_format;
+        if (output_dpi && output_dpi !== "retina")
+            body.output_dpi = dpiMap[output_dpi] ?? 2;
+        if (colormap)
+            body.colormap = colormap;
+        const data = (await apiCall("POST", `/v1/results/${project_onto_job}/derive`, body));
+        const deriveJobId = data.id;
+        const poll = await pollUntilComplete(deriveJobId);
+        if (poll.status === "completed") {
+            const results = (await apiCall("GET", `/v1/results/${deriveJobId}`));
+            const summary = (results.summary ?? {});
+            const stats = (summary.variable_stats ?? {});
+            const content = [];
+            content.push({
+                type: "text",
+                text: [
+                    `Derived Variable Projected: ${name} — job: ${deriveJobId}`,
+                    `Expression: ${expression}`,
+                    `Parent SOM: ${project_onto_job} | Aggregation: ${aggregation ?? "mean"}`,
+                    ``,
+                    `Statistics (per-node ${aggregation ?? "mean"}):`,
+                    `  Min:  ${stats.min !== undefined ? Number(stats.min).toFixed(3) : "N/A"}`,
+                    `  Max:  ${stats.max !== undefined ? Number(stats.max).toFixed(3) : "N/A"}`,
+                    `  Mean: ${stats.mean !== undefined ? Number(stats.mean).toFixed(3) : "N/A"}`,
+                    `  Nodes with data: ${stats.n_nodes_with_data ?? "N/A"}`,
+                    summary.nan_count ? `  NaN values: ${summary.nan_count}` : "",
+                ]
+                    .filter((l) => l !== "")
+                    .join("\n"),
+            });
+            const safeName = name.replace(/[^a-zA-Z0-9_]/g, "_");
+            const imgExt = summary.output_format ?? output_format ?? "png";
+            await tryAttachImage(content, deriveJobId, `projected_${safeName}.${imgExt}`);
+            return { content };
+        }
+        if (poll.status === "failed") {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Derive+project job ${deriveJobId} failed: ${poll.error ?? "unknown error"}`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `Derive job submitted. Poll: get_job_status("${deriveJobId}")`,
+                }],
+        };
+    }
+    else {
+        // Mode: add to dataset
+        const body = { name, expression };
+        if (options)
+            body.options = options;
+        const data = (await apiCall("POST", `/v1/datasets/${dataset_id}/derive`, body));
+        const deriveJobId = data.id;
+        const poll = await pollUntilComplete(deriveJobId);
+        if (poll.status === "completed") {
+            const results = (await apiCall("GET", `/v1/results/${deriveJobId}`));
+            const summary = (results.summary ?? {});
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Derived column "${name}" added to dataset ${dataset_id}`,
+                            `Expression: ${expression}`,
+                            `Rows: ${summary.n_rows ?? "?"}`,
+                            summary.nan_count ? `NaN values: ${summary.nan_count}` : "",
+                            `Min: ${summary.min ?? "?"} | Max: ${summary.max ?? "?"} | Mean: ${summary.mean ?? "?"}`,
+                            ``,
+                            `The column is now available in the dataset. Include it in train_som`,
+                            `via the 'columns' parameter, or use preview_dataset to verify.`,
+                        ]
+                            .filter((l) => l !== "")
+                            .join("\n"),
+                    }],
+            };
+        }
+        if (poll.status === "failed") {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Derive variable job ${deriveJobId} failed: ${poll.error ?? "unknown error"}`,
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `Derive job submitted. Poll: get_job_status("${deriveJobId}")`,
+                }],
+        };
+    }
+});
+// ---- quality_report ----
+server.tool("quality_report", `Generate a comprehensive quality report for a trained SOM.
+
+Returns all available metrics organized by category:
+- **Standard metrics**: Quantization Error (QE), Topographic Error (TE), Distortion
+- **Cluster metrics**: Silhouette, Davies-Bouldin, Calinski-Harabasz
+- **Topology metrics**: Neighborhood Preservation, Trustworthiness, Topographic Product
+- **Training info**: duration, epochs, learning parameters
+
+Metric interpretation guide:
+- QE < 0.5: excellent | 0.5–1.0: good | 1.0–2.0: fair | >2.0: needs improvement
+- TE < 0.05: excellent | 0.05–0.10: good | 0.10–0.20: fair | >0.20: poor topology
+- Trustworthiness: closer to 1.0 = better (local neighborhoods preserved)
+- Neighborhood Preservation: closer to 1.0 = better (global structure preserved)
+- Topographic Product: near 0 = well-sized grid | <0 = grid too small | >0 = grid too large
+
+After showing the report, ask the user:
+- "Which metrics are most important for your use case?"
+- "Do any metrics suggest the map needs retraining?"`, {
+    job_id: z.string().describe("Job ID of a completed training job"),
+}, async ({ job_id }) => {
+    const data = (await apiCall("GET", `/v1/results/${job_id}/quality-report`));
+    const std = data.standard_metrics ?? {};
+    const clust = data.cluster_metrics ?? {};
+    const topo = data.topology_metrics ?? {};
+    const train = data.training ?? {};
+    const grid = data.grid ?? [0, 0];
+    const fmt = (v) => v !== null && v !== undefined ? v.toFixed(4) : "—";
+    const fmtPct = (v) => v !== null && v !== undefined ? `${(v * 100).toFixed(1)}%` : "—";
+    const recommendations = [];
+    const qe = std.quantization_error;
+    const te = std.topographic_error;
+    const ev = std.explained_variance;
+    const sil = clust.silhouette;
+    const trust = topo.trustworthiness;
+    const nbp = topo.neighborhood_preservation;
+    if (qe !== null && qe !== undefined && qe > 2.0)
+        recommendations.push("QE is high → try more epochs or a larger grid");
+    if (te !== null && te !== undefined && te > 0.15)
+        recommendations.push("TE is high → topology is not well-preserved, try larger grid");
+    if (ev !== null && ev !== undefined && ev < 0.7)
+        recommendations.push("Explained variance < 70% → consider more training or feature selection");
+    if (sil !== null && sil !== undefined && sil < 0.1)
+        recommendations.push("Low silhouette → clusters overlap, try sigma_f=0.5 or more epochs");
+    if (trust !== null && trust !== undefined && trust < 0.85)
+        recommendations.push("Trustworthiness < 85% → local neighborhood structure is distorted");
+    if (recommendations.length === 0)
+        recommendations.push("All metrics look healthy — good map quality!");
+    const epochs = train.epochs;
+    const epochStr = epochs
+        ? epochs[1] === 0 ? `${epochs[0]} ordering only` : `${epochs[0]}+${epochs[1]}`
+        : "—";
+    const lines = [
+        `Quality Report — Job ${job_id}`,
+        `Grid: ${grid[0]}×${grid[1]} | Model: ${data.model ?? "SOM"} | Samples: ${data.n_samples ?? "?"}`,
+        `Epochs: ${epochStr} | Duration: ${train.duration_seconds ? `${train.duration_seconds}s` : "—"}`,
+        ``,
+        `Standard Metrics:`,
+        `  Quantization Error:  ${fmt(std.quantization_error)}   (lower is better)`,
+        `  Topographic Error:   ${fmt(std.topographic_error)}   (lower is better)`,
+        `  Distortion:          ${fmt(std.distortion)}`,
+        `  Kaski-Lagus Error:   ${fmt(std.kaski_lagus_error)}   (lower is better)`,
+        `  Explained Variance:  ${fmtPct(std.explained_variance)}`,
+        ``,
+        `Cluster Quality Metrics:`,
+        `  Silhouette Score:    ${fmt(clust.silhouette)}   (higher is better, -1 to +1)`,
+        `  Davies-Bouldin:      ${fmt(clust.davies_bouldin)}   (lower is better)`,
+        `  Calinski-Harabasz:   ${fmt(clust.calinski_harabasz)}   (higher is better)`,
+        ``,
+        `Topology Metrics:`,
+        `  Neighborhood Preservation: ${fmtPct(topo.neighborhood_preservation)}   (higher is better)`,
+        `  Trustworthiness:           ${fmtPct(topo.trustworthiness)}   (higher is better)`,
+        `  Topographic Product:       ${fmt(topo.topographic_product)}   (near 0 is ideal)`,
+        ``,
+        `Recommendations:`,
+        ...recommendations.map((r) => `  • ${r}`),
+    ];
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// ---- system_info ----
+server.tool("system_info", `Get runtime environment and worker topology information.
+
+Returns compute resources, configured worker topology (num_workers,
+threads_per_worker, max_concurrent_jobs), job queue state, and training
+time estimates.
+
+Use this BEFORE submitting large jobs to:
+- See how many workers are running and how many threads each has
+- Check queue depth to decide whether to wait or proceed
+- Estimate wall-clock time based on the current topology
+- Decide whether to call configure_resources first
+
+Worker topology example:
+  2 workers × 8 threads = 16 total threads
+  max_concurrent_jobs=2 → both workers train simultaneously
+  Wall-clock time for 30×30 60-epoch SOM: ~350s instead of ~700s
+
+Use configure_resources to change the topology.`, {}, async () => {
+    const data = (await apiCall("GET", "/v1/system/info"));
+    const estimates = data.training_time_estimates_seconds ?? {};
+    const notes = data.notes ?? [];
+    const topo = data.worker_topology ?? {};
+    const lines = [
+        `System Information`,
+        ``,
+        `Worker Topology (configured):`,
+        `  Workers:             ${topo.num_workers ?? "?"}`,
+        `  Threads per Worker:  ${topo.threads_per_worker ?? "?"}`,
+        `  Max Concurrent Jobs: ${topo.max_concurrent_jobs ?? "?"}`,
+        `  Total Thread Budget: ${topo.total_thread_budget ?? "?"}`,
+        `  To apply changes:    ${topo.restart_command ?? "see configure_resources"}`,
+        ``,
+        `Host Resources (API server):`,
+        `  CPU Threads:     ${data.cpu_threads}`,
+        `  Total Memory:    ${data.total_memory_gb} GB`,
+        `  Free Memory:     ${data.free_memory_gb} GB`,
+        `  GPU Available:   ${data.gpu_available ? "Yes" : "No (CPU only)"}`,
+        ``,
+        `Job Queue:`,
+        `  Running Jobs:  ${data.running_jobs}`,
+        `  Pending Jobs:  ${data.pending_jobs}`,
+        `  Queue Depth:   ${data.queue_depth}`,
+        ``,
+        `Estimated Training Times (seconds, per-worker):`,
+        ...Object.entries(estimates)
+            .filter(([k]) => k !== "formula")
+            .map(([k, v]) => `  ${k}: ~${v}s`),
+        `  ${estimates.formula ?? ""}`,
+        ``,
+        `Notes:`,
+        ...notes.map((n) => `  • ${n}`),
+        topo.note ? `  • ${topo.note}` : "",
+    ].filter((l) => l !== undefined);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// ---- configure_resources ----
+server.tool("configure_resources", `Configure worker topology: thread count, worker replicas, and job concurrency.
+
+Parameters:
+- threads_per_worker  (int, 1–64)  — Julia threads each worker uses for training.
+                                     More threads = faster per-job training.
+                                     Typical: 4, 8, 16. Match to physical cores.
+- num_workers         (int, 1–16)  — Number of worker replicas running in parallel.
+                                     More workers = more simultaneous training jobs.
+                                     Each worker is a separate process with its own threads.
+- max_concurrent_jobs (int, 1–num_workers) — DB-level concurrency cap.
+                                     Set equal to num_workers to fully utilize all replicas.
+
+Effect:
+- max_concurrent_jobs takes effect IMMEDIATELY (no restart needed)
+- threads_per_worker and num_workers require a worker restart
+  → the response includes the exact restart_command to run
+
+Examples:
+  Single beefy run:   threads_per_worker=16, num_workers=1, max_concurrent_jobs=1
+  Parallel sweeps:    threads_per_worker=8,  num_workers=2, max_concurrent_jobs=2
+  CI / light load:    threads_per_worker=4,  num_workers=1, max_concurrent_jobs=1
+
+Rule of thumb: threads_per_worker × num_workers ≤ physical CPU core count.
+Call system_info first to see how many CPU threads are available.`, {
+    threads_per_worker: z
+        .number()
+        .int()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Julia threads per worker process (1–64). Restart required."),
+    num_workers: z
+        .number()
+        .int()
+        .min(1)
+        .max(16)
+        .optional()
+        .describe("Number of parallel worker replicas (1–16). Restart required."),
+    max_concurrent_jobs: z
+        .number()
+        .int()
+        .min(1)
+        .max(16)
+        .optional()
+        .describe("Maximum simultaneous training jobs (1–num_workers). Takes effect immediately."),
+}, async ({ threads_per_worker, num_workers, max_concurrent_jobs }) => {
+    const body = {};
+    if (threads_per_worker !== undefined)
+        body.threads_per_worker = threads_per_worker;
+    if (num_workers !== undefined)
+        body.num_workers = num_workers;
+    if (max_concurrent_jobs !== undefined)
+        body.max_concurrent_jobs = max_concurrent_jobs;
+    if (Object.keys(body).length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "No parameters provided. Specify at least one of: threads_per_worker, num_workers, max_concurrent_jobs.",
+                },
+            ],
+        };
+    }
+    const result = (await apiCall("POST", "/v1/system/resources", body));
+    const applied = result.applied ?? {};
+    const lines = [
+        `Resource Configuration Applied`,
+        ``,
+        `Current Settings:`,
+        `  Threads per Worker:  ${applied.threads_per_worker}`,
+        `  Worker Replicas:     ${applied.num_workers}`,
+        `  Max Concurrent Jobs: ${applied.max_concurrent_jobs}`,
+        `  Total Thread Budget: ${applied.total_thread_budget}`,
+        ``,
+        `max_concurrent_jobs: ${result.max_concurrent_jobs_effective}`,
+    ];
+    if (result.restart_required) {
+        lines.push(``, `⚠ Worker restart required for thread/replica changes.`, `  Run: ${result.restart_command}`, ``, `  ${result.restart_note}`);
+    }
+    else {
+        lines.push(``, `✓ All changes applied immediately — no restart needed.`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+server.prompt("prepare_training", "Guided pre-training checklist. Use after uploading a dataset and before calling " +
+    "train_som. Walks through column selection, transforms, cyclic features, " +
+    "temporal features, weighting, derived variables, and grid sizing.", { dataset_id: z.string().describe("Dataset ID to prepare for training") }, ({ dataset_id }) => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: `Guide me through preparing dataset ${dataset_id} for SOM training. ` +
+                    `For each step, show the relevant data and ask me to decide:\n` +
+                    `1. COLUMN SELECTION: Which columns to include/exclude?\n` +
+                    `2. TRANSFORMS: Any columns need log, sqrt, or rank transforms? (check for skewed distributions)\n` +
+                    `3. CYCLIC FEATURES: Any periodic columns (hour, weekday, angle, direction)?\n` +
+                    `4. TEMPORAL FEATURES: Any datetime columns to extract components from?\n` +
+                    `5. FEATURE WEIGHTS: Should any features be emphasized or de-emphasized?\n` +
+                    `6. DERIVED VARIABLES: Any new columns to compute from existing ones? (e.g., ratios, differences)\n` +
+                    `7. GRID & MODEL: What grid size and model type?\n\n` +
+                    `Start by calling preview_dataset to show me the columns and statistics.`,
+            },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Image helper
+// ---------------------------------------------------------------------------
+function mimeForFilename(fname) {
+    if (fname.endsWith(".pdf"))
+        return "application/pdf";
+    if (fname.endsWith(".svg"))
+        return "image/svg+xml";
+    return "image/png";
+}
+async function tryAttachImage(content, jobId, filename) {
+    try {
+        const { data: imgBuf } = await apiRawCall(`/v1/results/${jobId}/image/${filename}`);
+        content.push({
+            type: "image",
+            data: imgBuf.toString("base64"),
+            mimeType: mimeForFilename(filename),
+            annotations: { audience: ["user"], priority: 0.8 },
+        });
+    }
+    catch {
+        content.push({
+            type: "text",
+            text: `(${filename} not available for inline display)`,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Connect via stdio
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map