@ruvector/ruvllm 4.0.0 → 4.1.0

package/dist/esm/lora.d.ts

@@ -0,0 +1,251 @@
+/**
+ * LoRA (Low-Rank Adaptation) Runtime
+ *
+ * Efficient parameter-efficient fine-tuning adapters for LLMs.
+ * Supports micro-LoRA (fast, small updates) and base-LoRA (deeper adaptation).
+ *
+ * @example
+ * ```typescript
+ * import { LoraAdapter, LoraManager } from '@ruvector/ruvllm';
+ *
+ * // Create adapter
+ * const adapter = new LoraAdapter({
+ *   rank: 8,
+ *   alpha: 16,
+ *   dropout: 0.1,
+ *   targetModules: ['query', 'value'],
+ * });
+ *
+ * // Apply to hidden states
+ * const output = adapter.forward(hiddenStates);
+ *
+ * // Manage multiple adapters
+ * const manager = new LoraManager();
+ * manager.register('task-1', adapter);
+ * manager.activate('task-1');
+ * ```
+ */
+import { LoRAConfig } from './types.js';
+/**
+ * LoRA adapter weights
+ */
+export interface LoraWeights {
+    /** Down projection matrix (d x r) */
+    loraA: number[][];
+    /** Up projection matrix (r x d) */
+    loraB: number[][];
+    /** Scaling factor */
+    scaling: number;
+}
+/**
+ * LoRA training state
+ */
+export interface LoraTrainingState {
+    /** Current step */
+    step: number;
+    /** Learning rate */
+    learningRate: number;
+    /** Accumulated gradients for A */
+    gradA: number[][];
+    /** Accumulated gradients for B */
+    gradB: number[][];
+    /** Loss history */
+    lossHistory: number[];
+}
+/**
+ * LoRA Adapter
+ *
+ * Implements low-rank decomposition for parameter-efficient fine-tuning.
+ * W' = W + BA where A is (d x r) and B is (r x d), r << d
+ *
+ * @example
+ * ```typescript
+ * const adapter = new LoraAdapter({
+ *   rank: 8,
+ *   alpha: 16,
+ *   inputDim: 768,
+ *   outputDim: 768,
+ * });
+ *
+ * // Forward pass
+ * const output = adapter.forward(input);
+ *
+ * // Training step
+ * adapter.backward(input, gradOutput, 0.001);
+ * ```
+ */
+export declare class LoraAdapter {
+    private config;
+    private inputDim;
+    private outputDim;
+    private weights;
+    private trainingState;
+    private frozen;
+    constructor(config?: Partial<LoRAConfig>, inputDim?: number, outputDim?: number);
+    /**
+     * Forward pass through LoRA adapter
+     * OPTIMIZED: Uses Float64Array and loop unrolling
+     *
+     * output = input + scaling * (input @ A @ B)
+     */
+    forward(input: number[]): number[];
+    /**
+     * Forward with batch processing
+     */
+    forwardBatch(inputs: number[][]): number[][];
+    /**
+     * Backward pass and weight update
+     */
+    backward(input: number[], gradOutput: number[], learningRate: number): number;
+    /**
+     * Start training mode
+     */
+    startTraining(learningRate?: number): void;
+    /**
+     * End training mode
+     */
+    endTraining(): LoraTrainingState | null;
+    /**
+     * Freeze adapter (no more updates)
+     */
+    freeze(): void;
+    /**
+     * Unfreeze adapter
+     */
+    unfreeze(): void;
+    /**
+     * Check if frozen
+     */
+    isFrozen(): boolean;
+    /**
+     * Get adapter config
+     */
+    getConfig(): Required<LoRAConfig>;
+    /**
+     * Get input dimension (rows of loraA).
+     *
+     * The adapter's geometry (inputDim/outputDim) is not part of LoRAConfig,
+     * so these getters expose it for checkpoint metadata and shape validation.
+     */
+    getInputDim(): number;
+    /**
+     * Get output dimension (cols of loraB).
+     */
+    getOutputDim(): number;
+    /**
+     * Get adapter weights
+     */
+    getWeights(): LoraWeights;
+    /**
+     * Set adapter weights
+     */
+    setWeights(weights: LoraWeights): void;
+    /**
+     * Merge adapter into base weights
+     *
+     * Returns delta to add to base model weights
+     */
+    merge(): number[][];
+    /**
+     * Get number of trainable parameters
+     */
+    numParameters(): number;
+    /**
+     * Reset to initial weights
+     */
+    reset(): void;
+    /**
+     * Clone adapter
+     */
+    clone(): LoraAdapter;
+    /**
+     * Serialize to JSON
+     */
+    toJSON(): string;
+    /**
+     * Deserialize from JSON
+     */
+    static fromJSON(json: string): LoraAdapter;
+    private initializeWeights;
+}
+/**
+ * LoRA Manager for multiple adapters
+ *
+ * Manages a collection of LoRA adapters for different tasks/domains.
+ */
+export declare class LoraManager {
+    private adapters;
+    private activeAdapterId;
+    private defaultConfig;
+    constructor(defaultConfig?: Partial<LoRAConfig>);
+    /**
+     * Register a new adapter
+     */
+    register(id: string, adapter: LoraAdapter): void;
+    /**
+     * Create and register a new adapter
+     */
+    create(id: string, config?: Partial<LoRAConfig>, inputDim?: number, outputDim?: number): LoraAdapter;
+    /**
+     * Get adapter by ID
+     */
+    get(id: string): LoraAdapter | undefined;
+    /**
+     * Remove adapter
+     */
+    remove(id: string): boolean;
+    /**
+     * Activate an adapter
+     */
+    activate(id: string): boolean;
+    /**
+     * Deactivate current adapter
+     */
+    deactivate(): void;
+    /**
+     * Get active adapter
+     */
+    getActive(): LoraAdapter | null;
+    /**
+     * Get active adapter ID
+     */
+    getActiveId(): string | null;
+    /**
+     * Apply active adapter
+     */
+    forward(input: number[]): number[];
+    /**
+     * List all adapter IDs
+     */
+    list(): string[];
+    /**
+     * Get adapter count
+     */
+    count(): number;
+    /**
+     * Freeze all adapters
+     */
+    freezeAll(): void;
+    /**
+     * Unfreeze all adapters
+     */
+    unfreezeAll(): void;
+    /**
+     * Merge multiple adapters into one
+     */
+    mergeAdapters(ids: string[], outputId: string): LoraAdapter | null;
+    /**
+     * Get statistics
+     */
+    stats(): {
+        totalAdapters: number;
+        activeAdapter: string | null;
+        totalParameters: number;
+        frozenCount: number;
+    };
+    /**
+     * Clear all adapters
+     */
+    clear(): void;
+}
+//# sourceMappingURL=lora.d.ts.map

package/dist/esm/lora.d.ts.map

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