sentienceapi 0.90.16__py3-none-any.whl → 0.92.2__py3-none-any.whl

sentience/extension/release.json

@@ -1,45 +1,45 @@
 {
-  "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/273122615",
-  "assets_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/273122615/assets",
-  "upload_url": "https://uploads.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/273122615/assets{?name,label}",
-  "html_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/tag/v2.0.7",
-  "id": 273122615,
+  "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/274400382",
+  "assets_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/274400382/assets",
+  "upload_url": "https://uploads.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/274400382/assets{?name,label}",
+  "html_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/tag/v2.2.0",
+  "id": 274400382,
   "author": {
-    "login": "github-actions[bot]",
-    "id": 41898282,
-    "node_id": "MDM6Qm90NDE4OTgyODI=",
-    "avatar_url": "https://avatars.githubusercontent.com/in/15368?v=4",
+    "login": "rcholic",
+    "id": 135060,
+    "node_id": "MDQ6VXNlcjEzNTA2MA==",
+    "avatar_url": "https://avatars.githubusercontent.com/u/135060?v=4",
     "gravatar_id": "",
-    "url": "https://api.github.com/users/github-actions%5Bbot%5D",
-    "html_url": "https://github.com/apps/github-actions",
-    "followers_url": "https://api.github.com/users/github-actions%5Bbot%5D/followers",
-    "following_url": "https://api.github.com/users/github-actions%5Bbot%5D/following{/other_user}",
-    "gists_url": "https://api.github.com/users/github-actions%5Bbot%5D/gists{/gist_id}",
-    "starred_url": "https://api.github.com/users/github-actions%5Bbot%5D/starred{/owner}{/repo}",
-    "subscriptions_url": "https://api.github.com/users/github-actions%5Bbot%5D/subscriptions",
-    "organizations_url": "https://api.github.com/users/github-actions%5Bbot%5D/orgs",
-    "repos_url": "https://api.github.com/users/github-actions%5Bbot%5D/repos",
-    "events_url": "https://api.github.com/users/github-actions%5Bbot%5D/events{/privacy}",
-    "received_events_url": "https://api.github.com/users/github-actions%5Bbot%5D/received_events",
-    "type": "Bot",
+    "url": "https://api.github.com/users/rcholic",
+    "html_url": "https://github.com/rcholic",
+    "followers_url": "https://api.github.com/users/rcholic/followers",
+    "following_url": "https://api.github.com/users/rcholic/following{/other_user}",
+    "gists_url": "https://api.github.com/users/rcholic/gists{/gist_id}",
+    "starred_url": "https://api.github.com/users/rcholic/starred{/owner}{/repo}",
+    "subscriptions_url": "https://api.github.com/users/rcholic/subscriptions",
+    "organizations_url": "https://api.github.com/users/rcholic/orgs",
+    "repos_url": "https://api.github.com/users/rcholic/repos",
+    "events_url": "https://api.github.com/users/rcholic/events{/privacy}",
+    "received_events_url": "https://api.github.com/users/rcholic/received_events",
+    "type": "User",
     "user_view_type": "public",
     "site_admin": false
   },
-  "node_id": "RE_kwDOQshiJ84QR4U3",
-  "tag_name": "v2.0.7",
+  "node_id": "RE_kwDOQshiJ84QWwR-",
+  "tag_name": "v2.2.0",
   "target_commitish": "main",
-  "name": "Release v2.0.7",
+  "name": "Release v2.2.0",
   "draft": false,
   "immutable": false,
   "prerelease": false,
-  "created_at": "2025-12-29T03:56:13Z",
-  "updated_at": "2025-12-29T03:57:09Z",
-  "published_at": "2025-12-29T03:57:08Z",
+  "created_at": "2026-01-06T03:10:35Z",
+  "updated_at": "2026-01-06T03:16:45Z",
+  "published_at": "2026-01-06T03:16:10Z",
   "assets": [
     {
-      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/333966751",
-      "id": 333966751,
-      "node_id": "RA_kwDOQshiJ84T5-2f",
+      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/336823100",
+      "id": 336823100,
+      "node_id": "RA_kwDOQshiJ84UE4M8",
       "name": "extension-files.tar.gz",
       "label": "",
       "uploader": {
@@ -65,17 +65,17 @@
       },
       "content_type": "application/gzip",
       "state": "uploaded",
-      "size": 78091,
-      "digest": "sha256:e281f8b755b61da4b8015d6172064aa9a337c14133ceceff4ab29199ee53307e",
-      "download_count": 5,
-      "created_at": "2025-12-29T03:57:09Z",
-      "updated_at": "2025-12-29T03:57:09Z",
-      "browser_download_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/download/v2.0.7/extension-files.tar.gz"
+      "size": 72250,
+      "digest": "sha256:adb68bd89b417f23f32c029c6cf045cc3677588e6a7760b7c8d0deb7e2601dd1",
+      "download_count": 0,
+      "created_at": "2026-01-06T03:16:44Z",
+      "updated_at": "2026-01-06T03:16:45Z",
+      "browser_download_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/download/v2.2.0/extension-files.tar.gz"
     },
     {
-      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/333966752",
-      "id": 333966752,
-      "node_id": "RA_kwDOQshiJ84T5-2g",
+      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/336823099",
+      "id": 336823099,
+      "node_id": "RA_kwDOQshiJ84UE4M7",
       "name": "extension-package.zip",
       "label": "",
       "uploader": {
@@ -101,15 +101,15 @@
       },
       "content_type": "application/zip",
       "state": "uploaded",
-      "size": 80179,
-      "digest": "sha256:a025edeb8b6d05bfb25c57f913b68507060653ecbdf616000a46df4cb8dec377",
+      "size": 73962,
+      "digest": "sha256:7483812c016842fb02add2d6c8d887e321cb9eb89030fee016cf4ea9f812f4bf",
       "download_count": 0,
-      "created_at": "2025-12-29T03:57:09Z",
-      "updated_at": "2025-12-29T03:57:09Z",
-      "browser_download_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/download/v2.0.7/extension-package.zip"
+      "created_at": "2026-01-06T03:16:44Z",
+      "updated_at": "2026-01-06T03:16:45Z",
+      "browser_download_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/download/v2.2.0/extension-package.zip"
     }
   ],
-  "tarball_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/tarball/v2.0.7",
-  "zipball_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/zipball/v2.0.7",
-  "body": "**Full Changelog**: https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/compare/v2.0.6...v2.0.7"
+  "tarball_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/tarball/v2.2.0",
+  "zipball_url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/zipball/v2.2.0",
+  "body": ""
 }

sentience/formatting.py

@@ -1,59 +1,15 @@
 """
 Snapshot formatting utilities for LLM prompts.
 
-Provides functions to convert Sentience snapshots into text format suitable
-for LLM consumption.
-"""
-
-from typing import List
-
-from .models import Snapshot
-
-
-def format_snapshot_for_llm(snap: Snapshot, limit: int = 50) -> str:
-    """
-    Convert snapshot elements to text format for LLM consumption.
-
-    This is the canonical way Sentience formats DOM state for LLMs.
-    The format includes element ID, role, text preview, visual cues,
-    position, and importance score.
+DEPRECATED: This module is maintained for backward compatibility only.
+New code should import from sentience.utils.formatting or sentience directly:
 
-    Args:
-        snap: Snapshot object with elements
-        limit: Maximum number of elements to include (default: 50)
-
-    Returns:
-        Formatted string with one element per line
-
-    Example:
-        >>> snap = snapshot(browser)
-        >>> formatted = format_snapshot_for_llm(snap, limit=10)
-        >>> print(formatted)
-        [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
-        [2] <input> "Email address" @ (100,100) (Imp:8)
-        ...
-    """
-    lines: list[str] = []
-
-    for el in snap.elements[:limit]:
-        # Build visual cues string
-        cues = []
-        if getattr(el.visual_cues, "is_primary", False):
-            cues.append("PRIMARY")
-        if getattr(el.visual_cues, "is_clickable", False):
-            cues.append("CLICKABLE")
-
-        cues_str = f" {{{','.join(cues)}}}" if cues else ""
-
-        # Format text preview (truncate to 50 chars)
-        text_preview = el.text or ""
-        if len(text_preview) > 50:
-            text_preview = text_preview[:50] + "..."
+    from sentience.utils.formatting import format_snapshot_for_llm
+    # or
+    from sentience import format_snapshot_for_llm
+"""
 
-        # Build element line: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
-        lines.append(
-            f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
-            f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
-        )
+# Re-export from new location for backward compatibility
+from .utils.formatting import format_snapshot_for_llm
 
-    return "\n".join(lines)
+__all__ = ["format_snapshot_for_llm"]

sentience/inspector.py

@@ -1,8 +1,10 @@
+from typing import Optional
+
 """
 Inspector tool - helps developers see what the agent "sees"
 """
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
 
 
 class Inspector:
@@ -183,3 +185,183 @@ def inspect(browser: SentienceBrowser) -> Inspector:
         Inspector instance
     """
     return Inspector(browser)
+
+
+class InspectorAsync:
+    """Inspector for debugging - shows element info on hover/click (async)"""
+
+    def __init__(self, browser: AsyncSentienceBrowser):
+        self.browser = browser
+        self._active = False
+        self._last_element_id: int | None = None
+
+    async def start(self) -> None:
+        """Start inspection mode - prints element info on mouse move/click (async)"""
+        if not self.browser.page:
+            raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+        self._active = True
+
+        # Inject inspector script into page
+        await self.browser.page.evaluate(
+            """
+            (() => {
+                // Remove existing inspector if any
+                if (window.__sentience_inspector_active) {
+                    return;
+                }
+
+                window.__sentience_inspector_active = true;
+                window.__sentience_last_element_id = null;
+
+                // Get element at point
+                function getElementAtPoint(x, y) {
+                    const el = document.elementFromPoint(x, y);
+                    if (!el) return null;
+
+                    // Find element in registry
+                    if (window.sentience_registry) {
+                        for (let i = 0; i < window.sentience_registry.length; i++) {
+                            if (window.sentience_registry[i] === el) {
+                                return i;
+                            }
+                        }
+                    }
+                    return null;
+                }
+
+                // Mouse move handler
+                function handleMouseMove(e) {
+                    if (!window.__sentience_inspector_active) return;
+
+                    const elementId = getElementAtPoint(e.clientX, e.clientY);
+                    if (elementId === null || elementId === window.__sentience_last_element_id) {
+                        return;
+                    }
+
+                    window.__sentience_last_element_id = elementId;
+
+                    // Get element info from snapshot if available
+                    if (window.sentience && window.sentience_registry) {
+                        const el = window.sentience_registry[elementId];
+                        if (el) {
+                            const rect = el.getBoundingClientRect();
+                            const text = el.getAttribute('aria-label') ||
+                                        el.value ||
+                                        el.placeholder ||
+                                        el.alt ||
+                                        (el.innerText || '').substring(0, 50);
+
+                            const role = el.getAttribute('role') || el.tagName.toLowerCase();
+
+                            console.log(`[Sentience Inspector] Element #${elementId}: role=${role}, text="${text}", bbox=(${Math.round(rect.x)}, ${Math.round(rect.y)}, ${Math.round(rect.width)}, ${Math.round(rect.height)})`);
+                        }
+                    }
+                }
+
+                // Click handler
+                function handleClick(e) {
+                    if (!window.__sentience_inspector_active) return;
+
+                    e.preventDefault();
+                    e.stopPropagation();
+
+                    const elementId = getElementAtPoint(e.clientX, e.clientY);
+                    if (elementId === null) return;
+
+                    // Get full element info
+                    if (window.sentience && window.sentience_registry) {
+                        const el = window.sentience_registry[elementId];
+                        if (el) {
+                            const rect = el.getBoundingClientRect();
+                            const info = {
+                                id: elementId,
+                                tag: el.tagName.toLowerCase(),
+                                role: el.getAttribute('role') || 'generic',
+                                text: el.getAttribute('aria-label') ||
+                                      el.value ||
+                                      el.placeholder ||
+                                      el.alt ||
+                                      (el.innerText || '').substring(0, 100),
+                                bbox: {
+                                    x: Math.round(rect.x),
+                                    y: Math.round(rect.y),
+                                    width: Math.round(rect.width),
+                                    height: Math.round(rect.height)
+                                },
+                                attributes: {
+                                    id: el.id || null,
+                                    class: el.className || null,
+                                    name: el.name || null,
+                                    type: el.type || null
+                                }
+                            };
+
+                            console.log('[Sentience Inspector] Clicked element:', JSON.stringify(info, null, 2));
+
+                            // Also try to get from snapshot if available
+                            window.sentience.snapshot({ limit: 100 }).then(snap => {
+                                const element = snap.elements.find(el => el.id === elementId);
+                                if (element) {
+                                    console.log('[Sentience Inspector] Snapshot element:', JSON.stringify(element, null, 2));
+                                }
+                            }).catch(() => {});
+                        }
+                    }
+                }
+
+                // Add event listeners
+                document.addEventListener('mousemove', handleMouseMove, true);
+                document.addEventListener('click', handleClick, true);
+
+                // Store cleanup function
+                window.__sentience_inspector_cleanup = () => {
+                    document.removeEventListener('mousemove', handleMouseMove, true);
+                    document.removeEventListener('click', handleClick, true);
+                    window.__sentience_inspector_active = false;
+                };
+
+                console.log('[Sentience Inspector] ✅ Inspection mode active. Hover elements to see info, click to see full details.');
+            })();
+        """
+        )
+
+    async def stop(self) -> None:
+        """Stop inspection mode (async)"""
+        if not self.browser.page:
+            return
+
+        self._active = False
+
+        # Cleanup inspector
+        await self.browser.page.evaluate(
+            """
+            () => {
+                if (window.__sentience_inspector_cleanup) {
+                    window.__sentience_inspector_cleanup();
+                }
+            }
+        """
+        )
+
+    async def __aenter__(self):
+        """Context manager entry"""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        await self.stop()
+
+
+def inspect_async(browser: AsyncSentienceBrowser) -> InspectorAsync:
+    """
+    Create an inspector instance (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+
+    Returns:
+        InspectorAsync instance
+    """
+    return InspectorAsync(browser)

sentience/llm_interaction_handler.py

@@ -0,0 +1,191 @@
+"""
+LLM Interaction Handler for Sentience Agent.
+
+Handles all LLM-related operations: context building, querying, and response parsing.
+This separates LLM interaction concerns from action execution.
+"""
+
+import re
+
+from .llm_provider import LLMProvider, LLMResponse
+from .models import Snapshot
+
+
+class LLMInteractionHandler:
+    """
+    Handles LLM queries and response parsing for Sentience Agent.
+
+    This class encapsulates all LLM interaction logic, making it easier to:
+    - Test LLM interactions independently
+    - Swap LLM providers without changing agent code
+    - Modify prompt templates in one place
+    """
+
+    def __init__(self, llm: LLMProvider):
+        """
+        Initialize LLM interaction handler.
+
+        Args:
+            llm: LLM provider instance (OpenAIProvider, AnthropicProvider, etc.)
+        """
+        self.llm = llm
+
+    def build_context(self, snap: Snapshot, goal: str | None = None) -> str:
+        """
+        Convert snapshot elements to token-efficient prompt string.
+
+        Format: [ID] <role> "text" {cues} @ position size:WxH importance:score [status]
+
+        Args:
+            snap: Snapshot object
+            goal: Optional user goal (for context, currently unused but kept for API consistency)
+
+        Returns:
+            Formatted element context string
+        """
+        lines = []
+        for el in 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
+            cues: list[str] = []
+            if el.visual_cues.is_primary:
+                cues.append("PRIMARY")
+            if el.visual_cues.is_clickable:
+                cues.append("CLICKABLE")
+            if el.visual_cues.background_color_name:
+                cues.append(f"color:{el.visual_cues.background_color_name}")
+
+            # Format element line with improved readability
+            # Ensure cues is defined before using it in f-string
+            cues_str = f" {{{','.join(cues)}}}" if cues else ""
+
+            # Better text handling - show truncation indicator
+            text_preview = ""
+            if el.text:
+                if len(el.text) > 50:
+                    text_preview = f'"{el.text[:50]}..."'
+                else:
+                    text_preview = f'"{el.text}"'
+
+            # Build position and size info
+            x, y = int(el.bbox.x), int(el.bbox.y)
+            width, height = int(el.bbox.width), int(el.bbox.height)
+            position_str = f"@ ({x},{y})"
+            size_str = f"size:{width}x{height}"
+
+            # Build status indicators (only include if relevant)
+            status_parts = []
+            if not el.in_viewport:
+                status_parts.append("not_in_viewport")
+            if el.is_occluded:
+                status_parts.append("occluded")
+            if el.diff_status:
+                status_parts.append(f"diff:{el.diff_status}")
+            status_str = f" [{','.join(status_parts)}]" if status_parts else ""
+
+            # Format: [ID] <role> "text" {cues} @ (x,y) size:WxH importance:score [status]
+            lines.append(
+                f"[{el.id}] <{el.role}> {text_preview}{cues_str} "
+                f"{position_str} {size_str} importance:{el.importance}{status_str}"
+            )
+
+        return "\n".join(lines)
+
+    def query_llm(self, dom_context: str, goal: str) -> LLMResponse:
+        """
+        Query LLM with standardized prompt template.
+
+        Args:
+            dom_context: Formatted element context from build_context()
+            goal: User goal
+
+        Returns:
+            LLMResponse from LLM provider
+        """
+        system_prompt = f"""You are an AI web automation agent.
+
+GOAL: {goal}
+
+VISIBLE ELEMENTS (sorted by importance):
+{dom_context}
+
+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)```
+"""
+
+        user_prompt = "Return the single action command:"
+
+        return self.llm.generate(system_prompt, user_prompt, temperature=0.0)
+
+    def extract_action(self, response: str) -> str:
+        """
+        Extract action command from LLM response.
+
+        Handles cases where the LLM adds extra explanation despite instructions.
+
+        Args:
+            response: Raw LLM response text
+
+        Returns:
+            Cleaned action command string (e.g., "CLICK(42)", "TYPE(15, \"text\")")
+        """
+        # Remove markdown code blocks if present
+        response = re.sub(r"```[\w]*\n?", "", response)
+        response = response.strip()
+
+        # Try to find action patterns in the response
+        # Pattern matches: CLICK(123), TYPE(123, "text"), PRESS("key"), FINISH()
+        action_pattern = r'(CLICK\s*\(\s*\d+\s*\)|TYPE\s*\(\s*\d+\s*,\s*["\'].*?["\']\s*\)|PRESS\s*\(\s*["\'].*?["\']\s*\)|FINISH\s*\(\s*\))'
+
+        match = re.search(action_pattern, response, re.IGNORECASE)
+        if match:
+            return match.group(1)
+
+        # If no pattern match, return the original response (will likely fail parsing)
+        return response