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

package/src/cli/commands/simulate-wizard.ts

@@ -0,0 +1,379 @@
+/**
+ * Interactive wizard for simulation configuration
+ * Uses inquirer.js for beautiful prompts
+ */
+
+import inquirer from 'inquirer';
+import { SimulationRunner } from '../lib/simulation-runner.js';
+import { ReportGenerator } from '../lib/report-generator.js';
+import { ConfigValidator, type SimulationConfig } from '../lib/config-validator.js';
+import chalk from 'chalk';
+
+export async function runWizard(): Promise<void> {
+  console.log(chalk.cyan.bold('\n🧙 AgentDB Simulation Wizard\n'));
+
+  // Step 1: Choose mode
+  const { mode } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'mode',
+      message: 'What would you like to do?',
+      choices: [
+        { name: '🎯 Run validated scenario (recommended)', value: 'scenario' },
+        { name: '🔧 Build custom simulation', value: 'custom' },
+        { name: '📊 View past reports', value: 'reports' },
+        { name: '❌ Exit', value: 'exit' },
+      ],
+    },
+  ]);
+
+  if (mode === 'exit') {
+    console.log(chalk.gray('\n👋 Goodbye!\n'));
+    return;
+  }
+
+  if (mode === 'reports') {
+    const { viewReport } = await import('./simulate-report.js');
+    await viewReport();
+    return;
+  }
+
+  if (mode === 'custom') {
+    await customWizard();
+    return;
+  }
+
+  await scenarioWizard();
+}
+
+async function scenarioWizard(): Promise<void> {
+  console.log(chalk.bold('\n📋 Scenario Selection\n'));
+
+  // Step 2: Select scenario
+  const { scenario } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'scenario',
+      message: 'Choose a simulation scenario:',
+      choices: [
+        {
+          name: '⚡ HNSW Exploration (8.2x speedup)',
+          value: 'hnsw',
+          short: 'HNSW',
+        },
+        {
+          name: '🧠 Attention Analysis (12.4% improvement)',
+          value: 'attention',
+          short: 'Attention',
+        },
+        {
+          name: '🎯 Traversal Optimization (96.8% recall)',
+          value: 'traversal',
+          short: 'Traversal',
+        },
+        {
+          name: '🔄 Self-Organizing (97.9% uptime)',
+          value: 'self-organizing',
+          short: 'Self-Organizing',
+        },
+        {
+          name: '🚀 Neural Augmentation (29.4% improvement)',
+          value: 'neural',
+          short: 'Neural',
+        },
+        {
+          name: '🔗 Hypergraph Exploration (3.7x compression)',
+          value: 'hypergraph',
+          short: 'Hypergraph',
+        },
+        {
+          name: '📊 Clustering Analysis (Q=0.758)',
+          value: 'clustering',
+          short: 'Clustering',
+        },
+        {
+          name: '🔮 Quantum-Hybrid (Theoretical)',
+          value: 'quantum',
+          short: 'Quantum',
+        },
+      ],
+    },
+  ]);
+
+  // Step 3: Configuration
+  const config = await inquirer.prompt([
+    {
+      type: 'number',
+      name: 'nodes',
+      message: 'Number of nodes:',
+      default: 100000,
+      validate: (value: number) => {
+        if (value < 1000 || value > 10000000) {
+          return 'Node count must be between 1,000 and 10,000,000';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'number',
+      name: 'dimensions',
+      message: 'Vector dimensions:',
+      default: 384,
+      validate: (value: number) => {
+        if (value < 64 || value > 2048) {
+          return 'Dimensions must be between 64 and 2048';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'number',
+      name: 'iterations',
+      message: 'Number of runs (for coherence analysis):',
+      default: 3,
+      validate: (value: number) => {
+        if (value < 1 || value > 100) {
+          return 'Iterations must be between 1 and 100';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'confirm',
+      name: 'useOptimal',
+      message: 'Use optimal validated configuration?',
+      default: true,
+    },
+    {
+      type: 'list',
+      name: 'format',
+      message: 'Report format:',
+      choices: [
+        { name: 'Markdown (readable)', value: 'md' },
+        { name: 'JSON (data)', value: 'json' },
+        { name: 'HTML (web)', value: 'html' },
+      ],
+      default: 'md',
+    },
+  ]);
+
+  // Merge with optimal config if requested
+  const finalConfig: SimulationConfig = config.useOptimal
+    ? { ...ConfigValidator.getOptimalConfig(scenario), ...config }
+    : { ...config };
+
+  // Step 4: Confirmation
+  console.log(chalk.bold('\n📋 Simulation Configuration:'));
+  console.log(`   Scenario: ${chalk.cyan(scenario)}`);
+  console.log(`   Nodes: ${chalk.cyan(finalConfig.nodes?.toLocaleString())}`);
+  console.log(`   Dimensions: ${chalk.cyan(finalConfig.dimensions)}`);
+  console.log(`   Iterations: ${chalk.cyan(finalConfig.iterations)}`);
+  console.log(`   Format: ${chalk.cyan(config.format)}`);
+  if (config.useOptimal) {
+    console.log(chalk.green('   ✅ Using optimal validated parameters'));
+  }
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Start simulation?',
+      default: true,
+    },
+  ]);
+
+  if (!confirm) {
+    console.log(chalk.yellow('\n❌ Simulation cancelled\n'));
+    return;
+  }
+
+  // Run simulation
+  try {
+    const runner = new SimulationRunner();
+    const report = await runner.runScenario(scenario, finalConfig, finalConfig.iterations || 3);
+
+    // Generate and save report
+    const generator = new ReportGenerator();
+    const outputPath = './reports';
+    const savedPath = await generator.saveReport(report, outputPath, config.format);
+
+    console.log(chalk.green(`\n✅ Report saved to: ${savedPath}\n`));
+
+    // Show summary
+    console.log(chalk.bold('Summary:'));
+    console.log(`  Success Rate: ${(report.summary.successRate * 100).toFixed(1)}%`);
+    console.log(`  Coherence: ${(report.coherenceScore * 100).toFixed(1)}%`);
+    console.log(`  Avg Latency: ${report.summary.avgLatencyUs.toFixed(2)}μs`);
+    console.log(`  Avg Recall@10: ${(report.summary.avgRecall * 100).toFixed(1)}%`);
+    console.log('');
+  } catch (error: any) {
+    console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
+    throw error;
+  }
+}
+
+async function customWizard(): Promise<void> {
+  console.log(chalk.bold('\n🔧 Custom Simulation Builder\n'));
+
+  const components = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'backend',
+      message: '1/6 Choose vector backend:',
+      choices: [
+        { name: '🚀 RuVector (8.2x speedup) [OPTIMAL]', value: 'ruvector' },
+        { name: '📦 hnswlib (baseline)', value: 'hnswlib' },
+        { name: '🔬 FAISS', value: 'faiss' },
+      ],
+      default: 'ruvector',
+    },
+    {
+      type: 'list',
+      name: 'attentionHeads',
+      message: '2/6 Attention mechanism:',
+      choices: [
+        { name: '🧠 8-head attention (+12.4%) [OPTIMAL]', value: 8 },
+        { name: '4-head attention', value: 4 },
+        { name: '16-head attention', value: 16 },
+        { name: 'No attention', value: 0 },
+      ],
+      default: 8,
+    },
+    {
+      type: 'list',
+      name: 'searchStrategy',
+      message: '3/6 Search strategy:',
+      choices: [
+        { name: '🎯 Beam-5 + Dynamic-k (96.8% recall) [OPTIMAL]', value: 'beam-dynamic' },
+        { name: 'Greedy (baseline)', value: 'greedy' },
+        { name: 'A* search', value: 'astar' },
+        { name: 'Dynamic-k only', value: 'dynamic-k' },
+      ],
+      default: 'beam-dynamic',
+    },
+    {
+      type: 'list',
+      name: 'clustering',
+      message: '4/6 Clustering algorithm:',
+      choices: [
+        { name: '🎯 Louvain (Q=0.758) [OPTIMAL]', value: 'louvain' },
+        { name: 'Spectral', value: 'spectral' },
+        { name: 'Hierarchical', value: 'hierarchical' },
+        { name: 'None', value: 'none' },
+      ],
+      default: 'louvain',
+    },
+    {
+      type: 'list',
+      name: 'selfHealing',
+      message: '5/6 Self-healing mode:',
+      choices: [
+        { name: '🛡️ MPC (97.9% uptime) [OPTIMAL]', value: 'mpc' },
+        { name: 'Reactive', value: 'reactive' },
+        { name: 'None', value: 'none' },
+      ],
+      default: 'mpc',
+    },
+    {
+      type: 'checkbox',
+      name: 'neuralFeatures',
+      message: '6/6 Neural augmentation features:',
+      choices: [
+        { name: 'GNN edge selection (-18% memory)', value: 'gnn-edges', checked: true },
+        { name: 'RL navigation (-26% hops)', value: 'rl-nav', checked: true },
+        { name: 'Joint optimization (+9.1%)', value: 'joint-opt', checked: true },
+        { name: 'Full neural pipeline (+29.4%)', value: 'full-pipeline', checked: true },
+      ],
+    },
+  ]);
+
+  // Additional configuration
+  const additionalConfig = await inquirer.prompt([
+    {
+      type: 'number',
+      name: 'nodes',
+      message: 'Number of nodes:',
+      default: 100000,
+    },
+    {
+      type: 'number',
+      name: 'dimensions',
+      message: 'Vector dimensions:',
+      default: 384,
+    },
+    {
+      type: 'number',
+      name: 'iterations',
+      message: 'Number of iterations:',
+      default: 3,
+    },
+    {
+      type: 'list',
+      name: 'format',
+      message: 'Report format:',
+      choices: [
+        { name: 'Markdown', value: 'md' },
+        { name: 'JSON', value: 'json' },
+        { name: 'HTML', value: 'html' },
+      ],
+      default: 'md',
+    },
+  ]);
+
+  const finalConfig: SimulationConfig = { ...components, ...additionalConfig };
+
+  // Validate configuration
+  const validation = ConfigValidator.validate(finalConfig);
+  if (!validation.valid) {
+    console.log(chalk.red('\n❌ Invalid configuration:'));
+    validation.errors.forEach((err) => console.log(`   - ${err}`));
+    console.log('');
+    return;
+  }
+
+  if (validation.warnings.length > 0) {
+    console.log(chalk.yellow('\n⚠️  Configuration warnings:'));
+    validation.warnings.forEach((warn) => console.log(`   - ${warn}`));
+    console.log('');
+  }
+
+  // Show configuration
+  console.log(chalk.bold('\n📋 Custom Simulation Configuration:'));
+  console.log(`   Backend: ${chalk.cyan(finalConfig.backend)}`);
+  console.log(`   Attention: ${chalk.cyan(finalConfig.attentionHeads)}-head`);
+  console.log(`   Search: ${chalk.cyan(finalConfig.searchStrategy)}`);
+  console.log(`   Clustering: ${chalk.cyan(finalConfig.clustering)}`);
+  console.log(`   Self-healing: ${chalk.cyan(finalConfig.selfHealing)}`);
+  console.log(`   Neural features: ${chalk.cyan(finalConfig.neuralFeatures?.length || 0)} enabled`);
+  console.log('');
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Run custom simulation?',
+      default: true,
+    },
+  ]);
+
+  if (!confirm) {
+    console.log(chalk.yellow('\n❌ Simulation cancelled\n'));
+    return;
+  }
+
+  // Run simulation with custom scenario
+  try {
+    const runner = new SimulationRunner();
+    const report = await runner.runScenario('custom', finalConfig, finalConfig.iterations);
+
+    // Generate and save report
+    const generator = new ReportGenerator();
+    const outputPath = './reports';
+    const savedPath = await generator.saveReport(report, outputPath, additionalConfig.format);
+
+    console.log(chalk.green(`\n✅ Report saved to: ${savedPath}\n`));
+  } catch (error: any) {
+    console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
+    throw error;
+  }
+}

package/src/cli/commands/simulate.ts

@@ -0,0 +1,115 @@
+/**
+ * Main simulate command
+ * Entry point for AgentDB latent space simulations
+ */
+
+import { Command } from 'commander';
+import { HelpFormatter } from '../lib/help-formatter.js';
+import { SimulationRunner } from '../lib/simulation-runner.js';
+import { ReportGenerator } from '../lib/report-generator.js';
+import chalk from 'chalk';
+
+export const simulateCommand = new Command('simulate')
+  .description('Run AgentDB latent space simulations')
+  .argument('[scenario]', 'Simulation scenario to run (hnsw, attention, clustering, traversal, hypergraph, self-organizing, neural, quantum)')
+  .option('--iterations <n>', 'Number of runs (default: 3)', '3')
+  .option('--output <path>', 'Report output path (default: ./reports)')
+  .option('--format <type>', 'Report format: md, json, html (default: md)', 'md')
+  .option('--verbose', 'Detailed output')
+  .option('--wizard', 'Interactive wizard mode')
+  .option('--custom', 'Custom simulation builder')
+  .option('--list', 'List all scenarios')
+  .option('--report <id>', 'View simulation report by ID')
+  .action(async (scenario, options) => {
+    try {
+      // Handle special modes
+      if (options.list) {
+        console.log(HelpFormatter.formatList());
+        return;
+      }
+
+      if (options.wizard) {
+        const { runWizard } = await import('./simulate-wizard.js');
+        await runWizard();
+        return;
+      }
+
+      if (options.custom) {
+        const { runCustomBuilder } = await import('./simulate-custom.js');
+        await runCustomBuilder();
+        return;
+      }
+
+      if (options.report) {
+        const { viewReport } = await import('./simulate-report.js');
+        await viewReport(options.report);
+        return;
+      }
+
+      // Validate scenario
+      const validScenarios = ['hnsw', 'attention', 'clustering', 'traversal', 'hypergraph', 'self-organizing', 'neural', 'quantum'];
+
+      if (!scenario) {
+        console.log(HelpFormatter.formatTopLevel());
+        return;
+      }
+
+      if (!validScenarios.includes(scenario)) {
+        console.log(chalk.red(`\n❌ Unknown scenario: ${scenario}\n`));
+        console.log(HelpFormatter.formatList());
+        process.exit(1);
+      }
+
+      // Parse iterations
+      const iterations = parseInt(options.iterations, 10);
+      if (isNaN(iterations) || iterations < 1 || iterations > 100) {
+        console.log(chalk.red('\n❌ Iterations must be between 1 and 100\n'));
+        process.exit(1);
+      }
+
+      // Validate format
+      const validFormats = ['md', 'json', 'html'];
+      if (!validFormats.includes(options.format)) {
+        console.log(chalk.red(`\n❌ Invalid format: ${options.format}. Must be one of: ${validFormats.join(', ')}\n`));
+        process.exit(1);
+      }
+
+      // Run simulation
+      console.log(chalk.cyan.bold('\n╔══════════════════════════════════════════════════════════════╗'));
+      console.log(chalk.cyan.bold('║  AgentDB Latent Space Simulation                           ║'));
+      console.log(chalk.cyan.bold('╚══════════════════════════════════════════════════════════════╝\n'));
+
+      const runner = new SimulationRunner();
+      const config = {
+        useOptimal: true, // Default to optimal configuration
+      };
+
+      const report = await runner.runScenario(scenario, config, iterations);
+
+      // Generate and save report
+      const generator = new ReportGenerator();
+      const outputPath = options.output || './reports';
+      const savedPath = await generator.saveReport(report, outputPath, options.format);
+
+      console.log(chalk.green(`\n✅ Report saved to: ${savedPath}\n`));
+
+      // Show summary
+      console.log(chalk.bold('Summary:'));
+      console.log(`  Success Rate: ${(report.summary.successRate * 100).toFixed(1)}%`);
+      console.log(`  Coherence: ${(report.coherenceScore * 100).toFixed(1)}%`);
+      console.log(`  Avg Latency: ${report.summary.avgLatencyUs.toFixed(2)}μs`);
+      console.log(`  Avg Recall@10: ${(report.summary.avgRecall * 100).toFixed(1)}%`);
+      console.log('');
+    } catch (error: any) {
+      console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
+      if (options.verbose && error.stack) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  });
+
+// Add custom help
+simulateCommand.on('--help', () => {
+  console.log(HelpFormatter.formatTopLevel());
+});

package/src/cli/commands/status.ts

@@ -0,0 +1,156 @@
+/**
+ * AgentDB Status Command - Show database and backend status
+ */
+
+import { createDatabase } from '../../db-fallback.js';
+import { detectBackend } from '../../backends/detector.js';
+import * as fs from 'fs';
+
+// Color codes
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m'
+};
+
+interface StatusOptions {
+  dbPath?: string;
+  verbose?: boolean;
+}
+
+export async function statusCommand(options: StatusOptions = {}): Promise<void> {
+  const { dbPath = './agentdb.db', verbose = false } = options;
+
+  try {
+    console.log(`\n${colors.bright}${colors.cyan}📊 AgentDB Status${colors.reset}\n`);
+
+    // Check database existence
+    const dbExists = fs.existsSync(dbPath);
+    console.log(`${colors.bright}Database:${colors.reset}`);
+    console.log(`  Path:          ${colors.blue}${dbPath}${colors.reset}`);
+    console.log(`  Status:        ${dbExists ? colors.green + '✅ Exists' : colors.red + '❌ Not found'}${colors.reset}`);
+
+    if (!dbExists) {
+      console.log(`\n${colors.yellow}💡 Run ${colors.cyan}agentdb init${colors.yellow} to create database${colors.reset}\n`);
+      return;
+    }
+
+    // Get file size
+    const stats = fs.statSync(dbPath);
+    const sizeInMB = (stats.size / (1024 * 1024)).toFixed(2);
+    console.log(`  Size:          ${colors.blue}${sizeInMB} MB${colors.reset}`);
+    console.log('');
+
+    // Open database and get configuration
+    const db = await createDatabase(dbPath);
+
+    try {
+      // Get backend configuration
+      const configQuery = db.prepare('SELECT key, value FROM agentdb_config');
+      const configs = configQuery.all() as Array<{ key: string; value: string }>;
+      const configMap = new Map(configs.map(c => [c.key, c.value]));
+
+      const backend = configMap.get('backend') as 'ruvector' | 'hnswlib' | undefined;
+      const dimension = configMap.get('dimension');
+      const version = configMap.get('version');
+
+      console.log(`${colors.bright}Configuration:${colors.reset}`);
+      console.log(`  Version:       ${colors.blue}${version || 'N/A'}${colors.reset}`);
+      console.log(`  Backend:       ${backend ? getBackendColor(backend) + backend : colors.yellow + 'Not configured'}${colors.reset}`);
+      console.log(`  Dimension:     ${colors.blue}${dimension || 'N/A'}${colors.reset}`);
+      console.log('');
+
+      // Get table statistics
+      const tables = [
+        { name: 'reflexion_episodes', label: 'Episodes' },
+        { name: 'skill_library', label: 'Skills' },
+        { name: 'causal_nodes', label: 'Causal Nodes' },
+        { name: 'causal_edges', label: 'Causal Edges' },
+        { name: 'reasoning_patterns', label: 'Patterns' }
+      ];
+
+      console.log(`${colors.bright}Data Statistics:${colors.reset}`);
+
+      let totalRecords = 0;
+      for (const table of tables) {
+        try {
+          const result = db.prepare(`SELECT COUNT(*) as count FROM ${table.name}`).get() as { count: number };
+          const count = result.count;
+          totalRecords += count;
+
+          if (verbose || count > 0) {
+            console.log(`  ${table.label.padEnd(20)} ${colors.blue}${count.toLocaleString()}${colors.reset}`);
+          }
+        } catch {
+          // Table doesn't exist
+          if (verbose) {
+            console.log(`  ${table.label.padEnd(20)} ${colors.yellow}N/A${colors.reset}`);
+          }
+        }
+      }
+
+      console.log(`  ${colors.bright}Total Records${colors.reset}      ${colors.blue}${totalRecords.toLocaleString()}${colors.reset}`);
+      console.log('');
+
+      // Detect available backends
+      const detection = await detectBackend();
+
+      console.log(`${colors.bright}Available Backends:${colors.reset}`);
+      console.log(`  Detected:      ${getBackendColor(detection.backend)}${detection.backend}${colors.reset}`);
+      console.log(`  Native:        ${detection.native ? colors.green + '✅ Yes' : colors.yellow + '⚠️  WASM'}${colors.reset}`);
+      console.log(`  Platform:      ${colors.blue}${detection.platform.combined}${colors.reset}`);
+      console.log('');
+
+      console.log(`${colors.bright}Features:${colors.reset}`);
+      console.log(`  GNN:           ${detection.features.gnn ? colors.green + '✅ Available' : colors.yellow + '⚠️  Not available'}${colors.reset}`);
+      console.log(`  Graph:         ${detection.features.graph ? colors.green + '✅ Available' : colors.yellow + '⚠️  Not available'}${colors.reset}`);
+      console.log(`  Compression:   ${detection.features.compression ? colors.green + '✅ Available' : colors.yellow + '⚠️  Not available'}${colors.reset}`);
+      console.log('');
+
+      // Performance info
+      if (backend === 'ruvector' && detection.backend === 'ruvector') {
+        console.log(`${colors.bright}${colors.green}⚡ Performance:${colors.reset}`);
+        console.log(`  Search speed:  ${colors.green}150x faster${colors.reset} than pure SQLite`);
+        console.log(`  Vector ops:    ${colors.green}Sub-millisecond${colors.reset} latency`);
+        if (detection.features.gnn) {
+          console.log(`  Self-learning: ${colors.green}✅ Enabled${colors.reset}`);
+        }
+        console.log('');
+      }
+
+      // Memory stats (verbose mode)
+      if (verbose) {
+        const memoryStats = db.prepare("PRAGMA page_count").get() as { page_count?: number };
+        const pageSize = db.prepare("PRAGMA page_size").get() as { page_size?: number };
+
+        if (memoryStats.page_count && pageSize.page_size) {
+          const memoryInMB = ((memoryStats.page_count * pageSize.page_size) / (1024 * 1024)).toFixed(2);
+          console.log(`${colors.bright}Memory:${colors.reset}`);
+          console.log(`  Pages:         ${colors.blue}${memoryStats.page_count.toLocaleString()}${colors.reset}`);
+          console.log(`  Page Size:     ${colors.blue}${pageSize.page_size} bytes${colors.reset}`);
+          console.log(`  Total:         ${colors.blue}${memoryInMB} MB${colors.reset}`);
+          console.log('');
+        }
+      }
+
+    } finally {
+      db.close();
+    }
+
+    console.log(`${colors.green}✅ Status check complete${colors.reset}\n`);
+
+  } catch (error) {
+    console.error(`${colors.red}❌ Status check failed:${colors.reset}`);
+    console.error(`   ${(error as Error).message}`);
+    process.exit(1);
+  }
+}
+
+function getBackendColor(backend: 'ruvector' | 'hnswlib'): string {
+  return backend === 'ruvector' ? colors.green : colors.yellow;
+}