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

package/src/utils/LegacyAttentionAdapter.ts

@@ -0,0 +1,393 @@
+/**
+ * LegacyAttentionAdapter - Compatibility layer for deprecated services/AttentionService
+ *
+ * This module re-exports the legacy config types and provides a backward-compatible
+ * AttentionService class that delegates to the production controllers/AttentionService.
+ *
+ * Created as part of ADR-056: consolidation of services/AttentionService into controllers.
+ *
+ * @module LegacyAttentionAdapter
+ */
+
+import { AttentionService as ControllersAttentionService } from '../controllers/AttentionService.js';
+import type { AttentionResult } from '../controllers/AttentionService.js';
+
+// Database type placeholder (matches legacy pattern)
+type Database = any;
+
+// ========================================================================
+// Legacy Config Types (previously in services/AttentionService.ts)
+// ========================================================================
+
+export interface HyperbolicAttentionConfig {
+  enabled: boolean;
+  curvature?: number;
+  dimension?: number;
+  temperature?: number;
+}
+
+export interface FlashAttentionConfig {
+  enabled: boolean;
+  blockSize?: number;
+  useSIMD?: boolean;
+  maxSeqLen?: number;
+}
+
+export interface GraphRoPEConfig {
+  enabled: boolean;
+  maxHops?: number;
+  rotaryDim?: number;
+  baseFreq?: number;
+}
+
+export interface MoEAttentionConfig {
+  enabled: boolean;
+  numExperts?: number;
+  topK?: number;
+  expertDomains?: string[];
+}
+
+// Legacy result types
+export interface HyperbolicAttentionResult {
+  attended: Float32Array;
+  weights: Float32Array;
+  distances: number[];
+  metrics: {
+    computeTimeMs: number;
+    memoryUsedMB: number;
+  };
+}
+
+export interface FlashAttentionResult {
+  output: Float32Array;
+  scores?: Float32Array;
+  metrics: {
+    computeTimeMs: number;
+    peakMemoryMB: number;
+    blocksProcessed: number;
+  };
+}
+
+export interface GraphRoPEResult {
+  queries: Float32Array;
+  keys: Float32Array;
+  hopEncodings: Float32Array;
+  metrics: {
+    computeTimeMs: number;
+  };
+}
+
+// ========================================================================
+// Legacy AttentionService Adapter
+// ========================================================================
+
+/**
+ * Backward-compatible AttentionService that delegates to the production
+ * controllers/AttentionService while maintaining the legacy constructor
+ * and method signatures used by ExplainableRecall, NightlyLearner, and
+ * CausalMemoryGraph.
+ */
+export class AttentionService {
+  private delegate: ControllersAttentionService;
+  private hyperbolicConfig: HyperbolicAttentionConfig;
+  private flashConfig: FlashAttentionConfig;
+  private graphRoPEConfig: GraphRoPEConfig;
+
+  constructor(
+    _db: Database,
+    configs?: {
+      hyperbolic?: Partial<HyperbolicAttentionConfig>;
+      flash?: Partial<FlashAttentionConfig>;
+      graphRoPE?: Partial<GraphRoPEConfig>;
+      moe?: Partial<MoEAttentionConfig>;
+    }
+  ) {
+    this.hyperbolicConfig = {
+      enabled: false,
+      curvature: 1.0,
+      dimension: 384,
+      temperature: 1.0,
+      ...configs?.hyperbolic,
+    };
+
+    this.flashConfig = {
+      enabled: false,
+      blockSize: 256,
+      useSIMD: true,
+      maxSeqLen: 4096,
+      ...configs?.flash,
+    };
+
+    this.graphRoPEConfig = {
+      enabled: false,
+      maxHops: 10,
+      rotaryDim: 64,
+      baseFreq: 10000,
+      ...configs?.graphRoPE,
+    };
+
+    const dim = this.hyperbolicConfig.dimension ?? 384;
+    this.delegate = new ControllersAttentionService({
+      numHeads: 1,
+      headDim: dim,
+      embedDim: dim,
+      useFlash: this.flashConfig.enabled,
+      useHyperbolic: this.hyperbolicConfig.enabled,
+    });
+  }
+
+  async hyperbolicAttention(
+    queries: Float32Array,
+    keys: Float32Array,
+    values: Float32Array,
+    hierarchyLevels: number[]
+  ): Promise<HyperbolicAttentionResult> {
+    const startTime = Date.now();
+    const dim = this.hyperbolicConfig.dimension ?? 384;
+    const numKeys = keys.length / dim;
+
+    try {
+      const result: AttentionResult = await this.delegate.hyperbolicAttention(
+        queries,
+        keys,
+        values,
+        this.hyperbolicConfig.curvature ?? 1.0
+      );
+
+      const weights = result.weights ?? new Float32Array(numKeys);
+      const distances = hierarchyLevels.slice(0, numKeys);
+
+      return {
+        attended: result.output,
+        weights,
+        distances,
+        metrics: {
+          computeTimeMs: result.executionTimeMs ?? (Date.now() - startTime),
+          memoryUsedMB: (result.output.byteLength + weights.byteLength) / (1024 * 1024),
+        },
+      };
+    } catch {
+      // Fallback: simple hierarchical attention
+      return this.fallbackHyperbolicAttention(queries, keys, values, hierarchyLevels, startTime);
+    }
+  }
+
+  async flashAttention(
+    queries: Float32Array,
+    keys: Float32Array,
+    values: Float32Array
+  ): Promise<FlashAttentionResult> {
+    const startTime = Date.now();
+
+    try {
+      const result: AttentionResult = await this.delegate.flashAttention(
+        queries,
+        keys,
+        values
+      );
+
+      return {
+        output: result.output,
+        metrics: {
+          computeTimeMs: result.executionTimeMs ?? (Date.now() - startTime),
+          peakMemoryMB: result.output.byteLength / (1024 * 1024),
+          blocksProcessed: 1,
+        },
+      };
+    } catch {
+      // Fallback: chunked attention
+      return this.fallbackFlashAttention(queries, keys, values, startTime);
+    }
+  }
+
+  async graphRoPE(
+    queries: Float32Array,
+    keys: Float32Array,
+    hopDistances: number[][]
+  ): Promise<GraphRoPEResult> {
+    const startTime = Date.now();
+    // GraphRoPE is not in the controllers version; use fallback
+    return this.fallbackGraphRoPE(queries, keys, hopDistances, startTime);
+  }
+
+  // ========================================================================
+  // Fallback implementations (preserved from deprecated services version)
+  // ========================================================================
+
+  private fallbackHyperbolicAttention(
+    queries: Float32Array,
+    keys: Float32Array,
+    values: Float32Array,
+    hierarchyLevels: number[],
+    startTime: number
+  ): HyperbolicAttentionResult {
+    const dim = this.hyperbolicConfig.dimension!;
+    const numQueries = queries.length / dim;
+    const numKeys = keys.length / dim;
+
+    const scores = new Float32Array(numQueries * numKeys);
+    const distances: number[] = [];
+
+    for (let i = 0; i < numQueries; i++) {
+      for (let j = 0; j < numKeys; j++) {
+        let score = 0;
+        for (let d = 0; d < dim; d++) {
+          score += queries[i * dim + d] * keys[j * dim + d];
+        }
+        const hierarchyScale = Math.exp(-hierarchyLevels[j] * 0.5);
+        score *= hierarchyScale;
+        scores[i * numKeys + j] = score;
+        distances.push(hierarchyLevels[j]);
+      }
+    }
+
+    const weights = this.softmax(scores, numQueries, numKeys);
+
+    const attended = new Float32Array(numQueries * dim);
+    for (let i = 0; i < numQueries; i++) {
+      for (let j = 0; j < numKeys; j++) {
+        const weight = weights[i * numKeys + j];
+        for (let d = 0; d < dim; d++) {
+          attended[i * dim + d] += weight * values[j * dim + d];
+        }
+      }
+    }
+
+    return {
+      attended,
+      weights,
+      distances,
+      metrics: {
+        computeTimeMs: Date.now() - startTime,
+        memoryUsedMB: (attended.byteLength + weights.byteLength) / (1024 * 1024),
+      },
+    };
+  }
+
+  private fallbackFlashAttention(
+    queries: Float32Array,
+    keys: Float32Array,
+    values: Float32Array,
+    startTime: number
+  ): FlashAttentionResult {
+    const dim = 384;
+    const numQueries = queries.length / dim;
+    const numKeys = keys.length / dim;
+    const blockSize = this.flashConfig.blockSize!;
+
+    const output = new Float32Array(numQueries * dim);
+    let blocksProcessed = 0;
+    let peakMemory = 0;
+
+    for (let qStart = 0; qStart < numQueries; qStart += blockSize) {
+      const qEnd = Math.min(qStart + blockSize, numQueries);
+
+      for (let kStart = 0; kStart < numKeys; kStart += blockSize) {
+        const kEnd = Math.min(kStart + blockSize, numKeys);
+
+        const blockScores = new Float32Array((qEnd - qStart) * (kEnd - kStart));
+
+        for (let i = qStart; i < qEnd; i++) {
+          for (let j = kStart; j < kEnd; j++) {
+            let score = 0;
+            for (let d = 0; d < dim; d++) {
+              score += queries[i * dim + d] * keys[j * dim + d];
+            }
+            blockScores[(i - qStart) * (kEnd - kStart) + (j - kStart)] = score;
+          }
+        }
+
+        const blockWeights = this.softmax(blockScores, qEnd - qStart, kEnd - kStart);
+
+        for (let i = qStart; i < qEnd; i++) {
+          for (let j = kStart; j < kEnd; j++) {
+            const weight = blockWeights[(i - qStart) * (kEnd - kStart) + (j - kStart)];
+            for (let d = 0; d < dim; d++) {
+              output[i * dim + d] += weight * values[j * dim + d];
+            }
+          }
+        }
+
+        peakMemory = Math.max(peakMemory, blockScores.byteLength + blockWeights.byteLength);
+        blocksProcessed++;
+      }
+    }
+
+    return {
+      output,
+      metrics: {
+        computeTimeMs: Date.now() - startTime,
+        peakMemoryMB: peakMemory / (1024 * 1024),
+        blocksProcessed,
+      },
+    };
+  }
+
+  private fallbackGraphRoPE(
+    queries: Float32Array,
+    keys: Float32Array,
+    hopDistances: number[][],
+    startTime: number
+  ): GraphRoPEResult {
+    const dim = 384;
+    const numQueries = queries.length / dim;
+    const numKeys = keys.length / dim;
+
+    const encodedQueries = new Float32Array(queries);
+    const encodedKeys = new Float32Array(keys);
+    const hopEncodings = new Float32Array(numQueries * numKeys);
+
+    for (let i = 0; i < numQueries; i++) {
+      for (let j = 0; j < numKeys; j++) {
+        const distance = hopDistances[i]?.[j] || 0;
+        const scale = 1.0 / (1.0 + distance);
+        hopEncodings[i * numKeys + j] = scale;
+
+        for (let d = 0; d < dim; d++) {
+          encodedQueries[i * dim + d] *= Math.sqrt(scale);
+          encodedKeys[j * dim + d] *= Math.sqrt(scale);
+        }
+      }
+    }
+
+    return {
+      queries: encodedQueries,
+      keys: encodedKeys,
+      hopEncodings,
+      metrics: {
+        computeTimeMs: Date.now() - startTime,
+      },
+    };
+  }
+
+  private softmax(scores: Float32Array, rows: number, cols: number): Float32Array {
+    const result = new Float32Array(scores.length);
+
+    for (let i = 0; i < rows; i++) {
+      let max = -Infinity;
+      for (let j = 0; j < cols; j++) {
+        max = Math.max(max, scores[i * cols + j]);
+      }
+
+      let sum = 0;
+      for (let j = 0; j < cols; j++) {
+        result[i * cols + j] = Math.exp(scores[i * cols + j] - max);
+        sum += result[i * cols + j];
+      }
+
+      for (let j = 0; j < cols; j++) {
+        result[i * cols + j] /= sum;
+      }
+    }
+
+    return result;
+  }
+
+  getConfig() {
+    return {
+      hyperbolic: this.hyperbolicConfig,
+      flash: this.flashConfig,
+      graphRoPE: this.graphRoPEConfig,
+    };
+  }
+}

package/src/utils/NodeIdMapper.ts

@@ -0,0 +1,64 @@
+/**
+ * NodeIdMapper - Maps numeric episode IDs to full graph node IDs
+ *
+ * Solves the issue where ReflexionMemory.storeEpisode() returns numeric IDs
+ * but GraphDatabaseAdapter edges need full string node IDs (e.g., "episode-123456")
+ */
+
+export class NodeIdMapper {
+  private static instance: NodeIdMapper | null = null;
+  private numericToNode = new Map<number, string>();
+  private nodeToNumeric = new Map<string, number>();
+
+  private constructor() {
+    // Private constructor for singleton pattern
+  }
+
+  static getInstance(): NodeIdMapper {
+    if (!NodeIdMapper.instance) {
+      NodeIdMapper.instance = new NodeIdMapper();
+    }
+    return NodeIdMapper.instance;
+  }
+
+  /**
+   * Register a mapping between numeric ID and full node ID
+   */
+  register(numericId: number, nodeId: string): void {
+    this.numericToNode.set(numericId, nodeId);
+    this.nodeToNumeric.set(nodeId, numericId);
+  }
+
+  /**
+   * Get full node ID from numeric ID
+   */
+  getNodeId(numericId: number): string | undefined {
+    return this.numericToNode.get(numericId);
+  }
+
+  /**
+   * Get numeric ID from full node ID
+   */
+  getNumericId(nodeId: string): number | undefined {
+    return this.nodeToNumeric.get(nodeId);
+  }
+
+  /**
+   * Clear all mappings (useful for testing)
+   */
+  clear(): void {
+    this.numericToNode.clear();
+    this.nodeToNumeric.clear();
+  }
+
+  /**
+   * Get statistics about mappings
+   */
+  getStats(): { totalMappings: number; numericIds: number; nodeIds: number } {
+    return {
+      totalMappings: this.numericToNode.size,
+      numericIds: this.numericToNode.size,
+      nodeIds: this.nodeToNumeric.size
+    };
+  }
+}

package/src/utils/attention-metrics.ts

@@ -0,0 +1,253 @@
+/**
+ * Performance Metrics and Monitoring for Attention Mechanisms
+ * Real-time tracking of latency, throughput, and memory usage
+ */
+
+export interface AttentionMetrics {
+  mechanism: string;
+  operationCount: number;
+  totalLatencyMs: number;
+  avgLatencyUs: number;
+  minLatencyUs: number;
+  maxLatencyUs: number;
+  p50LatencyUs: number;
+  p95LatencyUs: number;
+  p99LatencyUs: number;
+  throughputOpsPerSec: number;
+  memoryUsageBytes: number;
+  peakMemoryBytes: number;
+  allocationCount: number;
+}
+
+export interface OperationMetrics {
+  startTime: number;
+  endTime: number;
+  latencyUs: number;
+  memoryBefore: number;
+  memoryAfter: number;
+  memoryDelta: number;
+}
+
+export class AttentionMetricsCollector {
+  private metrics: Map<string, OperationMetrics[]> = new Map();
+  private startMemory: Map<string, number> = new Map();
+
+  /**
+   * Start measuring an operation
+   */
+  startOperation(mechanism: string): void {
+    const memoryBefore = process.memoryUsage().heapUsed;
+    this.startMemory.set(mechanism, memoryBefore);
+  }
+
+  /**
+   * End measuring an operation and record metrics
+   */
+  endOperation(mechanism: string, startTime: number): void {
+    const endTime = performance.now();
+    const memoryBefore = this.startMemory.get(mechanism) || 0;
+    const memoryAfter = process.memoryUsage().heapUsed;
+
+    const operationMetrics: OperationMetrics = {
+      startTime,
+      endTime,
+      latencyUs: (endTime - startTime) * 1000, // Convert ms to µs
+      memoryBefore,
+      memoryAfter,
+      memoryDelta: memoryAfter - memoryBefore,
+    };
+
+    if (!this.metrics.has(mechanism)) {
+      this.metrics.set(mechanism, []);
+    }
+    this.metrics.get(mechanism)!.push(operationMetrics);
+    this.startMemory.delete(mechanism);
+  }
+
+  /**
+   * Get aggregated metrics for a mechanism
+   */
+  getMetrics(mechanism: string): AttentionMetrics | null {
+    const operations = this.metrics.get(mechanism);
+    if (!operations || operations.length === 0) {
+      return null;
+    }
+
+    const latencies = operations.map(op => op.latencyUs).sort((a, b) => a - b);
+    const memoryDeltas = operations.map(op => op.memoryDelta);
+    const totalLatencyMs = latencies.reduce((sum, lat) => sum + lat, 0) / 1000;
+    const totalTimeMs = operations[operations.length - 1].endTime - operations[0].startTime;
+
+    // Calculate percentiles
+    const p50Index = Math.floor(latencies.length * 0.5);
+    const p95Index = Math.floor(latencies.length * 0.95);
+    const p99Index = Math.floor(latencies.length * 0.99);
+
+    return {
+      mechanism,
+      operationCount: operations.length,
+      totalLatencyMs,
+      avgLatencyUs: latencies.reduce((sum, lat) => sum + lat, 0) / latencies.length,
+      minLatencyUs: latencies[0],
+      maxLatencyUs: latencies[latencies.length - 1],
+      p50LatencyUs: latencies[p50Index],
+      p95LatencyUs: latencies[p95Index],
+      p99LatencyUs: latencies[p99Index],
+      throughputOpsPerSec: totalTimeMs > 0 ? (operations.length / totalTimeMs) * 1000 : 0,
+      memoryUsageBytes: operations[operations.length - 1].memoryAfter,
+      peakMemoryBytes: Math.max(...operations.map(op => op.memoryAfter)),
+      allocationCount: memoryDeltas.filter(delta => delta > 0).length,
+    };
+  }
+
+  /**
+   * Get all collected metrics
+   */
+  getAllMetrics(): Map<string, AttentionMetrics> {
+    const allMetrics = new Map<string, AttentionMetrics>();
+    for (const mechanism of this.metrics.keys()) {
+      const metrics = this.getMetrics(mechanism);
+      if (metrics) {
+        allMetrics.set(mechanism, metrics);
+      }
+    }
+    return allMetrics;
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.metrics.clear();
+    this.startMemory.clear();
+  }
+
+  /**
+   * Export metrics as JSON
+   */
+  exportJSON(): string {
+    const allMetrics: Record<string, AttentionMetrics> = {};
+    for (const [mechanism, metrics] of this.getAllMetrics()) {
+      allMetrics[mechanism] = metrics;
+    }
+    return JSON.stringify(allMetrics, null, 2);
+  }
+
+  /**
+   * Export metrics in markdown format
+   */
+  exportMarkdown(): string {
+    const lines: string[] = [
+      '# Attention Mechanism Performance Metrics',
+      '',
+      '## Summary',
+      '',
+      '| Mechanism | Ops | Avg Latency (µs) | P95 (µs) | P99 (µs) | Throughput (ops/s) | Memory (MB) |',
+      '|-----------|-----|------------------|----------|----------|-------------------|-------------|',
+    ];
+
+    for (const [mechanism, metrics] of this.getAllMetrics()) {
+      lines.push(
+        `| ${mechanism} | ${metrics.operationCount} | ${metrics.avgLatencyUs.toFixed(2)} | ${metrics.p95LatencyUs.toFixed(2)} | ${metrics.p99LatencyUs.toFixed(2)} | ${metrics.throughputOpsPerSec.toFixed(2)} | ${(metrics.memoryUsageBytes / 1024 / 1024).toFixed(2)} |`
+      );
+    }
+
+    lines.push('', '## Detailed Metrics', '');
+
+    for (const [mechanism, metrics] of this.getAllMetrics()) {
+      lines.push(
+        `### ${mechanism}`,
+        '',
+        `- **Operations**: ${metrics.operationCount}`,
+        `- **Total Latency**: ${metrics.totalLatencyMs.toFixed(2)} ms`,
+        `- **Average Latency**: ${metrics.avgLatencyUs.toFixed(2)} µs`,
+        `- **Min Latency**: ${metrics.minLatencyUs.toFixed(2)} µs`,
+        `- **Max Latency**: ${metrics.maxLatencyUs.toFixed(2)} µs`,
+        `- **P50 Latency**: ${metrics.p50LatencyUs.toFixed(2)} µs`,
+        `- **P95 Latency**: ${metrics.p95LatencyUs.toFixed(2)} µs`,
+        `- **P99 Latency**: ${metrics.p99LatencyUs.toFixed(2)} µs`,
+        `- **Throughput**: ${metrics.throughputOpsPerSec.toFixed(2)} ops/sec`,
+        `- **Memory Usage**: ${(metrics.memoryUsageBytes / 1024 / 1024).toFixed(2)} MB`,
+        `- **Peak Memory**: ${(metrics.peakMemoryBytes / 1024 / 1024).toFixed(2)} MB`,
+        `- **Allocations**: ${metrics.allocationCount}`,
+        ''
+      );
+    }
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Global metrics collector instance
+ */
+export const metricsCollector = new AttentionMetricsCollector();
+
+/**
+ * Decorator for measuring function performance
+ */
+export function measurePerformance(mechanism: string) {
+  return function (
+    target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: any[]) {
+      metricsCollector.startOperation(mechanism);
+      const startTime = performance.now();
+
+      try {
+        const result = await originalMethod.apply(this, args);
+        metricsCollector.endOperation(mechanism, startTime);
+        return result;
+      } catch (error) {
+        metricsCollector.endOperation(mechanism, startTime);
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Helper to measure a synchronous operation
+ */
+export function measureSync<T>(
+  mechanism: string,
+  operation: () => T
+): T {
+  metricsCollector.startOperation(mechanism);
+  const startTime = performance.now();
+
+  try {
+    const result = operation();
+    metricsCollector.endOperation(mechanism, startTime);
+    return result;
+  } catch (error) {
+    metricsCollector.endOperation(mechanism, startTime);
+    throw error;
+  }
+}
+
+/**
+ * Helper to measure an async operation
+ */
+export async function measureAsync<T>(
+  mechanism: string,
+  operation: () => Promise<T>
+): Promise<T> {
+  metricsCollector.startOperation(mechanism);
+  const startTime = performance.now();
+
+  try {
+    const result = await operation();
+    metricsCollector.endOperation(mechanism, startTime);
+    return result;
+  } catch (error) {
+    metricsCollector.endOperation(mechanism, startTime);
+    throw error;
+  }
+}