@arclabs561/ai-visual-test 0.5.1 → 0.7.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arclabs561/ai-visual-test",
-  "version": "0.5.1",
-  "description": "AI-powered visual testing framework for web applications using Vision Language Models",
+  "version": "0.7.3",
+  "description": "Visual testing framework for web applications using Vision Language Models",
   "type": "module",
   "main": "src/index.mjs",
   "exports": {
@@ -16,11 +16,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "src/**/*.mjs",
+    "src/**/*",
     "index.d.ts",
-    "api/**/*.js",
-    "public/**/*.html",
-    "vercel.json",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -29,42 +26,6 @@
     "LICENSE",
     ".secretsignore.example"
   ],
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:validation": "node --test test/validation-*.test.mjs",
-    "test:unit": "node --test test/unit/*.test.mjs",
-    "test:integration": "node --test test/integration/*.test.mjs",
-    "test:e2e": "node --test test/e2e/*.test.mjs",
-    "test:datasets": "node --test test/dataset-*.test.mjs",
-    "playwright:check": "node scripts/ensure-playwright.mjs",
-    "playwright:install": "node scripts/ensure-playwright.mjs --install",
-    "playwright:setup": "node scripts/ensure-playwright.mjs --install --install-browsers",
-    "annotate": "node evaluation/utils/invoke-human-annotation.mjs",
-    "annotate:quick": "node evaluation/utils/quick-start-annotation.mjs",
-    "annotate:full": "node evaluation/utils/start-human-annotation.mjs",
-    "validate:annotations": "node evaluation/utils/validate-annotation-quality.mjs",
-    "validate:dataset": "node evaluation/utils/validate-dataset-quality.mjs",
-    "match:vllm": "node evaluation/utils/match-annotations-with-vllm.mjs",
-    "datasets:download": "node evaluation/utils/download-all-datasets.mjs",
-    "datasets:parse": "node evaluation/utils/parse-all-datasets.mjs",
-    "datasets:setup": "npm run datasets:download && npm run datasets:parse",
-    "docs": "node scripts/generate-docs.mjs",
-    "lint": "echo 'No linter configured'",
-    "prepublishOnly": "npm test",
-    "check:secrets": "node scripts/detect-secrets.mjs",
-    "check:quality": "node node_modules/@arclabs561/hookwise/src/hooks/code-quality.mjs || echo 'Hookwise not available'",
-    "check:docs": "node node_modules/@arclabs561/hookwise/src/hooks/doc-bloat.mjs || echo 'Hookwise not available'",
-    "check:security": "npm run check:secrets",
-    "check:test-performance": "node node_modules/@arclabs561/hookwise/src/hooks/test-performance.mjs || node scripts/analyze-test-performance.mjs",
-    "check:commit": "node node_modules/@arclabs561/hookwise/src/hooks/commit-msg.mjs .git/COMMIT_EDITMSG || echo 'Hookwise not available'",
-    "check:all": "npm run check:secrets && npx hookwise garden && npm run check:test-performance",
-    "garden": "npx hookwise garden",
-    "garden:enhanced": "node scripts/enhanced-garden.mjs",
-    "deprecate:old": "node scripts/deprecate-old-package.mjs",
-    "garden:watch": "node scripts/watch-garden.mjs",
-    "test:performance": "npm run check:test-performance",
-    "test:slow": "npm test 2>&1 | grep -E '✔.*\\([0-9]+\\.[0-9]+ms\\)' | sort -t'(' -k2 -nr | head -20"
-  },
   "keywords": [
     "visual-testing",
     "ai",
@@ -78,7 +39,11 @@
   "author": "arclabs561 <henry@henrywallace.io>",
   "license": "MIT",
   "dependencies": {
-    "dotenv": "^16.4.5"
+    "@anthropic-ai/sdk": "0.70.0",
+    "@google/generative-ai": "0.24.1",
+    "async-mutex": "0.5.0",
+    "dotenv": "^16.4.5",
+    "openai": "6.9.1"
   },
   "peerDependencies": {
     "@arclabs561/llm-utils": "*",
@@ -92,21 +57,15 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@types/node": "^22.10.1",
-    "async-mutex": "0.5.0",
-    "fast-check": "4.3.0",
-    "proper-lockfile": "4.1.2"
-  },
   "engines": {
     "node": ">=18.0.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/arclabs561/ai-visual-test.git"
+    "url": "https://github.com/arclabs561/ai-visual-test.git"
   },
   "homepage": "https://github.com/arclabs561/ai-visual-test#readme",
   "bugs": {
     "url": "https://github.com/arclabs561/ai-visual-test/issues"
   }
-}
+}

package/src/batch-optimizer.mjs

@@ -218,6 +218,25 @@ export class BatchOptimizer {
       } catch (metricsError) {
         warn(`[BatchOptimizer] Error updating rejection metrics: ${metricsError.message}`);
       }
+      
+      // Log batch optimizer rejection (weighted: rejections are critical)
+      // Use dynamic import with proper error handling to prevent unhandled promise rejections
+      import('./utils/performance-logger.mjs')
+        .then(({ logBatchOptimizer }) => {
+          logBatchOptimizer({
+            event: 'reject',
+            queueDepth: this.queue.length,
+            maxQueueSize: this.maxQueueSize,
+            activeRequests: this.activeRequests,
+            maxConcurrency: this.maxConcurrency,
+            reason: 'Queue full - preventing memory leak'
+          });
+        })
+        .catch((importError) => {
+          // Log to console if performance logger unavailable (better than silent failure)
+          warn(`[BatchOptimizer] Performance logger unavailable: ${importError.message}`);
+        });
+      
       warn(`[BatchOptimizer] Queue is full (${this.queue.length}/${this.maxQueueSize}). Rejecting request to prevent memory leak. Total rejections: ${this.metrics.queueRejections}`);
       throw new TimeoutError(
         `Queue is full (${this.queue.length}/${this.maxQueueSize}). Too many concurrent requests.`,
@@ -236,6 +255,26 @@ export class BatchOptimizer {
       
       const timeoutId = setTimeout(() => {
         timeoutFired = true;
+        
+        // Log batch optimizer timeout (weighted: timeouts are critical)
+        // Use dynamic import with proper error handling to prevent unhandled promise rejections
+        import('./utils/performance-logger.mjs')
+          .then(({ logBatchOptimizer }) => {
+            logBatchOptimizer({
+              event: 'timeout',
+              queueDepth: this.queue.length,
+              maxQueueSize: this.maxQueueSize,
+              activeRequests: this.activeRequests,
+              maxConcurrency: this.maxConcurrency,
+              waitTime: Date.now() - queueStartTime,
+              reason: 'Request timeout - queue wait exceeded limit'
+            });
+          })
+          .catch((importError) => {
+            // Log to console if performance logger unavailable (better than silent failure)
+            warn(`[BatchOptimizer] Performance logger unavailable: ${importError.message}`);
+          });
+        
         // Remove from queue if still waiting
         // CRITICAL FIX: Use stored queueEntry reference instead of searching by resolve function
         // The resolve function is wrapped, so direct comparison might not work

package/src/cache.mjs

@@ -1,7 +1,7 @@
 /**
  * VLLM Cache
  *
- * Provides persistent caching for VLLM API calls to reduce costs and improve performance.
+ * Provides persistent caching for VLLM API calls (vision) and text-only LLM calls to reduce costs and improve performance.
  * Uses file-based storage for cache persistence across test runs.
  *
  * BUGS FIXED (2025-01):
@@ -15,6 +15,7 @@
  * - Why separate: Different persistence strategy (file vs memory), different lifetime (7 days vs process lifetime),
  *   different failure domain (disk errors don't affect in-memory batching), minimal data overlap (<5%)
  * - No coordination with BatchOptimizer cache or TemporalPreprocessing cache (by design - they serve different purposes)
+ * - Supports both vision LLM calls (with images) and text-only LLM calls (no images)
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'fs';
@@ -73,36 +74,106 @@ export function initCache(cacheDir) {
 }
 
 /**
- * Generate cache key from image path, prompt, and context
+ * Generate cache key from image path, prompt, and context (for vision LLM calls)
  *
  * @param {string} imagePath - Path to image file
  * @param {string} prompt - Validation prompt
  * @param {import('./index.mjs').ValidationContext} [context={}] - Validation context
  * @returns {string} SHA-256 hash of cache key
  */
+/**
+ * Normalize and sort object keys for deterministic JSON serialization
+ */
+function deterministicStringify(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return JSON.stringify(obj);
+  }
+  if (Array.isArray(obj)) {
+    return '[' + obj.map(deterministicStringify).join(',') + ']';
+  }
+  const sortedKeys = Object.keys(obj).sort();
+  const pairs = sortedKeys.map(key => {
+    return JSON.stringify(key) + ':' + deterministicStringify(obj[key]);
+  });
+  return '{' + pairs.join(',') + '}';
+}
+
 export function generateCacheKey(imagePath, prompt, context = {}) {
-  // NOTE: Don't truncate cache keys - it causes collisions!
-  //
-  // The bug: Truncating prompt (1000 chars) and gameState (500 chars) means:
-  // - Different prompts with same first 1000 chars = same cache key = wrong cache hit
-  // - Different game states with same first 500 chars = same cache key = wrong cache hit
+  // Content-addressed: hash image bytes, not the file path.
+  // This ensures cache invalidation when a screenshot is regenerated
+  // to the same path (e.g. /tmp/vlm_magic.png).
   //
-  // The fix: Hash the FULL content, don't truncate
-  // SHA-256 handles arbitrary length, so there's no reason to truncate
-  //
-  // Why truncation existed: Probably to keep keys "manageable", but it's dangerous
-  // Better approach: Hash full content, collisions are cryptographically unlikely
+  // For multi-image keys, imagePath may be a pipe-delimited string
+  // like "path1|path2" from judge.mjs.
+  const pathStr = imagePath || '';
+  const paths = pathStr.includes('|') ? pathStr.split('|') : [pathStr];
+  const imageHashes = paths.map(p => {
+    try {
+      const bytes = readFileSync(p);
+      return createHash('sha256').update(bytes).digest('hex');
+    } catch (error) {
+      // File unreadable (deleted, permissions) -- fall back to path hash
+      // so the key is still deterministic for error cases.
+      warn(`Cannot read image for cache key, falling back to path hash: ${p}`);
+      return createHash('sha256').update(p).digest('hex');
+    }
+  });
+  const imageDigest = imageHashes.length === 1
+    ? imageHashes[0]
+    : createHash('sha256').update(imageHashes.join(':')).digest('hex');
+
+  // Build key data with deterministic structure
   const keyData = {
-    imagePath,
+    type: 'vision', // Distinguish from text-only calls
+    imageDigest, // SHA-256 of image bytes (content-addressed)
     prompt, // Full prompt, not truncated
     testType: context.testType || '',
     frame: context.frame || '',
     score: context.score || '',
-    viewport: context.viewport ? JSON.stringify(context.viewport) : '',
-    gameState: context.gameState ? JSON.stringify(context.gameState) : '' // Full game state, not truncated
+    // Use deterministic stringify for nested objects to ensure consistent keys
+    viewport: context.viewport ? deterministicStringify(context.viewport) : '',
+    gameState: context.gameState ? deterministicStringify(context.gameState) : '' // Full game state, not truncated
   };
 
-  const keyString = JSON.stringify(keyData);
+  // Use deterministic stringify to ensure consistent key generation
+  // even if object property order varies
+  const keyString = deterministicStringify(keyData);
+  return createHash('sha256').update(keyString).digest('hex');
+}
+
+/**
+ * Generate cache key for text-only LLM calls
+ *
+ * @param {string} prompt - Text prompt
+ * @param {string} provider - LLM provider (e.g., 'gemini', 'openai', 'claude')
+ * @param {{
+ *   model?: string | null;
+ *   temperature?: number;
+ *   maxTokens?: number;
+ *   tier?: string;
+ * }} [options={}] - LLM call options
+ * @returns {string} SHA-256 hash of cache key
+ */
+export function generateTextLLMCacheKey(prompt, provider, options = {}) {
+  const {
+    model = null,
+    temperature = 0.1,
+    maxTokens = 1000,
+    tier = null
+  } = options;
+
+  const keyData = {
+    type: 'text', // Distinguish from vision calls
+    prompt, // Full prompt, not truncated
+    provider,
+    model,
+    temperature,
+    maxTokens,
+    tier
+  };
+
+  // Use deterministic stringify for consistent cache keys
+  const keyString = deterministicStringify(keyData);
   return createHash('sha256').update(keyString).digest('hex');
 }
 
@@ -208,6 +279,33 @@ async function saveCache(cache) {
 
     // Apply size limits (LRU eviction: keep most recently accessed)
     const entriesToKeep = entries.slice(-MAX_CACHE_SIZE);
+    const evictedCount = entries.length - entriesToKeep.length;
+    
+    // Log cache eviction (weighted: evictions are important for cache health)
+    if (evictedCount > 0) {
+      // Use dynamic import with proper error handling to prevent unhandled promise rejections
+      import('./utils/performance-logger.mjs')
+        .then(({ logCacheOperation }) => {
+          logCacheOperation({
+            operation: 'evict',
+            cacheSize: entriesToKeep.length,
+            maxSize: MAX_CACHE_SIZE,
+            reason: `LRU eviction: ${evictedCount} entries removed`
+          });
+        })
+        .catch(async (importError) => {
+          // Log to logger if performance logger unavailable (better than silent failure)
+          if (process.env.DEBUG_CACHE) {
+            try {
+              const { warn } = await import('./logger.mjs');
+              warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            } catch {
+              // Fallback to console if logger also unavailable
+              console.warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            }
+          }
+        });
+    }
 
     for (const { key, value, timestamp } of entriesToKeep) {
       const entry = {
@@ -346,6 +444,32 @@ export function getCached(imagePath, prompt, context = {}) {
     const age = Date.now() - originalTimestamp;
     if (age > MAX_CACHE_AGE) {
       cache.delete(key); // Remove expired entry
+      
+      // Log cache expiration (weighted: expirations are important for cache health)
+      // Use dynamic import with proper error handling to prevent unhandled promise rejections
+      import('./utils/performance-logger.mjs')
+        .then(({ logCacheOperation }) => {
+          const currentCache = getCache();
+          logCacheOperation({
+            operation: 'expire',
+            cacheSize: currentCache.size,
+            maxSize: MAX_CACHE_SIZE,
+            reason: `Entry expired (age: ${Math.floor(age / (1000 * 60 * 60 * 24))} days)`
+          });
+        })
+        .catch(async (importError) => {
+          // Log to logger if performance logger unavailable (better than silent failure)
+          if (process.env.DEBUG_CACHE) {
+            try {
+              const { warn } = await import('./logger.mjs');
+              warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            } catch {
+              // Fallback to console if logger also unavailable
+              console.warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            }
+          }
+        });
+      
       return null;
     }
   }
@@ -404,6 +528,107 @@ export function clearCache() {
   });
 }
 
+/**
+ * Get cached text-only LLM response
+ *
+ * @param {string} prompt - Text prompt
+ * @param {string} provider - LLM provider
+ * @param {{
+ *   model?: string | null;
+ *   temperature?: number;
+ *   maxTokens?: number;
+ *   tier?: string;
+ * }} [options={}] - LLM call options
+ * @returns {string | null} Cached response or null if not found
+ */
+export function getCachedTextLLM(prompt, provider, options = {}) {
+  const cache = getCache();
+  const key = generateTextLLMCacheKey(prompt, provider, options);
+  const cached = cache.get(key);
+
+  if (cached) {
+    // Update access time for LRU eviction
+    cached._lastAccessed = Date.now();
+
+    // Check expiration based on original timestamp
+    const originalTimestamp = cached._originalTimestamp || cached._lastAccessed;
+    const age = Date.now() - originalTimestamp;
+    if (age > MAX_CACHE_AGE) {
+      cache.delete(key); // Remove expired entry
+      
+      // Log cache expiration
+      // Use dynamic import with proper error handling to prevent unhandled promise rejections
+      import('./utils/performance-logger.mjs')
+        .then(({ logCacheOperation }) => {
+          const currentCache = getCache();
+          logCacheOperation({
+            operation: 'expire',
+            cacheSize: currentCache.size,
+            maxSize: MAX_CACHE_SIZE,
+            reason: `Text LLM entry expired (age: ${Math.floor(age / (1000 * 60 * 60 * 24))} days)`
+          });
+        })
+        .catch(async (importError) => {
+          // Log to logger if performance logger unavailable (better than silent failure)
+          if (process.env.DEBUG_CACHE) {
+            try {
+              const { warn } = await import('./logger.mjs');
+              warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            } catch {
+              // Fallback to console if logger also unavailable
+              console.warn(`[Cache] Performance logger unavailable: ${importError.message}`);
+            }
+          }
+        });
+      
+      return null;
+    }
+
+    // Return the cached response (stored as 'response' field for text-only calls)
+    return cached.response || null;
+  }
+
+  return null;
+}
+
+/**
+ * Set cached text-only LLM response
+ *
+ * @param {string} prompt - Text prompt
+ * @param {string} provider - LLM provider
+ * @param {{
+ *   model?: string | null;
+ *   temperature?: number;
+ *   maxTokens?: number;
+ *   tier?: string;
+ * }} [options={}] - LLM call options
+ * @param {string} response - LLM response to cache
+ * @returns {void}
+ */
+export function setCachedTextLLM(prompt, provider, options, response) {
+  const cache = getCache();
+  const key = generateTextLLMCacheKey(prompt, provider, options);
+  const now = Date.now();
+
+  // Check if this is a new entry or updating existing
+  const existing = cache.get(key);
+  const originalTimestamp = existing?._originalTimestamp || now;
+
+  // Store response with metadata for cache management
+  const resultWithMetadata = {
+    response, // Store the text response
+    _lastAccessed: now,
+    _originalTimestamp: originalTimestamp
+  };
+
+  cache.set(key, resultWithMetadata);
+
+  // Save cache (async, fire-and-forget)
+  saveCache(cache).catch(error => {
+    warn(`[VLLM Cache] Failed to save text LLM cache (non-blocking): ${error.message}`);
+  });
+}
+
 /**
  * Get cache statistics
  *

package/src/config.mjs

@@ -8,97 +8,11 @@
 import { ConfigError } from './errors.mjs';
 import { loadEnv } from './load-env.mjs';
 import { API_CONSTANTS } from './constants.mjs';
+import { MODEL_TIERS, PROVIDER_CONFIGS } from './provider-data.mjs';
 
-// Load .env file automatically on module load
+// Load .env file on module load
 loadEnv();
 
-/**
- * Model tiers for each provider
- * Updated January 2025: Latest models - Gemini 2.5 Pro, GPT-5, Claude 4.5 Sonnet
- * 
- * GROQ INTEGRATION (2025):
- * - Groq added for high-frequency decisions (10-60Hz temporal decisions)
- * - ~0.22s latency (vs 1-3s for other providers)
- * - 185-276 tokens/sec throughput
- * - OpenAI-compatible API
- * - Cost-competitive, free tier available
- * - Best for: Fast tier decisions, high-Hz temporal decisions, real-time applications
- */
-const MODEL_TIERS = {
-  gemini: {
-    fast: 'gemini-2.0-flash-exp',      // Fast, outperforms 1.5 Pro (2x speed)
-    balanced: 'gemini-2.5-pro',        // Best balance (2025 leader, released June 2025)
-    best: 'gemini-2.5-pro'              // Best quality (top vision-language model, 1M+ context)
-  },
-  openai: {
-    fast: 'gpt-4o-mini',               // Fast, cheaper
-    balanced: 'gpt-5',                 // Best balance (released August 2025, unified reasoning)
-    best: 'gpt-5'                      // Best quality (state-of-the-art multimodal, August 2025)
-  },
-  claude: {
-    fast: 'claude-3-5-haiku-20241022', // Fast, cheaper
-    balanced: 'claude-sonnet-4-5',     // Best balance (released September 2025, enhanced vision)
-    best: 'claude-sonnet-4-5'          // Best quality (latest flagship, September 2025)
-  },
-  groq: {
-    // NOTE: Groq vision support requires different model
-    // For vision: meta-llama/llama-4-scout-17b-16e-instruct (preview, supports vision)
-    // For text-only: llama-3.3-70b-versatile is fastest (~0.22s latency)
-    fast: 'meta-llama/llama-4-scout-17b-16e-instruct',   // Vision-capable, fastest Groq option
-    balanced: 'meta-llama/llama-4-scout-17b-16e-instruct', // Vision-capable, balanced
-    best: 'meta-llama/llama-4-scout-17b-16e-instruct'   // Vision-capable, best quality (preview)
-    // WARNING: Groq vision models are preview-only. Text-only: use llama-3.3-70b-versatile
-  }
-};
-
-/**
- * Default provider configurations
- * 
- * GROQ INTEGRATION:
- * - OpenAI-compatible API (easy migration)
- * - ~0.22s latency (10x faster than typical providers)
- * - Best for high-frequency decisions (10-60Hz temporal decisions)
- * - Free tier available for testing
- */
-const PROVIDER_CONFIGS = {
-  gemini: {
-    name: 'gemini',
-    apiUrl: 'https://generativelanguage.googleapis.com/v1beta',
-    model: 'gemini-2.5-pro',            // Latest: Released June 2025, top vision-language model, 1M+ context
-    freeTier: true,
-    pricing: { input: 1.25, output: 5.00 }, // Updated pricing for 2.5 Pro
-    priority: 1 // Higher priority = preferred
-  },
-  openai: {
-    name: 'openai',
-    apiUrl: 'https://api.openai.com/v1',
-    model: 'gpt-5',                     // Latest: Released August 2025, state-of-the-art multimodal
-    freeTier: false,
-    pricing: { input: 5.00, output: 15.00 }, // Updated pricing for gpt-5
-    priority: 2
-  },
-  claude: {
-    name: 'claude',
-    apiUrl: 'https://api.anthropic.com/v1',
-    model: 'claude-sonnet-4-5',         // Latest: Released September 2025, enhanced vision capabilities
-    freeTier: false,
-    pricing: { input: 3.00, output: 15.00 }, // Updated pricing for 4.5
-    priority: 3
-  },
-  groq: {
-    name: 'groq',
-    apiUrl: 'https://api.groq.com/openai/v1', // OpenAI-compatible endpoint
-    model: 'meta-llama/llama-4-scout-17b-16e-instruct',   // Vision-capable (preview), ~0.22s latency
-    freeTier: true,                      // Free tier available
-    pricing: { input: 0.59, output: 0.79 }, // Actual 2025 pricing: $0.59/$0.79 per 1M tokens (real-time API)
-    priority: 0,                         // Highest priority for high-frequency decisions
-    latency: 220,                        // ~0.22s latency in ms (10x faster than typical)
-    throughput: 200,                     // ~200 tokens/sec average
-    visionSupported: true               // llama-4-scout-17b-16e-instruct supports vision (preview)
-    // Text-only alternative: llama-3.3-70b-versatile (faster, no vision)
-  }
-};
-
 /**
  * Create configuration from environment or options
  *
@@ -111,12 +25,13 @@ export function createConfig(options = {}) {
     apiKey = null,
     env = process.env,
     cacheDir = null,
-    cacheEnabled = true,
+    cacheEnabled = process.env.DISABLE_LLM_CACHE !== 'true',
     maxConcurrency = API_CONSTANTS.DEFAULT_MAX_CONCURRENCY,
     timeout = API_CONSTANTS.DEFAULT_TIMEOUT_MS,
     verbose = false,
     modelTier = null, // 'fast', 'balanced', 'best', or null for default
-    model = null      // Explicit model override
+    model = null,     // Explicit model override
+    anchors = null    // Domain visual anchors: { domain?, positive?: string[], negative?: string[] }
   } = options;
 
   // Auto-detect provider if not specified
@@ -154,11 +69,39 @@ export function createConfig(options = {}) {
     providerConfig.model = env.VLM_MODEL;
   }
 
+  // Normalize anchors: ensure arrays, filter empty/invalid entries.
+  // Each entry can be a plain string or { text?, image?, label?, dimension? }.
+  let normalizedAnchors = null;
+  if (anchors && typeof anchors === 'object') {
+    const normalizeEntries = (arr) => {
+      if (!Array.isArray(arr)) return [];
+      return arr.filter(entry => {
+        if (typeof entry === 'string') return entry.trim().length > 0;
+        if (entry && typeof entry === 'object') {
+          return (entry.text && typeof entry.text === 'string' && entry.text.trim()) ||
+                 (entry.image && typeof entry.image === 'string' && entry.image.trim());
+        }
+        return false;
+      });
+    };
+    const pos = normalizeEntries(anchors.positive);
+    const neg = normalizeEntries(anchors.negative);
+    const hasDomain = anchors.domain && typeof anchors.domain === 'string' && anchors.domain.trim();
+
+    if (pos.length > 0 || neg.length > 0 || hasDomain) {
+      normalizedAnchors = {};
+      if (hasDomain) normalizedAnchors.domain = anchors.domain.trim();
+      if (pos.length > 0) normalizedAnchors.positive = pos;
+      if (neg.length > 0) normalizedAnchors.negative = neg;
+    }
+  }
+
   return {
     provider: selectedProvider,
     apiKey: selectedApiKey,
     providerConfig,
     enabled: !!selectedApiKey,
+    anchors: normalizedAnchors,
     cache: {
       enabled: cacheEnabled,
       dir: cacheDir
@@ -265,4 +208,3 @@ export function getProvider(providerName = null) {
   const provider = providerName || config.provider;
   return PROVIDER_CONFIGS[provider] || PROVIDER_CONFIGS.gemini;
 }
-

package/src/constants.mjs

@@ -78,3 +78,57 @@ export const UNCERTAINTY_CONSTANTS = {
   EDGE_CASE_SELF_CONSISTENCY_N: 3
 };
 
+/**
+ * API Endpoint Configuration (for serverless functions)
+ */
+export const API_ENDPOINT_CONSTANTS = {
+  /** Maximum image size in bytes (10MB) */
+  MAX_IMAGE_SIZE: 10 * 1024 * 1024,
+  
+  /** Maximum prompt length in characters */
+  MAX_PROMPT_LENGTH: 5000,
+  
+  /** Maximum context size in bytes */
+  MAX_CONTEXT_SIZE: 10000,
+  
+  /** Default rate limit window in milliseconds (1 minute) */
+  RATE_LIMIT_WINDOW_MS: 60 * 1000,
+  
+  /** Default maximum requests per window */
+  RATE_LIMIT_MAX_REQUESTS: 10
+};
+
+/**
+ * Retry Configuration
+ */
+export const RETRY_CONSTANTS = {
+  /** Default base delay for exponential backoff in milliseconds (1 second) */
+  DEFAULT_BASE_DELAY_MS: 1000,
+  
+  /** Default maximum delay for exponential backoff in milliseconds (30 seconds) */
+  DEFAULT_MAX_DELAY_MS: 30000,
+  
+  /** Default maximum number of retries */
+  DEFAULT_MAX_RETRIES: 3,
+  
+  /** Jitter amount as percentage of delay (±25%) */
+  JITTER_PERCENTAGE: 0.25
+};
+
+/**
+ * Validation Configuration
+ */
+export const VALIDATION_CONSTANTS = {
+  /** Maximum prompt length for validation (10k characters) */
+  MAX_PROMPT_LENGTH: 10000,
+  
+  /** Maximum context size in bytes */
+  MAX_CONTEXT_SIZE: 50000,
+  
+  /** Minimum timeout in milliseconds */
+  MIN_TIMEOUT_MS: 1000,
+  
+  /** Maximum timeout in milliseconds (5 minutes) */
+  MAX_TIMEOUT_MS: 300000
+};
+