wifi-densepose/npm/packages/agentic-synth/training/QUICK_START.md

DSPy.ts Integration - Quick Start Guide

🚀 5-Minute Start

1. Install & Setup

cd /home/user/ruvector/packages/agentic-synth

# Set API key
export OPENAI_API_KEY="sk-your-key-here"

2. Run the Example

# Run the built-in example
npx tsx training/dspy-real-integration.ts

3. Use in Your Code

import { DSPyAgenticSynthTrainer } from './training/dspy-real-integration.js';

// Define schema
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' },
    email: { type: 'string' }
  }
};

// Training examples
const examples = [{
  input: JSON.stringify(schema),
  output: JSON.stringify({ name: 'Alice', age: 28, email: 'alice@example.com' }),
  quality: 0.9
}];

// Create & initialize trainer
const trainer = new DSPyAgenticSynthTrainer({
  models: ['gpt-3.5-turbo'],
  optimizationRounds: 5,
  minQualityScore: 0.8
});

await trainer.initialize();

// Train with optimization
const result = await trainer.trainWithOptimization(schema, examples);
console.log(`Improvement: ${result.improvements.improvement}%`);

// Generate optimized data
const data = await trainer.generateOptimizedData(100, schema);
console.log(`Generated ${data.length} optimized samples`);

📋 Key Configuration Options

{
  models: ['gpt-3.5-turbo'],     // Models to use
  optimizationRounds: 5,          // Number of optimization iterations
  minQualityScore: 0.8,          // Quality threshold
  batchSize: 10,                 // Samples per iteration
  maxExamples: 50,               // Max training examples
  enableCaching: true,           // Cache results
  hooks: {                       // Event callbacks
    onIterationComplete: (iter, metrics) => { },
    onOptimizationComplete: (result) => { }
  }
}

🎯 Main Methods

Method	Purpose
initialize()	Setup DSPy.ts models
trainWithOptimization(schema, examples)	Train with auto-optimization
generateOptimizedData(count, schema?)	Generate quality data
evaluateQuality(data)	Assess data quality
getStatistics()	Get training stats

📊 Expected Results

Initial Quality:  0.70-0.75
Optimized:        0.85-0.90
Improvement:      15-25%
Convergence:      3-5 rounds
Speed:            2-5s/iteration

🔧 Environment Variables

# Required for OpenAI models
export OPENAI_API_KEY="sk-..."

# Optional for Claude models
export ANTHROPIC_API_KEY="sk-ant-..."

📚 Files Reference

File	Description
dspy-real-integration.ts	Main implementation (868 lines)
DSPY_INTEGRATION_README.md	Full documentation
test-dspy-integration.ts	Simple test
INTEGRATION_COMPLETE.md	Implementation summary
QUICK_START.md	This file

🧪 Quick Test

# Test without API key (structure check only)
npx tsx training/test-dspy-integration.ts

# Test with API key (full test)
export OPENAI_API_KEY="sk-..."
npx tsx training/test-dspy-integration.ts

⚡ Common Patterns

Monitor Progress

trainer.on('status', msg => console.log('Status:', msg));
trainer.on('progress', ({current, total}) => {
  console.log(`Progress: ${current}/${total}`);
});

Handle Errors

trainer.on('error', error => {
  console.error('Training error:', error);
});

Multi-Model Training

const trainer = new DSPyAgenticSynthTrainer({
  models: [
    'gpt-3.5-turbo',              // Fast baseline
    'gpt-4',                      // High quality
    'claude-3-sonnet-20240229'   // Alternative
  ]
});

🎨 Example Schemas

User Profile

{
  type: 'object',
  properties: {
    userId: { type: 'string' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    age: { type: 'number' }
  }
}

E-commerce Product

{
  type: 'object',
  properties: {
    productId: { type: 'string' },
    name: { type: 'string' },
    price: { type: 'number' },
    category: { type: 'string' }
  }
}

Time Series

{
  type: 'object',
  properties: {
    timestamp: { type: 'string', format: 'date-time' },
    metric: { type: 'string' },
    value: { type: 'number' }
  }
}

🐛 Troubleshooting

Issue	Solution
API Key Error	Set OPENAI_API_KEY environment variable
Import Error	Check Node.js version >= 18
Low Quality	Provide better training examples
Slow Performance	Reduce batchSize or use faster model

📖 Learn More

• Full API Reference: DSPY_INTEGRATION_README.md
• Implementation Details: INTEGRATION_COMPLETE.md
• Source Code: dspy-real-integration.ts

💡 Pro Tips

1. Start Simple: Begin with one model and few rounds
2. Good Examples: Provide high-quality training examples (>0.8 score)
3. Monitor Progress: Use event hooks to track improvement
4. Tune Threshold: Adjust minQualityScore based on your needs
5. Cache Results: Enable caching for repeated runs

---

Ready to go! Start with the example and customize from there. 🚀