@agentic-qe/v3 3.0.0-alpha.6 → 3.0.0-alpha.7

package/src/kernel/agentdb-backend.ts

@@ -1,504 +0,0 @@
-/**
- * Agentic QE v3 - AgentDB Memory Backend
- * High-performance vector storage with HNSW indexing for O(log n) search
- */
-
-import { MemoryBackend, StoreOptions, VectorSearchResult } from './interfaces';
-
-// ============================================================================
-// AgentDB Types
-// ============================================================================
-
-/**
- * AgentDB connection configuration
- */
-export interface AgentDBConfig {
-  /** Database file path or connection string */
-  path: string;
-  /** HNSW index configuration */
-  hnsw: HNSWConfig;
-  /** Enable write-ahead logging for durability */
-  walEnabled: boolean;
-  /** Cache size in bytes */
-  cacheSize: number;
-}
-
-/**
- * HNSW (Hierarchical Navigable Small World) index configuration
- * Provides O(log n) approximate nearest neighbor search
- */
-export interface HNSWConfig {
-  /** Number of neighbors per node (default: 16) */
-  M: number;
-  /** Size of dynamic candidate list during construction (default: 200) */
-  efConstruction: number;
-  /** Size of dynamic candidate list during search (default: 100) */
-  efSearch: number;
-  /** Distance metric */
-  metric: 'cosine' | 'euclidean' | 'dot';
-  /** Vector dimensions */
-  dimensions: number;
-}
-
-/**
- * Connection state for AgentDB
- */
-type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
-
-// ============================================================================
-// AgentDB Client Implementation
-// ============================================================================
-
-/**
- * AgentDB client interface
- * Current implementation provides fully functional in-memory vector storage with:
- * - Key-value operations with TTL support
- * - Vector similarity search (cosine, euclidean, dot product)
- * - HNSW-compatible interface for future optimization
- *
- * Suitable for development, testing, and moderate-scale production.
- * For large-scale deployments (1M+ vectors), integrate with native HNSW library.
- */
-interface AgentDBClient {
-  connect(): Promise<void>;
-  disconnect(): Promise<void>;
-  isConnected(): boolean;
-
-  // Key-value operations
-  set(key: string, value: unknown, options?: { ttl?: number }): Promise<void>;
-  get<T>(key: string): Promise<T | undefined>;
-  delete(key: string): Promise<boolean>;
-  exists(key: string): Promise<boolean>;
-  keys(pattern: string, limit: number): Promise<string[]>;
-
-  // Vector operations with HNSW
-  insertVector(key: string, vector: number[], metadata?: unknown): Promise<void>;
-  searchVectors(query: number[], k: number, filter?: unknown): Promise<VectorMatch[]>;
-  deleteVector(key: string): Promise<boolean>;
-
-  // Index management
-  buildIndex(): Promise<void>;
-  indexStats(): Promise<IndexStats>;
-}
-
-interface VectorMatch {
-  key: string;
-  distance: number;
-  metadata?: unknown;
-}
-
-interface IndexStats {
-  vectorCount: number;
-  indexSize: number;
-  buildTime: number;
-  queryLatencyP50: number;
-  queryLatencyP99: number;
-}
-
-/**
- * Creates an in-memory AgentDB client
- *
- * This is a fully functional implementation providing:
- * - Key-value storage with TTL expiration
- * - Vector storage with configurable distance metrics
- * - Pattern-based key search
- * - Simulated HNSW performance characteristics
- *
- * For datasets > 100K vectors, consider integrating hnswlib-node
- * or usearch for true O(log n) performance.
- */
-function createInMemoryAgentDBClient(config: AgentDBConfig): AgentDBClient {
-  const store = new Map<string, { value: unknown; expiresAt?: number }>();
-  const vectors = new Map<string, { vector: number[]; metadata?: unknown }>();
-  let connected = false;
-
-  return {
-    async connect() {
-      // Simulate connection delay
-      await new Promise(resolve => setTimeout(resolve, 10));
-      connected = true;
-    },
-
-    async disconnect() {
-      connected = false;
-      store.clear();
-      vectors.clear();
-    },
-
-    isConnected() {
-      return connected;
-    },
-
-    async set(key, value, options) {
-      if (!connected) throw new Error('AgentDB not connected');
-      const entry: { value: unknown; expiresAt?: number } = { value };
-      if (options?.ttl) {
-        entry.expiresAt = Date.now() + options.ttl * 1000;
-      }
-      store.set(key, entry);
-    },
-
-    async get<T>(key: string): Promise<T | undefined> {
-      if (!connected) throw new Error('AgentDB not connected');
-      const entry = store.get(key);
-      if (!entry) return undefined;
-      if (entry.expiresAt && Date.now() > entry.expiresAt) {
-        store.delete(key);
-        return undefined;
-      }
-      return entry.value as T;
-    },
-
-    async delete(key) {
-      if (!connected) throw new Error('AgentDB not connected');
-      return store.delete(key);
-    },
-
-    async exists(key) {
-      if (!connected) throw new Error('AgentDB not connected');
-      const entry = store.get(key);
-      if (!entry) return false;
-      if (entry.expiresAt && Date.now() > entry.expiresAt) {
-        store.delete(key);
-        return false;
-      }
-      return true;
-    },
-
-    async keys(pattern, limit) {
-      if (!connected) throw new Error('AgentDB not connected');
-      const regex = new RegExp(pattern.replace(/\*/g, '.*'));
-      const results: string[] = [];
-      for (const key of store.keys()) {
-        if (regex.test(key)) {
-          results.push(key);
-          if (results.length >= limit) break;
-        }
-      }
-      return results;
-    },
-
-    async insertVector(key, vector, metadata) {
-      if (!connected) throw new Error('AgentDB not connected');
-      vectors.set(key, { vector, metadata });
-    },
-
-    async searchVectors(query, k) {
-      if (!connected) throw new Error('AgentDB not connected');
-
-      // Linear scan vector search - O(n) complexity
-      // For O(log n) performance with large datasets, integrate hnswlib-node
-      const results: VectorMatch[] = [];
-
-      for (const [key, entry] of vectors.entries()) {
-        const distance = cosineDistance(query, entry.vector, config.hnsw.metric);
-        results.push({ key, distance, metadata: entry.metadata });
-      }
-
-      // Sort by distance (lower is better) and take top k
-      return results
-        .sort((a, b) => a.distance - b.distance)
-        .slice(0, k);
-    },
-
-    async deleteVector(key) {
-      if (!connected) throw new Error('AgentDB not connected');
-      return vectors.delete(key);
-    },
-
-    async buildIndex() {
-      if (!connected) throw new Error('AgentDB not connected');
-      // In-memory implementation uses linear scan, no index building needed
-      // For HNSW optimization, implement index construction here
-    },
-
-    async indexStats() {
-      return {
-        vectorCount: vectors.size,
-        indexSize: vectors.size * 1024, // Approximate
-        buildTime: 0,
-        queryLatencyP50: 1,
-        queryLatencyP99: 5,
-      };
-    },
-  };
-}
-
-/**
- * Compute distance between vectors based on metric
- */
-function cosineDistance(a: number[], b: number[], metric: string): number {
-  if (a.length !== b.length) {
-    throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
-  }
-
-  if (metric === 'euclidean') {
-    let sum = 0;
-    for (let i = 0; i < a.length; i++) {
-      const diff = a[i] - b[i];
-      sum += diff * diff;
-    }
-    return Math.sqrt(sum);
-  }
-
-  if (metric === 'dot') {
-    let sum = 0;
-    for (let i = 0; i < a.length; i++) {
-      sum += a[i] * b[i];
-    }
-    // Convert dot product to distance (higher dot = lower distance)
-    return 1 - sum;
-  }
-
-  // Default: cosine distance
-  let dotProduct = 0;
-  let normA = 0;
-  let normB = 0;
-
-  for (let i = 0; i < a.length; i++) {
-    dotProduct += a[i] * b[i];
-    normA += a[i] * a[i];
-    normB += b[i] * b[i];
-  }
-
-  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
-  const similarity = denominator === 0 ? 0 : dotProduct / denominator;
-
-  // Convert similarity to distance (1 - similarity)
-  return 1 - similarity;
-}
-
-// ============================================================================
-// AgentDB Backend Implementation
-// ============================================================================
-
-/**
- * AgentDB Memory Backend
- *
- * Provides high-performance vector storage and retrieval using HNSW indexing.
- * Key features:
- * - O(log n) approximate nearest neighbor search
- * - 150x faster than linear scan for large datasets
- * - Persistent storage with WAL for durability
- * - Configurable distance metrics (cosine, euclidean, dot product)
- */
-export class AgentDBBackend implements MemoryBackend {
-  private client: AgentDBClient | null = null;
-  private config: AgentDBConfig;
-  private state: ConnectionState = 'disconnected';
-  private initPromise: Promise<void> | null = null;
-
-  constructor(config?: Partial<AgentDBConfig>) {
-    this.config = {
-      path: config?.path ?? '.agentic-qe/agentdb.db',
-      walEnabled: config?.walEnabled ?? true,
-      cacheSize: config?.cacheSize ?? 64 * 1024 * 1024, // 64MB default
-      hnsw: {
-        M: config?.hnsw?.M ?? 16,
-        efConstruction: config?.hnsw?.efConstruction ?? 200,
-        efSearch: config?.hnsw?.efSearch ?? 100,
-        metric: config?.hnsw?.metric ?? 'cosine',
-        dimensions: config?.hnsw?.dimensions ?? 384, // Default for common embeddings
-        ...config?.hnsw,
-      },
-    };
-  }
-
-  /**
-   * Initialize the AgentDB connection
-   */
-  async initialize(): Promise<void> {
-    if (this.initPromise) {
-      return this.initPromise;
-    }
-
-    this.initPromise = this.doInitialize();
-    return this.initPromise;
-  }
-
-  private async doInitialize(): Promise<void> {
-    if (this.state === 'connected') {
-      return;
-    }
-
-    this.state = 'connecting';
-
-    try {
-      // Create in-memory client
-      this.client = createInMemoryAgentDBClient(this.config);
-
-      // Connect to database
-      await this.client.connect();
-
-      // Build initial HNSW index if needed
-      await this.client.buildIndex();
-
-      this.state = 'connected';
-    } catch (error) {
-      this.state = 'error';
-      throw new Error(`Failed to initialize AgentDB: ${error}`);
-    }
-  }
-
-  /**
-   * Dispose of the AgentDB connection
-   */
-  async dispose(): Promise<void> {
-    if (this.client && this.state === 'connected') {
-      await this.client.disconnect();
-    }
-    this.client = null;
-    this.state = 'disconnected';
-    this.initPromise = null;
-  }
-
-  /**
-   * Store a value in AgentDB
-   */
-  async set<T>(key: string, value: T, options?: StoreOptions): Promise<void> {
-    this.ensureConnected();
-
-    const fullKey = this.buildKey(key, options?.namespace);
-    await this.client!.set(fullKey, value, { ttl: options?.ttl });
-  }
-
-  /**
-   * Retrieve a value from AgentDB
-   */
-  async get<T>(key: string): Promise<T | undefined> {
-    this.ensureConnected();
-    return this.client!.get<T>(key);
-  }
-
-  /**
-   * Delete a value from AgentDB
-   */
-  async delete(key: string): Promise<boolean> {
-    this.ensureConnected();
-
-    // Delete both key-value and vector entries
-    const kvDeleted = await this.client!.delete(key);
-    const vectorDeleted = await this.client!.deleteVector(key);
-
-    return kvDeleted || vectorDeleted;
-  }
-
-  /**
-   * Check if a key exists in AgentDB
-   */
-  async has(key: string): Promise<boolean> {
-    this.ensureConnected();
-    return this.client!.exists(key);
-  }
-
-  /**
-   * Search for keys matching a pattern
-   */
-  async search(pattern: string, limit: number = 100): Promise<string[]> {
-    this.ensureConnected();
-    return this.client!.keys(pattern, limit);
-  }
-
-  /**
-   * Perform vector similarity search using HNSW index
-   *
-   * Performance: O(log n) due to HNSW hierarchical graph traversal
-   * Compared to O(n) linear scan, this provides ~150x speedup for 1M vectors
-   *
-   * @param embedding - Query vector
-   * @param k - Number of nearest neighbors to return
-   * @returns Top k most similar vectors with scores
-   */
-  async vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]> {
-    this.ensureConnected();
-
-    // Validate embedding dimensions
-    if (embedding.length !== this.config.hnsw.dimensions) {
-      throw new Error(
-        `Embedding dimension mismatch: expected ${this.config.hnsw.dimensions}, got ${embedding.length}`
-      );
-    }
-
-    const matches = await this.client!.searchVectors(embedding, k);
-
-    // Convert distance to similarity score (1 - distance for cosine)
-    return matches.map(match => ({
-      key: match.key,
-      score: 1 - match.distance,
-      metadata: match.metadata,
-    }));
-  }
-
-  /**
-   * Store a vector embedding with HNSW indexing
-   *
-   * @param key - Unique identifier for the vector
-   * @param embedding - Vector to store
-   * @param metadata - Optional metadata to associate with the vector
-   */
-  async storeVector(
-    key: string,
-    embedding: number[],
-    metadata?: unknown
-  ): Promise<void> {
-    this.ensureConnected();
-
-    // Validate embedding dimensions
-    if (embedding.length !== this.config.hnsw.dimensions) {
-      throw new Error(
-        `Embedding dimension mismatch: expected ${this.config.hnsw.dimensions}, got ${embedding.length}`
-      );
-    }
-
-    await this.client!.insertVector(key, embedding, metadata);
-  }
-
-  // ============================================================================
-  // AgentDB-specific Methods
-  // ============================================================================
-
-  /**
-   * Get HNSW index statistics
-   */
-  async getIndexStats(): Promise<IndexStats> {
-    this.ensureConnected();
-    return this.client!.indexStats();
-  }
-
-  /**
-   * Rebuild the HNSW index
-   * Call after bulk insertions for optimal performance
-   */
-  async rebuildIndex(): Promise<void> {
-    this.ensureConnected();
-    await this.client!.buildIndex();
-  }
-
-  /**
-   * Get current connection state
-   */
-  getConnectionState(): ConnectionState {
-    return this.state;
-  }
-
-  /**
-   * Get backend configuration
-   */
-  getConfig(): Readonly<AgentDBConfig> {
-    return { ...this.config };
-  }
-
-  // ============================================================================
-  // Private Helpers
-  // ============================================================================
-
-  private ensureConnected(): void {
-    if (this.state !== 'connected' || !this.client) {
-      throw new Error('AgentDB backend not initialized. Call initialize() first.');
-    }
-  }
-
-  private buildKey(key: string, namespace?: string): string {
-    return namespace ? `${namespace}:${key}` : key;
-  }
-}

package/src/kernel/event-bus.ts

@@ -1,129 +0,0 @@
-/**
- * Agentic QE v3 - Event Bus Implementation
- * Domain event router for cross-domain communication
- */
-
-import {
-  DomainEvent,
-  DomainName,
-  EventHandler,
-} from '../shared/types';
-import { EventBus, Subscription, EventFilter } from './interfaces';
-
-interface SubscriptionEntry {
-  id: string;
-  eventType: string | '*';
-  channel?: DomainName;
-  handler: EventHandler;
-  active: boolean;
-}
-
-export class InMemoryEventBus implements EventBus {
-  private subscriptions: Map<string, SubscriptionEntry> = new Map();
-  private eventHistory: DomainEvent[] = [];
-  private maxHistorySize = 10000;
-  private subscriptionCounter = 0;
-
-  async publish<T>(event: DomainEvent<T>): Promise<void> {
-    // Store in history
-    this.eventHistory.push(event);
-    if (this.eventHistory.length > this.maxHistorySize) {
-      this.eventHistory.shift();
-    }
-
-    // Find matching subscriptions
-    const matchingSubscriptions = Array.from(this.subscriptions.values()).filter(
-      (sub) => {
-        if (!sub.active) return false;
-
-        // Check channel match
-        if (sub.channel && sub.channel !== event.source) return false;
-
-        // Check event type match
-        if (sub.eventType !== '*' && sub.eventType !== event.type) return false;
-
-        return true;
-      }
-    );
-
-    // Execute handlers concurrently
-    await Promise.allSettled(
-      matchingSubscriptions.map((sub) => sub.handler(event))
-    );
-  }
-
-  subscribe<T>(eventType: string, handler: EventHandler<T>): Subscription {
-    const id = `sub_${++this.subscriptionCounter}`;
-    const entry: SubscriptionEntry = {
-      id,
-      eventType,
-      handler: handler as EventHandler,
-      active: true,
-    };
-    this.subscriptions.set(id, entry);
-
-    return {
-      unsubscribe: () => {
-        entry.active = false;
-        this.subscriptions.delete(id);
-      },
-      get active() {
-        return entry.active;
-      },
-    };
-  }
-
-  subscribeToChannel(domain: DomainName, handler: EventHandler): Subscription {
-    const id = `sub_${++this.subscriptionCounter}`;
-    const entry: SubscriptionEntry = {
-      id,
-      eventType: '*',
-      channel: domain,
-      handler,
-      active: true,
-    };
-    this.subscriptions.set(id, entry);
-
-    return {
-      unsubscribe: () => {
-        entry.active = false;
-        this.subscriptions.delete(id);
-      },
-      get active() {
-        return entry.active;
-      },
-    };
-  }
-
-  async getHistory(filter?: EventFilter): Promise<DomainEvent[]> {
-    let events = [...this.eventHistory];
-
-    if (filter) {
-      if (filter.eventTypes?.length) {
-        events = events.filter((e) => filter.eventTypes!.includes(e.type));
-      }
-      if (filter.sources?.length) {
-        events = events.filter((e) => filter.sources!.includes(e.source));
-      }
-      if (filter.fromTimestamp) {
-        events = events.filter((e) => e.timestamp >= filter.fromTimestamp!);
-      }
-      if (filter.toTimestamp) {
-        events = events.filter((e) => e.timestamp <= filter.toTimestamp!);
-      }
-      if (filter.correlationId) {
-        events = events.filter((e) => e.correlationId === filter.correlationId);
-      }
-      if (filter.limit) {
-        events = events.slice(-filter.limit);
-      }
-    }
-
-    return events;
-  }
-
-  async dispose(): Promise<void> {
-    this.subscriptions.clear();
-    this.eventHistory = [];
-  }
-}