@barivia/barmesh-mcp 0.5.4 → 0.6.0

package/dist/training_review.js

@@ -0,0 +1,182 @@
+/**
+ * Post-hoc review mode for barmesh_training_monitor on already-terminal jobs.
+ * Replays QE curves from training-log and surfaces final timing/metrics.
+ */
+import { apiCall } from "./shared.js";
+import { formatSnapshotLine, snapshotFromJob, } from "./job_monitor.js";
+import { formatJobStatusText } from "./job_status_format.js";
+export const REVIEW_MAX_SNAPSHOTS = 16;
+function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+function hasCurveArrays(data) {
+    const ord = data.ordering_errors;
+    const conv = data.convergence_errors;
+    return ((Array.isArray(ord) && ord.length > 0) || (Array.isArray(conv) && conv.length > 0));
+}
+export async function enrichWithTrainingLog(job_id, data) {
+    if (hasCurveArrays(data))
+        return data;
+    try {
+        const log = (await apiCall("GET", `/v1/results/${job_id}/training-log`));
+        return {
+            ...data,
+            ordering_errors: log.ordering_errors ?? data.ordering_errors,
+            convergence_errors: log.convergence_errors ?? data.convergence_errors,
+            ordering_topographic_errors: log.ordering_topographic_errors ?? data.ordering_topographic_errors,
+            convergence_topographic_errors: log.convergence_topographic_errors ?? data.convergence_topographic_errors,
+            quantization_error: log.quantization_error ?? data.quantization_error,
+            topographic_error: log.topographic_error ?? data.topographic_error,
+            grid: log.grid ?? data.grid,
+            epochs: log.epochs ?? data.epochs,
+            training_duration_seconds: log.training_duration_seconds ?? data.training_duration_seconds,
+            training_curve_source_batches: log.training_curve_source_batches ?? data.training_curve_source_batches,
+        };
+    }
+    catch {
+        return data;
+    }
+}
+/** Evenly sample indices for a compact epoch/QE timeline in review mode. */
+export function sampleReviewIndices(length, maxPoints = REVIEW_MAX_SNAPSHOTS) {
+    if (length <= 0)
+        return [];
+    if (length <= maxPoints)
+        return Array.from({ length }, (_, i) => i);
+    const out = [];
+    for (let i = 0; i < maxPoints; i += 1) {
+        out.push(Math.round((i * (length - 1)) / (maxPoints - 1)));
+    }
+    return [...new Set(out)].sort((a, b) => a - b);
+}
+export function buildCurveSnapshots(ordering, convergence, orderingEpochs) {
+    const snaps = [];
+    const ordIdx = sampleReviewIndices(ordering.length);
+    for (const i of ordIdx) {
+        const qe = ordering[i];
+        if (qe == null || Number.isNaN(Number(qe)))
+            continue;
+        const epoch = ordering.length > 1 && orderingEpochs > 0
+            ? Math.max(1, Math.round(((i + 1) / ordering.length) * orderingEpochs))
+            : i + 1;
+        snaps.push({
+            elapsed_sec: 0,
+            status: "completed",
+            progress_pct: 100,
+            phase: "ordering",
+            epoch,
+            total_epochs: orderingEpochs > 0 ? orderingEpochs : undefined,
+            qe: Math.round(Number(qe) * 10_000) / 10_000,
+            note: i === ordIdx[ordIdx.length - 1] ? "ordering (review)" : undefined,
+        });
+    }
+    if (convergence.length > 0) {
+        const convIdx = sampleReviewIndices(convergence.length, Math.min(6, REVIEW_MAX_SNAPSHOTS));
+        for (const i of convIdx) {
+            const qe = convergence[i];
+            if (qe == null || Number.isNaN(Number(qe)))
+                continue;
+            snaps.push({
+                elapsed_sec: 0,
+                status: "completed",
+                progress_pct: 100,
+                phase: "convergence",
+                qe: Math.round(Number(qe) * 10_000) / 10_000,
+                note: i === convIdx[convIdx.length - 1] ? "convergence (review)" : undefined,
+            });
+        }
+    }
+    return snaps;
+}
+export function formatPhaseBreakdown(data) {
+    const epochs = data.epochs;
+    if (!epochs || epochs.length < 2)
+        return null;
+    const [ord, conv] = epochs;
+    const ordN = Array.isArray(data.ordering_errors) ? data.ordering_errors.length : 0;
+    const convN = Array.isArray(data.convergence_errors) ? data.convergence_errors.length : 0;
+    const parts = [`ordering ${ord} epoch(s)`];
+    if (ordN > 0)
+        parts.push(`${ordN} batch samples logged`);
+    if (conv > 0) {
+        parts.push(`convergence ${conv} epoch(s)`);
+        if (convN > 0)
+            parts.push(`${convN} batch samples`);
+    }
+    return parts.join(", ");
+}
+export function formatTimingSummary(data) {
+    const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
+        ? Math.round(Number(data.wall_elapsed_sec))
+        : null;
+    const kernel = data.kernel_elapsed_sec != null && !Number.isNaN(Number(data.kernel_elapsed_sec))
+        ? Math.round(Number(data.kernel_elapsed_sec))
+        : data.training_elapsed_sec != null && !Number.isNaN(Number(data.training_elapsed_sec))
+            ? Math.round(Number(data.training_elapsed_sec))
+            : data.training_duration_seconds != null
+                ? Math.round(Number(data.training_duration_seconds))
+                : null;
+    if (wall != null && kernel != null && Math.abs(wall - kernel) >= 2) {
+        return `wall ${wall}s, kernel training ${kernel}s`;
+    }
+    if (wall != null)
+        return `wall ${wall}s`;
+    if (kernel != null)
+        return `kernel training ${kernel}s`;
+    return null;
+}
+export function formatReviewMonitorText(result, review) {
+    const lines = [
+        `Job ${result.job_id} monitor (post-hoc review — job already ${result.data.status ?? "terminal"}):`,
+    ];
+    if (review.phaseBreakdown)
+        lines.push(`Phases: ${review.phaseBreakdown}`);
+    if (review.timing)
+        lines.push(`Timing: ${review.timing}`);
+    const qe = result.data.quantization_error;
+    const te = result.data.topographic_error;
+    if (qe != null || te != null) {
+        const qeS = qe != null ? `QE ${Number(qe).toFixed(4)}` : "";
+        const teS = te != null ? `TE ${Number(te).toFixed(4)}` : "";
+        lines.push(`Final: ${[qeS, teS].filter(Boolean).join(", ")}`);
+    }
+    lines.push("");
+    lines.push("Training curve (sampled from ordering_errors / convergence_errors):");
+    for (const s of result.snapshots)
+        lines.push(formatSnapshotLine(s));
+    lines.push("");
+    lines.push(`Terminal: ${result.status_text}`);
+    lines.push(result.suggested_next_step);
+    lines.push("Tip: learning_curve.png is attached when available; use barmesh_results_explorer for all figures.");
+    return lines.join("\n");
+}
+export async function buildPostHocReview(job_id, data, suggested_next_step) {
+    const enriched = await enrichWithTrainingLog(job_id, data);
+    const ordering = enriched.ordering_errors ?? [];
+    const convergence = enriched.convergence_errors ?? [];
+    const epochs = enriched.epochs ?? [];
+    const orderingEpochs = epochs.length > 0 ? Number(epochs[0]) || 0 : 0;
+    let snapshots = buildCurveSnapshots(ordering, convergence, orderingEpochs);
+    if (snapshots.length === 0) {
+        snapshots = [snapshotFromJob(enriched, 0, "post-hoc review (no training-log curves)")];
+    }
+    const statusText = await formatJobStatusText(job_id, enriched);
+    const phaseBreakdown = formatPhaseBreakdown(enriched);
+    const timing = formatTimingSummary(enriched);
+    const result = {
+        job_id,
+        terminal: true,
+        timed_out: false,
+        snapshots,
+        status_text: statusText,
+        data: { ...enriched, monitor_mode: "review" },
+        suggested_next_step,
+    };
+    result.data.status_text = formatReviewMonitorText(result, {
+        phaseBreakdown,
+        timing,
+        mode: "review",
+    });
+    return result;
+}
+export { isTerminalStatus, hasCurveArrays };