@arclabs561/ai-visual-test 0.5.1

package/src/temporal-prompt-formatter.mjs

@@ -0,0 +1,219 @@
+/**
+ * Temporal Prompt Formatter
+ *
+ * Formats temporal notes (single-scale and multi-scale) for optimal VLM understanding.
+ * Provides different formatting strategies for different temporal aggregation types.
+ */
+
+import { formatNotesForPrompt } from './temporal.mjs';
+
+/**
+ * Format temporal notes for prompt inclusion
+ *
+ * Handles both single-scale (AggregatedTemporalNotes) and multi-scale (MultiScaleAggregation)
+ * temporal notes, formatting them optimally for VLM understanding.
+ *
+ * @param {import('./index.mjs').AggregatedTemporalNotes | import('./index.mjs').MultiScaleAggregation | Array} temporalNotes - Temporal notes (aggregated, multi-scale, or raw array)
+ * @param {Object} options - Formatting options
+ * @param {boolean} [options.includeMultiScale=true] - Include multi-scale insights if available
+ * @param {boolean} [options.naturalLanguage=true] - Use natural language formatting
+ * @returns {string} Formatted temporal context for prompt
+ */
+export function formatTemporalForPrompt(temporalNotes, options = {}) {
+  const {
+    includeMultiScale = true,
+    naturalLanguage = true
+  } = options;
+
+  if (!temporalNotes) {
+    return '';
+  }
+
+  // Handle raw array - should be aggregated first (caller's responsibility)
+  if (Array.isArray(temporalNotes)) {
+    return ''; // Don't format raw arrays here
+  }
+
+  // Handle multi-scale aggregation
+  if (temporalNotes.scales && !temporalNotes.windows) {
+    return formatMultiScaleForPrompt(temporalNotes, { naturalLanguage });
+  }
+
+  // Handle single-scale aggregation
+  if (temporalNotes.windows) {
+    return formatSingleScaleForPrompt(temporalNotes, { naturalLanguage });
+  }
+
+  return '';
+}
+
+/**
+ * Format single-scale aggregated notes for prompt
+ */
+function formatSingleScaleForPrompt(aggregated, options = {}) {
+  const { naturalLanguage = true } = options;
+
+  if (naturalLanguage) {
+    // Natural language format
+    const parts = [];
+
+    parts.push('TEMPORAL CONTEXT:');
+    parts.push(aggregated.summary || 'Previous observations over time.');
+
+    if (aggregated.windows && aggregated.windows.length > 0) {
+      parts.push('\nTime Windows:');
+      aggregated.windows.slice(-5).forEach((window, i) => {
+        const timeRange = window.timeRange || `window ${window.window || i + 1}`;
+        const score = window.avgScore !== null && window.avgScore !== undefined
+          ? `${window.avgScore.toFixed(1)}/10`
+          : 'N/A';
+        parts.push(`  ${timeRange}: Score ${score}, ${window.noteCount || 0} observations`);
+        if (window.observations) {
+          parts.push(`    Notes: ${window.observations.substring(0, 150)}${window.observations.length > 150 ? '...' : ''}`);
+        }
+      });
+    }
+
+    if (aggregated.coherence !== null && aggregated.coherence !== undefined) {
+      const coherenceDesc = aggregated.coherence > 0.7 ? 'high' : aggregated.coherence > 0.4 ? 'moderate' : 'low';
+      parts.push(`\nTemporal Coherence: ${(aggregated.coherence * 100).toFixed(0)}% (${coherenceDesc})`);
+    }
+
+    if (aggregated.conflicts && aggregated.conflicts.length > 0) {
+      parts.push(`\nCoherence Issues: ${aggregated.conflicts.length} potential conflicts detected`);
+    }
+
+    parts.push('\nWhen evaluating, consider how the current state relates to these temporal patterns and trends.');
+
+    return parts.join('\n');
+  } else {
+    // Structured format (original)
+    return formatNotesForPrompt(aggregated);
+  }
+}
+
+/**
+ * Format multi-scale aggregation for prompt
+ */
+function formatMultiScaleForPrompt(multiScale, options = {}) {
+  const { naturalLanguage = true } = options;
+
+  if (!multiScale.scales || Object.keys(multiScale.scales).length === 0) {
+    return '';
+  }
+
+  const parts = [];
+
+  if (naturalLanguage) {
+    parts.push('TEMPORAL CONTEXT (Multi-Scale Analysis):');
+    parts.push('The experience has been analyzed across multiple time scales:');
+    parts.push('');
+
+    // Order scales by time (shortest to longest)
+    const scaleOrder = ['immediate', 'short', 'medium', 'long'];
+    const orderedScales = scaleOrder
+      .filter(scale => multiScale.scales[scale])
+      .map(scale => [scale, multiScale.scales[scale]]);
+
+    orderedScales.forEach(([scaleName, scaleData]) => {
+      const scaleDescriptions = {
+        immediate: 'Instant perception (0.1s) - visual feedback, animations',
+        short: 'Quick interaction (1s) - button responses, immediate feedback',
+        medium: 'Short task (5s) - form filling, quick actions',
+        long: 'Longer session (30s) - overall experience, engagement'
+      };
+
+      parts.push(`${scaleName.toUpperCase()} Scale (${scaleDescriptions[scaleName] || scaleName}):`);
+
+      if (scaleData.windows && scaleData.windows.length > 0) {
+        const recentWindows = scaleData.windows.slice(-3); // Last 3 windows
+        recentWindows.forEach((window, i) => {
+          const timeRange = window.timeRange || `window ${window.window || i + 1}`;
+          const score = window.avgScore !== null && window.avgScore !== undefined
+            ? `${window.avgScore.toFixed(1)}/10`
+            : 'N/A';
+          parts.push(`  ${timeRange}: Score ${score}`);
+        });
+
+        if (scaleData.coherence !== null && scaleData.coherence !== undefined) {
+          const coherenceDesc = scaleData.coherence > 0.7 ? 'high' : scaleData.coherence > 0.4 ? 'moderate' : 'low';
+          parts.push(`  Coherence: ${(scaleData.coherence * 100).toFixed(0)}% (${coherenceDesc})`);
+        }
+      } else {
+        parts.push(`  No windows in this scale`);
+      }
+      parts.push('');
+    });
+
+    // Overall summary
+    if (multiScale.summary) {
+      parts.push(`Overall: ${multiScale.summary}`);
+    }
+
+    parts.push('\nWhen evaluating, consider patterns at different time scales:');
+    parts.push('- Immediate: Visual feedback and animation quality');
+    parts.push('- Short: Interaction responsiveness and quick feedback');
+    parts.push('- Medium: Task completion flow and user journey');
+    parts.push('- Long: Overall experience quality and engagement');
+
+    return parts.join('\n');
+  } else {
+    // Structured format
+    parts.push('TEMPORAL CONTEXT (Multi-Scale):');
+    parts.push(multiScale.summary || 'Multi-scale temporal analysis');
+    parts.push('');
+
+    Object.entries(multiScale.scales).forEach(([scaleName, scaleData]) => {
+      parts.push(`${scaleName.toUpperCase()} Scale:`);
+      parts.push(`  Windows: ${scaleData.windows?.length || 0}`);
+      parts.push(`  Coherence: ${scaleData.coherence ? (scaleData.coherence * 100).toFixed(0) : 'N/A'}%`);
+      if (scaleData.windows && scaleData.windows.length > 0) {
+        scaleData.windows.slice(-3).forEach(window => {
+          const timeRange = window.timeRange || `window ${window.window}`;
+          const score = window.avgScore !== null && window.avgScore !== undefined
+            ? `${window.avgScore.toFixed(1)}/10`
+            : 'N/A';
+          parts.push(`  ${timeRange}: ${score}`);
+        });
+      }
+      parts.push('');
+    });
+
+    return parts.join('\n');
+  }
+}
+
+/**
+ * Format temporal notes with optimal strategy
+ *
+ * Chooses the best formatting based on the type of temporal notes provided.
+ *
+ * @param {any} temporalNotes - Temporal notes (any format)
+ * @param {Object} options - Formatting options
+ * @returns {string} Formatted temporal context
+ */
+export function formatTemporalContext(temporalNotes, options = {}) {
+  if (!temporalNotes) {
+    return '';
+  }
+
+  // Raw array - return empty (should be aggregated first)
+  if (Array.isArray(temporalNotes)) {
+    return '';
+  }
+
+  // Multi-scale - use multi-scale formatter
+  if (temporalNotes.scales && !temporalNotes.windows) {
+    return formatMultiScaleForPrompt(temporalNotes, options);
+  }
+
+  // Single-scale - use single-scale formatter
+  if (temporalNotes.windows) {
+    return formatSingleScaleForPrompt(temporalNotes, options);
+  }
+
+  return '';
+}
+
+export { formatSingleScaleForPrompt, formatMultiScaleForPrompt };
+

package/src/temporal-validation.mjs

@@ -0,0 +1,159 @@
+/**
+ * Temporal Validation
+ * Input validation for temporal decision-making components
+ */
+
+import { MultiScaleError, PerceptionTimeError, SequentialContextError } from './temporal-errors.mjs';
+import { warn } from './logger.mjs';
+
+/**
+ * Validate temporal notes
+ */
+export function validateNotes(notes) {
+  if (!Array.isArray(notes)) {
+    throw new MultiScaleError('Notes must be an array', { received: typeof notes });
+  }
+  
+  const validNotes = [];
+  const invalidNotes = [];
+  
+  for (let i = 0; i < notes.length; i++) {
+    const note = notes[i];
+    
+    if (!note || typeof note !== 'object') {
+      invalidNotes.push({ index: i, reason: 'Not an object' });
+      continue;
+    }
+    
+    if (!note.timestamp && note.elapsed === undefined) {
+      invalidNotes.push({ index: i, reason: 'Missing timestamp or elapsed' });
+      continue;
+    }
+    
+    if (note.timestamp && typeof note.timestamp !== 'number') {
+      invalidNotes.push({ index: i, reason: 'Invalid timestamp type' });
+      continue;
+    }
+    
+    if (note.elapsed !== undefined && typeof note.elapsed !== 'number') {
+      invalidNotes.push({ index: i, reason: 'Invalid elapsed type' });
+      continue;
+    }
+    
+    validNotes.push(note);
+  }
+  
+  if (invalidNotes.length > 0) {
+    warn(`[Temporal] ${invalidNotes.length} invalid notes filtered out:`, invalidNotes);
+  }
+  
+  return validNotes;
+}
+
+/**
+ * Validate and sort notes
+ * Convenience function that validates and sorts in one step
+ */
+export function validateAndSortNotes(notes) {
+  const validNotes = validateNotes(notes);
+  return validNotes.sort((a, b) => (a.timestamp || 0) - (b.timestamp || 0));
+}
+
+/**
+ * Validate time scales
+ */
+export function validateTimeScales(timeScales) {
+  if (typeof timeScales !== 'object' || timeScales === null) {
+    throw new MultiScaleError('Time scales must be an object', { received: typeof timeScales });
+  }
+  
+  for (const [name, value] of Object.entries(timeScales)) {
+    if (typeof value !== 'number' || value <= 0) {
+      throw new MultiScaleError(`Invalid time scale ${name}: ${value}`, { 
+        scaleName: name, 
+        value,
+        type: typeof value
+      });
+    }
+  }
+  
+  return true;
+}
+
+/**
+ * Validate action for human perception time
+ */
+export function validateAction(action) {
+  const validActions = ['page-load', 'reading', 'interaction', 'evaluation', 'scanning', 'visual-appeal'];
+  
+  if (typeof action !== 'string') {
+    throw new PerceptionTimeError('Action must be a string', { received: typeof action });
+  }
+  
+  if (!validActions.includes(action)) {
+    throw new PerceptionTimeError(`Invalid action: ${action}`, { 
+      action,
+      validActions 
+    });
+  }
+  
+  return true;
+}
+
+/**
+ * Validate context for human perception time
+ */
+export function validatePerceptionContext(context) {
+  if (context === null || typeof context !== 'object') {
+    throw new PerceptionTimeError('Context must be an object', { received: typeof context });
+  }
+  
+  if (context.attentionLevel && !['focused', 'normal', 'distracted'].includes(context.attentionLevel)) {
+    throw new PerceptionTimeError(`Invalid attentionLevel: ${context.attentionLevel}`, {
+      attentionLevel: context.attentionLevel,
+      validLevels: ['focused', 'normal', 'distracted']
+    });
+  }
+  
+  if (context.actionComplexity && !['simple', 'normal', 'complex'].includes(context.actionComplexity)) {
+    throw new PerceptionTimeError(`Invalid actionComplexity: ${context.actionComplexity}`, {
+      actionComplexity: context.actionComplexity,
+      validComplexities: ['simple', 'normal', 'complex']
+    });
+  }
+  
+  if (context.contentLength !== undefined && (typeof context.contentLength !== 'number' || context.contentLength < 0)) {
+    throw new PerceptionTimeError('contentLength must be a non-negative number', {
+      contentLength: context.contentLength
+    });
+  }
+  
+  return true;
+}
+
+/**
+ * Validate sequential decision context options
+ */
+export function validateSequentialContextOptions(options) {
+  // Allow empty object or undefined (defaults will be used)
+  if (options === null || options === undefined) {
+    return true;
+  }
+  
+  // Allow empty object {} (defaults will be used)
+  if (typeof options !== 'object') {
+    throw new SequentialContextError('Options must be an object', { received: typeof options });
+  }
+  
+  // Only validate if maxHistory is explicitly provided
+  if (options.maxHistory !== undefined && options.maxHistory !== null) {
+    if (typeof options.maxHistory !== 'number' || options.maxHistory < 1) {
+      throw new SequentialContextError('maxHistory must be a positive number', {
+        maxHistory: options.maxHistory
+      });
+    }
+  }
+  
+  return true;
+}
+