sentienceapi 0.95.0__py3-none-any.whl

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,367 @@
+from typing import Optional
+
+"""
+Inspector tool - helps developers see what the agent "sees"
+"""
+
+from .browser import AsyncSentienceBrowser, 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)
+
+
+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)