@claude-flow/cli 3.18.2 → 3.20.0

package/dist/src/services/native-training.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Native training via @ruvector/ruvllm's TrainingPipeline (#2549 follow-up).
+ *
+ * `neural train` historically trained only on the RuVector WASM path
+ * (MicroLoRA + InfoNCE) and its "checkpoint" was a freshly-constructed
+ * adapter's weights — the native TrainingPipeline (real epochs, loss
+ * history, early stopping, EWC registration, disk checkpoints since
+ * ruvllm 2.5.7) was never exercised. This service routes the LoRA
+ * training leg through it.
+ *
+ * Batch formulation: pattern-alignment pairs — input = embedding[i],
+ * target = embedding[i+1 mod n], quality 1.0 — the MSE analogue of the
+ * WASM path's anchor→positive contrastive objective (adjacent training
+ * items belong to the same pattern family by construction).
+ *
+ * Graceful: returns null when @ruvector/ruvllm is absent or anything
+ * throws — callers fall back to the WASM path.
+ */
+export interface NativeTrainingResult {
+    epochs: number;
+    steps: number;
+    finalLoss: number;
+    bestValLoss: number | null;
+    durationMs: number;
+    earlyStopped: boolean;
+    checkpointPath?: string;
+    checkpointBytes?: number;
+    /** True when training resumed from a --resume checkpoint. */
+    resumed?: boolean;
+    /**
+     * How the resume happened: 'resumeFrom' (ruvllm >=2.6.0 — restores epoch
+     * position + optimizer state) or 'loadCheckpoint' (2.5.7 fallback —
+     * weights only, training restarts from epoch 0).
+     */
+    resumeMode?: 'resumeFrom' | 'loadCheckpoint';
+}
+export interface NativeTrainingOptions {
+    embeddings: Float32Array[];
+    epochs: number;
+    batchSize: number;
+    learningRate: number;
+    dim: number;
+    /**
+     * Validation holdout fraction (0..1). >0 makes the pipeline report
+     * bestValLoss + early-stopping; 0 (or omitted) disables validation.
+     * validationSplit exists in ruvllm 2.5.7 — no version gate needed.
+     */
+    validationSplit?: number;
+    /**
+     * Resume weights (and, on >=2.6.0, epoch position) from this checkpoint
+     * BEFORE training. A missing/invalid path throws ResumeFailedError — an
+     * explicit --resume must fail loudly, never silently fresh-train.
+     */
+    resumeFrom?: string;
+    /** When set, the TRAINED pipeline checkpoints here (ruvllm >=2.5.7). */
+    checkpointPath?: string;
+}
+/**
+ * Thrown when an explicit --resume checkpoint cannot be found or loaded.
+ * Distinct from the generic "native unavailable → null" degradation so the
+ * caller can surface a loud, exit-1 failure rather than fresh training.
+ */
+export declare class ResumeFailedError extends Error {
+    constructor(message: string);
+}
+export declare function nativeTrainingAvailable(): boolean;
+export declare function runNativeTraining(opts: NativeTrainingOptions): Promise<NativeTrainingResult | null>;
+//# sourceMappingURL=native-training.d.ts.map

package/dist/src/services/native-training.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-training.d.ts","sourceRoot":"","sources":["../../../src/services/native-training.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;CAC9C;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAOjD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAsGtC"}

package/dist/src/services/native-training.js

@@ -0,0 +1,141 @@
+/**
+ * Native training via @ruvector/ruvllm's TrainingPipeline (#2549 follow-up).
+ *
+ * `neural train` historically trained only on the RuVector WASM path
+ * (MicroLoRA + InfoNCE) and its "checkpoint" was a freshly-constructed
+ * adapter's weights — the native TrainingPipeline (real epochs, loss
+ * history, early stopping, EWC registration, disk checkpoints since
+ * ruvllm 2.5.7) was never exercised. This service routes the LoRA
+ * training leg through it.
+ *
+ * Batch formulation: pattern-alignment pairs — input = embedding[i],
+ * target = embedding[i+1 mod n], quality 1.0 — the MSE analogue of the
+ * WASM path's anchor→positive contrastive objective (adjacent training
+ * items belong to the same pattern family by construction).
+ *
+ * Graceful: returns null when @ruvector/ruvllm is absent or anything
+ * throws — callers fall back to the WASM path.
+ */
+import { createRequire } from 'module';
+import { mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+/**
+ * Thrown when an explicit --resume checkpoint cannot be found or loaded.
+ * Distinct from the generic "native unavailable → null" degradation so the
+ * caller can surface a loud, exit-1 failure rather than fresh training.
+ */
+export class ResumeFailedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResumeFailedError';
+    }
+}
+export function nativeTrainingAvailable() {
+    try {
+        createRequire(import.meta.url).resolve('@ruvector/ruvllm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runNativeTraining(opts) {
+    const { embeddings, epochs, batchSize, learningRate, dim, validationSplit, resumeFrom, checkpointPath } = opts;
+    if (embeddings.length < 2)
+        return null;
+    try {
+        const req = createRequire(import.meta.url);
+        const ruvllm = req('@ruvector/ruvllm');
+        const pipelineConfig = {
+            learningRate,
+            batchSize,
+            epochs,
+            inputDim: dim,
+            outputDim: dim,
+        };
+        // 0 (or omitted) disables validation; only pass a real holdout through.
+        if (typeof validationSplit === 'number' && validationSplit > 0) {
+            pipelineConfig.validationSplit = validationSplit;
+        }
+        const pipeline = new ruvllm.TrainingPipeline(pipelineConfig);
+        // Resume BEFORE training. Prefer resumeFrom() (2.6.0 — epoch position +
+        // optimizer state); fall back to loadCheckpoint() (2.5.7 — weights only).
+        // Any failure with an explicit --resume is loud (ResumeFailedError),
+        // never silent fresh training.
+        let resumed = false;
+        let resumeMode;
+        if (resumeFrom) {
+            if (!existsSync(resumeFrom)) {
+                throw new ResumeFailedError(`--resume checkpoint not found: ${resumeFrom}`);
+            }
+            try {
+                if (typeof pipeline.resumeFrom === 'function') {
+                    pipeline.resumeFrom(resumeFrom);
+                    resumeMode = 'resumeFrom';
+                }
+                else {
+                    const ok = pipeline.loadCheckpoint(resumeFrom);
+                    if (ok === false)
+                        throw new Error('loadCheckpoint returned false');
+                    resumeMode = 'loadCheckpoint';
+                }
+                resumed = true;
+            }
+            catch (e) {
+                if (e instanceof ResumeFailedError)
+                    throw e;
+                throw new ResumeFailedError(`--resume failed to load checkpoint ${resumeFrom}: ${e.message}`);
+            }
+        }
+        // Pattern-alignment pairs, chunked into pipeline batches.
+        const inputs = [];
+        const targets = [];
+        const qualities = [];
+        for (let i = 0; i < embeddings.length; i++) {
+            inputs.push(Array.from(embeddings[i]));
+            targets.push(Array.from(embeddings[(i + 1) % embeddings.length]));
+            qualities.push(1.0);
+        }
+        for (let i = 0; i < inputs.length; i += batchSize) {
+            pipeline.addBatch(inputs.slice(i, i + batchSize), targets.slice(i, i + batchSize), qualities.slice(i, i + batchSize));
+        }
+        const r = pipeline.train();
+        // When validation is disabled the pipeline reports Infinity for
+        // bestValLoss — normalize any non-finite value to null so downstream
+        // "bestValLoss !== null ⇒ validation ran" holds for the results table.
+        const bestValLoss = typeof r.bestValLoss === 'number' && Number.isFinite(r.bestValLoss)
+            ? r.bestValLoss
+            : null;
+        const result = {
+            epochs: r.epochs,
+            steps: r.steps,
+            finalLoss: r.finalLoss,
+            bestValLoss,
+            durationMs: r.durationMs,
+            earlyStopped: !!r.earlyStopped,
+            resumed,
+            resumeMode,
+        };
+        if (checkpointPath) {
+            try {
+                mkdirSync(dirname(checkpointPath), { recursive: true });
+                const saved = pipeline.saveCheckpoint(checkpointPath);
+                // <2.5.7 returns undefined and writes nothing — verify on disk.
+                if (existsSync(checkpointPath)) {
+                    result.checkpointPath = checkpointPath;
+                    result.checkpointBytes = saved?.bytes;
+                }
+            }
+            catch { /* checkpoint is best-effort; training result stands */ }
+        }
+        return result;
+    }
+    catch (err) {
+        // An explicit --resume failure must propagate as a loud error; every
+        // other failure degrades to null so callers fall back to the WASM path.
+        if (err instanceof ResumeFailedError)
+            throw err;
+        return null;
+    }
+}
+//# sourceMappingURL=native-training.js.map

package/dist/src/services/native-training.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-training.js","sourceRoot":"","sources":["../../../src/services/native-training.ts"],"names":[],"mappings":"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"}