@barivia/barsom-mcp 0.3.2 → 0.3.5

package/dist/index.js

@@ -1,2446 +1,2 @@
 #!/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 ?? "pdf";
-    await tryAttachImage(content, job_id, `combined.${imgExt}`);
-    return { content };
-});
-// ---- datasets ----
-server.tool("datasets", `Manage datasets: upload, preview, subset, or delete.
-
-action=upload: Upload a CSV for SOM analysis. Prefer file_path over csv_data so the MCP reads the file directly. Returns dataset ID and metadata. Then use datasets(action=preview) before train_som.
-action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train_som on an unfamiliar dataset.
-action=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range or filters.
-  - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)
-  - filters: array of conditions, ALL must match (AND logic). Each: { column, op, value }.
-    Operators:
-      eq     — exact match (string or number): { column: "region", op: "eq", value: "Europe" }
-      ne     — not equal: { column: "status", op: "ne", value: "error" }
-      in     — value in set: { column: "grade", op: "in", value: ["A", "B"] }
-      gt/lt  — above/below threshold: { column: "temp", op: "gt", value: 20 }
-      gte/lte — at or above/below: { column: "price", op: "gte", value: 100 }
-      between — closed interval [lo, hi]: { column: "age", op: "between", value: [18, 65] }
-  - Combine row_range + filters to slice both rows and values.
-  - Single filter object is also accepted (auto-wrapped).
-action=delete: Remove a dataset and free the slot.
-
-BEST FOR: Tabular numeric data. CSV with header required. Use list(type=datasets) to see existing datasets.`, {
-    action: z
-        .enum(["upload", "preview", "subset", "delete"])
-        .describe("upload: add a CSV; preview: inspect before training; subset: create subset dataset; delete: remove dataset"),
-    name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
-    file_path: z.string().optional().describe("Path to local CSV (for upload; prefer over csv_data)"),
-    csv_data: z.string().optional().describe("Inline CSV string (for upload; use for small data)"),
-    dataset_id: z.string().optional().describe("Dataset ID (required for preview, subset, and delete)"),
-    n_rows: z.number().int().optional().default(5).describe("Sample rows to return (preview only)"),
-    row_range: z
-        .tuple([z.number().int(), z.number().int()])
-        .optional()
-        .describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),
-    filters: z.preprocess((v) => {
-        if (v === undefined || v === null)
-            return v;
-        if (Array.isArray(v))
-            return v;
-        if (typeof v === "object" && v !== null && "column" in v)
-            return [v];
-        return v;
-    }, z
-        .array(z.object({
-        column: z.string(),
-        op: z.enum(["eq", "ne", "in", "gt", "lt", "gte", "lte", "between"]),
-        value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
-    }))
-        .optional()
-        .describe("For subset: filter conditions (AND logic). Single object or array. " +
-        "ops: eq, ne, in, gt, lt, gte, lte, between. " +
-        "Examples: { column: 'temp', op: 'between', value: [15, 30] }, { column: 'region', op: 'eq', value: 'Europe' }")),
-    filter: z
-        .object({
-        column: z.string(),
-        op: z.enum(["eq", "ne", "in", "gt", "lt", "gte", "lte", "between"]),
-        value: z.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))]),
-    })
-        .optional()
-        .describe("Deprecated — use filters instead. Single filter condition."),
-}, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter }) => {
-    if (action === "upload") {
-        if (!name)
-            throw new Error("datasets(upload) requires name");
-        let body;
-        if (file_path) {
-            const resolved = path.resolve(file_path);
-            try {
-                body = await fs.readFile(resolved, "utf-8");
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                throw new Error(`Cannot read file "${resolved}": ${msg}`);
-            }
-        }
-        else if (csv_data && csv_data.length > 0) {
-            body = csv_data;
-        }
-        else {
-            throw new Error("datasets(upload) requires file_path or csv_data");
-        }
-        const data = await apiCall("POST", "/v1/datasets", body, {
-            "X-Dataset-Name": name,
-            "Content-Type": "text/csv",
-        });
-        return textResult(data);
-    }
-    if (action === "preview") {
-        if (!dataset_id)
-            throw new Error("datasets(preview) requires dataset_id");
-        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 (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(", ")}`);
-            }
-        }
-        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") }] };
-    }
-    if (action === "subset") {
-        if (!dataset_id)
-            throw new Error("datasets(subset) requires dataset_id");
-        if (!name)
-            throw new Error("datasets(subset) requires name");
-        const allFilters = filters ?? (filter ? [filter] : undefined);
-        if (row_range === undefined && allFilters === undefined) {
-            throw new Error("datasets(subset) requires at least one of row_range or filters");
-        }
-        const body = { name };
-        if (row_range !== undefined)
-            body.row_range = row_range;
-        if (allFilters !== undefined)
-            body.filters = allFilters;
-        const data = await apiCall("POST", `/v1/datasets/${dataset_id}/subset`, JSON.stringify(body), {
-            "Content-Type": "application/json",
-        });
-        return textResult(data);
-    }
-    if (action === "delete") {
-        if (!dataset_id)
-            throw new Error("datasets(delete) requires dataset_id");
-        const data = await apiCall("DELETE", `/v1/datasets/${dataset_id}`);
-        return textResult(data);
-    }
-    throw new Error("Invalid action");
-});
-// ---- 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 license_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?
-
-PRESET TABLE:
-| preset   | grid  | epochs    | batch_size |
-| quick    | 15x15 | [15, 5]   | 48         |
-| standard | 25x25 | [30, 15]  | 48         |
-| refined  | 40x40 | [50, 25]  | 32         |
-| high_res | 60x60 | [60, 40]  | 32         |
-
-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 datasets(action=preview) 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_job_export(export="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: default format pdf, default colormap coolwarm. Override with output_format (png/pdf/svg), output_dpi (standard/retina/print), colormap (e.g. viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral).
-
-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 datasets(action=upload) or list(type=datasets)"),
-    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, [15,5], batch=48. " +
-        "standard: 25×25, [30,15], batch=48, best with GPU. " +
-        "refined: 40×40, [50,25], batch=32, best with GPU. " +
-        "high_res: 60×60, [60,40], batch=32, best with GPU."),
-    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.preprocess((v) => {
-        if (v === undefined || v === null)
-            return v;
-        if (typeof v === "string") {
-            const n = parseInt(v, 10);
-            if (!Number.isNaN(n))
-                return n;
-            const m = v.match(/^\[\s*(\d+)\s*,\s*(\d+)\s*\]$/);
-            if (m)
-                return [parseInt(m[1], 10), parseInt(m[2], 10)];
-        }
-        return v;
-    }, z
-        .union([z.number().int(), z.array(z.number().int()).length(2)])
-        .optional()
-        .describe("epochs: integer or [ordering, convergence] array, not a string. Example: 40 or [40, 20]. Set convergence=0 to skip phase 2 (e.g. [15, 0]).")),
-    model: 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.preprocess((v) => {
-        if (v === undefined || v === null)
-            return v;
-        if (typeof v === "string") {
-            const n = parseFloat(v);
-            if (!Number.isNaN(n))
-                return n;
-        }
-        return v;
-    }, 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.preprocess((v) => {
-        if (v === undefined || v === null)
-            return v;
-        if (typeof v === "string") {
-            const n = parseFloat(v);
-            if (!Number.isNaN(n))
-                return n;
-        }
-        return v;
-    }, 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("pdf")
-        .describe("Image output format. PDF (default) for publication-quality vector graphics, PNG for quick viewing, 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 (coolwarm) for component planes and hit histogram. Examples: viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix always uses grays, cyclic features use twilight."),
-    row_range: z
-        .tuple([z.number().int().min(1), z.number().int().min(1)])
-        .optional()
-        .describe("Train on a subset of rows only: [start, end] 1-based inclusive. Alternative to creating a subset dataset with datasets(action=subset)."),
-}, async ({ dataset_id, 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, row_range, }) => {
-    const PRESETS = {
-        quick: { grid: [15, 15], epochs: [15, 5], batch_size: 48 },
-        standard: { grid: [25, 25], epochs: [30, 15], batch_size: 48, backend: "cuda" },
-        refined: { grid: [40, 40], epochs: [50, 25], batch_size: 32, backend: "cuda" },
-        high_res: { grid: [60, 60], epochs: [60, 40], 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;
-    }
-    params.output_format = output_format ?? "pdf";
-    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;
-    }
-    if (row_range && row_range.length >= 2 && row_range[0] <= row_range[1]) {
-        params.row_range = row_range;
-    }
-    const data = (await apiCall("POST", "/v1/jobs", {
-        dataset_id,
-        params,
-    }));
-    try {
-        const sys = (await apiCall("GET", "/v1/system/info"));
-        const p = Number(sys.status?.pending_jobs ?? sys.pending_jobs ?? 0);
-        const totalEta = Number(sys.training_time_estimates_seconds?.total ??
-            (sys.gpu_available ? 45 : 120));
-        // Simple calculation: wait time is jobs ahead of us * time per job
-        const waitMinutes = Math.round((p * totalEta) / 60);
-        if (waitMinutes > 1) {
-            data.estimated_wait_minutes = waitMinutes;
-            data.message = `Job submitted. You are #${p + 1} in queue. Estimated wait before start: ~${waitMinutes} min.`;
-        }
-        else {
-            data.message = "Job submitted. Should start momentarily.";
-        }
-    }
-    catch (e) {
-        // Ignore system info errors
-    }
-    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;
-    const label = data.label != null && data.label !== "" ? String(data.label) : null;
-    const jobDesc = label ? `Job ${label} (id: ${job_id})` : `Job ${job_id}`;
-    let text = `${jobDesc}: ${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 }] };
-});
-/** Resolve get_results figures param to list of image filenames to fetch. */
-function getResultsImagesToFetch(jobType, summary, figures, includeIndividual) {
-    const ext = summary.output_format ?? "pdf";
-    if (jobType === "transition_flow") {
-        const lag = summary.lag ?? 1;
-        return [`transition_flow_lag${lag}.${ext}`];
-    }
-    if (jobType === "project_variable") {
-        const varName = summary.variable_name ?? "variable";
-        const safe = String(varName).replace(/[^a-zA-Z0-9_]/g, "_");
-        return [`projected_${safe}.${ext}`];
-    }
-    if (jobType === "derive_variable") {
-        const varName = summary.variable_name ?? "variable";
-        const safe = String(varName).replace(/[^a-zA-Z0-9_]/g, "_");
-        return [`projected_${safe}.${ext}`];
-    }
-    // train_som
-    const features = summary.features ?? [];
-    const combinedName = `combined.${ext}`;
-    const umatrixName = `umatrix.${ext}`;
-    const hitHistName = `hit_histogram.${ext}`;
-    const correlationName = `correlation.${ext}`;
-    const componentNames = features.map((f, i) => `component_${i + 1}_${f.replace(/[^a-zA-Z0-9_]/g, "_")}.${ext}`);
-    const allList = [combinedName, umatrixName, hitHistName, correlationName, ...componentNames];
-    if (figures === undefined || figures === "default") {
-        return includeIndividual ? allList : [combinedName];
-    }
-    if (figures === "combined_only")
-        return [combinedName];
-    if (figures === "all")
-        return allList;
-    if (Array.isArray(figures)) {
-        const nameToFile = {
-            combined: combinedName,
-            umatrix: umatrixName,
-            hit_histogram: hitHistName,
-            correlation: correlationName,
-        };
-        features.forEach((_, i) => {
-            nameToFile[`component_${i + 1}`] = componentNames[i];
-        });
-        return figures
-            .map((key) => {
-            const k = key.trim().toLowerCase();
-            if (nameToFile[k])
-                return nameToFile[k];
-            if (key.includes("."))
-                return key;
-            return null;
-        })
-            .filter((f) => f != null);
-    }
-    return [combinedName];
-}
-// ---- 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 and inline images (combined view and all plots shown directly in chat).
-
-DOWNLOAD LINKS: Links to API-domain or presigned URLs may not work when clicked (MCP holds the API key, not the browser). Images are inlined. For weights use get_job_export(export="weights"); for node stats use get_job_export(export="nodes"). If the user wants to save a file, offer to fetch via the appropriate tool.
-
-OPTIONS:
-- figures: request specific plots only. Omit for default (combined only; or all if include_individual=true).
-  - "combined_only": only the combined view.
-  - "all": combined + umatrix + hit_histogram + all component planes.
-  - Array of logical names: e.g. figures: ["umatrix"] for just the U-matrix, or figures: ["combined","hit_histogram","correlation"] or ["combined","umatrix","component_1","component_2"]. Logical names: combined, umatrix, hit_histogram, correlation, component_1, component_2, ... (component_N = Nth feature). Pass an array to fetch/save only those figures.
-- include_individual=true: when figures is omitted, shows each component plane, U-matrix, and hit histogram
-  as separate inline images. Ignored when figures is set.
-
-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.
-Request specific figures with get_results(job_id, figures=[...]) (e.g. figures: ["umatrix"] or figures: ["combined","hit_histogram"]) or run analyze(job_id, analysis_type) for a single view.
-Use get_job_export(export="training_log") for the learning curve (QE vs epoch — healthy=steady decline then plateau).
-Use analyze(job_id, "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"),
-    figures: z
-        .union([
-        z.enum(["default", "combined_only", "all"]),
-        z.array(z.string()),
-    ])
-        .optional()
-        .describe("Which figures to return. Omit or 'default' for combined only (or all if include_individual=true). 'combined_only': just combined view. 'all': combined + umatrix + hit_histogram + correlation + all component planes. Or array of logical names to fetch only those: combined, umatrix, hit_histogram, correlation, component_1, component_2, ..."),
-    include_individual: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe("If true and figures is omitted, inline each individual plot (component planes, u-matrix, hit histogram). Ignored when figures is set."),
-}, async ({ job_id, figures, include_individual }) => {
-    const data = (await apiCall("GET", `/v1/results/${job_id}`));
-    const summary = (data.summary ?? {});
-    const downloadUrls = (data.download_urls ?? {});
-    const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
-    const resultsHeader = jobLabel
-        ? `Results for ${jobLabel} (job_id: ${job_id})`
-        : `Results for job_id: ${job_id}`;
-    const content = [];
-    const inlinedImages = new Set();
-    const jobType = summary.job_type ?? "train_som";
-    // ── Dispatch by job type ──────────────────────────────────────────────────
-    const fmtExt = summary.output_format ?? "pdf";
-    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 ${resultsHeader}`,
-                `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"),
-        });
-        for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-            await tryAttachImage(content, job_id, name);
-            inlinedImages.add(name);
-        }
-    }
-    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}) — ${resultsHeader}`,
-                `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"),
-        });
-        for (const name of getResultsImagesToFetch(jobType, summary, figures, include_individual)) {
-            await tryAttachImage(content, job_id, name);
-            inlinedImages.add(name);
-        }
-    }
-    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 ${resultsHeader}`,
-            `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_job_export(export="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 and quality_report; get_job_export(export="training_log") for learning curves.`,
-        ]
-            .filter((l) => l !== "")
-            .join("\n");
-        content.push({ type: "text", text: textSummary });
-        const imgExt = summary.output_format ?? "pdf";
-        const imagesToFetch = getResultsImagesToFetch(jobType, summary, figures, include_individual);
-        for (const name of imagesToFetch) {
-            await tryAttachImage(content, job_id, name);
-            inlinedImages.add(name);
-        }
-    }
-    // Inline remaining image files; for JSON provide tool hints (no clickable URLs — auth required)
-    const files = summary.files ?? [];
-    const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
-    for (const fname of files) {
-        if (isImage(fname) && !inlinedImages.has(fname)) {
-            await tryAttachImage(content, job_id, fname);
-        }
-        else if (fname.endsWith(".json")) {
-            const hint = fname === "weights.json"
-                ? `Use get_job_export(export="weights") for full weight matrix including node_coords.`
-                : fname === "node_stats.json"
-                    ? `Use get_job_export(export="nodes") for per-node statistics.`
-                    : fname === "summary.json"
-                        ? null
-                        : `Use get_job_export for structured data (weights or nodes).`;
-            if (hint) {
-                content.push({ type: "text", text: `${fname}: ${hint}` });
-            }
-        }
-    }
-    // List available artifacts so the LLM can offer to fetch specific views
-    if (files.length > 0) {
-        const features = summary.features ?? [];
-        const logicalNames = jobType === "train_som" || jobType === "render_variant"
-            ? `Logical names: combined, umatrix, hit_histogram, correlation, ${features.map((_, i) => `component_${i + 1}`).join(", ")}. `
-            : "";
-        content.push({
-            type: "text",
-            text: `Available to fetch individually: ${files.join(", ")}. ${logicalNames}Use get_results(job_id, figures=[...]) to request specific plots, get_results(job_id, include_individual=true) or figures="all" to inline all plots, or analyze(job_id, analysis_type) for a specific view (u_matrix, component_planes, bmu_hits, clusters, quality_report, etc.).`,
-        });
-    }
-    return { content };
-});
-// ---- recolor_som ----
-server.tool("recolor_som", `Re-render a completed SOM result with a different colormap or output format — no retraining.
-
-Use when the user wants to see the same combined (or other) plot with another color scheme (e.g. plasma, inferno, coolwarm). You can also use this to re-export figures in a different format (e.g. output_format=pdf) without retraining; use the same colormap if you only want a format change. Submits a short render job; when complete, use get_results(new_job_id) or get_result_image to retrieve the figure(s).
-
-Colormaps (default: coolwarm): e.g. viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix and cyclic panels keep fixed colormaps (grays, twilight).`, {
-    job_id: z.string().describe("Job ID of a completed SOM training job (parent)"),
-    colormap: z.string().describe("Colormap name (default: coolwarm). E.g. viridis, plasma, inferno, magma, coolwarm)"),
-    figures: z
-        .array(z.string())
-        .optional()
-        .default(["combined"])
-        .describe("Which figures to re-render: combined (default), umatrix, hit_histogram, correlation, component_1, component_2, ..."),
-    output_format: z.enum(["png", "pdf", "svg"]).optional().default("pdf"),
-    output_dpi: z.number().int().min(1).max(4).optional().default(2),
-}, async ({ job_id, colormap, figures, output_format, output_dpi }) => {
-    const body = { colormap, figures, output_format, output_dpi };
-    const data = (await apiCall("POST", `/v1/results/${job_id}/render`, JSON.stringify(body), {
-        "Content-Type": "application/json",
-    }));
-    const newJobId = data.id;
-    const content = [
-        {
-            type: "text",
-            text: [
-                `Re-render job submitted with colormap "${colormap}".`,
-                `New job_id: ${newJobId}. Poll get_job_status(job_id="${newJobId}") until status is 'completed', then use get_results(job_id="${newJobId}") or get_result_image to retrieve the recolored plot(s). No retraining was performed.`,
-            ].join("\n"),
-        },
-    ];
-    return { content };
-});
-// ---- download_results ----
-server.tool("download_results", `Save result figures (and optionally JSON) to a folder on disk. Use so the user can open, share, or version files locally without writing their own download script.
-
-folder: path to the directory (e.g. "." for current/workspace, "./results", or absolute path). When folder is a generic path like "." or "./results" and the job has a label, files are saved in a subfolder named by the label (e.g. ./results/Winedata_a1b2c3_badger_thong_oil). You can also pass a path that already includes the label.
-figures: "all" (default) = all image files from the job; "images" = same; or pass an array of filenames to save only those (e.g. ["combined.pdf", "umatrix.pdf", "correlation.pdf"]). Default export format is PDF.
-include_json: if true, also save summary.json (and other JSON artifacts) into the same folder.`, {
-    job_id: z.string().describe("Job ID of a completed job"),
-    folder: z.string().describe("Directory path to save files (e.g. '.' or './results'). When the job has a label, a subfolder with that label may be used. Relative paths are relative to process cwd (usually project root)."),
-    figures: z
-        .union([z.enum(["all", "images"]), z.array(z.string())])
-        .optional()
-        .default("all")
-        .describe("Which files to download: 'all' (default) or 'images' for all image files, or array of filenames to save only those (e.g. ['combined.pdf', 'umatrix.pdf', 'correlation.pdf'])."),
-    include_json: z.boolean().optional().default(false).describe("If true, also download summary.json and other JSON files"),
-}, async ({ job_id, folder, figures, include_json }) => {
-    const data = (await apiCall("GET", `/v1/results/${job_id}`));
-    const summary = (data.summary ?? {});
-    const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
-    const files = summary.files ?? [];
-    const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
-    const isJson = (f) => f.endsWith(".json");
-    let toDownload;
-    if (figures === "all" || figures === "images") {
-        toDownload = include_json ? files : files.filter(isImage);
-    }
-    else {
-        toDownload = figures;
-        if (include_json && !toDownload.includes("summary.json")) {
-            toDownload = [...toDownload, "summary.json"];
-        }
-    }
-    let resolvedDir = path.resolve(folder);
-    const useLabelSubfolder = jobLabel &&
-        (folder === "." || folder === "./results" || folder === "results");
-    if (useLabelSubfolder) {
-        resolvedDir = path.join(resolvedDir, jobLabel);
-    }
-    await fs.mkdir(resolvedDir, { recursive: true });
-    const saved = [];
-    for (const filename of toDownload) {
-        try {
-            const { data: buf } = await apiRawCall(`/v1/results/${job_id}/image/${filename}`);
-            const outPath = path.join(resolvedDir, filename);
-            await fs.writeFile(outPath, buf);
-            saved.push(filename);
-        }
-        catch {
-            // Skip missing or failed files
-        }
-    }
-    const text = saved.length > 0
-        ? `Saved ${saved.length} file(s) to ${resolvedDir}: ${saved.join(", ")}`
-        : `No files saved (job may have no matching files or download failed). Check job_id and that the job is completed.`;
-    return { content: [{ type: "text", text }] };
-});
-// ---- analyze ----
-server.tool("analyze", `Run a specific analysis on SOM results. Use after get_results to drill into aspects.
-Request specific plots: get_results(job_id, figures=[...]) for chosen figures (e.g. figures: ["umatrix"]) or analyze(job_id, analysis_type) for a single analysis view.
-
-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?"
-  quality_report    — Comprehensive quality report: QE, TE, silhouette, trustworthiness,
-                      neighborhood preservation, topographic product, and recommendations.
-
-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",
-        "quality_report",
-    ])
-        .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 ?? "pdf";
-    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}`);
-    }
-    else if (analysis_type === "quality_report") {
-        const qrData = (await apiCall("GET", `/v1/results/${job_id}/quality-report`));
-        const std = qrData.standard_metrics ?? {};
-        const clust = qrData.cluster_metrics ?? {};
-        const topo = qrData.topology_metrics ?? {};
-        const train = qrData.training ?? {};
-        const qrGrid = qrData.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;
-        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 qrLines = [
-            `Quality Report — Job ${job_id}`,
-            `Grid: ${qrGrid[0]}×${qrGrid[1]} | Model: ${qrData.model ?? "SOM"} | Samples: ${qrData.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}`),
-        ];
-        content.push({ type: "text", text: qrLines.join("\n") });
-    }
-    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") }],
-    };
-});
-// ---- manage_job ----
-server.tool("manage_job", `Cancel or delete a job.
-
-action=cancel: Cancel a pending or running job. Not instant — worker checks between phases (expect up to 30s). Use when run is too slow, wrong params, or to free the worker. Partial results discarded.
-action=delete: Permanently delete a job and all S3 result files. Use to free storage, remove test runs, or clean up after cancel. WARNING: Job ID will no longer work with get_results or other tools.`, {
-    job_id: z.string().describe("Job ID to cancel or delete"),
-    action: z
-        .enum(["cancel", "delete"])
-        .describe("cancel: stop the job; delete: remove job and all result files"),
-}, async ({ job_id, action }) => {
-    if (action === "cancel") {
-        const data = await apiCall("POST", `/v1/jobs/${job_id}/cancel`);
-        return textResult(data);
-    }
-    const data = await apiCall("DELETE", `/v1/jobs/${job_id}`);
-    return textResult(data);
-});
-// ---- list ----
-server.tool("list", `List datasets or jobs.
-
-type=datasets: List all datasets uploaded by the organization. Use to check what data is available before train_som or to find dataset IDs.
-type=jobs: List SOM training jobs (optionally filtered by dataset_id). Use to find job IDs for compare_runs, check completed vs pending, or review hyperparameters.`, {
-    type: z
-        .enum(["datasets", "jobs"])
-        .describe("What to list: datasets or jobs"),
-    dataset_id: z
-        .string()
-        .optional()
-        .describe("Filter jobs by dataset ID (only used when type=jobs)"),
-}, async ({ type, dataset_id }) => {
-    if (type === "datasets") {
-        const data = await apiCall("GET", "/v1/datasets");
-        return textResult(data);
-    }
-    const path = dataset_id
-        ? `/v1/jobs?dataset_id=${dataset_id}`
-        : "/v1/jobs";
-    const data = (await apiCall("GET", path));
-    if (type === "jobs" && Array.isArray(data)) {
-        const lines = data.map((job) => {
-            const id = String(job.id ?? "");
-            const status = String(job.status ?? "");
-            const label = job.label != null && job.label !== "" ? String(job.label) : null;
-            return label
-                ? `${label} (id: ${id}) — status: ${status}`
-                : `id: ${id} — status: ${status}`;
-        });
-        const text = lines.length > 0 ? lines.join("\n") : "No jobs found.";
-        return { content: [{ type: "text", text }] };
-    }
-    return textResult(data);
-});
-// ---- get_job_export ----
-server.tool("get_job_export", `Export structured data from a completed SOM training job.
-
-export=training_log: Learning curve and diagnostics (per-epoch QE, sparklines, inline plot). Use to diagnose convergence, plateau, or divergence.
-export=weights: Raw weight matrix with node_coords, normalized/denormalized values, normalization stats. Use for external analysis or custom visualizations. Can be large (e.g. 600KB+ for 30×30×12).
-export=nodes: Per-node statistics (hit count, feature mean/std). Use to profile clusters and characterize operating modes.`, {
-    job_id: z.string().describe("Job ID of a completed training job"),
-    export: z
-        .enum(["training_log", "weights", "nodes"])
-        .describe("What to export: training_log, weights, or nodes"),
-}, async ({ job_id, export: exportType }) => {
-    if (exportType === "training_log") {
-        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") },
-        ];
-        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 };
-    }
-    if (exportType === "weights") {
-        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}`,
-            `node_coords: [x,y] per node for topology`,
-            `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 (includes node_coords).`, `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) },
-            ],
-        };
-    }
-    // exportType === "nodes"
-    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. For formula-based variables from the training dataset,
-prefer derive_variable with project_onto_job; use project_variable only for
-externally computed arrays.
-NOT FOR: Re-training or adding features to the map.
-
-TIMING: ~5–15s (loads cached SOM, computes per-node aggregation, renders plot).
-
-values: array of length n_samples (~11 bytes/sample). Must match training sample
-count exactly (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
-
-HINT: If values length mismatch, suggest derive_variable for formula-based variables.`, {
-    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("pdf")
-        .describe("Image output format for the projection plot (default: pdf)."),
-    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: coolwarm). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral."),
-}, 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",
-        output_format: output_format ?? "pdf",
-    };
-    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 ?? "pdf";
-        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.
-
-**Requires time-ordered data.** Each row must represent a consecutive observation;
-the transition from row i to row i+lag is counted. If rows are not time-ordered,
-results will be meaningless.
-
-Best used for:
-- **Time-series dynamics**: how does the system state evolve step-by-step?
-- **Cyclic processes**: daily/weekly patterns, recurring operating modes
-- **Process monitoring**: identify common transition paths and bottlenecks
-- **Regime detection**: find absorbing states (nodes with self-loops) vs transient hubs
-
-**lag** controls the temporal horizon:
-- lag=1 (default): immediate next-step transitions — "where does the system go next?"
-- lag=N: transitions N steps apart — useful for periodic analysis (e.g. lag=24 for daily cycles in hourly data)
-- Try multiple lags to reveal different temporal scales.
-
-**min_transitions** filters noisy arrows — only transitions observed at least this many times are drawn. Increase for cleaner plots on large datasets.
-
-**top_k** controls how many top-flow nodes are reported in statistics.
-
-BEFORE calling, confirm:
-- Data is time-ordered (chronological row sequence)
-- The lag makes sense for the time resolution (e.g. lag=1 for hourly data = 1 hour ahead)
-
-After showing results, discuss:
-- Arrow direction and clustering patterns
-- Hub nodes (many transitions through them) vs absorbing nodes (self-loops)
-- Whether cyclic flow matches known periodic behavior`, {
-    job_id: z.string().describe("ID of the completed SOM training job"),
-    lag: z
-        .number()
-        .int()
-        .min(1)
-        .optional()
-        .default(1)
-        .describe("Step lag for transition pairs (default 1 = consecutive rows). Use larger values for periodic analysis (e.g. 24 for daily cycles in hourly data)."),
-    min_transitions: z
-        .number()
-        .int()
-        .min(1)
-        .optional()
-        .describe("Minimum transition count to draw an arrow (default: auto). Increase to filter noise on large datasets."),
-    top_k: z
-        .number()
-        .int()
-        .min(1)
-        .optional()
-        .default(10)
-        .describe("Number of top-flow nodes to include in statistics (default 10)."),
-    colormap: z
-        .string()
-        .optional()
-        .describe("Colormap for the U-matrix background (default: grays). Try viridis, plasma, or inferno for more contrast."),
-    output_format: z
-        .enum(["png", "pdf", "svg"])
-        .optional()
-        .default("pdf")
-        .describe("Image output format for the flow plot (default: pdf)."),
-    output_dpi: z
-        .enum(["standard", "retina", "print"])
-        .optional()
-        .default("retina")
-        .describe("Resolution: standard (1x), retina (2x), print (4x)."),
-}, async ({ job_id, lag, min_transitions, top_k, colormap, output_format, output_dpi }) => {
-    const dpiMap = { standard: 1, retina: 2, print: 4 };
-    const body = { lag: lag ?? 1, output_format: output_format ?? "pdf" };
-    if (min_transitions !== undefined)
-        body.min_transitions = min_transitions;
-    if (top_k !== undefined)
-        body.top_k = top_k;
-    if (colormap !== undefined)
-        body.colormap = colormap;
-    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 ?? "pdf";
-        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.
-
-EXPRESSION REFERENCE: In expressions, use underscore-normalized column names (e.g. fixed_acidity not "fixed acidity"). Column names with spaces/special chars are converted to underscores — use that form. Operators: +, -, *, /, ^. Functions: log, sqrt, rolling_mean(col, window), diff(col), etc.
-
-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
-- Spaces in column names: use underscores (e.g. fixed_acidity not "fixed acidity")`, {
-    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("pdf")
-        .describe("Image format for projection visualization when project_onto_job is set (default: pdf)."),
-    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: coolwarm). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral."),
-}, 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",
-            output_format: output_format ?? "pdf",
-        };
-        if (options)
-            body.options = options;
-        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 ?? "pdf";
-            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 datasets(action=preview) 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}")`,
-                }],
-        };
-    }
-});
-// ---- Compute Leases / Account Management ----
-server.tool("manage_account", `Manage compute leases, check account status, and view billing history.
-Your default backend is your local Primary Server. Use this tool to temporarily upgrade to cloud compute for heavy jobs.
-
-Actions:
-- request_compute: Provisions a cloud burst instance (requires tier and duration_minutes). Leaves tier blank to list options.
-- compute_status: Checks if a burst lease is active and how much time remains.
-- release_compute: Manually terminates an active lease and reverts routing to the Primary Server.
-- compute_history: Views recent compute leases and credit spend.
-- add_funds: Instructions on how to add credits to your account.`, {
-    action: {
-        type: "string",
-        description: "One of: request_compute, compute_status, release_compute, compute_history, add_funds",
-    },
-    tier: {
-        type: "string",
-        description: "Compute tier ID (e.g., cpu-8, gpu-t4). Leave empty during request_compute to list tiers.",
-        optional: true,
-    },
-    duration_minutes: {
-        type: "number",
-        description: "How long to lease the instance (default: 60)",
-        optional: true,
-    },
-    limit: {
-        type: "number",
-        description: "Number of records to fetch for compute_history (default: 10)",
-        optional: true,
-    }
-}, async ({ action, tier, duration_minutes, limit }) => {
-    if (action === "request_compute") {
-        if (!tier) {
-            return {
-                content: [{ type: "text", text: `Available Compute Tiers:
-CPU Tiers:
-  cpu-8: 16 vCPUs, 32 GB RAM (~$0.20/hr)
-  cpu-16: 32 vCPUs, 64 GB RAM (~$0.20/hr)
-  cpu-24: 48 vCPUs, 96 GB RAM (~$0.28/hr)
-  cpu-32: 64 vCPUs, 128 GB RAM (~$0.42/hr)
-  cpu-48: 96 vCPUs, 192 GB RAM (~$0.49/hr)
-GPU Tiers:
-  gpu-t4: 8 vCPUs, 32 GB, T4 16GB VRAM (~$0.22/hr)
-  gpu-t4x: 16 vCPUs, 64 GB, T4 16GB VRAM (~$0.36/hr)
-  gpu-t4xx: 32 vCPUs, 128 GB, T4 16GB VRAM (~$0.27/hr)
-  gpu-l4: 8 vCPUs, 32 GB, L4 24GB VRAM (~$0.41/hr)
-  gpu-l4x: 16 vCPUs, 64 GB, L4 24GB VRAM (~$0.37/hr)
-  gpu-a10: 8 vCPUs, 32 GB, A10G 24GB VRAM (~$0.51/hr)
-  gpu-a10x: 16 vCPUs, 64 GB, A10G 24GB VRAM (~$0.52/hr)` }]
-            };
-        }
-        const data = await apiCall("POST", "/v1/compute/lease", { tier, duration_minutes });
-        return {
-            content: [{ type: "text", text: `Compute Lease Requested:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Estimated Wait: ${data.estimated_wait_minutes} minutes
-Estimated Cost: $${(data.estimated_cost_cents / 100).toFixed(2)}
-Credits Remaining After Reserve: $${(data.credit_balance_cents / 100).toFixed(2)}
-
-IMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.` }]
-        };
-    }
-    if (action === "compute_status") {
-        const data = await apiCall("GET", "/v1/compute/lease");
-        if (data.status === "none" || !data.lease_id) {
-            return { content: [{ type: "text", text: "No active lease -- running on default Primary Server." }] };
-        }
-        return {
-            content: [{ type: "text", text: `Active Compute Lease:
-Lease ID: ${data.lease_id}
-Status: ${data.status}
-Tier: ${data.tier} (${data.instance_type})
-Time Remaining: ${Math.round(data.time_remaining_ms / 60000)} minutes` }]
-        };
-    }
-    if (action === "release_compute") {
-        const data = await apiCall("DELETE", "/v1/compute/lease");
-        return {
-            content: [{ type: "text", text: `Compute Released:
-Duration Billed: ${data.duration_minutes} minutes
-Credits Deducted: $${(data.credits_deducted / 100).toFixed(2)}
-Final Balance: $${(data.final_balance_cents / 100).toFixed(2)}
-
-Routing reverted to default Primary Server.` }]
-        };
-    }
-    if (action === "compute_history") {
-        const data = await apiCall("GET", `/v1/compute/history?limit=${limit || 10}`);
-        const history = data.history.map((h) => `- ${h.started_at} | ${h.tier} | ${h.duration_minutes} min | $${(h.credits_charged / 100).toFixed(2)}`).join("\n");
-        return {
-            content: [{ type: "text", text: `Credit Balance: $${(data.credit_balance_cents / 100).toFixed(2)}\n\nRecent Usage:\n${history}` }]
-        };
-    }
-    if (action === "add_funds") {
-        return {
-            content: [{ type: "text", text: `To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:
-bash scripts/manage-credits.sh add <org_id> <amount_usd>` }]
-        };
-    }
-    return {
-        content: [{ type: "text", text: `Unknown action: ${action}. Valid actions are request_compute, compute_status, release_compute, compute_history, add_funds.` }]
-    };
-});
-// ---- license_info ----
-server.tool("license_info", `Get plan/license capabilities, backend info, live status, and training time estimates.
-
-Returns what the current API key is connected to: plan tier, compute class
-(CPU/GPU), usage limits, backend hardware details, job queue state, and
-estimated training times.
-
-Use this BEFORE submitting large jobs to:
-- See your plan's compute class and whether GPU is available
-- Check queue depth to decide whether to wait or proceed
-- Estimate wall-clock time based on the current topology`, {}, async () => {
-    const data = (await apiCall("GET", "/v1/system/info"));
-    const plan = data.plan ?? {};
-    const backend = data.backend ?? {};
-    const status = data.status ?? {};
-    const estimates = data.training_time_estimates_seconds ?? {};
-    const topo = data.worker_topology ?? {};
-    const gpuEnabled = plan.gpu_enabled ?? data.gpu_available ?? false;
-    const computeDesc = gpuEnabled
-        ? backend.gpu_model
-            ? `GPU-accelerated (${backend.gpu_model}${backend.gpu_vram_gb ? `, ${backend.gpu_vram_gb} GB VRAM` : ""})`
-            : "GPU-accelerated"
-        : "CPU only";
-    const fmtLimit = (v) => v === -1 || v === "-1" ? "unlimited" : String(v ?? "?");
-    const leaseData = await apiCall("GET", "/v1/compute/lease").catch(() => null);
-    const historyData = await apiCall("GET", "/v1/compute/history?limit=30").catch(() => null);
-    const lines = [
-        `Your Plan: ${String(plan.tier ?? "unknown").charAt(0).toUpperCase()}${String(plan.tier ?? "unknown").slice(1)}`,
-        `  Priority:      ${plan.priority ?? "normal"}`,
-        `  Concurrency:   ${plan.max_concurrent_jobs ?? "?"} simultaneous job${plan.max_concurrent_jobs !== 1 ? "s" : ""}`,
-        `  Datasets:      ${fmtLimit(plan.max_datasets)} max, ${fmtLimit(plan.max_dataset_rows)} rows each`,
-        `  Monthly Jobs:  ${fmtLimit(plan.max_monthly_jobs)}`,
-        `  Grid Size:     ${fmtLimit(plan.max_grid_size)} max`,
-        `  Features:      ${fmtLimit(plan.max_features)} max`,
-    ];
-    if (historyData) {
-        lines.push(``, `Compute Credits:  $${(historyData.credit_balance_cents / 100).toFixed(2)} remaining`);
-    }
-    lines.push(``, `Default Backend:`, `  Label:         ${backend.label ?? "unknown"}`, `  Compute:       ${computeDesc}`);
-    if (backend.memory_gb)
-        lines.push(`  Memory:        ${backend.memory_gb} GB`);
-    if (leaseData && leaseData.lease_id) {
-        lines.push(``, `Active Compute Lease (Burst):`, `  Status:        ${leaseData.status}`, `  Tier:          ${leaseData.tier} (${leaseData.instance_type})`, `  Time Left:     ${Math.round(leaseData.time_remaining_ms / 60000)} min`);
-    }
-    const running = Number(status.running_jobs ?? data.running_jobs ?? 0);
-    const pending = Number(status.pending_jobs ?? data.pending_jobs ?? 0);
-    const queueDepth = Number(status.queue_depth ?? data.queue_depth ?? 0);
-    const freeMem = status.free_memory_gb ?? data.free_memory_gb;
-    const compute_eta = Number(data.training_time_estimates_seconds?.total || 0);
-    const final_eta_seconds = (pending + 1) * compute_eta;
-    lines.push(``, `Live Status:`, `  Running Jobs:  ${running}`, `  Pending Jobs:  ${pending}`, `  Queue Depth:   ${queueDepth}`, `  Current Wait:  ~${Math.round(final_eta_seconds / 60)} minutes (before your job starts)`);
-    if (freeMem !== undefined)
-        lines.push(`  Free Memory:   ${freeMem} GB`);
-    if (topo.num_workers !== undefined) {
-        lines.push(``, `Worker Topology:`, `  Workers:             ${topo.num_workers} × ${topo.threads_per_worker} threads`, `  Total Thread Budget: ${topo.total_thread_budget}`);
-    }
-    if (Object.keys(estimates).length > 0) {
-        lines.push(``, `Estimated Training Times (seconds):`, ...Object.entries(estimates)
-            .filter(([k]) => k !== "formula")
-            .map(([k, v]) => `  ${k}: ~${v}s`));
-        if (estimates.formula)
-            lines.push(`  ${estimates.formula}`);
-    }
-    return {
-        content: [{ type: "text", text: lines.join("\n") }],
-    };
-});
-// ---------------------------------------------------------------------------
-// Prompts
-// ---------------------------------------------------------------------------
-server.prompt("info", "Overview of the Barivia SOM MCP: capabilities, workflow, tools, analysis types, and tips. Use when the user asks what this MCP can do, how to get started, or what the process is.", {}, () => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: [
-                    "Inform the user using this overview:",
-                    "",
-                    "**What it is:** Barivia MCP connects you to a Self-Organizing Map (SOM) analytics engine. SOMs learn a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.",
-                    "",
-                    "**Core workflow:**",
-                    "1. **Upload** — `datasets(action=upload)` with a CSV file path or inline data",
-                    "2. **Preview** — `datasets(action=preview)` to inspect columns, stats, and detect cyclic/datetime fields",
-                    "3. **Prepare** — use the `prepare_training` prompt for a guided checklist (column selection, transforms, cyclic encoding, feature weights, grid sizing)",
-                    "4. **Train** — `train_som` with grid size, epochs, model type, and preprocessing options. Use `preset=quick|standard|refined|high_res` for sensible defaults",
-                    "5. **Monitor** — `get_job_status` to track progress; `get_results` to retrieve figures when complete",
-                    "6. **Analyze** — `analyze` with various analysis types (see below)",
-                    "7. **Iterate** — `recolor_som` to change colormap without retraining, `compare_runs` to compare hyperparameters, `project_variable` to overlay new variables",
-                    "",
-                    "**Analysis types** (via `analyze`):",
-                    "- `u_matrix` — cluster boundary distances",
-                    "- `component_planes` — per-feature heatmaps",
-                    "- `clusters` — automatic cluster detection and statistics",
-                    "- `quality_report` — QE, TE, explained variance, trustworthiness, neighborhood preservation",
-                    "- `hit_histogram` — data density across the map",
-                    "- `transition_flow` — temporal flow patterns (requires time-ordered data)",
-                    "",
-                    "**Data tools:**",
-                    "- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter",
-                    "- `derive_variable` — create computed columns from expressions (ratios, differences, etc.)",
-                    "- `project_variable` — overlay any variable onto a trained SOM",
-                    "",
-                    "**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, etc.) can be set at training or changed later via recolor_som.",
-                    "",
-                    "**Key tools:** datasets, list, train_som, get_job_status, get_results, analyze, recolor_som, download_results, project_variable, transition_flow, compare_runs, derive_variable, license_info, explore_som.",
-                    "",
-                    "**Tips:**",
-                    "- Always `preview` before training to understand your data",
-                    "- Use `license_info` to check GPU availability and plan limits before large jobs",
-                    "- Start with `preset=quick` for fast iteration, then `refined` for publication quality",
-                    "- For time-series data, consider `transition_flow` after training",
-                    "",
-                    "Keep the reply scannable with headers and bullet points.",
-                ].join("\n"),
-            },
-        },
-    ],
-}));
-server.prompt("prepare_training", "Guided pre-training checklist. Use after uploading a dataset and before calling train_som. " +
-    "Walks through data inspection, column selection, transforms, cyclic/temporal features, weighting, subsetting, and grid sizing.", { dataset_id: 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.`,
-                    "",
-                    "Start by calling datasets(action=preview, dataset_id=\"" + dataset_id + "\") to show the columns, statistics, and detected cyclic/datetime fields. Then walk through each step below, asking for my choices at each stage. When all choices are made, present the final train_som call and offer to submit.",
-                    "",
-                    "**Step 1: DATA INSPECTION**",
-                    "Show the preview output: column names, types, basic stats (min/max/mean/std), sample rows. Flag anything unusual:",
-                    "- Columns with many missing values or zero variance",
-                    "- Highly skewed distributions (consider transforms)",
-                    "- ID-like or categorical columns that shouldn't be trained on",
-                    "- Columns the preview flags as cyclic or datetime candidates",
-                    "",
-                    "**Step 2: SUBSETTING** (optional)",
-                    "Does the user want to train on a subset? Options:",
-                    "- Row range: datasets(action=subset, row_range=[start, end]) for first N rows or a specific slice",
-                    "- Value filters: datasets(action=subset, filters=[{column, op, value}]) — ops: eq, ne, gt, lt, gte, lte, between, in",
-                    "- Or pass row_range directly in train_som params for lightweight slicing",
-                    "",
-                    "**Step 3: COLUMN SELECTION**",
-                    "Which columns to include? Exclude IDs, free text, constants, or redundant features. → train_som param: columns",
-                    "",
-                    "**Step 4: TRANSFORMS**",
-                    "Any right-skewed or heavy-tailed columns? Available transforms (applied BEFORE normalization):",
-                    "- log: natural log (requires >0; use for prices, revenues, volumes)",
-                    "- log1p: log(1+x) (safe for zeros; counts, frequencies)",
-                    "- sqrt: square root (mild skew correction)",
-                    "- rank: replace with rank order (non-parametric; heavy outliers)",
-                    "- invert: 1/x (reciprocal relationship)",
-                    "→ train_som param: transforms, e.g. { revenue: 'log', count: 'log1p' }",
-                    "",
-                    "**Step 5: CYCLIC FEATURES**",
-                    "Any periodic variables (hour 0–24, weekday 0–6, month 1–12, angle 0–360)?",
-                    "These MUST be encoded as (cos, sin) pairs so the SOM sees 23:00 and 01:00 as close.",
-                    "→ train_som param: cyclic_features, e.g. [{ feature: 'hour', period: 24 }]",
-                    "",
-                    "**Step 6: TEMPORAL FEATURES**",
-                    "Any datetime columns? Extract components like hour_of_day, day_of_year, month, day_of_week.",
-                    "Preview shows auto-detected formats. NEVER add temporal_features without user confirmation.",
-                    "→ train_som param: temporal_features, e.g. [{ columns: ['Date'], format: 'yyyy-mm-dd', extract: ['month', 'day_of_week'], cyclic: true }]",
-                    "",
-                    "**Step 7: FEATURE WEIGHTS**",
-                    "Should any feature have more or less influence? weight=0 disables, >1 emphasizes, <1 de-emphasizes.",
-                    "Cyclic shorthand: { 'hour': 2.0 } auto-expands to both hour_cos and hour_sin.",
-                    "→ train_som param: feature_weights, e.g. { temperature: 2.0, noise_col: 0.5 }",
-                    "",
-                    "**Step 8: GRID, MODEL & HYPERPARAMETERS**",
-                    "- Presets: quick (15×15), standard (25×25), refined (40×40), high_res (60×60)",
-                    "- Or explicit: grid_x, grid_y, epochs (single int or [ordering, convergence])",
-                    "- Model: SOM (standard), RSOM (recurrent/time-series), SOM-SOFT (GTM-style), RSOM-SOFT",
-                    "- learning_rate: number (e.g. 0.05) or { ordering: [start, end], convergence: [start, end] }",
-                    "- sigma_f: final neighborhood radius (lower = sharper clusters, default 1.0)",
-                    "- output_format: pdf (vector), png, svg. colormap: coolwarm, viridis, plasma, etc.",
-                    "- Check license_info for GPU availability before large grids",
-                    "",
-                    "**Final: REVIEW & SUBMIT**",
-                    "Summarize all chosen parameters as a complete train_som call. Show the full param set and confirm before submitting.",
-                ].join("\n"),
-            },
-        },
-    ],
-}));
-// ---------------------------------------------------------------------------
-// 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
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{registerAppResource as a,registerAppTool as r,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import i from"node:fs/promises";import s from"node:path";const l=process.env.BARIVIA_API_URL??process.env.BARSOM_API_URL??"https://api.barivia.se",u=process.env.BARIVIA_API_KEY??process.env.BARSOM_API_KEY??"";u||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const d=parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS??"30000",10),c=new Set([502,503,504]);function p(e,t){return!(void 0===t||!c.has(t))||(e instanceof DOMException&&"AbortError"===e.name||e instanceof TypeError)}async function m(e,t,o=d){const a=new AbortController,r=setTimeout(()=>a.abort(),o);try{return await fetch(e,{...t,signal:a.signal})}finally{clearTimeout(r)}}async function g(e,t,o,a){const r=`${l}${t}`,n=a?.["Content-Type"]??"application/json",i=Math.random().toString(36).slice(2,10),s={Authorization:`Bearer ${u}`,"Content-Type":n,"X-Request-ID":i,...a};let d,c;void 0!==o&&(d="application/json"===n?JSON.stringify(o):String(o));for(let t=0;t<=2;t++)try{const o=await m(r,{method:e,headers:s,body:d}),a=await o.text();if(!o.ok){if(t<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}const e=(()=>{try{return JSON.parse(a)}catch{return null}})(),r=e?.error??a,n=400===o.status?" Check parameter types and required fields.":404===o.status?" The resource may not exist or may have been deleted.":409===o.status?" The job may not be in the expected state.":429===o.status?" Rate limit exceeded — wait a moment and retry.":"";throw new Error(`${r}${n}`)}return JSON.parse(a)}catch(e){if(c=e,t<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**t));continue}throw e}throw c}async function f(e){const t=`${l}${e}`;let o;for(let a=0;a<=2;a++)try{const o=await m(t,{method:"GET",headers:{Authorization:`Bearer ${u}`}});if(!o.ok){if(a<2&&p(null,o.status)){await new Promise(e=>setTimeout(e,1e3*2**a));continue}throw new Error(`API GET ${e} returned ${o.status}`)}const r=await o.arrayBuffer();return{data:Buffer.from(r),contentType:o.headers.get("content-type")??"application/octet-stream"}}catch(e){if(o=e,a<2&&p(e)){await new Promise(e=>setTimeout(e,1e3*2**a));continue}throw e}throw o}function h(e){return{content:[{type:"text",text:JSON.stringify(e,null,2)}]}}async function b(e,t=3e4,o=1e3){const a=Date.now();for(;Date.now()-a<t;){const t=await g("GET",`/v1/jobs/${e}`),a=t.status;if("completed"===a||"failed"===a||"cancelled"===a)return{status:a,result_ref:t.result_ref,error:t.error};await new Promise(e=>setTimeout(e,o))}return{status:"timeout"}}const _=new e({name:"analytics-engine",version:"0.4.0"}),y=import.meta.dirname??s.dirname(new URL(import.meta.url).pathname);async function w(e){const t=[s.join(y,"views","src","views",e,"index.html"),s.join(y,"views",e,"index.html"),s.join(y,"..","dist","views","src","views",e,"index.html")];for(const e of t)try{return await i.readFile(e,"utf-8")}catch{continue}return null}const v="ui://barsom/som-explorer",$="ui://barsom/data-preview",x="ui://barsom/training-monitor";function j(e,t,o,a){const r=t.output_format??"pdf";if("transition_flow"===e){return[`transition_flow_lag${t.lag??1}.${r}`]}if("project_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${r}`]}if("derive_variable"===e){const e=t.variable_name??"variable";return[`projected_${String(e).replace(/[^a-zA-Z0-9_]/g,"_")}.${r}`]}const n=t.features??[],i=`combined.${r}`,s=`umatrix.${r}`,l=`hit_histogram.${r}`,u=`correlation.${r}`,d=n.map((e,t)=>`component_${t+1}_${e.replace(/[^a-zA-Z0-9_]/g,"_")}.${r}`),c=[i,s,l,u,...d];if(void 0===o||"default"===o)return a?c:[i];if("combined_only"===o)return[i];if("all"===o)return c;if(Array.isArray(o)){const e={combined:i,umatrix:s,hit_histogram:l,correlation:u};return n.forEach((t,o)=>{e[`component_${o+1}`]=d[o]}),o.map(t=>{const o=t.trim().toLowerCase();return e[o]?e[o]:t.includes(".")?t:null}).filter(e=>null!=e)}return[i]}function S(e){return e.endsWith(".pdf")?"application/pdf":e.endsWith(".svg")?"image/svg+xml":"image/png"}async function T(e,t,o){try{const{data:a}=await f(`/v1/results/${t}/image/${o}`);e.push({type:"image",data:a.toString("base64"),mimeType:S(o),annotations:{audience:["user"],priority:.8}})}catch{e.push({type:"text",text:`(${o} not available for inline display)`})}}a(_,v,v,{mimeType:n},async()=>{const e=await w("som-explorer");return{contents:[{uri:v,mimeType:n,text:e??"<html><body>SOM Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),a(_,$,$,{mimeType:n},async()=>{const e=await w("data-preview");return{contents:[{uri:$,mimeType:n,text:e??"<html><body>Data Preview view not built yet.</body></html>"}]}}),a(_,x,x,{mimeType:n},async()=>{const e=await w("training-monitor");return{contents:[{uri:x,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),r(_,"explore_som",{title:"Explore SOM",description:"Interactive SOM explorer dashboard. Opens an inline visualization where you can toggle features, click nodes, and export figures. Use this after get_results for a richer, interactive exploration experience. Falls back to text+image on hosts that don't support MCP Apps.",inputSchema:{job_id:o.string().describe("Job ID of a completed SOM training job")},_meta:{ui:{resourceUri:v}}},async({job_id:e})=>{const t=await g("GET",`/v1/results/${e}`),o=t.summary??{},a=[];a.push({type:"text",text:JSON.stringify({job_id:e,summary:o,download_urls:t.download_urls})});const r=o.output_format??"pdf";return await T(a,e,`combined.${r}`),{content:a}}),_.tool("guide_barsom_workflow","Retrieve the Standard Operating Procedure (SOP) for the barSOM analysis pipeline.\nALWAYS call this tool first if you are unsure of the steps to execute a complete Self-Organizing Map analysis.\nThe workflow explains the exact sequence of tool calls needed: Upload → Preprocess → Train → Wait → Analyze.",{},async()=>({content:[{type:"text",text:"barSOM Standard Operating Procedure (SOP)\n\nStep 1: Upload Data\n- Use `datasets(action=upload)` with a local `file_path` to your CSV.\n- BEFORE UPLOADING: Clean the dataset to remove NaNs or malformed data.\n- Capture the `dataset_id` returned.\n\nStep 2: Preview & Preprocess\n- Use `datasets(action=preview)` to inspect columns, ranges, and types.\n- Check for skewed columns requiring 'log' or 'sqrt' transforms.\n- Check for cyclical or temporal features (hours, days) requiring `cyclic_features` or `temporal_features` during training.\n\nStep 3: Train the SOM\n- Call `train_som` with the `dataset_id`.\n- Carefully select columns to include (start with 5-10).\n- Assign `feature_weights` (especially for categorical data with natural hierarchies).\n- Wait for the returned `job_id`.\n\nStep 4: Wait for Completion (ASYNC POLLING)\n- Use `get_job_status` every 10-15 seconds.\n- Wait until status is \"completed\". DO NOT assume failure before 3 minutes (or longer for large grids).\n- If it fails, read the error message and adjust parameters (e.g., reduce grid size, fix column names).\n\nStep 5: Analyze and Export\n- Once completed, use `analyze(type=component_planes)` or `analyze(type=clusters)` to interpret the results.\n- Call `get_results` to get the final metrics (Quantization Error, Topographic Error)."}]})),_.tool("datasets",'Manage datasets: upload, preview, subset, or delete.\n\naction=upload: Upload a CSV for SOM analysis. Prefer file_path over csv_data so the MCP reads the file directly. Returns dataset ID and metadata. Then use datasets(action=preview) before train_som.\nBEFORE UPLOADING: Ensure data has no NaNs, missing values, or formats that can\'t be handled. The user/LLM is responsible for cleaning the dataset before upload. Categorical features should be weighted if there is a natural hierarchy.\naction=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train_som on an unfamiliar dataset.\naction=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range or filters.\n  - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)\n  - filters: array of conditions, ALL must match (AND logic). Each: { column, op, value }.\n    Operators:\n      eq     — exact match (string or number): { column: "region", op: "eq", value: "Europe" }\n      ne     — not equal: { column: "status", op: "ne", value: "error" }\n      in     — value in set: { column: "grade", op: "in", value: ["A", "B"] }\n      gt/lt  — above/below threshold: { column: "temp", op: "gt", value: 20 }\n      gte/lte — at or above/below: { column: "price", op: "gte", value: 100 }\n      between — closed interval [lo, hi]: { column: "age", op: "between", value: [18, 65] }\n  - Combine row_range + filters to slice both rows and values.\n  - Single filter object is also accepted (auto-wrapped).\naction=delete: Remove a dataset and free the slot.\n\nBEST FOR: Tabular numeric data. CSV with header required. Use list(type=datasets) to see existing datasets.',{action:o.enum(["upload","preview","subset","delete"]).describe("upload: add a CSV; preview: inspect before training; subset: create subset dataset; delete: remove dataset"),name:o.string().optional().describe("Dataset name (required for action=upload and subset)"),file_path:o.string().optional().describe("Path to local CSV (for upload; prefer over csv_data)"),csv_data:o.string().optional().describe("Inline CSV string (for upload; use for small data)"),dataset_id:o.string().optional().describe("Dataset ID (required for preview, subset, and delete)"),n_rows:o.number().int().optional().default(5).describe("Sample rows to return (preview only)"),row_range:o.tuple([o.number().int(),o.number().int()]).optional().describe("For subset: [start, end] 1-based inclusive row range (e.g. [1, 2000])"),filters:o.preprocess(e=>null==e||Array.isArray(e)?e:"object"==typeof e&&null!==e&&"column"in e?[e]:e,o.array(o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])})).optional().describe("For subset: filter conditions (AND logic). Single object or array. ops: eq, ne, in, gt, lt, gte, lte, between. Examples: { column: 'temp', op: 'between', value: [15, 30] }, { column: 'region', op: 'eq', value: 'Europe' }")),filter:o.object({column:o.string(),op:o.enum(["eq","ne","in","gt","lt","gte","lte","between"]),value:o.union([o.string(),o.number(),o.array(o.union([o.string(),o.number()]))])}).optional().describe("Deprecated — use filters instead. Single filter condition.")},async({action:e,name:t,file_path:o,csv_data:a,dataset_id:r,n_rows:n,row_range:l,filters:u,filter:d})=>{if("upload"===e){if(!t)throw new Error("datasets(upload) requires name");let e;if(o){const t=s.resolve(o);try{e=await i.readFile(t,"utf-8")}catch(e){const o=e instanceof Error?e.message:String(e);throw new Error(`Cannot read file "${t}": ${o}`)}}else{if(!(a&&a.length>0))throw new Error("datasets(upload) requires file_path or csv_data");e=a}return h(await g("POST","/v1/datasets",e,{"X-Dataset-Name":t,"Content-Type":"text/csv"}))}if("preview"===e){if(!r)throw new Error("datasets(preview) requires dataset_id");const e=await g("GET",`/v1/datasets/${r}/preview?n_rows=${n??5}`),t=e.columns??[],o=e.column_stats??[],a=e.cyclic_hints??[],i=e.sample_rows??[],s=e.datetime_columns??[],l=e.temporal_suggestions??[],u=e=>null==e?"—":Number(e).toFixed(3),d=[`Dataset: ${e.name} (${e.dataset_id})`,`${e.total_rows} rows × ${e.total_cols} columns`,"","Column Statistics:","| Column | Min | Max | Mean | Std | Nulls | Numeric |","|--------|-----|-----|------|-----|-------|---------|"];for(const e of o)d.push(`| ${e.column} | ${u(e.min)} | ${u(e.max)} | ${u(e.mean)} | ${u(e.std)} | ${e.null_count??0} | ${!1!==e.is_numeric?"yes":"no"} |`);if(a.length>0){d.push("","Detected Cyclic Feature Hints:");for(const e of a)d.push(`  • ${e.column} — period=${e.period} (${e.reason})`)}if(s.length>0){d.push("","Detected Datetime Columns:");for(const e of s){const t=(e.detected_formats??[]).map(e=>`${e.format} — ${e.description} (${(100*e.match_rate).toFixed(0)}% match)`).join("; ");d.push(`  • ${e.column}: sample="${e.sample}" → ${t}`)}}if(l.length>0){d.push("","Temporal Feature Suggestions (require user approval):");for(const e of l)d.push(`  • Columns: ${e.columns.join(" + ")} → format: "${e.format}"`),d.push(`    Available components: ${e.available_components.join(", ")}`)}if(i.length>0){d.push("",`Sample Rows (first ${i.length}):`),d.push(`| ${t.join(" | ")} |`),d.push(`| ${t.map(()=>"---").join(" | ")} |`);for(const e of i)d.push(`| ${t.map(t=>String(e[t]??"")).join(" | ")} |`)}return{content:[{type:"text",text:d.join("\n")}]}}if("subset"===e){if(!r)throw new Error("datasets(subset) requires dataset_id");if(!t)throw new Error("datasets(subset) requires name");const e=u??(d?[d]:void 0);if(void 0===l&&void 0===e)throw new Error("datasets(subset) requires at least one of row_range or filters");const o={name:t};void 0!==l&&(o.row_range=l),void 0!==e&&(o.filters=e);return h(await g("POST",`/v1/datasets/${r}/subset`,JSON.stringify(o),{"Content-Type":"application/json"}))}if("delete"===e){if(!r)throw new Error("datasets(delete) requires dataset_id");return h(await g("DELETE",`/v1/datasets/${r}`))}throw new Error("Invalid action")}),_.tool("train_som","Train a Self-Organizing Map on the dataset. Returns a job_id for polling.\n\nBEST FOR: Exploratory analysis of multivariate numeric data — clustering, regime\ndetection, process monitoring, anomaly visualization, dimensionality reduction.\nNOT FOR: Time-series forecasting, classification, or text/image data.\n\nASYNC POLLING PROTOCOL:\n- This tool returns a job_id. You MUST poll get_job_status to check completion.\n- Poll every 10-15 seconds.\n- Wait for status \"completed\" before calling analyze() or get_results().\n\nBEFORE calling, ask the user:\n1. Which columns to include? (use 'columns' to restrict)\n2. Any cyclic features?\n3. Any skewed columns? (suggest transforms)\n4. Feature weights?\n5. Quick exploration or refined map?\n\nESCALATION LADDER (If this tool fails):\n- Error mentions temporal validation: The dataset likely has datetime formatting issues. Use datasets(action=preview).\n- Error mentions column not found: Use datasets(action=preview) to verify exact column names (case-sensitive).\n- Error mentions NaNs or missing data: The user must clean the dataset.\n\nSee docs/SOM_PROCESS_AND_BEST_PRACTICES.md for detailed processual knowledge.",{dataset_id:o.string().describe("Dataset ID from datasets(action=upload) or list(type=datasets)"),preset:o.enum(["quick","standard","refined","high_res"]).optional().describe("Training preset — sets sensible defaults for grid, epochs, and batch_size. Explicit params override preset values. quick: 15×15, [15,5], batch=48. standard: 25×25, [30,15], batch=48, best with GPU. refined: 40×40, [50,25], batch=32, best with GPU. high_res: 60×60, [60,40], batch=32, best with GPU."),grid_x:o.number().int().optional().describe("Grid width (omit for auto from data size)"),grid_y:o.number().int().optional().describe("Grid height (omit for auto from data size)"),epochs:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseInt(e,10);if(!Number.isNaN(t))return t;const o=e.match(/^\[\s*(\d+)\s*,\s*(\d+)\s*\]$/);if(o)return[parseInt(o[1],10),parseInt(o[2],10)]}return e},o.union([o.number().int(),o.array(o.number().int()).length(2)]).optional().describe("epochs: integer or [ordering, convergence] array, not a string. Example: 40 or [40, 20]. Set convergence=0 to skip phase 2 (e.g. [15, 0]).")),model:o.enum(["SOM","RSOM","SOM-SOFT","RSOM-SOFT"]).optional().default("SOM").describe("SOM model type. SOM=standard, SOM-SOFT=GTM-style soft responsibilities, RSOM=recurrent (time-series), RSOM-SOFT=recurrent+soft."),periodic:o.boolean().optional().default(!0).describe("Use periodic (toroidal) boundaries"),columns:o.array(o.string()).optional().describe("Subset of CSV column names to train on. Omit to use all columns. Useful to exclude irrelevant features."),cyclic_features:o.array(o.object({feature:o.string().describe("Column name (e.g., 'weekday')"),period:o.number().describe("Period (e.g., 7 for weekday, 24 for hour, 360 for angle)")})).optional().describe("Features to encode as cyclic (cos, sin) pairs"),temporal_features:o.array(o.object({columns:o.array(o.string()).describe("Column name(s) containing datetime strings, combined in order (e.g. ['Date', 'Time'])"),format:o.string().describe("Julia Dates format string from the whitelist (e.g. 'dd.mm.yyyy HH:MM'). Must match the combined column values."),extract:o.array(o.enum(["hour_of_day","day_of_year","month","day_of_week","minute_of_hour"])).describe("Which temporal components to extract"),cyclic:o.boolean().default(!0).describe("Encode extracted components as cyclic sin/cos pairs (default true)"),separator:o.string().optional().describe("Separator when combining multiple columns (default ' '). Use 'T' for ISO 8601.")})).optional().describe("Temporal feature extraction from datetime columns. Parses dates/times and extracts components. NEVER add this without user approval."),feature_weights:o.record(o.number()).optional().describe("Per-feature importance weights as {column_name: weight}. Applied after normalization (column *= sqrt(weight)). weight=0 disables, >1 emphasizes, <1 de-emphasizes. Cyclic shorthand: {'day_of_year': 2.0} auto-expands to both _cos and _sin. Categorical features should be weighted by the LLM if there is any natural hierarchy applicable that could be constructive."),transforms:o.record(o.enum(["log","log1p","log10","sqrt","square","abs","invert","rank","none"])).optional().describe("Per-column preprocessing applied BEFORE normalization. Example: {revenue: 'log', pressure: 'sqrt'}. 'log' = natural log (fails on <=0), 'log1p' = log(1+x) (safe for zeros), 'sqrt' = square root, 'rank' = replace with rank order, 'invert' = 1/x. Suggest log/log1p for right-skewed distributions (prices, volumes, counts)."),normalize:o.union([o.enum(["all","auto"]),o.array(o.string())]).optional().default("auto").describe("Normalization mode. 'auto' skips already-cyclic features."),sigma_f:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseFloat(e);if(!Number.isNaN(t))return t}return e},o.number().optional().describe("Final neighborhood radius at end of ordering phase (default 1.0). Lower values (0.5–0.7) produce sharper cluster boundaries.")),learning_rate:o.preprocess(e=>{if(null==e)return e;if("string"==typeof e){const t=parseFloat(e);if(!Number.isNaN(t))return t}return e},o.union([o.number(),o.object({ordering:o.tuple([o.number(),o.number()]),convergence:o.tuple([o.number(),o.number()])})]).optional().describe("Learning rate control. Number = sets ordering final rate (e.g. 0.05). Object = full control: {ordering: [eta_0, eta_f], convergence: [eta_0, eta_f]}. Default: ordering 0.1→0.01, convergence 0.01→0.001.")),batch_size:o.number().int().optional().describe("Training batch size (default: auto ≈ n_samples/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:o.enum(["auto","cpu","cuda","cuda_graphs"]).optional().default("auto").describe("Compute backend. 'auto' uses CUDA if GPU is available (recommended). 'cpu' forces CPU. 'cuda_graphs' uses CUDA graph capture for maximum GPU throughput."),output_format:o.enum(["png","pdf","svg"]).optional().default("pdf").describe("Image output format. PDF (default) for publication-quality vector graphics, PNG for quick viewing, SVG for web embedding."),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution for PNG output: standard (1x), retina (2x, default), print (4x). Ignored for PDF/SVG."),colormap:o.string().optional().describe("Override default colormap (coolwarm) for component planes and hit histogram. Examples: viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix always uses grays, cyclic features use twilight."),row_range:o.tuple([o.number().int().min(1),o.number().int().min(1)]).optional().describe("Train on a subset of rows only: [start, end] 1-based inclusive. Alternative to creating a subset dataset with datasets(action=subset).")},async({dataset_id:e,preset:t,grid_x:o,grid_y:a,epochs:r,model:n,periodic:i,columns:s,transforms:l,cyclic_features:u,temporal_features:d,feature_weights:c,normalize:p,sigma_f:m,learning_rate:f,batch_size:b,backend:_,output_format:y,output_dpi:w,colormap:v,row_range:$})=>{let x={};try{const e=await g("GET","/v1/training/config");x=e?.presets||{}}catch(e){if(t&&!o&&!r)throw new Error("Could not fetch training config from server, and missing explicit grid/epochs.")}const j=t?x[t]:void 0,S={model:n,periodic:i,normalize:p};void 0!==o&&void 0!==a?S.grid=[o,a]:j&&(S.grid=j.grid),void 0!==r?S.epochs=r:j&&(S.epochs=j.epochs),u&&u.length>0&&(S.cyclic_features=u),s&&s.length>0&&(S.columns=s),l&&Object.keys(l).length>0&&(S.transforms=l),d&&d.length>0&&(S.temporal_features=d),c&&Object.keys(c).length>0&&(S.feature_weights=c),void 0!==m&&(S.sigma_f=m),void 0!==f&&(S.learning_rate=f),void 0!==b?S.batch_size=b:j&&(S.batch_size=j.batch_size),void 0!==_&&"auto"!==_?S.backend=_:j?.backend&&(S.backend=j.backend),S.output_format=y??"pdf";const T={standard:1,retina:2,print:4};w&&"retina"!==w&&(S.output_dpi=T[w]??2),v&&(S.colormap=v),$&&$.length>=2&&$[0]<=$[1]&&(S.row_range=$);const E=await g("POST","/v1/jobs",{dataset_id:e,params:S});try{const e=await g("GET","/v1/system/info"),t=Number(e.status?.pending_jobs??e.pending_jobs??0),o=Number(e.training_time_estimates_seconds?.total??(e.gpu_available?45:120)),a=Math.round(t*o/60);a>1?(E.estimated_wait_minutes=a,E.message=`Job submitted. You are #${t+1} in queue. Estimated wait before start: ~${a} min.`):E.message="Job submitted. Should start momentarily."}catch(e){}return h(E)}),_.tool("get_job_status","Check status and progress of a training or analysis job.\n\nASYNC POLLING PROTOCOL:\n- Poll every 10-15 seconds. Do NOT poll faster as it wastes context.\n- For large grids (40x40+), do not assume failure before 3 minutes on CPU.\n- Wait for status \"completed\" before calling analyze() or get_results().\n\nESCALATION LADDER:\n- When status is 'completed', call get_results() to retrieve the map and metrics.\n- When status is 'failed', the worker hit an error. Extract the error message.\n  - If the error is about memory/allocation, reduce batch_size or grid_x/grid_y and run train_som again.\n  - If the error is about column missing, verify columns with datasets(action=preview).\n  - If the error is about NaNs, the user MUST clean the dataset.\n\nTIMING:\nTypical completion times (CPU, 8700 samples):\n  10x10, 10 epochs: ~30s | 20x20, 30 epochs: ~3–5 min | 40x40, 60 epochs: ~15–30 min",{job_id:o.string().describe("Job ID from train_som")},async({job_id:e})=>{const t=await g("GET",`/v1/jobs/${e}`),o=t.status,a=100*(t.progress??0),r=null!=t.label&&""!==t.label?String(t.label):null;let n=`${r?`Job ${r} (id: ${e})`:`Job ${e}`}: ${o} (${a.toFixed(1)}%)`;return"completed"===o?n+=` | Results ready. Use get_results(job_id="${e}") to retrieve.`:"failed"===o&&(n+=` | Error: ${t.error??"unknown"}`),{content:[{type:"text",text:n}]}}),_.tool("get_results",'Retrieve results of a completed SOM training, projection, or derived variable job.\n\nWHEN TO USE: \n- Getting the first look at a trained SOM — combined visualization + quality metrics.\n- ONLY call this after get_job_status returns "completed".\n\nESCALATION LADDER:\n- If this returns an error that the job is not found, verify the job_id.\n- If it returns "job not complete", you polled too early. Call get_job_status and WAIT.\n\nTIMING: Near-instant (reads pre-computed results from S3).\n\nReturns: text summary with metrics and inline images (combined view and all plots shown directly in chat).\n\nDOWNLOAD LINKS: Links to API-domain or presigned URLs may not work when clicked (MCP holds the API key, not the browser). Images are inlined. For weights use get_job_export(export="weights"); for node stats use get_job_export(export="nodes"). If the user wants to save a file, offer to fetch via the appropriate tool.\n\nOPTIONS:\n- figures: request specific plots only. Omit for default (combined only; or all if include_individual=true).\n  - "combined_only": only the combined view.\n  - "all": combined + umatrix + hit_histogram + all component planes.\n  - Array of logical names: e.g. figures: ["umatrix"] for just the U-matrix, or figures: ["combined","hit_histogram","correlation"] or ["combined","umatrix","component_1","component_2"]. Logical names: combined, umatrix, hit_histogram, correlation, component_1, component_2, ... (component_N = Nth feature). Pass an array to fetch/save only those figures.\n- include_individual=true: when figures is omitted, shows each component plane, U-matrix, and hit histogram\n  as separate inline images. Ignored when figures is set.\n\nAFTER showing results, guide the user:\n1. "The U-matrix shows [N] distinct regions. Does this match expected groupings?"\n2. "QE=X, TE=Y — [assessment]. Would you like to retrain with different params?"\n3. "Which features show interesting patterns in the component planes?"\n4. If QE > 2: suggest more epochs or larger grid\n5. If TE > 0.15: suggest larger grid\n6. If explained variance < 0.7: suggest transforms, feature selection, or more training\n\nWORKFLOW: get_results → analyze(clusters) → component_planes → feature_correlation.\nRequest specific figures with get_results(job_id, figures=[...]) (e.g. figures: ["umatrix"] or figures: ["combined","hit_histogram"]) or run analyze(job_id, analysis_type) for a single view.\nUse get_job_export(export="training_log") for the learning curve (QE vs epoch — healthy=steady decline then plateau).\nUse analyze(job_id, "quality_report") for extended metrics (trustworthiness, neighborhood preservation).\n\nMETRIC INTERPRETATION:\n- QE < 1.5: good fit. QE > 2: consider more epochs, larger grid, or batch_size=32.\n- TE < 0.05: good topology. TE > 0.15: grid too small.\n- Explained variance > 0.8: good. < 0.7: try transforms, fewer features, or more training.\nAfter successful retrieval, you may auto-generate a brief piece of feedback based on the user\'s experience so far and ask if they\'d like you to send it to the developers via send_feedback (max 190 words).',{job_id:o.string().describe("Job ID of a completed job"),figures:o.union([o.enum(["default","combined_only","all"]),o.array(o.string())]).optional().describe("Which figures to return. Omit or 'default' for combined only (or all if include_individual=true). 'combined_only': just combined view. 'all': combined + umatrix + hit_histogram + correlation + all component planes. Or array of logical names to fetch only those: combined, umatrix, hit_histogram, correlation, component_1, component_2, ..."),include_individual:o.boolean().optional().default(!1).describe("If true and figures is omitted, inline each individual plot (component planes, u-matrix, hit histogram). Ignored when figures is set.")},async({job_id:e,figures:t,include_individual:o})=>{const a=await g("GET",`/v1/results/${e}`),r=a.summary??{},n=(a.download_urls,null!=a.label&&""!==a.label?String(a.label):null),i=n?`Results for ${n} (job_id: ${e})`:`Results for job_id: ${e}`,s=[],l=new Set,u=r.job_type??"train_som";r.output_format;if("transition_flow"===u){const a=r.lag??1,n=r.flow_stats??{};s.push({type:"text",text:[`Transition Flow ${i}`,`Parent SOM: ${r.parent_job_id??"N/A"} | Lag: ${a} | Samples: ${r.n_samples??0}`,"","Flow Statistics:",`  Mean flow magnitude: ${void 0!==n.mean_magnitude?Number(n.mean_magnitude).toFixed(4):"N/A"}`,`  Max flow magnitude:  ${void 0!==n.max_magnitude?Number(n.max_magnitude).toFixed(4):"N/A"}`,`  Nodes with flow:     ${n.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")});for(const a of j(u,r,t,o))await T(s,e,a),l.add(a)}else if("project_variable"===u){const a=r.variable_name??"variable",n=r.aggregation??"mean",d=r.variable_stats??{};s.push({type:"text",text:[`Projected Variable: ${a} (${n}) — ${i}`,`Parent SOM: ${r.parent_job_id??"N/A"} | Samples: ${r.n_samples??0}`,"",`Variable Statistics (per-node ${n}):`,`  Min:            ${void 0!==d.min?Number(d.min).toFixed(3):"N/A"}`,`  Max:            ${void 0!==d.max?Number(d.max).toFixed(3):"N/A"}`,`  Mean:           ${void 0!==d.mean?Number(d.mean).toFixed(3):"N/A"}`,`  Nodes with data: ${d.n_nodes_with_data??"N/A"} / ${Number(d.n_nodes_with_data??0)+Number(d.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")});for(const a of j(u,r,t,o))await T(s,e,a),l.add(a)}else{const a=r.grid??[0,0],n=r.features??[],d=r.epochs,c=Array.isArray(d)?0===d[1]?`${d[0]} ordering only`:`${d[0]} ordering + ${d[1]} convergence`:String(d??"N/A"),p=e=>null!=e?Number(e).toFixed(4):"N/A",m=r.training_duration_seconds,g=r.ordering_errors,f=[`SOM Training ${i}`,`Grid: ${a[0]}×${a[1]} | Features: ${r.n_features??0} | Samples: ${r.n_samples??0}`,`Model: ${r.model??"SOM"} | Epochs: ${c}`,`Periodic: ${r.periodic??!0} | Normalize: ${r.normalize??"auto"}`,void 0!==r.sigma_f?`Sigma_f: ${r.sigma_f}`:"",void 0!==m?`Training duration: ${m}s`:"","","Quality Metrics:",`  Quantization Error: ${p(r.quantization_error)}  (lower is better)`,`  Topographic Error:  ${p(r.topographic_error)}   (lower is better, <0.1 is good)`,`  Explained Variance: ${p(r.explained_variance)}  (higher is better, >0.7 is good)`,`  Silhouette Score:   ${p(r.silhouette)}          (higher is better, [-1, 1])`,`  Davies-Bouldin:     ${p(r.davies_bouldin)}      (lower is better)`,`  Calinski-Harabasz:  ${p(r.calinski_harabasz)}   (higher is better)`,g&&g.length>0?`  Final ordering QE: ${g.at(-1)?.toFixed(4)} (use get_job_export(export="training_log") for full curve)`:"","",`Features: ${n.join(", ")}`,r.selected_columns?`Selected columns: ${r.selected_columns.join(", ")}`:"",r.transforms?`Transforms: ${Object.entries(r.transforms).map(([e,t])=>`${e}=${t}`).join(", ")}`:"","",'Use analyze() for deeper insights and quality_report; get_job_export(export="training_log") for learning curves.'].filter(e=>""!==e).join("\n");s.push({type:"text",text:f});r.output_format;const h=j(u,r,t,o);for(const t of h)await T(s,e,t),l.add(t)}const d=r.files??[],c=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");for(const t of d)if(c(t)&&!l.has(t))await T(s,e,t);else if(t.endsWith(".json")){const e="weights.json"===t?'Use get_job_export(export="weights") for full weight matrix including node_coords.':"node_stats.json"===t?'Use get_job_export(export="nodes") for per-node statistics.':"summary.json"===t?null:"Use get_job_export for structured data (weights or nodes).";e&&s.push({type:"text",text:`${t}: ${e}`})}if(d.length>0){const e=r.features??[],t="train_som"===u||"render_variant"===u?`Logical names: combined, umatrix, hit_histogram, correlation, ${e.map((e,t)=>`component_${t+1}`).join(", ")}. `:"";s.push({type:"text",text:`Available to fetch individually: ${d.join(", ")}. ${t}Use get_results(job_id, figures=[...]) to request specific plots, get_results(job_id, include_individual=true) or figures="all" to inline all plots, or analyze(job_id, analysis_type) for a specific view (u_matrix, component_planes, bmu_hits, clusters, quality_report, etc.).`})}return{content:s}}),_.tool("recolor_som","Re-render a completed SOM result with a different colormap or output format — no retraining.\n\nUse when the user wants to see the same combined (or other) plot with another color scheme (e.g. plasma, inferno, coolwarm). You can also use this to re-export figures in a different format (e.g. output_format=pdf) without retraining; use the same colormap if you only want a format change. Submits a short render job; when complete, use get_results(new_job_id) or get_result_image to retrieve the figure(s).\n\nColormaps (default: coolwarm): e.g. viridis, plasma, inferno, magma, cividis, turbo, thermal, hot, coolwarm, balance, RdBu, Spectral. U-matrix and cyclic panels keep fixed colormaps (grays, twilight).",{job_id:o.string().describe("Job ID of a completed SOM training job (parent)"),colormap:o.string().describe("Colormap name (default: coolwarm). E.g. viridis, plasma, inferno, magma, coolwarm)"),figures:o.array(o.string()).optional().default(["combined"]).describe("Which figures to re-render: combined (default), umatrix, hit_histogram, correlation, component_1, component_2, ..."),output_format:o.enum(["png","pdf","svg"]).optional().default("pdf"),output_dpi:o.number().int().min(1).max(4).optional().default(2)},async({job_id:e,colormap:t,figures:o,output_format:a,output_dpi:r})=>{const n={colormap:t,figures:o,output_format:a,output_dpi:r},i=(await g("POST",`/v1/results/${e}/render`,JSON.stringify(n),{"Content-Type":"application/json"})).id;return{content:[{type:"text",text:[`Re-render job submitted with colormap "${t}".`,`New job_id: ${i}. Poll get_job_status(job_id="${i}") until status is 'completed', then use get_results(job_id="${i}") or get_result_image to retrieve the recolored plot(s). No retraining was performed.`].join("\n")}]}}),_.tool("download_results",'Save result figures (and optionally JSON) to a folder on disk. Use so the user can open, share, or version files locally without writing their own download script.\n\nfolder: path to the directory (e.g. "." for current/workspace, "./results", or absolute path). When folder is a generic path like "." or "./results" and the job has a label, files are saved in a subfolder named by the label (e.g. ./results/Winedata_a1b2c3_badger_thong_oil). You can also pass a path that already includes the label.\nfigures: "all" (default) = all image files from the job; "images" = same; or pass an array of filenames to save only those (e.g. ["combined.pdf", "umatrix.pdf", "correlation.pdf"]). Default export format is PDF.\ninclude_json: if true, also save summary.json (and other JSON artifacts) into the same folder.\nAfter saving files, you may auto-generate a brief piece of feedback based on the session and ask the user if they\'d like you to send it via send_feedback to the developers.',{job_id:o.string().describe("Job ID of a completed job"),folder:o.string().describe("Directory path to save files (e.g. '.' or './results'). When the job has a label, a subfolder with that label may be used. Relative paths are relative to process cwd (usually project root)."),figures:o.union([o.enum(["all","images"]),o.array(o.string())]).optional().default("all").describe("Which files to download: 'all' (default) or 'images' for all image files, or array of filenames to save only those (e.g. ['combined.pdf', 'umatrix.pdf', 'correlation.pdf'])."),include_json:o.boolean().optional().default(!1).describe("If true, also download summary.json and other JSON files")},async({job_id:e,folder:t,figures:o,include_json:a})=>{const r=await g("GET",`/v1/results/${e}`),n=r.summary??{},l=null!=r.label&&""!==r.label?String(r.label):null,u=n.files??[],d=e=>e.endsWith(".png")||e.endsWith(".svg")||e.endsWith(".pdf");let c;"all"===o||"images"===o?c=a?u:u.filter(d):(c=o,a&&!c.includes("summary.json")&&(c=[...c,"summary.json"]));let p=s.resolve(t);l&&("."===t||"./results"===t||"results"===t)&&(p=s.join(p,l)),await i.mkdir(p,{recursive:!0});const m=[];for(const t of c)try{const{data:o}=await f(`/v1/results/${e}/image/${t}`),a=s.join(p,t);await i.writeFile(a,o),m.push(t)}catch{}return{content:[{type:"text",text:m.length>0?`Saved ${m.length} file(s) to ${p}: ${m.join(", ")}`:"No files saved (job may have no matching files or download failed). Check job_id and that the job is completed."}]}}),_.tool("analyze",'Run a specific analysis on SOM results. Use after get_results to drill into aspects.\nRequest specific plots: get_results(job_id, figures=[...]) for chosen figures (e.g. figures: ["umatrix"]) or analyze(job_id, analysis_type) for a single analysis view.\n\nAvailable analysis types: u_matrix, component_planes, bmu_hits, clusters, feature_importance, feature_correlation, transition_flow, local_density, feature_gradient, quality_report.\n(Detailed interpretation guidance is fetched from the server).',{job_id:o.string().describe("Job ID of a completed job"),analysis_type:o.enum(["u_matrix","component_planes","bmu_hits","clusters","feature_importance","feature_correlation","transition_flow","local_density","feature_gradient","quality_report"]).describe("Type of analysis to run"),params:o.record(o.unknown()).optional().describe("Analysis-specific parameters. For component_planes/feature_gradient: {features: [col,...]} to restrict to specific columns.")},async({job_id:e,analysis_type:t,params:o})=>{let a="";try{a=(await g("GET","/v1/docs/tool_guidance?tool=analyze")).guidance||""}catch(e){}const r=(await g("GET",`/v1/results/${e}`)).summary??{},n=r.features??[],i=r.grid??[0,0],s=r.output_format??"pdf",l=[];if("u_matrix"===t)l.push({type:"text",text:[`U-Matrix Analysis (job: ${e})`,`Grid: ${i[0]}×${i[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 T(l,e,`umatrix.${s}`);else if("component_planes"===t){const t=o?.features??n;l.push({type:"text",text:[`Component Planes (job: ${e})`,`Features: ${t.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 o=0;o<n.length;o++){if(!t.includes(n[o]))continue;const a=n[o].replace(/[^a-zA-Z0-9_]/g,"_");await T(l,e,`component_${o+1}_${a}.${s}`)}}else if("bmu_hits"===t)l.push({type:"text",text:[`BMU Hit Histogram (job: ${e})`,`Grid: ${i[0]}×${i[1]} | Samples: ${r.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 T(l,e,`hit_histogram.${s}`);else if("clusters"===t){const t=r.quantization_error,o=r.topographic_error,a=r.explained_variance,s=r.silhouette,u=void 0===t?"N/A":t<.5?"excellent":t<1?"good":t<2?"fair":"poor",d=void 0===o?"N/A":o<.05?"excellent":o<.1?"good":o<.2?"fair":"poor",c=e=>void 0!==e?e.toFixed(4):"N/A",p=[];void 0!==o&&o>.15&&p.push(`Topographic error ${(100*o).toFixed(1)}% is high — try a larger grid or more epochs.`),void 0!==t&&t>2&&p.push(`Quantization error ${t.toFixed(3)} is high — try more epochs, a larger grid, or check for outliers.`),void 0!==a&&a<.7&&p.push(`Explained variance ${(100*a).toFixed(1)}% is low — try more epochs, a larger grid, or feature weighting.`),void 0!==s&&s<.1&&p.push("Low silhouette score — clusters overlap. Try sigma_f=0.5 or more training."),0===p.length&&p.push("Metrics look healthy. Proceed with component plane and feature analysis.");const m=i[0]>0?`${i[0]}×${i[1]}`:"N/A";l.push({type:"text",text:[`Cluster Quality Assessment (job: ${e})`,`Grid: ${m} | Features: ${n.length} | Samples: ${r.n_samples??"N/A"}`,"",`Quantization Error:  ${c(t)}  (${u})`,`Topographic Error:   ${c(o)}  (${d})`,`Explained Variance:  ${c(a)}`,`Silhouette Score:    ${c(s)}`,`Davies-Bouldin:      ${c(r.davies_bouldin)}`,`Calinski-Harabasz:   ${c(r.calinski_harabasz)}`,"","Recommendations:",...p.map(e=>`  - ${e}`)].join("\n")})}else if("feature_importance"===t)l.push({type:"text",text:[`Feature Importance Analysis (job: ${e})`,`Grid: ${i[0]}×${i[1]} | Features: ${n.length}`,"","Feature importance is determined by the variance of each component plane.","Higher variance = feature contributes more to the SOM structure.","",`Features analyzed: ${n.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 T(l,e,`combined.${s}`);else if("feature_correlation"===t){l.push({type:"text",text:[`Feature Correlation Analysis (job: ${e})`,`Features: ${n.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 t=0;t<n.length;t++){const o=n[t].replace(/[^a-zA-Z0-9_]/g,"_");await T(l,e,`component_${t+1}_${o}.${s}`)}}else if("transition_flow"===t)l.push({type:"text",text:[`Transition Flow Analysis (job: ${e})`,`Grid: ${i[0]}×${i[1]} | Samples: ${r.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 T(l,e,`umatrix.${s}`);else if("local_density"===t)l.push({type:"text",text:[`Local Density & Cluster Analysis (job: ${e})`,`Grid: ${i[0]}×${i[1]} | Samples: ${r.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 T(l,e,`umatrix.${s}`),await T(l,e,`hit_histogram.${s}`);else if("feature_gradient"===t){const t=o?.feature;if(l.push({type:"text",text:[`Feature Gradient Analysis (job: ${e})`,`Target: ${t??"all features"}`,`Grid: ${i[0]}×${i[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")}),t){const o=n.indexOf(t);if(o>=0){const a=t.replace(/[^a-zA-Z0-9_]/g,"_");await T(l,e,`component_${o+1}_${a}.${s}`)}}else await T(l,e,`combined.${s}`);await T(l,e,`umatrix.${s}`)}else if("quality_report"===t){const t=await g("GET",`/v1/results/${e}/quality-report`),o=t.standard_metrics??{},a=t.cluster_metrics??{},r=t.topology_metrics??{},n=t.training??{},i=t.grid??[0,0],s=e=>null!=e?e.toFixed(4):"—",u=e=>null!=e?`${(100*e).toFixed(1)}%`:"—",d=[],c=o.quantization_error,p=o.topographic_error,m=o.explained_variance,f=a.silhouette,h=r.trustworthiness;null!=c&&c>2&&d.push("QE is high → try more epochs or a larger grid"),null!=p&&p>.15&&d.push("TE is high → topology is not well-preserved, try larger grid"),null!=m&&m<.7&&d.push("Explained variance < 70% → consider more training or feature selection"),null!=f&&f<.1&&d.push("Low silhouette → clusters overlap, try sigma_f=0.5 or more epochs"),null!=h&&h<.85&&d.push("Trustworthiness < 85% → local neighborhood structure is distorted"),0===d.length&&d.push("All metrics look healthy — good map quality!");const b=n.epochs,_=b?0===b[1]?`${b[0]} ordering only`:`${b[0]}+${b[1]}`:"—",y=[`Quality Report — Job ${e}`,`Grid: ${i[0]}×${i[1]} | Model: ${t.model??"SOM"} | Samples: ${t.n_samples??"?"}`,`Epochs: ${_} | Duration: ${n.duration_seconds?`${n.duration_seconds}s`:"—"}`,"","Standard Metrics:",`  Quantization Error:  ${s(o.quantization_error)}   (lower is better)`,`  Topographic Error:   ${s(o.topographic_error)}   (lower is better)`,`  Distortion:          ${s(o.distortion)}`,`  Kaski-Lagus Error:   ${s(o.kaski_lagus_error)}   (lower is better)`,`  Explained Variance:  ${u(o.explained_variance)}`,"","Cluster Quality Metrics:",`  Silhouette Score:    ${s(a.silhouette)}   (higher is better, -1 to +1)`,`  Davies-Bouldin:      ${s(a.davies_bouldin)}   (lower is better)`,`  Calinski-Harabasz:   ${s(a.calinski_harabasz)}   (higher is better)`,"","Topology Metrics:",`  Neighborhood Preservation: ${u(r.neighborhood_preservation)}   (higher is better)`,`  Trustworthiness:           ${u(r.trustworthiness)}   (higher is better)`,`  Topographic Product:       ${s(r.topographic_product)}   (near 0 is ideal)`,"","Recommendations:",...d.map(e=>`  • ${e}`)];l.push({type:"text",text:y.join("\n")})}return{content:l}}),_.tool("compare_runs",'Compare metrics across multiple completed SOM training jobs.\nReturns a table of QE, TE, silhouette, and other metrics for each job.\n\nUse to evaluate hyperparameter choices: grid size, epochs, sigma_f, model type, feature selection.\n\nAfter comparing, ask the user:\n"Which job produced the best metrics for your goal?"\n- For visualization clarity: prioritize low topographic error (<0.1)\n- For tight clusters: prioritize low QE and high silhouette\n- For dimensionality reduction: prioritize high explained variance (>0.8)',{job_ids:o.array(o.string()).min(2).describe("Array of job IDs to compare (minimum 2)")},async({job_ids:e})=>{const t=e.join(","),o=(await g("GET",`/v1/jobs/compare?ids=${t}`)).comparisons??[],a=["| Job ID | Grid | Epochs | Model | QE | TE | Expl.Var | Silhouette |","|--------|------|--------|-------|----|----|----------|------------|"];for(const e of o){if(e.error){a.push(`| ${e.job_id.slice(0,8)}... | — | — | — | ${e.error} | — | — | — |`);continue}const t=e.grid,o=t?`${t[0]}×${t[1]}`:"—",r=e.epochs,n=r?0===r[1]?`${r[0]}+0`:`${r[0]}+${r[1]}`:"—",i=e.model??"—",s=e=>null!=e?Number(e).toFixed(4):"—";a.push(`| ${e.job_id.slice(0,8)}... | ${o} | ${n} | ${i} | ${s(e.quantization_error)} | ${s(e.topographic_error)} | ${s(e.explained_variance)} | ${s(e.silhouette)} |`)}return{content:[{type:"text",text:a.join("\n")}]}}),_.tool("manage_job","Cancel or delete a job.\n\naction=cancel: Cancel a pending or running job. Not instant — worker checks between phases (expect up to 30s). Use when run is too slow, wrong params, or to free the worker. Partial results discarded.\naction=delete: Permanently delete a job and all S3 result files. Use to free storage, remove test runs, or clean up after cancel. WARNING: Job ID will no longer work with get_results or other tools.",{job_id:o.string().describe("Job ID to cancel or delete"),action:o.enum(["cancel","delete"]).describe("cancel: stop the job; delete: remove job and all result files")},async({job_id:e,action:t})=>{if("cancel"===t){return h(await g("POST",`/v1/jobs/${e}/cancel`))}return h(await g("DELETE",`/v1/jobs/${e}`))}),_.tool("list","List datasets or jobs.\n\ntype=datasets: List all datasets uploaded by the organization. Use to check what data is available before train_som or to find dataset IDs.\ntype=jobs: List SOM training jobs (optionally filtered by dataset_id). Use to find job IDs for compare_runs, check completed vs pending, or review hyperparameters.",{type:o.enum(["datasets","jobs"]).describe("What to list: datasets or jobs"),dataset_id:o.string().optional().describe("Filter jobs by dataset ID (only used when type=jobs)")},async({type:e,dataset_id:t})=>{if("datasets"===e){return h(await g("GET","/v1/datasets"))}const o=t?`/v1/jobs?dataset_id=${t}`:"/v1/jobs",a=await g("GET",o);if("jobs"===e&&Array.isArray(a)){const e=a.map(e=>{const t=String(e.id??""),o=String(e.status??""),a=null!=e.label&&""!==e.label?String(e.label):null;return a?`${a} (id: ${t}) — status: ${o}`:`id: ${t} — status: ${o}`});return{content:[{type:"text",text:e.length>0?e.join("\n"):"No jobs found."}]}}return h(a)}),_.tool("get_job_export","Export structured data from a completed SOM training job.\n\nexport=training_log: Learning curve and diagnostics (per-epoch QE, sparklines, inline plot). Use to diagnose convergence, plateau, or divergence.\nexport=weights: Raw weight matrix with node_coords, normalized/denormalized values, normalization stats. Use for external analysis or custom visualizations. Can be large (e.g. 600KB+ for 30×30×12).\nexport=nodes: Per-node statistics (hit count, feature mean/std). Use to profile clusters and characterize operating modes.",{job_id:o.string().describe("Job ID of a completed training job"),export:o.enum(["training_log","weights","nodes"]).describe("What to export: training_log, weights, or nodes")},async({job_id:e,export:t})=>{if("training_log"===t){const t=await g("GET",`/v1/results/${e}/training-log`),o=t.ordering_errors??[],a=t.convergence_errors??[],r=t.training_duration_seconds,n=t.epochs,i=e=>{if(0===e.length)return"(no data)";const t=Math.min(...e),o=Math.max(...e)-t||1;return e.map(e=>"▁▂▃▄▅▆▇█"[Math.min(7,Math.floor((e-t)/o*7))]).join("")},s=[`Training Log — Job ${e}`,`Grid: ${JSON.stringify(t.grid)} | Model: ${t.model??"SOM"}`,"Epochs: "+(n?`[${n[0]} ordering, ${n[1]} convergence]`:"N/A"),"Duration: "+(null!=r?`${r}s`:"N/A"),`Features: ${t.n_features??"?"} | Samples: ${t.n_samples??"?"}`,"",`Ordering Phase (${o.length} epochs):`,`  Start QE: ${o[0]?.toFixed(4)??"—"}  →  End QE: ${o.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(o)}`];a.length>0?s.push("",`Convergence Phase (${a.length} epochs):`,`  Start QE: ${a[0]?.toFixed(4)??"—"}  →  End QE: ${a.at(-1)?.toFixed(4)??"—"}`,`  Curve:    ${i(a)}`):0===(n?.[1]??0)&&s.push("","Convergence phase: skipped (epochs[1]=0)");const l=t.quantization_error,u=t.explained_variance;null!=l&&s.push("",`Final QE: ${l.toFixed(4)} | Explained Variance: ${(u??0).toFixed(4)}`);const d=[{type:"text",text:s.join("\n")}];let c=!1;for(const t of["png","pdf","svg"])try{const{data:o}=await f(`/v1/results/${e}/image/learning_curve.${t}`);d.push({type:"image",data:o.toString("base64"),mimeType:S(`learning_curve.${t}`),annotations:{audience:["user"],priority:.8}}),c=!0;break}catch{continue}return c||d.push({type:"text",text:"(learning curve plot not available)"}),{content:d}}if("weights"===t){const t=await g("GET",`/v1/results/${e}/weights`),o=t.features??[],a=t.n_nodes??0,r=t.grid??[0,0],n=[`SOM Weights — Job ${e}`,`Grid: ${r[0]}×${r[1]} | Nodes: ${a} | Features: ${o.length}`,"node_coords: [x,y] per node for topology",`Features: ${o.join(", ")}`,"","Normalization Stats:"],i=t.normalization_stats??{};for(const[e,t]of Object.entries(i))n.push(`  ${e}: mean=${t.mean?.toFixed(4)}, std=${t.std?.toFixed(4)}`);return n.push("","Full weight matrix available in the response JSON (includes node_coords).","Use the denormalized_weights array for original-scale values."),{content:[{type:"text",text:n.join("\n")},{type:"text",text:JSON.stringify(t,null,2)}]}}const o=await g("GET",`/v1/results/${e}/nodes`),a=[...o].sort((e,t)=>(t.hit_count??0)-(e.hit_count??0)).slice(0,10),r=o.filter(e=>0===e.hit_count).length,n=o.reduce((e,t)=>e+(t.hit_count??0),0),i=[`Node Statistics — Job ${e}`,`Total nodes: ${o.length} | Active: ${o.length-r} | Empty: ${r}`,`Total hits: ${n}`,"","Top 10 Most Populated Nodes:","| Node | Coords | Hits | Hit% |","|------|--------|------|------|"];for(const e of a){if(0===e.hit_count)break;const t=e.coords,o=(e.hit_count/n*100).toFixed(1);i.push(`| ${e.node_index} | (${t?.[0]?.toFixed(1)}, ${t?.[1]?.toFixed(1)}) | ${e.hit_count} | ${o}% |`)}return{content:[{type:"text",text:i.join("\n")},{type:"text",text:`\nFull node statistics JSON:\n${JSON.stringify(o,null,2)}`}]}}),_.tool("project_variable",'Project a pre-computed variable onto a trained SOM without retraining.\n\nBEST FOR: Mapping external metrics (revenue, labels, anomaly scores) onto the\ntrained SOM structure. For formula-based variables from the training dataset,\nprefer derive_variable with project_onto_job; use project_variable only for\nexternally computed arrays.\nNOT FOR: Re-training or adding features to the map.\n\nTIMING: ~5–15s (loads cached SOM, computes per-node aggregation, renders plot).\n\nvalues: array of length n_samples (~11 bytes/sample). Must match training sample\ncount exactly (same CSV row order). Aggregation controls how multiple samples\nper node are combined (mean/median/sum/max/count).\n\nBEFORE calling, ask:\n- "What variable? Is it from the original data or externally computed?"\n- "How to aggregate per node: mean (typical), sum (totals), max (peaks)?"\n\nCOMMON MISTAKES:\n- Wrong number of values (must match n_samples from training)\n- Using mean aggregation for count data (use sum instead)\n- Not trying derive_variable first when the variable can be computed from columns\n\nHINT: If values length mismatch, suggest derive_variable for formula-based variables.',{job_id:o.string().describe("ID of the completed SOM training job"),variable_name:o.string().describe("Name for this variable (used in visualization labels)"),values:o.array(o.number()).describe("Array of values to project — one per training sample, in original CSV row order"),aggregation:o.enum(["mean","median","sum","min","max","std","count"]).optional().default("mean").describe("How to aggregate values for nodes with multiple samples"),output_format:o.enum(["png","pdf","svg"]).optional().default("pdf").describe("Image output format for the projection plot (default: pdf)."),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x), print (4x)."),colormap:o.string().optional().describe("Override colormap for the projection plot (default: coolwarm). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral.")},async({job_id:e,variable_name:t,values:o,aggregation:a,output_format:r,output_dpi:n,colormap:i})=>{const s={variable_name:t,values:o,aggregation:a??"mean",output_format:r??"pdf"};n&&"retina"!==n&&(s.output_dpi={standard:1,retina:2,print:4}[n]??2),i&&(s.colormap=i);const l=(await g("POST",`/v1/results/${e}/project`,s)).id,u=await b(l);if("completed"===u.status){const o=(await g("GET",`/v1/results/${l}`)).summary??{},n=o.variable_stats??{},i=[];i.push({type:"text",text:[`Projected Variable: ${t} (${a??"mean"}) — job: ${l}`,`Parent SOM: ${e} | Samples: ${o.n_samples??0}`,"",`Variable Statistics (per-node ${a??"mean"}):`,`  Min:  ${void 0!==n.min?Number(n.min).toFixed(3):"N/A"}`,`  Max:  ${void 0!==n.max?Number(n.max).toFixed(3):"N/A"}`,`  Mean: ${void 0!==n.mean?Number(n.mean).toFixed(3):"N/A"}`,`  Nodes with data: ${n.n_nodes_with_data??"N/A"}`].join("\n")});const s=t.replace(/[^a-zA-Z0-9_]/g,"_"),u=o.output_format??r??"pdf";return await T(i,l,`projected_${s}.${u}`),{content:i}}return"failed"===u.status?{content:[{type:"text",text:`Projection job ${l} failed: ${u.error??"unknown error"}`}]}:{content:[{type:"text",text:["Variable projection job submitted but did not complete within 30s.",`Projection job ID: ${l}`,"",`Poll with: get_job_status(job_id="${l}")`,`Retrieve with: get_results(job_id="${l}")`].join("\n")}]}}),_.tool("transition_flow",'Compute temporal transition flow for a trained SOM.\n\nShows how data points move between SOM nodes over time — revealing directional\npatterns, cycles, and state machine behavior in sequential data.\n\n**Requires time-ordered data.** Each row must represent a consecutive observation;\nthe transition from row i to row i+lag is counted. If rows are not time-ordered,\nresults will be meaningless.\n\nBest used for:\n- **Time-series dynamics**: how does the system state evolve step-by-step?\n- **Cyclic processes**: daily/weekly patterns, recurring operating modes\n- **Process monitoring**: identify common transition paths and bottlenecks\n- **Regime detection**: find absorbing states (nodes with self-loops) vs transient hubs\n\n**lag** controls the temporal horizon:\n- lag=1 (default): immediate next-step transitions — "where does the system go next?"\n- lag=N: transitions N steps apart — useful for periodic analysis (e.g. lag=24 for daily cycles in hourly data)\n- Try multiple lags to reveal different temporal scales.\n\n**min_transitions** filters noisy arrows — only transitions observed at least this many times are drawn. Increase for cleaner plots on large datasets.\n\n**top_k** controls how many top-flow nodes are reported in statistics.\n\nBEFORE calling, confirm:\n- Data is time-ordered (chronological row sequence)\n- The lag makes sense for the time resolution (e.g. lag=1 for hourly data = 1 hour ahead)\n\nAfter showing results, discuss:\n- Arrow direction and clustering patterns\n- Hub nodes (many transitions through them) vs absorbing nodes (self-loops)\n- Whether cyclic flow matches known periodic behavior',{job_id:o.string().describe("ID of the completed SOM training job"),lag:o.number().int().min(1).optional().default(1).describe("Step lag for transition pairs (default 1 = consecutive rows). Use larger values for periodic analysis (e.g. 24 for daily cycles in hourly data)."),min_transitions:o.number().int().min(1).optional().describe("Minimum transition count to draw an arrow (default: auto). Increase to filter noise on large datasets."),top_k:o.number().int().min(1).optional().default(10).describe("Number of top-flow nodes to include in statistics (default 10)."),colormap:o.string().optional().describe("Colormap for the U-matrix background (default: grays). Try viridis, plasma, or inferno for more contrast."),output_format:o.enum(["png","pdf","svg"]).optional().default("pdf").describe("Image output format for the flow plot (default: pdf)."),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x), print (4x).")},async({job_id:e,lag:t,min_transitions:o,top_k:a,colormap:r,output_format:n,output_dpi:i})=>{const s={lag:t??1,output_format:n??"pdf"};void 0!==o&&(s.min_transitions=o),void 0!==a&&(s.top_k=a),void 0!==r&&(s.colormap=r),i&&"retina"!==i&&(s.output_dpi={standard:1,retina:2,print:4}[i]??2);const l=(await g("POST",`/v1/results/${e}/transition-flow`,s)).id,u=await b(l);if("completed"===u.status){const o=(await g("GET",`/v1/results/${l}`)).summary??{},a=o.flow_stats??{},r=[];r.push({type:"text",text:[`Transition Flow Results (job: ${l})`,`Parent SOM: ${e} | Lag: ${t??1} | Samples: ${o.n_samples??0}`,"","Flow Statistics:",`  Active flow nodes:  ${a.active_flow_nodes??"N/A"}`,`  Total transitions:  ${a.total_transitions??"N/A"}`,`  Mean magnitude:     ${void 0!==a.mean_magnitude?Number(a.mean_magnitude).toFixed(4):"N/A"}`].join("\n")});const i=n??"pdf";return await T(r,l,`transition_flow_lag${t??1}.${i}`),{content:r}}return"failed"===u.status?{content:[{type:"text",text:`Transition flow job ${l} failed: ${u.error??"unknown error"}`}]}:{content:[{type:"text",text:["Transition flow job submitted but did not complete within 30s.",`Flow job ID: ${l}`,`Parent job: ${e} | Lag: ${t??1}`,"",`Poll with: get_job_status(job_id="${l}")`,`Retrieve with: get_results(job_id="${l}")`].join("\n")}]}}),_.tool("derive_variable",'Create a derived variable from existing dataset columns using mathematical expressions.\n\nBEST FOR: Computing ratios, differences, log transforms, rolling statistics,\nor any combination of existing columns — either to enrich a dataset before\ntraining or to project a computed variable onto an existing SOM.\n\nTWO MODES:\n1. Add to dataset (default): computes the new column and appends it to the dataset CSV.\n   The column is then available for future train_som calls via the \'columns\' parameter.\n2. Project onto SOM: computes the column from the training dataset and projects it\n   onto a trained SOM, returning the visualization. Use this to explore how\n   derived quantities distribute across the learned map structure.\n\nCOMMON FORMULAS:\n- Ratio:       "revenue / cost"\n- Difference:  "US10Y - US3M"\n- Log return:  "log(close) - log(open)"\n- Z-score:     "(volume - rolling_mean(volume, 20)) / rolling_std(volume, 20)"\n- Magnitude:   "sqrt(x^2 + y^2)"\n- Unit convert: "temperature - 273.15"\n- First diff:  "diff(consumption)"\n\nSUPPORTED FUNCTIONS:\n- Arithmetic: +, -, *, /, ^\n- Math: log, log1p, log10, exp, sqrt, abs, sign, clamp, min, max\n- Trig: sin, cos, tan, asin, acos, atan\n- Rolling: rolling_mean(col, window), rolling_std(col, window), rolling_min, rolling_max\n- Temporal: diff(col), diff(col, n)\n- Constants: pi, numeric literals\n\nWORKFLOW: Ask the user what domain-specific variables they care about.\nSuggest derived variables based on the column names. For example, if\nthe dataset has "revenue" and "cost", suggest "revenue - cost" as profit\nand "revenue / cost" as cost efficiency.\n\nEXPRESSION REFERENCE: In expressions, use underscore-normalized column names (e.g. fixed_acidity not "fixed acidity"). Column names with spaces/special chars are converted to underscores — use that form. Operators: +, -, *, /, ^. Functions: log, sqrt, rolling_mean(col, window), diff(col), etc.\n\nCOMMON MISTAKES:\n- Division by zero: if denominator column has zeros, use options.missing="skip"\n- Rolling functions produce NaN for the first (window-1) rows\n- diff() produces NaN for the first row\n- Spaces in column names: use underscores (e.g. fixed_acidity not "fixed acidity")',{dataset_id:o.string().describe("Dataset ID (source of column data)"),name:o.string().describe("Name for the derived variable (used in column header and visualization)"),expression:o.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:o.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:o.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:o.object({missing:o.enum(["skip","zero","interpolate"]).optional().default("skip").describe("How to handle NaN/missing values in the result"),window:o.number().int().optional().describe("Default window size for rolling functions (default 20)"),description:o.string().optional().describe("Human-readable description of what this variable represents")}).optional().describe("Configuration for expression evaluation"),output_format:o.enum(["png","pdf","svg"]).optional().default("pdf").describe("Image format for projection visualization when project_onto_job is set (default: pdf)."),output_dpi:o.enum(["standard","retina","print"]).optional().default("retina").describe("Resolution for projection visualization"),colormap:o.string().optional().describe("Colormap for projection visualization (default: coolwarm). Examples: viridis, plasma, inferno, magma, cividis, turbo, coolwarm, RdBu, Spectral.")},async({dataset_id:e,name:t,expression:o,project_onto_job:a,aggregation:r,options:n,output_format:i,output_dpi:s,colormap:l})=>{const u={standard:1,retina:2,print:4};if(a){const e={name:t,expression:o,aggregation:r??"mean",output_format:i??"pdf"};n&&(e.options=n),s&&"retina"!==s&&(e.output_dpi=u[s]??2),l&&(e.colormap=l);const d=(await g("POST",`/v1/results/${a}/derive`,e)).id,c=await b(d);if("completed"===c.status){const e=(await g("GET",`/v1/results/${d}`)).summary??{},n=e.variable_stats??{},s=[];s.push({type:"text",text:[`Derived Variable Projected: ${t} — job: ${d}`,`Expression: ${o}`,`Parent SOM: ${a} | Aggregation: ${r??"mean"}`,"",`Statistics (per-node ${r??"mean"}):`,`  Min:  ${void 0!==n.min?Number(n.min).toFixed(3):"N/A"}`,`  Max:  ${void 0!==n.max?Number(n.max).toFixed(3):"N/A"}`,`  Mean: ${void 0!==n.mean?Number(n.mean).toFixed(3):"N/A"}`,`  Nodes with data: ${n.n_nodes_with_data??"N/A"}`,e.nan_count?`  NaN values: ${e.nan_count}`:""].filter(e=>""!==e).join("\n")});const l=t.replace(/[^a-zA-Z0-9_]/g,"_"),u=e.output_format??i??"pdf";return await T(s,d,`projected_${l}.${u}`),{content:s}}return"failed"===c.status?{content:[{type:"text",text:`Derive+project job ${d} failed: ${c.error??"unknown error"}`}]}:{content:[{type:"text",text:`Derive job submitted. Poll: get_job_status("${d}")`}]}}{const a={name:t,expression:o};n&&(a.options=n);const r=(await g("POST",`/v1/datasets/${e}/derive`,a)).id,i=await b(r);if("completed"===i.status){const a=(await g("GET",`/v1/results/${r}`)).summary??{};return{content:[{type:"text",text:[`Derived column "${t}" added to dataset ${e}`,`Expression: ${o}`,`Rows: ${a.n_rows??"?"}`,a.nan_count?`NaN values: ${a.nan_count}`:"",`Min: ${a.min??"?"} | Max: ${a.max??"?"} | Mean: ${a.mean??"?"}`,"","The column is now available in the dataset. Include it in train_som","via the 'columns' parameter, or use datasets(action=preview) to verify."].filter(e=>""!==e).join("\n")}]}}return"failed"===i.status?{content:[{type:"text",text:`Derive variable job ${r} failed: ${i.error??"unknown error"}`}]}:{content:[{type:"text",text:`Derive job submitted. Poll: get_job_status("${r}")`}]}}}),_.tool("manage_account","Manage compute leases, check account status, and view billing history.\nYour default backend is your local Primary Server. Use this tool to temporarily upgrade to cloud compute for heavy jobs.\n\nActions:\n- request_compute: Provisions a cloud burst instance (requires tier and duration_minutes). Leaves tier blank to list options.\n- compute_status: Checks if a burst lease is active and how much time remains.\n- release_compute: Manually terminates an active lease and reverts routing to the Primary Server.\n- compute_history: Views recent compute leases and credit spend.\n- add_funds: Instructions on how to add credits to your account.",{action:{type:"string",description:"One of: request_compute, compute_status, release_compute, compute_history, add_funds"},tier:{type:"string",description:"Compute tier ID (e.g., cpu-8, gpu-t4). Leave empty during request_compute to list tiers.",optional:!0},duration_minutes:{type:"number",description:"How long to lease the instance (default: 60)",optional:!0},limit:{type:"number",description:"Number of records to fetch for compute_history (default: 10)",optional:!0}},async({action:e,tier:t,duration_minutes:o,limit:a})=>{if("request_compute"===e){if(!t)return{content:[{type:"text",text:"Available Compute Tiers:\nCPU Tiers:\n  cpu-8: 16 vCPUs, 32 GB RAM (~$0.20/hr)\n  cpu-16: 32 vCPUs, 64 GB RAM (~$0.20/hr)\n  cpu-24: 48 vCPUs, 96 GB RAM (~$0.28/hr)\n  cpu-32: 64 vCPUs, 128 GB RAM (~$0.42/hr)\n  cpu-48: 96 vCPUs, 192 GB RAM (~$0.49/hr)\nGPU Tiers:\n  gpu-t4: 8 vCPUs, 32 GB, T4 16GB VRAM (~$0.22/hr)\n  gpu-t4x: 16 vCPUs, 64 GB, T4 16GB VRAM (~$0.36/hr)\n  gpu-t4xx: 32 vCPUs, 128 GB, T4 16GB VRAM (~$0.27/hr)\n  gpu-l4: 8 vCPUs, 32 GB, L4 24GB VRAM (~$0.41/hr)\n  gpu-l4x: 16 vCPUs, 64 GB, L4 24GB VRAM (~$0.37/hr)\n  gpu-a10: 8 vCPUs, 32 GB, A10G 24GB VRAM (~$0.51/hr)\n  gpu-a10x: 16 vCPUs, 64 GB, A10G 24GB VRAM (~$0.52/hr)"}]};const e=await g("POST","/v1/compute/lease",{tier:t,duration_minutes:o});return{content:[{type:"text",text:`Compute Lease Requested:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nEstimated Wait: ${e.estimated_wait_minutes} minutes\nEstimated Cost: $${(e.estimated_cost_cents/100).toFixed(2)}\nCredits Remaining After Reserve: $${(e.credit_balance_cents/100).toFixed(2)}\n\nIMPORTANT: Cloud burst active. Data is pulled from shared Cloudflare R2, so you do NOT need to re-upload datasets. Just wait ~3 minutes and check status.`}]}}if("compute_status"===e){const e=await g("GET","/v1/compute/lease");return"none"!==e.status&&e.lease_id?{content:[{type:"text",text:`Active Compute Lease:\nLease ID: ${e.lease_id}\nStatus: ${e.status}\nTier: ${e.tier} (${e.instance_type})\nTime Remaining: ${Math.round(e.time_remaining_ms/6e4)} minutes`}]}:{content:[{type:"text",text:"No active lease -- running on default Primary Server."}]}}if("release_compute"===e){const e=await g("DELETE","/v1/compute/lease");return{content:[{type:"text",text:`Compute Released:\nDuration Billed: ${e.duration_minutes} minutes\nCredits Deducted: $${(e.credits_deducted/100).toFixed(2)}\nFinal Balance: $${(e.final_balance_cents/100).toFixed(2)}\n\nRouting reverted to default Primary Server.`}]}}if("compute_history"===e){const e=await g("GET",`/v1/compute/history?limit=${a||10}`),t=e.history.map(e=>`- ${e.started_at} | ${e.tier} | ${e.duration_minutes} min | $${(e.credits_charged/100).toFixed(2)}`).join("\n");return{content:[{type:"text",text:`Credit Balance: $${(e.credit_balance_cents/100).toFixed(2)}\n\nRecent Usage:\n${t}`}]}}return"add_funds"===e?{content:[{type:"text",text:"To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:\nbash scripts/manage-credits.sh add <org_id> <amount_usd>"}]}:{content:[{type:"text",text:`Unknown action: ${e}. Valid actions are request_compute, compute_status, release_compute, compute_history, add_funds.`}]}}),_.tool("license_info","Get plan/license capabilities, backend info, live status, and training time estimates.\n\nReturns what the current API key is connected to: plan tier, compute class\n(CPU/GPU), usage limits, backend hardware details, job queue state, and\nestimated training times.\n\nUse this BEFORE submitting large jobs to:\n- See your plan's compute class and whether GPU is available\n- Check queue depth to decide whether to wait or proceed\n- Estimate wall-clock time based on the current topology",{},async()=>{const e=await g("GET","/v1/system/info"),t=e.plan??{},o=e.backend??{},a=e.status??{},r=e.training_time_estimates_seconds??{},n=e.worker_topology??{},i=t.gpu_enabled??e.gpu_available??!1?o.gpu_model?`GPU-accelerated (${o.gpu_model}${o.gpu_vram_gb?`, ${o.gpu_vram_gb} GB VRAM`:""})`:"GPU-accelerated":"CPU only",s=e=>-1===e||"-1"===e?"unlimited":String(e??"?"),l=await g("GET","/v1/compute/lease").catch(()=>null),u=await g("GET","/v1/compute/history?limit=30").catch(()=>null),d=[`Your Plan: ${String(t.tier??"unknown").charAt(0).toUpperCase()}${String(t.tier??"unknown").slice(1)}`,`  Priority:      ${t.priority??"normal"}`,`  Concurrency:   ${t.max_concurrent_jobs??"?"} simultaneous job${1!==t.max_concurrent_jobs?"s":""}`,`  Datasets:      ${s(t.max_datasets)} max, ${s(t.max_dataset_rows)} rows each`,`  Monthly Jobs:  ${s(t.max_monthly_jobs)}`,`  Grid Size:     ${s(t.max_grid_size)} max`,`  Features:      ${s(t.max_features)} max`];u&&d.push("",`Compute Credits:  $${(u.credit_balance_cents/100).toFixed(2)} remaining`),d.push("","Default Backend:",`  Label:         ${o.label??"unknown"}`,`  Compute:       ${i}`),o.memory_gb&&d.push(`  Memory:        ${o.memory_gb} GB`),l&&l.lease_id&&d.push("","Active Compute Lease (Burst):",`  Status:        ${l.status}`,`  Tier:          ${l.tier} (${l.instance_type})`,`  Time Left:     ${Math.round(l.time_remaining_ms/6e4)} min`);const c=Number(a.running_jobs??e.running_jobs??0),p=Number(a.pending_jobs??e.pending_jobs??0),m=Number(a.queue_depth??e.queue_depth??0),f=a.free_memory_gb??e.free_memory_gb,h=(p+1)*Number(e.training_time_estimates_seconds?.total||0);return d.push("","Live Status:",`  Running Jobs:  ${c}`,`  Pending Jobs:  ${p}`,`  Queue Depth:   ${m}`,`  Current Wait:  ~${Math.round(h/60)} minutes (before your job starts)`),void 0!==f&&d.push(`  Free Memory:   ${f} GB`),void 0!==n.num_workers&&d.push("","Worker Topology:",`  Workers:             ${n.num_workers} × ${n.threads_per_worker} threads`,`  Total Thread Budget: ${n.total_thread_budget}`),Object.keys(r).length>0&&(d.push("","Estimated Training Times (seconds):",...Object.entries(r).filter(([e])=>"formula"!==e).map(([e,t])=>`  ${e}: ~${t}s`)),r.formula&&d.push(`  ${r.formula}`)),{content:[{type:"text",text:d.join("\n")}]}}),_.prompt("info","Overview of the Barivia SOM MCP: capabilities, workflow, tools, analysis types, and tips. Use when the user asks what this MCP can do, how to get started, or what the process is.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Inform the user using this overview:","","**What it is:** Barivia MCP connects you to a Self-Organizing Map (SOM) analytics engine. SOMs learn a 2D map from high-dimensional data for visualization, clustering, pattern discovery, and temporal analysis.","","**Core workflow:**","1. **Upload** — `datasets(action=upload)` with a CSV file path or inline data","2. **Preview** — `datasets(action=preview)` to inspect columns, stats, and detect cyclic/datetime fields","3. **Prepare** — use the `prepare_training` prompt for a guided checklist (column selection, transforms, cyclic encoding, feature weights, grid sizing)","4. **Train** — `train_som` with grid size, epochs, model type, and preprocessing options. Use `preset=quick|standard|refined|high_res` for sensible defaults","5. **Monitor** — `get_job_status` to track progress; `get_results` to retrieve figures when complete","6. **Analyze** — `analyze` with various analysis types (see below)","7. **Iterate** — `recolor_som` to change colormap without retraining, `compare_runs` to compare hyperparameters, `project_variable` to overlay new variables","","**Analysis types** (via `analyze`):","- `u_matrix` — cluster boundary distances","- `component_planes` — per-feature heatmaps","- `clusters` — automatic cluster detection and statistics","- `quality_report` — QE, TE, explained variance, trustworthiness, neighborhood preservation","- `hit_histogram` — data density across the map","- `transition_flow` — temporal flow patterns (requires time-ordered data)","","**Data tools:**","- `datasets(action=subset)` — filter by row range, value thresholds (gt/lt/gte/lte), equality, or set membership. Combine row_range + filter","- `derive_variable` — create computed columns from expressions (ratios, differences, etc.)","- `project_variable` — overlay any variable onto a trained SOM","","**Output options:** Format (png/pdf/svg) and colormap (coolwarm, viridis, plasma, inferno, etc.) can be set at training or changed later via recolor_som.","","**Key tools:** datasets, list, train_som, get_job_status, get_results, analyze, recolor_som, download_results, project_variable, transition_flow, compare_runs, derive_variable, license_info, explore_som.","","**Tips:**","- Always `preview` before training to understand your data","- Use `license_info` to check GPU availability and plan limits before large jobs","- Start with `preset=quick` for fast iteration, then `refined` for publication quality","- For time-series data, consider `transition_flow` after training","","Keep the reply scannable with headers and bullet points."].join("\n")}}]})),_.prompt("prepare_training","Guided pre-training checklist. Use after uploading a dataset and before calling train_som. Walks through data inspection, column selection, transforms, cyclic/temporal features, weighting, subsetting, and grid sizing.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{let t=`Please run datasets(action="preview", dataset_id="${e}") first, then call train_som with appropriate parameters or preset.`;try{const o=await g("GET",`/v1/docs/prepare_training?dataset_id=${e}`);o.prompt&&(t=o.prompt)}catch(e){}return{messages:[{role:"user",content:{type:"text",text:t}}]}});const E=new t;_.tool("send_feedback",'Send brief feedback or feature requests to Barivia developers (max 190 words). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but you should proactively generate feedback text based on the user\'s workflow or errors encountered and ask them "Would you like me to send this feedback to the developers?". Once they accept, call this tool.',{feedback:o.string().max(1330).describe("Feedback text")},async({feedback:e})=>h(await g("POST","/v1/feedback",{feedback:e}))),async function(){await _.connect(E)}().catch(console.error);