agentdb 1.0.11 → 1.1.0

package/bin/agentdb.js

@@ -1,733 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * AgentDB CLI
- *
- * Command-line interface for agentdb operations
- */
-
-const { version } = require('../package.json');
-
-const COMMANDS = {
-  help: showHelp,
-  version: showVersion,
-  mcp: startMcpServer,
-  init: initDatabase,
-  benchmark: runBenchmark,
-  repl: startRepl,
-  'create-plugin': createPlugin,
-  'list-plugins': listPlugins,
-  'list-templates': listTemplates,
-  'plugin-info': pluginInfo,
-  'use-plugin': usePlugin,
-  import: importCommand,
-  export: exportCommand,
-  query: queryCommand,
-  stats: statsCommand,
-};
-
-function showHelp(subcommand) {
-  // Show command-specific help if requested
-  if (subcommand && COMMANDS[subcommand]) {
-    showCommandHelp(subcommand);
-    return;
-  }
-
-  console.log(`
-█▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █▀▄ █▄▄
-█▀█ █▄█ ██▄ █░▀█ ░█░ █▄▀ █▄█
-
-AgentDB v${version} - Agent Memory & Vector Database
-Website: https://agentdb.ruv.io
-
-USAGE
-  npx agentdb <command> [options]
-  npx agentdb <command> --help    (detailed command help)
-
-CORE COMMANDS
-  init <path>       Initialize vector database
-  mcp               Start MCP server for Claude Code
-  benchmark         Run performance benchmarks
-  version           Show version information
-
-PLUGIN COMMANDS
-  create-plugin     Create learning plugin (interactive wizard)
-  list-plugins      List available plugins
-  list-templates    List plugin templates
-  plugin-info       Show plugin details
-
-DATABASE COMMANDS
-  import <file>     Import vectors from file
-  export <file>     Export vectors to file
-  query <db>        Query vector database
-  stats <db>        Show database statistics
-
-QUICK START
-  npx agentdb create-plugin              # Create plugin
-  npx agentdb init ./agents.db           # Initialize DB
-  npx agentdb mcp                        # Start MCP server
-  npx agentdb benchmark                  # Run benchmarks
-
-HELP & INFO
-  npx agentdb help <command>             # Command-specific help
-  npx agentdb <command> --help           # Alternative syntax
-  npx agentdb version                    # Version info
-
-DOCUMENTATION
-  GitHub:  https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
-  Issues:  https://github.com/ruvnet/agentic-flow/issues
-  License: MIT OR Apache-2.0
-`);
-}
-
-function showCommandHelp(command) {
-  const helps = {
-    init: `
-COMMAND: init
-
-Initialize a new vector database
-
-USAGE
-  npx agentdb init <path> [options]
-
-ARGUMENTS
-  <path>            Database file path (e.g., ./vectors.db)
-
-OPTIONS
-  --dimension <n>   Vector dimension (default: 1536)
-  --preset <name>   Use preset: small, medium, large
-  --in-memory       Create in-memory database
-
-EXAMPLES
-  npx agentdb init ./vectors.db
-  npx agentdb init ./vectors.db --dimension 768
-  npx agentdb init ./vectors.db --preset large
-`,
-    mcp: `
-COMMAND: mcp
-
-Start Model Context Protocol server for Claude Code integration
-
-USAGE
-  npx agentdb mcp [options]
-
-OPTIONS
-  --port <number>   Port to listen on (default: 3000)
-  --host <string>   Host to bind to (default: localhost)
-  --log <level>     Log level: debug, info, warn, error
-
-EXAMPLES
-  npx agentdb mcp
-  npx agentdb mcp --port 3000
-  npx agentdb mcp --log debug
-
-CLAUDE DESKTOP CONFIG
-  Add to ~/.config/claude/config.json:
-  {
-    "mcpServers": {
-      "agentdb": {
-        "command": "npx",
-        "args": ["agentdb", "mcp"]
-      }
-    }
-  }
-`,
-    'create-plugin': `
-COMMAND: create-plugin
-
-Create a new learning plugin with interactive wizard
-
-USAGE
-  npx agentdb create-plugin [options]
-
-OPTIONS
-  -t, --template <name>     Use template (see list-templates)
-  -n, --name <name>         Plugin name (lowercase-hyphenated)
-  --no-customize            Skip customization (use defaults)
-  -o, --output <dir>        Output directory (default: ./plugins)
-  --force                   Overwrite existing plugin
-  --dry-run                 Preview without creating files
-
-AVAILABLE TEMPLATES
-  decision-transformer      Sequence modeling RL (recommended)
-  q-learning               Value-based learning
-  sarsa                    On-policy TD learning
-  actor-critic             Policy gradient with baseline
-
-EXAMPLES
-  npx agentdb create-plugin
-  npx agentdb create-plugin -t q-learning -n my-agent
-  npx agentdb create-plugin --dry-run
-`,
-    import: `
-COMMAND: import
-
-Import vectors from file into database
-
-USAGE
-  npx agentdb import <database> <file> [options]
-
-ARGUMENTS
-  <database>        Database path
-  <file>            Input file (JSON, CSV)
-
-OPTIONS
-  -f, --format <type>       Format: json, csv (default: json)
-  -b, --batch-size <n>      Batch size (default: 1000)
-  -v, --verbose             Verbose output
-
-EXAMPLES
-  npx agentdb import ./db.sqlite vectors.json
-  npx agentdb import ./db.sqlite data.csv -f csv -v
-`,
-    export: `
-COMMAND: export
-
-Export vectors from database to file
-
-USAGE
-  npx agentdb export <database> <file> [options]
-
-ARGUMENTS
-  <database>        Database path
-  <file>            Output file
-
-OPTIONS
-  -f, --format <type>       Format: json, csv (default: json)
-  -l, --limit <n>           Limit number of vectors
-  -v, --verbose             Verbose output
-
-EXAMPLES
-  npx agentdb export ./db.sqlite vectors.json
-  npx agentdb export ./db.sqlite data.csv -f csv -l 1000
-`,
-    query: `
-COMMAND: query
-
-Query vector database for similar vectors
-
-USAGE
-  npx agentdb query <database> <embedding> [options]
-
-ARGUMENTS
-  <database>        Database path
-  <embedding>       Vector as JSON array or space-separated
-
-OPTIONS
-  -k, --top-k <n>           Results to return (default: 5)
-  -m, --metric <name>       Metric: cosine, euclidean, dot
-  -t, --threshold <n>       Min similarity threshold
-  -f, --format <type>       Output: table, json (default: table)
-  -v, --verbose             Verbose output
-
-EXAMPLES
-  npx agentdb query ./db.sqlite "[0.1,0.2,0.3]"
-  npx agentdb query ./db.sqlite "0.1 0.2 0.3" -k 10
-`,
-    stats: `
-COMMAND: stats
-
-Show database statistics and information
-
-USAGE
-  npx agentdb stats <database> [options]
-
-ARGUMENTS
-  <database>        Database path
-
-OPTIONS
-  -d, --detailed            Show detailed statistics
-  -f, --format <type>       Output: table, json (default: table)
-
-EXAMPLES
-  npx agentdb stats ./db.sqlite
-  npx agentdb stats ./db.sqlite -d -f json
-`,
-    benchmark: `
-COMMAND: benchmark
-
-Run comprehensive performance benchmarks
-
-USAGE
-  npx agentdb benchmark [options]
-
-OPTIONS
-  --suite <name>            Suite: insertion, search, all
-  --size <n>                Dataset size (default: 10000)
-  --dimension <n>           Vector dimension (default: 1536)
-
-EXAMPLES
-  npx agentdb benchmark
-  npx agentdb benchmark --suite insertion
-  npx agentdb benchmark --size 50000
-`,
-    'list-plugins': `
-COMMAND: list-plugins
-
-List all available learning plugins
-
-USAGE
-  npx agentdb list-plugins [options]
-
-OPTIONS
-  -v, --verbose             Show detailed information
-  --filter <pattern>        Filter by name pattern
-  --json                    Output as JSON
-
-EXAMPLES
-  npx agentdb list-plugins
-  npx agentdb list-plugins --verbose
-  npx agentdb list-plugins --filter "q-*"
-`,
-    'list-templates': `
-COMMAND: list-templates
-
-List all available plugin templates
-
-USAGE
-  npx agentdb list-templates [options]
-
-OPTIONS
-  -d, --detailed            Show detailed information
-  -c, --category <name>     Filter by category
-  --json                    Output as JSON
-
-EXAMPLES
-  npx agentdb list-templates
-  npx agentdb list-templates --detailed
-  npx agentdb list-templates -c reinforcement-learning
-`,
-    'plugin-info': `
-COMMAND: plugin-info
-
-Get detailed information about a plugin
-
-USAGE
-  npx agentdb plugin-info <name> [options]
-
-ARGUMENTS
-  <name>            Plugin name
-
-OPTIONS
-  --json                    Output as JSON
-  --metrics                 Include performance metrics
-  --dependencies            Show dependencies
-
-EXAMPLES
-  npx agentdb plugin-info my-plugin
-  npx agentdb plugin-info my-plugin --metrics
-`
-  };
-
-  if (helps[command]) {
-    console.log(helps[command]);
-  } else {
-    console.error(`No detailed help available for: ${command}`);
-    console.error(`Run: npx agentdb ${command} --help`);
-  }
-}
-
-function showVersion() {
-  console.log(`agentdb v${version}`);
-  console.log(`Node: ${process.version}`);
-  console.log(`Platform: ${process.platform} ${process.arch}`);
-}
-
-async function startMcpServer() {
-  console.error('🚀 Starting AgentDB MCP Server...');
-  console.error('');
-
-  try {
-    // Check if MCP implementation exists
-    const mcpPath = require.resolve('../dist/mcp-server.js');
-
-    // Import and start the MCP server
-    const { AgentDBMCPServer } = require(mcpPath);
-    const server = new AgentDBMCPServer();
-    await server.start();
-  } catch (error) {
-    console.error('❌ Failed to start MCP server');
-    console.error('');
-    console.error('Error:', error.message);
-    console.error('');
-    console.error('Make sure to build the project first:');
-    console.error('  npm run build');
-    console.error('');
-    process.exit(1);
-  }
-}
-
-function initDatabase(path) {
-  if (!path) {
-    console.error('❌ Error: Database path required');
-    console.error('');
-    console.error('Usage: agentdb init <path>');
-    console.error('Example: agentdb init ./agents.db');
-    process.exit(1);
-  }
-
-  console.log(`📦 Initializing agent memory database: ${path}`);
-  console.log('');
-
-  try {
-    const { SQLiteVectorDB, Presets } = require('../dist/index.js');
-
-    // Create a small test database
-    const config = Presets.smallDataset(1536, path);
-    const db = new SQLiteVectorDB(config);
-
-    console.log('✅ Database initialized successfully!');
-    console.log('');
-    console.log('Configuration:');
-    console.log(`  Path: ${path}`);
-    console.log(`  Mode: ${config.memoryMode ? 'in-memory' : 'persistent'}`);
-    console.log(`  Cache Size: ${config.cacheSize}MB`);
-    console.log(`  WAL Mode: ${config.walMode ? 'enabled' : 'disabled'}`);
-    console.log('');
-    console.log('Next steps:');
-    console.log('  1. Import the library: const { SQLiteVectorDB } = require("agentdb")');
-    console.log('  2. Insert vectors: db.insert({ embedding: [...], metadata: {...} })');
-    console.log('  3. Search: db.search(queryVector, 5, "cosine", 0.0)');
-    console.log('  4. View the documentation: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb');
-    console.log('');
-
-    db.close();
-  } catch (error) {
-    console.error('❌ Failed to initialize database:', error.message);
-    if (error.stack) {
-      console.error('\nStack trace:');
-      console.error(error.stack);
-    }
-    process.exit(1);
-  }
-}
-
-async function runBenchmark(...args) {
-  try {
-    // Convert arguments to array
-    const argArray = Array.isArray(args[0]) ? args[0] : Array.from(args);
-
-    // Parse arguments
-    const options = {
-      quick: argArray.includes('--quick') || argArray.includes('-q'),
-      vectors: null
-    };
-
-    // Parse custom vector count
-    const vectorsIndex = argArray.findIndex(arg => arg === '--vectors' || arg === '-v');
-    if (vectorsIndex !== -1 && argArray[vectorsIndex + 1]) {
-      options.vectors = parseInt(argArray[vectorsIndex + 1], 10);
-    }
-
-    // Show help if requested
-    if (argArray.includes('--help') || argArray.includes('-h')) {
-      console.log('');
-      console.log('AgentDB Benchmark');
-      console.log('');
-      console.log('USAGE');
-      console.log('  npx agentdb benchmark [options]');
-      console.log('');
-      console.log('OPTIONS');
-      console.log('  --quick, -q          Run quick benchmark (500/1000 vectors)');
-      console.log('  --vectors, -v <n>    Custom batch size (default: 5000, quick: 1000)');
-      console.log('  --help, -h           Show this help');
-      console.log('');
-      console.log('EXAMPLES');
-      console.log('  npx agentdb benchmark              # Standard benchmark (5K vectors)');
-      console.log('  npx agentdb benchmark --quick      # Quick benchmark (1K vectors)');
-      console.log('  npx agentdb benchmark -v 10000     # Custom 10K vectors');
-      console.log('');
-      console.log('For comprehensive benchmarks with WASM comparison:');
-      console.log('  git clone https://github.com/ruvnet/agentic-flow.git');
-      console.log('  cd agentic-flow/packages/agentdb');
-      console.log('  npm install && npm run bench:comprehensive');
-      console.log('');
-      return;
-    }
-
-    // Run the included benchmark
-    const benchmarkPath = require.resolve('./benchmark.js');
-    const { runBenchmark } = require(benchmarkPath);
-    await runBenchmark(options);
-  } catch (error) {
-    console.error('');
-    console.error('❌ Benchmark failed:', error.message);
-    console.error('');
-    console.error('For comprehensive benchmarks, clone the source repository:');
-    console.error('');
-    console.error('  git clone https://github.com/ruvnet/agentic-flow.git');
-    console.error('  cd agentic-flow/packages/agentdb');
-    console.error('  npm install');
-    console.error('  npm run bench:comprehensive');
-    console.error('');
-    process.exit(1);
-  }
-}
-
-function startRepl() {
-  console.log('🔧 Interactive REPL (experimental)');
-  console.log('');
-  console.error('❌ REPL not implemented yet');
-  console.error('');
-  console.error('For now, use Node.js REPL:');
-  console.error('  node');
-  console.error('  > const { SqliteVectorDB, Presets } = require("agentdb")');
-  console.error('  > const db = await SqliteVectorDB.new(Presets.inMemory(1536))');
-  console.error('');
-  process.exit(1);
-}
-
-// Learning Plugin CLI commands
-function createPlugin(...args) {
-  try {
-    const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
-    // Use the .mjs wrapper to load the ES module
-    // Prepend 'create-plugin' command since plugin-cli expects it
-    const { spawn } = require('child_process');
-    const child = spawn('node', [wrapperPath, 'create-plugin', ...args], {
-      stdio: 'inherit',
-      cwd: require('path').resolve(__dirname, '..')
-    });
-
-    child.on('close', (code) => {
-      process.exit(code);
-    });
-  } catch (error) {
-    console.error('❌ Plugin CLI not available');
-    console.error('');
-    console.error('Error:', error.message);
-    console.error('');
-    console.error('Make sure to build the project first:');
-    console.error('  npm run build');
-    console.error('');
-    process.exit(1);
-  }
-}
-
-function listPlugins(...args) {
-  // Call plugin CLI wrapper with list-plugins command
-  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
-  const { spawn } = require('child_process');
-  const child = spawn('node', [wrapperPath, 'list-plugins', ...args], {
-    stdio: 'inherit',
-    cwd: require('path').resolve(__dirname, '..')
-  });
-  child.on('close', (code) => process.exit(code));
-}
-
-function listTemplates(...args) {
-  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
-  const { spawn} = require('child_process');
-  const child = spawn('node', [wrapperPath, 'list-templates', ...args], {
-    stdio: 'inherit',
-    cwd: require('path').resolve(__dirname, '..')
-  });
-  child.on('close', (code) => process.exit(code));
-}
-
-function pluginInfo(...args) {
-  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
-  const { spawn } = require('child_process');
-  const child = spawn('node', [wrapperPath, 'plugin-info', ...args], {
-    stdio: 'inherit',
-    cwd: require('path').resolve(__dirname, '..')
-  });
-  child.on('close', (code) => process.exit(code));
-}
-
-function usePlugin(...args) {
-  const wrapperPath = require('path').join(__dirname, 'plugin-cli-wrapper.mjs');
-  const { spawn } = require('child_process');
-  const child = spawn('node', [wrapperPath, 'use-plugin', ...args], {
-    stdio: 'inherit',
-    cwd: require('path').resolve(__dirname, '..')
-  });
-  child.on('close', (code) => process.exit(code));
-}
-
-// Database commands
-function importCommand(...args) {
-  const [database, file, ...flags] = args;
-
-  if (!database || !file) {
-    console.error('❌ Usage: agentdb import <database> <file> [options]');
-    console.error('');
-    console.error('Options:');
-    console.error('  -f, --format <format>       File format (json|csv), default: json');
-    console.error('  -b, --batch-size <size>     Batch size for imports, default: 1000');
-    console.error('  -v, --verbose               Verbose output');
-    console.error('');
-    console.error('Examples:');
-    console.error('  agentdb import ./db.sqlite vectors.json');
-    console.error('  agentdb import ./db.sqlite data.csv -f csv -v');
-    process.exit(1);
-  }
-
-  try {
-    const { importVectors } = require('../dist/cli/db-commands.js');
-    const options = parseFlags(flags);
-    importVectors(database, file, options).catch(err => {
-      console.error('❌ Import failed:', err.message);
-      process.exit(1);
-    });
-  } catch (error) {
-    console.error('❌ Database commands not available. Please run: npm run build');
-    process.exit(1);
-  }
-}
-
-function exportCommand(...args) {
-  const [database, file, ...flags] = args;
-
-  if (!database || !file) {
-    console.error('❌ Usage: agentdb export <database> <file> [options]');
-    console.error('');
-    console.error('Options:');
-    console.error('  -f, --format <format>       File format (json|csv), default: json');
-    console.error('  -l, --limit <number>        Limit number of vectors');
-    console.error('  -v, --verbose               Verbose output');
-    console.error('');
-    console.error('Examples:');
-    console.error('  agentdb export ./db.sqlite vectors.json');
-    console.error('  agentdb export ./db.sqlite data.csv -f csv -l 1000');
-    process.exit(1);
-  }
-
-  try {
-    const { exportVectors } = require('../dist/cli/db-commands.js');
-    const options = parseFlags(flags);
-    exportVectors(database, file, options).catch(err => {
-      console.error('❌ Export failed:', err.message);
-      process.exit(1);
-    });
-  } catch (error) {
-    console.error('❌ Database commands not available. Please run: npm run build');
-    process.exit(1);
-  }
-}
-
-function queryCommand(...args) {
-  const [database, embedding, ...flags] = args;
-
-  if (!database || !embedding) {
-    console.error('❌ Usage: agentdb query <database> <embedding> [options]');
-    console.error('');
-    console.error('Options:');
-    console.error('  -k, --top-k <number>        Number of results, default: 5');
-    console.error('  -m, --metric <metric>       Similarity metric (cosine|euclidean|dot), default: cosine');
-    console.error('  -t, --threshold <number>    Minimum similarity threshold, default: 0.0');
-    console.error('  -f, --format <format>       Output format (table|json), default: table');
-    console.error('  -v, --verbose               Verbose output');
-    console.error('');
-    console.error('Examples:');
-    console.error('  agentdb query ./db.sqlite "[0.1,0.2,0.3]"');
-    console.error('  agentdb query ./db.sqlite "0.1 0.2 0.3" -k 10 -m euclidean');
-    process.exit(1);
-  }
-
-  try {
-    const { queryVectors } = require('../dist/cli/db-commands.js');
-    const options = parseFlags(flags);
-    queryVectors(database, embedding, options).catch(err => {
-      console.error('❌ Query failed:', err.message);
-      process.exit(1);
-    });
-  } catch (error) {
-    console.error('❌ Database commands not available. Please run: npm run build');
-    process.exit(1);
-  }
-}
-
-function statsCommand(...args) {
-  const [database, ...flags] = args;
-
-  if (!database) {
-    console.error('❌ Usage: agentdb stats <database> [options]');
-    console.error('');
-    console.error('Options:');
-    console.error('  -d, --detailed              Show detailed statistics');
-    console.error('  -f, --format <format>       Output format (table|json), default: table');
-    console.error('');
-    console.error('Examples:');
-    console.error('  agentdb stats ./db.sqlite');
-    console.error('  agentdb stats ./db.sqlite -d -f json');
-    process.exit(1);
-  }
-
-  try {
-    const { showStats } = require('../dist/cli/db-commands.js');
-    const options = parseFlags(flags);
-    showStats(database, options).catch(err => {
-      console.error('❌ Stats command failed:', err.message);
-      process.exit(1);
-    });
-  } catch (error) {
-    console.error('❌ Database commands not available. Please run: npm run build');
-    process.exit(1);
-  }
-}
-
-// Parse command line flags into options object
-function parseFlags(flags) {
-  const options = {};
-  for (let i = 0; i < flags.length; i++) {
-    const flag = flags[i];
-
-    if (flag === '-f' || flag === '--format') {
-      options.format = flags[++i];
-    } else if (flag === '-b' || flag === '--batch-size') {
-      options.batchSize = parseInt(flags[++i], 10);
-    } else if (flag === '-k' || flag === '--top-k') {
-      options.k = parseInt(flags[++i], 10);
-    } else if (flag === '-m' || flag === '--metric') {
-      options.metric = flags[++i];
-    } else if (flag === '-t' || flag === '--threshold') {
-      options.threshold = parseFloat(flags[++i]);
-    } else if (flag === '-l' || flag === '--limit') {
-      options.limit = parseInt(flags[++i], 10);
-    } else if (flag === '-d' || flag === '--detailed') {
-      options.detailed = true;
-    } else if (flag === '-v' || flag === '--verbose') {
-      options.verbose = true;
-    }
-  }
-  return options;
-}
-
-// Parse command line arguments
-const [,, command = 'help', ...args] = process.argv;
-
-// Handle --version and -v flags at root level
-if (command === '--version' || command === '-v') {
-  showVersion();
-  process.exit(0);
-}
-
-// Handle --help and -h flags at root level
-if (command === '--help' || command === '-h') {
-  showHelp();
-  process.exit(0);
-}
-
-// Handle --help flag for any command
-if (args.includes('--help') || args.includes('-h')) {
-  showCommandHelp(command);
-  process.exit(0);
-}
-
-const handler = COMMANDS[command];
-if (handler) {
-  // Handle async commands
-  const result = handler(...args);
-  if (result instanceof Promise) {
-    result.catch(error => {
-      console.error('Error:', error);
-      process.exit(1);
-    });
-  }
-} else {
-  console.error(`❌ Unknown command: ${command}`);
-  console.error('');
-  console.error('Run "npx agentdb help" for usage information');
-  process.exit(1);
-}