ruvector/packages/agentic-synth

🎲 Agentic Synth

High-performance synthetic data generator for AI/ML training, RAG systems, and agentic workflows

Generate realistic, diverse synthetic data for training AI models, testing systems, and building robust agentic applications. Powered by Gemini and OpenRouter with intelligent context caching and model routing.

---

🚀 Why Agentic Synth?

The Problem: Training AI models and testing agentic systems requires massive amounts of diverse, high-quality data. Real data is expensive, privacy-sensitive, and often insufficient for edge cases.

The Solution: Agentic Synth generates unlimited synthetic data tailored to your exact needs—from time-series data to complex events and structured records—with built-in streaming, automation, and vector database integration.

---

✨ Features

🎯 Core Capabilities

• 🤖 Multi-Provider AI Integration - Gemini and OpenRouter with automatic fallback
• ⚡ Context Caching - 95%+ performance improvement with intelligent LRU cache
• 🧠 Smart Model Routing - Load balancing, performance-based selection, cost optimization
• 📊 Multiple Data Types - Time-series, events, structured data, embeddings
• 🌊 Streaming Support - Real-time data generation with AsyncGenerator
• 📦 Batch Processing - Parallel generation with concurrency control

🔌 Integrations

• 🎯 Ruvector - Native vector database integration (optional workspace dependency)
• 🤖 Agentic-Robotics - Automation workflow integration (optional peer dependency)
• 🌊 Midstreamer - Real-time streaming pipelines (optional peer dependency)
• 🦜 LangChain - AI application framework compatibility
• 🔍 AgenticDB - Agentic database compatibility layer

🛠️ Developer Experience

• 💻 Dual Interface - Use as SDK or CLI (npx agentic-synth)
• 📝 TypeScript-First - Full type safety with Zod runtime validation
• 🧪 98% Test Coverage - Comprehensive unit, integration, and E2E tests
• 📖 Rich Documentation - API reference, examples, troubleshooting guides
• ⚙️ Flexible Configuration - JSON, YAML, or programmatic setup

---

📦 Installation

# NPM
npm install @ruvector/agentic-synth

# Yarn
yarn add @ruvector/agentic-synth

# PNPM
pnpm add @ruvector/agentic-synth

# NPX (no installation required)
npx @ruvector/agentic-synth generate --count 100

---

🏃 Quick Start (< 5 minutes)

1️⃣ SDK Usage

import { AgenticSynth } from '@ruvector/agentic-synth';

// Initialize
const synth = new AgenticSynth({
  provider: 'gemini',
  apiKey: process.env.GEMINI_API_KEY,
  cache: { enabled: true, maxSize: 1000 }
});

// Generate time-series data
const timeSeries = await synth.generateTimeSeries({
  count: 100,
  interval: '1h',
  trend: 'upward',
  seasonality: true,
  noise: 0.1
});

// Generate event logs
const events = await synth.generateEvents({
  count: 50,
  types: ['login', 'purchase', 'logout'],
  distribution: 'poisson',
  timeRange: { start: '2024-01-01', end: '2024-12-31' }
});

// Generate structured data
const users = await synth.generateStructured({
  count: 200,
  schema: {
    name: { type: 'string', format: 'fullName' },
    email: { type: 'string', format: 'email' },
    age: { type: 'number', min: 18, max: 65 },
    score: { type: 'number', min: 0, max: 100, distribution: 'normal' }
  }
});

2️⃣ CLI Usage

# Generate time-series data
agentic-synth generate timeseries --count 100 --output data.json

# Generate events with custom schema
agentic-synth generate events \
  --count 50 \
  --types login,purchase,logout \
  --format csv \
  --output events.csv

# Generate structured data
agentic-synth generate structured \
  --schema ./schema.json \
  --count 200 \
  --output users.json

# Interactive mode
agentic-synth interactive

# Show configuration
agentic-synth config show

3️⃣ Streaming Example

import { AgenticSynth } from '@ruvector/agentic-synth';

const synth = new AgenticSynth({ provider: 'gemini' });

// Stream data in real-time
for await (const item of synth.generateStream({
  type: 'events',
  count: 1000,
  chunkSize: 10
})) {
  console.log('Generated:', item);
  // Process item immediately (e.g., send to queue, insert to DB)
}

---

🔧 Configuration

Environment Variables

# .env file
GEMINI_API_KEY=your_gemini_api_key
OPENROUTER_API_KEY=your_openrouter_api_key

# Optional integrations
RUVECTOR_URL=http://localhost:8080
MIDSTREAMER_ENDPOINT=ws://localhost:3000

Configuration File

{
  "provider": "gemini",
  "model": "gemini-2.0-flash-exp",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttl": 3600
  },
  "routing": {
    "strategy": "performance",
    "fallback": ["gemini", "openrouter"]
  },
  "output": {
    "format": "json",
    "pretty": true
  }
}

---

📊 Performance Benchmarks

Metric	Without Cache	With Cache	Improvement
P99 Latency	2,500ms	45ms	98.2%
Throughput	12 req/s	450 req/s	37.5x
Cache Hit Rate	N/A	85%	-
Memory Usage	180MB	220MB	+22%
Cost per 1K requests	$0.50	$0.08	84% savings

---

🎯 Use Cases

1. RAG System Training Data

Generate diverse Q&A pairs, document embeddings, and context for retrieval-augmented generation systems.

2. Agent Memory Synthesis

Create realistic conversation histories, decision logs, and state transitions for agentic AI systems.

3. ML Model Training

Generate labeled datasets for classification, regression, clustering, and anomaly detection.

4. Edge Case Testing

Produce boundary conditions, error scenarios, and stress test data for robust testing.

5. Time-Series Forecasting

Generate realistic time-series data with trends, seasonality, and noise for forecasting models.

---

🔗 Integration Examples

With Ruvector (Vector Database)

import { AgenticSynth } from '@ruvector/agentic-synth';
import { Ruvector } from 'ruvector';

const synth = new AgenticSynth();
const db = new Ruvector();

// Generate embeddings and insert to vector DB
const embeddings = await synth.generateStructured({
  count: 1000,
  schema: {
    text: { type: 'string', length: 100 },
    embedding: { type: 'vector', dimensions: 768 }
  }
});

await db.insertBatch(embeddings);

With Midstreamer (Real-time Streaming)

import { AgenticSynth } from '@ruvector/agentic-synth';
import { Midstreamer } from 'midstreamer';

const synth = new AgenticSynth();
const stream = new Midstreamer({ endpoint: 'ws://localhost:3000' });

// Stream generated data to real-time pipeline
for await (const data of synth.generateStream({ type: 'events' })) {
  await stream.send('events', data);
}

With Agentic-Robotics (Automation)

import { AgenticSynth } from '@ruvector/agentic-synth';
import { AgenticRobotics } from 'agentic-robotics';

const synth = new AgenticSynth();
const robotics = new AgenticRobotics();

// Automate data generation workflows
await robotics.schedule({
  task: 'generate-training-data',
  interval: '1h',
  action: async () => {
    const data = await synth.generateBatch({ count: 1000 });
    await robotics.store('training-data', data);
  }
});

---

📚 Documentation

• API Reference - Complete API documentation
• Examples - Advanced use cases and patterns
• Integrations - Integration guides for Ruvector, LangChain, etc.
• Troubleshooting - Common issues and solutions
• Performance Guide - Optimization tips and benchmarks
• Changelog - Version history and migration guides

---

🧪 Testing

# Run all tests (98% coverage)
npm test

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# CLI tests
npm run test:cli

# Coverage report
npm run test:coverage

# Benchmarks
npm run benchmark

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

Built with:

• Gemini - Google's generative AI
• OpenRouter - Multi-model AI routing
• Ruvector - High-performance vector database
• TypeScript - Type-safe development

---

🔗 Links

• GitHub: ruvnet/ruvector
• NPM: @ruvector/agentic-synth
• Issues: Report a bug
• Discussions: Join the community

---

Made with ❤️ by rUv