agentic-flow 1.9.0 → 1.9.1

package/docs/features/agent-booster/04-NPM-SDK.md

@@ -1,673 +0,0 @@
-# Agent Booster: NPM SDK & CLI Design
-
-## 📦 NPM Package Structure
-
-```
-npm/
-├── agent-booster/                  # Main SDK package
-│   ├── package.json
-│   ├── index.js                    # Auto-detection loader
-│   ├── index.d.ts                  # TypeScript definitions
-│   ├── native/                     # Native addon binaries
-│   │   ├── index.node             # Auto-selected by platform
-│   │   ├── linux-x64.node
-│   │   ├── darwin-x64.node
-│   │   ├── darwin-arm64.node
-│   │   └── win32-x64.node
-│   ├── wasm/                       # WebAssembly fallback
-│   │   ├── agent_booster_bg.wasm
-│   │   └── agent_booster.js
-│   └── README.md
-│
-└── agent-booster-cli/              # Standalone CLI
-    ├── package.json
-    ├── bin/
-    │   └── agent-booster.js        # CLI entry point
-    ├── commands/
-    │   ├── apply.js
-    │   ├── batch.js
-    │   ├── watch.js
-    │   ├── mcp.js
-    │   └── dashboard.js
-    └── README.md
-```
-
-## 🎯 Main SDK Package
-
-### package.json
-
-```json
-{
-  "name": "agent-booster",
-  "version": "0.1.0",
-  "description": "Ultra-fast code application engine for AI agents (200x faster than LLMs)",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "keywords": [
-    "ai",
-    "code-editing",
-    "ast",
-    "semantic-merge",
-    "vector-embeddings",
-    "llm",
-    "morph-alternative",
-    "agentic-flow",
-    "mcp",
-    "rust",
-    "napi",
-    "wasm"
-  ],
-  "author": "Your Name <your@email.com>",
-  "license": "MIT OR Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/your-org/agent-booster.git"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "os": ["linux", "darwin", "win32"],
-  "cpu": ["x64", "arm64"],
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "native/",
-    "wasm/",
-    "README.md",
-    "LICENSE"
-  ],
-  "optionalDependencies": {
-    "@agent-booster/linux-x64": "0.1.0",
-    "@agent-booster/darwin-x64": "0.1.0",
-    "@agent-booster/darwin-arm64": "0.1.0",
-    "@agent-booster/win32-x64": "0.1.0"
-  },
-  "dependencies": {
-    "detect-libc": "^2.0.2"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "postinstall": "node scripts/download-model.js",
-    "test": "node test/index.js"
-  }
-}
-```
-
-### index.js (Auto-Detection Loader)
-
-```javascript
-// npm/agent-booster/index.js
-
-const os = require('os');
-const path = require('path');
-
-let AgentBooster = null;
-
-// Try to load native addon first (fastest)
-function loadNative() {
-  try {
-    const platform = os.platform();
-    const arch = os.arch();
-    const nativeBinding = `${platform}-${arch}.node`;
-
-    // Try platform-specific package
-    try {
-      const platformPackage = `@agent-booster/${platform}-${arch}`;
-      AgentBooster = require(platformPackage).AgentBooster;
-      console.log(`[agent-booster] Using native addon (${platform}-${arch})`);
-      return true;
-    } catch (e) {
-      // Fall through to bundled native
-    }
-
-    // Try bundled native addon
-    const nativePath = path.join(__dirname, 'native', nativeBinding);
-    AgentBooster = require(nativePath).AgentBooster;
-    console.log(`[agent-booster] Using bundled native addon (${platform}-${arch})`);
-    return true;
-  } catch (error) {
-    console.warn('[agent-booster] Native addon not available:', error.message);
-    return false;
-  }
-}
-
-// Fallback to WASM
-function loadWasm() {
-  try {
-    const wasmModule = require('./wasm/agent_booster.js');
-    AgentBooster = wasmModule.AgentBooster;
-    console.log('[agent-booster] Using WebAssembly');
-    return true;
-  } catch (error) {
-    console.error('[agent-booster] WASM not available:', error.message);
-    return false;
-  }
-}
-
-// Load in order of preference
-if (!loadNative()) {
-  if (!loadWasm()) {
-    throw new Error(
-      'Failed to load Agent Booster. Neither native addon nor WASM are available.\n' +
-      'Please report this issue: https://github.com/your-org/agent-booster/issues'
-    );
-  }
-}
-
-module.exports = { AgentBooster };
-module.exports.default = AgentBooster;
-```
-
-### index.d.ts (TypeScript Definitions)
-
-```typescript
-// npm/agent-booster/index.d.ts
-
-export interface AgentBoosterConfig {
-  /** Embedding model to use */
-  model?: 'jina-code-v2' | 'all-MiniLM-L6-v2' | string;
-
-  /** Confidence threshold (0-1). Edits below this will fail or fallback. */
-  confidenceThreshold?: number;
-
-  /** Enable fallback to Morph LLM when confidence is low */
-  fallbackToMorph?: boolean;
-
-  /** Morph API key (required if fallbackToMorph is true) */
-  morphApiKey?: string;
-
-  /** Model cache directory */
-  cacheDir?: string;
-
-  /** Maximum number of chunks to extract per file */
-  maxChunks?: number;
-
-  /** Enable embedding caching */
-  cacheEmbeddings?: boolean;
-
-  /** Enable debug logging */
-  debug?: boolean;
-}
-
-export interface EditRequest {
-  /** Original code content */
-  originalCode: string;
-
-  /** Edit description or snippet to apply */
-  editSnippet: string;
-
-  /** Programming language */
-  language?: 'javascript' | 'typescript' | 'python' | 'rust' | 'go' | 'java' | string;
-
-  /** Optional edit options */
-  options?: EditOptions;
-}
-
-export interface EditOptions {
-  /** Preferred merge strategy (auto-detected if not specified) */
-  strategy?: 'exact' | 'fuzzy' | 'insert' | 'append';
-
-  /** Minimum confidence required */
-  minConfidence?: number;
-
-  /** Enable syntax validation */
-  validateSyntax?: boolean;
-}
-
-export interface EditResult {
-  /** Merged code */
-  mergedCode: string;
-
-  /** Confidence score (0-1) */
-  confidence: number;
-
-  /** Merge strategy used */
-  strategy: 'exact_replace' | 'insert_before' | 'insert_after' | 'append' | 'fuzzy_replace';
-
-  /** Additional metadata */
-  metadata: EditMetadata;
-}
-
-export interface EditMetadata {
-  /** Latency in milliseconds */
-  latency_ms: number;
-
-  /** Matched chunk information */
-  matched_chunk?: {
-    start_line: number;
-    end_line: number;
-    node_type: string;
-  };
-
-  /** Syntax validation result */
-  syntax_valid: boolean;
-
-  /** Method used (native/wasm) */
-  method: 'native' | 'wasm';
-
-  /** Model used */
-  model: string;
-}
-
-export class AgentBooster {
-  constructor(config?: AgentBoosterConfig);
-
-  /**
-   * Apply a single code edit
-   */
-  applyEdit(request: EditRequest): Promise<EditResult>;
-
-  /**
-   * Apply multiple edits in parallel
-   */
-  batchApply(requests: EditRequest[]): Promise<EditResult[]>;
-
-  /**
-   * Get current configuration
-   */
-  getConfig(): AgentBoosterConfig;
-
-  /**
-   * Update configuration
-   */
-  updateConfig(config: Partial<AgentBoosterConfig>): void;
-}
-
-export default AgentBooster;
-```
-
-## 🖥️ Standalone CLI Package
-
-### package.json
-
-```json
-{
-  "name": "agent-booster-cli",
-  "version": "0.1.0",
-  "description": "CLI for Agent Booster - ultra-fast code editing",
-  "bin": {
-    "agent-booster": "./bin/agent-booster.js"
-  },
-  "keywords": ["cli", "code-editing", "ai", "agent-booster"],
-  "author": "Your Name <your@email.com>",
-  "license": "MIT OR Apache-2.0",
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "dependencies": {
-    "agent-booster": "^0.1.0",
-    "commander": "^11.0.0",
-    "chalk": "^5.0.0",
-    "ora": "^7.0.0",
-    "glob": "^10.0.0",
-    "chokidar": "^3.5.0"
-  }
-}
-```
-
-### bin/agent-booster.js
-
-```javascript
-#!/usr/bin/env node
-
-const { Command } = require('commander');
-const chalk = require('chalk');
-const packageJson = require('../package.json');
-
-const program = new Command();
-
-program
-  .name('agent-booster')
-  .description('Ultra-fast code application engine for AI agents')
-  .version(packageJson.version);
-
-// Commands
-program
-  .command('apply <file> <edit>')
-  .description('Apply a single code edit')
-  .option('-m, --model <model>', 'Embedding model', 'jina-code-v2')
-  .option('-t, --threshold <threshold>', 'Confidence threshold', '0.65')
-  .option('--dry-run', 'Show result without writing')
-  .option('--fallback', 'Fallback to Morph LLM if needed')
-  .action(require('../commands/apply'));
-
-program
-  .command('batch <edits-file>')
-  .description('Apply multiple edits from JSON file')
-  .option('-m, --model <model>', 'Embedding model', 'jina-code-v2')
-  .option('-o, --output <dir>', 'Output directory')
-  .option('--parallel <n>', 'Parallel jobs', '4')
-  .action(require('../commands/batch'));
-
-program
-  .command('watch <path>')
-  .description('Watch directory for changes and apply edits')
-  .option('-m, --model <model>', 'Embedding model', 'jina-code-v2')
-  .option('--ignore <patterns>', 'Ignore patterns (comma-separated)')
-  .action(require('../commands/watch'));
-
-program
-  .command('mcp')
-  .description('Start Model Context Protocol server')
-  .option('--port <port>', 'HTTP port (default: stdio)', '')
-  .option('--config <file>', 'Config file')
-  .action(require('../commands/mcp'));
-
-program
-  .command('dashboard')
-  .description('Start web dashboard for metrics')
-  .option('-p, --port <port>', 'Port', '8080')
-  .action(require('../commands/dashboard'));
-
-program
-  .command('download-models')
-  .description('Download embedding models')
-  .option('-m, --model <models>', 'Models to download (comma-separated)', 'jina-code-v2')
-  .action(require('../commands/download-models'));
-
-program.parse();
-```
-
-### commands/apply.js
-
-```javascript
-// npm/agent-booster-cli/commands/apply.js
-
-const { AgentBooster } = require('agent-booster');
-const { readFileSync, writeFileSync } = require('fs');
-const chalk = require('chalk');
-const ora = require('ora');
-
-module.exports = async function apply(file, edit, options) {
-  const spinner = ora(`Applying edit to ${file}...`).start();
-
-  try {
-    // Initialize Agent Booster
-    const booster = new AgentBooster({
-      model: options.model,
-      confidenceThreshold: parseFloat(options.threshold),
-      fallbackToMorph: options.fallback,
-      morphApiKey: process.env.MORPH_API_KEY,
-    });
-
-    // Read file
-    const originalCode = readFileSync(file, 'utf-8');
-
-    // Apply edit
-    const startTime = Date.now();
-    const result = await booster.applyEdit({
-      originalCode,
-      editSnippet: edit,
-      language: detectLanguage(file),
-    });
-    const latency = Date.now() - startTime;
-
-    spinner.succeed('Edit applied successfully!');
-
-    // Display results
-    console.log('');
-    console.log(chalk.bold('Results:'));
-    console.log(`  Strategy:    ${chalk.cyan(result.strategy)}`);
-    console.log(`  Confidence:  ${formatConfidence(result.confidence)}`);
-    console.log(`  Latency:     ${chalk.green(latency + 'ms')}`);
-    console.log(`  Cost:        ${chalk.green('$0.00')}`);
-    console.log('');
-
-    if (result.confidence < parseFloat(options.threshold)) {
-      console.log(chalk.yellow('⚠️  Warning: Low confidence'));
-      console.log(chalk.yellow(`   Consider using --fallback for better accuracy`));
-      console.log('');
-    }
-
-    // Write or preview
-    if (options.dryRun) {
-      console.log(chalk.bold('Dry run - no changes written'));
-      console.log('');
-      console.log(chalk.dim('─'.repeat(80)));
-      console.log(result.mergedCode);
-      console.log(chalk.dim('─'.repeat(80)));
-    } else {
-      writeFileSync(file, result.mergedCode, 'utf-8');
-      console.log(chalk.green(`✓ Saved to ${file}`));
-    }
-  } catch (error) {
-    spinner.fail('Edit failed');
-    console.error(chalk.red('Error:'), error.message);
-    process.exit(1);
-  }
-};
-
-function detectLanguage(filePath) {
-  const ext = filePath.split('.').pop();
-  const langMap = {
-    'js': 'javascript',
-    'jsx': 'javascript',
-    'ts': 'typescript',
-    'tsx': 'typescript',
-    'py': 'python',
-    'rs': 'rust',
-  };
-  return langMap[ext] || 'javascript';
-}
-
-function formatConfidence(confidence) {
-  const percentage = (confidence * 100).toFixed(1) + '%';
-  if (confidence >= 0.85) return chalk.green(percentage);
-  if (confidence >= 0.65) return chalk.yellow(percentage);
-  return chalk.red(percentage);
-}
-```
-
-### commands/watch.js
-
-```javascript
-// npm/agent-booster-cli/commands/watch.js
-
-const { AgentBooster } = require('agent-booster');
-const chokidar = require('chokidar');
-const chalk = require('chalk');
-const path = require('path');
-
-module.exports = async function watch(directory, options) {
-  console.log(chalk.bold(`\n📁 Watching ${directory} for changes...\n`));
-
-  const booster = new AgentBooster({
-    model: options.model,
-  });
-
-  const ignorePatterns = options.ignore
-    ? options.ignore.split(',')
-    : ['node_modules/**', '.git/**', 'dist/**', 'build/**'];
-
-  const watcher = chokidar.watch(directory, {
-    ignored: ignorePatterns,
-    persistent: true,
-    ignoreInitial: true,
-  });
-
-  watcher
-    .on('change', async (filePath) => {
-      console.log(chalk.dim(`${new Date().toLocaleTimeString()} `), 'Changed:', filePath);
-
-      // Auto-apply formatting or linting fixes
-      // This is a placeholder - actual implementation would read
-      // from a .agent-booster.json config file
-    })
-    .on('error', (error) => {
-      console.error(chalk.red('Watcher error:'), error);
-    });
-
-  // Keep process alive
-  await new Promise(() => {});
-};
-```
-
-## 📚 Usage Examples
-
-### Example 1: Simple API Usage
-
-```typescript
-import { AgentBooster } from 'agent-booster';
-import { readFileSync, writeFileSync } from 'fs';
-
-const booster = new AgentBooster({
-  model: 'jina-code-v2',
-  confidenceThreshold: 0.65,
-});
-
-const result = await booster.applyEdit({
-  originalCode: readFileSync('src/utils/parser.ts', 'utf-8'),
-  editSnippet: 'add error handling to parseConfig function',
-  language: 'typescript',
-});
-
-if (result.confidence >= 0.65) {
-  writeFileSync('src/utils/parser.ts', result.mergedCode, 'utf-8');
-  console.log(`✓ Applied edit with ${(result.confidence * 100).toFixed(1)}% confidence`);
-} else {
-  console.log(`✗ Confidence too low: ${(result.confidence * 100).toFixed(1)}%`);
-}
-```
-
-### Example 2: Batch Processing
-
-```typescript
-const edits = [
-  {
-    originalCode: readFileSync('src/auth.ts', 'utf-8'),
-    editSnippet: 'add JWT token validation',
-    language: 'typescript',
-  },
-  {
-    originalCode: readFileSync('src/db.ts', 'utf-8'),
-    editSnippet: 'add connection pooling',
-    language: 'typescript',
-  },
-  {
-    originalCode: readFileSync('src/api.ts', 'utf-8'),
-    editSnippet: 'add rate limiting',
-    language: 'typescript',
-  },
-];
-
-const results = await booster.batchApply(edits);
-
-console.log(`✓ Applied ${results.filter(r => r.confidence >= 0.65).length} of ${results.length} edits`);
-```
-
-### Example 3: CLI Usage
-
-```bash
-# Apply single edit
-npx agent-booster apply src/main.ts "add error handling to parseConfig"
-
-# Dry run (preview only)
-npx agent-booster apply src/main.ts "add logging" --dry-run
-
-# Batch edits from JSON file
-cat > edits.json <<EOF
-[
-  {
-    "file": "src/auth.ts",
-    "edit": "add JWT validation"
-  },
-  {
-    "file": "src/db.ts",
-    "edit": "add connection pooling"
-  }
-]
-EOF
-
-npx agent-booster batch edits.json
-
-# Watch mode
-npx agent-booster watch src/ --model jina-code-v2
-
-# Start MCP server
-npx agent-booster mcp --port 3000
-
-# Download models
-npx agent-booster download-models --model jina-code-v2,all-MiniLM-L6-v2
-```
-
-## 🚀 Distribution Strategy
-
-### Platform-Specific Packages
-
-```json
-// @agent-booster/linux-x64/package.json
-{
-  "name": "@agent-booster/linux-x64",
-  "version": "0.1.0",
-  "os": ["linux"],
-  "cpu": ["x64"],
-  "main": "agent-booster.linux-x64.node"
-}
-
-// Similar for:
-// - @agent-booster/darwin-x64
-// - @agent-booster/darwin-arm64
-// - @agent-booster/win32-x64
-```
-
-### Post-Install Script
-
-```javascript
-// scripts/download-model.js
-
-const https = require('https');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const MODEL_URLS = {
-  'jina-code-v2': 'https://huggingface.co/jinaai/jina-embeddings-v2-base-code/resolve/main/onnx/model.onnx',
-  'all-MiniLM-L6-v2': 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx',
-};
-
-async function downloadModel(modelName) {
-  const cacheDir = path.join(os.homedir(), '.cache', 'agent-booster', 'models');
-  const modelPath = path.join(cacheDir, `${modelName}.onnx`);
-
-  if (fs.existsSync(modelPath)) {
-    console.log(`[agent-booster] Model ${modelName} already cached`);
-    return;
-  }
-
-  console.log(`[agent-booster] Downloading model ${modelName}...`);
-
-  // Create cache directory
-  fs.mkdirSync(cacheDir, { recursive: true });
-
-  // Download model
-  // (implementation omitted for brevity)
-
-  console.log(`[agent-booster] Model ${modelName} downloaded successfully`);
-}
-
-// Run on install
-const defaultModel = process.env.AGENT_BOOSTER_MODEL || 'jina-code-v2';
-downloadModel(defaultModel).catch(console.error);
-```
-
-## 📊 Bundle Size Analysis
-
-```
-agent-booster@0.1.0
-├── Native addon (per platform): ~2-3 MB
-├── WASM fallback: ~1.5 MB
-├── JavaScript/TypeScript: ~50 KB
-└── Total installed: ~5-8 MB
-
-agent-booster-cli@0.1.0
-├── Dependencies: ~2 MB
-├── CLI code: ~100 KB
-└── Total installed: ~2.1 MB
-
-Models (downloaded on-demand):
-├── jina-code-v2: ~150 MB (one-time)
-└── all-MiniLM-L6-v2: ~90 MB (one-time)
-```