Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

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

@@ -0,0 +1,225 @@
+# DSPy.ts Integration - Quick Start Guide
+
+## 🚀 5-Minute Start
+
+### 1. Install & Setup
+
+```bash
+cd /home/user/ruvector/packages/agentic-synth
+
+# Set API key
+export OPENAI_API_KEY="sk-your-key-here"
+```
+
+### 2. Run the Example
+
+```bash
+# Run the built-in example
+npx tsx training/dspy-real-integration.ts
+```
+
+### 3. Use in Your Code
+
+```typescript
+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
+
+```typescript
+{
+  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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```typescript
+trainer.on('status', msg => console.log('Status:', msg));
+trainer.on('progress', ({current, total}) => {
+  console.log(`Progress: ${current}/${total}`);
+});
+```
+
+### Handle Errors
+
+```typescript
+trainer.on('error', error => {
+  console.error('Training error:', error);
+});
+```
+
+### Multi-Model Training
+
+```typescript
+const trainer = new DSPyAgenticSynthTrainer({
+  models: [
+    'gpt-3.5-turbo',              // Fast baseline
+    'gpt-4',                      // High quality
+    'claude-3-sonnet-20240229'   // Alternative
+  ]
+});
+```
+
+## 🎨 Example Schemas
+
+### User Profile
+```typescript
+{
+  type: 'object',
+  properties: {
+    userId: { type: 'string' },
+    name: { type: 'string' },
+    email: { type: 'string', format: 'email' },
+    age: { type: 'number' }
+  }
+}
+```
+
+### E-commerce Product
+```typescript
+{
+  type: 'object',
+  properties: {
+    productId: { type: 'string' },
+    name: { type: 'string' },
+    price: { type: 'number' },
+    category: { type: 'string' }
+  }
+}
+```
+
+### Time Series
+```typescript
+{
+  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.** 🚀