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

package/simulation/scenarios/domain-examples/e-commerce-recommendations.ts

@@ -0,0 +1,220 @@
+/**
+ * E-Commerce Recommendations: Personalized Product Discovery
+ *
+ * Use Case: Recommend similar products based on user preferences,
+ * browsing history, and product embeddings.
+ *
+ * Optimization Priority: DIVERSITY + RELEVANCE
+ */
+
+import { UnifiedMetrics } from '../../types';
+
+export const ECOMMERCE_ATTENTION_CONFIG = {
+  heads: 8,                        // Optimal for balanced performance
+  forwardPassTargetMs: 20,         // 20ms acceptable for recommendations
+  batchSize: 64,                   // Batch user requests
+  precision: 'float32' as const,   // Full precision for quality
+  diversityBoost: true,            // Promote diverse recommendations
+
+  // Louvain clustering for product categories
+  clustering: {
+    algorithm: 'louvain' as const,
+    minModularity: 0.75,           // High-quality clusters
+    semanticPurity: 0.87,          // 87.2% purity validated
+    hierarchicalLevels: 3          // Category hierarchy (dept > category > subcategory)
+  },
+
+  // Dynamic-k based on user engagement
+  dynamicK: {
+    min: 10,                       // Minimum 10 recommendations
+    max: 50,                       // Maximum 50 for exploration
+    adaptationStrategy: 'user-engagement' as const  // Active users get more
+  }
+};
+
+// E-commerce-specific metrics
+export interface ECommerceMetrics extends UnifiedMetrics {
+  clickThroughRate: number;        // CTR on recommendations
+  conversionRate: number;          // Purchase conversion rate
+  diversityScore: number;          // Recommendation diversity
+  categoryBalanceScore: number;    // Cross-category recommendations
+  userSatisfaction: number;        // Implicit feedback signals
+}
+
+// Recommendation interface
+export interface Recommendation {
+  productId: string;
+  relevanceScore: number;
+  category: string;
+  cluster: string;
+  priceUSD: number;
+}
+
+// Example: Product recommendation with diversity
+export async function recommendProducts(
+  userProfile: Float32Array,       // User preferences embeddings
+  productCatalog: any,             // HNSWGraph type
+  userEngagement: number,
+  applyAttention: (data: Float32Array, config: any) => Promise<Float32Array>,
+  applyDiversityBoost: (candidates: any[], weight: number) => Promise<any[]>,
+  clusterRecommendations: (items: any[], config: any) => Promise<any[]>,
+  findCluster: (item: any, clusters: any[]) => string,
+  diversityWeight: number = 0.3
+): Promise<Recommendation[]> {
+  const config = ECOMMERCE_ATTENTION_CONFIG;
+
+  // 8-head attention for user query enhancement
+  const enhanced = await applyAttention(userProfile, config);
+
+  // Dynamic-k based on user engagement (engaged users get more options)
+  const k = Math.round(10 + userEngagement * 40);  // 10-50 range
+
+  // Search with clustering for category diversity
+  const candidates = await productCatalog.search(enhanced, k);
+
+  // Apply diversity boost (promote different categories)
+  const diversified = await applyDiversityBoost(candidates, diversityWeight);
+
+  // Cluster recommendations by category (Louvain)
+  const clusters = await clusterRecommendations(diversified, config.clustering);
+
+  return diversified.map((p: any) => ({
+    productId: p.id,
+    relevanceScore: p.score,
+    category: p.metadata.category,
+    cluster: findCluster(p, clusters),
+    priceUSD: p.metadata.price
+  }));
+}
+
+// Performance targets for e-commerce
+export const ECOMMERCE_PERFORMANCE_TARGETS = {
+  p95LatencyMs: 50,                // 50ms p95 (user experience)
+  clickThroughRate: 0.15,          // 15% CTR target
+  conversionRate: 0.05,            // 5% conversion target
+  diversityScore: 0.7,             // 70% category diversity
+  uptimePercent: 99.9              // 99.9% uptime (3 nines)
+};
+
+// E-commerce platform-specific configurations
+export const ECOMMERCE_CONFIG_VARIATIONS = {
+  // Fashion/apparel (high visual similarity)
+  fashion: {
+    ...ECOMMERCE_ATTENTION_CONFIG,
+    heads: 12,                     // More heads for visual nuance
+    diversityBoost: true,
+    clustering: {
+      ...ECOMMERCE_ATTENTION_CONFIG.clustering,
+      hierarchicalLevels: 4        // Deeper taxonomy (category > subcategory > style > color)
+    }
+  },
+
+  // Electronics (specification-driven)
+  electronics: {
+    ...ECOMMERCE_ATTENTION_CONFIG,
+    heads: 8,
+    specificationWeight: 0.6,      // Emphasize specs over style
+    diversityBoost: false          // Users want specific features
+  },
+
+  // Grocery (frequent purchases)
+  grocery: {
+    ...ECOMMERCE_ATTENTION_CONFIG,
+    heads: 6,
+    forwardPassTargetMs: 10,       // Faster for mobile
+    batchSize: 128,                // High volume
+    dynamicK: { min: 15, max: 30, adaptationStrategy: 'cart-size' as const }
+  },
+
+  // Luxury goods (personalization critical)
+  luxury: {
+    ...ECOMMERCE_ATTENTION_CONFIG,
+    heads: 16,                     // Maximum personalization
+    forwardPassTargetMs: 50,       // Allow more time
+    diversityBoost: false,         // Highly targeted
+    precision: 'float32' as const
+  }
+};
+
+// User segment adaptations
+export function adaptConfigToUserSegment(
+  baseConfig: typeof ECOMMERCE_ATTENTION_CONFIG,
+  segment: 'browser' | 'buyer' | 'loyal' | 'vip'
+): typeof ECOMMERCE_ATTENTION_CONFIG {
+  switch (segment) {
+    case 'browser':
+      return {
+        ...baseConfig,
+        dynamicK: { ...baseConfig.dynamicK, min: 20, max: 50 }, // More exploration
+        diversityBoost: true       // Show variety
+      };
+    case 'buyer':
+      return {
+        ...baseConfig,
+        dynamicK: { ...baseConfig.dynamicK, min: 10, max: 30 }, // Focused recommendations
+        diversityBoost: false
+      };
+    case 'loyal':
+      return {
+        ...baseConfig,
+        heads: 12,                 // Better personalization
+        dynamicK: { ...baseConfig.dynamicK, min: 15, max: 40 }
+      };
+    case 'vip':
+      return {
+        ...baseConfig,
+        heads: 16,                 // Maximum personalization
+        forwardPassTargetMs: 30,
+        precision: 'float32' as const
+      };
+  }
+}
+
+// Seasonal/promotional adaptations
+export interface PromotionalContext {
+  isSale: boolean;
+  seasonalEvent: string | null;
+  inventoryPressure: number;      // 0-1, how much to push certain items
+}
+
+export function adaptConfigToPromotion(
+  baseConfig: typeof ECOMMERCE_ATTENTION_CONFIG,
+  context: PromotionalContext
+): typeof ECOMMERCE_ATTENTION_CONFIG {
+  if (context.isSale) {
+    return {
+      ...baseConfig,
+      dynamicK: { ...baseConfig.dynamicK, min: 20, max: 60 }, // Show more options
+      diversityBoost: true        // Cross-sell opportunities
+      // Note: Sale boost handled in ranking layer
+    };
+  }
+  return baseConfig;
+}
+
+// A/B testing configuration generator
+export function generateABTestConfigs(
+  baseConfig: typeof ECOMMERCE_ATTENTION_CONFIG
+): Record<string, typeof ECOMMERCE_ATTENTION_CONFIG> {
+  return {
+    control: baseConfig,
+
+    moreHeads: {
+      ...baseConfig,
+      heads: 12
+    },
+
+    moreDiversity: {
+      ...baseConfig,
+      diversityBoost: true,
+      dynamicK: { ...baseConfig.dynamicK, min: 15, max: 60 }
+    },
+
+    fasterLatency: {
+      ...baseConfig,
+      heads: 6,
+      forwardPassTargetMs: 10,
+      precision: 'float32' as const  // Lower precision not yet supported
+    }
+  };
+}

package/simulation/scenarios/domain-examples/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Domain-Specific Attention Configuration Examples
+ *
+ * This module exports real-world configurations and examples for various industries
+ * and use cases, demonstrating how to adapt AgentDB's attention mechanisms for
+ * specific requirements.
+ */
+
+export {
+  TRADING_ATTENTION_CONFIG,
+  TRADING_PERFORMANCE_TARGETS,
+  TRADING_CONFIG_VARIATIONS,
+  type TradingMetrics,
+  type TradingSignal,
+  matchTradingPattern,
+  adaptConfigToMarket
+} from './trading-systems';
+
+export {
+  MEDICAL_ATTENTION_CONFIG,
+  MEDICAL_PERFORMANCE_TARGETS,
+  MEDICAL_CONFIG_VARIATIONS,
+  type MedicalMetrics,
+  type SimilarCase,
+  type MedicalDataQuality,
+  findSimilarCases,
+  adaptConfigToUrgency,
+  validateMedicalData
+} from './medical-imaging';
+
+export {
+  ROBOTICS_ATTENTION_CONFIG,
+  ROBOTICS_PERFORMANCE_TARGETS,
+  ROBOTICS_CONFIG_VARIATIONS,
+  type RoboticsMetrics,
+  type RobotContext,
+  type NavigationPlan,
+  matchEnvironment,
+  adaptConfigToEnvironment,
+  adaptConfigToPower
+} from './robotics-navigation';
+
+export {
+  ECOMMERCE_ATTENTION_CONFIG,
+  ECOMMERCE_PERFORMANCE_TARGETS,
+  ECOMMERCE_CONFIG_VARIATIONS,
+  type ECommerceMetrics,
+  type Recommendation,
+  type PromotionalContext,
+  recommendProducts,
+  adaptConfigToUserSegment,
+  adaptConfigToPromotion,
+  generateABTestConfigs
+} from './e-commerce-recommendations';
+
+export {
+  RESEARCH_ATTENTION_CONFIG,
+  RESEARCH_PERFORMANCE_TARGETS,
+  RESEARCH_CONFIG_VARIATIONS,
+  type ResearchMetrics,
+  type ResearchConnection,
+  type CitationNetworkMetrics,
+  discoverRelatedResearch,
+  adaptConfigToSearchMode,
+  adaptConfigToResearchStage,
+  analyzeCitationNetwork
+} from './scientific-research';
+
+export {
+  IOT_ATTENTION_CONFIG,
+  IOT_PERFORMANCE_TARGETS,
+  IOT_CONFIG_VARIATIONS,
+  type IoTMetrics,
+  type Sensor,
+  type AnomalyAlert,
+  type NetworkTopology,
+  detectAnomalies,
+  adaptConfigToDeployment,
+  adaptConfigToBattery,
+  adaptConfigToTopology
+} from './iot-sensor-networks';

package/simulation/scenarios/domain-examples/iot-sensor-networks.ts

@@ -0,0 +1,290 @@
+/**
+ * IoT Sensor Networks: Distributed Anomaly Detection
+ *
+ * Use Case: Real-time anomaly detection in IoT sensor networks
+ * with limited compute resources.
+ *
+ * Optimization Priority: POWER EFFICIENCY + LATENCY
+ */
+
+import { UnifiedMetrics } from '../../types';
+
+export const IOT_ATTENTION_CONFIG = {
+  heads: 4,                        // Lightweight for edge devices
+  forwardPassTargetMs: 5,          // 5ms for real-time monitoring
+  batchSize: 1,                    // Single-sensor processing
+  precision: 'int8' as const,      // Quantized for edge (NVIDIA TensorRT, TFLite)
+  edgeOptimized: true,             // ESP32, Raspberry Pi, Coral TPU
+  powerBudgetMw: 500,              // 500mW power budget
+
+  // Hypergraph for multi-sensor correlations
+  hypergraph: {
+    enabled: true,
+    maxHyperedgeSize: 5,           // 5-sensor correlations
+    compressionRatio: 3.7,         // 3.7x edge compression validated
+    distributedProcessing: true    // Process across sensor network
+  },
+
+  // Dynamic-k based on anomaly severity
+  dynamicK: {
+    min: 3,                        // Minimum candidates (normal operation)
+    max: 15,                       // Maximum candidates (anomaly detected)
+    adaptationStrategy: 'anomaly-severity' as const
+  },
+
+  // Self-healing for autonomous operation
+  selfHealing: {
+    enabled: true,
+    adaptationIntervalMs: 1000,    // 1s monitoring
+    degradationThreshold: 0.10,    // 10% tolerance (edge constraints)
+    networkResilience: true        // Handle node failures
+  }
+};
+
+// IoT-specific metrics
+export interface IoTMetrics extends UnifiedMetrics {
+  anomalyDetectionRate: number;    // True positive anomaly detection
+  falseAlarmRate: number;          // False positive rate (minimize network traffic)
+  powerConsumptionMw: number;      // Power consumption (battery life critical)
+  networkLatencyMs: number;        // Multi-hop network latency
+  sensorCoverage: number;          // Sensor network coverage
+}
+
+// Sensor interface
+export interface Sensor {
+  id: string;
+  reading: Float32Array;
+  timestamp: number;
+  batteryPercent: number;
+}
+
+// Anomaly alert interface
+export interface AnomalyAlert {
+  sensorId: string;
+  anomalyScore: number;
+  severity: 'warning' | 'critical';
+  correlatedSensors: string[];
+  timestamp: number;
+  latencyMs: number;
+}
+
+// Example: Distributed anomaly detection
+export async function detectAnomalies(
+  sensorReading: Float32Array & { id: string },
+  normalPatterns: any,             // HNSWGraph type
+  neighborSensors: Sensor[],
+  applyAttention: (data: Float32Array, config: any) => Promise<Float32Array>,
+  createHyperedge: (readings: Float32Array[]) => Promise<Float32Array>,
+  severityThreshold: number = 0.8
+): Promise<AnomalyAlert[]> {
+  const startTime = Date.now();
+  const config = IOT_ATTENTION_CONFIG;
+
+  // 4-head attention for lightweight processing
+  const enhanced = await applyAttention(sensorReading, config);
+
+  // Hypergraph: Correlate with neighbor sensors (multi-sensor patterns)
+  const hyperedge = await createHyperedge([
+    sensorReading,
+    ...neighborSensors.map(s => s.reading)
+  ]);
+
+  // Search for normal patterns
+  const matches = await normalPatterns.search(enhanced, 10);
+
+  // Anomaly = low similarity to normal patterns
+  const anomalyScore = 1 - matches[0].score;
+
+  if (anomalyScore > severityThreshold) {
+    // Dynamic-k: Get more candidates for anomaly analysis
+    const k = Math.round(3 + anomalyScore * 12);  // 3-15 range
+    const detailedMatches = await normalPatterns.search(enhanced, k);
+
+    return [{
+      sensorId: sensorReading.id,
+      anomalyScore,
+      severity: anomalyScore > 0.9 ? 'critical' : 'warning',
+      correlatedSensors: neighborSensors.map(s => s.id),
+      timestamp: Date.now(),
+      latencyMs: Date.now() - startTime
+    }];
+  }
+
+  return [];
+}
+
+// Performance targets for IoT
+export const IOT_PERFORMANCE_TARGETS = {
+  p50LatencyMs: 5,                 // 5ms median (real-time monitoring)
+  anomalyDetectionRate: 0.95,      // 95% true positive rate
+  falseAlarmRate: 0.05,            // 5% false positive rate
+  powerConsumptionMw: 500,         // 500mW max (battery life)
+  uptimePercent: 99.9              // 99.9% uptime (3 nines, edge resilience)
+};
+
+// IoT platform-specific configurations
+export const IOT_CONFIG_VARIATIONS = {
+  // ESP32 (very constrained, WiFi)
+  esp32: {
+    ...IOT_ATTENTION_CONFIG,
+    heads: 2,                      // Minimal heads
+    precision: 'int8' as const,
+    powerBudgetMw: 200,
+    forwardPassTargetMs: 10,
+    batchSize: 1
+  },
+
+  // Raspberry Pi (more capable, still battery)
+  raspberryPi: {
+    ...IOT_ATTENTION_CONFIG,
+    heads: 4,
+    precision: 'float16' as const,
+    powerBudgetMw: 1000,           // 1W budget
+    forwardPassTargetMs: 5
+  },
+
+  // NVIDIA Jetson Nano (edge AI, powered)
+  jetsonNano: {
+    ...IOT_ATTENTION_CONFIG,
+    heads: 8,                      // More capable
+    precision: 'float16' as const,
+    powerBudgetMw: 5000,           // 5W budget
+    forwardPassTargetMs: 3,
+    batchSize: 4
+  },
+
+  // Google Coral TPU (ML accelerator)
+  coralTPU: {
+    ...IOT_ATTENTION_CONFIG,
+    heads: 6,
+    precision: 'int8' as const,    // TPU optimized
+    powerBudgetMw: 2000,           // 2W budget
+    forwardPassTargetMs: 2,
+    batchSize: 8
+  }
+};
+
+// Deployment environment adaptations
+export function adaptConfigToDeployment(
+  baseConfig: typeof IOT_ATTENTION_CONFIG,
+  environment: 'urban' | 'industrial' | 'agricultural' | 'remote'
+): typeof IOT_ATTENTION_CONFIG {
+  switch (environment) {
+    case 'urban':
+      return {
+        ...baseConfig,
+        heads: 6,                  // More sensors, more complex
+        hypergraph: {
+          ...baseConfig.hypergraph,
+          maxHyperedgeSize: 8      // Dense sensor network
+        }
+      };
+    case 'industrial':
+      return {
+        ...baseConfig,
+        heads: 8,                  // High reliability needed
+        forwardPassTargetMs: 3,
+        powerBudgetMw: 2000        // Powered sensors
+      };
+    case 'agricultural':
+      return {
+        ...baseConfig,
+        heads: 4,
+        powerBudgetMw: 300,        // Solar-powered, battery constrained
+        selfHealing: {
+          ...baseConfig.selfHealing,
+          networkResilience: true  // Sparse network
+        }
+      };
+    case 'remote':
+      return {
+        ...baseConfig,
+        heads: 2,                  // Minimal computation
+        precision: 'int8' as const,
+        powerBudgetMw: 100,        // Extreme battery constraint
+        forwardPassTargetMs: 20    // Slower acceptable
+      };
+  }
+}
+
+// Battery-aware configuration
+export function adaptConfigToBattery(
+  baseConfig: typeof IOT_ATTENTION_CONFIG,
+  batteryPercent: number,
+  chargingStatus: 'charging' | 'discharging' | 'solar'
+): typeof IOT_ATTENTION_CONFIG {
+  if (chargingStatus === 'charging') {
+    return {
+      ...baseConfig,
+      heads: 8                     // Use more resources when charging
+      // Note: Precision optimization coming in future release
+    };
+  }
+
+  if (batteryPercent < 10) {
+    // Critical battery
+    return {
+      ...baseConfig,
+      heads: 2,
+      precision: 'int8' as const,
+      powerBudgetMw: 100,
+      batchSize: 1
+    };
+  } else if (batteryPercent < 30) {
+    // Low battery
+    return {
+      ...baseConfig,
+      heads: 3,
+      precision: 'int8' as const,
+      powerBudgetMw: 300
+    };
+  } else if (chargingStatus === 'solar') {
+    // Solar powered - adaptive
+    return {
+      ...baseConfig,
+      heads: 5,
+      powerBudgetMw: 600
+    };
+  }
+
+  return baseConfig;
+}
+
+// Network topology adaptations
+export interface NetworkTopology {
+  nodeCount: number;
+  averageDegree: number;
+  meshDensity: number;
+  gatewayDistance: number;
+}
+
+export function adaptConfigToTopology(
+  baseConfig: typeof IOT_ATTENTION_CONFIG,
+  topology: NetworkTopology
+): typeof IOT_ATTENTION_CONFIG {
+  if (topology.meshDensity > 0.7) {
+    // Dense mesh - can use more correlations
+    return {
+      ...baseConfig,
+      hypergraph: {
+        ...baseConfig.hypergraph,
+        maxHyperedgeSize: 8
+      }
+    };
+  } else if (topology.meshDensity < 0.3) {
+    // Sparse mesh - limited correlations
+    return {
+      ...baseConfig,
+      hypergraph: {
+        ...baseConfig.hypergraph,
+        maxHyperedgeSize: 3
+      },
+      selfHealing: {
+        ...baseConfig.selfHealing,
+        networkResilience: true
+      }
+    };
+  }
+
+  return baseConfig;
+}