Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
index 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.ts
index 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 acceleration
for (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.ts
new file mode 100644
index 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;
+ }
+}