@ruvector/ruvllm 3.0.0 → 4.0.1

package/scripts/training/contrastive-finetune.js

@@ -1,517 +0,0 @@
-#!/usr/bin/env node
-/**
- * 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)
- */
-
-const { execSync } = require('child_process');
-const { existsSync, writeFileSync, readFileSync, mkdirSync } = require('fs');
-const { join } = require('path');
-const { homedir } = require('os');
-
-const MODELS_DIR = join(homedir(), '.ruvllm', 'models');
-const OUTPUT_DIR = join(homedir(), '.ruvllm', 'training');
-const RUVLTRA_MODEL = join(MODELS_DIR, 'ruvltra-claude-code-0.5b-q4_k_m.gguf');
-
-// Import training data
-const { AGENT_TRAINING_DATA, generateTrainingDataset, generateContrastivePairs, getDatasetStats } = require('./routing-dataset');
-
-// Build agent descriptions from training data
-const AGENT_DESCRIPTIONS = {};
-for (const [agent, data] of Object.entries(AGENT_TRAINING_DATA)) {
-  AGENT_DESCRIPTIONS[agent] = data.description;
-}
-
-// Get training data
-const TRAINING_EXAMPLES = generateTrainingDataset();
-const CONTRASTIVE_PAIRS_RAW = generateContrastivePairs();
-
-// Training configuration
-const CONFIG = {
-  epochs: 10,
-  batchSize: 16,
-  learningRate: 0.0001,
-  margin: 0.5,           // Triplet loss margin
-  temperature: 0.07,     // InfoNCE temperature
-  hardNegativeRatio: 0.7, // Ratio of hard negatives
-  outputPath: join(OUTPUT_DIR, 'ruvltra-finetuned'),
-};
-
-/**
- * Get embedding from model
- */
-function getEmbedding(modelPath, text) {
-  try {
-    const sanitized = text.replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 500);
-    const result = execSync(
-      `llama-embedding -m "${modelPath}" -p "${sanitized}" --embd-output-format json 2>/dev/null`,
-      { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
-    );
-    const json = JSON.parse(result);
-    return json.data[json.data.length - 1].embedding;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Compute cosine similarity
- */
-function cosineSimilarity(a, b) {
-  if (!a || !b || a.length !== b.length) return 0;
-  let dot = 0, normA = 0, normB = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    normA += a[i] * a[i];
-    normB += b[i] * b[i];
-  }
-  return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
-}
-
-/**
- * Compute triplet loss
- * L = max(0, margin + d(anchor, positive) - d(anchor, negative))
- */
-function tripletLoss(anchorEmb, positiveEmb, negativeEmb, margin = CONFIG.margin) {
-  const posDist = 1 - cosineSimilarity(anchorEmb, positiveEmb);
-  const negDist = 1 - cosineSimilarity(anchorEmb, negativeEmb);
-  return Math.max(0, margin + posDist - negDist);
-}
-
-/**
- * Compute InfoNCE loss (contrastive)
- */
-function infoNCELoss(anchorEmb, positiveEmb, negativeEmbs, temperature = CONFIG.temperature) {
-  const posSim = cosineSimilarity(anchorEmb, positiveEmb) / temperature;
-  const negSims = negativeEmbs.map(neg => cosineSimilarity(anchorEmb, neg) / temperature);
-
-  // Softmax denominator
-  const maxSim = Math.max(posSim, ...negSims);
-  const expPos = Math.exp(posSim - maxSim);
-  const expNegs = negSims.map(sim => Math.exp(sim - maxSim));
-  const denominator = expPos + expNegs.reduce((a, b) => a + b, 0);
-
-  // Cross-entropy loss
-  return -Math.log(expPos / denominator);
-}
-
-/**
- * Prepare training batches with triplets
- */
-function prepareTrainingData(modelPath) {
-  console.log('Preparing training data...');
-
-  // Pre-compute agent description embeddings
-  const agentEmbeddings = {};
-  for (const [agent, desc] of Object.entries(AGENT_DESCRIPTIONS)) {
-    process.stdout.write(`  Embedding ${agent}... `);
-    agentEmbeddings[agent] = getEmbedding(modelPath, desc);
-    console.log('done');
-  }
-
-  // Create triplets from training examples
-  const triplets = [];
-  const agents = Object.keys(AGENT_DESCRIPTIONS);
-
-  console.log(`\nGenerating triplets from ${TRAINING_EXAMPLES.length} examples...`);
-
-  // Group examples by agent
-  const examplesByAgent = {};
-  for (const ex of TRAINING_EXAMPLES) {
-    if (!examplesByAgent[ex.agent]) examplesByAgent[ex.agent] = [];
-    examplesByAgent[ex.agent].push(ex);
-  }
-
-  // Create triplets: anchor task, positive agent, negative agent
-  for (const example of TRAINING_EXAMPLES.slice(0, 200)) { // Limit for speed
-    const anchorEmb = getEmbedding(modelPath, example.task);
-    if (!anchorEmb) continue;
-
-    const positiveAgent = example.agent;
-    const positiveEmb = agentEmbeddings[positiveAgent];
-
-    // Get hard negatives (confusing agents)
-    const hardNegatives = example.confusing_with
-      ? [example.confusing_with]
-      : agents.filter(a => a !== positiveAgent).slice(0, 2);
-
-    for (const negAgent of hardNegatives) {
-      const negativeEmb = agentEmbeddings[negAgent];
-      if (negativeEmb) {
-        triplets.push({
-          anchor: example.task,
-          anchorEmb,
-          positive: positiveAgent,
-          positiveEmb,
-          negative: negAgent,
-          negativeEmb,
-          isHard: !!example.confusing_with,
-        });
-      }
-    }
-
-    // Add random negative for diversity
-    const randomNeg = agents.filter(a => a !== positiveAgent)[Math.floor(Math.random() * (agents.length - 1))];
-    if (agentEmbeddings[randomNeg]) {
-      triplets.push({
-        anchor: example.task,
-        anchorEmb,
-        positive: positiveAgent,
-        positiveEmb,
-        negative: randomNeg,
-        negativeEmb: agentEmbeddings[randomNeg],
-        isHard: false,
-      });
-    }
-  }
-
-  console.log(`Created ${triplets.length} triplets`);
-  return { triplets, agentEmbeddings };
-}
-
-/**
- * Compute gradient for embedding update (simplified)
- * In practice, this would be done via proper backprop
- */
-function computeGradient(anchorEmb, positiveEmb, negativeEmb, lr = CONFIG.learningRate) {
-  const dim = anchorEmb.length;
-  const gradient = new Array(dim).fill(0);
-
-  // Pull anchor towards positive
-  for (let i = 0; i < dim; i++) {
-    gradient[i] += lr * (positiveEmb[i] - anchorEmb[i]);
-  }
-
-  // Push anchor away from negative
-  for (let i = 0; i < dim; i++) {
-    gradient[i] -= lr * 0.5 * (negativeEmb[i] - anchorEmb[i]);
-  }
-
-  return gradient;
-}
-
-/**
- * Export training data for external fine-tuning tools
- */
-function exportTrainingData(triplets, outputPath) {
-  console.log(`\nExporting training data to ${outputPath}...`);
-
-  // JSONL format for fine-tuning
-  const jsonlData = triplets.map(t => ({
-    anchor: t.anchor,
-    positive: t.positive,
-    negative: t.negative,
-    isHard: t.isHard,
-  }));
-
-  // CSV format for analysis
-  const csvData = [
-    'anchor,positive,negative,is_hard',
-    ...triplets.map(t => `"${t.anchor.replace(/"/g, '""')}",${t.positive},${t.negative},${t.isHard}`)
-  ].join('\n');
-
-  // Embedding matrix for direct training
-  const embeddingData = {
-    anchors: triplets.map(t => t.anchorEmb),
-    positives: triplets.map(t => t.positiveEmb),
-    negatives: triplets.map(t => t.negativeEmb),
-    labels: triplets.map(t => t.positive),
-  };
-
-  mkdirSync(outputPath, { recursive: true });
-  writeFileSync(join(outputPath, 'triplets.jsonl'), jsonlData.map(JSON.stringify).join('\n'));
-  writeFileSync(join(outputPath, 'triplets.csv'), csvData);
-  writeFileSync(join(outputPath, 'embeddings.json'), JSON.stringify(embeddingData, null, 2));
-
-  console.log(`  Exported ${triplets.length} triplets`);
-  return outputPath;
-}
-
-/**
- * Simulate training loop (compute losses)
- */
-function simulateTraining(triplets, epochs = CONFIG.epochs) {
-  console.log(`\nSimulating ${epochs} epochs of training...`);
-
-  const batchSize = CONFIG.batchSize;
-  const history = [];
-
-  for (let epoch = 0; epoch < epochs; epoch++) {
-    let epochLoss = 0;
-    let batchCount = 0;
-
-    // Shuffle triplets
-    const shuffled = [...triplets].sort(() => Math.random() - 0.5);
-
-    for (let i = 0; i < shuffled.length; i += batchSize) {
-      const batch = shuffled.slice(i, i + batchSize);
-      let batchLoss = 0;
-
-      for (const triplet of batch) {
-        const loss = tripletLoss(
-          triplet.anchorEmb,
-          triplet.positiveEmb,
-          triplet.negativeEmb
-        );
-        batchLoss += loss;
-      }
-
-      epochLoss += batchLoss / batch.length;
-      batchCount++;
-    }
-
-    const avgLoss = epochLoss / batchCount;
-    history.push({ epoch: epoch + 1, loss: avgLoss });
-
-    process.stdout.write(`  Epoch ${epoch + 1}/${epochs}: loss = ${avgLoss.toFixed(4)}\r`);
-  }
-
-  console.log('\n');
-  return history;
-}
-
-/**
- * Evaluate model on test set
- */
-function evaluateModel(modelPath, agentEmbeddings) {
-  const ROUTING_TESTS = [
-    { task: 'Implement a binary search function in TypeScript', expected: 'coder' },
-    { task: 'Write unit tests for the authentication module', expected: 'tester' },
-    { task: 'Review the pull request for security vulnerabilities', expected: 'reviewer' },
-    { task: 'Research best practices for React state management', expected: 'researcher' },
-    { task: 'Design the database schema for user profiles', expected: 'architect' },
-    { task: 'Fix the null pointer exception in the login handler', expected: 'debugger' },
-    { task: 'Audit the API endpoints for XSS vulnerabilities', expected: 'security-architect' },
-    { task: 'Write JSDoc comments for the utility functions', expected: 'documenter' },
-    { task: 'Refactor the payment module to use async/await', expected: 'refactorer' },
-    { task: 'Optimize the database queries for the dashboard', expected: 'optimizer' },
-    { task: 'Set up the CI/CD pipeline for the microservices', expected: 'devops' },
-    { task: 'Generate OpenAPI documentation for the REST API', expected: 'api-docs' },
-    { task: 'Create a sprint plan for the next two weeks', expected: 'planner' },
-    { task: 'Build a React component for user registration', expected: 'coder' },
-    { task: 'Debug memory leak in the WebSocket handler', expected: 'debugger' },
-    { task: 'Investigate slow API response times', expected: 'researcher' },
-    { task: 'Check code for potential race conditions', expected: 'reviewer' },
-    { task: 'Add integration tests for the payment gateway', expected: 'tester' },
-    { task: 'Plan the architecture for real-time notifications', expected: 'architect' },
-    { task: 'Cache the frequently accessed user data', expected: 'optimizer' },
-  ];
-
-  let correct = 0;
-  const results = [];
-
-  for (const test of ROUTING_TESTS) {
-    const taskEmb = getEmbedding(modelPath, test.task);
-
-    let bestAgent = 'coder';
-    let bestSim = -1;
-
-    for (const [agent, emb] of Object.entries(agentEmbeddings)) {
-      const sim = cosineSimilarity(taskEmb, emb);
-      if (sim > bestSim) {
-        bestSim = sim;
-        bestAgent = agent;
-      }
-    }
-
-    const isCorrect = bestAgent === test.expected;
-    if (isCorrect) correct++;
-    results.push({ task: test.task, expected: test.expected, got: bestAgent, correct: isCorrect });
-  }
-
-  return { accuracy: correct / ROUTING_TESTS.length, correct, total: ROUTING_TESTS.length, results };
-}
-
-/**
- * Generate LoRA adapter configuration
- */
-function generateLoRAConfig(outputPath) {
-  const loraConfig = {
-    model_type: 'qwen2',
-    base_model: 'Qwen/Qwen2.5-0.5B',
-    output_dir: outputPath,
-
-    // LoRA parameters
-    lora_r: 8,
-    lora_alpha: 16,
-    lora_dropout: 0.05,
-    target_modules: ['q_proj', 'v_proj', 'k_proj', 'o_proj'],
-
-    // Training parameters
-    learning_rate: CONFIG.learningRate,
-    num_train_epochs: CONFIG.epochs,
-    per_device_train_batch_size: CONFIG.batchSize,
-    gradient_accumulation_steps: 4,
-    warmup_ratio: 0.1,
-
-    // Contrastive loss parameters
-    loss_type: 'triplet',
-    margin: CONFIG.margin,
-    temperature: CONFIG.temperature,
-
-    // Data
-    train_data: join(outputPath, 'triplets.jsonl'),
-    eval_data: join(outputPath, 'eval.jsonl'),
-  };
-
-  writeFileSync(join(outputPath, 'lora_config.json'), JSON.stringify(loraConfig, null, 2));
-  return loraConfig;
-}
-
-/**
- * Generate training script for external tools
- */
-function generateTrainingScript(outputPath) {
-  const script = `#!/bin/bash
-# RuvLTRA Fine-tuning Script
-# Prerequisites: pip install transformers peft accelerate
-
-set -e
-
-MODEL_PATH="${outputPath}"
-BASE_MODEL="Qwen/Qwen2.5-0.5B"
-
-echo "=== RuvLTRA Contrastive Fine-tuning ==="
-echo "Base model: $BASE_MODEL"
-echo "Output: $MODEL_PATH"
-
-# Check for training data
-if [ ! -f "$MODEL_PATH/triplets.jsonl" ]; then
-  echo "Error: Training data not found at $MODEL_PATH/triplets.jsonl"
-  exit 1
-fi
-
-# Install dependencies if needed
-python3 -c "import transformers, peft" 2>/dev/null || {
-  echo "Installing dependencies..."
-  pip install transformers peft accelerate sentencepiece
-}
-
-# Fine-tune with LoRA
-python3 << 'PYTHON'
-import json
-import torch
-from pathlib import Path
-from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
-from peft import LoraConfig, get_peft_model, TaskType
-
-# Load config
-config_path = Path("${outputPath}/lora_config.json")
-with open(config_path) as f:
-    config = json.load(f)
-
-print(f"Loading base model: {config['base_model']}")
-
-# Load model and tokenizer
-tokenizer = AutoTokenizer.from_pretrained(config['base_model'])
-model = AutoModelForCausalLM.from_pretrained(
-    config['base_model'],
-    torch_dtype=torch.float16,
-    device_map='auto'
-)
-
-# Configure LoRA
-lora_config = LoraConfig(
-    r=config['lora_r'],
-    lora_alpha=config['lora_alpha'],
-    lora_dropout=config['lora_dropout'],
-    target_modules=config['target_modules'],
-    task_type=TaskType.CAUSAL_LM,
-)
-
-model = get_peft_model(model, lora_config)
-model.print_trainable_parameters()
-
-print("Model ready for fine-tuning!")
-print(f"Training data: {config['train_data']}")
-print("Note: Full training requires GPU. This script validates the setup.")
-PYTHON
-
-echo ""
-echo "=== Setup Complete ==="
-echo "To train on GPU, run the full training pipeline."
-echo "Training data exported to: $MODEL_PATH/triplets.jsonl"
-`;
-
-  writeFileSync(join(outputPath, 'train.sh'), script);
-  execSync(`chmod +x "${join(outputPath, 'train.sh')}"`);
-  return join(outputPath, 'train.sh');
-}
-
-/**
- * Main training pipeline
- */
-async function main() {
-  console.log('╔═══════════════════════════════════════════════════════════════════════════════════╗');
-  console.log('║           RuvLTRA Contrastive Fine-tuning Pipeline                                ║');
-  console.log('╚═══════════════════════════════════════════════════════════════════════════════════╝\n');
-
-  if (!existsSync(RUVLTRA_MODEL)) {
-    console.error('RuvLTRA model not found. Run download-models.sh first.');
-    process.exit(1);
-  }
-
-  const stats = getDatasetStats();
-  console.log(`Model: ${RUVLTRA_MODEL}`);
-  console.log(`Training examples: ${stats.totalExamples}`);
-  console.log(`Contrastive pairs: ${stats.contrastivePairs}`);
-  console.log(`Output: ${CONFIG.outputPath}\n`);
-
-  // Prepare training data
-  const { triplets, agentEmbeddings } = prepareTrainingData(RUVLTRA_MODEL);
-
-  // Export for external training
-  exportTrainingData(triplets, CONFIG.outputPath);
-
-  // Generate LoRA config
-  const loraConfig = generateLoRAConfig(CONFIG.outputPath);
-  console.log('Generated LoRA config:', join(CONFIG.outputPath, 'lora_config.json'));
-
-  // Generate training script
-  const scriptPath = generateTrainingScript(CONFIG.outputPath);
-  console.log('Generated training script:', scriptPath);
-
-  // Simulate training to show expected loss curve
-  const history = simulateTraining(triplets);
-
-  // Evaluate current model
-  console.log('─────────────────────────────────────────────────────────────────');
-  console.log('                   CURRENT MODEL EVALUATION');
-  console.log('─────────────────────────────────────────────────────────────────\n');
-
-  const evalResult = evaluateModel(RUVLTRA_MODEL, agentEmbeddings);
-  console.log(`Embedding-only accuracy: ${(evalResult.accuracy * 100).toFixed(1)}%\n`);
-
-  // Summary
-  console.log('═══════════════════════════════════════════════════════════════════════════════════');
-  console.log('                              TRAINING SUMMARY');
-  console.log('═══════════════════════════════════════════════════════════════════════════════════\n');
-
-  console.log('Training data exported:');
-  console.log(`  - ${join(CONFIG.outputPath, 'triplets.jsonl')} (${triplets.length} triplets)`);
-  console.log(`  - ${join(CONFIG.outputPath, 'triplets.csv')} (spreadsheet format)`);
-  console.log(`  - ${join(CONFIG.outputPath, 'embeddings.json')} (precomputed embeddings)`);
-  console.log(`  - ${join(CONFIG.outputPath, 'lora_config.json')} (LoRA configuration)`);
-  console.log(`  - ${join(CONFIG.outputPath, 'train.sh')} (training script)\n`);
-
-  console.log('Expected training loss (simulated):');
-  console.log(`  Initial: ${history[0].loss.toFixed(4)}`);
-  console.log(`  Final:   ${history[history.length - 1].loss.toFixed(4)}`);
-  console.log(`  Improvement: ${((1 - history[history.length - 1].loss / history[0].loss) * 100).toFixed(1)}%\n`);
-
-  console.log('To fine-tune on GPU:');
-  console.log(`  cd ${CONFIG.outputPath}`);
-  console.log('  ./train.sh\n');
-
-  console.log('After training, convert to GGUF:');
-  console.log('  python convert_lora.py --base Qwen/Qwen2.5-0.5B --lora ./lora-adapter');
-  console.log('  llama-quantize model-merged.gguf ruvltra-finetuned-q4_k_m.gguf q4_k_m\n');
-}
-
-main().catch(console.error);