sentienceapi 0.90.9__py3-none-any.whl

sentience/extension/release.json

@@ -0,0 +1,115 @@
+{
+  "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,
+  "author": {
+    "login": "github-actions[bot]",
+    "id": 41898282,
+    "node_id": "MDM6Qm90NDE4OTgyODI=",
+    "avatar_url": "https://avatars.githubusercontent.com/in/15368?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",
+    "user_view_type": "public",
+    "site_admin": false
+  },
+  "node_id": "RE_kwDOQshiJ84QR4U3",
+  "tag_name": "v2.0.7",
+  "target_commitish": "main",
+  "name": "Release v2.0.7",
+  "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",
+  "assets": [
+    {
+      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/333966751",
+      "id": 333966751,
+      "node_id": "RA_kwDOQshiJ84T5-2f",
+      "name": "extension-files.tar.gz",
+      "label": "",
+      "uploader": {
+        "login": "github-actions[bot]",
+        "id": 41898282,
+        "node_id": "MDM6Qm90NDE4OTgyODI=",
+        "avatar_url": "https://avatars.githubusercontent.com/in/15368?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",
+        "user_view_type": "public",
+        "site_admin": false
+      },
+      "content_type": "application/gzip",
+      "state": "uploaded",
+      "size": 78091,
+      "digest": "sha256:e281f8b755b61da4b8015d6172064aa9a337c14133ceceff4ab29199ee53307e",
+      "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-files.tar.gz"
+    },
+    {
+      "url": "https://api.github.com/repos/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/assets/333966752",
+      "id": 333966752,
+      "node_id": "RA_kwDOQshiJ84T5-2g",
+      "name": "extension-package.zip",
+      "label": "",
+      "uploader": {
+        "login": "github-actions[bot]",
+        "id": 41898282,
+        "node_id": "MDM6Qm90NDE4OTgyODI=",
+        "avatar_url": "https://avatars.githubusercontent.com/in/15368?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",
+        "user_view_type": "public",
+        "site_admin": false
+      },
+      "content_type": "application/zip",
+      "state": "uploaded",
+      "size": 80179,
+      "digest": "sha256:a025edeb8b6d05bfb25c57f913b68507060653ecbdf616000a46df4cb8dec377",
+      "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"
+    }
+  ],
+  "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"
+}

sentience/extension/test-content.js

@@ -0,0 +1,4 @@
+// test-content.js - Simple test script
+console.log('TEST: Extension content script is loading!');
+window.testExtension = true;
+alert('Extension loaded!');

sentience/formatting.py

@@ -0,0 +1,59 @@
+"""
+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.
+
+    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] + "..."
+
+        # 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})"
+        )
+
+    return "\n".join(lines)

sentience/generator.py

@@ -0,0 +1,202 @@
+"""
+Script Generator - converts trace into executable code
+"""
+
+from .recorder import Trace, TraceStep
+
+
+class ScriptGenerator:
+    """Generates Python or TypeScript code from a trace"""
+
+    def __init__(self, trace: Trace):
+        self.trace = trace
+
+    def generate_python(self) -> str:
+        """Generate Python script from trace"""
+        lines = [
+            '"""',
+            f"Generated script from trace: {self.trace.start_url}",
+            f"Created: {self.trace.created_at}",
+            '"""',
+            "",
+            "from sentience import SentienceBrowser, snapshot, find, click, type_text, press",
+            "",
+            "def main():",
+            "    with SentienceBrowser(headless=False) as browser:",
+            f'        browser.page.goto("{self.trace.start_url}")',
+            '        browser.page.wait_for_load_state("networkidle")',
+            "",
+        ]
+
+        for step in self.trace.steps:
+            lines.extend(self._generate_python_step(step, indent="        "))
+
+        lines.extend(
+            [
+                "",
+                'if __name__ == "__main__":',
+                "    main()",
+            ]
+        )
+
+        return "\n".join(lines)
+
+    def generate_typescript(self) -> str:
+        """Generate TypeScript script from trace"""
+        lines = [
+            "/**",
+            f" * Generated script from trace: {self.trace.start_url}",
+            f" * Created: {self.trace.created_at}",
+            " */",
+            "",
+            "import { SentienceBrowser, snapshot, find, click, typeText, press } from './src';",
+            "",
+            "async function main() {",
+            "  const browser = new SentienceBrowser(undefined, false);",
+            "",
+            "  try {",
+            "    await browser.start();",
+            f"    await browser.getPage().goto('{self.trace.start_url}');",
+            "    await browser.getPage().waitForLoadState('networkidle');",
+            "",
+        ]
+
+        for step in self.trace.steps:
+            lines.extend(self._generate_typescript_step(step, indent="    "))
+
+        lines.extend(
+            [
+                "  } finally {",
+                "    await browser.close();",
+                "  }",
+                "}",
+                "",
+                "main().catch(console.error);",
+            ]
+        )
+
+        return "\n".join(lines)
+
+    def _generate_python_step(self, step: TraceStep, indent: str = "") -> list[str]:
+        """Generate Python code for a single step"""
+        lines = []
+
+        if step.type == "navigation":
+            lines.append(f"{indent}# Navigate to {step.url}")
+            lines.append(f'{indent}browser.page.goto("{step.url}")')
+            lines.append(f'{indent}browser.page.wait_for_load_state("networkidle")')
+
+        elif step.type == "click":
+            if step.selector:
+                # Use semantic selector
+                lines.append(f"{indent}# Click: {step.selector}")
+                lines.append(f"{indent}snap = snapshot(browser)")
+                lines.append(f'{indent}element = find(snap, "{step.selector}")')
+                lines.append(f"{indent}if element:")
+                lines.append(f"{indent}    click(browser, element.id)")
+                lines.append(f"{indent}else:")
+                lines.append(f'{indent}    raise Exception("Element not found: {step.selector}")')
+            elif step.element_id is not None:
+                # Fallback to element ID
+                lines.append(f"{indent}# TODO: replace with semantic selector")
+                lines.append(f"{indent}click(browser, {step.element_id})")
+            lines.append("")
+
+        elif step.type == "type":
+            if step.selector:
+                lines.append(f"{indent}# Type into: {step.selector}")
+                lines.append(f"{indent}snap = snapshot(browser)")
+                lines.append(f'{indent}element = find(snap, "{step.selector}")')
+                lines.append(f"{indent}if element:")
+                lines.append(f'{indent}    type_text(browser, element.id, "{step.text}")')
+                lines.append(f"{indent}else:")
+                lines.append(f'{indent}    raise Exception("Element not found: {step.selector}")')
+            elif step.element_id is not None:
+                lines.append(f"{indent}# TODO: replace with semantic selector")
+                lines.append(f'{indent}type_text(browser, {step.element_id}, "{step.text}")')
+            lines.append("")
+
+        elif step.type == "press":
+            lines.append(f"{indent}# Press key: {step.key}")
+            lines.append(f'{indent}press(browser, "{step.key}")')
+            lines.append("")
+
+        return lines
+
+    def _generate_typescript_step(self, step: TraceStep, indent: str = "") -> list[str]:
+        """Generate TypeScript code for a single step"""
+        lines = []
+
+        if step.type == "navigation":
+            lines.append(f"{indent}// Navigate to {step.url}")
+            lines.append(f"{indent}await browser.getPage().goto('{step.url}');")
+            lines.append(f"{indent}await browser.getPage().waitForLoadState('networkidle');")
+
+        elif step.type == "click":
+            if step.selector:
+                lines.append(f"{indent}// Click: {step.selector}")
+                lines.append(f"{indent}const snap = await snapshot(browser);")
+                lines.append(f"{indent}const element = find(snap, '{step.selector}');")
+                lines.append(f"{indent}if (element) {{")
+                lines.append(f"{indent}  await click(browser, element.id);")
+                lines.append(f"{indent}}} else {{")
+                lines.append(f"{indent}  throw new Error('Element not found: {step.selector}');")
+                lines.append(f"{indent}}}")
+            elif step.element_id is not None:
+                lines.append(f"{indent}// TODO: replace with semantic selector")
+                lines.append(f"{indent}await click(browser, {step.element_id});")
+            lines.append("")
+
+        elif step.type == "type":
+            if step.selector:
+                lines.append(f"{indent}// Type into: {step.selector}")
+                lines.append(f"{indent}const snap = await snapshot(browser);")
+                lines.append(f"{indent}const element = find(snap, '{step.selector}');")
+                lines.append(f"{indent}if (element) {{")
+                lines.append(f"{indent}  await typeText(browser, element.id, '{step.text}');")
+                lines.append(f"{indent}}} else {{")
+                lines.append(f"{indent}  throw new Error('Element not found: {step.selector}');")
+                lines.append(f"{indent}}}")
+            elif step.element_id is not None:
+                lines.append(f"{indent}// TODO: replace with semantic selector")
+                lines.append(f"{indent}await typeText(browser, {step.element_id}, '{step.text}');")
+            lines.append("")
+
+        elif step.type == "press":
+            lines.append(f"{indent}// Press key: {step.key}")
+            lines.append(f"{indent}await press(browser, '{step.key}');")
+            lines.append("")
+
+        return lines
+
+    def save_python(self, filepath: str) -> None:
+        """Generate and save Python script"""
+        code = self.generate_python()
+        with open(filepath, "w") as f:
+            f.write(code)
+
+    def save_typescript(self, filepath: str) -> None:
+        """Generate and save TypeScript script"""
+        code = self.generate_typescript()
+        with open(filepath, "w") as f:
+            f.write(code)
+
+
+def generate(trace: Trace, language: str = "py") -> str:
+    """
+    Generate script from trace
+
+    Args:
+        trace: Trace object
+        language: 'py' or 'ts'
+
+    Returns:
+        Generated code as string
+    """
+    generator = ScriptGenerator(trace)
+    if language == "py":
+        return generator.generate_python()
+    elif language == "ts":
+        return generator.generate_typescript()
+    else:
+        raise ValueError(f"Unsupported language: {language}. Use 'py' or 'ts'")

sentience/inspector.py

@@ -0,0 +1,185 @@
+"""
+Inspector tool - helps developers see what the agent "sees"
+"""
+
+from .browser import SentienceBrowser
+
+
+class Inspector:
+    """Inspector for debugging - shows element info on hover/click"""
+
+    def __init__(self, browser: SentienceBrowser):
+        self.browser = browser
+        self._active = False
+        self._last_element_id: int | None = None
+
+    def start(self) -> None:
+        """Start inspection mode - prints element info on mouse move/click"""
+        if not self.browser.page:
+            raise RuntimeError("Browser not started. Call browser.start() first.")
+
+        self._active = True
+
+        # Inject inspector script into page
+        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.');
+            })();
+        """
+        )
+
+    def stop(self) -> None:
+        """Stop inspection mode"""
+        if not self.browser.page:
+            return
+
+        self._active = False
+
+        # Cleanup inspector
+        self.browser.page.evaluate(
+            """
+            () => {
+                if (window.__sentience_inspector_cleanup) {
+                    window.__sentience_inspector_cleanup();
+                }
+            }
+        """
+        )
+
+    def __enter__(self):
+        """Context manager entry"""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.stop()
+
+
+def inspect(browser: SentienceBrowser) -> Inspector:
+    """
+    Create an inspector instance
+
+    Args:
+        browser: SentienceBrowser instance
+
+    Returns:
+        Inspector instance
+    """
+    return Inspector(browser)