handhold-sdk 1.0.0

package/src/intent/ActionVerbMap.js

@@ -0,0 +1,324 @@
+/**
+ * Hand Hold SDK - Action Verb Map
+ * Maps common button/link text to canonical action verbs
+ */
+
+const ACTION_VERB_MAP = {
+  // Approval actions
+  'approve': 'approve',
+  'confirm': 'confirm',
+  'accept': 'approve',
+  'authorize': 'approve',
+  'validate': 'approve',
+  'verify': 'approve',
+  'ok': 'confirm',
+  'yes': 'confirm',
+
+  // Creation actions
+  'create': 'create',
+  'add': 'create',
+  'new': 'create',
+  'insert': 'create',
+  'plus': 'create',
+  '+': 'create',
+
+  // Submission actions
+  'submit': 'submit',
+  'send': 'submit',
+  'post': 'submit',
+  'publish': 'submit',
+  'apply': 'submit',
+
+  // Save actions
+  'save': 'save',
+  'store': 'save',
+  'keep': 'save',
+  'preserve': 'save',
+
+  // Update actions
+  'update': 'update',
+  'edit': 'edit',
+  'modify': 'edit',
+  'change': 'edit',
+  'revise': 'edit',
+
+  // Delete actions
+  'delete': 'delete',
+  'remove': 'delete',
+  'trash': 'delete',
+  'discard': 'delete',
+  'clear': 'delete',
+  'erase': 'delete',
+
+  // Download/Export actions
+  'download': 'download',
+  'export': 'export',
+  'extract': 'export',
+  'get': 'download',
+
+  // Upload/Import actions
+  'upload': 'upload',
+  'import': 'import',
+  'load': 'import',
+
+  // Execution actions
+  'run': 'run',
+  'execute': 'run',
+  'process': 'run',
+  'start': 'run',
+  'begin': 'run',
+  'launch': 'run',
+  'trigger': 'run',
+
+  // View actions
+  'view': 'view',
+  'see': 'view',
+  'show': 'view',
+  'display': 'view',
+  'open': 'view',
+  'preview': 'view',
+  'look': 'view',
+
+  // Search actions
+  'search': 'search',
+  'find': 'search',
+  'lookup': 'search',
+  'query': 'search',
+
+  // Filter actions
+  'filter': 'filter',
+  'sort': 'filter',
+  'refine': 'filter',
+
+  // Cancel actions
+  'cancel': 'cancel',
+  'abort': 'cancel',
+  'stop': 'cancel',
+  'close': 'cancel',
+  'dismiss': 'cancel',
+  'back': 'cancel',
+  'exit': 'cancel',
+  'no': 'cancel',
+
+  // Print actions
+  'print': 'print',
+
+  // Review actions
+  'review': 'review',
+  'check': 'review',
+  'inspect': 'review',
+  'examine': 'review',
+
+  // Generate actions
+  'generate': 'generate',
+  'produce': 'generate',
+  'build': 'generate',
+  'make': 'generate',
+
+  // Copy actions
+  'copy': 'copy',
+  'duplicate': 'copy',
+  'clone': 'copy',
+
+  // Share actions
+  'share': 'share',
+  'invite': 'share',
+
+  // Refresh actions
+  'refresh': 'refresh',
+  'reload': 'refresh',
+  'sync': 'refresh',
+
+  // Navigate actions
+  'navigate': 'navigate',
+  'go': 'navigate',
+  'next': 'navigate',
+  'previous': 'navigate',
+  'prev': 'navigate',
+  'continue': 'navigate',
+
+  // Help actions
+  'help': 'help',
+  'support': 'help',
+  'assist': 'help',
+
+  // Login/Logout actions
+  'login': 'login',
+  'signin': 'login',
+  'sign-in': 'login',
+  'logout': 'logout',
+  'signout': 'logout',
+  'sign-out': 'logout',
+
+  // Enable/Disable actions
+  'enable': 'enable',
+  'activate': 'enable',
+  'disable': 'disable',
+  'deactivate': 'disable',
+
+  // Connect/Disconnect actions
+  'connect': 'connect',
+  'link': 'connect',
+  'disconnect': 'disconnect',
+  'unlink': 'disconnect',
+
+  // Schedule actions
+  'schedule': 'schedule',
+  'plan': 'schedule',
+  'book': 'schedule',
+  'reserve': 'schedule',
+
+  // Assign actions
+  'assign': 'assign',
+  'delegate': 'assign',
+  'transfer': 'assign',
+
+  // Archive actions
+  'archive': 'archive',
+  'store': 'archive',
+
+  // Restore actions
+  'restore': 'restore',
+  'recover': 'restore',
+  'undo': 'restore',
+
+  // Compare actions
+  'compare': 'compare',
+  'diff': 'compare',
+
+  // Select actions
+  'select': 'select',
+  'choose': 'select',
+  'pick': 'select',
+
+  // Pay/Purchase actions
+  'pay': 'pay',
+  'purchase': 'pay',
+  'buy': 'pay',
+  'checkout': 'pay',
+};
+
+// Reverse map for label generation
+const VERB_LABELS = {
+  'approve': 'Approve',
+  'confirm': 'Confirm',
+  'create': 'Create',
+  'submit': 'Submit',
+  'save': 'Save',
+  'update': 'Update',
+  'edit': 'Edit',
+  'delete': 'Delete',
+  'download': 'Download',
+  'export': 'Export',
+  'upload': 'Upload',
+  'import': 'Import',
+  'run': 'Run',
+  'view': 'View',
+  'search': 'Search',
+  'filter': 'Filter',
+  'cancel': 'Cancel',
+  'print': 'Print',
+  'review': 'Review',
+  'generate': 'Generate',
+  'copy': 'Copy',
+  'share': 'Share',
+  'refresh': 'Refresh',
+  'navigate': 'Navigate',
+  'help': 'Help',
+  'login': 'Login',
+  'logout': 'Logout',
+  'enable': 'Enable',
+  'disable': 'Disable',
+  'connect': 'Connect',
+  'disconnect': 'Disconnect',
+  'schedule': 'Schedule',
+  'assign': 'Assign',
+  'archive': 'Archive',
+  'restore': 'Restore',
+  'compare': 'Compare',
+  'select': 'Select',
+  'pay': 'Pay',
+};
+
+class ActionVerbMap {
+  /**
+   * Get canonical verb for a word
+   * @param {string} word - Input word
+   * @returns {string|null} - Canonical verb or null
+   */
+  static get(word) {
+    if (!word) return null;
+    return ACTION_VERB_MAP[word.toLowerCase()] || null;
+  }
+
+  /**
+   * Get label for a canonical verb
+   * @param {string} verb - Canonical verb
+   * @returns {string} - Human-readable label
+   */
+  static getLabel(verb) {
+    return VERB_LABELS[verb] || verb.charAt(0).toUpperCase() + verb.slice(1);
+  }
+
+  /**
+   * Check if a word is an action verb
+   * @param {string} word - Input word
+   * @returns {boolean}
+   */
+  static isActionVerb(word) {
+    if (!word) return false;
+    return ACTION_VERB_MAP.hasOwnProperty(word.toLowerCase());
+  }
+
+  /**
+   * Get all action verbs
+   * @returns {Object} - Map of verbs
+   */
+  static getAll() {
+    return { ...ACTION_VERB_MAP };
+  }
+
+  /**
+   * Get all canonical verbs
+   * @returns {string[]} - Array of canonical verbs
+   */
+  static getCanonicalVerbs() {
+    return Object.keys(VERB_LABELS);
+  }
+
+  /**
+   * Find matching verb in a text string
+   * @param {string} text - Text to search
+   * @returns {Object|null} - { verb, position } or null
+   */
+  static findInText(text) {
+    if (!text) return null;
+
+    const words = text.toLowerCase().split(/\s+/);
+    
+    // Check first word (most likely to be the action)
+    if (words[0] && ACTION_VERB_MAP[words[0]]) {
+      return {
+        word: words[0],
+        verb: ACTION_VERB_MAP[words[0]],
+        position: 0,
+      };
+    }
+
+    // Check other words
+    for (let i = 1; i < words.length; i++) {
+      if (ACTION_VERB_MAP[words[i]]) {
+        return {
+          word: words[i],
+          verb: ACTION_VERB_MAP[words[i]],
+          position: i,
+        };
+      }
+    }
+
+    return null;
+  }
+}
+
+export default ActionVerbMap;
+export { ACTION_VERB_MAP, VERB_LABELS };

package/src/intent/IntentExtractor.js

@@ -0,0 +1,317 @@
+/**
+ * Hand Hold SDK - Intent Extractor
+ * Rule-based intent extraction from UI elements (no LLM required)
+ */
+
+import ActionVerbMap from './ActionVerbMap.js';
+import { toSnakeCase, toTitleCase } from '../utils/stringUtils.js';
+
+class IntentExtractor {
+  /**
+   * Extract intents from UI elements
+   * @param {Array} uiElements - Array of UI element objects
+   * @param {string} route - Current page route
+   * @param {Object} options - { maxIntents: 6 }
+   * @returns {Array} - Array of intent objects
+   */
+  static extract(uiElements, route, options = {}) {
+    const maxIntents = options.maxIntents || 6;
+    const intents = [];
+    const routeContext = this._extractRouteContext(route);
+
+    // Process buttons first (highest priority)
+    const buttons = uiElements.filter(el => el.role === 'button' && !el.disabled);
+    for (const button of buttons) {
+      const intent = this._extractIntentFromElement(button, routeContext);
+      if (intent) {
+        intents.push({
+          ...intent,
+          source_element: button.selector,
+          element_position: button.position,
+          element_type: 'button',
+        });
+      }
+    }
+
+    // Process links with action text (medium priority)
+    const links = uiElements.filter(el => el.role === 'link');
+    for (const link of links) {
+      const intent = this._extractIntentFromElement(link, routeContext);
+      if (intent) {
+        intent.confidence *= 0.85; // Lower confidence for links
+        intents.push({
+          ...intent,
+          source_element: link.selector,
+          element_position: link.position,
+          element_type: 'link',
+        });
+      }
+    }
+
+    // Process other interactive elements
+    const others = uiElements.filter(el => 
+      !['button', 'link'].includes(el.role) && 
+      ['menuitem', 'tab', 'checkbox', 'radio'].includes(el.role)
+    );
+    for (const element of others) {
+      const intent = this._extractIntentFromElement(element, routeContext);
+      if (intent) {
+        intent.confidence *= 0.75;
+        intents.push({
+          ...intent,
+          source_element: element.selector,
+          element_position: element.position,
+          element_type: element.role,
+        });
+      }
+    }
+
+    // Sort by confidence and position
+    intents.sort((a, b) => {
+      // Primary sort by confidence
+      if (Math.abs(a.confidence - b.confidence) > 0.1) {
+        return b.confidence - a.confidence;
+      }
+      // Secondary sort by vertical position (higher on page = more important)
+      const aY = a.element_position?.y || 9999;
+      const bY = b.element_position?.y || 9999;
+      return aY - bY;
+    });
+
+    // Deduplicate by intent key
+    const uniqueIntents = this._deduplicateIntents(intents);
+
+    // Return top N intents
+    return uniqueIntents.slice(0, maxIntents);
+  }
+
+  /**
+   * Extract route context (module name from URL)
+   * @param {string} route - Page route
+   * @returns {string} - Context word
+   */
+  static _extractRouteContext(route) {
+    // Extract meaningful segments
+    const segments = route.split('/').filter(s => s.length > 0 && !s.match(/^\d+$/));
+    
+    if (segments.length === 0) {
+      return 'page';
+    }
+
+    // Use the first meaningful segment as context
+    // e.g., "/payroll/processing" -> "payroll"
+    // e.g., "/employees/123/edit" -> "employees"
+    return segments[0].toLowerCase();
+  }
+
+  /**
+   * Extract intent from a single UI element
+   * @param {Object} element - UI element object
+   * @param {string} routeContext - Route context word
+   * @returns {Object|null} - Intent object or null
+   */
+  static _extractIntentFromElement(element, routeContext) {
+    // Get text from element (prefer aria-label for accessibility)
+    const text = (element.aria_label || element.text || element.title || '').trim();
+    
+    if (!text || text.length < 2 || text.length > 50) {
+      return null;
+    }
+
+    // Skip generic/navigation elements
+    const skipPatterns = [
+      /^home$/i, /^menu$/i, /^settings$/i, /^profile$/i,
+      /^\d+$/, /^[<>]$/, /^more$/i, /^options$/i,
+    ];
+    if (skipPatterns.some(p => p.test(text))) {
+      return null;
+    }
+
+    // Find action verb in text
+    const verbMatch = ActionVerbMap.findInText(text);
+    
+    if (!verbMatch) {
+      return null;
+    }
+
+    // Extract object (what the action applies to)
+    const words = text.toLowerCase().split(/\s+/);
+    let objectName = '';
+
+    if (verbMatch.position === 0 && words.length > 1) {
+      // Action verb is first word, rest is the object
+      objectName = words.slice(1).join('_');
+    } else if (verbMatch.position > 0) {
+      // Action verb is not first, object might be before
+      objectName = words.slice(0, verbMatch.position).join('_');
+    } else {
+      // Single word action, use route context
+      objectName = routeContext;
+    }
+
+    // Clean up object name
+    objectName = objectName.replace(/[^\w_]/g, '').replace(/_+/g, '_');
+    
+    if (!objectName) {
+      objectName = routeContext;
+    }
+
+    // Generate intent key and label
+    const intentKey = `${verbMatch.verb}_${objectName}`;
+    const intentLabel = this._generateLabel(verbMatch.verb, objectName);
+
+    return {
+      key: intentKey,
+      label: intentLabel,
+      verb: verbMatch.verb,
+      object: objectName,
+      confidence: this._calculateConfidence(element, verbMatch),
+      original_text: text,
+    };
+  }
+
+  /**
+   * Generate human-readable label for intent
+   * @param {string} verb - Canonical verb
+   * @param {string} object - Object name in snake_case
+   * @returns {string} - Human-readable label
+   */
+  static _generateLabel(verb, object) {
+    const verbLabel = ActionVerbMap.getLabel(verb);
+    const objectLabel = toTitleCase(object);
+    return `${verbLabel} ${objectLabel}`;
+  }
+
+  /**
+   * Calculate confidence score for an intent
+   * @param {Object} element - UI element
+   * @param {Object} verbMatch - Verb match result
+   * @returns {number} - Confidence score (0-1)
+   */
+  static _calculateConfidence(element, verbMatch) {
+    let confidence = 0.85; // Base confidence for rule-based extraction
+
+    // Boost if verb is first word
+    if (verbMatch.position === 0) {
+      confidence += 0.05;
+    }
+
+    // Boost if element has data-testid (indicates well-structured UI)
+    if (element.data_testid) {
+      confidence += 0.03;
+    }
+
+    // Boost if element has aria-label
+    if (element.aria_label) {
+      confidence += 0.02;
+    }
+
+    // Slight penalty for very long text (might be descriptive, not actionable)
+    const textLength = (element.text || '').length;
+    if (textLength > 30) {
+      confidence -= 0.05;
+    }
+
+    // Cap at 0.95
+    return Math.min(0.95, confidence);
+  }
+
+  /**
+   * Deduplicate intents by key, keeping highest confidence
+   * @param {Array} intents - Array of intents
+   * @returns {Array} - Deduplicated array
+   */
+  static _deduplicateIntents(intents) {
+    const seen = new Map();
+
+    for (const intent of intents) {
+      const existing = seen.get(intent.key);
+      if (!existing || intent.confidence > existing.confidence) {
+        seen.set(intent.key, intent);
+      }
+    }
+
+    return Array.from(seen.values());
+  }
+
+  /**
+   * Match user query to available intents
+   * @param {string} query - User's free-text query
+   * @param {Array} availableIntents - Array of intent objects
+   * @returns {Object|null} - Best matching intent or null
+   */
+  static matchQueryToIntent(query, availableIntents) {
+    if (!query || !availableIntents?.length) {
+      return null;
+    }
+
+    const queryLower = query.toLowerCase();
+    const queryWords = queryLower.split(/\s+/).filter(w => w.length > 2);
+
+    let bestMatch = null;
+    let bestScore = 0;
+
+    for (const intent of availableIntents) {
+      let score = 0;
+
+      // Check if query contains the verb
+      if (queryLower.includes(intent.verb)) {
+        score += 0.4;
+      }
+
+      // Check if query contains object words
+      const objectWords = intent.object.split('_');
+      const objectMatchCount = objectWords.filter(w => queryLower.includes(w)).length;
+      score += (objectMatchCount / objectWords.length) * 0.4;
+
+      // Check if label matches
+      if (queryLower.includes(intent.label.toLowerCase())) {
+        score += 0.3;
+      }
+
+      // Check keyword overlap
+      const intentKeywords = [intent.verb, ...objectWords];
+      const keywordMatches = queryWords.filter(w => 
+        intentKeywords.some(k => k.includes(w) || w.includes(k))
+      ).length;
+      score += (keywordMatches / Math.max(queryWords.length, 1)) * 0.2;
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = { ...intent, match_score: score };
+      }
+    }
+
+    // Return match only if confidence is reasonable
+    if (bestScore >= 0.3) {
+      return bestMatch;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get suggested clarification when query is ambiguous
+   * @param {string} query - User's query
+   * @param {Array} candidates - Possible matching intents
+   * @returns {Object} - { question, options }
+   */
+  static getClarification(query, candidates) {
+    if (!candidates || candidates.length < 2) {
+      return null;
+    }
+
+    // Take top 2-3 candidates
+    const topCandidates = candidates.slice(0, 3);
+
+    return {
+      question: 'Did you mean one of these?',
+      options: topCandidates.map(c => ({
+        key: c.key,
+        label: c.label,
+      })),
+    };
+  }
+}
+
+export default IntentExtractor;