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

sentience/canonicalization.py

@@ -0,0 +1,207 @@
+"""
+Shared canonicalization utilities for snapshot comparison and indexing.
+
+This module provides consistent normalization functions used by both:
+- trace_indexing/indexer.py (for computing stable digests)
+- snapshot_diff.py (for computing diff_status labels)
+
+By sharing these helpers, we ensure consistent behavior:
+- Same text normalization (whitespace, case, length)
+- Same bbox rounding (2px precision)
+- Same change detection thresholds
+"""
+
+from typing import Any
+
+
+def normalize_text(text: str | None, max_len: int = 80) -> str:
+    """
+    Normalize text for canonical comparison.
+
+    Transforms:
+    - Trims leading/trailing whitespace
+    - Collapses internal whitespace to single spaces
+    - Lowercases
+    - Caps length
+
+    Args:
+        text: Input text (may be None)
+        max_len: Maximum length to retain (default: 80)
+
+    Returns:
+        Normalized text string (empty string if input is None)
+
+    Examples:
+        >>> normalize_text("  Hello   World  ")
+        'hello world'
+        >>> normalize_text(None)
+        ''
+    """
+    if not text:
+        return ""
+    # Trim and collapse whitespace
+    normalized = " ".join(text.split())
+    # Lowercase
+    normalized = normalized.lower()
+    # Cap length
+    if len(normalized) > max_len:
+        normalized = normalized[:max_len]
+    return normalized
+
+
+def round_bbox(bbox: dict[str, float], precision: int = 2) -> dict[str, int]:
+    """
+    Round bbox coordinates to reduce noise.
+
+    Snaps coordinates to grid of `precision` pixels to ignore
+    sub-pixel rendering differences.
+
+    Args:
+        bbox: Bounding box with x, y, width, height
+        precision: Grid size in pixels (default: 2)
+
+    Returns:
+        Rounded bbox with integer coordinates
+
+    Examples:
+        >>> round_bbox({"x": 101, "y": 203, "width": 50, "height": 25})
+        {'x': 100, 'y': 202, 'width': 50, 'height': 24}
+    """
+    return {
+        "x": round(bbox.get("x", 0) / precision) * precision,
+        "y": round(bbox.get("y", 0) / precision) * precision,
+        "width": round(bbox.get("width", 0) / precision) * precision,
+        "height": round(bbox.get("height", 0) / precision) * precision,
+    }
+
+
+def bbox_equal(bbox1: dict[str, Any], bbox2: dict[str, Any], threshold: float = 5.0) -> bool:
+    """
+    Check if two bboxes are equal within a threshold.
+
+    Args:
+        bbox1: First bounding box
+        bbox2: Second bounding box
+        threshold: Maximum allowed difference in pixels (default: 5.0)
+
+    Returns:
+        True if all bbox properties differ by less than threshold
+
+    Examples:
+        >>> bbox_equal({"x": 100, "y": 200, "width": 50, "height": 25},
+        ...            {"x": 102, "y": 200, "width": 50, "height": 25})
+        True  # 2px difference is below 5px threshold
+    """
+    return (
+        abs(bbox1.get("x", 0) - bbox2.get("x", 0)) <= threshold
+        and abs(bbox1.get("y", 0) - bbox2.get("y", 0)) <= threshold
+        and abs(bbox1.get("width", 0) - bbox2.get("width", 0)) <= threshold
+        and abs(bbox1.get("height", 0) - bbox2.get("height", 0)) <= threshold
+    )
+
+
+def bbox_changed(bbox1: dict[str, Any], bbox2: dict[str, Any], threshold: float = 5.0) -> bool:
+    """
+    Check if two bboxes differ beyond the threshold.
+
+    This is the inverse of bbox_equal, provided for semantic clarity
+    in diff detection code.
+
+    Args:
+        bbox1: First bounding box
+        bbox2: Second bounding box
+        threshold: Maximum allowed difference in pixels (default: 5.0)
+
+    Returns:
+        True if any bbox property differs by more than threshold
+    """
+    return not bbox_equal(bbox1, bbox2, threshold)
+
+
+def canonicalize_element(elem: dict[str, Any]) -> dict[str, Any]:
+    """
+    Create canonical representation of an element for comparison/hashing.
+
+    Extracts and normalizes the fields that matter for identity:
+    - id, role, normalized text, rounded bbox
+    - is_primary, is_clickable from visual_cues
+
+    Args:
+        elem: Raw element dictionary
+
+    Returns:
+        Canonical element dictionary with normalized fields
+
+    Examples:
+        >>> canonicalize_element({
+        ...     "id": 1,
+        ...     "role": "button",
+        ...     "text": "  Click Me  ",
+        ...     "bbox": {"x": 101, "y": 200, "width": 50, "height": 25},
+        ...     "visual_cues": {"is_primary": True, "is_clickable": True}
+        ... })
+        {'id': 1, 'role': 'button', 'text_norm': 'click me', 'bbox': {'x': 100, 'y': 200, 'width': 50, 'height': 24}, 'is_primary': True, 'is_clickable': True}
+    """
+    # Extract is_primary and is_clickable from visual_cues if present
+    visual_cues = elem.get("visual_cues", {})
+    is_primary = (
+        visual_cues.get("is_primary", False)
+        if isinstance(visual_cues, dict)
+        else elem.get("is_primary", False)
+    )
+    is_clickable = (
+        visual_cues.get("is_clickable", False)
+        if isinstance(visual_cues, dict)
+        else elem.get("is_clickable", False)
+    )
+
+    return {
+        "id": elem.get("id"),
+        "role": elem.get("role", ""),
+        "text_norm": normalize_text(elem.get("text")),
+        "bbox": round_bbox(elem.get("bbox", {"x": 0, "y": 0, "width": 0, "height": 0})),
+        "is_primary": is_primary,
+        "is_clickable": is_clickable,
+    }
+
+
+def content_equal(elem1: dict[str, Any], elem2: dict[str, Any]) -> bool:
+    """
+    Check if two elements have equal content (ignoring position).
+
+    Compares normalized text, role, and visual cues.
+
+    Args:
+        elem1: First element (raw or canonical)
+        elem2: Second element (raw or canonical)
+
+    Returns:
+        True if content is equal after normalization
+    """
+    # Normalize both elements
+    c1 = canonicalize_element(elem1)
+    c2 = canonicalize_element(elem2)
+
+    return (
+        c1["role"] == c2["role"]
+        and c1["text_norm"] == c2["text_norm"]
+        and c1["is_primary"] == c2["is_primary"]
+        and c1["is_clickable"] == c2["is_clickable"]
+    )
+
+
+def content_changed(elem1: dict[str, Any], elem2: dict[str, Any]) -> bool:
+    """
+    Check if two elements have different content (ignoring position).
+
+    This is the inverse of content_equal, provided for semantic clarity
+    in diff detection code.
+
+    Args:
+        elem1: First element
+        elem2: Second element
+
+    Returns:
+        True if content differs after normalization
+    """
+    return not content_equal(elem1, elem2)

sentience/cloud_tracing.py

@@ -16,6 +16,7 @@ from typing import Any, Optional, Protocol, Union
 
 import requests
 
+from sentience.constants import SENTIENCE_API_URL
 from sentience.models import TraceStats
 from sentience.trace_file_manager import TraceFileManager
 from sentience.tracing import TraceSink
@@ -93,7 +94,7 @@ class CloudTraceSink(TraceSink):
         self.upload_url = upload_url
         self.run_id = run_id
         self.api_key = api_key
-        self.api_url = api_url or "https://api.sentienceapi.com"
+        self.api_url = api_url or SENTIENCE_API_URL
         self.logger = logger
 
         # Use persistent cache directory instead of temp file
@@ -147,40 +148,80 @@ class CloudTraceSink(TraceSink):
 
         self._closed = True
 
-        # Flush and sync file to disk before closing to ensure all data is written
-        # This is critical on CI systems where file system operations may be slower
-        self._trace_file.flush()
+        if not blocking:
+            # Fire-and-forget background finalize+upload.
+            #
+            # IMPORTANT: for truly non-blocking close, we avoid synchronous work here
+            # (flush/fsync/index generation). That work happens in the background thread.
+            thread = threading.Thread(
+                target=self._close_and_upload_background,
+                args=(on_progress,),
+                daemon=True,
+            )
+            thread.start()
+            return  # Return immediately
+
+        # Blocking mode: finalize trace file and upload now.
+        if not self._finalize_trace_file_for_upload():
+            return
+        self._do_upload(on_progress)
+
+    def _finalize_trace_file_for_upload(self) -> bool:
+        """
+        Finalize the local trace file so it is ready for upload.
+
+        Returns:
+            True if there is data to upload, False if the trace is empty/missing.
+        """
+        # Flush and sync file to disk before closing to ensure all data is written.
+        # This can be slow on CI file systems; in non-blocking close we do this in background.
+        try:
+            self._trace_file.flush()
+        except Exception:
+            pass
         try:
-            # Force OS to write buffered data to disk
             os.fsync(self._trace_file.fileno())
         except (OSError, AttributeError):
-            # Some file handles don't support fsync (e.g., StringIO in tests)
-            # This is fine - flush() is usually sufficient
+            # Some file handles don't support fsync; flush is usually sufficient.
+            pass
+        try:
+            self._trace_file.close()
+        except Exception:
             pass
-        self._trace_file.close()
 
         # Ensure file exists and has content before proceeding
-        if not self._path.exists() or self._path.stat().st_size == 0:
-            # No events were emitted, nothing to upload
-            if self.logger:
-                self.logger.warning("No trace events to upload (file is empty or missing)")
-            return
+        try:
+            if not self._path.exists() or self._path.stat().st_size == 0:
+                if self.logger:
+                    self.logger.warning("No trace events to upload (file is empty or missing)")
+                return False
+        except Exception:
+            # If we can't stat, don't attempt upload
+            return False
 
         # Generate index after closing file
         self._generate_index()
+        return True
 
-        if not blocking:
-            # Fire-and-forget background upload
-            thread = threading.Thread(
-                target=self._do_upload,
-                args=(on_progress,),
-                daemon=True,
-            )
-            thread.start()
-            return  # Return immediately
+    def _close_and_upload_background(
+        self, on_progress: Callable[[int, int], None] | None = None
+    ) -> None:
+        """
+        Background worker for non-blocking close.
 
-        # Blocking mode
-        self._do_upload(on_progress)
+        Performs file finalization + index generation + upload.
+        """
+        try:
+            if not self._finalize_trace_file_for_upload():
+                return
+            self._do_upload(on_progress)
+        except Exception as e:
+            # Non-fatal: preserve trace locally
+            self._upload_successful = False
+            print(f"❌ [Sentience] Error uploading trace (background): {e}")
+            print(f"   Local trace preserved at: {self._path}")
+            if self.logger:
+                self.logger.error(f"Error uploading trace (background): {e}")
 
     def _do_upload(self, on_progress: Callable[[int, int], None] | None = None) -> None:
         """

sentience/constants.py

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

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/extension/content.js

@@ -114,6 +114,41 @@
 
           case "SENTIENCE_CLEAR_OVERLAY":
             removeOverlay();
+            break;
+
+          case "SENTIENCE_SHOW_GRID_OVERLAY":
+            !function(data) {
+                const {grids: grids, targetGridId: targetGridId} = data;
+                if (!grids || !Array.isArray(grids)) return;
+                removeOverlay();
+                const host = document.createElement("div");
+                host.id = OVERLAY_HOST_ID, host.style.cssText = "\n        position: fixed !important;\n        top: 0 !important;\n        left: 0 !important;\n        width: 100vw !important;\n        height: 100vh !important;\n        pointer-events: none !important;\n        z-index: 2147483647 !important;\n        margin: 0 !important;\n        padding: 0 !important;\n    ", 
+                document.body.appendChild(host);
+                const shadow = host.attachShadow({
+                    mode: "closed"
+                });
+                grids.forEach(grid => {
+                    const bbox = grid.bbox;
+                    if (!bbox) return;
+                    const isTarget = grid.grid_id === targetGridId, isDominant = !0 === grid.is_dominant;
+                    let color = "#9B59B6";
+                    isTarget ? color = "#FF0000" : isDominant && (color = "#FF8C00");
+                    const borderStyle = isTarget ? "solid" : "dashed", borderWidth = isTarget ? 3 : isDominant ? 2.5 : 2, opacity = isTarget ? 1 : isDominant ? .9 : .8, fillOpacity = .1 * opacity, hexOpacity = Math.round(255 * fillOpacity).toString(16).padStart(2, "0"), box = document.createElement("div");
+                    box.style.cssText = `\n            position: absolute;\n            left: ${bbox.x}px;\n            top: ${bbox.y}px;\n            width: ${bbox.width}px;\n            height: ${bbox.height}px;\n            border: ${borderWidth}px ${borderStyle} ${color};\n            background-color: ${color}${hexOpacity};\n            box-sizing: border-box;\n            opacity: ${opacity};\n            pointer-events: none;\n        `;
+                    let labelText = grid.label ? `Grid ${grid.grid_id}: ${grid.label}` : `Grid ${grid.grid_id}`;
+                    grid.is_dominant && (labelText = `⭐ ${labelText} (dominant)`);
+                    const badge = document.createElement("span");
+                    if (badge.textContent = labelText, badge.style.cssText = `\n                position: absolute;\n                top: -18px;\n                left: 0;\n                background: ${color};\n                color: white;\n                font-size: 11px;\n                font-weight: bold;\n                padding: 2px 6px;\n                font-family: Arial, sans-serif;\n                border-radius: 3px;\n                opacity: 0.95;\n                white-space: nowrap;\n                pointer-events: none;\n            `, 
+                    box.appendChild(badge), isTarget) {
+                        const targetIndicator = document.createElement("span");
+                        targetIndicator.textContent = "🎯", targetIndicator.style.cssText = "\n                position: absolute;\n                top: -18px;\n                right: 0;\n                font-size: 16px;\n                pointer-events: none;\n            ", 
+                        box.appendChild(targetIndicator);
+                    }
+                    shadow.appendChild(box);
+                }), overlayTimeout = setTimeout(() => {
+                    removeOverlay();
+                }, 5e3);
+            }(event.data);
         }
     });
     const OVERLAY_HOST_ID = "sentience-overlay-host";