@ruvector/ruvllm 4.0.0 → 4.1.0

package/dist/esm/contrastive.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Contrastive Fine-tuning for RuvLTRA Claude Code Router
+ *
+ * Uses triplet loss to fine-tune embeddings:
+ * - Anchor: task description
+ * - Positive: correct agent description
+ * - Negative: wrong agent description (hard negative)
+ *
+ * Goal: minimize distance(anchor, positive) and maximize distance(anchor, negative)
+ *
+ * @example
+ * ```typescript
+ * import { ContrastiveTrainer, tripletLoss, infoNCELoss } from '@ruvector/ruvllm';
+ *
+ * const trainer = new ContrastiveTrainer({
+ *   epochs: 10,
+ *   batchSize: 16,
+ *   margin: 0.5,
+ * });
+ *
+ * // Add triplets
+ * trainer.addTriplet(anchorEmb, positiveEmb, negativeEmb, true);
+ *
+ * // Train and export
+ * const results = trainer.train();
+ * trainer.exportTrainingData('./output');
+ * ```
+ */
+import { Embedding } from './types.js';
+/**
+ * Contrastive training configuration
+ */
+export interface ContrastiveConfig {
+    /** Number of training epochs (default: 10) */
+    epochs?: number;
+    /** Batch size (default: 16) */
+    batchSize?: number;
+    /** Learning rate (default: 0.0001) */
+    learningRate?: number;
+    /** Triplet loss margin (default: 0.5) */
+    margin?: number;
+    /** InfoNCE temperature (default: 0.07) */
+    temperature?: number;
+    /** Ratio of hard negatives (default: 0.7) */
+    hardNegativeRatio?: number;
+    /** Output directory for training data */
+    outputPath?: string;
+}
+/**
+ * Training triplet
+ */
+export interface TrainingTriplet {
+    /** Anchor embedding (task) */
+    anchor: string;
+    anchorEmb: Embedding;
+    /** Positive example (correct agent) */
+    positive: string;
+    positiveEmb: Embedding;
+    /** Negative example (wrong agent) */
+    negative: string;
+    negativeEmb: Embedding;
+    /** Whether this is a hard negative */
+    isHard: boolean;
+}
+/**
+ * Training history entry
+ */
+export interface TrainingHistoryEntry {
+    epoch: number;
+    loss: number;
+}
+/**
+ * Contrastive training results
+ */
+export interface ContrastiveTrainingResult {
+    /** Total triplets trained on */
+    tripletCount: number;
+    /** Final loss value */
+    finalLoss: number;
+    /** Initial loss value */
+    initialLoss: number;
+    /** Improvement percentage */
+    improvement: number;
+    /** Training history */
+    history: TrainingHistoryEntry[];
+    /** Duration in ms */
+    durationMs: number;
+}
+/**
+ * LoRA configuration for fine-tuning
+ */
+export interface LoRAExportConfig {
+    model_type: string;
+    base_model: string;
+    output_dir: string;
+    lora_r: number;
+    lora_alpha: number;
+    lora_dropout: number;
+    target_modules: string[];
+    learning_rate: number;
+    num_train_epochs: number;
+    per_device_train_batch_size: number;
+    gradient_accumulation_steps: number;
+    warmup_ratio: number;
+    loss_type: string;
+    margin: number;
+    temperature: number;
+    train_data: string;
+    eval_data: string;
+}
+/**
+ * Compute cosine similarity between two embeddings
+ */
+export declare function cosineSimilarity(a: Embedding, b: Embedding): number;
+/**
+ * Compute triplet loss
+ * L = max(0, margin + d(anchor, positive) - d(anchor, negative))
+ */
+export declare function tripletLoss(anchorEmb: Embedding, positiveEmb: Embedding, negativeEmb: Embedding, margin?: number): number;
+/**
+ * Compute InfoNCE loss (contrastive)
+ */
+export declare function infoNCELoss(anchorEmb: Embedding, positiveEmb: Embedding, negativeEmbs: Embedding[], temperature?: number): number;
+/**
+ * Compute gradient for embedding update (simplified)
+ */
+export declare function computeGradient(anchorEmb: Embedding, positiveEmb: Embedding, negativeEmb: Embedding, lr?: number): Embedding;
+/**
+ * Contrastive Trainer for RuvLTRA models
+ *
+ * Implements triplet loss and InfoNCE loss for embedding fine-tuning.
+ */
+export declare class ContrastiveTrainer {
+    private config;
+    private triplets;
+    private history;
+    private agentEmbeddings;
+    constructor(config?: ContrastiveConfig);
+    /**
+     * Add a training triplet
+     */
+    addTriplet(anchor: string, anchorEmb: Embedding, positive: string, positiveEmb: Embedding, negative: string, negativeEmb: Embedding, isHard?: boolean): void;
+    /**
+     * Add agent embedding for reference
+     */
+    addAgentEmbedding(agentName: string, embedding: Embedding): void;
+    /**
+     * Get all agent embeddings
+     */
+    getAgentEmbeddings(): Map<string, Embedding>;
+    /**
+     * Get triplet count
+     */
+    getTripletCount(): number;
+    /**
+     * Simulate training (compute losses without actual backprop)
+     * In a full implementation, this would use proper gradient descent
+     */
+    train(): ContrastiveTrainingResult;
+    /**
+     * Export training data for external fine-tuning tools
+     */
+    exportTrainingData(outputPath?: string): string;
+    /**
+     * Generate LoRA adapter configuration
+     */
+    generateLoRAConfig(outputPath?: string): LoRAExportConfig;
+    /**
+     * Generate training script for external tools
+     */
+    generateTrainingScript(outputPath?: string): string;
+    /**
+     * Get training history
+     */
+    getHistory(): TrainingHistoryEntry[];
+    /**
+     * Reset trainer
+     */
+    reset(): void;
+}
+/**
+ * Agent Training Data Interface
+ */
+export interface AgentTrainingData {
+    description: string;
+    keywords: string[];
+    examples: string[];
+    confusing_with?: string[];
+}
+/**
+ * Training Example Interface
+ */
+export interface TrainingExample {
+    task: string;
+    agent: string;
+    complexity?: string;
+    confusing_with?: string;
+}
+/**
+ * Dataset Statistics
+ */
+export interface DatasetStats {
+    totalExamples: number;
+    contrastivePairs: number;
+    agentTypes: number;
+    agents: string[];
+}
+/**
+ * Agent Training Data for Claude Code Router
+ */
+export declare const AGENT_TRAINING_DATA: Record<string, AgentTrainingData>;
+/**
+ * Generate training dataset from agent data
+ */
+export declare function generateTrainingDataset(): TrainingExample[];
+/**
+ * Generate contrastive pairs for training
+ */
+export declare function generateContrastivePairs(): Array<{
+    anchor: string;
+    positive: string;
+    negative: string;
+    isHard: boolean;
+}>;
+/**
+ * Get dataset statistics
+ */
+export declare function getDatasetStats(): DatasetStats;
+//# sourceMappingURL=contrastive.d.ts.map

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

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