agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/src/tests/wasm-vector-search.test.ts

@@ -0,0 +1,240 @@
+/**
+ * WASM Vector Search Tests
+ *
+ * Integration tests for WASM-accelerated vector operations
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { WASMVectorSearch } from '../controllers/WASMVectorSearch.js';
+import { EnhancedEmbeddingService } from '../controllers/EnhancedEmbeddingService.js';
+
+describe('WASMVectorSearch', () => {
+  let mockDb: any;
+  let wasmSearch: WASMVectorSearch;
+
+  beforeEach(() => {
+    mockDb = {
+      prepare: () => ({ all: () => [], get: () => null, run: () => ({ lastInsertRowid: 1, changes: 1 }) }),
+      exec: () => {},
+    };
+
+    wasmSearch = new WASMVectorSearch(mockDb);
+  });
+
+  describe('Cosine Similarity', () => {
+    it('should calculate cosine similarity correctly', () => {
+      const vectorA = new Float32Array([1, 0, 0]);
+      const vectorB = new Float32Array([1, 0, 0]);
+
+      const similarity = wasmSearch.cosineSimilarity(vectorA, vectorB);
+      expect(similarity).toBeCloseTo(1.0, 5);
+    });
+
+    it('should handle orthogonal vectors', () => {
+      const vectorA = new Float32Array([1, 0, 0]);
+      const vectorB = new Float32Array([0, 1, 0]);
+
+      const similarity = wasmSearch.cosineSimilarity(vectorA, vectorB);
+      expect(similarity).toBeCloseTo(0.0, 5);
+    });
+
+    it('should handle opposite vectors', () => {
+      const vectorA = new Float32Array([1, 0, 0]);
+      const vectorB = new Float32Array([-1, 0, 0]);
+
+      const similarity = wasmSearch.cosineSimilarity(vectorA, vectorB);
+      expect(similarity).toBeCloseTo(-1.0, 5);
+    });
+
+    it('should throw error for mismatched dimensions', () => {
+      const vectorA = new Float32Array([1, 0, 0]);
+      const vectorB = new Float32Array([1, 0]);
+
+      expect(() => wasmSearch.cosineSimilarity(vectorA, vectorB)).toThrow();
+    });
+  });
+
+  describe('Batch Similarity', () => {
+    it('should calculate batch similarities', () => {
+      const query = new Float32Array([1, 0, 0]);
+      const vectors = [
+        new Float32Array([1, 0, 0]),
+        new Float32Array([0, 1, 0]),
+        new Float32Array([0, 0, 1]),
+      ];
+
+      const similarities = wasmSearch.batchSimilarity(query, vectors);
+
+      expect(similarities).toHaveLength(3);
+      expect(similarities[0]).toBeCloseTo(1.0, 5);
+      expect(similarities[1]).toBeCloseTo(0.0, 5);
+      expect(similarities[2]).toBeCloseTo(0.0, 5);
+    });
+
+    it('should handle large batches efficiently', () => {
+      const query = new Float32Array(384).fill(0.5);
+      const vectors: Float32Array[] = [];
+
+      for (let i = 0; i < 1000; i++) {
+        vectors.push(new Float32Array(384).fill(Math.random()));
+      }
+
+      const startTime = performance.now();
+      const similarities = wasmSearch.batchSimilarity(query, vectors);
+      const duration = performance.now() - startTime;
+
+      expect(similarities).toHaveLength(1000);
+      expect(duration).toBeLessThan(1000); // Should complete in under 1 second
+    });
+  });
+
+  describe('Vector Index', () => {
+    it('should build index for large datasets', () => {
+      const vectors: Float32Array[] = [];
+      const ids: number[] = [];
+
+      for (let i = 0; i < 1500; i++) {
+        vectors.push(new Float32Array(128).fill(Math.random()));
+        ids.push(i);
+      }
+
+      wasmSearch.buildIndex(vectors, ids);
+
+      const stats = wasmSearch.getStats();
+      expect(stats.indexBuilt).toBe(true);
+      expect(stats.indexSize).toBe(1500);
+    });
+
+    it('should search index correctly', () => {
+      const vectors: Float32Array[] = [
+        new Float32Array([1, 0, 0]),
+        new Float32Array([0, 1, 0]),
+        new Float32Array([0, 0, 1]),
+        new Float32Array([0.7, 0.7, 0]),
+      ];
+      const ids = [1, 2, 3, 4];
+
+      wasmSearch = new WASMVectorSearch(mockDb, { indexThreshold: 3 });
+      wasmSearch.buildIndex(vectors, ids);
+
+      const query = new Float32Array([1, 0, 0]);
+      const results = wasmSearch.searchIndex(query, 2);
+
+      expect(results).toHaveLength(2);
+      expect(results[0].id).toBe(1); // Most similar
+      expect(results[0].similarity).toBeCloseTo(1.0, 5);
+    });
+
+    it('should clear index', () => {
+      const vectors = [new Float32Array([1, 0, 0])];
+      const ids = [1];
+
+      wasmSearch = new WASMVectorSearch(mockDb, { indexThreshold: 0 });
+      wasmSearch.buildIndex(vectors, ids);
+
+      let stats = wasmSearch.getStats();
+      expect(stats.indexBuilt).toBe(true);
+
+      wasmSearch.clearIndex();
+      stats = wasmSearch.getStats();
+      expect(stats.indexBuilt).toBe(false);
+    });
+  });
+
+  describe('Statistics', () => {
+    it('should report correct stats', () => {
+      const stats = wasmSearch.getStats();
+
+      expect(stats).toHaveProperty('wasmAvailable');
+      expect(stats).toHaveProperty('simdAvailable');
+      expect(stats).toHaveProperty('indexBuilt');
+      expect(stats).toHaveProperty('indexSize');
+      expect(typeof stats.wasmAvailable).toBe('boolean');
+      expect(typeof stats.simdAvailable).toBe('boolean');
+    });
+  });
+});
+
+describe('EnhancedEmbeddingService', () => {
+  let service: EnhancedEmbeddingService;
+
+  beforeEach(async () => {
+    service = new EnhancedEmbeddingService({
+      model: 'mock-model',
+      dimension: 384,
+      provider: 'local',
+      enableWASM: true,
+      enableBatchProcessing: true,
+      batchSize: 50,
+    });
+
+    await service.initialize();
+  });
+
+  describe('Batch Processing', () => {
+    it('should embed batch of texts', async () => {
+      const texts = ['hello', 'world', 'test', 'embedding', 'service'];
+      const embeddings = await service.embedBatch(texts);
+
+      expect(embeddings).toHaveLength(5);
+      embeddings.forEach(emb => {
+        expect(emb).toBeInstanceOf(Float32Array);
+        expect(emb.length).toBe(384);
+      });
+    });
+
+    it('should handle large batches efficiently', async () => {
+      const texts = Array.from({ length: 200 }, (_, i) => `text ${i}`);
+
+      const startTime = performance.now();
+      const embeddings = await service.embedBatch(texts);
+      const duration = performance.now() - startTime;
+
+      expect(embeddings).toHaveLength(200);
+      console.log(`Batch embedding of 200 texts took ${duration.toFixed(2)}ms`);
+    });
+  });
+
+  describe('Similarity', () => {
+    it('should calculate text similarity', async () => {
+      const similarity = await service.similarity('hello world', 'hello world');
+      expect(similarity).toBeCloseTo(1.0, 5);
+    });
+
+    it('should find most similar texts', async () => {
+      const corpus = [
+        'machine learning',
+        'artificial intelligence',
+        'deep learning',
+        'cooking recipes',
+        'neural networks',
+      ];
+
+      const results = await service.findMostSimilar('AI and ML', corpus, 3);
+
+      expect(results).toHaveLength(3);
+      expect(results[0]).toHaveProperty('text');
+      expect(results[0]).toHaveProperty('similarity');
+      expect(results[0]).toHaveProperty('index');
+
+      // Note: Mock embeddings are deterministic but not semantic,
+      // so we just verify the structure is correct
+      results.forEach(result => {
+        expect(result.similarity).toBeGreaterThanOrEqual(-1);
+        expect(result.similarity).toBeLessThanOrEqual(1);
+        expect(corpus).toContain(result.text);
+      });
+    });
+  });
+
+  describe('Statistics', () => {
+    it('should provide service statistics', () => {
+      const stats = service.getStats();
+
+      expect(stats).toHaveProperty('cacheSize');
+      expect(stats).toHaveProperty('wasmEnabled');
+      expect(stats).toHaveProperty('simdEnabled');
+      expect(typeof stats.cacheSize).toBe('number');
+    });
+  });
+});

package/src/types/attention.ts

@@ -0,0 +1,392 @@
+/**
+ * Attention Type Definitions for AgentDB v2
+ *
+ * Shared types for @ruvector/attention integration across memory controllers.
+ * These types are used by AttentionService and all enhanced controllers.
+ *
+ * @module types/attention
+ * @see controllers/AttentionService
+ * @see docs/integration/ARCHITECTURE.md
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Available attention mechanisms from @ruvector/attention
+ */
+export type AttentionMechanism =
+  | 'multihead' // Standard multi-head attention (Vaswani 2017)
+  | 'flash' // FlashAttention with block-wise tiling (Dao 2022)
+  | 'hyperbolic' // Hyperbolic attention using Poincaré distance
+  | 'graphrope' // Graph-aware RoPE with hop distances
+  | 'moe' // Mixture of Experts with sparse gating
+  | 'dualspace' // Hybrid Euclidean + hyperbolic fusion
+  | 'linear'; // Linear attention with kernel approximation
+
+/**
+ * Runtime environment detection
+ */
+export type AttentionRuntime = 'node' | 'browser' | 'auto';
+
+/**
+ * Backend implementation (NAPI for Node.js, WASM for browser)
+ */
+export type AttentionBackend = 'napi' | 'wasm';
+
+// ============================================================================
+// Memory Controller Enhancement Configurations
+// ============================================================================
+
+/**
+ * Configuration for memory controllers with attention enhancements
+ */
+export interface MemoryControllerAttentionConfig {
+  /** Enable hyperbolic attention for CausalMemoryGraph */
+  enableHyperbolicAttention?: boolean;
+
+  /** Enable FlashAttention for large memory consolidation */
+  enableFlashAttention?: boolean;
+
+  /** Enable GraphRoPE for graph-aware retrieval */
+  enableGraphRoPE?: boolean;
+
+  /** Enable MoE for expert routing */
+  enableMoERouting?: boolean;
+
+  /** Enable DualSpace for hybrid retrieval */
+  enableDualSpace?: boolean;
+
+  /** Hyperbolic attention curvature (default: -1.0) */
+  hyperbolicCurvature?: number;
+
+  /** FlashAttention block size (default: 256) */
+  flashBlockSize?: number;
+
+  /** GraphRoPE maximum hops (default: 32) */
+  maxGraphHops?: number;
+
+  /** MoE number of experts (default: 4) */
+  numExperts?: number;
+
+  /** MoE top-k expert selection (default: 1) */
+  expertTopK?: number;
+
+  /** Fallback to vector search on errors (default: true) */
+  fallbackToVector?: boolean;
+}
+
+// ============================================================================
+// Enhanced Search Results
+// ============================================================================
+
+/**
+ * Search result with attention scores (extends standard SearchResult)
+ */
+export interface AttentionEnhancedResult {
+  /** Original result ID */
+  id: string | number;
+
+  /** Original similarity/distance */
+  similarity: number;
+
+  /** Attention weight (0-1, higher = more relevant) */
+  attentionScore?: number;
+
+  /** Mechanism used for re-ranking */
+  mechanism?: AttentionMechanism;
+
+  /** Attention-weighted final score */
+  finalScore?: number;
+
+  /** Optional metadata */
+  metadata?: Record<string, any>;
+}
+
+// ============================================================================
+// CausalMemoryGraph Enhancements
+// ============================================================================
+
+/**
+ * Causal query with hyperbolic attention options
+ */
+export interface CausalQueryWithAttention {
+  /** Base causal query parameters */
+  interventionMemoryId: number;
+  interventionMemoryType: string;
+  outcomeMemoryId?: number;
+  minConfidence?: number;
+  minUplift?: number;
+
+  /** Hyperbolic attention options */
+  useHyperbolicAttention?: boolean;
+  curvature?: number;
+  temperature?: number;
+
+  /** Return attention weights for visualization */
+  returnWeights?: boolean;
+}
+
+/**
+ * Causal edge with hyperbolic attention metadata
+ */
+export interface CausalEdgeWithAttention {
+  /** Standard causal edge fields */
+  id?: number;
+  fromMemoryId: number;
+  fromMemoryType: string;
+  toMemoryId: number;
+  toMemoryType: string;
+  similarity: number;
+  uplift?: number;
+  confidence: number;
+
+  /** Hyperbolic attention enhancements */
+  hyperbolicScore?: number;
+  attentionWeight?: number;
+  mechanism?: 'hyperbolic' | 'vector';
+
+  /** Tree distance in Poincaré ball */
+  poincareDistance?: number;
+}
+
+// ============================================================================
+// ReasoningBank Enhancements
+// ============================================================================
+
+/**
+ * Pattern search query with Flash/MoE attention options
+ */
+export interface PatternSearchWithAttention {
+  /** Base pattern search parameters */
+  task?: string;
+  taskEmbedding?: Float32Array;
+  k?: number;
+  threshold?: number;
+
+  /** Flash attention for large libraries */
+  useFlashAttention?: boolean;
+  blockSize?: number;
+
+  /** MoE routing to specialized experts */
+  useMoERouting?: boolean;
+  numExperts?: number;
+  expertTopK?: number;
+
+  /** Return routing decisions */
+  returnExpertRouting?: boolean;
+}
+
+/**
+ * Reasoning pattern with attention metadata
+ */
+export interface ReasoningPatternWithAttention {
+  /** Standard pattern fields */
+  id?: number;
+  taskType: string;
+  approach: string;
+  successRate: number;
+  uses?: number;
+  avgReward?: number;
+
+  /** Attention enhancements */
+  flashScore?: number;
+  expertId?: number;
+  expertScore?: number;
+  routingWeight?: number;
+}
+
+// ============================================================================
+// ExplainableRecall Enhancements
+// ============================================================================
+
+/**
+ * Explanation query with GraphRoPE options
+ */
+export interface ExplanationQueryWithAttention {
+  /** Base explanation parameters */
+  query: string;
+  maxDepth?: number;
+  minConfidence?: number;
+
+  /** GraphRoPE for hop-aware ranking */
+  useGraphRoPE?: boolean;
+  maxHops?: number;
+  hopDecayFactor?: number;
+
+  /** Return attention heatmap for visualization */
+  returnAttentionHeatmap?: boolean;
+}
+
+/**
+ * Explanation chain with graph attention metadata
+ */
+export interface ExplanationChainWithAttention {
+  /** Standard explanation fields */
+  nodes: Array<{
+    id: number;
+    type: string;
+    content: string;
+  }>;
+  edges: Array<{
+    from: number;
+    to: number;
+    mechanism: string;
+  }>;
+  confidence: number;
+
+  /** GraphRoPE enhancements */
+  hopDistances?: number[];
+  graphRoPEScores?: number[];
+  positionalBias?: number[];
+}
+
+// ============================================================================
+// Attention Visualization
+// ============================================================================
+
+/**
+ * Attention heatmap data for visualization
+ */
+export interface AttentionHeatmap {
+  /** Query identifier */
+  queryId: string;
+
+  /** Key identifiers */
+  keyIds: string[];
+
+  /** Attention weights matrix (queries × keys) */
+  weights: number[][];
+
+  /** Mechanism used */
+  mechanism: AttentionMechanism;
+
+  /** Timestamp */
+  timestamp: number;
+}
+
+/**
+ * Attention weight distribution stats
+ */
+export interface AttentionWeightStats {
+  /** Mean attention weight */
+  mean: number;
+
+  /** Standard deviation */
+  stdDev: number;
+
+  /** Entropy (measure of distribution uniformity) */
+  entropy: number;
+
+  /** Maximum weight */
+  max: number;
+
+  /** Minimum weight */
+  min: number;
+
+  /** Top-k indices */
+  topKIndices: number[];
+
+  /** Top-k weights */
+  topKWeights: number[];
+}
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Attention performance metrics (subset for memory controllers)
+ */
+export interface AttentionPerformanceMetrics {
+  /** Mechanism used */
+  mechanism: AttentionMechanism;
+
+  /** Latency in milliseconds */
+  latencyMs: number;
+
+  /** Memory used in bytes */
+  memoryUsed: number;
+
+  /** Number of keys processed */
+  numKeys: number;
+
+  /** Backend used */
+  backend: AttentionBackend;
+}
+
+/**
+ * Feature flag utility type for controllers
+ */
+export interface AttentionFeatureFlags {
+  hyperbolic: boolean;
+  flash: boolean;
+  graphrope: boolean;
+  moe: boolean;
+  dualspace: boolean;
+  linear: boolean;
+}
+
+// ============================================================================
+// Re-exports from AttentionService (for convenience)
+// ============================================================================
+
+// Note: These types are also defined in AttentionService.ts
+// Re-exported here for convenience so memory controllers don't need
+// to import from AttentionService directly
+
+export type {
+  AttentionConfig,
+  AttentionOptions,
+  AttentionResult,
+  AttentionMetrics,
+} from '../controllers/AttentionService.js';
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard for attention-enhanced causal edge
+ */
+export function isCausalEdgeWithAttention(
+  edge: any
+): edge is CausalEdgeWithAttention {
+  return (
+    typeof edge === 'object' &&
+    edge !== null &&
+    'fromMemoryId' in edge &&
+    'toMemoryId' in edge &&
+    ('hyperbolicScore' in edge || 'attentionWeight' in edge)
+  );
+}
+
+/**
+ * Type guard for attention-enhanced pattern
+ */
+export function isPatternWithAttention(
+  pattern: any
+): pattern is ReasoningPatternWithAttention {
+  return (
+    typeof pattern === 'object' &&
+    pattern !== null &&
+    'taskType' in pattern &&
+    ('flashScore' in pattern || 'expertId' in pattern)
+  );
+}
+
+/**
+ * Type guard for attention-enhanced explanation
+ */
+export function isExplanationWithAttention(
+  explanation: any
+): explanation is ExplanationChainWithAttention {
+  return (
+    typeof explanation === 'object' &&
+    explanation !== null &&
+    'nodes' in explanation &&
+    'edges' in explanation &&
+    ('hopDistances' in explanation || 'graphRoPEScores' in explanation)
+  );
+}