sentienceapi 0.90.9__py3-none-any.whl

sentience/agent_config.py

@@ -0,0 +1,43 @@
+"""
+Configuration classes for Sentience agents.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentConfig:
+    """
+    Configuration for Sentience Agent execution.
+
+    This dataclass provides centralized configuration for agent behavior,
+    including snapshot limits, retry logic, verification, and screenshot capture.
+
+    Attributes:
+        snapshot_limit: Maximum elements to include in LLM context (default: 50)
+        temperature: LLM temperature 0.0-1.0 for response generation (default: 0.0)
+        max_retries: Number of retries on action failure (default: 1)
+        verify: Whether to run verification step after actions (default: True)
+        capture_screenshots: Whether to capture screenshots during execution (default: True)
+        screenshot_format: Screenshot format 'png' or 'jpeg' (default: 'jpeg')
+        screenshot_quality: JPEG quality 1-100, ignored for PNG (default: 80)
+
+    Example:
+        >>> from sentience import AgentConfig, SentienceAgent
+        >>> config = AgentConfig(
+        ...     snapshot_limit=100,
+        ...     max_retries=2,
+        ...     verify=True
+        ... )
+        >>> agent = SentienceAgent(browser, llm, config=config)
+    """
+
+    snapshot_limit: int = 50
+    temperature: float = 0.0
+    max_retries: int = 1
+    verify: bool = True
+
+    # Screenshot options
+    capture_screenshots: bool = True
+    screenshot_format: str = "jpeg"  # "png" or "jpeg"
+    screenshot_quality: int = 80  # 1-100 (for JPEG only)

sentience/base_agent.py

@@ -0,0 +1,101 @@
+"""
+BaseAgent: Abstract base class for all Sentience agents
+Defines the interface that all agent implementations must follow
+"""
+
+from abc import ABC, abstractmethod
+
+from .models import ActionHistory, AgentActionResult, Element, Snapshot, TokenStats
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all Sentience agents.
+
+    Provides a standard interface for:
+    - Executing natural language goals (act)
+    - Tracking execution history
+    - Monitoring token usage
+    - Filtering elements based on goals
+
+    Subclasses must implement:
+    - act(): Execute a natural language goal
+    - get_history(): Return execution history
+    - get_token_stats(): Return token usage statistics
+    - clear_history(): Reset history and token counters
+
+    Subclasses can override:
+    - filter_elements(): Customize element filtering logic
+    """
+
+    @abstractmethod
+    def act(self, goal: str, **kwargs) -> AgentActionResult:
+        """
+        Execute a natural language goal using the agent.
+
+        Args:
+            goal: Natural language instruction (e.g., "Click the login button")
+            **kwargs: Additional parameters (implementation-specific)
+
+        Returns:
+            AgentActionResult with execution details
+
+        Raises:
+            RuntimeError: If execution fails after retries
+        """
+        pass
+
+    @abstractmethod
+    def get_history(self) -> list[ActionHistory]:
+        """
+        Get the execution history of all actions taken.
+
+        Returns:
+            List of ActionHistory entries
+        """
+        pass
+
+    @abstractmethod
+    def get_token_stats(self) -> TokenStats:
+        """
+        Get token usage statistics for the agent session.
+
+        Returns:
+            TokenStats with cumulative token counts
+        """
+        pass
+
+    @abstractmethod
+    def clear_history(self) -> None:
+        """
+        Clear execution history and reset token counters.
+
+        This resets the agent to a clean state.
+        """
+        pass
+
+    def filter_elements(self, snapshot: Snapshot, goal: str | None = None) -> list[Element]:
+        """
+        Filter elements from a snapshot based on goal context.
+
+        Default implementation returns all elements unchanged.
+        Subclasses can override to implement custom filtering logic
+        such as:
+        - Removing irrelevant elements based on goal keywords
+        - Boosting importance of matching elements
+        - Filtering by role, size, or visual properties
+
+        Args:
+            snapshot: Current page snapshot
+            goal: User's goal (can inform filtering strategy)
+
+        Returns:
+            Filtered list of elements (default: all elements)
+
+        Example:
+            >>> agent = SentienceAgent(browser, llm)
+            >>> snap = snapshot(browser)
+            >>> filtered = agent.filter_elements(snap, goal="Click login")
+            >>> # filtered now contains only relevant elements
+        """
+        return snapshot.elements

sentience/browser.py

@@ -0,0 +1,409 @@
+"""
+Playwright browser harness with extension loading
+"""
+
+import os
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+from playwright.sync_api import BrowserContext, Page, Playwright, sync_playwright
+
+from sentience.models import ProxyConfig, StorageState
+
+# Import stealth for bot evasion (optional - graceful fallback if not available)
+try:
+    from playwright_stealth import stealth_sync
+
+    STEALTH_AVAILABLE = True
+except ImportError:
+    STEALTH_AVAILABLE = False
+
+
+class SentienceBrowser:
+    """Main browser session with Sentience extension loaded"""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_url: str | None = None,
+        headless: bool | None = None,
+        proxy: str | None = None,
+        user_data_dir: str | None = None,
+        storage_state: str | Path | StorageState | dict | None = None,
+    ):
+        """
+        Initialize Sentience browser
+
+        Args:
+            api_key: Optional API key for server-side processing (Pro/Enterprise tiers)
+                    If None, uses free tier (local extension only)
+            api_url: Server URL for API calls (defaults to https://api.sentienceapi.com if api_key provided)
+                    If None and api_key is provided, uses default URL
+                    If None and no api_key, uses free tier (local extension only)
+                    If 'local' or Docker sidecar URL, uses Enterprise tier
+            headless: Whether to run in headless mode. If None, defaults to True in CI, False otherwise
+            proxy: Optional proxy server URL (e.g., 'http://user:pass@proxy.example.com:8080')
+                   Supports HTTP, HTTPS, and SOCKS5 proxies
+                   Falls back to SENTIENCE_PROXY environment variable if not provided
+            user_data_dir: Optional path to user data directory for persistent sessions.
+                          If None, uses temporary directory (session not persisted).
+                          If provided, cookies and localStorage persist across browser restarts.
+            storage_state: Optional storage state to inject (cookies + localStorage).
+                          Can be:
+                          - Path to JSON file (str or Path)
+                          - StorageState object
+                          - Dictionary with 'cookies' and/or 'origins' keys
+                          If provided, browser starts with pre-injected authentication.
+        """
+        self.api_key = api_key
+        # Only set api_url if api_key is provided, otherwise None (free tier)
+        # Defaults to production API if key is present but url is missing
+        if self.api_key and not api_url:
+            self.api_url = "https://api.sentienceapi.com"
+        else:
+            self.api_url = api_url
+
+        # Determine headless mode
+        if headless is None:
+            # Default to False for local dev, True for CI
+            self.headless = os.environ.get("CI", "").lower() == "true"
+        else:
+            self.headless = headless
+
+        # Support proxy from argument or environment variable
+        self.proxy = proxy or os.environ.get("SENTIENCE_PROXY")
+
+        # Auth injection support
+        self.user_data_dir = user_data_dir
+        self.storage_state = storage_state
+
+        self.playwright: Playwright | None = None
+        self.context: BrowserContext | None = None
+        self.page: Page | None = None
+        self._extension_path: str | None = None
+
+    def _parse_proxy(self, proxy_string: str) -> ProxyConfig | None:
+        """
+        Parse proxy connection string into ProxyConfig.
+
+        Args:
+            proxy_string: Proxy URL (e.g., 'http://user:pass@proxy.example.com:8080')
+
+        Returns:
+            ProxyConfig object or None if invalid
+
+        Raises:
+            ValueError: If proxy format is invalid
+        """
+        if not proxy_string:
+            return None
+
+        try:
+            parsed = urlparse(proxy_string)
+
+            # Validate scheme
+            if parsed.scheme not in ("http", "https", "socks5"):
+                print(f"⚠️  [Sentience] Unsupported proxy scheme: {parsed.scheme}")
+                print("   Supported: http, https, socks5")
+                return None
+
+            # Validate host and port
+            if not parsed.hostname or not parsed.port:
+                print("⚠️  [Sentience] Proxy URL must include hostname and port")
+                print("   Expected format: http://username:password@host:port")
+                return None
+
+            # Build server URL
+            server = f"{parsed.scheme}://{parsed.hostname}:{parsed.port}"
+
+            # Create ProxyConfig with optional credentials
+            return ProxyConfig(
+                server=server,
+                username=parsed.username if parsed.username else None,
+                password=parsed.password if parsed.password else None,
+            )
+
+        except Exception as e:
+            print(f"⚠️  [Sentience] Invalid proxy configuration: {e}")
+            print("   Expected format: http://username:password@host:port")
+            return None
+
+    def start(self) -> None:
+        """Launch browser with extension loaded"""
+        # Get extension source path (relative to project root/package)
+        # Handle both development (src/) and installed package cases
+
+        # 1. Try relative to this file (installed package structure)
+        # sentience/browser.py -> sentience/extension/
+        package_ext_path = Path(__file__).parent / "extension"
+
+        # 2. Try development root (if running from source repo)
+        # sentience/browser.py -> ../sentience-chrome
+        dev_ext_path = Path(__file__).parent.parent.parent / "sentience-chrome"
+
+        if package_ext_path.exists() and (package_ext_path / "manifest.json").exists():
+            extension_source = package_ext_path
+        elif dev_ext_path.exists() and (dev_ext_path / "manifest.json").exists():
+            extension_source = dev_ext_path
+        else:
+            raise FileNotFoundError(
+                f"Extension not found. Checked:\n"
+                f"1. {package_ext_path}\n"
+                f"2. {dev_ext_path}\n"
+                "Make sure the extension is built and 'sentience/extension' directory exists."
+            )
+
+        # Create temporary extension bundle
+        # We copy it to a temp dir to avoid file locking issues and ensure clean state
+        self._extension_path = tempfile.mkdtemp(prefix="sentience-ext-")
+        shutil.copytree(extension_source, self._extension_path, dirs_exist_ok=True)
+
+        self.playwright = sync_playwright().start()
+
+        # Build launch arguments
+        args = [
+            f"--disable-extensions-except={self._extension_path}",
+            f"--load-extension={self._extension_path}",
+            "--disable-blink-features=AutomationControlled",  # Hides 'navigator.webdriver'
+            "--no-sandbox",
+            "--disable-infobars",
+            # WebRTC leak protection (prevents real IP exposure when using proxies/VPNs)
+            "--disable-features=WebRtcHideLocalIpsWithMdns",
+            "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+        ]
+
+        # Handle headless mode correctly for extensions
+        # 'headless=True' DOES NOT support extensions in standard Chrome
+        # We must use 'headless="new"' (Chrome 112+) or run visible
+        # launch_headless_arg = False  # Default to visible
+        if self.headless:
+            args.append("--headless=new")  # Use new headless mode via args
+
+        # Parse proxy configuration if provided
+        proxy_config = self._parse_proxy(self.proxy) if self.proxy else None
+
+        # Handle User Data Directory (Persistence)
+        if self.user_data_dir:
+            user_data_dir = str(self.user_data_dir)
+            Path(user_data_dir).mkdir(parents=True, exist_ok=True)
+        else:
+            user_data_dir = ""  # Ephemeral temp dir (existing behavior)
+
+        # Build launch_persistent_context parameters
+        launch_params = {
+            "user_data_dir": user_data_dir,
+            "headless": False,  # IMPORTANT: See note above
+            "args": args,
+            "viewport": {"width": 1280, "height": 800},
+            # Remove "HeadlessChrome" from User Agent automatically
+            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+        }
+
+        # Add proxy if configured
+        if proxy_config:
+            launch_params["proxy"] = proxy_config.to_playwright_dict()
+            # Ignore HTTPS errors when using proxy (many residential proxies use self-signed certs)
+            launch_params["ignore_https_errors"] = True
+            print(f"🌐 [Sentience] Using proxy: {proxy_config.server}")
+
+        # Launch persistent context (required for extensions)
+        # Note: We pass headless=False to launch_persistent_context because we handle
+        # headless mode via the --headless=new arg above. This is a Playwright workaround.
+        self.context = self.playwright.chromium.launch_persistent_context(**launch_params)
+
+        self.page = self.context.pages[0] if self.context.pages else self.context.new_page()
+
+        # Inject storage state if provided (must be after context creation)
+        if self.storage_state:
+            self._inject_storage_state(self.storage_state)
+
+        # Apply stealth if available
+        if STEALTH_AVAILABLE:
+            stealth_sync(self.page)
+
+        # Wait a moment for extension to initialize
+        time.sleep(0.5)
+
+    def goto(self, url: str) -> None:
+        """Navigate to a URL and ensure extension is ready"""
+        if not self.page:
+            raise RuntimeError("Browser not started. Call start() first.")
+
+        self.page.goto(url, wait_until="domcontentloaded")
+
+        # Wait for extension to be ready (injected into page)
+        if not self._wait_for_extension():
+            # Gather diagnostic info before failing
+            try:
+                diag = self.page.evaluate(
+                    """() => ({
+                    sentience_defined: typeof window.sentience !== 'undefined',
+                    registry_defined: typeof window.sentience_registry !== 'undefined',
+                    snapshot_defined: window.sentience && typeof window.sentience.snapshot === 'function',
+                    extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                    url: window.location.href
+                })"""
+                )
+            except Exception as e:
+                diag = f"Failed to get diagnostics: {str(e)}"
+
+            raise RuntimeError(
+                "Extension failed to load after navigation. Make sure:\n"
+                "1. Extension is built (cd sentience-chrome && ./build.sh)\n"
+                "2. All files are present (manifest.json, content.js, injected_api.js, pkg/)\n"
+                "3. Check browser console for errors (run with headless=False to see console)\n"
+                f"4. Extension path: {self._extension_path}\n"
+                f"5. Diagnostic info: {diag}"
+            )
+
+    def _inject_storage_state(
+        self, storage_state: str | Path | StorageState | dict
+    ) -> None:  # noqa: C901
+        """
+        Inject storage state (cookies + localStorage) into browser context.
+
+        Args:
+            storage_state: Path to JSON file, StorageState object, or dict containing storage state
+        """
+        import json
+
+        # Load storage state
+        if isinstance(storage_state, (str, Path)):
+            # Load from file
+            with open(storage_state, encoding="utf-8") as f:
+                state_dict = json.load(f)
+            state = StorageState.from_dict(state_dict)
+        elif isinstance(storage_state, StorageState):
+            # Already a StorageState object
+            state = storage_state
+        elif isinstance(storage_state, dict):
+            # Dictionary format
+            state = StorageState.from_dict(storage_state)
+        else:
+            raise ValueError(
+                f"Invalid storage_state type: {type(storage_state)}. "
+                "Expected str, Path, StorageState, or dict."
+            )
+
+        # Inject cookies (works globally)
+        if state.cookies:
+            # Convert to Playwright cookie format
+            playwright_cookies = []
+            for cookie in state.cookies:
+                cookie_dict = cookie.model_dump()
+                # Playwright expects lowercase keys for some fields
+                playwright_cookie = {
+                    "name": cookie_dict["name"],
+                    "value": cookie_dict["value"],
+                    "domain": cookie_dict["domain"],
+                    "path": cookie_dict["path"],
+                }
+                if cookie_dict.get("expires"):
+                    playwright_cookie["expires"] = cookie_dict["expires"]
+                if cookie_dict.get("httpOnly"):
+                    playwright_cookie["httpOnly"] = cookie_dict["httpOnly"]
+                if cookie_dict.get("secure"):
+                    playwright_cookie["secure"] = cookie_dict["secure"]
+                if cookie_dict.get("sameSite"):
+                    playwright_cookie["sameSite"] = cookie_dict["sameSite"]
+                playwright_cookies.append(playwright_cookie)
+
+            self.context.add_cookies(playwright_cookies)
+            print(f"✅ [Sentience] Injected {len(state.cookies)} cookie(s)")
+
+        # Inject LocalStorage (requires navigation to each domain)
+        if state.origins:
+            for origin_data in state.origins:
+                origin = origin_data.origin
+                if not origin:
+                    continue
+
+                # Navigate to origin to set localStorage
+                try:
+                    self.page.goto(origin, wait_until="domcontentloaded", timeout=10000)
+
+                    # Inject localStorage
+                    if origin_data.localStorage:
+                        # Convert to dict format for JavaScript
+                        localStorage_dict = {
+                            item.name: item.value for item in origin_data.localStorage
+                        }
+                        self.page.evaluate(
+                            """(localStorage_data) => {
+                                for (const [key, value] of Object.entries(localStorage_data)) {
+                                    localStorage.setItem(key, value);
+                                }
+                            }""",
+                            localStorage_dict,
+                        )
+                        print(
+                            f"✅ [Sentience] Injected {len(origin_data.localStorage)} localStorage item(s) for {origin}"
+                        )
+                except Exception as e:
+                    print(f"⚠️  [Sentience] Failed to inject localStorage for {origin}: {e}")
+
+    def _wait_for_extension(self, timeout_sec: float = 5.0) -> bool:
+        """Poll for window.sentience to be available"""
+        start_time = time.time()
+        last_error = None
+
+        while time.time() - start_time < timeout_sec:
+            try:
+                # Check if API exists and WASM is ready (optional check for _wasmModule)
+                result = self.page.evaluate(
+                    """() => {
+                        if (typeof window.sentience === 'undefined') {
+                            return { ready: false, reason: 'window.sentience undefined' };
+                        }
+                        // Check if WASM loaded (if exposed) or if basic API works
+                        // Note: injected_api.js defines window.sentience immediately,
+                        // but _wasmModule might take a few ms to load.
+                        if (window.sentience._wasmModule === null) {
+                             // It's defined but WASM isn't linked yet
+                             return { ready: false, reason: 'WASM module not fully loaded' };
+                        }
+                        // If _wasmModule is not exposed, that's okay - it might be internal
+                        // Just verify the API structure is correct
+                        return { ready: true };
+                    }
+                """
+                )
+
+                if isinstance(result, dict):
+                    if result.get("ready"):
+                        return True
+                    last_error = result.get("reason", "Unknown error")
+            except Exception as e:
+                # Continue waiting on errors
+                last_error = f"Evaluation error: {str(e)}"
+
+            time.sleep(0.3)
+
+        # Log the last error for debugging
+        if last_error:
+            import warnings
+
+            warnings.warn(f"Extension wait timeout. Last status: {last_error}")
+
+        return False
+
+    def close(self) -> None:
+        """Close browser and cleanup"""
+        if self.context:
+            self.context.close()
+        if self.playwright:
+            self.playwright.stop()
+        if self._extension_path and os.path.exists(self._extension_path):
+            shutil.rmtree(self._extension_path)
+
+    def __enter__(self):
+        """Context manager entry"""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.close()

sentience/cli.py

@@ -0,0 +1,130 @@
+"""
+CLI commands for Sentience SDK
+"""
+
+import argparse
+import sys
+
+from .browser import SentienceBrowser
+from .generator import ScriptGenerator
+from .inspector import inspect
+from .recorder import Trace, record
+
+
+def cmd_inspect(args):
+    """Start inspector mode"""
+    browser = SentienceBrowser(headless=False)
+    try:
+        browser.start()
+        print("✅ Inspector started. Hover elements to see info, click to see full details.")
+        print("Press Ctrl+C to stop.")
+
+        with inspect(browser):
+            # Keep running until interrupted
+            import time
+
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print("\n👋 Inspector stopped.")
+    finally:
+        browser.close()
+
+
+def cmd_record(args):
+    """Start recording mode"""
+    browser = SentienceBrowser(headless=False)
+    try:
+        browser.start()
+
+        # Navigate to start URL if provided
+        if args.url:
+            browser.page.goto(args.url)
+            browser.page.wait_for_load_state("networkidle")
+
+        print("✅ Recording started. Perform actions in the browser.")
+        print("Press Ctrl+C to stop and save trace.")
+
+        with record(browser, capture_snapshots=args.snapshots) as rec:
+            # Add mask patterns if provided
+            for pattern in args.mask or []:
+                rec.add_mask_pattern(pattern)
+
+            # Keep running until interrupted
+            import time
+
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print("\n💾 Saving trace...")
+                output = args.output or "trace.json"
+                rec.save(output)
+                print(f"✅ Trace saved to {output}")
+    finally:
+        browser.close()
+
+
+def cmd_gen(args):
+    """Generate script from trace"""
+    # Load trace
+    trace = Trace.load(args.trace)
+
+    # Generate script
+    generator = ScriptGenerator(trace)
+
+    if args.lang == "py":
+        output = args.output or "generated.py"
+        generator.save_python(output)
+    elif args.lang == "ts":
+        output = args.output or "generated.ts"
+        generator.save_typescript(output)
+    else:
+        print(f"❌ Unsupported language: {args.lang}")
+        sys.exit(1)
+
+    print(f"✅ Generated {args.lang.upper()} script: {output}")
+
+
+def main():
+    """Main CLI entry point"""
+    parser = argparse.ArgumentParser(description="Sentience SDK CLI")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # Inspect command
+    inspect_parser = subparsers.add_parser("inspect", help="Start inspector mode")
+    inspect_parser.set_defaults(func=cmd_inspect)
+
+    # Record command
+    record_parser = subparsers.add_parser("record", help="Start recording mode")
+    record_parser.add_argument("--url", help="Start URL")
+    record_parser.add_argument("--output", "-o", help="Output trace file", default="trace.json")
+    record_parser.add_argument(
+        "--snapshots", action="store_true", help="Capture snapshots at each step"
+    )
+    record_parser.add_argument(
+        "--mask",
+        action="append",
+        help="Pattern to mask in recorded text (e.g., password)",
+    )
+    record_parser.set_defaults(func=cmd_record)
+
+    # Generate command
+    gen_parser = subparsers.add_parser("gen", help="Generate script from trace")
+    gen_parser.add_argument("trace", help="Trace JSON file")
+    gen_parser.add_argument("--lang", choices=["py", "ts"], default="py", help="Output language")
+    gen_parser.add_argument("--output", "-o", help="Output script file")
+    gen_parser.set_defaults(func=cmd_gen)
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()