/**
 * 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
 */
/**
 * Default LoRA rank (determines memory/quality tradeoff)
 */
export declare const DEFAULT_RANK = 8;
/**
 * Input dimension (384 from ONNX MiniLM-L6-v2)
 */
export declare const INPUT_DIM = 384;
/**
 * Default output dimension (same as input for adapter)
 */
export declare const OUTPUT_DIM = 384;
/**
 * Default alpha scaling factor
 */
export declare const DEFAULT_ALPHA = 16;
/**
 * LoRA configuration
 */
export interface LoRAConfig {
    /** Rank of decomposition (lower = more compression) */
    rank: number;
    /** Alpha scaling factor for output */
    alpha: number;
    /** Input dimension */
    inputDim: number;
    /** Output dimension */
    outputDim: number;
    /** Learning rate for updates */
    learningRate: number;
    /** Path for weight persistence */
    weightsPath: string;
    /** Enable dropout for regularization */
    enableDropout: boolean;
    /** Dropout probability */
    dropoutProb: number;
    /** Auto-save interval in updates */
    autoSaveInterval: number;
}
/**
 * LoRA adapter weights
 */
export interface LoRAWeights {
    /** A matrix (rank × inputDim) - down projection */
    A: Float32Array;
    /** B matrix (outputDim × rank) - up projection */
    B: Float32Array;
    /** Scaling factor (alpha / rank) */
    scaling: number;
}
/**
 * Adaptation result
 */
export interface AdaptationResult {
    /** Adapted embedding */
    adapted: Float32Array;
    /** Magnitude of adaptation */
    adaptationNorm: number;
    /** Time taken in ms */
    timeMs: number;
}
/**
 * LoRA statistics
 */
export interface LoRAStats {
    /** Total adaptations performed */
    totalAdaptations: number;
    /** Total training updates */
    totalUpdates: number;
    /** Current rank */
    rank: number;
    /** Memory savings ratio */
    compressionRatio: number;
    /** Average adaptation norm */
    avgAdaptationNorm: number;
    /** Last update timestamp */
    lastUpdate: number | null;
    /** Training backend in use ('ruvllm' | 'js-fallback') */
    _trainingBackend?: string;
}
/**
 * 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 declare function resolveTrainingBackend(): 'ruvllm' | '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 declare function nativeCheckpointsSupported(): boolean;
/**
 * Low-Rank Adaptation module for efficient embedding fine-tuning
 */
export declare class LoRAAdapter {
    private config;
    private weights;
    private totalAdaptations;
    private totalUpdates;
    private adaptationNormSum;
    private lastUpdate;
    private updatesSinceLastSave;
    constructor(config?: Partial<LoRAConfig>);
    /**
     * Eagerly load the ruvllm TrainingPipeline backend.
     * Called automatically during first checkpoint operation,
     * or call explicitly to make getStats() report backend status.
     */
    initBackend(): Promise<void>;
    /**
     * Get a readonly copy of the adapter configuration
     */
    getConfig(): Readonly<LoRAConfig>;
    /**
     * Initialize weights with Kaiming/He initialization
     */
    private initializeWeights;
    /**
     * Box-Muller transform for Gaussian random numbers
     */
    private gaussianRandom;
    /**
     * Initialize adapter and load persisted weights
     */
    initialize(): Promise<{
        success: boolean;
        weightsLoaded: boolean;
    }>;
    /**
     * Apply LoRA adaptation to an embedding
     * output = input + scaling * (B @ A @ input)
     */
    adapt(input: Float32Array): AdaptationResult;
    /**
     * Train the adapter with a gradient signal
     * Uses simplified update: A += lr * hidden^T @ grad, B += lr * grad @ hidden^T
     */
    train(input: Float32Array, gradOutput: Float32Array, reward?: number): {
        updated: boolean;
        loss: number;
    };
    /**
     * Merge LoRA weights into base weights (for deployment)
     * Returns: W' = W + scaling * B @ A
     */
    merge(baseWeights: Float32Array): Float32Array;
    /**
     * Get current statistics
     */
    getStats(): LoRAStats;
    /**
     * Reset adapter to initial state
     */
    reset(): void;
    /**
     * Save weights to disk
     */
    saveWeights(): boolean;
    /**
     * Load weights from disk
     */
    loadWeights(): boolean;
    /**
     * Save a training checkpoint via ruvllm TrainingPipeline.
     * Falls back to writing our own weight JSON if ruvllm is unavailable.
     */
    saveCheckpoint(path: string): Promise<boolean>;
    /**
     * Load a training checkpoint via ruvllm TrainingPipeline.
     * Falls back to reading our own weight JSON if ruvllm is unavailable.
     */
    loadCheckpoint(path: string): Promise<boolean>;
    /**
     * Export weights as JSON
     */
    exportWeights(): {
        A: number[];
        B: number[];
        scaling: number;
        config: Partial<LoRAConfig>;
    };
    /**
     * Import weights from JSON
     */
    importWeights(data: {
        A: number[];
        B: number[];
        scaling: number;
    }): boolean;
}
/**
 * Info about the newest on-disk training checkpoint.
 */
export interface CheckpointInfo {
    /** Absolute path to the checkpoint file */
    path: string;
    /** Basename, e.g. lora-checkpoint-1712345678901.json */
    filename: string;
    /** Age in ms derived from the filename timestamp (falls back to mtime) */
    ageMs: number;
    /** Human-friendly age, e.g. "2h ago" */
    ageLabel: string;
}
/** Compact relative-age label. Most-significant unit only. */
export declare function formatCheckpointAge(ms: number): string;
/**
 * 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 declare function latestCheckpointInfo(): CheckpointInfo | null;
/**
 * 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 declare function loadLatestCheckpoint(adapter: LoRAAdapter): Promise<{
    loaded: boolean;
    path?: string;
    ageMs?: number;
}>;
/**
 * Get or create singleton LoRA adapter instance
 */
export declare function getLoRAAdapter(): Promise<LoRAAdapter>;
/**
 * Reset singleton instance (for testing)
 */
export declare function resetLoRAAdapter(): void;
/**
 * Create new LoRA adapter instance (factory)
 */
export declare function createLoRAAdapter(config?: Partial<LoRAConfig>): LoRAAdapter;
/**
 * Quick adaptation (convenience function)
 */
export declare function adaptEmbedding(input: Float32Array): Promise<AdaptationResult>;
/**
 * Quick training (convenience function)
 */
export declare function trainLoRA(input: Float32Array, gradOutput: Float32Array, reward?: number): Promise<{
    updated: boolean;
    loss: number;
}>;
/**
 * Get LoRA statistics (convenience function)
 */
export declare function getLoRAStats(): Promise<LoRAStats>;
declare const _default: {
    LoRAAdapter: typeof LoRAAdapter;
    getLoRAAdapter: typeof getLoRAAdapter;
    resetLoRAAdapter: typeof resetLoRAAdapter;
    createLoRAAdapter: typeof createLoRAAdapter;
    adaptEmbedding: typeof adaptEmbedding;
    trainLoRA: typeof trainLoRA;
    getLoRAStats: typeof getLoRAStats;
    DEFAULT_RANK: number;
    DEFAULT_ALPHA: number;
    INPUT_DIM: number;
    OUTPUT_DIM: number;
};
export default _default;
//# sourceMappingURL=lora-adapter.d.ts.map