🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(neural): route neural train through the native TrainingPipeline (#2549 final follow-up) (#2556)
rUv4bea342e01d9
diff --git a/v3/@claude-flow/cli/__tests__/neural-status-training-backend-2549.test.ts b/v3/@claude-flow/cli/__tests__/neural-status-training-backend-2549.test.tsindex 78e4e4099a..03365fb904 100644--- a/v3/@claude-flow/cli/__tests__/neural-status-training-backend-2549.test.ts+++ b/v3/@claude-flow/cli/__tests__/neural-status-training-backend-2549.test.ts@@ -81,3 +81,37 @@ describe('#2549 follow-up — native checkpoint capability gate', () => {expect(nativeCheckpointsSupported()).toBe(expected);});});++describe('#2549 follow-up — native training routing', () => {+ it('runNativeTraining trains and checkpoints through the native pipeline', async () => {+ const { runNativeTraining, nativeTrainingAvailable } = await import('../src/services/native-training.js');+ if (!nativeTrainingAvailable()) {+ expect(await runNativeTraining({ embeddings: [], epochs: 1, batchSize: 2, learningRate: 0.01, dim: 8 })).toBeNull();+ return;+ }+ const { mkdtempSync, existsSync, rmSync } = await import('node:fs');+ const { join } = await import('node:path');+ const { tmpdir } = await import('node:os');+ const dir = mkdtempSync(join(tmpdir(), 'native-train-'));+ try {+ const embeddings = Array.from({ length: 6 }, (_, s) =>+ Float32Array.from({ length: 8 }, (_, i) => Math.sin(s + i)));+ const cp = join(dir, 'ckpt.json');+ const r = await runNativeTraining({+ embeddings, epochs: 2, batchSize: 2, learningRate: 0.01, dim: 8, checkpointPath: cp,+ });+ expect(r).not.toBeNull();+ expect(typeof r!.finalLoss).toBe('number');+ expect(r!.steps).toBeGreaterThan(0);+ expect(r!.checkpointPath).toBe(cp);+ expect(existsSync(cp)).toBe(true);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it('returns null rather than throwing on degenerate input', async () => {+ const { runNativeTraining } = await import('../src/services/native-training.js');+ expect(await runNativeTraining({ embeddings: [new Float32Array(8)], epochs: 1, batchSize: 2, learningRate: 0.01, dim: 8 })).toBeNull();+ });+});diff --git a/v3/@claude-flow/cli/src/commands/neural.ts b/v3/@claude-flow/cli/src/commands/neural.tsindex c75f8bf71b..f31eba02f5 100644--- a/v3/@claude-flow/cli/src/commands/neural.ts+++ b/v3/@claude-flow/cli/src/commands/neural.ts@@ -26,6 +26,7 @@ const trainCommand: Command = {{ name: 'hyperbolic', type: 'boolean', description: 'Enable hyperbolic attention for hierarchical patterns', default: 'false' },{ name: 'contrastive', type: 'boolean', description: 'Use contrastive learning (InfoNCE)', default: 'true' },{ name: 'curriculum', type: 'boolean', description: 'Enable curriculum learning', default: 'false' },+ { name: 'backend', type: 'string', description: 'Training backend: auto (native when available), native (@ruvector/ruvllm TrainingPipeline, disk checkpoints), wasm (RuVector MicroLoRA/InfoNCE)', default: 'auto' },],examples: [{ command: 'claude-flow neural train -p coordination -e 100', description: 'Train coordination patterns' },@@ -38,6 +39,11 @@ const trainCommand: Command = {const learningRate = parseFloat(ctx.flags['learning-rate'] as string || '0.01');const batchSize = parseInt(ctx.flags['batch-size'] as string || '32', 10);const dim = Math.min(parseInt(ctx.flags.dim as string || '256', 10), 256);+ // #2549 follow-up — backend routing: 'native' = @ruvector/ruvllm+ // TrainingPipeline (real epochs/early-stopping/disk checkpoints),+ // 'wasm' = RuVector MicroLoRA/InfoNCE (pre-3.19 behavior),+ // 'auto' = native when the module resolves, else wasm.+ const backendFlag = String(ctx.flags.backend || 'auto');const useWasm = ctx.flags.wasm !== false;const useFlash = ctx.flags.flash !== false;const useMoE = ctx.flags.moe === true;@@ -204,6 +210,35 @@ const trainCommand: Command = {spinner.setText(`Training with ${embeddings.length} embeddings...`);+ // #2549 — native TrainingPipeline leg. In 'auto'/'native' mode the+ // LoRA training runs through @ruvector/ruvllm with the checkpoint+ // taken from the TRAINED pipeline (the old best-effort block saved+ // a fresh adapter's untrained weights). SONA/ReasoningBank+ // persistence in the loop below runs regardless of backend.+ const nativeTraining = await import('../services/native-training.js');+ const useNative = backendFlag === 'native'+ || (backendFlag === 'auto' && nativeTraining.nativeTrainingAvailable());+ let nativeResult: import('../services/native-training.js').NativeTrainingResult | null = null;+ if (useNative) {+ spinner.setText(`Training ${patternType} on native @ruvector/ruvllm pipeline...`);+ const path = await import('path');+ nativeResult = await nativeTraining.runNativeTraining({+ embeddings,+ epochs,+ batchSize,+ learningRate,+ dim,+ checkpointPath: path.join(process.cwd(), '.claude-flow', 'neural', `lora-checkpoint-${Date.now()}.json`),+ });+ if (!nativeResult && backendFlag === 'native') {+ spinner.fail('Native backend requested (--backend native) but @ruvector/ruvllm training failed');+ return { success: false, exitCode: 1 };+ }+ }+ // Native handles the LoRA leg; WASM contrastive runs when native+ // didn't (absent module, or explicit --backend wasm).+ const runWasmLeg = !nativeResult;+// Main training loop with WASM accelerationfor (let epoch = 0; epoch < epochs; epoch++) {const epochStart = performance.now();@@ -218,7 +253,7 @@ const trainCommand: Command = {if (batch.length === 0) continue;// Training step with contrastive learning- if (useContrastive && batch.length >= 3 && useWasm && wasmFeatures.length > 0) {+ if (runWasmLeg && useContrastive && batch.length >= 3 && useWasm && wasmFeatures.length > 0) {const anchor = batch[0];const positives = [batch[1]];const negatives = batch.slice(2);@@ -302,16 +337,21 @@ const trainCommand: Command = {flushPatterns();const persistence = getPersistenceStatus();- // Save LoRA checkpoint via ruvllm TrainingPipeline if available- try {- const { LoRAAdapter } = await import('../ruvector/lora-adapter.js');- const path = await import('path');- const cpDir = path.join(process.cwd(), '.claude-flow', 'neural');- const cpPath = path.join(cpDir, `lora-checkpoint-${Date.now()}.json`);- const adapter = new LoRAAdapter({ inputDim: dim, outputDim: dim, rank: 4 });- await adapter.initBackend();- await adapter.saveCheckpoint(cpPath);- } catch { /* checkpoint save is best-effort */ }+ // Checkpoint: when the native pipeline trained, its checkpoint (the+ // TRAINED weights) was already written by runNativeTraining. The+ // pre-3.19 fallback below saved a FRESH adapter's weights — only+ // meaningful as a fallback when the native leg didn't run.+ if (!nativeResult?.checkpointPath) {+ try {+ const { LoRAAdapter } = await import('../ruvector/lora-adapter.js');+ const path = await import('path');+ const cpDir = path.join(process.cwd(), '.claude-flow', 'neural');+ const cpPath = path.join(cpDir, `lora-checkpoint-${Date.now()}.json`);+ const adapter = new LoRAAdapter({ inputDim: dim, outputDim: dim, rank: 4 });+ await adapter.initBackend();+ await adapter.saveCheckpoint(cpPath);+ } catch { /* checkpoint save is best-effort */ }+ }output.writeln();@@ -328,8 +368,24 @@ const trainCommand: Command = {{ metric: 'Avg Epoch Time', value: `${(epochTimes.reduce((a, b) => a + b, 0) / epochTimes.length).toFixed(2)}ms` },];+ // Native pipeline metrics (#2549 — the LoRA leg trained on ruvllm)+ if (nativeResult) {+ tableData.push(+ { metric: 'Backend', value: 'native (@ruvector/ruvllm TrainingPipeline)' },+ { metric: 'Native Steps', value: String(nativeResult.steps) },+ { metric: 'Final Loss', value: nativeResult.finalLoss.toExponential(3) },+ { metric: 'Early Stopped', value: nativeResult.earlyStopped ? 'yes' : 'no' },+ );+ if (nativeResult.checkpointPath) {+ tableData.push({+ metric: 'Checkpoint',+ value: `${nativeResult.checkpointPath}${nativeResult.checkpointBytes ? ` (${(nativeResult.checkpointBytes / 1024).toFixed(1)} KB)` : ''}`,+ });+ }+ }+// Add WASM-specific metrics- if (useWasm && wasmFeatures.length > 0) {+ if (runWasmLeg && useWasm && wasmFeatures.length > 0) {const backendUsed = ruvectorStats?.backend || 'unknown';tableData.push({ metric: 'Backend', value: backendUsed === 'wasm' ? 'WASM (native)' : 'JS (fallback)' },diff --git a/v3/@claude-flow/cli/src/services/native-training.ts b/v3/@claude-flow/cli/src/services/native-training.tsnew file mode 100644index 0000000000..24d4053867--- /dev/null+++ b/v3/@claude-flow/cli/src/services/native-training.ts@@ -0,0 +1,114 @@+/**+ * 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';++export interface NativeTrainingResult {+ epochs: number;+ steps: number;+ finalLoss: number;+ bestValLoss: number | null;+ durationMs: number;+ earlyStopped: boolean;+ checkpointPath?: string;+ checkpointBytes?: number;+}++export interface NativeTrainingOptions {+ embeddings: Float32Array[];+ epochs: number;+ batchSize: number;+ learningRate: number;+ dim: number;+ /** When set, the TRAINED pipeline checkpoints here (ruvllm >=2.5.7). */+ checkpointPath?: string;+}++export function nativeTrainingAvailable(): boolean {+ try {+ createRequire(import.meta.url).resolve('@ruvector/ruvllm');+ return true;+ } catch {+ return false;+ }+}++export async function runNativeTraining(+ opts: NativeTrainingOptions,+): Promise<NativeTrainingResult | null> {+ const { embeddings, epochs, batchSize, learningRate, dim, checkpointPath } = opts;+ if (embeddings.length < 2) return null;++ try {+ const req = createRequire(import.meta.url);+ const ruvllm = req('@ruvector/ruvllm');+ const pipeline = new ruvllm.TrainingPipeline({+ learningRate,+ batchSize,+ epochs,+ inputDim: dim,+ outputDim: dim,+ });++ // Pattern-alignment pairs, chunked into pipeline batches.+ const inputs: number[][] = [];+ const targets: number[][] = [];+ const qualities: number[] = [];+ 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();+ const result: NativeTrainingResult = {+ epochs: r.epochs,+ steps: r.steps,+ finalLoss: r.finalLoss,+ bestValLoss: r.bestValLoss ?? null,+ durationMs: r.durationMs,+ earlyStopped: !!r.earlyStopped,+ };++ 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 {+ return null;+ }+}