Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
433
npm/packages/agentic-synth/examples/docs/README.md
Normal file
433
npm/packages/agentic-synth/examples/docs/README.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# AgenticSynth Examples
|
||||
|
||||
Comprehensive examples demonstrating AgenticSynth's capabilities for synthetic data generation, DSPy integration, and agentic workflows.
|
||||
|
||||
## 📚 Table of Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
- [Core Examples](#core-examples)
|
||||
- [DSPy Integration](#dspy-integration)
|
||||
- [Specialized Examples](#specialized-examples)
|
||||
- [Testing](#testing)
|
||||
- [Configuration](#configuration)
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
# Node.js version
|
||||
node >= 18.0.0
|
||||
|
||||
# Environment setup
|
||||
cp .env.example .env
|
||||
# Edit .env with your API keys
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build the package
|
||||
npm run build
|
||||
|
||||
# Run an example
|
||||
npx tsx examples/basic-usage.ts
|
||||
```
|
||||
|
||||
## 📖 Core Examples
|
||||
|
||||
### 1. Basic Usage (`basic-usage.ts`)
|
||||
|
||||
**Purpose**: Introduction to AgenticSynth's core functionality
|
||||
|
||||
**Features**:
|
||||
- Structured data generation
|
||||
- Time-series generation
|
||||
- Event generation
|
||||
- Streaming support
|
||||
- Batch processing
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
export GEMINI_API_KEY=...
|
||||
npx tsx examples/basic-usage.ts
|
||||
```
|
||||
|
||||
### 2. Integration Examples (`integration-examples.ts`)
|
||||
|
||||
**Purpose**: Real-world integration patterns
|
||||
|
||||
**Features**:
|
||||
- Vector database integration (AgenticDB)
|
||||
- Streaming with Midstreamer
|
||||
- Robotics simulation
|
||||
- Multi-provider orchestration
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
npx tsx examples/integration-examples.ts
|
||||
```
|
||||
|
||||
### 3. Benchmark Example (`benchmark-example.ts`)
|
||||
|
||||
**Purpose**: Performance testing and comparison
|
||||
|
||||
**Features**:
|
||||
- Provider comparison (Gemini, OpenRouter, Claude)
|
||||
- Latency measurement
|
||||
- Token usage tracking
|
||||
- Quality assessment
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
npx tsx examples/benchmark-example.ts
|
||||
```
|
||||
|
||||
## 🧠 DSPy Integration
|
||||
|
||||
### DSPy Complete Example (`dspy-complete-example.ts`) ⭐ NEW
|
||||
|
||||
**Purpose**: Production-ready DSPy.ts + AgenticSynth integration
|
||||
|
||||
**What It Does**:
|
||||
1. Generates baseline e-commerce product data with AgenticSynth
|
||||
2. Sets up DSPy ChainOfThought reasoning module
|
||||
3. Uses BootstrapFewShot to learn from high-quality examples
|
||||
4. Compares baseline vs optimized results
|
||||
5. Generates detailed quality metrics and reports
|
||||
|
||||
**Key Features**:
|
||||
- ✅ Real DSPy.ts v2.1.1 modules (ChainOfThought, BootstrapFewShot)
|
||||
- ✅ Integration with AgenticSynth for baseline generation
|
||||
- ✅ Quality metrics (completeness, coherence, persuasiveness, SEO)
|
||||
- ✅ Cost and performance comparison
|
||||
- ✅ Production-ready error handling
|
||||
- ✅ Comprehensive documentation
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
export OPENAI_API_KEY=sk-...
|
||||
export GEMINI_API_KEY=...
|
||||
npx tsx examples/dspy-complete-example.ts
|
||||
```
|
||||
|
||||
**Expected Results**:
|
||||
- Baseline Quality: ~68%
|
||||
- Optimized Quality: ~84%
|
||||
- Quality Improvement: +23.6%
|
||||
- Cost Efficiency: +14.8%
|
||||
|
||||
**Documentation**: See [dspy-complete-example-guide.md](./docs/dspy-complete-example-guide.md)
|
||||
|
||||
### DSPy Training Example (`dspy-training-example.ts`)
|
||||
|
||||
**Purpose**: Multi-model DSPy training framework
|
||||
|
||||
**Features**:
|
||||
- Multi-model training sessions
|
||||
- Automatic prompt optimization
|
||||
- Cross-model learning
|
||||
- Cost-optimized training
|
||||
- Quality-focused training
|
||||
- Benchmark comparison
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
# Run specific example (0-4)
|
||||
npx tsx examples/dspy-training-example.ts 0
|
||||
```
|
||||
|
||||
### Verify DSPy Setup (`dspy-verify-setup.ts`)
|
||||
|
||||
**Purpose**: Pre-flight checks before running DSPy examples
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
npx tsx examples/dspy-verify-setup.ts
|
||||
```
|
||||
|
||||
## 🎯 Specialized Examples
|
||||
|
||||
### Business & Finance
|
||||
|
||||
#### Ad ROAS Optimization (`ad-roas/`)
|
||||
- `ad-campaign-optimizer.ts` - Campaign optimization
|
||||
- `roas-benchmark.ts` - ROAS benchmarking
|
||||
- `multi-channel-optimizer.ts` - Multi-channel campaigns
|
||||
|
||||
#### Stock Market (`stocks/`)
|
||||
- `stock-data-generator.ts` - Market data generation
|
||||
- `portfolio-simulator.ts` - Portfolio simulation
|
||||
- `risk-analyzer.ts` - Risk analysis
|
||||
|
||||
#### Crypto (`crypto/`)
|
||||
- `crypto-market-generator.ts` - Crypto market data
|
||||
- `defi-simulator.ts` - DeFi simulation
|
||||
- `nft-metadata-generator.ts` - NFT metadata
|
||||
|
||||
### Enterprise
|
||||
|
||||
#### Business Management (`business-management/`)
|
||||
- `crm-data-generator.ts` - CRM data
|
||||
- `inventory-simulator.ts` - Inventory management
|
||||
- `supply-chain-simulator.ts` - Supply chain
|
||||
|
||||
#### Employee Simulation (`employee-simulation/`)
|
||||
- `employee-generator.ts` - Employee profiles
|
||||
- `performance-simulator.ts` - Performance tracking
|
||||
- `org-chart-generator.ts` - Organization charts
|
||||
|
||||
### Development
|
||||
|
||||
#### CI/CD (`cicd/`)
|
||||
- `pipeline-generator.ts` - Pipeline configuration
|
||||
- `test-data-generator.ts` - Test data
|
||||
- `deployment-simulator.ts` - Deployment simulation
|
||||
|
||||
#### Security (`security/`)
|
||||
- `security-audit-generator.ts` - Security audits
|
||||
- `threat-simulator.ts` - Threat simulation
|
||||
- `compliance-checker.ts` - Compliance checks
|
||||
|
||||
### AI & Learning
|
||||
|
||||
#### Self-Learning (`self-learning/`)
|
||||
- `pattern-learner.ts` - Pattern recognition
|
||||
- `adaptive-generator.ts` - Adaptive generation
|
||||
- `feedback-optimizer.ts` - Feedback optimization
|
||||
|
||||
#### Agentic Jujutsu (`agentic-jujutsu/`)
|
||||
- `version-control-integration.ts` - VCS integration
|
||||
- `multi-agent-coordination.ts` - Agent coordination
|
||||
- `self-learning-commit.ts` - Self-learning commits
|
||||
|
||||
### Swarms (`swarms/`)
|
||||
- `multi-agent-generator.ts` - Multi-agent systems
|
||||
- `swarm-coordinator.ts` - Swarm coordination
|
||||
- `consensus-builder.ts` - Consensus mechanisms
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Run All Examples
|
||||
|
||||
```bash
|
||||
npx tsx examples/test-all-examples.ts
|
||||
```
|
||||
|
||||
### Run Specific Category
|
||||
|
||||
```bash
|
||||
# Business examples
|
||||
npx tsx examples/test-all-examples.ts --category business
|
||||
|
||||
# DSPy examples
|
||||
npx tsx examples/test-all-examples.ts --category dspy
|
||||
|
||||
# Integration examples
|
||||
npx tsx examples/test-all-examples.ts --category integration
|
||||
```
|
||||
|
||||
### Run Unit Tests
|
||||
|
||||
```bash
|
||||
npm run test:unit
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file in the package root:
|
||||
|
||||
```bash
|
||||
# Required for most examples
|
||||
GEMINI_API_KEY=...
|
||||
|
||||
# Required for DSPy examples
|
||||
OPENAI_API_KEY=sk-...
|
||||
|
||||
# Optional
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
OPENROUTER_API_KEY=sk-or-...
|
||||
TOGETHER_API_KEY=...
|
||||
|
||||
# Database (optional)
|
||||
AGENTDB_PATH=./data/agentdb
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
### Common Configuration Patterns
|
||||
|
||||
#### Provider Selection
|
||||
|
||||
```typescript
|
||||
import { AgenticSynth } from '@ruvector/agentic-synth';
|
||||
|
||||
// Gemini (Fast, cost-effective)
|
||||
const synthGemini = new AgenticSynth({
|
||||
provider: 'gemini',
|
||||
model: 'gemini-2.0-flash-exp'
|
||||
});
|
||||
|
||||
// OpenRouter (Access to many models)
|
||||
const synthOpenRouter = new AgenticSynth({
|
||||
provider: 'openrouter',
|
||||
model: 'anthropic/claude-3.5-sonnet'
|
||||
});
|
||||
|
||||
// Claude (High quality)
|
||||
const synthClaude = new AgenticSynth({
|
||||
provider: 'anthropic',
|
||||
model: 'claude-3-5-sonnet-20241022'
|
||||
});
|
||||
```
|
||||
|
||||
#### Caching
|
||||
|
||||
```typescript
|
||||
// Memory cache (default)
|
||||
const synth = new AgenticSynth({
|
||||
cacheStrategy: 'memory',
|
||||
cacheTTL: 3600
|
||||
});
|
||||
|
||||
// Redis cache (for distributed systems)
|
||||
const synth = new AgenticSynth({
|
||||
cacheStrategy: 'redis',
|
||||
cacheTTL: 3600,
|
||||
redisUrl: process.env.REDIS_URL
|
||||
});
|
||||
```
|
||||
|
||||
#### Streaming
|
||||
|
||||
```typescript
|
||||
// Enable streaming
|
||||
const synth = new AgenticSynth({
|
||||
streaming: true
|
||||
});
|
||||
|
||||
// Use streaming
|
||||
for await (const item of synth.generateStream('structured', options)) {
|
||||
console.log('Generated:', item);
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Example Comparison
|
||||
|
||||
| Example | Complexity | API Keys Required | Output | Use Case |
|
||||
|---------|-----------|-------------------|---------|----------|
|
||||
| basic-usage | ⭐ | GEMINI | Console | Learning basics |
|
||||
| dspy-complete-example | ⭐⭐⭐ | OPENAI, GEMINI | JSON + Report | Production DSPy |
|
||||
| dspy-training-example | ⭐⭐⭐ | Multiple | Metrics | Model training |
|
||||
| integration-examples | ⭐⭐ | GEMINI | Console | Integrations |
|
||||
| benchmark-example | ⭐⭐ | Multiple | Metrics | Performance |
|
||||
| ad-roas | ⭐⭐ | GEMINI | JSON | Marketing |
|
||||
| stocks | ⭐⭐ | GEMINI | JSON | Finance |
|
||||
| employee-simulation | ⭐ | GEMINI | JSON | HR |
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
### Beginner
|
||||
1. Start with `basic-usage.ts`
|
||||
2. Review `benchmark-example.ts`
|
||||
3. Try a specialized example (e.g., `employee-generator.ts`)
|
||||
|
||||
### Intermediate
|
||||
1. Review `integration-examples.ts`
|
||||
2. Try `dspy-verify-setup.ts`
|
||||
3. Run `dspy-complete-example.ts`
|
||||
4. Experiment with different categories
|
||||
|
||||
### Advanced
|
||||
1. Study `dspy-training-example.ts`
|
||||
2. Implement custom DSPy modules
|
||||
3. Build multi-agent systems with swarms
|
||||
4. Integrate with AgenticDB and vector databases
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Import Errors
|
||||
|
||||
```bash
|
||||
Error: Cannot find module '@ruvector/agentic-synth'
|
||||
```
|
||||
|
||||
**Solution**: Build the package
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
#### API Key Errors
|
||||
|
||||
```bash
|
||||
Error: Missing API key
|
||||
```
|
||||
|
||||
**Solution**: Set environment variables
|
||||
```bash
|
||||
export GEMINI_API_KEY=...
|
||||
```
|
||||
|
||||
#### Module Not Found (DSPy)
|
||||
|
||||
```bash
|
||||
Error: Cannot find module 'dspy.ts'
|
||||
```
|
||||
|
||||
**Solution**: Install dependencies
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
#### TypeScript Errors
|
||||
|
||||
```bash
|
||||
Error: Cannot find type definitions
|
||||
```
|
||||
|
||||
**Solution**: Check TypeScript version
|
||||
```bash
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Check the specific example's documentation
|
||||
2. Review the main [README.md](../README.md)
|
||||
3. Open an issue on [GitHub](https://github.com/ruvnet/ruvector/issues)
|
||||
4. Join the [Discord](https://discord.gg/ruvector)
|
||||
|
||||
## 📝 Contributing
|
||||
|
||||
Want to add an example?
|
||||
|
||||
1. Create a new file in the appropriate category
|
||||
2. Follow the existing patterns
|
||||
3. Add comprehensive comments
|
||||
4. Update this README
|
||||
5. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - See [LICENSE](../LICENSE) file for details.
|
||||
|
||||
## 🙏 Credits
|
||||
|
||||
Built with ❤️ by [rUv](https://github.com/ruvnet)
|
||||
|
||||
Special thanks to:
|
||||
- Stanford's DSPy team
|
||||
- AgenticDB contributors
|
||||
- The open-source community
|
||||
|
||||
---
|
||||
|
||||
**Need help?** Open an issue or join our [Discord](https://discord.gg/ruvector)
|
||||
Reference in New Issue
Block a user