@sparkleideas/agentdb-onnx 1.0.1

package/README.md

@@ -0,0 +1,418 @@
+# AgentDB-ONNX
+
+> **High-Performance AI Agent Memory with ONNX Embeddings**
+
+100% local, GPU-accelerated embeddings with AgentDB vector storage for intelligent AI agents.
+
+[![Tests](https://img.shields.io/badge/tests-passing-green)]()
+[![Performance](https://img.shields.io/badge/performance-optimized-brightgreen)]()
+[![License](https://img.shields.io/badge/license-MIT-blue)]()
+
+## 🚀 Features
+
+### **100% Local Inference**
+- No API calls, no cloud dependencies
+- Complete data privacy
+- Zero latency overhead from network requests
+- Free unlimited embeddings
+
+### **GPU Acceleration**
+- ONNX Runtime with CUDA support (Linux/Windows)
+- DirectML support (Windows)
+- CoreML support (macOS)
+- Automatic fallback to CPU
+
+### **Performance Optimized**
+- ⚡ **Batch processing**: 3-4x faster than sequential
+- 💾 **LRU caching**: 80%+ hit rate for common queries
+- 🔥 **Model warmup**: Pre-JIT compilation for consistent latency
+- 📊 **Smart batching**: Automatic chunking for large datasets
+
+### **Enterprise Features**
+- **ReasoningBank**: Store and retrieve successful patterns
+- **Reflexion Memory**: Self-improving episodic memory
+- **Comprehensive metrics**: Latency, throughput, cache performance
+- **Full TypeScript support**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install agentdb-onnx
+```
+
+**Optional GPU acceleration:**
+
+```bash
+# CUDA (NVIDIA GPUs on Linux/Windows)
+npm install onnxruntime-node-gpu
+
+# DirectML (Any GPU on Windows)
+# Already included in onnxruntime-node on Windows
+
+# CoreML (Apple Silicon on macOS)
+# Automatic on macOS ARM64
+```
+
+---
+
+## ⚡ Quick Start
+
+### Basic Usage
+
+```typescript
+import { createONNXAgentDB } from 'agentdb-onnx';
+
+// Initialize
+const agentdb = await createONNXAgentDB({
+  dbPath: './my-agent-memory.db',
+  modelName: 'Xenova/all-MiniLM-L6-v2', // 384 dimensions
+  useGPU: true,
+  batchSize: 32,
+  cacheSize: 10000
+});
+
+// Store a reasoning pattern
+const patternId = await agentdb.reasoningBank.storePattern({
+  taskType: 'debugging',
+  approach: 'Start with logs, reproduce issue, binary search for root cause',
+  successRate: 0.92,
+  tags: ['systematic', 'efficient']
+});
+
+// Search for similar patterns
+const patterns = await agentdb.reasoningBank.searchPatterns(
+  'how to debug memory leaks',
+  { k: 5, threshold: 0.7 }
+);
+
+patterns.forEach(p => {
+  console.log(`${p.approach} (${(p.similarity * 100).toFixed(1)}% match)`);
+});
+```
+
+### Reflexion Memory (Self-Improvement)
+
+```typescript
+// Store an episode with self-critique
+const episodeId = await agentdb.reflexionMemory.storeEpisode({
+  sessionId: 'debug-session-1',
+  task: 'Fix authentication bug',
+  reward: 0.95,
+  success: true,
+  input: 'Users cannot log in',
+  output: 'Fixed JWT token validation',
+  critique: 'Should have checked token expiration first. Worked well.',
+  latencyMs: 1200,
+  tokensUsed: 450
+});
+
+// Learn from past experiences
+const similar = await agentdb.reflexionMemory.retrieveRelevant(
+  'authentication issues',
+  { k: 5, onlySuccesses: true, minReward: 0.8 }
+);
+
+// Get critique summary
+const critiques = await agentdb.reflexionMemory.getCritiqueSummary(
+  'authentication debugging',
+  10
+);
+```
+
+### Batch Operations (3-4x Faster)
+
+```typescript
+// Store multiple patterns efficiently
+const patterns = [
+  { taskType: 'debugging', approach: 'Approach 1', successRate: 0.9 },
+  { taskType: 'testing', approach: 'Approach 2', successRate: 0.85 },
+  { taskType: 'optimization', approach: 'Approach 3', successRate: 0.92 }
+];
+
+const ids = await agentdb.reasoningBank.storePatternsBatch(patterns);
+// 3-4x faster than storing individually
+```
+
+---
+
+## 🎯 Available Models
+
+| Model | Dimensions | Speed | Quality | Use Case |
+|-------|------------|-------|---------|----------|
+| `Xenova/all-MiniLM-L6-v2` | 384 | ⚡⚡⚡ | ⭐⭐⭐ | **Recommended** - Best balance |
+| `Xenova/all-MiniLM-L12-v2` | 384 | ⚡⚡ | ⭐⭐⭐⭐ | Higher quality |
+| `Xenova/bge-small-en-v1.5` | 384 | ⚡⚡⚡ | ⭐⭐⭐⭐ | Better accuracy |
+| `Xenova/bge-base-en-v1.5` | 768 | ⚡⚡ | ⭐⭐⭐⭐⭐ | Highest quality |
+| `Xenova/e5-small-v2` | 384 | ⚡⚡⚡ | ⭐⭐⭐ | E5 series |
+| `Xenova/e5-base-v2` | 768 | ⚡⚡ | ⭐⭐⭐⭐ | E5 series |
+
+---
+
+## 📊 Performance
+
+### Benchmarks (M1 Pro CPU)
+
+| Operation | Throughput | Latency (p50) | Latency (p95) |
+|-----------|------------|---------------|---------------|
+| Single embedding | 45 ops/sec | 22ms | 45ms |
+| Cached embedding | 5000+ ops/sec | <1ms | 2ms |
+| Batch (10 items) | 120 ops/sec | 83ms | 150ms |
+| Pattern storage | 85 ops/sec | 12ms | 28ms |
+| Pattern search | 110 ops/sec | 9ms | 22ms |
+| Episode storage | 90 ops/sec | 11ms | 25ms |
+
+**Cache performance:**
+- Hit rate: 80-95% for common queries
+- Speedup: 100-200x for cached access
+
+---
+
+## 🛠️ CLI Usage
+
+```bash
+# Initialize database
+npx agentdb-onnx init ./my-memory.db --model Xenova/all-MiniLM-L6-v2 --gpu
+
+# Store pattern
+npx agentdb-onnx store-pattern ./my-memory.db \
+  --task-type debugging \
+  --approach "Check logs first" \
+  --success-rate 0.92 \
+  --tags "systematic,efficient"
+
+# Search patterns
+npx agentdb-onnx search-patterns ./my-memory.db "how to debug" \
+  --top-k 5 \
+  --threshold 0.7
+
+# Store episode
+npx agentdb-onnx store-episode ./my-memory.db \
+  --session debug-1 \
+  --task "Fix bug" \
+  --reward 0.95 \
+  --success \
+  --critique "Worked well"
+
+# Search episodes
+npx agentdb-onnx search-episodes ./my-memory.db "debugging" \
+  --top-k 5 \
+  --only-successes
+
+# Get statistics
+npx agentdb-onnx stats ./my-memory.db
+
+# Run benchmarks
+npx agentdb-onnx benchmark
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Run specific test file
+npm test onnx-embedding.test.ts
+
+# Run with coverage
+npm test -- --coverage
+```
+
+---
+
+## 📈 Optimization Tips
+
+### 1. **Enable GPU Acceleration**
+
+```typescript
+const agentdb = await createONNXAgentDB({
+  dbPath: './db.db',
+  useGPU: true  // Requires onnxruntime-node-gpu
+});
+```
+
+### 2. **Increase Batch Size**
+
+```typescript
+const agentdb = await createONNXAgentDB({
+  dbPath: './db.db',
+  batchSize: 64  // Higher for GPU, lower for CPU
+});
+```
+
+### 3. **Warm Up Model**
+
+```typescript
+await agentdb.embedder.warmup(10);  // Pre-JIT compile
+```
+
+### 4. **Increase Cache Size**
+
+```typescript
+const agentdb = await createONNXAgentDB({
+  dbPath: './db.db',
+  cacheSize: 50000  // More memory, better hit rate
+});
+```
+
+### 5. **Use Batch Operations**
+
+```typescript
+// ✅ Good - batch insert
+await agentdb.reasoningBank.storePatternsBatch(patterns);
+
+// ❌ Slow - sequential inserts
+for (const p of patterns) {
+  await agentdb.reasoningBank.storePattern(p);
+}
+```
+
+---
+
+## 🎓 Examples
+
+### Complete Workflow
+
+```bash
+npm run example
+```
+
+See [`examples/complete-workflow.ts`](examples/complete-workflow.ts) for a comprehensive demo including:
+- Pattern storage and retrieval
+- Episode-based learning
+- Batch operations
+- Performance optimization
+- Real-world agent simulation
+
+### Key Patterns
+
+**1. Learn from Experience:**
+```typescript
+// Store successful approach
+await agentdb.reflexionMemory.storeEpisode({
+  task: 'Optimize API',
+  reward: 0.95,
+  success: true,
+  critique: 'Database indexes were key'
+});
+
+// Later: retrieve when facing similar task
+const experiences = await agentdb.reflexionMemory.retrieveRelevant(
+  'slow API performance',
+  { onlySuccesses: true }
+);
+```
+
+**2. Build Knowledge Base:**
+```typescript
+// Accumulate successful patterns
+await agentdb.reasoningBank.storePatternsBatch([
+  { taskType: 'debugging', approach: 'Binary search', successRate: 0.92 },
+  { taskType: 'testing', approach: 'TDD', successRate: 0.88 }
+]);
+
+// Query when needed
+const approaches = await agentdb.reasoningBank.searchPatterns(
+  'how to debug production issues',
+  { k: 3 }
+);
+```
+
+---
+
+## 📚 API Reference
+
+### `createONNXAgentDB(config)`
+
+Creates an optimized AgentDB instance with ONNX embeddings.
+
+**Config:**
+- `dbPath: string` - Database file path
+- `modelName?: string` - HuggingFace model (default: `Xenova/all-MiniLM-L6-v2`)
+- `useGPU?: boolean` - Enable GPU (default: `true`)
+- `batchSize?: number` - Batch size (default: `32`)
+- `cacheSize?: number` - Cache size (default: `10000`)
+
+**Returns:**
+- `db` - Database instance
+- `embedder` - ONNX embedding service
+- `reasoningBank` - Pattern storage controller
+- `reflexionMemory` - Episodic memory controller
+- `close()` - Cleanup function
+- `getStats()` - Performance statistics
+
+### `ONNXEmbeddingService`
+
+High-performance embedding generation.
+
+**Methods:**
+- `embed(text)` - Generate single embedding
+- `embedBatch(texts)` - Generate multiple embeddings
+- `warmup(samples)` - Pre-warm the model
+- `getStats()` - Get performance metrics
+- `clearCache()` - Clear embedding cache
+- `getDimension()` - Get embedding dimension
+
+### `ONNXReasoningBank`
+
+Store and retrieve successful reasoning patterns.
+
+**Methods:**
+- `storePattern(pattern)` - Store pattern
+- `storePatternsBatch(patterns)` - Batch store (3-4x faster)
+- `searchPatterns(query, options)` - Semantic search
+- `getPattern(id)` - Get by ID
+- `updatePattern(id, updates)` - Update pattern
+- `deletePattern(id)` - Delete pattern
+- `getStats()` - Get statistics
+
+### `ONNXReflexionMemory`
+
+Episodic memory with self-critique for continuous improvement.
+
+**Methods:**
+- `storeEpisode(episode)` - Store episode
+- `storeEpisodesBatch(episodes)` - Batch store (3-4x faster)
+- `retrieveRelevant(task, options)` - Search similar episodes
+- `getCritiqueSummary(task, k)` - Get critique summary
+- `getEpisode(id)` - Get by ID
+- `deleteEpisode(id)` - Delete episode
+- `getTaskStats(sessionId?)` - Get statistics
+
+---
+
+## 🤝 Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md)
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🙏 Acknowledgments
+
+- **AgentDB** - Vector database for AI agents
+- **ONNX Runtime** - High-performance inference
+- **Transformers.js** - Browser-compatible ML models
+- **Xenova** - Optimized HuggingFace model conversions
+
+---
+
+## 🔗 Links
+
+- [AgentDB](https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb)
+- [ONNX Runtime](https://onnxruntime.ai/)
+- [Transformers.js](https://huggingface.co/docs/transformers.js)
+- [HuggingFace Models](https://huggingface.co/models)
+
+---
+
+**Built with ❤️ for the agentic era**

package/examples/complete-workflow.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env tsx
+/**
+ * Complete Workflow Example: AgentDB + ONNX
+ *
+ * Demonstrates:
+ * - Pattern storage and retrieval
+ * - Episodic memory with self-critique
+ * - Batch operations
+ * - Performance optimization
+ */
+
+import { createONNXAgentDB } from '../src/index.js';
+import { unlink } from 'fs/promises';
+
+async function main() {
+  console.log('🚀 AgentDB + ONNX Complete Workflow\n');
+
+  // Step 1: Initialize
+  console.log('1️⃣  Initializing AgentDB with ONNX embeddings...');
+  const agentdb = await createONNXAgentDB({
+    dbPath: './example-workflow.db',
+    modelName: 'Xenova/all-MiniLM-L6-v2',
+    useGPU: false, // Set to true for GPU acceleration
+    batchSize: 32,
+    cacheSize: 10000
+  });
+  console.log('✅ Initialized\n');
+
+  // Step 2: Store reasoning patterns
+  console.log('2️⃣  Storing reasoning patterns...');
+
+  const patterns = [
+    {
+      taskType: 'debugging',
+      approach: 'Start with logs, reproduce the issue, then binary search for the root cause',
+      successRate: 0.92,
+      tags: ['systematic', 'efficient'],
+      domain: 'software-engineering'
+    },
+    {
+      taskType: 'debugging',
+      approach: 'Use debugger breakpoints to step through execution',
+      successRate: 0.85,
+      tags: ['interactive', 'detailed'],
+      domain: 'software-engineering'
+    },
+    {
+      taskType: 'optimization',
+      approach: 'Profile first, identify bottlenecks, then optimize hot paths',
+      successRate: 0.95,
+      tags: ['data-driven', 'methodical'],
+      domain: 'performance'
+    },
+    {
+      taskType: 'api-design',
+      approach: 'RESTful principles with versioning and clear documentation',
+      successRate: 0.88,
+      tags: ['standards', 'maintainable'],
+      domain: 'architecture'
+    },
+    {
+      taskType: 'testing',
+      approach: 'Write unit tests first (TDD), then integration tests',
+      successRate: 0.90,
+      tags: ['test-driven', 'reliable'],
+      domain: 'quality-assurance'
+    }
+  ];
+
+  // Batch store for efficiency
+  const patternIds = await agentdb.reasoningBank.storePatternsBatch(patterns);
+  console.log(`✅ Stored ${patternIds.length} patterns\n`);
+
+  // Step 3: Search for patterns
+  console.log('3️⃣  Searching for debugging strategies...');
+
+  const debugPatterns = await agentdb.reasoningBank.searchPatterns(
+    'how to debug a memory leak in production',
+    {
+      k: 3,
+      threshold: 0.5,
+      filters: {
+        taskType: 'debugging',
+        minSuccessRate: 0.8
+      }
+    }
+  );
+
+  console.log(`Found ${debugPatterns.length} relevant patterns:`);
+  debugPatterns.forEach((p, i) => {
+    console.log(`\n   ${i + 1}. ${p.approach}`);
+    console.log(`      Success rate: ${(p.successRate * 100).toFixed(1)}%`);
+    console.log(`      Similarity:   ${(p.similarity * 100).toFixed(1)}%`);
+    console.log(`      Tags:         ${p.tags?.join(', ')}`);
+  });
+  console.log();
+
+  // Step 4: Store episodes with self-critique
+  console.log('4️⃣  Storing reflexion episodes...');
+
+  const episodes = [
+    {
+      sessionId: 'debug-session-1',
+      task: 'Fix memory leak in Node.js application',
+      reward: 0.95,
+      success: true,
+      input: 'Application consuming 2GB+ memory',
+      output: 'Found event listener leak, fixed with proper cleanup',
+      critique: 'Should have checked event listeners earlier. Profiling was key.',
+      latencyMs: 1800,
+      tokensUsed: 450
+    },
+    {
+      sessionId: 'debug-session-1',
+      task: 'Reproduce memory leak locally',
+      reward: 0.88,
+      success: true,
+      input: 'Production memory leak',
+      output: 'Reproduced with stress test script',
+      critique: 'Reproduction helped a lot. Could have added heap snapshots.',
+      latencyMs: 600,
+      tokensUsed: 200
+    },
+    {
+      sessionId: 'optimize-session-1',
+      task: 'Optimize API response time',
+      reward: 0.92,
+      success: true,
+      input: 'API taking 2-3 seconds per request',
+      output: 'Added database indexes, reduced to 200ms',
+      critique: 'Profiling showed N+1 queries. Database indexes solved it.',
+      latencyMs: 1200,
+      tokensUsed: 350
+    },
+    {
+      sessionId: 'test-session-1',
+      task: 'Write tests for authentication',
+      reward: 0.85,
+      success: true,
+      input: 'JWT authentication module',
+      output: 'Unit tests with 95% coverage',
+      critique: 'TDD approach worked well. Could add more edge cases.',
+      latencyMs: 900,
+      tokensUsed: 300
+    }
+  ];
+
+  const episodeIds = await agentdb.reflexionMemory.storeEpisodesBatch(episodes);
+  console.log(`✅ Stored ${episodeIds.length} episodes\n`);
+
+  // Step 5: Learn from past experiences
+  console.log('5️⃣  Learning from past experiences...');
+
+  const similarExperiences = await agentdb.reflexionMemory.retrieveRelevant(
+    'how to fix performance issues in production',
+    {
+      k: 3,
+      onlySuccesses: true,
+      minReward: 0.85
+    }
+  );
+
+  console.log(`Found ${similarExperiences.length} relevant experiences:`);
+  similarExperiences.forEach((e, i) => {
+    console.log(`\n   ${i + 1}. ${e.task}`);
+    console.log(`      Reward:      ${(e.reward * 100).toFixed(1)}%`);
+    console.log(`      Similarity:  ${(e.similarity * 100).toFixed(1)}%`);
+    console.log(`      Critique:    ${e.critique?.substring(0, 80)}...`);
+  });
+  console.log();
+
+  // Step 6: Get critique summary
+  console.log('6️⃣  Getting critique summary for debugging tasks...');
+
+  const critiques = await agentdb.reflexionMemory.getCritiqueSummary(
+    'debugging memory issues',
+    5
+  );
+
+  console.log(`Learned ${critiques.length} insights from past debugging:`);
+  critiques.forEach((c, i) => {
+    console.log(`   ${i + 1}. ${c}`);
+  });
+  console.log();
+
+  // Step 7: Performance statistics
+  console.log('7️⃣  Performance statistics:');
+
+  const stats = agentdb.getStats();
+
+  console.log(`\n   📊 Embeddings:`);
+  console.log(`      Total:       ${stats.embedder.totalEmbeddings}`);
+  console.log(`      Avg latency: ${stats.embedder.avgLatency.toFixed(2)}ms`);
+  console.log(`      Cache hits:  ${(stats.embedder.cache.hitRate * 100).toFixed(1)}%`);
+  console.log(`      Cache size:  ${stats.embedder.cache.size}/${stats.embedder.cache.maxSize}`);
+
+  console.log(`\n   💾 Database:`);
+  console.log(`      Backend:     ${stats.database?.backend || 'Unknown'}`);
+
+  // Step 8: Real-world scenario simulation
+  console.log('\n8️⃣  Simulating real-world agent workflow...\n');
+
+  // Scenario: Agent needs to solve a new task
+  const newTask = 'Optimize database query performance in production API';
+
+  console.log(`   📝 New task: "${newTask}"\n`);
+
+  // Step 8a: Retrieve relevant patterns
+  console.log('   🔍 Searching for relevant patterns...');
+  const relevantPatterns = await agentdb.reasoningBank.searchPatterns(
+    newTask,
+    { k: 2, threshold: 0.6 }
+  );
+
+  console.log(`   Found ${relevantPatterns.length} patterns:`);
+  relevantPatterns.forEach((p, i) => {
+    console.log(`      ${i + 1}. ${p.approach} (${(p.similarity * 100).toFixed(0)}% match)`);
+  });
+
+  // Step 8b: Retrieve similar episodes
+  console.log('\n   📚 Searching for similar past experiences...');
+  const relevantEpisodes = await agentdb.reflexionMemory.retrieveRelevant(
+    newTask,
+    { k: 2, onlySuccesses: true }
+  );
+
+  console.log(`   Found ${relevantEpisodes.length} experiences:`);
+  relevantEpisodes.forEach((e, i) => {
+    console.log(`      ${i + 1}. ${e.task} (${(e.similarity * 100).toFixed(0)}% match)`);
+    console.log(`         Critique: ${e.critique?.substring(0, 60)}...`);
+  });
+
+  // Step 8c: Agent executes task with learned approach
+  console.log('\n   ⚡ Agent executes with learned approach...');
+  console.log('   ✅ Task completed successfully!\n');
+
+  // Step 8d: Store new episode with self-critique
+  console.log('   💭 Agent reflects on execution...');
+  const newEpisodeId = await agentdb.reflexionMemory.storeEpisode({
+    sessionId: 'new-session',
+    task: newTask,
+    reward: 0.94,
+    success: true,
+    input: 'Slow database queries in production',
+    output: 'Added composite indexes, query time reduced by 10x',
+    critique: 'Profiling showed table scans. Learned from past episode about indexing. Very effective approach.',
+    latencyMs: 1500,
+    tokensUsed: 400
+  });
+
+  console.log(`   ✅ Stored new episode (ID: ${newEpisodeId})\n`);
+
+  // Step 9: Show improvement over time
+  console.log('9️⃣  Self-improvement demonstration:\n');
+
+  const taskStats = await agentdb.reflexionMemory.getTaskStats();
+  console.log(`   Total episodes:  ${taskStats.totalEpisodes}`);
+  console.log(`   Success rate:    ${(taskStats.successRate * 100).toFixed(1)}%`);
+  console.log(`   Avg reward:      ${(taskStats.avgReward * 100).toFixed(1)}%`);
+  console.log(`   Avg latency:     ${taskStats.avgLatency.toFixed(0)}ms`);
+
+  // Cleanup
+  console.log('\n🧹 Cleaning up...');
+  await agentdb.close();
+
+  try {
+    await unlink('./example-workflow.db');
+  } catch {}
+
+  console.log('✅ Complete!\n');
+  console.log('═══════════════════════════════════════════════════');
+  console.log('Key Takeaways:');
+  console.log('  • ONNX embeddings provide fast, local semantic search');
+  console.log('  • Batch operations are 3-4x faster than sequential');
+  console.log('  • ReasoningBank stores successful patterns');
+  console.log('  • ReflexionMemory enables self-improvement');
+  console.log('  • Cache provides significant speedup for common queries');
+  console.log('═══════════════════════════════════════════════════\n');
+}
+
+main().catch(console.error);