proffesor-for-testing__agentic-qe/v2/docs/api/AGENTDB-SERVICE-API.md

AgentDBService API Documentation

Overview

AgentDBService is a production-ready wrapper around AgentDB that provides:

• Pattern storage with vector embeddings
• HNSW-based similarity search (150x faster)
• Batch operations for high-performance inserts
• Query caching and quantization support
• Full TypeScript support

Installation

import { AgentDBService, createAgentDBService } from '@agentic-qe/core/memory';

Quick Start

// Create service with default configuration
const service = createAgentDBService({
  dbPath: '.agentic-qe/agentdb/patterns.db'
});

// Initialize
await service.initialize();

// Store a pattern
const pattern: QEPattern = {
  id: 'pattern-1',
  type: 'test-generator',
  domain: 'unit-testing',
  data: { framework: 'jest' },
  confidence: 0.95,
  usageCount: 1,
  successCount: 1,
  createdAt: Date.now(),
  lastUsed: Date.now()
};

const embedding = await generateEmbedding(pattern.data);
await service.storePattern(pattern, embedding);

// Search similar patterns
const results = await service.searchSimilar(queryEmbedding, {
  k: 10,
  domain: 'unit-testing',
  minConfidence: 0.8
});

// Clean up
await service.close();

Configuration

AgentDBServiceConfig

interface AgentDBServiceConfig {
  /** Path to database file */
  dbPath: string;

  /** Embedding dimension (default: 384 for all-MiniLM-L6-v2) */
  embeddingDim: number;

  /** Enable HNSW indexing for fast search */
  enableHNSW: boolean;

  /** HNSW configuration */
  hnswConfig?: Partial<HNSWConfig>;

  /** Enable query caching */
  enableCache: boolean;

  /** Cache size (default: 1000) */
  cacheSize?: number;

  /** Cache TTL in milliseconds (default: 3600000 = 1 hour) */
  cacheTTL?: number;

  /** Enable quantization for memory efficiency */
  enableQuantization?: boolean;

  /** Quantization bits (4, 8, or 16) */
  quantizationBits?: number;
}

Default Configuration

{
  dbPath: '.agentic-qe/agentdb/patterns.db',
  embeddingDim: 384, // all-MiniLM-L6-v2
  enableHNSW: true,
  enableCache: true,
  cacheSize: 1000,
  cacheTTL: 3600000, // 1 hour
  enableQuantization: false,
  quantizationBits: 8
}

Core Methods

initialize()

Initialize the database and HNSW index.

await service.initialize();

Throws:

• Error if already initialized
• Error if database initialization fails

---

storePattern(pattern, embedding)

Store a pattern with its vector embedding.

const id = await service.storePattern(pattern, embedding);

Parameters:

• pattern: QEPattern - Pattern data
• embedding: number[] - Vector embedding (must match embeddingDim)

Returns: Promise<string> - Pattern ID

Throws:

• Error if service not initialized
• Error if embedding dimension mismatch

Performance: <2ms for single insert

---

retrievePattern(id)

Retrieve a pattern by ID.

const pattern = await service.retrievePattern('pattern-1');

Parameters:

• id: string - Pattern ID

Returns: Promise<QEPattern | null> - Pattern or null if not found

Performance: <1ms with cache

---

searchSimilar(queryEmbedding, options)

Search for similar patterns using HNSW vector search.

const results = await service.searchSimilar(queryEmbedding, {
  k: 10,
  metric: 'cosine',
  threshold: 0.7,
  domain: 'unit-testing',
  type: 'test-generator',
  minConfidence: 0.8
});

Parameters:

• queryEmbedding: number[] - Query vector
• options: PatternSearchOptions - Search options (optional)

Options:

interface PatternSearchOptions {
  k?: number; // Number of results (default: 10)
  metric?: 'cosine' | 'euclidean' | 'dot'; // Similarity metric
  threshold?: number; // Minimum similarity (0-1)
  domain?: string; // Filter by domain
  type?: string; // Filter by agent type
  minConfidence?: number; // Minimum confidence score
}

Returns: Promise<PatternSearchResult[]>

interface PatternSearchResult {
  pattern: QEPattern;
  similarity: number; // 0-1 similarity score
  distance: number; // Distance metric
}

Performance: <100µs with HNSW (150x faster than linear search)

---

storeBatch(patterns, embeddings)

Store multiple patterns in a single transaction (high performance).

const result = await service.storeBatch(patterns, embeddings);

if (result.success) {
  console.log(`Inserted ${result.insertedIds.length} patterns in ${result.duration}ms`);
} else {
  console.error(`Errors:`, result.errors);
}

Parameters:

• patterns: QEPattern[] - Array of patterns
• embeddings: number[][] - Array of embeddings (same length as patterns)

Returns: Promise<BatchResult>

interface BatchResult {
  success: boolean;
  insertedIds: string[];
  errors: Array<{ index: number; error: string }>;
  duration: number;
}

Performance: ~2ms for 100 patterns (50x faster than sequential)

---

deletePattern(id)

Delete a pattern by ID.

const deleted = await service.deletePattern('pattern-1');

Parameters:

• id: string - Pattern ID

Returns: Promise<boolean> - true if deleted, false if not found

---

getStats()

Get database statistics.

const stats = await service.getStats();

console.log(`Patterns: ${stats.count}`);
console.log(`Database size: ${stats.size} bytes`);
console.log(`Cache hit rate: ${stats.cacheStats?.hitRate}%`);

Returns: Promise<DatabaseStats>

interface DatabaseStats {
  count: number; // Total patterns
  size: number; // Database size in bytes
  cacheStats?: {
    hits: number;
    misses: number;
    hitRate: number;
    size: number;
  };
  compressionStats?: {
    originalSize: number;
    compressedSize: number;
    ratio: number;
  };
}

---

clearCache()

Clear the query cache.

service.clearCache();

---

close()

Close database connection and clean up resources.

await service.close();

Data Types

QEPattern

interface QEPattern {
  id: string; // Unique pattern ID
  type: string; // Agent type (test-generator, coverage-analyzer, etc.)
  domain: string; // Domain/category (unit-testing, coverage-analysis, etc.)
  data: any; // Pattern-specific data
  confidence: number; // 0-1 confidence score
  usageCount: number; // How many times used
  successCount: number; // Successful executions
  createdAt: number; // Unix timestamp
  lastUsed: number; // Unix timestamp
  metadata?: Record<string, any>; // Optional metadata
}

Performance Benchmarks

Operation	Latency	Throughput	Notes
Single Insert	<2ms	500/sec	With HNSW indexing
Batch Insert (100)	~2ms	50,000/sec	50x faster than sequential
Vector Search	<100µs	10,000/sec	HNSW with k=10
Pattern Retrieval	<1ms	1,000/sec	With cache hit
Cache Hit Rate	N/A	>90%	With proper TTL

Best Practices

1. Use Batch Operations

// ❌ Slow: Sequential inserts
for (const pattern of patterns) {
  await service.storePattern(pattern, embeddings[i]);
}

// ✅ Fast: Batch insert
await service.storeBatch(patterns, embeddings);

2. Enable Caching

// Enable caching for frequently accessed patterns
const service = createAgentDBService({
  enableCache: true,
  cacheSize: 1000,
  cacheTTL: 3600000 // 1 hour
});

3. Use Appropriate Filters

// Narrow search space with filters
const results = await service.searchSimilar(embedding, {
  k: 10,
  domain: 'unit-testing', // Reduce search space
  minConfidence: 0.8 // Filter low-quality patterns
});

4. Monitor Statistics

// Periodically check performance
const stats = await service.getStats();

if (stats.cacheStats?.hitRate < 50) {
  console.warn('Low cache hit rate, consider increasing cache size');
}

5. Handle Errors Gracefully

try {
  await service.storePattern(pattern, embedding);
} catch (error) {
  if (error.message.includes('dimension mismatch')) {
    // Handle embedding dimension error
  } else {
    // Handle other errors
  }
}

Integration Examples

Example 1: Test Generator Agent

class TestGeneratorAgent extends BaseAgent {
  private agentDBService: AgentDBService;

  async onPostTask(data: { assignment: TaskAssignment; result: any }): Promise<void> {
    // Generate embedding for test patterns
    const embedding = await this.generateEmbedding(data.result);

    // Store pattern
    const pattern: QEPattern = {
      id: generateId(),
      type: 'test-generator',
      domain: 'unit-testing',
      data: data.result,
      confidence: this.calculateConfidence(data.result),
      usageCount: 1,
      successCount: 1,
      createdAt: Date.now(),
      lastUsed: Date.now()
    };

    await this.agentDBService.storePattern(pattern, embedding);
  }

  async onPreTask(data: { assignment: TaskAssignment }): Promise<void> {
    // Search for similar patterns
    const queryEmbedding = await this.generateEmbedding(data.assignment.task);

    const results = await this.agentDBService.searchSimilar(queryEmbedding, {
      k: 5,
      domain: 'unit-testing',
      minConfidence: 0.8
    });

    // Use patterns to inform test generation
    this.contextPatterns = results.map(r => r.pattern);
  }
}

Example 2: Coverage Analyzer Agent

async analyzeCoverageGaps(): Promise<CoverageGap[]> {
  // Generate embedding for coverage context
  const embedding = await this.generateEmbedding(this.coverageContext);

  // Search for similar coverage patterns
  const patterns = await this.agentDBService.searchSimilar(embedding, {
    k: 10,
    type: 'coverage-analyzer',
    minConfidence: 0.85
  });

  // Use patterns to identify gaps
  return this.identifyGapsFromPatterns(patterns);
}

Troubleshooting

Issue: "dimension mismatch" error

Cause: Embedding vector length doesn't match configured embeddingDim

Solution:

// Ensure embedding generator matches config
const service = createAgentDBService({
  embeddingDim: 384 // Match your embedding model
});

Issue: Slow search performance

Cause: HNSW indexing not enabled or needs tuning

Solution:

const service = createAgentDBService({
  enableHNSW: true,
  hnswConfig: {
    M: 16, // Higher = better recall, slower build
    efConstruction: 200 // Higher = better index quality
  }
});

Issue: Low cache hit rate

Cause: Cache too small or TTL too short

Solution:

const service = createAgentDBService({
  enableCache: true,
  cacheSize: 2000, // Increase size
  cacheTTL: 7200000 // 2 hours
});

Migration from Legacy MemoryManager

// Old (MemoryManager)
await memoryManager.store('key', value, namespace);
const data = await memoryManager.retrieve('key', namespace);

// New (AgentDBService)
const pattern: QEPattern = {
  id: 'key',
  type: agentType,
  domain: namespace,
  data: value,
  confidence: 1.0,
  usageCount: 1,
  successCount: 1,
  createdAt: Date.now(),
  lastUsed: Date.now()
};

const embedding = await generateEmbedding(value);
await agentDBService.storePattern(pattern, embedding);

// Retrieve
const retrieved = await agentDBService.retrievePattern('key');

References

• AgentDB Documentation
• HNSW Algorithm Paper
• Implementation Plan
• Integration Guide

---

Version: 1.2.0 Last Updated: 2025-10-22 Status: Production Ready