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

sentience/constants.py

@@ -0,0 +1,6 @@
+"""
+Sentience SDK constants.
+"""
+
+# Sentience API endpoint
+SENTIENCE_API_URL = "https://api.sentienceapi.com"

sentience/conversational_agent.py

@@ -5,12 +5,13 @@ Enables end users to control web automation using plain English
 
 import json
 import time
-from typing import Any
+from typing import Any, Union
 
 from .agent import SentienceAgent
 from .browser import SentienceBrowser
 from .llm_provider import LLMProvider
-from .models import Snapshot, SnapshotOptions
+from .models import ExtractionResult, Snapshot, SnapshotOptions, StepExecutionResult
+from .protocols import BrowserProtocol
 from .snapshot import snapshot
 
 
@@ -29,12 +30,18 @@ class ConversationalAgent:
          The top result is from amazon.com selling the Apple Magic Mouse 2 for $79."
     """
 
-    def __init__(self, browser: SentienceBrowser, llm: LLMProvider, verbose: bool = True):
+    def __init__(
+        self,
+        browser: SentienceBrowser | BrowserProtocol,
+        llm: LLMProvider,
+        verbose: bool = True,
+    ):
         """
         Initialize conversational agent
 
         Args:
-            browser: SentienceBrowser instance
+            browser: SentienceBrowser instance or BrowserProtocol-compatible object
+                    (for testing, can use mock objects that implement BrowserProtocol)
             llm: LLM provider (OpenAI, Anthropic, LocalLLM, etc.)
             verbose: Print step-by-step execution logs (default: True)
         """
@@ -90,7 +97,7 @@ class ConversationalAgent:
             step_result = self._execute_step(step)
             execution_results.append(step_result)
 
-            if not step_result.get("success", False):
+            if not step_result.success:
                 # Early exit on failure
                 if self.verbose:
                     print(f"⚠️  Step failed: {step['description']}")
@@ -203,7 +210,7 @@ Create a step-by-step execution plan."""
                 "expected_outcome": "Complete user request",
             }
 
-    def _execute_step(self, step: dict[str, Any]) -> dict[str, Any]:
+    def _execute_step(self, step: dict[str, Any]) -> StepExecutionResult:
         """
         Execute a single atomic step from the plan
 
@@ -230,46 +237,42 @@ Create a step-by-step execution plan."""
                 self.execution_context["current_url"] = url
                 time.sleep(1)  # Brief wait for page to settle
 
-                return {"success": True, "action": action, "data": {"url": url}}
+                return StepExecutionResult(success=True, action=action, data={"url": url})
 
             elif action == "FIND_AND_CLICK":
                 element_desc = params["element_description"]
                 # Use technical agent to find and click (returns AgentActionResult)
                 result = self.technical_agent.act(f"Click the {element_desc}")
-                return {
-                    "success": result.success,  # Use attribute access
-                    "action": action,
-                    "data": result.model_dump(),  # Convert to dict for flexibility
-                }
+                return StepExecutionResult(
+                    success=result.success,
+                    action=action,
+                    data=result.model_dump(),  # Convert to dict for flexibility
+                )
 
             elif action == "FIND_AND_TYPE":
                 element_desc = params["element_description"]
                 text = params["text"]
                 # Use technical agent to find input and type (returns AgentActionResult)
                 result = self.technical_agent.act(f"Type '{text}' into {element_desc}")
-                return {
-                    "success": result.success,  # Use attribute access
-                    "action": action,
-                    "data": {"text": text, "result": result.model_dump()},
-                }
+                return StepExecutionResult(
+                    success=result.success,
+                    action=action,
+                    data={"text": text, "result": result.model_dump()},
+                )
 
             elif action == "PRESS_KEY":
                 key = params["key"]
                 result = self.technical_agent.act(f"Press {key} key")
-                return {
-                    "success": result.success,  # Use attribute access
-                    "action": action,
-                    "data": {"key": key, "result": result.model_dump()},
-                }
+                return StepExecutionResult(
+                    success=result.success,
+                    action=action,
+                    data={"key": key, "result": result.model_dump()},
+                )
 
             elif action == "WAIT":
                 duration = params.get("duration", 2.0)
                 time.sleep(duration)
-                return {
-                    "success": True,
-                    "action": action,
-                    "data": {"duration": duration},
-                }
+                return StepExecutionResult(success=True, action=action, data={"duration": duration})
 
             elif action == "EXTRACT_INFO":
                 info_type = params["info_type"]
@@ -279,21 +282,28 @@ Create a step-by-step execution plan."""
                 # Use LLM to extract specific information
                 extracted = self._extract_information(snap, info_type)
 
-                return {
-                    "success": True,
-                    "action": action,
-                    "data": {"extracted": extracted, "info_type": info_type},
-                }
+                return StepExecutionResult(
+                    success=True,
+                    action=action,
+                    data={
+                        "extracted": (
+                            extracted.model_dump()
+                            if isinstance(extracted, ExtractionResult)
+                            else extracted
+                        ),
+                        "info_type": info_type,
+                    },
+                )
 
             elif action == "VERIFY":
                 condition = params["condition"]
                 # Verify condition using current page state
                 is_verified = self._verify_condition(condition)
-                return {
-                    "success": is_verified,
-                    "action": action,
-                    "data": {"condition": condition, "verified": is_verified},
-                }
+                return StepExecutionResult(
+                    success=is_verified,
+                    action=action,
+                    data={"condition": condition, "verified": is_verified},
+                )
 
             else:
                 raise ValueError(f"Unknown action: {action}")
@@ -301,9 +311,9 @@ Create a step-by-step execution plan."""
         except Exception as e:
             if self.verbose:
                 print(f"❌ Step failed: {e}")
-            return {"success": False, "action": action, "error": str(e)}
+            return StepExecutionResult(success=False, action=action, error=str(e))
 
-    def _extract_information(self, snap: Snapshot, info_type: str) -> dict[str, Any]:
+    def _extract_information(self, snap: Snapshot, info_type: str) -> ExtractionResult:
         """
         Extract specific information from snapshot using LLM
 
@@ -403,14 +413,38 @@ Return JSON:
             Human-readable response string
         """
         # Build summary of what happened
-        successful_steps = [r for r in execution_results if r.get("success")]
-        failed_steps = [r for r in execution_results if not r.get("success")]
+        successful_steps = [
+            r
+            for r in execution_results
+            if (isinstance(r, StepExecutionResult) and r.success)
+            or (isinstance(r, dict) and r.get("success", False))
+        ]
+        failed_steps = [
+            r
+            for r in execution_results
+            if (isinstance(r, StepExecutionResult) and not r.success)
+            or (isinstance(r, dict) and not r.get("success", False))
+        ]
 
         # Extract key data
         extracted_data = []
         for result in execution_results:
-            if result.get("action") == "EXTRACT_INFO":
-                extracted_data.append(result.get("data", {}).get("extracted", {}))
+            if isinstance(result, StepExecutionResult):
+                action = result.action
+                data = result.data
+            else:
+                action = result.get("action")
+                data = result.get("data", {})
+
+            if action == "EXTRACT_INFO":
+                extracted = data.get("extracted", {})
+                if isinstance(extracted, dict):
+                    extracted_data.append(extracted)
+                else:
+                    # If it's an ExtractionResult model, convert to dict
+                    extracted_data.append(
+                        extracted.model_dump() if hasattr(extracted, "model_dump") else extracted
+                    )
 
         # Use LLM to create natural response
         system_prompt = """You are a helpful assistant that summarizes web automation results

sentience/cursor_policy.py

@@ -0,0 +1,142 @@
+"""
+Human-like cursor movement policy + metadata.
+
+This is intentionally SDK-local (no snapshot schema changes). It is used by actions to:
+- generate more realistic mouse movement (multiple moves with easing, optional overshoot/jitter)
+- emit trace/debug metadata describing the movement path
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CursorPolicy:
+    """
+    Policy for cursor movement.
+
+    - mode="instant": current behavior (single click without multi-step motion)
+    - mode="human": move with a curved path + optional jitter/overshoot
+    """
+
+    mode: str = "instant"  # "instant" | "human"
+
+    # Motion shaping (human mode)
+    steps: int | None = None
+    duration_ms: int | None = None
+    jitter_px: float = 1.0
+    overshoot_px: float = 6.0
+    pause_before_click_ms: int = 20
+
+    # Determinism hook for tests/repro
+    seed: int | None = None
+
+
+def _clamp(v: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, v))
+
+
+def _ease_in_out(t: float) -> float:
+    # Smoothstep-ish easing
+    return t * t * (3 - 2 * t)
+
+
+def _bezier(
+    p0: tuple[float, float],
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    p3: tuple[float, float],
+    t: float,
+) -> tuple[float, float]:
+    u = 1.0 - t
+    tt = t * t
+    uu = u * u
+    uuu = uu * u
+    ttt = tt * t
+    x = uuu * p0[0] + 3 * uu * t * p1[0] + 3 * u * tt * p2[0] + ttt * p3[0]
+    y = uuu * p0[1] + 3 * uu * t * p1[1] + 3 * u * tt * p2[1] + ttt * p3[1]
+    return (x, y)
+
+
+def build_human_cursor_path(
+    *,
+    start: tuple[float, float],
+    target: tuple[float, float],
+    policy: CursorPolicy,
+) -> dict:
+    """
+    Build a human-like cursor path and metadata.
+
+    Returns a dict suitable for attaching to ActionResult/trace payloads:
+      {
+        "mode": "human",
+        "from": {"x":..., "y":...},
+        "to": {"x":..., "y":...},
+        "steps": ...,
+        "duration_ms": ...,
+        "pause_before_click_ms": ...,
+        "jitter_px": ...,
+        "overshoot_px": ...,
+        "path": [{"x":..., "y":..., "t":...}, ...]
+      }
+    """
+    rng = random.Random(policy.seed)
+
+    x0, y0 = start
+    x1, y1 = target
+    dx = x1 - x0
+    dy = y1 - y0
+    dist = math.hypot(dx, dy)
+
+    # Defaults based on distance (bounded)
+    steps = int(policy.steps if policy.steps is not None else _clamp(10 + dist / 25.0, 12, 40))
+    duration_ms = int(
+        policy.duration_ms if policy.duration_ms is not None else _clamp(120 + dist * 0.9, 120, 700)
+    )
+
+    # Control points: offset roughly perpendicular to travel direction
+    if dist < 1e-6:
+        dist = 1.0
+    ux, uy = dx / dist, dy / dist
+    px, py = -uy, ux
+    curve_mag = _clamp(dist / 3.5, 10.0, 140.0)
+    curve_mag *= rng.uniform(0.5, 1.2)
+
+    c1 = (x0 + dx * 0.25 + px * curve_mag, y0 + dy * 0.25 + py * curve_mag)
+    c2 = (x0 + dx * 0.75 - px * curve_mag, y0 + dy * 0.75 - py * curve_mag)
+
+    overshoot = float(policy.overshoot_px or 0.0)
+    overshoot_point = (x1 + ux * overshoot, y1 + uy * overshoot) if overshoot > 0 else (x1, y1)
+
+    pts: list[dict] = []
+    for i in range(steps):
+        t_raw = 0.0 if steps <= 1 else i / (steps - 1)
+        t = _ease_in_out(t_raw)
+        bx, by = _bezier((x0, y0), c1, c2, overshoot_point, t)
+
+        # Small jitter, decaying near target
+        jitter_scale = float(policy.jitter_px) * (1.0 - t_raw) * 0.9
+        jx = rng.uniform(-jitter_scale, jitter_scale)
+        jy = rng.uniform(-jitter_scale, jitter_scale)
+
+        pts.append({"x": bx + jx, "y": by + jy, "t": round(t_raw, 4)})
+
+    # If we overshot, add a small correction segment back to target.
+    if overshoot > 0:
+        pts.append({"x": x1, "y": y1, "t": 1.0})
+
+    return {
+        "mode": "human",
+        "from": {"x": x0, "y": y0},
+        "to": {"x": x1, "y": y1},
+        "steps": steps,
+        "duration_ms": duration_ms,
+        "pause_before_click_ms": int(policy.pause_before_click_ms),
+        "jitter_px": float(policy.jitter_px),
+        "overshoot_px": overshoot,
+        # Keep path bounded for trace size
+        "path": pts[:64],
+    }

sentience/element_filter.py

@@ -0,0 +1,136 @@
+"""
+Element filtering utilities for agent-based element selection.
+
+This module provides centralized element filtering logic to reduce duplication
+across agent implementations.
+"""
+
+from typing import Optional
+
+from .models import Element, Snapshot
+
+
+class ElementFilter:
+    """
+    Centralized element filtering logic for agent-based element selection.
+
+    Provides static methods for filtering elements based on:
+    - Importance scores
+    - Goal-based keyword matching
+    - Role and visual properties
+    """
+
+    # Common stopwords for keyword extraction
+    STOPWORDS = {
+        "the",
+        "a",
+        "an",
+        "and",
+        "or",
+        "but",
+        "in",
+        "on",
+        "at",
+        "to",
+        "for",
+        "of",
+        "with",
+        "by",
+        "from",
+        "as",
+        "is",
+        "was",
+    }
+
+    @staticmethod
+    def filter_by_importance(
+        snapshot: Snapshot,
+        max_elements: int = 50,
+    ) -> list[Element]:
+        """
+        Filter elements by importance score (simple top-N selection).
+
+        Args:
+            snapshot: Current page snapshot
+            max_elements: Maximum number of elements to return
+
+        Returns:
+            Top N elements sorted by importance score
+        """
+        # Filter out REMOVED elements - they're not actionable and shouldn't be in LLM context
+        elements = [el for el in snapshot.elements if el.diff_status != "REMOVED"]
+        # Elements are already sorted by importance in snapshot
+        return elements[:max_elements]
+
+    @staticmethod
+    def filter_by_goal(
+        snapshot: Snapshot,
+        goal: str | None,
+        max_elements: int = 100,
+    ) -> list[Element]:
+        """
+        Filter elements from snapshot based on goal context.
+
+        Applies goal-based keyword matching to boost relevant elements
+        and filters out irrelevant ones.
+
+        Args:
+            snapshot: Current page snapshot
+            goal: User's goal (can inform filtering)
+            max_elements: Maximum number of elements to return
+
+        Returns:
+            Filtered list of elements sorted by boosted importance score
+        """
+        # Filter out REMOVED elements - they're not actionable and shouldn't be in LLM context
+        elements = [el for el in snapshot.elements if el.diff_status != "REMOVED"]
+
+        # If no goal provided, return all elements (up to limit)
+        if not goal:
+            return elements[:max_elements]
+
+        goal_lower = goal.lower()
+
+        # Extract keywords from goal
+        keywords = ElementFilter._extract_keywords(goal_lower)
+
+        # Boost elements matching goal keywords
+        scored_elements = []
+        for el in elements:
+            score = el.importance
+
+            # Boost if element text matches goal
+            if el.text and any(kw in el.text.lower() for kw in keywords):
+                score += 0.3
+
+            # Boost if role matches goal intent
+            if "click" in goal_lower and el.visual_cues.is_clickable:
+                score += 0.2
+            if "type" in goal_lower and el.role in ["textbox", "searchbox"]:
+                score += 0.2
+            if "search" in goal_lower:
+                # Filter out non-interactive elements for search tasks
+                if el.role in ["link", "img"] and not el.visual_cues.is_primary:
+                    score -= 0.5
+
+            scored_elements.append((score, el))
+
+        # Re-sort by boosted score
+        scored_elements.sort(key=lambda x: x[0], reverse=True)
+        elements = [el for _, el in scored_elements]
+
+        return elements[:max_elements]
+
+    @staticmethod
+    def _extract_keywords(text: str) -> list[str]:
+        """
+        Extract meaningful keywords from goal text.
+
+        Args:
+            text: Text to extract keywords from
+
+        Returns:
+            List of keywords (non-stopwords, length > 2)
+        """
+        words = text.split()
+        return [w for w in words if w not in ElementFilter.STOPWORDS and len(w) > 2]

sentience/expect.py

@@ -2,12 +2,13 @@
 Expect/Assert functionality
 """
 
+import asyncio
 import time
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .models import Element
 from .query import query
-from .wait import wait_for
+from .wait import wait_for, wait_for_async
 
 
 class Expectation:
@@ -90,3 +91,98 @@ def expect(browser: SentienceBrowser, selector: str | dict) -> Expectation:
         Expectation helper
     """
     return Expectation(browser, selector)
+
+
+class ExpectationAsync:
+    """Assertion helper for element expectations (async)"""
+
+    def __init__(self, browser: AsyncSentienceBrowser, selector: str | dict):
+        self.browser = browser
+        self.selector = selector
+
+    async def to_be_visible(self, timeout: float = 10.0) -> Element:
+        """Assert element is visible (exists and in viewport)"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element not found: {self.selector} (timeout: {timeout}s)")
+
+        element = result.element
+        if not element.in_viewport:
+            raise AssertionError(f"Element found but not visible in viewport: {self.selector}")
+
+        return element
+
+    async def to_exist(self, timeout: float = 10.0) -> Element:
+        """Assert element exists"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element does not exist: {self.selector} (timeout: {timeout}s)")
+
+        return result.element
+
+    async def to_have_text(self, expected_text: str, timeout: float = 10.0) -> Element:
+        """Assert element has specific text"""
+        result = await wait_for_async(self.browser, self.selector, timeout=timeout)
+
+        if not result.found:
+            raise AssertionError(f"Element not found: {self.selector} (timeout: {timeout}s)")
+
+        element = result.element
+        if not element.text or expected_text not in element.text:
+            raise AssertionError(
+                f"Element text mismatch. Expected '{expected_text}', got '{element.text}'"
+            )
+
+        return element
+
+    async def to_have_count(self, expected_count: int, timeout: float = 10.0) -> None:
+        """Assert selector matches exactly N elements"""
+        from .snapshot import snapshot_async
+
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            snap = await snapshot_async(self.browser)
+            matches = query(snap, self.selector)
+
+            if len(matches) == expected_count:
+                return
+
+            await asyncio.sleep(0.25)
+
+        # Final check
+        snap = await snapshot_async(self.browser)
+        matches = query(snap, self.selector)
+        actual_count = len(matches)
+
+        raise AssertionError(
+            f"Element count mismatch. Expected {expected_count}, got {actual_count}"
+        )
+
+
+def expect_async(browser: AsyncSentienceBrowser, selector: str | dict) -> ExpectationAsync:
+    """
+    Create expectation helper for assertions (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        selector: String DSL or dict query
+
+    Returns:
+        ExpectationAsync helper
+
+    Example:
+        # Assert element is visible
+        element = await expect_async(browser, "role=button").to_be_visible()
+
+        # Assert element has text
+        element = await expect_async(browser, "h1").to_have_text("Welcome")
+
+        # Assert element exists
+        element = await expect_async(browser, "role=link").to_exist()
+
+        # Assert count
+        await expect_async(browser, "role=button").to_have_count(5)
+    """
+    return ExpectationAsync(browser, selector)