@arclabs561/ai-visual-test 0.5.1

package/src/temporal-batch-optimizer.mjs

@@ -0,0 +1,222 @@
+/**
+ * Temporal Batch Optimizer
+ * 
+ * Adaptive batching that considers temporal dependencies and human perception.
+ * 
+ * Research context (loosely related):
+ * - Efficient Sequential Decision Making (arXiv:2406.12125)
+ *   * Paper focuses on online model selection (NOT implemented here)
+ *   * We use temporal dependency concepts inspired by sequential decision aspects
+ *   * We do NOT implement the paper's core online model selection algorithm
+ * - Serving LLM Reasoning Efficiently (arXiv:2505.13326)
+ *   * Paper discusses "short and right" thinking management (NOT implemented here)
+ *   * We do adaptive batching with temporal awareness (loosely related concept)
+ *   * We do NOT implement the paper's specific adaptive batching strategy
+ * - Human Time Perception (NN/g, PMC)
+ *   * 0.1s threshold for direct manipulation (used in time scales)
+ *   * Attention affects temporal perception (used in weighting)
+ * 
+ * IMPORTANT: This implements temporal-aware batching with dependencies, but does NOT
+ * implement the core algorithms from the cited papers. The citations are for loosely
+ * related concepts, not direct implementations.
+ */
+
+import { BatchOptimizer } from './batch-optimizer.mjs';
+
+/**
+ * Temporal Batch Optimizer
+ * Extends BatchOptimizer with temporal awareness
+ */
+export class TemporalBatchOptimizer extends BatchOptimizer {
+  constructor(options = {}) {
+    super(options);
+    this.temporalDependencies = new Map(); // Track dependencies
+    this.sequentialContext = options.sequentialContext || null;
+    this.adaptiveBatching = options.adaptiveBatching !== false;
+  }
+  
+  /**
+   * Add request with temporal dependencies
+   */
+  async addTemporalRequest(imagePath, prompt, context, dependencies = []) {
+    // Track dependencies
+    this.temporalDependencies.set(imagePath, {
+      dependencies,
+      timestamp: Date.now(),
+      priority: this.calculatePriority(dependencies, context)
+    });
+    
+    return this._queueRequest(imagePath, prompt, context);
+  }
+  
+  /**
+   * Calculate priority based on temporal dependencies
+   */
+  calculatePriority(dependencies, context) {
+    // Higher priority for:
+    // - No dependencies (can run in parallel)
+    // - Earlier timestamps (sequential order)
+    // - Critical evaluations (high importance)
+    
+    let priority = 0;
+    
+    // No dependencies = can run immediately
+    if (dependencies.length === 0) {
+      priority += 100;
+    } else {
+      // Dependencies reduce priority (must wait)
+      priority -= dependencies.length * 10;
+    }
+    
+    // Earlier timestamps get higher priority (decay over time)
+    if (context.timestamp) {
+      const age = Date.now() - context.timestamp;
+      // Earlier requests (older timestamp = larger age) should have higher priority
+      // But we want to decay this over time, so very old requests get lower priority
+      // For requests within reasonable time window, earlier = higher priority
+      if (age < 60000) { // Within 1 minute
+        priority += Math.max(0, 30 - age / 1000); // Earlier = higher, but decays
+      }
+    }
+    
+    // Critical evaluations get higher priority
+    if (context.critical || context.testType === 'critical') {
+      priority += 50;
+    }
+    
+    return priority;
+  }
+  
+  /**
+   * Process queue with temporal awareness
+   */
+  async _processQueue() {
+    if (this.processing || this.queue.length === 0) {
+      return;
+    }
+    
+    this.processing = true;
+    
+    try {
+      // Sort by priority and dependencies
+      const sortedQueue = this.sortByTemporalDependencies([...this.queue]);
+      
+      // Process in batches, respecting dependencies
+      while (sortedQueue.length > 0 && this.activeRequests < this.maxConcurrency) {
+        const batch = this.selectTemporalBatch(sortedQueue);
+        
+        // Remove from queue
+        batch.forEach(item => {
+          const index = this.queue.findIndex(q => q.imagePath === item.imagePath);
+          if (index >= 0) this.queue.splice(index, 1);
+        });
+        
+        // Process batch
+        const promises = batch.map(async ({ imagePath, prompt, context, validateFn, resolve, reject }) => {
+          try {
+            // Check cache
+            if (this.cache) {
+              const cacheKey = this._getCacheKey(imagePath, prompt, context);
+              if (this.cache.has(cacheKey)) {
+                resolve(this.cache.get(cacheKey));
+                return;
+              }
+            }
+            
+            // Add sequential context if available
+            if (this.sequentialContext) {
+              context = {
+                ...context,
+                sequentialContext: this.sequentialContext.getContext()
+              };
+            }
+            
+            const result = await this._processRequest(imagePath, prompt, context, validateFn);
+            
+            // Update sequential context
+            if (this.sequentialContext && result.score !== null) {
+              this.sequentialContext.addDecision({
+                score: result.score,
+                issues: result.issues || [],
+                assessment: result.assessment,
+                reasoning: result.reasoning
+              });
+            }
+            
+            resolve(result);
+          } catch (error) {
+            reject(error);
+          }
+        });
+        
+        await Promise.allSettled(promises);
+      }
+    } finally {
+      this.processing = false;
+    }
+  }
+  
+  /**
+   * Sort queue by temporal dependencies
+   */
+  sortByTemporalDependencies(queue) {
+    return queue.sort((a, b) => {
+      const depsA = this.temporalDependencies.get(a.imagePath);
+      const depsB = this.temporalDependencies.get(b.imagePath);
+      
+      // No dependencies come first
+      if (!depsA && depsB) return -1;
+      if (depsA && !depsB) return 1;
+      if (!depsA && !depsB) return 0;
+      
+      // Compare priorities
+      return depsB.priority - depsA.priority;
+    });
+  }
+  
+  /**
+   * Select batch considering temporal dependencies
+   */
+  selectTemporalBatch(sortedQueue) {
+    if (!this.adaptiveBatching) {
+      // Fixed batch size
+      return sortedQueue.splice(0, this.batchSize);
+    }
+    
+    // Adaptive batch selection
+    const batch = [];
+    const processed = new Set();
+    
+    for (const item of sortedQueue) {
+      if (batch.length >= this.batchSize) break;
+      if (processed.has(item.imagePath)) continue;
+      
+      const deps = this.temporalDependencies.get(item.imagePath);
+      
+      // Check if dependencies are satisfied
+      if (!deps || deps.dependencies.every(dep => processed.has(dep))) {
+        batch.push(item);
+        processed.add(item.imagePath);
+      }
+    }
+    
+    return batch;
+  }
+  
+  /**
+   * Get temporal statistics
+   */
+  getTemporalStats() {
+    return {
+      ...this.getCacheStats(),
+      dependencies: this.temporalDependencies.size,
+      sequentialContext: this.sequentialContext
+        ? {
+            historyLength: this.sequentialContext.history.length,
+            patterns: this.sequentialContext.identifyPatterns()
+          }
+        : null
+    };
+  }
+}
+

package/src/temporal-constants.mjs

@@ -0,0 +1,69 @@
+/**
+ * Temporal Constants
+ * Centralized definitions for all temporal decision-making constants
+ * 
+ * Single source of truth for all magic numbers and time scales
+ */
+
+// Time Scales (based on research: NN/g, PMC, Lindgaard)
+export const TIME_SCALES = {
+  INSTANT: 100,           // 0.1s - perceived instant, direct manipulation threshold (NN/g)
+  VISUAL_DECISION: 50,    // 50ms - visual appeal decision (Lindgaard research)
+  QUICK: 1000,            // 1s - noticeable delay (NN/g)
+  NORMAL: 3000,           // 3s - normal interaction
+  EXTENDED: 10000,        // 10s - extended focus (NN/g)
+  LONG: 60000             // 60s - deep evaluation
+};
+
+// Multi-Scale Windows
+export const MULTI_SCALE_WINDOWS = {
+  immediate: TIME_SCALES.INSTANT,
+  short: TIME_SCALES.QUICK,
+  medium: TIME_SCALES.EXTENDED,
+  long: TIME_SCALES.LONG
+};
+
+// Reading Speeds (words per minute)
+export const READING_SPEEDS = {
+  SCANNING: 300,    // Fast scanning
+  NORMAL: 250,      // Average reading
+  DEEP: 200         // Deep reading
+};
+
+// Attention Multipliers
+export const ATTENTION_MULTIPLIERS = {
+  focused: 0.8,      // Faster when focused (reduced cognitive load)
+  normal: 1.0,
+  distracted: 1.5    // Slower when distracted (increased cognitive load)
+};
+
+// Complexity Multipliers
+export const COMPLEXITY_MULTIPLIERS = {
+  simple: 0.7,       // Simple actions are faster
+  normal: 1.0,
+  complex: 1.5        // Complex actions take longer
+};
+
+// Confidence Thresholds
+export const CONFIDENCE_THRESHOLDS = {
+  HIGH_VARIANCE: 1.0,    // Variance < 1.0 = high confidence
+  MEDIUM_VARIANCE: 2.0,   // Variance < 2.0 = medium confidence
+  LOW_VARIANCE: 2.0       // Variance >= 2.0 = low confidence
+};
+
+// Time Bounds
+export const TIME_BOUNDS = {
+  MIN_PERCEPTION: 100,        // Minimum perception time (0.1s)
+  MIN_READING_SHORT: 1000,     // Minimum reading time for short content
+  MIN_READING_LONG: 2000,      // Minimum reading time for long content
+  MAX_READING_SHORT: 15000,    // Maximum reading time for short content
+  MAX_READING_LONG: 30000      // Maximum reading time for long content
+};
+
+// Content Length Thresholds
+export const CONTENT_THRESHOLDS = {
+  SHORT: 100,      // Short content (< 100 chars)
+  MEDIUM: 1000,    // Medium content (< 1000 chars)
+  LONG: 1000       // Long content (>= 1000 chars)
+};
+

package/src/temporal-context.mjs

@@ -0,0 +1,49 @@
+/**
+ * Temporal Context Utilities
+ * Standardized context creation and merging for temporal components
+ */
+
+/**
+ * Create standardized temporal context
+ */
+export function createTemporalContext(options = {}) {
+  return {
+    sequentialContext: options.sequentialContext || null,
+    viewport: options.viewport || null,
+    testType: options.testType || null,
+    enableBiasMitigation: options.enableBiasMitigation !== false,
+    attentionLevel: options.attentionLevel || 'normal',
+    actionComplexity: options.actionComplexity || 'normal',
+    persona: options.persona || null,
+    contentLength: options.contentLength || 0,
+    ...options
+  };
+}
+
+/**
+ * Merge temporal contexts
+ */
+export function mergeTemporalContext(base, additional) {
+  return {
+    ...base,
+    ...additional,
+    sequentialContext: additional.sequentialContext || base.sequentialContext,
+    // Preserve base values if additional doesn't override
+    attentionLevel: additional.attentionLevel || base.attentionLevel || 'normal',
+    actionComplexity: additional.actionComplexity || base.actionComplexity || 'normal'
+  };
+}
+
+/**
+ * Extract temporal context from options
+ */
+export function extractTemporalContext(options) {
+  return {
+    sequentialContext: options.sequentialContext,
+    attentionLevel: options.attentionLevel,
+    actionComplexity: options.actionComplexity,
+    persona: options.persona,
+    contentLength: options.contentLength
+  };
+}
+

package/src/temporal-decision-manager.mjs

@@ -0,0 +1,271 @@
+/**
+ * Temporal Decision Manager
+ * 
+ * Implements decision logic for WHEN to prompt based on temporal context.
+ * 
+ * Research: arXiv:2406.12125 - "Efficient Sequential Decision Making"
+ * - Paper's core finding: Don't prompt on every state change, prompt when decision is needed
+ * - Online model selection achieves 6x gains with 1.5% LLM calls
+ * 
+ * This module implements the decision logic (when to prompt) that was missing from
+ * our temporal aggregation system. It complements temporal-decision.mjs which handles
+ * HOW to aggregate temporal context, while this handles WHEN to use it.
+ */
+
+import { aggregateTemporalNotes } from './temporal.mjs';
+import { aggregateMultiScale } from './temporal-decision.mjs';
+
+/**
+ * Temporal Decision Manager
+ * 
+ * Decides when context is sufficient to prompt, when to wait, and when to prompt immediately.
+ */
+export class TemporalDecisionManager {
+  constructor(options = {}) {
+    this.minNotesForPrompt = options.minNotesForPrompt || 3; // Minimum notes before prompting
+    this.coherenceThreshold = options.coherenceThreshold || 0.5; // Minimum coherence to prompt
+    this.urgencyThreshold = options.urgencyThreshold || 0.3; // Coherence drop triggers urgency
+    this.maxWaitTime = options.maxWaitTime || 10000; // Max time to wait (10s)
+    this.stateChangeThreshold = options.stateChangeThreshold || 0.2; // Significant state change
+  }
+
+  /**
+   * Decide if we should prompt now or wait for more context
+   * 
+   * @param {Object} currentState - Current state
+   * @param {Object} previousState - Previous state (if any)
+   * @param {import('./index.mjs').TemporalNote[]} temporalNotes - Temporal notes so far
+   * @param {Object} context - Additional context
+   * @returns {{shouldPrompt: boolean, reason: string, urgency: 'low'|'medium'|'high'}}
+   */
+  shouldPrompt(currentState, previousState, temporalNotes, context = {}) {
+    // 1. Check if we have minimum notes
+    if (temporalNotes.length < this.minNotesForPrompt) {
+      return {
+        shouldPrompt: false,
+        reason: `Insufficient notes (${temporalNotes.length} < ${this.minNotesForPrompt})`,
+        urgency: 'low'
+      };
+    }
+
+    // 2. Calculate temporal coherence
+    const aggregated = aggregateTemporalNotes(temporalNotes);
+    const coherence = aggregated.coherence || 0;
+
+    // 3. Check for significant state change
+    const stateChange = this.calculateStateChange(currentState, previousState);
+
+    // 4. Check for user action
+    const hasUserAction = this.hasRecentUserAction(temporalNotes, context);
+
+    // 5. Check for decision point
+    const isDecisionPoint = this.isDecisionPoint(currentState, context);
+
+    // 6. Check for coherence drop (urgency signal)
+    const coherenceDrop = this.detectCoherenceDrop(temporalNotes, aggregated);
+
+    // Decision logic (from research: prompt when decision needed, not on every change)
+    if (isDecisionPoint) {
+      return {
+        shouldPrompt: true,
+        reason: 'Decision point reached',
+        urgency: 'high'
+      };
+    }
+
+    if (coherenceDrop) {
+      return {
+        shouldPrompt: true,
+        reason: 'Coherence drop detected (quality issue)',
+        urgency: 'high'
+      };
+    }
+
+    if (hasUserAction && stateChange > this.stateChangeThreshold) {
+      return {
+        shouldPrompt: true,
+        reason: 'User action with significant state change',
+        urgency: 'medium'
+      };
+    }
+
+    if (coherence >= this.coherenceThreshold && stateChange > this.stateChangeThreshold) {
+      return {
+        shouldPrompt: true,
+        reason: 'Stable context with significant state change',
+        urgency: 'medium'
+      };
+    }
+
+    // Wait for more context
+    return {
+      shouldPrompt: false,
+      reason: `Context not sufficient (coherence: ${coherence.toFixed(2)}, stateChange: ${stateChange.toFixed(2)})`,
+      urgency: 'low'
+    };
+  }
+
+  /**
+   * Calculate state change magnitude
+   */
+  calculateStateChange(currentState, previousState) {
+    if (!previousState) return 1.0; // First state = maximum change
+
+    // Simple state change calculation (can be enhanced)
+    let change = 0.0;
+    let comparisons = 0;
+
+    // Compare scores if available
+    if (currentState.score !== undefined && previousState.score !== undefined) {
+      const scoreChange = Math.abs(currentState.score - previousState.score) / 10; // Normalize to 0-1
+      change += scoreChange;
+      comparisons++;
+    }
+
+    // Compare issues if available
+    if (currentState.issues && previousState.issues) {
+      const currentIssues = new Set(currentState.issues);
+      const previousIssues = new Set(previousState.issues);
+      const added = [...currentIssues].filter(i => !previousIssues.has(i)).length;
+      const removed = [...previousIssues].filter(i => !currentIssues.has(i)).length;
+      const issueChange = (added + removed) / Math.max(currentIssues.size + previousIssues.size, 1);
+      change += issueChange;
+      comparisons++;
+    }
+
+    // Compare game state if available
+    if (currentState.gameState && previousState.gameState) {
+      const gameStateChange = this.calculateGameStateChange(currentState.gameState, previousState.gameState);
+      change += gameStateChange;
+      comparisons++;
+    }
+
+    return comparisons > 0 ? change / comparisons : 0.0;
+  }
+
+  /**
+   * Calculate game state change
+   */
+  calculateGameStateChange(current, previous) {
+    // Simple comparison (can be enhanced)
+    const currentKeys = Object.keys(current || {});
+    const previousKeys = Object.keys(previous || {});
+    
+    const added = currentKeys.filter(k => !previousKeys.includes(k)).length;
+    const removed = previousKeys.filter(k => !currentKeys.includes(k)).length;
+    const changed = currentKeys.filter(k => 
+      previousKeys.includes(k) && 
+      JSON.stringify(current[k]) !== JSON.stringify(previous[k])
+    ).length;
+
+    const totalKeys = new Set([...currentKeys, ...previousKeys]).size;
+    return totalKeys > 0 ? (added + removed + changed) / totalKeys : 0.0;
+  }
+
+  /**
+   * Check for recent user action
+   */
+  hasRecentUserAction(temporalNotes, context) {
+    if (context.recentAction) return true;
+
+    // Check last few notes for interactions
+    const recentNotes = temporalNotes.slice(-3);
+    return recentNotes.some(note => 
+      note.step?.includes('interaction') ||
+      note.step?.includes('click') ||
+      note.step?.includes('action') ||
+      note.observation?.includes('user') ||
+      note.observation?.includes('clicked')
+    );
+  }
+
+  /**
+   * Check if this is a decision point
+   */
+  isDecisionPoint(currentState, context) {
+    // Decision points based on context
+    if (context.stage === 'decision' || context.stage === 'evaluation') return true;
+    if (context.testType === 'critical' || context.critical) return true;
+    if (context.goal && context.goalCompleted) return true;
+    
+    return false;
+  }
+
+  /**
+   * Detect coherence drop (quality issue signal)
+   */
+  detectCoherenceDrop(temporalNotes, currentAggregated) {
+    if (temporalNotes.length < 4) return false; // Need history to detect drop
+
+    // Get previous coherence (from notes without last one)
+    const previousNotes = temporalNotes.slice(0, -1);
+    const previousAggregated = aggregateTemporalNotes(previousNotes);
+    const previousCoherence = previousAggregated.coherence || 1.0;
+    const currentCoherence = currentAggregated.coherence || 1.0;
+
+    // Drop detected if coherence decreased significantly
+    const drop = previousCoherence - currentCoherence;
+    return drop > this.urgencyThreshold;
+  }
+
+  /**
+   * Calculate prompt urgency
+   */
+  calculatePromptUrgency(temporalContext, decision) {
+    if (decision.urgency === 'high') return 1.0;
+    if (decision.urgency === 'medium') return 0.6;
+    
+    // Low urgency, but check if we should wait
+    const coherence = temporalContext.coherence || 0;
+    const timeSinceLastPrompt = temporalContext.timeSinceLastPrompt || 0;
+    
+    // Increase urgency if coherence is good and it's been a while
+    if (coherence > 0.7 && timeSinceLastPrompt > 5000) {
+      return 0.4; // Medium-low
+    }
+    
+    return 0.2; // Low
+  }
+
+  /**
+   * Select optimal timing for requests
+   */
+  selectOptimalTiming(requests, temporalContext) {
+    const decisions = requests.map(req => ({
+      request: req,
+      decision: this.shouldPrompt(
+        req.currentState,
+        req.previousState,
+        req.temporalNotes || [],
+        req.context || {}
+      )
+    }));
+
+    // Separate by urgency
+    const urgent = decisions.filter(d => d.decision.urgency === 'high');
+    const medium = decisions.filter(d => d.decision.urgency === 'medium');
+    const low = decisions.filter(d => d.decision.urgency === 'low');
+
+    // Urgent: prompt immediately
+    // Medium: batch if context stable, otherwise prompt
+    // Low: wait or batch
+
+    const stable = temporalContext.coherence > 0.7;
+    const shouldBatch = stable && medium.length + low.length > 1;
+
+    return {
+      promptNow: urgent.map(d => d.request),
+      batch: shouldBatch ? [...medium, ...low].map(d => d.request) : medium.map(d => d.request),
+      wait: shouldBatch ? [] : low.map(d => d.request),
+      decisions
+    };
+  }
+}
+
+/**
+ * Create a temporal decision manager with default options
+ */
+export function createTemporalDecisionManager(options = {}) {
+  return new TemporalDecisionManager(options);
+}
+