@agentic-qe/v3 3.0.0-alpha.3

package/src/kernel/memory-factory.ts

@@ -0,0 +1,293 @@
+/**
+ * Agentic QE v3 - Memory Backend Factory
+ * Creates appropriate memory backend based on configuration
+ */
+
+import { MemoryBackend } from './interfaces';
+import { InMemoryBackend } from './memory-backend';
+import { AgentDBBackend, AgentDBConfig } from './agentdb-backend';
+import { HybridMemoryBackend, HybridBackendConfig, SQLiteConfig } from './hybrid-backend';
+
+// ============================================================================
+// Factory Types
+// ============================================================================
+
+/**
+ * Supported memory backend types
+ */
+export type MemoryBackendType = 'memory' | 'sqlite' | 'agentdb' | 'hybrid';
+
+/**
+ * Memory backend configuration union
+ */
+export interface MemoryBackendConfig {
+  /** Backend type to create */
+  type: MemoryBackendType;
+
+  /** InMemory backend options (type: 'memory') */
+  memory?: {
+    cleanupInterval?: number;
+  };
+
+  /** SQLite backend options (type: 'sqlite') */
+  sqlite?: Partial<SQLiteConfig>;
+
+  /** AgentDB backend options (type: 'agentdb') */
+  agentdb?: Partial<AgentDBConfig>;
+
+  /** Hybrid backend options (type: 'hybrid') */
+  hybrid?: Partial<HybridBackendConfig>;
+}
+
+/**
+ * Result of backend creation
+ */
+export interface MemoryBackendResult {
+  backend: MemoryBackend;
+  type: MemoryBackendType;
+  initialized: boolean;
+}
+
+// ============================================================================
+// Factory Implementation
+// ============================================================================
+
+/**
+ * Create a memory backend based on configuration
+ *
+ * @param config - Backend configuration
+ * @param autoInitialize - Whether to automatically initialize the backend
+ * @returns The created and optionally initialized memory backend
+ *
+ * @example
+ * ```typescript
+ * // Simple in-memory backend
+ * const memory = await createMemoryBackend({ type: 'memory' });
+ *
+ * // AgentDB with HNSW for vector search
+ * const vectorMemory = await createMemoryBackend({
+ *   type: 'agentdb',
+ *   agentdb: {
+ *     path: './data/vectors.db',
+ *     hnsw: { dimensions: 384, metric: 'cosine' }
+ *   }
+ * });
+ *
+ * // Hybrid: SQLite + AgentDB with fallback
+ * const hybridMemory = await createMemoryBackend({
+ *   type: 'hybrid',
+ *   hybrid: {
+ *     enableFallback: true,
+ *     sqlite: { path: './data/memory.db' },
+ *     agentdb: { path: './data/vectors.db' }
+ *   }
+ * });
+ * ```
+ */
+export async function createMemoryBackend(
+  config: MemoryBackendConfig,
+  autoInitialize: boolean = true
+): Promise<MemoryBackendResult> {
+  let backend: MemoryBackend;
+
+  switch (config.type) {
+    case 'memory':
+      backend = new InMemoryBackend();
+      break;
+
+    case 'sqlite':
+      // SQLite-only mode uses hybrid backend with AgentDB disabled
+      backend = new HybridMemoryBackend({
+        sqlite: config.sqlite,
+        enableFallback: true,
+        // Don't initialize AgentDB for SQLite-only mode
+        agentdb: undefined,
+      });
+      break;
+
+    case 'agentdb':
+      backend = new AgentDBBackend(config.agentdb);
+      break;
+
+    case 'hybrid':
+      backend = new HybridMemoryBackend(config.hybrid);
+      break;
+
+    default:
+      throw new Error(`Unknown memory backend type: ${config.type}`);
+  }
+
+  if (autoInitialize) {
+    await backend.initialize();
+  }
+
+  return {
+    backend,
+    type: config.type,
+    initialized: autoInitialize,
+  };
+}
+
+/**
+ * Create the default memory backend based on environment
+ *
+ * Uses environment variables to determine backend type:
+ * - AQE_MEMORY_BACKEND: 'memory' | 'sqlite' | 'agentdb' | 'hybrid'
+ * - AQE_MEMORY_PATH: Path for persistent storage
+ * - AQE_VECTOR_DIMENSIONS: Vector embedding dimensions
+ *
+ * @param autoInitialize - Whether to automatically initialize
+ * @returns Configured memory backend
+ */
+export async function createDefaultMemoryBackend(
+  autoInitialize: boolean = true
+): Promise<MemoryBackendResult> {
+  const backendType = (process.env.AQE_MEMORY_BACKEND as MemoryBackendType) ?? 'memory';
+  const storagePath = process.env.AQE_MEMORY_PATH ?? '.agentic-qe';
+  const vectorDimensions = parseInt(process.env.AQE_VECTOR_DIMENSIONS ?? '384', 10);
+
+  const config: MemoryBackendConfig = {
+    type: backendType,
+    sqlite: {
+      path: `${storagePath}/memory.db`,
+      walMode: true,
+    },
+    agentdb: {
+      path: `${storagePath}/vectors.db`,
+      hnsw: {
+        dimensions: vectorDimensions,
+        metric: 'cosine',
+        M: 16,
+        efConstruction: 200,
+        efSearch: 100,
+      },
+    },
+    hybrid: {
+      enableFallback: true,
+      sqlite: {
+        path: `${storagePath}/memory.db`,
+      },
+      agentdb: {
+        path: `${storagePath}/vectors.db`,
+        hnsw: {
+          dimensions: vectorDimensions,
+          metric: 'cosine',
+          M: 16,
+          efConstruction: 200,
+          efSearch: 100,
+        },
+      },
+    },
+  };
+
+  return createMemoryBackend(config, autoInitialize);
+}
+
+// ============================================================================
+// Backend Selection Helpers
+// ============================================================================
+
+/**
+ * Determine the best backend type based on requirements
+ *
+ * @param requirements - Backend requirements
+ * @returns Recommended backend type
+ */
+export function selectBackendType(requirements: {
+  needsVectorSearch: boolean;
+  needsPersistence: boolean;
+  needsHighPerformance: boolean;
+  maxMemoryMB?: number;
+}): MemoryBackendType {
+  // High-performance vector search -> AgentDB with HNSW
+  if (requirements.needsVectorSearch && requirements.needsHighPerformance) {
+    return 'agentdb';
+  }
+
+  // Need both persistence and vectors -> Hybrid
+  if (requirements.needsPersistence && requirements.needsVectorSearch) {
+    return 'hybrid';
+  }
+
+  // Only persistence needed -> SQLite
+  if (requirements.needsPersistence) {
+    return 'sqlite';
+  }
+
+  // Memory constrained or ephemeral -> In-memory
+  return 'memory';
+}
+
+/**
+ * Get recommended configuration for a specific use case
+ */
+export function getRecommendedConfig(
+  useCase: 'testing' | 'development' | 'production' | 'ci'
+): MemoryBackendConfig {
+  switch (useCase) {
+    case 'testing':
+      // Fast, ephemeral storage for tests
+      return { type: 'memory' };
+
+    case 'development':
+      // Persistent with fallback for dev comfort
+      return {
+        type: 'hybrid',
+        hybrid: {
+          enableFallback: true,
+          cleanupInterval: 60000,
+        },
+      };
+
+    case 'production':
+      // Full hybrid with all features
+      return {
+        type: 'hybrid',
+        hybrid: {
+          enableFallback: false, // Fail fast in production
+          sqlite: {
+            walMode: true,
+            poolSize: 10,
+            busyTimeout: 10000,
+          },
+          agentdb: {
+            walEnabled: true,
+            cacheSize: 256 * 1024 * 1024, // 256MB
+            hnsw: {
+              M: 32, // Higher connectivity for better recall
+              efConstruction: 400,
+              efSearch: 200,
+              metric: 'cosine',
+              dimensions: 384,
+            },
+          },
+        },
+      };
+
+    case 'ci':
+      // SQLite only for CI reproducibility
+      return {
+        type: 'sqlite',
+        sqlite: {
+          path: ':memory:', // In-memory SQLite for CI
+          walMode: false,
+        },
+      };
+
+    default:
+      return { type: 'memory' };
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  InMemoryBackend,
+  AgentDBBackend,
+  HybridMemoryBackend,
+  type AgentDBConfig,
+  type HybridBackendConfig,
+  type SQLiteConfig,
+};

package/src/kernel/plugin-loader.ts

@@ -0,0 +1,179 @@
+/**
+ * Agentic QE v3 - Plugin Loader
+ * Dynamic domain plugin loading with lazy initialization
+ */
+
+import { DomainName } from '../shared/types';
+import { DomainPlugin, PluginLoader, EventBus, MemoryBackend } from './interfaces';
+
+type PluginFactory = (eventBus: EventBus, memory: MemoryBackend) => Promise<DomainPlugin>;
+
+export class DefaultPluginLoader implements PluginLoader {
+  private plugins: Map<DomainName, DomainPlugin> = new Map();
+  private factories: Map<DomainName, PluginFactory> = new Map();
+  private loading: Map<DomainName, Promise<DomainPlugin>> = new Map();
+
+  constructor(
+    private readonly eventBus: EventBus,
+    private readonly memory: MemoryBackend,
+    _lazyLoading: boolean = true // Reserved for future use
+  ) {}
+
+  /**
+   * Register a plugin factory for a domain
+   */
+  registerFactory(domain: DomainName, factory: PluginFactory): void {
+    this.factories.set(domain, factory);
+  }
+
+  async load(domain: DomainName): Promise<DomainPlugin> {
+    // Return if already loaded
+    const existing = this.plugins.get(domain);
+    if (existing) {
+      return existing;
+    }
+
+    // Check if currently loading (prevent duplicate loads)
+    const loadingPromise = this.loading.get(domain);
+    if (loadingPromise) {
+      return loadingPromise;
+    }
+
+    // Get factory
+    const factory = this.factories.get(domain);
+    if (!factory) {
+      throw new Error(`No factory registered for domain: ${domain}`);
+    }
+
+    // Start loading
+    const promise = this.loadPlugin(domain, factory);
+    this.loading.set(domain, promise);
+
+    try {
+      const plugin = await promise;
+      this.plugins.set(domain, plugin);
+      return plugin;
+    } finally {
+      this.loading.delete(domain);
+    }
+  }
+
+  private async loadPlugin(
+    _domain: DomainName, // Reserved for future logging/metrics
+    factory: PluginFactory
+  ): Promise<DomainPlugin> {
+    // Create plugin instance
+    const plugin = await factory(this.eventBus, this.memory);
+
+    // Load dependencies first
+    for (const dep of plugin.dependencies) {
+      if (!this.isLoaded(dep)) {
+        await this.load(dep);
+      }
+    }
+
+    // Initialize plugin
+    await plugin.initialize();
+
+    return plugin;
+  }
+
+  async unload(domain: DomainName): Promise<void> {
+    const plugin = this.plugins.get(domain);
+    if (!plugin) {
+      return;
+    }
+
+    // Check if other plugins depend on this one
+    for (const [name, p] of this.plugins.entries()) {
+      if (p.dependencies.includes(domain)) {
+        throw new Error(
+          `Cannot unload ${domain}: domain ${name} depends on it`
+        );
+      }
+    }
+
+    // Dispose plugin
+    await plugin.dispose();
+    this.plugins.delete(domain);
+  }
+
+  isLoaded(domain: DomainName): boolean {
+    return this.plugins.has(domain);
+  }
+
+  getLoaded(): DomainName[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  async loadAll(): Promise<void> {
+    const registeredDomains = Array.from(this.factories.keys());
+
+    // Sort by dependencies (topological sort)
+    const sorted = this.topologicalSort(registeredDomains);
+
+    // Load in order
+    for (const domain of sorted) {
+      await this.load(domain);
+    }
+  }
+
+  private topologicalSort(domains: DomainName[]): DomainName[] {
+    const result: DomainName[] = [];
+    const visited = new Set<DomainName>();
+    const visiting = new Set<DomainName>();
+
+    const visit = (domain: DomainName): void => {
+      if (visited.has(domain)) return;
+      if (visiting.has(domain)) {
+        throw new Error(`Circular dependency detected involving: ${domain}`);
+      }
+
+      visiting.add(domain);
+
+      // Get dependencies from factory if not loaded
+      const plugin = this.plugins.get(domain);
+      const deps = plugin?.dependencies ?? [];
+
+      for (const dep of deps) {
+        if (domains.includes(dep)) {
+          visit(dep);
+        }
+      }
+
+      visiting.delete(domain);
+      visited.add(domain);
+      result.push(domain);
+    };
+
+    for (const domain of domains) {
+      visit(domain);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get a loaded plugin
+   */
+  getPlugin(domain: DomainName): DomainPlugin | undefined {
+    return this.plugins.get(domain);
+  }
+
+  /**
+   * Dispose all plugins
+   */
+  async disposeAll(): Promise<void> {
+    // Unload in reverse dependency order
+    const loaded = [...this.getLoaded()].reverse();
+
+    for (const domain of loaded) {
+      try {
+        await this.unload(domain);
+      } catch {
+        // Force remove on error
+        this.plugins.delete(domain);
+      }
+    }
+  }
+}

package/src/learning/index.ts

@@ -0,0 +1,219 @@
+/**
+ * Agentic QE v3 - Learning Module
+ * ADR-021: QE ReasoningBank for Pattern Learning
+ *
+ * This module provides QE-specific pattern learning capabilities:
+ * - QEReasoningBank: Pattern storage and retrieval with HNSW indexing
+ * - QE Patterns: Domain-specific pattern types and validation
+ * - QE Guidance: Best practices and anti-pattern detection
+ * - QE Hooks: Event handlers for pattern capture
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createQEReasoningBank,
+ *   setupQEHooks,
+ *   QEDomain,
+ *   generateGuidanceContext,
+ * } from './learning';
+ *
+ * // Create and initialize
+ * const reasoningBank = createQEReasoningBank(memory);
+ * await reasoningBank.initialize();
+ *
+ * // Setup hooks
+ * const hooks = setupQEHooks(reasoningBank, eventBus);
+ *
+ * // Route a task
+ * const routing = await reasoningBank.routeTask({
+ *   task: 'Generate unit tests for UserService',
+ *   context: { language: 'typescript', framework: 'vitest' },
+ * });
+ *
+ * // Get guidance
+ * const guidance = generateGuidanceContext('test-generation', {
+ *   framework: 'vitest',
+ *   language: 'typescript',
+ * });
+ * ```
+ *
+ * @module learning
+ */
+
+// ============================================================================
+// QE ReasoningBank
+// ============================================================================
+
+export {
+  QEReasoningBank,
+  createQEReasoningBank,
+  DEFAULT_QE_REASONING_BANK_CONFIG,
+} from './qe-reasoning-bank.js';
+
+export type {
+  QEReasoningBankConfig,
+  QERoutingRequest,
+  QERoutingResult,
+  LearningOutcome,
+  IQEReasoningBank,
+  QEReasoningBankStats,
+} from './qe-reasoning-bank.js';
+
+// ============================================================================
+// QE Patterns
+// ============================================================================
+
+export {
+  // Domain patterns
+  QE_DOMAINS,
+  QE_DOMAIN_LIST,
+
+  // Pattern types
+  QE_PATTERN_TYPES,
+
+  // Utility functions
+  detectQEDomain,
+  detectQEDomains,
+  mapQEDomainToAQE,
+  calculateQualityScore,
+  shouldPromotePattern,
+  validateQEPattern,
+  applyPatternTemplate,
+  matchPatternContext,
+} from './qe-patterns.js';
+
+export type {
+  QEDomain,
+  QEPatternType,
+  QEPattern,
+  QEPatternContext,
+  QEPatternTemplate,
+  QETemplateVariable,
+  ProgrammingLanguage,
+  TestFramework,
+  ComplexityLevel,
+  CreateQEPatternOptions,
+  PatternMatchResult,
+} from './qe-patterns.js';
+
+// ============================================================================
+// QE Guidance
+// ============================================================================
+
+export {
+  // Guidance registry
+  QE_GUIDANCE_REGISTRY,
+
+  // Domain guidance templates
+  TEST_GENERATION_GUIDANCE,
+  COVERAGE_ANALYSIS_GUIDANCE,
+  MUTATION_TESTING_GUIDANCE,
+  API_TESTING_GUIDANCE,
+  SECURITY_TESTING_GUIDANCE,
+  VISUAL_TESTING_GUIDANCE,
+  ACCESSIBILITY_GUIDANCE,
+  PERFORMANCE_GUIDANCE,
+
+  // Guidance functions
+  getGuidance,
+  getFrameworkGuidance,
+  getLanguageGuidance,
+  getCombinedGuidance,
+  checkAntiPatterns,
+  generateGuidanceContext,
+} from './qe-guidance.js';
+
+export type {
+  QEGuidance,
+  AntiPattern,
+  GuidanceExample,
+} from './qe-guidance.js';
+
+// ============================================================================
+// Pattern Store
+// ============================================================================
+
+export {
+  PatternStore,
+  createPatternStore,
+  DEFAULT_PATTERN_STORE_CONFIG,
+} from './pattern-store.js';
+
+export type {
+  IPatternStore,
+  PatternStoreConfig,
+  PatternStoreStats,
+  PatternSearchOptions,
+  PatternSearchResult,
+} from './pattern-store.js';
+
+// ============================================================================
+// QE Hooks
+// ============================================================================
+
+export {
+  // Hook events
+  QE_HOOK_EVENTS,
+
+  // Hook handlers
+  createQEHookHandlers,
+
+  // Hook registry
+  QEHookRegistry,
+  createQEHookRegistry,
+  setupQEHooks,
+} from './qe-hooks.js';
+
+export type {
+  QEHookEvent,
+  QEHookContext,
+  QEHookResult,
+  QEHookHandler,
+} from './qe-hooks.js';
+
+// ============================================================================
+// REAL Implementation (ADR-021 Compliant)
+// ============================================================================
+
+export {
+  // Real QE ReasoningBank (extends agentic-flow HybridReasoningBank)
+  RealQEReasoningBank,
+  createRealQEReasoningBank,
+  DEFAULT_REAL_CONFIG,
+} from './real-qe-reasoning-bank.js';
+
+export type {
+  RealQEReasoningBankConfig,
+  RealQERoutingRequest,
+  RealQERoutingResult,
+  RealQEReasoningBankStats,
+  LearningOutcome as RealLearningOutcome,
+} from './real-qe-reasoning-bank.js';
+
+// Real Transformer Embeddings
+export {
+  computeRealEmbedding,
+  computeBatchEmbeddings,
+  cosineSimilarity,
+  clearEmbeddingCache,
+  getCacheStats,
+  isTransformerAvailable,
+  getEmbeddingDimension,
+  resetInitialization,
+  DEFAULT_EMBEDDING_CONFIG,
+} from './real-embeddings.js';
+
+export type {
+  EmbeddingConfig,
+} from './real-embeddings.js';
+
+// Real SQLite Persistence
+export {
+  SQLitePatternStore,
+  createSQLitePatternStore,
+  DEFAULT_SQLITE_CONFIG,
+} from './sqlite-persistence.js';
+
+export type {
+  SQLitePersistenceConfig,
+} from './sqlite-persistence.js';