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

package/simulation/docs/architecture/EXTENSION-API.md

@@ -0,0 +1,868 @@
+# AgentDB Extension API v2.0
+
+## Overview
+
+This document defines the Extension API for creating custom simulation scenarios, components, and integrations with AgentDB v2.0.
+
+---
+
+## Table of Contents
+
+1. [Creating Custom Scenarios](#creating-custom-scenarios)
+2. [Component Interfaces](#component-interfaces)
+3. [Plugin System](#plugin-system)
+4. [Event System](#event-system)
+5. [Code Examples](#code-examples)
+
+---
+
+## Creating Custom Scenarios
+
+### Scenario Interface
+
+All simulation scenarios must implement the `SimulationScenario` interface:
+
+```typescript
+interface SimulationScenario {
+  metadata: SimulationMetadata;
+  execute(config: AgentDBConfig): Promise<SimulationResult>;
+  validate?(config: AgentDBConfig): ValidationResult;
+  cleanup?(): Promise<void>;
+}
+
+interface SimulationMetadata {
+  id: string;
+  name: string;
+  version: string;
+  category: 'core' | 'experimental' | 'plugin';
+  description: string;
+  author?: string;
+  agentdbVersion: string; // Semver range (e.g., "^2.0.0")
+  tags?: string[];
+  estimatedDuration?: number; // milliseconds
+  requiredMemoryMB?: number;
+}
+
+interface AgentDBConfig {
+  profile: 'production' | 'memory' | 'latency' | 'recall' | 'custom';
+  hnsw: { M: number; efConstruction: number; efSearch: number };
+  attention: { heads: number; dimension: number };
+  traversal: { beamWidth: number; strategy: 'greedy' | 'beam' | 'dynamic' };
+  clustering: { algorithm: 'louvain' | 'leiden' | 'spectral'; resolution: number };
+  neural: { mode: 'none' | 'gnn-only' | 'full'; reinforcementLearning: boolean };
+  hypergraph: { enabled: boolean; maxEdgeSize: number };
+  storage: { reportPath: string; autoBackup: boolean };
+  monitoring: { enabled: boolean; alertThresholds: { memoryMB: number; latencyMs: number } };
+}
+
+interface SimulationResult {
+  scenario: string;
+  timestamp: Date;
+  config: AgentDBConfig;
+  metrics: {
+    recall: number;
+    latency: number;
+    throughput: number;
+    memoryUsage: number;
+    [key: string]: any;
+  };
+  insights: string[];
+  recommendations: string[];
+  iterations?: number;
+  duration?: number;
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors?: string[];
+  warnings?: string[];
+}
+```
+
+### Minimal Example
+
+```typescript
+// ~/.agentdb/plugins/my-scenario/index.ts
+import { SimulationScenario, SimulationResult, AgentDBConfig } from 'agentdb';
+
+export const myScenario: SimulationScenario = {
+  metadata: {
+    id: 'my-custom-scenario',
+    name: 'My Custom Scenario',
+    version: '1.0.0',
+    category: 'plugin',
+    description: 'Custom simulation for specific use case',
+    author: 'Your Name',
+    agentdbVersion: '^2.0.0',
+    tags: ['custom', 'experimental'],
+    estimatedDuration: 30000, // 30 seconds
+    requiredMemoryMB: 512
+  },
+
+  async execute(config: AgentDBConfig): Promise<SimulationResult> {
+    // Your simulation logic here
+    console.log('Running custom scenario...');
+
+    // Example: Simulate HNSW search
+    const recall = 0.95;
+    const latency = 120;
+    const throughput = 1000;
+    const memoryUsage = 512;
+
+    return {
+      scenario: this.metadata.id,
+      timestamp: new Date(),
+      config,
+      metrics: {
+        recall,
+        latency,
+        throughput,
+        memoryUsage
+      },
+      insights: [
+        'Custom insight 1: Performance is optimal',
+        'Custom insight 2: Memory usage is within bounds'
+      ],
+      recommendations: [
+        'Try increasing M parameter for better recall',
+        'Consider enabling neural augmentation'
+      ],
+      iterations: 1,
+      duration: 25000
+    };
+  },
+
+  validate(config: AgentDBConfig): ValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // Custom validation logic
+    if (config.hnsw.M < 16) {
+      errors.push('M must be at least 16 for this scenario');
+    }
+
+    if (config.neural.mode === 'none') {
+      warnings.push('Neural mode recommended for best results');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : undefined,
+      warnings: warnings.length > 0 ? warnings : undefined
+    };
+  },
+
+  async cleanup(): Promise<void> {
+    // Optional cleanup logic
+    console.log('Cleaning up custom scenario...');
+  }
+};
+
+export default myScenario;
+```
+
+### Advanced Example with Progress Tracking
+
+```typescript
+import { SimulationScenario, SimulationResult, AgentDBConfig } from 'agentdb';
+import { EventEmitter } from 'events';
+
+export class AdvancedScenario extends EventEmitter implements SimulationScenario {
+  metadata = {
+    id: 'advanced-scenario',
+    name: 'Advanced Scenario',
+    version: '1.0.0',
+    category: 'plugin' as const,
+    description: 'Advanced simulation with progress tracking',
+    agentdbVersion: '^2.0.0',
+    estimatedDuration: 60000,
+    requiredMemoryMB: 1024
+  };
+
+  async execute(config: AgentDBConfig): Promise<SimulationResult> {
+    const totalIterations = 100;
+    const metrics = {
+      recall: 0,
+      latency: 0,
+      throughput: 0,
+      memoryUsage: 0
+    };
+
+    for (let i = 0; i < totalIterations; i++) {
+      // Simulate work
+      await this.simulateIteration(i, config);
+
+      // Emit progress
+      this.emit('progress', {
+        iteration: i + 1,
+        total: totalIterations,
+        percent: ((i + 1) / totalIterations) * 100
+      });
+
+      // Update metrics
+      metrics.recall += Math.random() * 0.01;
+      metrics.latency += Math.random() * 5;
+    }
+
+    metrics.recall /= totalIterations;
+    metrics.latency /= totalIterations;
+    metrics.throughput = 1000 / (metrics.latency / 1000);
+    metrics.memoryUsage = process.memoryUsage().heapUsed / 1024 / 1024;
+
+    return {
+      scenario: this.metadata.id,
+      timestamp: new Date(),
+      config,
+      metrics,
+      insights: [
+        `Achieved ${(metrics.recall * 100).toFixed(1)}% recall`,
+        `Average latency: ${metrics.latency.toFixed(2)}ms`
+      ],
+      recommendations: this.generateRecommendations(metrics, config),
+      iterations: totalIterations
+    };
+  }
+
+  private async simulateIteration(iteration: number, config: AgentDBConfig): Promise<void> {
+    // Simulate work with delay
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+
+  private generateRecommendations(metrics: any, config: AgentDBConfig): string[] {
+    const recommendations: string[] = [];
+
+    if (metrics.recall < 0.95) {
+      recommendations.push('Increase beam width to improve recall');
+    }
+
+    if (metrics.latency > 200) {
+      recommendations.push('Reduce efSearch to lower latency');
+    }
+
+    if (metrics.memoryUsage > config.monitoring.alertThresholds.memoryMB) {
+      recommendations.push('Enable memory-constrained profile');
+    }
+
+    return recommendations;
+  }
+}
+
+export default new AdvancedScenario();
+```
+
+---
+
+## Component Interfaces
+
+### SearchStrategy Interface
+
+```typescript
+interface SearchStrategy {
+  name: string;
+
+  // Build index from vectors
+  build(vectors: Vector[]): Promise<void>;
+
+  // Search for k nearest neighbors
+  search(query: Vector, k: number): Promise<SearchResult[]>;
+
+  // Get index statistics
+  getStats(): SearchStats;
+
+  // Optional: Incremental updates
+  insert?(vector: Vector): Promise<void>;
+  delete?(id: string): Promise<void>;
+}
+
+interface Vector {
+  id: string;
+  data: number[];
+  metadata?: Record<string, any>;
+}
+
+interface SearchResult {
+  id: string;
+  distance: number;
+  vector: Vector;
+}
+
+interface SearchStats {
+  totalVectors: number;
+  dimensions: number;
+  indexSize: number; // bytes
+  buildTime: number; // ms
+  avgSearchTime: number; // ms
+}
+```
+
+**Example Implementation**:
+
+```typescript
+class CustomSearchStrategy implements SearchStrategy {
+  name = 'custom-hnsw';
+  private index: Map<string, Vector> = new Map();
+
+  async build(vectors: Vector[]): Promise<void> {
+    const startTime = Date.now();
+
+    for (const vector of vectors) {
+      this.index.set(vector.id, vector);
+    }
+
+    console.log(`Built index in ${Date.now() - startTime}ms`);
+  }
+
+  async search(query: Vector, k: number): Promise<SearchResult[]> {
+    const results: SearchResult[] = [];
+
+    for (const [id, vector] of this.index.entries()) {
+      const distance = this.calculateDistance(query.data, vector.data);
+      results.push({ id, distance, vector });
+    }
+
+    results.sort((a, b) => a.distance - b.distance);
+    return results.slice(0, k);
+  }
+
+  getStats(): SearchStats {
+    return {
+      totalVectors: this.index.size,
+      dimensions: this.index.values().next().value?.data.length || 0,
+      indexSize: 0, // Calculate actual size
+      buildTime: 0,
+      avgSearchTime: 0
+    };
+  }
+
+  private calculateDistance(a: number[], b: number[]): number {
+    // Euclidean distance
+    return Math.sqrt(a.reduce((sum, val, i) => sum + Math.pow(val - b[i], 2), 0));
+  }
+}
+```
+
+### ClusteringAlgorithm Interface
+
+```typescript
+interface ClusteringAlgorithm {
+  name: string;
+
+  // Cluster graph into communities
+  cluster(graph: Graph): Promise<Community[]>;
+
+  // Get modularity score
+  getModularity(): number;
+
+  // Refine clustering
+  refine(): Promise<void>;
+}
+
+interface Graph {
+  nodes: Node[];
+  edges: Edge[];
+}
+
+interface Node {
+  id: string;
+  data?: any;
+}
+
+interface Edge {
+  source: string;
+  target: string;
+  weight?: number;
+}
+
+interface Community {
+  id: string;
+  nodes: string[];
+  modularity: number;
+}
+```
+
+**Example Implementation**:
+
+```typescript
+class CustomClusteringAlgorithm implements ClusteringAlgorithm {
+  name = 'custom-louvain';
+  private communities: Community[] = [];
+  private modularity: number = 0;
+
+  async cluster(graph: Graph): Promise<Community[]> {
+    // Implement Louvain algorithm
+    // (simplified example)
+
+    const communityMap = new Map<string, string[]>();
+
+    for (const node of graph.nodes) {
+      const communityId = `community-${Math.floor(Math.random() * 5)}`;
+
+      if (!communityMap.has(communityId)) {
+        communityMap.set(communityId, []);
+      }
+
+      communityMap.get(communityId)!.push(node.id);
+    }
+
+    this.communities = Array.from(communityMap.entries()).map(([id, nodes]) => ({
+      id,
+      nodes,
+      modularity: this.calculateModularity(graph, nodes)
+    }));
+
+    this.modularity = this.communities.reduce((sum, c) => sum + c.modularity, 0);
+
+    return this.communities;
+  }
+
+  getModularity(): number {
+    return this.modularity;
+  }
+
+  async refine(): Promise<void> {
+    // Implement refinement logic
+  }
+
+  private calculateModularity(graph: Graph, nodes: string[]): number {
+    // Simplified modularity calculation
+    return Math.random() * 0.5;
+  }
+}
+```
+
+### NeuralAugmentation Interface
+
+```typescript
+interface NeuralAugmentation {
+  name: string;
+
+  // Augment features with neural network
+  augment(features: Tensor): Promise<Tensor>;
+
+  // Train neural network
+  train(samples: TrainingSample[]): Promise<void>;
+
+  // Evaluate performance
+  evaluate(): Promise<EvaluationMetrics>;
+}
+
+interface Tensor {
+  shape: number[];
+  data: number[];
+}
+
+interface TrainingSample {
+  input: Tensor;
+  target: Tensor;
+}
+
+interface EvaluationMetrics {
+  accuracy: number;
+  loss: number;
+  f1Score: number;
+}
+```
+
+---
+
+## Plugin System
+
+### Plugin Structure
+
+```
+~/.agentdb/plugins/my-plugin/
+├── index.ts               # Main entry point
+├── metadata.json          # Plugin metadata
+├── package.json           # npm package (optional)
+├── README.md              # Documentation
+└── tests/                 # Tests (optional)
+    └── index.test.ts
+```
+
+### metadata.json
+
+```json
+{
+  "id": "my-custom-plugin",
+  "name": "My Custom Plugin",
+  "version": "1.0.0",
+  "category": "plugin",
+  "description": "Custom plugin for AgentDB",
+  "author": "Your Name <your.email@example.com>",
+  "agentdbVersion": "^2.0.0",
+  "tags": ["custom", "experimental"],
+  "estimatedDuration": 30000,
+  "requiredMemoryMB": 512,
+  "license": "MIT"
+}
+```
+
+### Installing Plugins
+
+```bash
+# Install from directory
+agentdb plugin install ~/.agentdb/plugins/my-plugin
+
+# Install from npm
+agentdb plugin install my-agentdb-plugin
+
+# Install from git
+agentdb plugin install https://github.com/user/my-plugin.git
+```
+
+### Listing Plugins
+
+```bash
+agentdb plugin list
+```
+
+**Output**:
+```
+📦 Installed Plugins:
+
+✓ my-custom-plugin (v1.0.0)
+  Category: plugin
+  Author: Your Name
+  Description: Custom plugin for AgentDB
+
+✓ advanced-scenario (v1.0.0)
+  Category: experimental
+  Author: AgentDB Team
+  Description: Advanced simulation with progress tracking
+```
+
+### Uninstalling Plugins
+
+```bash
+agentdb plugin uninstall my-custom-plugin
+```
+
+---
+
+## Event System
+
+### Available Events
+
+```typescript
+// Simulation lifecycle
+runner.on('start', (scenario: string, config: AgentDBConfig) => {
+  console.log(`Starting ${scenario}...`);
+});
+
+runner.on('progress', (progress: ProgressUpdate) => {
+  console.log(`Progress: ${progress.percent.toFixed(1)}%`);
+});
+
+runner.on('complete', (result: SimulationResult) => {
+  console.log(`Completed with recall: ${result.metrics.recall}`);
+});
+
+runner.on('error', (error: Error) => {
+  console.error(`Error: ${error.message}`);
+});
+
+runner.on('cancelled', () => {
+  console.log('Simulation cancelled');
+});
+
+// Health monitoring
+monitor.on('alert', (alert: Alert) => {
+  console.warn(`Alert: ${alert.message}`);
+});
+
+monitor.on('metrics', (metrics: HealthMetrics) => {
+  console.log(`Memory: ${metrics.memory.heapUsed.toFixed(0)}MB`);
+});
+
+monitor.on('healing', (action: HealingAction) => {
+  console.log(`Self-healing: ${action.type}`);
+});
+
+// Registry events
+registry.on('scenario-discovered', (scenario: SimulationScenario) => {
+  console.log(`Discovered: ${scenario.metadata.name}`);
+});
+
+registry.on('plugin-registered', (plugin: SimulationScenario) => {
+  console.log(`Registered plugin: ${plugin.metadata.name}`);
+});
+```
+
+### Custom Event Emitters
+
+```typescript
+class CustomScenario extends EventEmitter implements SimulationScenario {
+  async execute(config: AgentDBConfig): Promise<SimulationResult> {
+    // Emit custom events
+    this.emit('custom-event', { data: 'example' });
+
+    // Emit progress
+    for (let i = 0; i < 100; i++) {
+      this.emit('progress', {
+        iteration: i,
+        total: 100,
+        percent: (i / 100) * 100
+      });
+
+      await this.simulateWork();
+    }
+
+    return {
+      scenario: this.metadata.id,
+      timestamp: new Date(),
+      config,
+      metrics: { recall: 0.95, latency: 100, throughput: 1000, memoryUsage: 512 },
+      insights: [],
+      recommendations: []
+    };
+  }
+
+  private async simulateWork(): Promise<void> {
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+}
+```
+
+---
+
+## Code Examples
+
+### Example 1: HNSW Optimization Plugin
+
+```typescript
+// ~/.agentdb/plugins/hnsw-optimizer/index.ts
+import { SimulationScenario, SimulationResult, AgentDBConfig } from 'agentdb';
+
+export const hnswOptimizer: SimulationScenario = {
+  metadata: {
+    id: 'hnsw-optimizer',
+    name: 'HNSW Optimizer',
+    version: '1.0.0',
+    category: 'plugin',
+    description: 'Find optimal HNSW parameters for your dataset',
+    agentdbVersion: '^2.0.0',
+    tags: ['hnsw', 'optimization'],
+    estimatedDuration: 120000,
+    requiredMemoryMB: 2048
+  },
+
+  async execute(config: AgentDBConfig): Promise<SimulationResult> {
+    const results: Array<{ M: number; recall: number; latency: number }> = [];
+
+    // Test different M values
+    for (let M = 8; M <= 64; M += 8) {
+      const recall = await this.testHNSW(M, config.hnsw.efConstruction, config.hnsw.efSearch);
+      const latency = await this.measureLatency(M, config.hnsw.efSearch);
+
+      results.push({ M, recall, latency });
+    }
+
+    // Find optimal M (best recall with latency < threshold)
+    const optimal = results
+      .filter(r => r.latency < config.monitoring.alertThresholds.latencyMs)
+      .sort((a, b) => b.recall - a.recall)[0];
+
+    return {
+      scenario: this.metadata.id,
+      timestamp: new Date(),
+      config,
+      metrics: {
+        recall: optimal.recall,
+        latency: optimal.latency,
+        throughput: 1000 / (optimal.latency / 1000),
+        memoryUsage: process.memoryUsage().heapUsed / 1024 / 1024,
+        optimalM: optimal.M
+      },
+      insights: [
+        `Optimal M found: ${optimal.M}`,
+        `Achieves ${(optimal.recall * 100).toFixed(1)}% recall`,
+        `Latency: ${optimal.latency.toFixed(2)}ms`
+      ],
+      recommendations: [
+        `Set hnsw.M to ${optimal.M} for best results`,
+        `This provides ${((optimal.recall - config.hnsw.M / 100) * 100).toFixed(1)}% better recall`
+      ]
+    };
+  },
+
+  private async testHNSW(M: number, efConstruction: number, efSearch: number): Promise<number> {
+    // Implement HNSW testing logic
+    return 0.9 + (M / 100) * 0.08; // Simplified
+  },
+
+  private async measureLatency(M: number, efSearch: number): Promise<number> {
+    // Implement latency measurement
+    return 100 + M * 2; // Simplified
+  }
+};
+
+export default hnswOptimizer;
+```
+
+### Example 2: A/B Testing Plugin
+
+```typescript
+// ~/.agentdb/plugins/ab-testing/index.ts
+import { SimulationScenario, SimulationResult, AgentDBConfig } from 'agentdb';
+import { ReportStore } from 'agentdb/cli/lib/report-store';
+
+export class ABTestingScenario implements SimulationScenario {
+  metadata = {
+    id: 'ab-testing',
+    name: 'A/B Testing',
+    version: '1.0.0',
+    category: 'plugin' as const,
+    description: 'Compare two configurations automatically',
+    agentdbVersion: '^2.0.0',
+    estimatedDuration: 60000
+  };
+
+  async execute(config: AgentDBConfig): Promise<SimulationResult> {
+    // Configuration A (current)
+    const resultA = await this.runConfiguration(config, 'A');
+
+    // Configuration B (alternative with higher M)
+    const configB = { ...config, hnsw: { ...config.hnsw, M: config.hnsw.M + 16 } };
+    const resultB = await this.runConfiguration(configB, 'B');
+
+    // Statistical significance test
+    const pValue = this.calculatePValue(resultA.recall, resultB.recall);
+    const significant = pValue < 0.05;
+
+    const winner = resultB.recall > resultA.recall ? 'B' : 'A';
+
+    return {
+      scenario: this.metadata.id,
+      timestamp: new Date(),
+      config,
+      metrics: {
+        recall: Math.max(resultA.recall, resultB.recall),
+        latency: winner === 'A' ? resultA.latency : resultB.latency,
+        throughput: winner === 'A' ? resultA.throughput : resultB.throughput,
+        memoryUsage: process.memoryUsage().heapUsed / 1024 / 1024,
+        pValue,
+        winner: winner === 'A' ? 0 : 1
+      },
+      insights: [
+        `Configuration ${winner} wins with ${significant ? 'significant' : 'insignificant'} improvement`,
+        `p-value: ${pValue.toFixed(4)}`,
+        `Recall improvement: ${((resultB.recall - resultA.recall) * 100).toFixed(2)}%`
+      ],
+      recommendations: winner === 'B' ? [
+        `Switch to configuration B (M=${configB.hnsw.M})`,
+        `Expected improvement: ${((resultB.recall - resultA.recall) * 100).toFixed(1)}%`
+      ] : [
+        'Current configuration is optimal'
+      ]
+    };
+  }
+
+  private async runConfiguration(config: AgentDBConfig, variant: string): Promise<any> {
+    // Run simulation with configuration
+    // (simplified example)
+    return {
+      recall: 0.92 + Math.random() * 0.05,
+      latency: 100 + Math.random() * 50,
+      throughput: 1000
+    };
+  }
+
+  private calculatePValue(recallA: number, recallB: number): number {
+    // Simplified p-value calculation
+    const diff = Math.abs(recallB - recallA);
+    return Math.max(0.01, 0.5 - diff * 2);
+  }
+}
+
+export default new ABTestingScenario();
+```
+
+---
+
+## Testing Plugins
+
+### Unit Tests
+
+```typescript
+// ~/.agentdb/plugins/my-plugin/tests/index.test.ts
+import { describe, it, expect } from 'vitest';
+import myPlugin from '../index';
+
+describe('My Plugin', () => {
+  it('should have valid metadata', () => {
+    expect(myPlugin.metadata.id).toBe('my-plugin');
+    expect(myPlugin.metadata.version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+
+  it('should execute successfully', async () => {
+    const config = createMockConfig();
+    const result = await myPlugin.execute(config);
+
+    expect(result.metrics.recall).toBeGreaterThan(0);
+    expect(result.metrics.latency).toBeGreaterThan(0);
+  });
+
+  it('should validate configuration', () => {
+    const config = createMockConfig();
+    const validation = myPlugin.validate!(config);
+
+    expect(validation.valid).toBe(true);
+  });
+});
+
+function createMockConfig(): any {
+  return {
+    profile: 'production',
+    hnsw: { M: 32, efConstruction: 200, efSearch: 100 },
+    // ... other fields
+  };
+}
+```
+
+---
+
+## Publishing Plugins
+
+### npm Package
+
+```json
+// package.json
+{
+  "name": "agentdb-plugin-myname",
+  "version": "1.0.0",
+  "description": "My custom AgentDB plugin",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": ["agentdb", "plugin", "simulation"],
+  "peerDependencies": {
+    "agentdb": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest"
+  }
+}
+```
+
+### Publishing
+
+```bash
+npm publish
+```
+
+### Installing Published Plugin
+
+```bash
+npm install -g agentdb-plugin-myname
+agentdb plugin install agentdb-plugin-myname
+```
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-30
+**Maintainer**: AgentDB Team