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

package/src/kernel/hybrid-backend.ts

@@ -1,538 +0,0 @@
-/**
- * Agentic QE v3 - Hybrid Memory Backend
- * Combines SQLite (structured data) with AgentDB (vector search)
- */
-
-import { MemoryBackend, StoreOptions, VectorSearchResult } from './interfaces';
-import { AgentDBBackend, AgentDBConfig } from './agentdb-backend';
-import { InMemoryBackend } from './memory-backend';
-
-// ============================================================================
-// SQLite Types
-// ============================================================================
-
-/**
- * SQLite connection configuration
- */
-export interface SQLiteConfig {
-  /** Database file path */
-  path: string;
-  /** Enable WAL mode for better concurrency */
-  walMode: boolean;
-  /** Connection pool size */
-  poolSize: number;
-  /** Busy timeout in milliseconds */
-  busyTimeout: number;
-}
-
-/**
- * SQLite client interface
- * Current implementation uses in-memory storage which is suitable for:
- * - Development and testing
- * - Single-process deployments
- * - Ephemeral workloads
- *
- * For persistent storage, integrate better-sqlite3 or sql.js
- */
-interface SQLiteClient {
-  open(): Promise<void>;
-  close(): Promise<void>;
-  isOpen(): boolean;
-
-  // Key-value operations
-  set(key: string, value: string, namespace: string, ttl?: number): Promise<void>;
-  get(key: string, namespace: string): Promise<string | undefined>;
-  delete(key: string, namespace: string): Promise<boolean>;
-  exists(key: string, namespace: string): Promise<boolean>;
-  search(pattern: string, namespace: string, limit: number): Promise<string[]>;
-
-  // Cleanup
-  cleanupExpired(): Promise<number>;
-}
-
-/**
- * Creates an in-memory SQLite-compatible client
- *
- * This is a fully functional implementation that:
- * - Provides key-value storage with namespace isolation
- * - Supports TTL-based expiration
- * - Handles pattern-based key search
- * - Manages automatic cleanup of expired entries
- *
- * Suitable for development, testing, and single-process production use.
- * For multi-process or persistent storage, replace with better-sqlite3.
- */
-function createInMemorySQLiteClient(_config: SQLiteConfig): SQLiteClient {
-  const store = new Map<string, { value: string; namespace: string; expiresAt?: number }>();
-  let isOpen = false;
-
-  return {
-    async open() {
-      await new Promise(resolve => setTimeout(resolve, 5));
-      isOpen = true;
-    },
-
-    async close() {
-      isOpen = false;
-      store.clear();
-    },
-
-    isOpen() {
-      return isOpen;
-    },
-
-    async set(key, value, namespace, ttl) {
-      if (!isOpen) throw new Error('SQLite not open');
-      const fullKey = `${namespace}:${key}`;
-      store.set(fullKey, {
-        value,
-        namespace,
-        expiresAt: ttl ? Date.now() + ttl * 1000 : undefined,
-      });
-    },
-
-    async get(key, namespace) {
-      if (!isOpen) throw new Error('SQLite not open');
-      const fullKey = `${namespace}:${key}`;
-      const entry = store.get(fullKey);
-      if (!entry) return undefined;
-      if (entry.expiresAt && Date.now() > entry.expiresAt) {
-        store.delete(fullKey);
-        return undefined;
-      }
-      return entry.value;
-    },
-
-    async delete(key, namespace) {
-      if (!isOpen) throw new Error('SQLite not open');
-      const fullKey = `${namespace}:${key}`;
-      return store.delete(fullKey);
-    },
-
-    async exists(key, namespace) {
-      if (!isOpen) throw new Error('SQLite not open');
-      const fullKey = `${namespace}:${key}`;
-      const entry = store.get(fullKey);
-      if (!entry) return false;
-      if (entry.expiresAt && Date.now() > entry.expiresAt) {
-        store.delete(fullKey);
-        return false;
-      }
-      return true;
-    },
-
-    async search(pattern, namespace, limit) {
-      if (!isOpen) throw new Error('SQLite not open');
-      const regex = new RegExp(pattern.replace(/\*/g, '.*'));
-      const prefix = `${namespace}:`;
-      const results: string[] = [];
-
-      for (const fullKey of store.keys()) {
-        if (fullKey.startsWith(prefix)) {
-          const key = fullKey.slice(prefix.length);
-          if (regex.test(key)) {
-            results.push(key);
-            if (results.length >= limit) break;
-          }
-        }
-      }
-
-      return results;
-    },
-
-    async cleanupExpired() {
-      if (!isOpen) return 0;
-      const now = Date.now();
-      let cleaned = 0;
-
-      for (const [key, entry] of store.entries()) {
-        if (entry.expiresAt && now > entry.expiresAt) {
-          store.delete(key);
-          cleaned++;
-        }
-      }
-
-      return cleaned;
-    },
-  };
-}
-
-// ============================================================================
-// Hybrid Backend Configuration
-// ============================================================================
-
-/**
- * Hybrid backend configuration
- */
-export interface HybridBackendConfig {
-  /** SQLite configuration for structured data */
-  sqlite: Partial<SQLiteConfig>;
-  /** AgentDB configuration for vector operations */
-  agentdb: Partial<AgentDBConfig>;
-  /** Whether to fallback to in-memory if backends fail */
-  enableFallback: boolean;
-  /** Default namespace for operations */
-  defaultNamespace: string;
-  /** Cleanup interval in milliseconds */
-  cleanupInterval: number;
-}
-
-/**
- * Backend health status
- */
-interface BackendHealth {
-  sqlite: 'healthy' | 'degraded' | 'unavailable';
-  agentdb: 'healthy' | 'degraded' | 'unavailable';
-  fallback: 'active' | 'inactive';
-}
-
-// ============================================================================
-// Hybrid Backend Implementation
-// ============================================================================
-
-/**
- * Hybrid Memory Backend
- *
- * Combines SQLite for structured key-value storage with AgentDB for
- * high-performance vector operations. Provides automatic fallback to
- * in-memory storage if persistent backends are unavailable.
- *
- * Architecture:
- * - SQLite: Structured data, key patterns, namespace management
- * - AgentDB: Vector embeddings, HNSW indexing, similarity search
- * - InMemory: Fallback when persistent backends unavailable
- */
-export class HybridMemoryBackend implements MemoryBackend {
-  private sqliteClient: SQLiteClient | null = null;
-  private agentdbBackend: AgentDBBackend | null = null;
-  private fallbackBackend: InMemoryBackend | null = null;
-  private config: HybridBackendConfig;
-  private cleanupInterval?: ReturnType<typeof setInterval>;
-  private initialized = false;
-  private useFallback = false;
-
-  constructor(config?: Partial<HybridBackendConfig>) {
-    this.config = {
-      sqlite: {
-        path: config?.sqlite?.path ?? '.agentic-qe/memory.db',
-        walMode: config?.sqlite?.walMode ?? true,
-        poolSize: config?.sqlite?.poolSize ?? 5,
-        busyTimeout: config?.sqlite?.busyTimeout ?? 5000,
-        ...config?.sqlite,
-      },
-      agentdb: {
-        path: config?.agentdb?.path ?? '.agentic-qe/vectors.db',
-        ...config?.agentdb,
-      },
-      enableFallback: config?.enableFallback ?? true,
-      defaultNamespace: config?.defaultNamespace ?? 'default',
-      cleanupInterval: config?.cleanupInterval ?? 60000,
-    };
-  }
-
-  /**
-   * Initialize all backend connections
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) {
-      return;
-    }
-
-    const errors: string[] = [];
-
-    // Initialize SQLite (using in-memory implementation)
-    try {
-      this.sqliteClient = createInMemorySQLiteClient(this.config.sqlite as SQLiteConfig);
-      await this.sqliteClient.open();
-    } catch (error) {
-      errors.push(`SQLite initialization failed: ${error}`);
-      this.sqliteClient = null;
-    }
-
-    // Initialize AgentDB
-    try {
-      this.agentdbBackend = new AgentDBBackend(this.config.agentdb);
-      await this.agentdbBackend.initialize();
-    } catch (error) {
-      errors.push(`AgentDB initialization failed: ${error}`);
-      this.agentdbBackend = null;
-    }
-
-    // Check if we need fallback
-    if (errors.length > 0) {
-      if (this.config.enableFallback) {
-        console.warn(
-          `Hybrid backend degraded, using fallback: ${errors.join('; ')}`
-        );
-        this.fallbackBackend = new InMemoryBackend();
-        await this.fallbackBackend.initialize();
-        this.useFallback = true;
-      } else if (!this.sqliteClient && !this.agentdbBackend) {
-        throw new Error(`All backends failed: ${errors.join('; ')}`);
-      }
-    }
-
-    // Start cleanup interval
-    this.cleanupInterval = setInterval(
-      () => this.cleanup(),
-      this.config.cleanupInterval
-    );
-
-    this.initialized = true;
-  }
-
-  /**
-   * Dispose of all backend connections
-   */
-  async dispose(): Promise<void> {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-    }
-
-    const disposePromises: Promise<void>[] = [];
-
-    if (this.sqliteClient?.isOpen()) {
-      disposePromises.push(this.sqliteClient.close());
-    }
-
-    if (this.agentdbBackend) {
-      disposePromises.push(this.agentdbBackend.dispose());
-    }
-
-    if (this.fallbackBackend) {
-      disposePromises.push(this.fallbackBackend.dispose());
-    }
-
-    await Promise.all(disposePromises);
-
-    this.sqliteClient = null;
-    this.agentdbBackend = null;
-    this.fallbackBackend = null;
-    this.initialized = false;
-    this.useFallback = false;
-  }
-
-  /**
-   * Store a value - routes to SQLite or fallback
-   */
-  async set<T>(key: string, value: T, options?: StoreOptions): Promise<void> {
-    this.ensureInitialized();
-    const namespace = options?.namespace ?? this.config.defaultNamespace;
-
-    // Use fallback if SQLite unavailable
-    if (this.useFallback && this.fallbackBackend) {
-      return this.fallbackBackend.set(key, value, options);
-    }
-
-    if (this.sqliteClient) {
-      const serialized = JSON.stringify(value);
-      await this.sqliteClient.set(key, serialized, namespace, options?.ttl);
-    }
-  }
-
-  /**
-   * Retrieve a value - routes to SQLite or fallback
-   */
-  async get<T>(key: string): Promise<T | undefined> {
-    this.ensureInitialized();
-
-    // Use fallback if SQLite unavailable
-    if (this.useFallback && this.fallbackBackend) {
-      return this.fallbackBackend.get<T>(key);
-    }
-
-    if (this.sqliteClient) {
-      const value = await this.sqliteClient.get(key, this.config.defaultNamespace);
-      if (value) {
-        return JSON.parse(value) as T;
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Delete a value from all backends
-   */
-  async delete(key: string): Promise<boolean> {
-    this.ensureInitialized();
-
-    const results: boolean[] = [];
-
-    // Delete from SQLite
-    if (this.sqliteClient) {
-      results.push(
-        await this.sqliteClient.delete(key, this.config.defaultNamespace)
-      );
-    }
-
-    // Delete from AgentDB (in case it has vector data)
-    if (this.agentdbBackend) {
-      results.push(await this.agentdbBackend.delete(key));
-    }
-
-    // Delete from fallback
-    if (this.fallbackBackend) {
-      results.push(await this.fallbackBackend.delete(key));
-    }
-
-    return results.some(r => r);
-  }
-
-  /**
-   * Check if key exists
-   */
-  async has(key: string): Promise<boolean> {
-    this.ensureInitialized();
-
-    if (this.useFallback && this.fallbackBackend) {
-      return this.fallbackBackend.has(key);
-    }
-
-    if (this.sqliteClient) {
-      return this.sqliteClient.exists(key, this.config.defaultNamespace);
-    }
-
-    return false;
-  }
-
-  /**
-   * Search for keys matching pattern - uses SQLite
-   */
-  async search(pattern: string, limit: number = 100): Promise<string[]> {
-    this.ensureInitialized();
-
-    if (this.useFallback && this.fallbackBackend) {
-      return this.fallbackBackend.search(pattern, limit);
-    }
-
-    if (this.sqliteClient) {
-      return this.sqliteClient.search(pattern, this.config.defaultNamespace, limit);
-    }
-
-    return [];
-  }
-
-  /**
-   * Vector similarity search - routes to AgentDB or fallback
-   * Uses HNSW index for O(log n) performance
-   */
-  async vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]> {
-    this.ensureInitialized();
-
-    // Prefer AgentDB for vectors (HNSW indexing)
-    if (this.agentdbBackend) {
-      return this.agentdbBackend.vectorSearch(embedding, k);
-    }
-
-    // Fallback to in-memory linear search
-    if (this.fallbackBackend) {
-      return this.fallbackBackend.vectorSearch(embedding, k);
-    }
-
-    return [];
-  }
-
-  /**
-   * Store vector embedding - routes to AgentDB or fallback
-   */
-  async storeVector(
-    key: string,
-    embedding: number[],
-    metadata?: unknown
-  ): Promise<void> {
-    this.ensureInitialized();
-
-    // Prefer AgentDB for vectors
-    if (this.agentdbBackend) {
-      return this.agentdbBackend.storeVector(key, embedding, metadata);
-    }
-
-    // Fallback to in-memory
-    if (this.fallbackBackend) {
-      return this.fallbackBackend.storeVector(key, embedding, metadata);
-    }
-
-    throw new Error('No vector storage backend available');
-  }
-
-  // ============================================================================
-  // Hybrid-specific Methods
-  // ============================================================================
-
-  /**
-   * Get health status of all backends
-   */
-  getHealth(): BackendHealth {
-    return {
-      sqlite: this.sqliteClient?.isOpen() ? 'healthy' : 'unavailable',
-      agentdb: this.agentdbBackend?.getConnectionState() === 'connected'
-        ? 'healthy'
-        : 'unavailable',
-      fallback: this.useFallback ? 'active' : 'inactive',
-    };
-  }
-
-  /**
-   * Get configuration
-   */
-  getConfig(): Readonly<HybridBackendConfig> {
-    return { ...this.config };
-  }
-
-  /**
-   * Store with explicit backend selection
-   */
-  async setWithBackend<T>(
-    key: string,
-    value: T,
-    backend: 'sqlite' | 'memory',
-    options?: StoreOptions
-  ): Promise<void> {
-    this.ensureInitialized();
-    const namespace = options?.namespace ?? this.config.defaultNamespace;
-
-    if (backend === 'sqlite' && this.sqliteClient) {
-      const serialized = JSON.stringify(value);
-      await this.sqliteClient.set(key, serialized, namespace, options?.ttl);
-    } else if (this.fallbackBackend) {
-      await this.fallbackBackend.set(key, value, options);
-    } else {
-      throw new Error(`Backend ${backend} not available`);
-    }
-  }
-
-  /**
-   * Get AgentDB index statistics (if available)
-   */
-  async getVectorStats(): Promise<{ vectorCount: number; indexSize: number } | null> {
-    if (this.agentdbBackend) {
-      const stats = await this.agentdbBackend.getIndexStats();
-      return {
-        vectorCount: stats.vectorCount,
-        indexSize: stats.indexSize,
-      };
-    }
-    return null;
-  }
-
-  // ============================================================================
-  // Private Helpers
-  // ============================================================================
-
-  private ensureInitialized(): void {
-    if (!this.initialized) {
-      throw new Error('HybridMemoryBackend not initialized. Call initialize() first.');
-    }
-  }
-
-  private async cleanup(): Promise<void> {
-    if (this.sqliteClient?.isOpen()) {
-      try {
-        await this.sqliteClient.cleanupExpired();
-      } catch (error) {
-        console.warn('SQLite cleanup failed:', error);
-      }
-    }
-  }
-}

package/src/kernel/index.ts

@@ -1,28 +0,0 @@
-/**
- * Agentic QE v3 - Kernel Exports
- */
-
-// Interfaces
-export * from './interfaces';
-
-// Implementations
-export { InMemoryEventBus } from './event-bus';
-export { DefaultAgentCoordinator } from './agent-coordinator';
-export { DefaultPluginLoader } from './plugin-loader';
-export { InMemoryBackend } from './memory-backend';
-export { QEKernelImpl, createKernel } from './kernel';
-
-// Memory Backends
-export { AgentDBBackend } from './agentdb-backend';
-export type { AgentDBConfig, HNSWConfig } from './agentdb-backend';
-export { HybridMemoryBackend } from './hybrid-backend';
-export type { HybridBackendConfig, SQLiteConfig } from './hybrid-backend';
-
-// Memory Factory
-export {
-  createMemoryBackend,
-  createDefaultMemoryBackend,
-  selectBackendType,
-  getRecommendedConfig,
-} from './memory-factory';
-export type { MemoryBackendType, MemoryBackendConfig, MemoryBackendResult } from './memory-factory';