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

package/simulation/scenarios/domain-examples/medical-imaging.ts

@@ -0,0 +1,181 @@
+/**
+ * Medical Imaging: High-Precision Image Similarity Search
+ *
+ * Use Case: Medical diagnosis requires highest possible accuracy
+ * for similar case retrieval and diagnostic assistance.
+ *
+ * Optimization Priority: RECALL/PRECISION (latency trade-off acceptable)
+ */
+
+import { UnifiedMetrics } from '../../types';
+
+export const MEDICAL_ATTENTION_CONFIG = {
+  heads: 16,                       // More heads = better quality (vs 8-head optimal)
+  forwardPassTargetMs: 50,         // 50ms acceptable (diagnostic aid, not real-time)
+  batchSize: 32,                   // Batch processing for efficiency
+  precision: 'float32' as const,   // Full precision (medical data critical)
+  ensembleSize: 3,                 // 3-model ensemble for robustness
+
+  // High-recall configuration
+  recallTarget: 0.99,              // 99% recall required (vs 96.8% general)
+  precisionTarget: 0.95,           // 95% precision required
+
+  // Self-healing with medical data integrity
+  selfHealing: {
+    enabled: true,
+    adaptationIntervalMs: 1000,    // 1s monitoring (less critical than trading)
+    degradationThreshold: 0.01,    // 1% tolerance (strict for medical)
+    dataIntegrityChecks: true      // Verify data quality
+  }
+};
+
+// Medical-specific metrics
+export interface MedicalMetrics extends UnifiedMetrics {
+  recallAt100: number;             // Recall@100 (retrieve more candidates)
+  precisionAt10: number;           // Precision@10 (top results critical)
+  diagnosticAgreement: number;     // Agreement with expert diagnosis
+  falseNegativeRate: number;       // Critical for medical (missed diagnoses)
+  dataIntegrityScore: number;      // DICOM compliance, quality checks
+}
+
+// Similar case interface
+export interface SimilarCase {
+  caseId: string;
+  diagnosis: string;
+  similarity: number;
+  radiologistNotes: string;
+  confidence: number;
+}
+
+// Example: Similar case retrieval for diagnosis
+export async function findSimilarCases(
+  patientScan: Float32Array,       // MRI/CT scan embeddings
+  medicalDatabase: any,            // HNSWGraph type
+  applyAttention: (data: Float32Array, config: any) => Promise<Float32Array>,
+  runEnsemble: (data: Float32Array, size: number) => Promise<any[]>,
+  calculateEnsembleConfidence: (candidate: any, ensemble: any[]) => number,
+  minConfidence: number = 0.95
+): Promise<SimilarCase[]> {
+  const config = MEDICAL_ATTENTION_CONFIG;
+
+  // 16-head attention for high-quality embeddings
+  const enhanced = await applyAttention(patientScan, config);
+
+  // High-recall search (k=100 for comprehensive retrieval)
+  const candidates = await medicalDatabase.search(enhanced, 100);
+
+  // Ensemble voting for robustness
+  const ensembleResults = await runEnsemble(patientScan, config.ensembleSize);
+
+  // Filter by confidence threshold
+  return candidates
+    .filter((c: any) => c.score >= minConfidence)
+    .map((c: any) => ({
+      caseId: c.id,
+      diagnosis: c.metadata.diagnosis,
+      similarity: c.score,
+      radiologistNotes: c.metadata.notes,
+      confidence: calculateEnsembleConfidence(c, ensembleResults)
+    }));
+}
+
+// Performance targets for medical imaging
+export const MEDICAL_PERFORMANCE_TARGETS = {
+  recallAt100: 0.99,               // 99% recall (comprehensive retrieval)
+  precisionAt10: 0.95,             // 95% precision (top 10 highly relevant)
+  p50LatencyMs: 50,                // 50ms median (batch processing acceptable)
+  falseNegativeRate: 0.01,         // <1% false negatives (critical)
+  uptimePercent: 99.9              // 99.9% uptime (3 nines)
+};
+
+// Medical imaging modality-specific configurations
+export const MEDICAL_CONFIG_VARIATIONS = {
+  // CT scans (high resolution, more detail needed)
+  ctScans: {
+    ...MEDICAL_ATTENTION_CONFIG,
+    heads: 20,                     // Even more heads for fine detail
+    recallTarget: 0.995,           // 99.5% recall
+    ensembleSize: 5                // Larger ensemble
+  },
+
+  // MRI scans (multiple sequences, complex)
+  mriScans: {
+    ...MEDICAL_ATTENTION_CONFIG,
+    heads: 16,
+    multiSequenceFusion: true,     // Fuse T1, T2, FLAIR, etc.
+    recallTarget: 0.99
+  },
+
+  // X-rays (simpler, faster acceptable)
+  xrays: {
+    ...MEDICAL_ATTENTION_CONFIG,
+    heads: 12,
+    forwardPassTargetMs: 30,       // Faster processing
+    recallTarget: 0.98
+  },
+
+  // Pathology slides (ultra-high resolution)
+  pathology: {
+    ...MEDICAL_ATTENTION_CONFIG,
+    heads: 24,                     // Maximum detail
+    forwardPassTargetMs: 100,      // Allow more time
+    recallTarget: 0.995,
+    hierarchicalProcessing: true   // Process at multiple scales
+  }
+};
+
+// Clinical urgency adaptations
+export function adaptConfigToUrgency(
+  baseConfig: typeof MEDICAL_ATTENTION_CONFIG,
+  urgency: 'routine' | 'urgent' | 'emergency'
+): typeof MEDICAL_ATTENTION_CONFIG {
+  switch (urgency) {
+    case 'routine':
+      return {
+        ...baseConfig,
+        heads: 20,                 // Maximum quality
+        forwardPassTargetMs: 100,  // Allow more time
+        ensembleSize: 5            // Largest ensemble
+      };
+    case 'urgent':
+      return {
+        ...baseConfig,
+        heads: 16,                 // Balanced
+        forwardPassTargetMs: 50
+      };
+    case 'emergency':
+      return {
+        ...baseConfig,
+        heads: 12,                 // Faster, still high quality
+        forwardPassTargetMs: 20,
+        ensembleSize: 1,           // Skip ensemble for speed
+        recallTarget: 0.97         // Slight quality trade-off
+      };
+  }
+}
+
+// Data quality monitoring
+export interface MedicalDataQuality {
+  dicomCompliance: boolean;
+  resolutionAdequate: boolean;
+  contrastQuality: number;
+  artifactScore: number;
+  calibrationValid: boolean;
+}
+
+export function validateMedicalData(scan: any): MedicalDataQuality {
+  return {
+    dicomCompliance: checkDICOMHeaders(scan),
+    resolutionAdequate: checkResolution(scan),
+    contrastQuality: assessContrast(scan),
+    artifactScore: detectArtifacts(scan),
+    calibrationValid: verifyCalibration(scan)
+  };
+}
+
+// Placeholder validation functions
+function checkDICOMHeaders(scan: any): boolean { return true; }
+function checkResolution(scan: any): boolean { return true; }
+function assessContrast(scan: any): number { return 0.95; }
+function detectArtifacts(scan: any): number { return 0.02; }
+function verifyCalibration(scan: any): boolean { return true; }

package/simulation/scenarios/domain-examples/robotics-navigation.ts

@@ -0,0 +1,214 @@
+/**
+ * Robotics Navigation: Adaptive Real-Time Path Planning
+ *
+ * Use Case: Autonomous robots need real-time similarity search
+ * for environment matching and obstacle avoidance.
+ *
+ * Optimization Priority: BALANCED (latency + accuracy)
+ */
+
+import { UnifiedMetrics } from '../../types';
+
+export const ROBOTICS_ATTENTION_CONFIG = {
+  heads: 8,                        // Optimal balance (validated)
+  forwardPassTargetMs: 10,         // 10ms for 100Hz control loop
+  batchSize: 4,                    // Small batches for real-time
+  precision: 'float16' as const,   // Reduced precision for edge devices
+  edgeOptimized: true,             // NVIDIA Jetson, Intel NCS optimization
+
+  // Dynamic attention based on environment complexity
+  dynamicHeads: {
+    enabled: true,
+    simple: 4,                     // 4 heads for simple environments
+    complex: 12,                   // 12 heads for complex scenes
+    adaptationStrategy: 'scene-complexity' as const
+  },
+
+  // Dynamic-k based on navigation context
+  dynamicK: {
+    min: 5,
+    max: 20,
+    adaptationStrategy: 'obstacle-density' as const  // More obstacles = more candidates
+  },
+
+  // Self-healing for continuous operation
+  selfHealing: {
+    enabled: true,
+    adaptationIntervalMs: 100,
+    degradationThreshold: 0.05,
+    hardwareMonitoring: true       // Battery, temperature, GPU
+  }
+};
+
+// Robotics-specific metrics
+export interface RoboticsMetrics extends UnifiedMetrics {
+  controlLoopLatencyMs: number;    // Control loop latency (10ms target)
+  navigationAccuracy: number;      // Path planning accuracy
+  obstacleDetectionRate: number;   // Obstacle detection success rate
+  powerConsumptionW: number;       // Power consumption (battery life)
+  temperatureCelsius: number;      // Hardware temperature monitoring
+}
+
+// Robot context interface
+export interface RobotContext {
+  velocity: number;
+  batteryPercent: number;
+  temperatureCelsius: number;
+  missionCriticality: 'low' | 'medium' | 'high';
+}
+
+// Navigation plan interface
+export interface NavigationPlan {
+  bestMatch: any;
+  suggestedPath: any;
+  confidence: number;
+  latencyMs: number;
+}
+
+// Example: Environment matching for navigation
+export async function matchEnvironment(
+  currentSensorData: Float32Array,  // LIDAR, camera, IMU
+  knownEnvironments: any,           // HNSWGraph type
+  robotContext: RobotContext,
+  applyAttention: (data: Float32Array, config: any) => Promise<Float32Array>,
+  analyzeSceneComplexity: (data: Float32Array) => number,
+  calculateObstacleDensity: (data: Float32Array) => number,
+  computePath: (matches: any[]) => any
+): Promise<NavigationPlan> {
+  const startTime = Date.now();
+  const config = ROBOTICS_ATTENTION_CONFIG;
+
+  // Adaptive attention based on scene complexity
+  const sceneComplexity = analyzeSceneComplexity(currentSensorData);
+  const adaptiveHeads = sceneComplexity > 0.7 ? 12 : 4;
+
+  // Apply attention with adaptive heads
+  const enhanced = await applyAttention(currentSensorData, {
+    ...config,
+    heads: adaptiveHeads
+  });
+
+  // Dynamic-k based on obstacle density
+  const obstacleDensity = calculateObstacleDensity(currentSensorData);
+  const k = Math.round(5 + obstacleDensity * 15);  // 5-20 range
+
+  // Search for similar environments
+  const matches = await knownEnvironments.search(enhanced, k);
+
+  return {
+    bestMatch: matches[0],
+    suggestedPath: computePath(matches),
+    confidence: matches[0].score,
+    latencyMs: Date.now() - startTime  // Track real-time performance
+  };
+}
+
+// Performance targets for robotics
+export const ROBOTICS_PERFORMANCE_TARGETS = {
+  controlLoopLatencyMs: 10,        // 10ms for 100Hz control
+  navigationAccuracy: 0.95,        // 95% path planning accuracy
+  p99LatencyMs: 15,                // 15ms p99 (real-time critical)
+  powerConsumptionW: 20,           // 20W max (battery life)
+  uptimePercent: 99.0              // 99% uptime (2 nines, field operation)
+};
+
+// Robot platform-specific configurations
+export const ROBOTICS_CONFIG_VARIATIONS = {
+  // High-performance robots (Boston Dynamics Spot, ANYmal)
+  highPerformance: {
+    ...ROBOTICS_ATTENTION_CONFIG,
+    heads: 12,
+    forwardPassTargetMs: 5,        // 5ms for 200Hz control
+    precision: 'float32' as const,  // Full precision available
+    powerConsumptionW: 100         // Higher power budget
+  },
+
+  // Consumer drones (DJI, Parrot)
+  consumerDrone: {
+    ...ROBOTICS_ATTENTION_CONFIG,
+    heads: 6,
+    forwardPassTargetMs: 20,       // 50Hz control acceptable
+    precision: 'float16' as const,
+    powerConsumptionW: 15          // Battery constrained
+  },
+
+  // Industrial AGVs (warehouse robots)
+  industrialAGV: {
+    ...ROBOTICS_ATTENTION_CONFIG,
+    heads: 8,
+    forwardPassTargetMs: 15,
+    precision: 'float32' as const,
+    dynamicK: { min: 10, max: 30, adaptationStrategy: 'warehouse-density' as const }
+  },
+
+  // Embedded robots (Raspberry Pi, Arduino)
+  embedded: {
+    ...ROBOTICS_ATTENTION_CONFIG,
+    heads: 4,
+    forwardPassTargetMs: 50,       // Slower acceptable
+    precision: 'int8' as const,    // Quantized for embedded
+    powerConsumptionW: 5           // Very power constrained
+  }
+};
+
+// Environment adaptation
+export function adaptConfigToEnvironment(
+  baseConfig: typeof ROBOTICS_ATTENTION_CONFIG,
+  environment: 'indoor' | 'outdoor' | 'underground' | 'aerial'
+): typeof ROBOTICS_ATTENTION_CONFIG {
+  switch (environment) {
+    case 'indoor':
+      return {
+        ...baseConfig,
+        heads: 8,
+        dynamicK: { ...baseConfig.dynamicK, min: 5, max: 15 }
+      };
+    case 'outdoor':
+      return {
+        ...baseConfig,
+        heads: 10,                 // More complexity
+        dynamicK: { ...baseConfig.dynamicK, min: 10, max: 25 },
+        selfHealing: { ...baseConfig.selfHealing, adaptationIntervalMs: 50 }
+      };
+    case 'underground':
+      return {
+        ...baseConfig,
+        heads: 6,                  // Limited sensors
+        forwardPassTargetMs: 15
+        // Note: Network resilience handled at transport layer
+      };
+    case 'aerial':
+      return {
+        ...baseConfig,
+        heads: 12,                 // Complex 3D navigation
+        forwardPassTargetMs: 8,
+        dynamicK: { ...baseConfig.dynamicK, min: 8, max: 20 }
+      };
+  }
+}
+
+// Power-aware configuration adjustment
+export function adaptConfigToPower(
+  baseConfig: typeof ROBOTICS_ATTENTION_CONFIG,
+  batteryPercent: number
+): typeof ROBOTICS_ATTENTION_CONFIG {
+  if (batteryPercent < 20) {
+    // Critical battery - minimize computation
+    return {
+      ...baseConfig,
+      heads: 4,
+      batchSize: 1
+      // Note: Precision optimization coming in future release
+    };
+  } else if (batteryPercent < 50) {
+    // Low battery - reduce quality slightly
+    return {
+      ...baseConfig,
+      heads: 6,
+      precision: 'float16' as const
+    };
+  } else {
+    // Normal operation
+    return baseConfig;
+  }
+}

package/simulation/scenarios/domain-examples/scientific-research.ts

@@ -0,0 +1,250 @@
+/**
+ * Scientific Research: Research Paper Similarity and Discovery
+ *
+ * Use Case: Find similar research papers, identify research trends,
+ * and discover cross-domain connections.
+ *
+ * Optimization Priority: QUALITY + CROSS-DOMAIN DISCOVERY
+ */
+
+import { UnifiedMetrics } from '../../types';
+
+export const RESEARCH_ATTENTION_CONFIG = {
+  heads: 12,                       // High-quality attention (more than 8-head optimal)
+  forwardPassTargetMs: 100,        // 100ms acceptable (research workflow)
+  batchSize: 128,                  // Large batches for corpus processing
+  precision: 'float32' as const,   // Full precision for scientific data
+  crossDomainDiscovery: true,      // Enable cross-field connections
+
+  // Hierarchical clustering for research topics
+  clustering: {
+    algorithm: 'hierarchical' as const, // Better for taxonomy
+    linkage: 'ward' as const,      // Ward's minimum variance
+    hierarchicalLevels: 5,         // Deep taxonomy (field > subfield > topic > subtopic > specific)
+    semanticPurity: 0.90           // High purity for research domains
+  },
+
+  // High-recall for comprehensive literature review
+  recallTarget: 0.98,              // 98% recall (don't miss relevant papers)
+
+  // Self-organizing for evolving research landscape
+  selfHealing: {
+    enabled: true,
+    adaptationIntervalMs: 60000,   // 1-minute adaptation (not real-time)
+    degradationThreshold: 0.03,    // 3% tolerance
+    taxonomyUpdates: true          // Update research taxonomy
+  }
+};
+
+// Research-specific metrics
+export interface ResearchMetrics extends UnifiedMetrics {
+  crossDomainConnections: number;  // Cross-field discoveries
+  citationAccuracy: number;        // Citation network accuracy
+  taxonomyQuality: number;         // Research taxonomy quality
+  noveltyScore: number;            // Novel connection discovery rate
+  expertAgreement: number;         // Agreement with domain experts
+}
+
+// Research connection interface
+export interface ResearchConnection {
+  paperId: string;
+  title: string;
+  authors: string[];
+  similarity: number;
+  domain: string;
+  crossDomainConnection?: {
+    targetDomain: string;
+    connectionType: string;
+    noveltyScore: number;
+  };
+  citations: number;
+}
+
+// Example: Research paper discovery with cross-domain connections
+export async function discoverRelatedResearch(
+  paperEmbedding: Float32Array,    // Paper abstract + citations embeddings
+  researchCorpus: any,             // HNSWGraph type
+  applyAttention: (data: Float32Array, config: any) => Promise<Float32Array>,
+  buildResearchTaxonomy: (papers: any[], config: any) => Promise<any>,
+  findCrossDomainConnections: (papers: any[], taxonomy: any) => Promise<any[]>,
+  findDomain: (paper: any, taxonomy: any) => string,
+  includeCrossDomain: boolean = true
+): Promise<ResearchConnection[]> {
+  const config = RESEARCH_ATTENTION_CONFIG;
+
+  // 12-head attention for nuanced understanding
+  const enhanced = await applyAttention(paperEmbedding, config);
+
+  // High-recall search (k=100 for comprehensive review)
+  const candidates = await researchCorpus.search(enhanced, 100);
+
+  // Hierarchical clustering for taxonomy
+  const taxonomy = await buildResearchTaxonomy(candidates, config.clustering);
+
+  // Cross-domain discovery (find connections across fields)
+  const crossDomain = includeCrossDomain
+    ? await findCrossDomainConnections(candidates, taxonomy)
+    : [];
+
+  return candidates.map((p: any) => ({
+    paperId: p.id,
+    title: p.metadata.title,
+    authors: p.metadata.authors,
+    similarity: p.score,
+    domain: findDomain(p, taxonomy),
+    crossDomainConnection: crossDomain.find((c: any) => c.paperId === p.id),
+    citations: p.metadata.citations
+  }));
+}
+
+// Performance targets for research
+export const RESEARCH_PERFORMANCE_TARGETS = {
+  recallAt100: 0.98,               // 98% recall (comprehensive)
+  p95LatencyMs: 200,               // 200ms p95 (batch processing)
+  crossDomainRate: 0.15,           // 15% cross-domain discoveries
+  expertAgreement: 0.85,           // 85% agreement with experts
+  uptimePercent: 99.0              // 99% uptime (2 nines)
+};
+
+// Research field-specific configurations
+export const RESEARCH_CONFIG_VARIATIONS = {
+  // Computer science (fast-moving field, many papers)
+  computerScience: {
+    ...RESEARCH_ATTENTION_CONFIG,
+    heads: 10,
+    forwardPassTargetMs: 50,       // Faster for large corpus
+    batchSize: 256,
+    recallTarget: 0.97             // Slightly lower for speed
+  },
+
+  // Medicine (high precision required, slower pace)
+  medicine: {
+    ...RESEARCH_ATTENTION_CONFIG,
+    heads: 16,                     // Maximum quality
+    forwardPassTargetMs: 150,
+    recallTarget: 0.99,            // Highest recall
+    precision: 'float32' as const
+  },
+
+  // Physics (mathematical precision, cross-domain links)
+  physics: {
+    ...RESEARCH_ATTENTION_CONFIG,
+    heads: 14,
+    crossDomainDiscovery: true,
+    clustering: {
+      ...RESEARCH_ATTENTION_CONFIG.clustering,
+      hierarchicalLevels: 6        // Deeper for specialized subfields
+    }
+  },
+
+  // Social sciences (qualitative, broader connections)
+  socialSciences: {
+    ...RESEARCH_ATTENTION_CONFIG,
+    heads: 12,
+    crossDomainDiscovery: true,
+    clustering: {
+      ...RESEARCH_ATTENTION_CONFIG.clustering,
+      semanticPurity: 0.85         // More flexible clustering
+    }
+  }
+};
+
+// Search mode adaptations
+export function adaptConfigToSearchMode(
+  baseConfig: typeof RESEARCH_ATTENTION_CONFIG,
+  mode: 'literature-review' | 'novelty-discovery' | 'citation-tracing' | 'interdisciplinary'
+): typeof RESEARCH_ATTENTION_CONFIG {
+  switch (mode) {
+    case 'literature-review':
+      return {
+        ...baseConfig,
+        heads: 12,
+        recallTarget: 0.99,        // Comprehensive recall
+        crossDomainDiscovery: false // Stay within field
+      };
+    case 'novelty-discovery':
+      return {
+        ...baseConfig,
+        heads: 16,                 // Maximum quality
+        crossDomainDiscovery: true,
+        clustering: {
+          ...baseConfig.clustering,
+          semanticPurity: 0.80     // More flexible for novel connections
+        }
+      };
+    case 'citation-tracing':
+      return {
+        ...baseConfig,
+        heads: 10,
+        forwardPassTargetMs: 50,
+        recallTarget: 0.95,        // Fast, focused
+        crossDomainDiscovery: false
+      };
+    case 'interdisciplinary':
+      return {
+        ...baseConfig,
+        heads: 14,
+        crossDomainDiscovery: true,
+        clustering: {
+          ...baseConfig.clustering,
+          hierarchicalLevels: 6,   // Deep taxonomy for connections
+          semanticPurity: 0.82     // Flexible for cross-field
+        }
+      };
+  }
+}
+
+// Research stage adaptations
+export function adaptConfigToResearchStage(
+  baseConfig: typeof RESEARCH_ATTENTION_CONFIG,
+  stage: 'initial-exploration' | 'hypothesis-formation' | 'validation' | 'writing'
+): typeof RESEARCH_ATTENTION_CONFIG {
+  switch (stage) {
+    case 'initial-exploration':
+      return {
+        ...baseConfig,
+        heads: 12,
+        crossDomainDiscovery: true,
+        recallTarget: 0.95         // Broad search
+      };
+    case 'hypothesis-formation':
+      return {
+        ...baseConfig,
+        heads: 14,
+        crossDomainDiscovery: true,
+        recallTarget: 0.98         // Comprehensive
+      };
+    case 'validation':
+      return {
+        ...baseConfig,
+        heads: 16,                 // Maximum precision
+        recallTarget: 0.99,
+        crossDomainDiscovery: false // Focused
+      };
+    case 'writing':
+      return {
+        ...baseConfig,
+        heads: 10,
+        forwardPassTargetMs: 50,   // Fast lookups
+        recallTarget: 0.95
+      };
+  }
+}
+
+// Citation network analysis
+export interface CitationNetworkMetrics {
+  networkDensity: number;
+  clusteringCoefficient: number;
+  averagePathLength: number;
+  communityModularity: number;
+}
+
+export function analyzeCitationNetwork(papers: ResearchConnection[]): CitationNetworkMetrics {
+  // Placeholder implementation
+  return {
+    networkDensity: 0.15,
+    clusteringCoefficient: 0.45,
+    averagePathLength: 3.2,
+    communityModularity: 0.78
+  };
+}