@predicatelabs/sdk 0.99.9

package/dist/utils/grid-utils.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Utility functions for working with grid layout data in snapshots.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGridBounds = getGridBounds;
+/**
+ * Get grid coordinates (bounding boxes) for detected grids.
+ *
+ * Groups elements by grid_id and computes the overall bounding box,
+ * row/column counts, and item count for each grid.
+ *
+ * @param snapshot - The snapshot containing elements with layout data
+ * @param gridId - Optional grid ID to filter by. If undefined, returns all grids.
+ * @returns Array of GridInfo objects, one per detected grid, sorted by grid_id.
+ *          Each GridInfo contains:
+ *          - grid_id: The grid identifier
+ *          - bbox: Bounding box (x, y, width, height) in document coordinates
+ *          - row_count: Number of rows in the grid
+ *          - col_count: Number of columns in the grid
+ *          - item_count: Total number of items in the grid
+ *          - confidence: Confidence score (currently 1.0)
+ *          - label: Optional inferred label (e.g., "product_grid", "search_results", "navigation")
+ *            Note: Label inference is best-effort and may not always be accurate
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await browser.snapshot();
+ * // Get all grids
+ * const allGrids = getGridBounds(snapshot);
+ * // Get specific grid
+ * const mainGrid = getGridBounds(snapshot, 0);
+ * if (mainGrid.length > 0) {
+ *   console.log(`Grid 0: ${mainGrid[0].item_count} items at (${mainGrid[0].bbox.x}, ${mainGrid[0].bbox.y})`);
+ * }
+ * ```
+ */
+function getGridBounds(snapshot, gridId) {
+    // Group elements by grid_id
+    const gridElements = new Map();
+    for (const elem of snapshot.elements) {
+        if (elem.layout?.grid_id != null) {
+            const gid = elem.layout.grid_id;
+            if (!gridElements.has(gid)) {
+                gridElements.set(gid, []);
+            }
+            gridElements.get(gid).push(elem);
+        }
+    }
+    // Filter by gridId if specified
+    if (gridId !== undefined) {
+        if (!gridElements.has(gridId)) {
+            return [];
+        }
+        const filtered = new Map([[gridId, gridElements.get(gridId)]]);
+        gridElements.clear();
+        filtered.forEach((v, k) => gridElements.set(k, v));
+    }
+    const gridInfos = [];
+    const gridDominantCounts = new Map();
+    // Sort by grid_id for consistent output
+    const sortedGridIds = Array.from(gridElements.keys()).sort((a, b) => a - b);
+    // First pass: compute all grid infos and count dominant group elements
+    for (const gid of sortedGridIds) {
+        const elementsInGrid = gridElements.get(gid);
+        if (elementsInGrid.length === 0) {
+            continue;
+        }
+        // Count dominant group elements in this grid
+        const dominantCount = elementsInGrid.filter(e => e.in_dominant_group === true).length;
+        gridDominantCounts.set(gid, {
+            dominant: dominantCount,
+            total: elementsInGrid.length,
+        });
+        // Compute bounding box
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        // Count rows and columns
+        const rowIndices = new Set();
+        const colIndices = new Set();
+        for (const elem of elementsInGrid) {
+            const bbox = elem.bbox;
+            minX = Math.min(minX, bbox.x);
+            minY = Math.min(minY, bbox.y);
+            maxX = Math.max(maxX, bbox.x + bbox.width);
+            maxY = Math.max(maxY, bbox.y + bbox.height);
+            if (elem.layout?.grid_pos) {
+                rowIndices.add(elem.layout.grid_pos.row_index);
+                colIndices.add(elem.layout.grid_pos.col_index);
+            }
+        }
+        // Infer grid label from element patterns (best-effort heuristic)
+        const label = inferGridLabel(elementsInGrid);
+        gridInfos.push({
+            grid_id: gid,
+            bbox: {
+                x: minX,
+                y: minY,
+                width: maxX - minX,
+                height: maxY - minY,
+            },
+            row_count: rowIndices.size,
+            col_count: colIndices.size,
+            item_count: elementsInGrid.length,
+            confidence: 1.0,
+            label: label,
+            is_dominant: false, // Will be set below
+        });
+    }
+    // Second pass: identify dominant grid
+    // The grid with the highest count (or highest percentage >= 50%) of dominant group elements
+    if (gridDominantCounts.size > 0) {
+        // Find grid with highest absolute count
+        let maxDominantCount = 0;
+        for (const { dominant } of gridDominantCounts.values()) {
+            maxDominantCount = Math.max(maxDominantCount, dominant);
+        }
+        if (maxDominantCount > 0) {
+            // Find grid(s) with highest count
+            const dominantGrids = [];
+            for (const [gid, counts] of gridDominantCounts.entries()) {
+                if (counts.dominant === maxDominantCount) {
+                    dominantGrids.push(gid);
+                }
+            }
+            // If multiple grids tie, prefer the one with highest percentage
+            dominantGrids.sort((a, b) => {
+                const aCounts = gridDominantCounts.get(a);
+                const bCounts = gridDominantCounts.get(b);
+                const aPct = aCounts.total > 0 ? aCounts.dominant / aCounts.total : 0;
+                const bPct = bCounts.total > 0 ? bCounts.dominant / bCounts.total : 0;
+                return bPct - aPct;
+            });
+            // Mark the dominant grid
+            const dominantGid = dominantGrids[0];
+            const counts = gridDominantCounts.get(dominantGid);
+            // Only mark as dominant if it has >= 50% dominant group elements or >= 3 elements
+            if (counts.dominant >= 3 || (counts.total > 0 && counts.dominant / counts.total >= 0.5)) {
+                const gridInfo = gridInfos.find(g => g.grid_id === dominantGid);
+                if (gridInfo) {
+                    gridInfo.is_dominant = true;
+                }
+            }
+        }
+    }
+    return gridInfos;
+}
+/**
+ * Infer grid label from element patterns using text fingerprinting (best-effort heuristic).
+ *
+ * Uses patterns similar to dominant_group.rs content filtering logic, inverted to detect
+ * semantic grid types. Analyzes first 5 items as a "bag of features".
+ *
+ * Returns null if label cannot be reliably determined.
+ * This is a simple heuristic and may not always be accurate.
+ */
+function inferGridLabel(elements) {
+    if (elements.length === 0) {
+        return null;
+    }
+    // Sample first 5 items for fingerprinting (as suggested in feedback)
+    const sampleElements = elements.slice(0, 5);
+    const elementTexts = sampleElements.map(e => (e.text || '').trim()).filter(t => t.length > 0);
+    if (elementTexts.length === 0) {
+        return null;
+    }
+    // Collect text patterns
+    const allText = elementTexts.map(t => t.toLowerCase()).join(' ');
+    const hrefs = sampleElements.filter(e => e.href).map(e => (e.href || '').toLowerCase());
+    // =========================================================================
+    // 1. PRODUCT GRID: Currency symbols, action verbs, ratings
+    // =========================================================================
+    // Currency patterns: $, €, £, or price patterns like "19.99", "$50", "€30"
+    const currencyPattern = /[$€£¥]\s*\d+|\d+\.\d{2}/.test(allText);
+    const productActionVerbs = [
+        'add to cart',
+        'buy now',
+        'shop now',
+        'purchase',
+        'out of stock',
+        'in stock',
+    ];
+    const hasProductActions = productActionVerbs.some(verb => allText.includes(verb));
+    // Ratings pattern: "4.5 stars", "(120 reviews)", "4.5/5"
+    const ratingPattern = /\d+\.?\d*\s*(stars?|reviews?|\/5|\/10)/i.test(allText);
+    // Product URL patterns
+    const productUrlPatterns = ['/product/', '/item/', '/dp/', '/p/', '/products/'];
+    const hasProductUrls = hrefs.some(href => productUrlPatterns.some(pattern => href.includes(pattern)));
+    if ((currencyPattern || hasProductActions || ratingPattern) &&
+        (hasProductUrls ||
+            elementTexts.filter(t => /[$€£¥]\s*\d+|\d+\.\d{2}/.test(t.toLowerCase())).length >= 2)) {
+        return 'product_grid';
+    }
+    // =========================================================================
+    // 2. ARTICLE/NEWS FEED: Timestamps, bylines, reading time
+    // =========================================================================
+    // Timestamp patterns (reusing logic from dominant_group.rs)
+    // "2 hours ago", "3 days ago", "5 minutes ago", "1 second ago", "2 ago"
+    const timestampPatterns = [
+        /\d+\s+(hour|day|minute|second)s?\s+ago/i,
+        /\d+\s+ago/i, // Short form: "2 ago"
+        /\d{1,2}\s+(hour|day|minute|second)\s+ago/i, // Singular
+    ];
+    const hasTimestamps = timestampPatterns.some(pattern => pattern.test(allText));
+    // Date patterns: "Aug 21, 2024", "2024-01-13", "Jan 15"
+    const datePatterns = [
+        /\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2},?\s+\d{4}/i,
+        /\d{4}-\d{2}-\d{2}/,
+        /\d{1,2}\/\d{1,2}\/\d{4}/,
+    ];
+    const hasDates = datePatterns.some(pattern => pattern.test(allText));
+    // Bylines: "By [Name]", "Author:", "Written by"
+    const bylinePatterns = ['by ', 'author:', 'written by', 'posted by'];
+    const hasBylines = bylinePatterns.some(pattern => allText.includes(pattern));
+    // Reading time: "5 min read", "10 min", "read more"
+    const readingTimePattern = /\d+\s*(min|minute)s?\s*(read)?/i.test(allText);
+    if (hasTimestamps || (hasDates && hasBylines) || readingTimePattern) {
+        return 'article_feed';
+    }
+    // =========================================================================
+    // 3. SEARCH RESULTS: Snippets, metadata, ellipses
+    // =========================================================================
+    const searchKeywords = ['result', 'search', 'found', 'showing', 'results 1-', 'sponsored'];
+    const hasSearchMetadata = searchKeywords.some(keyword => allText.includes(keyword));
+    // Snippet indicators: ellipses, "match found", truncated text
+    const hasEllipses = allText.includes('...') || elementTexts.some(t => t.length > 100 && t.includes('...'));
+    // Check if many elements are links (typical for search results)
+    const linkCount = sampleElements.filter(e => e.role === 'link' || e.href).length;
+    const isMostlyLinks = linkCount >= sampleElements.length * 0.7; // 70%+ are links
+    if ((hasSearchMetadata || hasEllipses) && isMostlyLinks) {
+        return 'search_results';
+    }
+    // =========================================================================
+    // 4. NAVIGATION: Short length, homogeneity, common nav terms
+    // =========================================================================
+    // Calculate average text length and variance
+    const textLengths = elementTexts.map(t => t.length);
+    if (textLengths.length > 0) {
+        const avgLength = textLengths.reduce((sum, len) => sum + len, 0) / textLengths.length;
+        // Low variance = homogeneous (typical of navigation)
+        const variance = textLengths.length > 1
+            ? textLengths.reduce((sum, len) => sum + Math.pow(len - avgLength, 2), 0) /
+                textLengths.length
+            : 0;
+        const navKeywords = [
+            'home',
+            'about',
+            'contact',
+            'menu',
+            'login',
+            'sign in',
+            'profile',
+            'settings',
+        ];
+        const hasNavKeywords = navKeywords.some(keyword => allText.includes(keyword));
+        // Navigation: short average length (< 15 chars) AND low variance OR nav keywords
+        if (avgLength < 15 && (variance < 20 || hasNavKeywords)) {
+            // Also check if all are links
+            if (sampleElements.every(e => e.role === 'link' || e.href)) {
+                return 'navigation';
+            }
+        }
+    }
+    // =========================================================================
+    // 5. BUTTON GRID: All buttons
+    // =========================================================================
+    if (sampleElements.every(e => e.role === 'button')) {
+        return 'button_grid';
+    }
+    // =========================================================================
+    // 6. LINK LIST: Mostly links but not navigation
+    // =========================================================================
+    const linkListCount = sampleElements.filter(e => e.role === 'link' || e.href).length;
+    if (linkListCount >= sampleElements.length * 0.8) {
+        // 80%+ are links
+        return 'link_list';
+    }
+    // Unknown/unclear
+    return null;
+}
+//# sourceMappingURL=grid-utils.js.map

package/dist/utils/grid-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-utils.js","sourceRoot":"","sources":["../../src/utils/grid-utils.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAmCH,sCAgIC;AA/JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,aAAa,CAAC,QAAkB,EAAE,MAAe;IAC/D,4BAA4B;IAC5B,MAAM,YAAY,GAA2B,IAAI,GAAG,EAAE,CAAC;IAEvD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;YAChC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC5B,CAAC;YACD,YAAY,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC,CAAC,CAAC,CAAC;QAChE,YAAY,CAAC,KAAK,EAAE,CAAC;QACrB,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA+C,CAAC;IAElF,wCAAwC;IACxC,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAE5E,uEAAuE;IACvE,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;QAC9C,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,SAAS;QACX,CAAC;QAED,6CAA6C;QAC7C,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;QACtF,kBAAkB,CAAC,GAAG,CAAC,GAAG,EAAE;YAC1B,QAAQ,EAAE,aAAa;YACvB,KAAK,EAAE,cAAc,CAAC,MAAM;SAC7B,CAAC,CAAC;QAEH,uBAAuB;QACvB,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC;QACrB,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC;QAErB,yBAAyB;QACzB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QAErC,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAE5C,IAAI,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAC1B,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBAC/C,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QAED,iEAAiE;QACjE,MAAM,KAAK,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;QAE7C,SAAS,CAAC,IAAI,CAAC;YACb,OAAO,EAAE,GAAG;YACZ,IAAI,EAAE;gBACJ,CAAC,EAAE,IAAI;gBACP,CAAC,EAAE,IAAI;gBACP,KAAK,EAAE,IAAI,GAAG,IAAI;gBAClB,MAAM,EAAE,IAAI,GAAG,IAAI;aACpB;YACD,SAAS,EAAE,UAAU,CAAC,IAAI;YAC1B,SAAS,EAAE,UAAU,CAAC,IAAI;YAC1B,UAAU,EAAE,cAAc,CAAC,MAAM;YACjC,UAAU,EAAE,GAAG;YACf,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,KAAK,EAAE,oBAAoB;SACzC,CAAC,CAAC;IACL,CAAC;IAED,sCAAsC;IACtC,4FAA4F;IAC5F,IAAI,kBAAkB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAChC,wCAAwC;QACxC,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,kBAAkB,CAAC,MAAM,EAAE,EAAE,CAAC;YACvD,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;YACzB,kCAAkC;YAClC,MAAM,aAAa,GAAa,EAAE,CAAC;YACnC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,kBAAkB,CAAC,OAAO,EAAE,EAAE,CAAC;gBACzD,IAAI,MAAM,CAAC,QAAQ,KAAK,gBAAgB,EAAE,CAAC;oBACzC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;YAED,gEAAgE;YAChE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC1B,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;gBAC3C,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACtE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACtE,OAAO,IAAI,GAAG,IAAI,CAAC;YACrB,CAAC,CAAC,CAAC;YAEH,yBAAyB;YACzB,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC;YACpD,kFAAkF;YAClF,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC;gBACxF,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC;gBAChE,IAAI,QAAQ,EAAE,CAAC;oBACb,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;gBAC9B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,QAAmB;IACzC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qEAAqE;IACrE,MAAM,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE9F,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IACxB,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAExF,4EAA4E;IAC5E,2DAA2D;IAC3D,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,eAAe,GAAG,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChE,MAAM,kBAAkB,GAAG;QACzB,aAAa;QACb,SAAS;QACT,UAAU;QACV,UAAU;QACV,cAAc;QACd,UAAU;KACX,CAAC;IACF,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAElF,yDAAyD;IACzD,MAAM,aAAa,GAAG,yCAAyC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE9E,uBAAuB;IACvB,MAAM,kBAAkB,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAChF,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAC3D,CAAC;IAEF,IACE,CAAC,eAAe,IAAI,iBAAiB,IAAI,aAAa,CAAC;QACvD,CAAC,cAAc;YACb,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,EACxF,CAAC;QACD,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,4EAA4E;IAC5E,0DAA0D;IAC1D,4EAA4E;IAC5E,4DAA4D;IAC5D,wEAAwE;IACxE,MAAM,iBAAiB,GAAG;QACxB,yCAAyC;QACzC,YAAY,EAAE,sBAAsB;QACpC,2CAA2C,EAAE,WAAW;KACzD,CAAC;IACF,MAAM,aAAa,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAE/E,wDAAwD;IACxD,MAAM,YAAY,GAAG;QACnB,gFAAgF;QAChF,mBAAmB;QACnB,yBAAyB;KAC1B,CAAC;IACF,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAErE,gDAAgD;IAChD,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IACrE,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAE7E,oDAAoD;IACpD,MAAM,kBAAkB,GAAG,iCAAiC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE3E,IAAI,aAAa,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACpE,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,4EAA4E;IAC5E,kDAAkD;IAClD,4EAA4E;IAC5E,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IAC3F,MAAM,iBAAiB,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpF,8DAA8D;IAC9D,MAAM,WAAW,GACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAEzF,gEAAgE;IAChE,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACjF,MAAM,aAAa,GAAG,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,iBAAiB;IAEjF,IAAI,CAAC,iBAAiB,IAAI,WAAW,CAAC,IAAI,aAAa,EAAE,CAAC;QACxD,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,4EAA4E;IAC5E,6DAA6D;IAC7D,4EAA4E;IAC5E,6CAA6C;IAC7C,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC;QACtF,qDAAqD;QACrD,MAAM,QAAQ,GACZ,WAAW,CAAC,MAAM,GAAG,CAAC;YACpB,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;gBACvE,WAAW,CAAC,MAAM;YACpB,CAAC,CAAC,CAAC,CAAC;QAER,MAAM,WAAW,GAAG;YAClB,MAAM;YACN,OAAO;YACP,SAAS;YACT,MAAM;YACN,OAAO;YACP,SAAS;YACT,SAAS;YACT,UAAU;SACX,CAAC;QACF,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAE9E,iFAAiF;QACjF,IAAI,SAAS,GAAG,EAAE,IAAI,CAAC,QAAQ,GAAG,EAAE,IAAI,cAAc,CAAC,EAAE,CAAC;YACxD,8BAA8B;YAC9B,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3D,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,8BAA8B;IAC9B,4EAA4E;IAC5E,IAAI,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;QACnD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,4EAA4E;IAC5E,gDAAgD;IAChD,4EAA4E;IAC5E,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACrF,IAAI,aAAa,IAAI,cAAc,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACjD,iBAAiB;QACjB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,kBAAkB;IAClB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/llm-interaction-handler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LLMInteractionHandler - Handles LLM queries and response parsing
+ *
+ * Extracted from SentienceAgent to improve separation of concerns
+ */
+import { LLMProvider, LLMResponse } from '../llm-provider';
+import { Snapshot } from '../types';
+/**
+ * LLMInteractionHandler handles all LLM-related operations
+ */
+export declare class LLMInteractionHandler {
+    private llm;
+    private verbose;
+    constructor(llm: LLMProvider, verbose?: boolean);
+    /**
+     * Build context string from snapshot for LLM prompt
+     *
+     * Format: [ID] <role> "text" {cues} @ (x,y) size:WxH importance:score [status]
+     *
+     * @param snap - Snapshot containing elements
+     * @param goal - Goal/task description (unused but kept for API consistency)
+     * @returns Formatted context string
+     */
+    buildContext(snap: Snapshot, _goal: string): string;
+    /**
+     * Query LLM with standardized prompt template
+     *
+     * @param domContext - DOM context string (formatted elements)
+     * @param goal - Goal/task description
+     * @returns LLM response
+     */
+    queryLLM(domContext: string, goal: string): Promise<LLMResponse>;
+    /**
+     * Extract action string from LLM response
+     *
+     * @param response - LLM response
+     * @returns Action string (e.g., "CLICK(42)")
+     */
+    extractAction(response: LLMResponse): string;
+}
+//# sourceMappingURL=llm-interaction-handler.d.ts.map

package/dist/utils/llm-interaction-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-interaction-handler.d.ts","sourceRoot":"","sources":["../../src/utils/llm-interaction-handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAGpC;;GAEG;AACH,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,OAAO;gBADP,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,OAAc;IAGjC;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IA4DnD;;;;;;OAMG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgFtE;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM;CAG7C"}

package/dist/utils/llm-interaction-handler.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * LLMInteractionHandler - Handles LLM queries and response parsing
+ *
+ * Extracted from SentienceAgent to improve separation of concerns
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMInteractionHandler = void 0;
+const llm_response_builder_1 = require("./llm-response-builder");
+/**
+ * LLMInteractionHandler handles all LLM-related operations
+ */
+class LLMInteractionHandler {
+    constructor(llm, verbose = true) {
+        this.llm = llm;
+        this.verbose = verbose;
+    }
+    /**
+     * Build context string from snapshot for LLM prompt
+     *
+     * Format: [ID] <role> "text" {cues} @ (x,y) size:WxH importance:score [status]
+     *
+     * @param snap - Snapshot containing elements
+     * @param goal - Goal/task description (unused but kept for API consistency)
+     * @returns Formatted context string
+     */
+    buildContext(snap, _goal) {
+        const lines = [];
+        for (const el of snap.elements) {
+            // Skip REMOVED elements - they're not actionable and shouldn't be in LLM context
+            if (el.diff_status === 'REMOVED') {
+                continue;
+            }
+            // Extract visual cues
+            const cues = [];
+            if (el.visual_cues.is_primary)
+                cues.push('PRIMARY');
+            if (el.visual_cues.is_clickable)
+                cues.push('CLICKABLE');
+            if (el.visual_cues.background_color_name) {
+                cues.push(`color:${el.visual_cues.background_color_name}`);
+            }
+            // Format element line with improved readability
+            const cuesStr = cues.length > 0 ? ` {${cues.join(',')}}` : '';
+            // Better text handling - show truncation indicator
+            let textPreview = '';
+            if (el.text) {
+                if (el.text.length > 50) {
+                    textPreview = `"${el.text.substring(0, 50)}..."`;
+                }
+                else {
+                    textPreview = `"${el.text}"`;
+                }
+            }
+            // Build position and size info
+            const x = Math.floor(el.bbox.x);
+            const y = Math.floor(el.bbox.y);
+            const width = Math.floor(el.bbox.width);
+            const height = Math.floor(el.bbox.height);
+            const positionStr = `@ (${x},${y})`;
+            const sizeStr = `size:${width}x${height}`;
+            // Build status indicators (only include if relevant)
+            const statusParts = [];
+            if (!el.in_viewport) {
+                statusParts.push('not_in_viewport');
+            }
+            if (el.is_occluded) {
+                statusParts.push('occluded');
+            }
+            if (el.diff_status) {
+                statusParts.push(`diff:${el.diff_status}`);
+            }
+            const statusStr = statusParts.length > 0 ? ` [${statusParts.join(',')}]` : '';
+            // Format: [ID] <role> "text" {cues} @ (x,y) size:WxH importance:score [status]
+            lines.push(`[${el.id}] <${el.role}> ${textPreview}${cuesStr} ` +
+                `${positionStr} ${sizeStr} importance:${el.importance}${statusStr}`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Query LLM with standardized prompt template
+     *
+     * @param domContext - DOM context string (formatted elements)
+     * @param goal - Goal/task description
+     * @returns LLM response
+     */
+    async queryLLM(domContext, goal) {
+        const systemPrompt = `You are an AI web automation agent.
+
+GOAL: ${goal}
+
+VISIBLE ELEMENTS (sorted by importance):
+${domContext}
+
+VISUAL CUES EXPLAINED:
+After the text, you may see visual cues in curly braces like {CLICKABLE} or {PRIMARY,CLICKABLE,color:white}:
+- PRIMARY: Main call-to-action element on the page
+- CLICKABLE: Element is clickable/interactive
+- color:X: Background color name (e.g., color:white, color:blue)
+Multiple cues are comma-separated inside the braces: {CLICKABLE,color:white}
+
+ELEMENT FORMAT EXPLAINED:
+Each element line follows this format:
+[ID] <role> "text" {cues} @ (x,y) size:WxH importance:score [status]
+
+Example: [346] <button> "Computer Accessories" {CLICKABLE,color:white} @ (664,100) size:150x40 importance:811
+
+Breaking down each part:
+- [ID]: The number in brackets is the element ID - use this EXACT number in CLICK/TYPE commands
+  Example: If you see [346], use CLICK(346) or TYPE(346, "text")
+- <role>: Element type (button, link, textbox, etc.)
+- "text": Visible text content (truncated with "..." if long)
+- {cues}: Optional visual cues in curly braces (e.g., {CLICKABLE}, {PRIMARY,CLICKABLE}, {CLICKABLE,color:white})
+  If no cues, this part is omitted entirely
+- @ (x,y): Element position in pixels from top-left corner
+- size:WxH: Element dimensions (width x height in pixels)
+- importance: Score indicating element relevance (higher = more important)
+- [status]: Optional status flags in brackets (not_in_viewport, occluded, diff:ADDED/MODIFIED/etc)
+
+CRITICAL RESPONSE FORMAT:
+You MUST respond with ONLY ONE of these exact action formats:
+- CLICK(id) - Click element by ID (use the number from [ID] brackets)
+- TYPE(id, "text") - Type text into element (use the number from [ID] brackets)
+- PRESS("key") - Press keyboard key (Enter, Escape, Tab, ArrowDown, etc)
+- FINISH() - Task complete
+
+DO NOT include any explanation, reasoning, or natural language.
+DO NOT use markdown formatting or code blocks.
+DO NOT say "The next step is..." or anything similar.
+
+CORRECT Examples (matching element IDs from the list above):
+If element is [346] <button> "Click me" → respond: CLICK(346)
+If element is [15] <textbox> "Search" → respond: TYPE(15, "magic mouse")
+PRESS("Enter")
+FINISH()
+
+INCORRECT Examples (DO NOT DO THIS):
+"The next step is to click..."
+"I will type..."
+\`\`\`CLICK(42)\`\`\``;
+        const userPrompt = 'Return the single action command:';
+        try {
+            const response = await this.llm.generate(systemPrompt, userPrompt, {
+                temperature: 0.0,
+            });
+            // Validate response
+            if (!llm_response_builder_1.LLMResponseBuilder.validate(response)) {
+                throw new Error('Invalid LLM response format');
+            }
+            return response;
+        }
+        catch (error) {
+            if (this.verbose) {
+                console.error('LLM query failed:', error);
+            }
+            // Return error response
+            return llm_response_builder_1.LLMResponseBuilder.createErrorResponse(error instanceof Error ? error : new Error(String(error)), this.llm.modelName);
+        }
+    }
+    /**
+     * Extract action string from LLM response
+     *
+     * @param response - LLM response
+     * @returns Action string (e.g., "CLICK(42)")
+     */
+    extractAction(response) {
+        return response.content.trim();
+    }
+}
+exports.LLMInteractionHandler = LLMInteractionHandler;
+//# sourceMappingURL=llm-interaction-handler.js.map

package/dist/utils/llm-interaction-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-interaction-handler.js","sourceRoot":"","sources":["../../src/utils/llm-interaction-handler.ts"],"names":[],"mappings":"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"}

package/dist/utils/llm-response-builder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * LLMResponseBuilder - Helper for consistent LLM response building
+ *
+ * Provides standardized response building and error handling across LLM providers
+ */
+import { LLMResponse } from '../llm-provider';
+/**
+ * LLMResponseBuilder provides static methods for building and validating LLM responses
+ */
+export declare class LLMResponseBuilder {
+    /**
+     * Build a standardized LLMResponse from provider-specific response data
+     *
+     * @param content - Response content text
+     * @param modelName - Model name/identifier
+     * @param usage - Token usage data (provider-specific format)
+     * @param providerType - Provider type for usage extraction
+     * @returns Standardized LLMResponse
+     *
+     * @example
+     * ```typescript
+     * // OpenAI format
+     * const response = LLMResponseBuilder.build(
+     *   'CLICK(1)',
+     *   'gpt-4o',
+     *   { prompt_tokens: 100, completion_tokens: 20, total_tokens: 120 },
+     *   'openai'
+     * );
+     *
+     * // Anthropic format
+     * const response = LLMResponseBuilder.build(
+     *   'CLICK(1)',
+     *   'claude-3-5-sonnet',
+     *   { input_tokens: 100, output_tokens: 20 },
+     *   'anthropic'
+     * );
+     * ```
+     */
+    static build(content: string, modelName: string, usage: any, providerType?: 'openai' | 'anthropic' | 'glm' | 'gemini' | 'generic'): LLMResponse;
+    /**
+     * Validate that an LLMResponse has required fields
+     *
+     * @param response - LLMResponse to validate
+     * @returns True if valid, false otherwise
+     */
+    static validate(response: LLMResponse): boolean;
+    /**
+     * Create an error response
+     *
+     * @param error - Error message or Error object
+     * @param modelName - Optional model name
+     * @returns LLMResponse with error content
+     */
+    static createErrorResponse(error: string | Error, modelName?: string): LLMResponse;
+}
+//# sourceMappingURL=llm-response-builder.d.ts.map

package/dist/utils/llm-response-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-response-builder.d.ts","sourceRoot":"","sources":["../../src/utils/llm-response-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,KAAK,CACV,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,GAAG,EACV,YAAY,GAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAqB,GAC9E,WAAW;IAgDd;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO;IAoB/C;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW;CAUnF"}