@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/ruvector/lora-adapter.js

@@ -0,0 +1,710 @@
+/**
+ * LoRA (Low-Rank Adaptation) Implementation
+ *
+ * Enables efficient fine-tuning by decomposing weight updates into low-rank matrices.
+ * Dramatically reduces memory requirements while maintaining adaptation quality.
+ *
+ * Features:
+ * - Rank decomposition (r << d) for memory efficiency
+ * - Additive weight updates: W' = W + BA (where B ∈ R^{d×r}, A ∈ R^{r×k})
+ * - Support for multiple adaptation heads
+ * - Persistence to .swarm/lora-weights.json
+ *
+ * Memory savings:
+ * - Original: d × k parameters
+ * - LoRA: r × (d + k) parameters
+ * - For d=384, k=384, r=8: 786,432 → 6,144 (128x reduction)
+ *
+ * @module lora-adapter
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { createRequire } from 'module';
+// ============================================================================
+// Types & Constants
+// ============================================================================
+/**
+ * Default LoRA rank (determines memory/quality tradeoff)
+ */
+export const DEFAULT_RANK = 8;
+/**
+ * Input dimension (384 from ONNX MiniLM-L6-v2)
+ */
+export const INPUT_DIM = 384;
+/**
+ * Default output dimension (same as input for adapter)
+ */
+export const OUTPUT_DIM = 384;
+/**
+ * Default alpha scaling factor
+ */
+export const DEFAULT_ALPHA = 16;
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_CONFIG = {
+    rank: DEFAULT_RANK,
+    alpha: DEFAULT_ALPHA,
+    inputDim: INPUT_DIM,
+    outputDim: OUTPUT_DIM,
+    learningRate: 0.001,
+    weightsPath: join(process.cwd(), '.swarm', 'lora-weights.json'),
+    enableDropout: true,
+    dropoutProb: 0.1,
+    autoSaveInterval: 50,
+};
+// ============================================================================
+// @ruvector/ruvllm TrainingPipeline (lazy-loaded)
+// ============================================================================
+let ruvllmPipeline = null;
+let pipelineLoaded = false;
+/**
+ * Which training backend a train call would use — WITHOUT loading the
+ * pipeline (#2549). Before this existed, status surfaces read module state
+ * that only a prior in-process train populates, so a fresh read-only
+ * process always reported 'js-fallback'/'unavailable' even with
+ * @ruvector/ruvllm installed. The pipeline stays lazy: this only probes
+ * module resolution.
+ */
+export function resolveTrainingBackend() {
+    if (pipelineLoaded)
+        return ruvllmPipeline ? 'ruvllm' : 'js-fallback';
+    try {
+        createRequire(import.meta.url).resolve('@ruvector/ruvllm');
+        return 'ruvllm';
+    }
+    catch {
+        return 'js-fallback';
+    }
+}
+/**
+ * Whether the resolved @ruvector/ruvllm persists checkpoints to disk.
+ * saveCheckpoint(path) was a silent no-op (private, void, wrote 0 bytes)
+ * before 2.5.7 — status surfaces must not advertise checkpoints against
+ * older versions. Reads the resolved package's version; the package does
+ * not export ./package.json, so walk up from the resolved entry instead.
+ */
+export function nativeCheckpointsSupported() {
+    try {
+        const req = createRequire(import.meta.url);
+        let dir = dirname(req.resolve('@ruvector/ruvllm'));
+        for (let i = 0; i < 5; i++) {
+            const pkgPath = join(dir, 'package.json');
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name !== '@ruvector/ruvllm') {
+                    dir = dirname(dir);
+                    continue;
+                }
+                const [maj, min, pat] = String(pkg.version).split('.').map(Number);
+                return maj > 2 || (maj === 2 && (min > 5 || (min === 5 && pat >= 7)));
+            }
+            dir = dirname(dir);
+        }
+    }
+    catch { /* unresolved — no native checkpoints */ }
+    return false;
+}
+async function loadTrainingPipeline(adapter) {
+    if (pipelineLoaded)
+        return ruvllmPipeline;
+    pipelineLoaded = true;
+    try {
+        const { createRequire } = await import('module');
+        const requireCjs = createRequire(import.meta.url);
+        const ruvllm = requireCjs('@ruvector/ruvllm');
+        const config = adapter.getConfig();
+        // Create a ruvllm LoraAdapter that mirrors our JS adapter's config
+        const nativeAdapter = new ruvllm.LoraAdapter(config.inputDim, config.outputDim, config.rank);
+        ruvllmPipeline = new ruvllm.TrainingPipeline({
+            adapter: nativeAdapter,
+            learningRate: 0.001,
+            batchSize: 8,
+        });
+        return ruvllmPipeline;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// LoRA Adapter Class
+// ============================================================================
+/**
+ * Low-Rank Adaptation module for efficient embedding fine-tuning
+ */
+export class LoRAAdapter {
+    config;
+    weights;
+    totalAdaptations = 0;
+    totalUpdates = 0;
+    adaptationNormSum = 0;
+    lastUpdate = null;
+    updatesSinceLastSave = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.weights = this.initializeWeights();
+    }
+    /**
+     * Eagerly load the ruvllm TrainingPipeline backend.
+     * Called automatically during first checkpoint operation,
+     * or call explicitly to make getStats() report backend status.
+     */
+    async initBackend() {
+        await loadTrainingPipeline(this);
+    }
+    /**
+     * Get a readonly copy of the adapter configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Initialize weights with Kaiming/He initialization
+     */
+    initializeWeights() {
+        const { rank, inputDim, outputDim, alpha } = this.config;
+        // A: rank × inputDim, initialized with Kaiming normal
+        const A = new Float32Array(rank * inputDim);
+        const stdA = Math.sqrt(2.0 / inputDim);
+        for (let i = 0; i < A.length; i++) {
+            A[i] = this.gaussianRandom() * stdA;
+        }
+        // B: outputDim × rank, initialized to zero (standard LoRA init)
+        const B = new Float32Array(outputDim * rank);
+        // B starts at zero so initial adaptation is zero
+        return {
+            A,
+            B,
+            scaling: alpha / rank,
+        };
+    }
+    /**
+     * Box-Muller transform for Gaussian random numbers
+     */
+    gaussianRandom() {
+        let u = 0, v = 0;
+        while (u === 0)
+            u = Math.random();
+        while (v === 0)
+            v = Math.random();
+        return Math.sqrt(-2.0 * Math.log(u)) * Math.cos(2.0 * Math.PI * v);
+    }
+    /**
+     * Initialize adapter and load persisted weights
+     */
+    async initialize() {
+        const loaded = this.loadWeights();
+        return { success: true, weightsLoaded: loaded };
+    }
+    /**
+     * Apply LoRA adaptation to an embedding
+     * output = input + scaling * (B @ A @ input)
+     */
+    adapt(input) {
+        const startTime = performance.now();
+        const { rank, inputDim, outputDim } = this.config;
+        const { A, B, scaling } = this.weights;
+        // Step 1: Compute A @ input (rank-dimensional)
+        const hidden = new Float32Array(rank);
+        for (let r = 0; r < rank; r++) {
+            let sum = 0;
+            const rowOffset = r * inputDim;
+            // Unroll by 4 for SIMD-friendly access
+            let i = 0;
+            for (; i + 3 < inputDim; i += 4) {
+                sum += A[rowOffset + i] * input[i];
+                sum += A[rowOffset + i + 1] * input[i + 1];
+                sum += A[rowOffset + i + 2] * input[i + 2];
+                sum += A[rowOffset + i + 3] * input[i + 3];
+            }
+            for (; i < inputDim; i++) {
+                sum += A[rowOffset + i] * input[i];
+            }
+            hidden[r] = sum;
+        }
+        // Optional dropout (during training inference, skip)
+        // In LoRA inference, we don't apply dropout
+        // Step 2: Compute B @ hidden (outputDim-dimensional)
+        const delta = new Float32Array(outputDim);
+        for (let o = 0; o < outputDim; o++) {
+            let sum = 0;
+            const rowOffset = o * rank;
+            for (let r = 0; r < rank; r++) {
+                sum += B[rowOffset + r] * hidden[r];
+            }
+            delta[o] = sum * scaling;
+        }
+        // Step 3: Add adaptation to input
+        const adapted = new Float32Array(outputDim);
+        let adaptationNorm = 0;
+        for (let i = 0; i < outputDim; i++) {
+            adapted[i] = input[i] + delta[i];
+            adaptationNorm += delta[i] * delta[i];
+        }
+        adaptationNorm = Math.sqrt(adaptationNorm);
+        // Update stats
+        this.totalAdaptations++;
+        this.adaptationNormSum += adaptationNorm;
+        const timeMs = performance.now() - startTime;
+        return { adapted, adaptationNorm, timeMs };
+    }
+    /**
+     * Train the adapter with a gradient signal
+     * Uses simplified update: A += lr * hidden^T @ grad, B += lr * grad @ hidden^T
+     */
+    train(input, gradOutput, reward = 1.0) {
+        const { rank, inputDim, outputDim, learningRate } = this.config;
+        const { A, B, scaling } = this.weights;
+        // Forward pass to get hidden states
+        const hidden = new Float32Array(rank);
+        for (let r = 0; r < rank; r++) {
+            let sum = 0;
+            const rowOffset = r * inputDim;
+            for (let i = 0; i < inputDim; i++) {
+                sum += A[rowOffset + i] * input[i];
+            }
+            hidden[r] = sum;
+        }
+        // Compute gradient for B: grad_B = gradOutput @ hidden^T
+        const scaledLr = learningRate * reward * scaling;
+        for (let o = 0; o < outputDim; o++) {
+            const rowOffset = o * rank;
+            for (let r = 0; r < rank; r++) {
+                B[rowOffset + r] += scaledLr * gradOutput[o] * hidden[r];
+            }
+        }
+        // Compute gradient for hidden: grad_hidden = B^T @ gradOutput
+        const gradHidden = new Float32Array(rank);
+        for (let r = 0; r < rank; r++) {
+            let sum = 0;
+            for (let o = 0; o < outputDim; o++) {
+                sum += B[o * rank + r] * gradOutput[o];
+            }
+            gradHidden[r] = sum;
+        }
+        // Compute gradient for A: grad_A = gradHidden @ input^T
+        for (let r = 0; r < rank; r++) {
+            const rowOffset = r * inputDim;
+            for (let i = 0; i < inputDim; i++) {
+                A[rowOffset + i] += scaledLr * gradHidden[r] * input[i];
+            }
+        }
+        // Compute loss (L2 norm of gradient)
+        let loss = 0;
+        for (let i = 0; i < gradOutput.length; i++) {
+            loss += gradOutput[i] * gradOutput[i];
+        }
+        loss = Math.sqrt(loss);
+        // Update counters
+        this.totalUpdates++;
+        this.lastUpdate = Date.now();
+        this.updatesSinceLastSave++;
+        // Auto-save if needed
+        if (this.updatesSinceLastSave >= this.config.autoSaveInterval) {
+            this.saveWeights();
+            this.updatesSinceLastSave = 0;
+        }
+        return { updated: true, loss };
+    }
+    /**
+     * Merge LoRA weights into base weights (for deployment)
+     * Returns: W' = W + scaling * B @ A
+     */
+    merge(baseWeights) {
+        const { rank, inputDim, outputDim } = this.config;
+        const { A, B, scaling } = this.weights;
+        // Compute BA product
+        const merged = new Float32Array(baseWeights);
+        for (let o = 0; o < outputDim; o++) {
+            for (let i = 0; i < inputDim; i++) {
+                let sum = 0;
+                for (let r = 0; r < rank; r++) {
+                    sum += B[o * rank + r] * A[r * inputDim + i];
+                }
+                merged[o * inputDim + i] += scaling * sum;
+            }
+        }
+        return merged;
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        const { rank, inputDim, outputDim } = this.config;
+        const originalParams = inputDim * outputDim;
+        const loraParams = rank * (inputDim + outputDim);
+        return {
+            totalAdaptations: this.totalAdaptations,
+            totalUpdates: this.totalUpdates,
+            rank: this.config.rank,
+            compressionRatio: originalParams / loraParams,
+            avgAdaptationNorm: this.totalAdaptations > 0
+                ? this.adaptationNormSum / this.totalAdaptations
+                : 0,
+            lastUpdate: this.lastUpdate,
+            _trainingBackend: resolveTrainingBackend(),
+        };
+    }
+    /**
+     * Reset adapter to initial state
+     */
+    reset() {
+        this.weights = this.initializeWeights();
+        this.totalAdaptations = 0;
+        this.totalUpdates = 0;
+        this.adaptationNormSum = 0;
+        this.lastUpdate = null;
+        this.updatesSinceLastSave = 0;
+    }
+    /**
+     * Save weights to disk
+     */
+    saveWeights() {
+        try {
+            const dir = dirname(this.config.weightsPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            const data = {
+                version: 1,
+                config: {
+                    rank: this.config.rank,
+                    alpha: this.config.alpha,
+                    inputDim: this.config.inputDim,
+                    outputDim: this.config.outputDim,
+                },
+                weights: {
+                    A: Array.from(this.weights.A),
+                    B: Array.from(this.weights.B),
+                    scaling: this.weights.scaling,
+                },
+                stats: {
+                    totalAdaptations: this.totalAdaptations,
+                    totalUpdates: this.totalUpdates,
+                    adaptationNormSum: this.adaptationNormSum,
+                    lastUpdate: this.lastUpdate,
+                },
+                savedAt: new Date().toISOString(),
+            };
+            writeFileSync(this.config.weightsPath, JSON.stringify(data, null, 2));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load weights from disk
+     */
+    loadWeights() {
+        try {
+            if (!existsSync(this.config.weightsPath)) {
+                return false;
+            }
+            const content = readFileSync(this.config.weightsPath, 'utf-8');
+            const data = JSON.parse(content);
+            if (data.version !== 1) {
+                return false;
+            }
+            // Verify dimensions match
+            const { rank, inputDim, outputDim } = data.config;
+            if (rank !== this.config.rank ||
+                inputDim !== this.config.inputDim ||
+                outputDim !== this.config.outputDim) {
+                return false;
+            }
+            // Load weights
+            this.weights = {
+                A: new Float32Array(data.weights.A),
+                B: new Float32Array(data.weights.B),
+                scaling: data.weights.scaling,
+            };
+            // Load stats
+            this.totalAdaptations = data.stats.totalAdaptations || 0;
+            this.totalUpdates = data.stats.totalUpdates || 0;
+            this.adaptationNormSum = data.stats.adaptationNormSum || 0;
+            this.lastUpdate = data.stats.lastUpdate || null;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Save a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to writing our own weight JSON if ruvllm is unavailable.
+     */
+    async saveCheckpoint(path) {
+        // Parent dir must exist for BOTH paths: ruvllm <2.5.7 never wrote a
+        // file at all, and the JS fallback's writeFileSync throws ENOENT on a
+        // missing dir — which the catch silently converted to `false` (#2549).
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch { /* fs errors surface on write below */ }
+        const pipeline = await loadTrainingPipeline(this);
+        if (pipeline) {
+            try {
+                pipeline.saveCheckpoint(path);
+                // Verify ruvllm actually wrote the file (<2.5.7 is a silent no-op)
+                const fs = await import('fs');
+                if (fs.existsSync(path))
+                    return true;
+            }
+            catch { /* fall through to JS fallback */ }
+        }
+        // Fallback: save our own weights as JSON
+        try {
+            const fs = await import('fs');
+            const data = JSON.stringify(this.exportWeights());
+            fs.writeFileSync(path, data);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to reading our own weight JSON if ruvllm is unavailable.
+     */
+    async loadCheckpoint(path) {
+        const pipeline = await loadTrainingPipeline(this);
+        if (pipeline) {
+            try {
+                pipeline.loadCheckpoint(path);
+                return true;
+            }
+            catch { /* fall through to JS fallback */ }
+        }
+        // Fallback: load from our JSON format
+        try {
+            const fs = await import('fs');
+            if (fs.existsSync(path)) {
+                const data = JSON.parse(fs.readFileSync(path, 'utf-8'));
+                return this.importWeights(data);
+            }
+        }
+        catch { /* return false below */ }
+        return false;
+    }
+    /**
+     * Export weights as JSON
+     */
+    exportWeights() {
+        return {
+            A: Array.from(this.weights.A),
+            B: Array.from(this.weights.B),
+            scaling: this.weights.scaling,
+            config: {
+                rank: this.config.rank,
+                alpha: this.config.alpha,
+                inputDim: this.config.inputDim,
+                outputDim: this.config.outputDim,
+            },
+        };
+    }
+    /**
+     * Import weights from JSON
+     */
+    importWeights(data) {
+        try {
+            const { rank, inputDim, outputDim } = this.config;
+            if (data.A.length !== rank * inputDim ||
+                data.B.length !== outputDim * rank) {
+                return false;
+            }
+            this.weights = {
+                A: new Float32Array(data.A),
+                B: new Float32Array(data.B),
+                scaling: data.scaling,
+            };
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Directories `neural train` writes checkpoints to. It only ever writes to
+ * `<cwd>/.claude-flow/neural` (see commands/neural.ts + services/native-training.ts),
+ * so that is the single source of truth — kept in a helper so the discovery
+ * and status surfaces stay consistent.
+ */
+function checkpointDirs() {
+    return [join(process.cwd(), '.claude-flow', 'neural')];
+}
+/** Compact relative-age label. Most-significant unit only. */
+export function formatCheckpointAge(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+}
+/**
+ * Find the newest `lora-checkpoint-<ts>.json` without loading it. Pure disk
+ * scan — safe to call from read-only status surfaces. Returns null when no
+ * checkpoint exists or the directory is unreadable.
+ */
+export function latestCheckpointInfo() {
+    try {
+        let best = null;
+        for (const dir of checkpointDirs()) {
+            if (!existsSync(dir))
+                continue;
+            for (const f of readdirSync(dir)) {
+                const match = /^lora-checkpoint-(\d+)\.json$/.exec(f);
+                if (!match)
+                    continue;
+                const ts = Number(match[1]);
+                if (!Number.isFinite(ts))
+                    continue;
+                if (!best || ts > best.ts)
+                    best = { path: join(dir, f), filename: f, ts };
+            }
+        }
+        if (!best)
+            return null;
+        const ageMs = Math.max(0, Date.now() - best.ts);
+        return { path: best.path, filename: best.filename, ageMs, ageLabel: formatCheckpointAge(ageMs) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a file looks like a ruvllm training checkpoint before loading it,
+ * so a stray/corrupt JSON in the neural dir can't poison routing weights.
+ * Accepts both the JS-fallback envelope ({A,B,scaling}) and native ruvllm
+ * checkpoint shapes (weights/adapter/epoch/step/loss/version/index markers).
+ */
+function isCheckpointEnvelope(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!data || typeof data !== 'object')
+            return false;
+        const obj = data;
+        if (Array.isArray(obj.A) && Array.isArray(obj.B))
+            return true;
+        return ['weights', 'adapter', 'epoch', 'step', 'loss', 'version', 'index'].some((k) => k in obj);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Flywheel entry point: locate the newest trained checkpoint and load it into
+ * `adapter` via the adapter's existing loadCheckpoint path, so routing /
+ * adaptation benefits from prior `neural train` runs.
+ *
+ * Contract: lazy (call on first adaptation use, never at CLI startup),
+ * non-fatal on any failure, and kill-switchable via
+ * CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD=1.
+ */
+export async function loadLatestCheckpoint(adapter) {
+    if (process.env.CLAUDE_FLOW_NO_CHECKPOINT_AUTOLOAD === '1')
+        return { loaded: false };
+    try {
+        const info = latestCheckpointInfo();
+        if (!info)
+            return { loaded: false };
+        if (!isCheckpointEnvelope(info.path))
+            return { loaded: false, path: info.path, ageMs: info.ageMs };
+        const loaded = await adapter.loadCheckpoint(info.path);
+        return { loaded, path: info.path, ageMs: info.ageMs };
+    }
+    catch {
+        return { loaded: false };
+    }
+}
+// ============================================================================
+// Singleton & Factory Functions
+// ============================================================================
+let loraInstance = null;
+let initPromise = null;
+/**
+ * Get or create singleton LoRA adapter instance
+ */
+export async function getLoRAAdapter() {
+    if (loraInstance) {
+        return loraInstance;
+    }
+    if (initPromise) {
+        return initPromise;
+    }
+    initPromise = (async () => {
+        const adapter = new LoRAAdapter();
+        await adapter.initialize();
+        // Flywheel: fold in the newest trained checkpoint so routing/adaptation
+        // benefits from prior `neural train` runs. This singleton is constructed
+        // lazily on first adaptation use (NOT at CLI startup), so the checkpoint
+        // scan + ruvllm load stay off the hot `--help` path. Non-fatal.
+        try {
+            await loadLatestCheckpoint(adapter);
+        }
+        catch { /* auto-load is best-effort — never block adaptation */ }
+        loraInstance = adapter;
+        return adapter;
+    })();
+    return initPromise;
+}
+/**
+ * Reset singleton instance (for testing)
+ */
+export function resetLoRAAdapter() {
+    if (loraInstance) {
+        loraInstance.reset();
+    }
+    loraInstance = null;
+    initPromise = null;
+}
+/**
+ * Create new LoRA adapter instance (factory)
+ */
+export function createLoRAAdapter(config) {
+    return new LoRAAdapter(config);
+}
+/**
+ * Quick adaptation (convenience function)
+ */
+export async function adaptEmbedding(input) {
+    const adapter = await getLoRAAdapter();
+    return adapter.adapt(input);
+}
+/**
+ * Quick training (convenience function)
+ */
+export async function trainLoRA(input, gradOutput, reward) {
+    const adapter = await getLoRAAdapter();
+    return adapter.train(input, gradOutput, reward);
+}
+/**
+ * Get LoRA statistics (convenience function)
+ */
+export async function getLoRAStats() {
+    const adapter = await getLoRAAdapter();
+    return adapter.getStats();
+}
+export default {
+    LoRAAdapter,
+    getLoRAAdapter,
+    resetLoRAAdapter,
+    createLoRAAdapter,
+    adaptEmbedding,
+    trainLoRA,
+    getLoRAStats,
+    DEFAULT_RANK,
+    DEFAULT_ALPHA,
+    INPUT_DIM,
+    OUTPUT_DIM,
+};
+//# sourceMappingURL=lora-adapter.js.map