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

sentience/snapshot_diff.py

@@ -2,10 +2,12 @@
 Snapshot comparison utilities for diff_status detection.
 
 Implements change detection logic for the Diff Overlay feature.
-"""
 
-from typing import Literal
+Uses shared canonicalization helpers from canonicalization.py to ensure
+consistent comparison behavior with trace_indexing/indexer.py.
+"""
 
+from .canonicalization import bbox_changed, content_changed
 from .models import Element, Snapshot
 
 
@@ -18,55 +20,30 @@ class SnapshotDiff:
     - REMOVED: Element existed in previous but not in current
     - MODIFIED: Element exists in both but has changed
     - MOVED: Element exists in both but position changed
-    """
-
-    @staticmethod
-    def _has_bbox_changed(el1: Element, el2: Element, threshold: float = 5.0) -> bool:
-        """
-        Check if element's bounding box has changed significantly.
 
-        Args:
-            el1: First element
-            el2: Second element
-            threshold: Position change threshold in pixels (default: 5.0)
-
-        Returns:
-            True if position or size changed beyond threshold
-        """
-        return (
-            abs(el1.bbox.x - el2.bbox.x) > threshold
-            or abs(el1.bbox.y - el2.bbox.y) > threshold
-            or abs(el1.bbox.width - el2.bbox.width) > threshold
-            or abs(el1.bbox.height - el2.bbox.height) > threshold
-        )
+    Uses canonicalized comparisons (normalized text, rounded bbox) to reduce
+    noise from insignificant changes like sub-pixel rendering differences
+    or whitespace variations.
+    """
 
     @staticmethod
-    def _has_content_changed(el1: Element, el2: Element) -> bool:
-        """
-        Check if element's content has changed.
-
-        Args:
-            el1: First element
-            el2: Second element
-
-        Returns:
-            True if text, role, or visual properties changed
-        """
-        # Compare text content
-        if el1.text != el2.text:
-            return True
-
-        # Compare role
-        if el1.role != el2.role:
-            return True
-
-        # Compare visual cues
-        if el1.visual_cues.is_primary != el2.visual_cues.is_primary:
-            return True
-        if el1.visual_cues.is_clickable != el2.visual_cues.is_clickable:
-            return True
-
-        return False
+    def _element_to_dict(el: Element) -> dict:
+        """Convert Element model to dict for canonicalization helpers."""
+        return {
+            "id": el.id,
+            "role": el.role,
+            "text": el.text,
+            "bbox": {
+                "x": el.bbox.x,
+                "y": el.bbox.y,
+                "width": el.bbox.width,
+                "height": el.bbox.height,
+            },
+            "visual_cues": {
+                "is_primary": el.visual_cues.is_primary,
+                "is_clickable": el.visual_cues.is_clickable,
+            },
+        }
 
     @staticmethod
     def compute_diff_status(
@@ -76,6 +53,10 @@ class SnapshotDiff:
         """
         Compare current snapshot with previous and set diff_status on elements.
 
+        Uses canonicalized comparisons:
+        - Text is normalized (trimmed, collapsed whitespace, lowercased)
+        - Bbox is rounded to 2px grid to ignore sub-pixel differences
+
         Args:
             current: Current snapshot
             previous: Previous snapshot (None if this is the first snapshot)
@@ -110,19 +91,23 @@ class SnapshotDiff:
                 # Element is new - mark as ADDED
                 el_dict["diff_status"] = "ADDED"
             else:
-                # Element existed before - check for changes
+                # Element existed before - check for changes using canonicalized comparisons
                 prev_el = previous_by_id[el.id]
 
-                bbox_changed = SnapshotDiff._has_bbox_changed(el, prev_el)
-                content_changed = SnapshotDiff._has_content_changed(el, prev_el)
+                # Convert to dicts for canonicalization helpers
+                el_data = SnapshotDiff._element_to_dict(el)
+                prev_el_data = SnapshotDiff._element_to_dict(prev_el)
+
+                has_bbox_changed = bbox_changed(el_data["bbox"], prev_el_data["bbox"])
+                has_content_changed = content_changed(el_data, prev_el_data)
 
-                if bbox_changed and content_changed:
+                if has_bbox_changed and has_content_changed:
                     # Both position and content changed - mark as MODIFIED
                     el_dict["diff_status"] = "MODIFIED"
-                elif bbox_changed:
+                elif has_bbox_changed:
                     # Only position changed - mark as MOVED
                     el_dict["diff_status"] = "MOVED"
-                elif content_changed:
+                elif has_content_changed:
                     # Only content changed - mark as MODIFIED
                     el_dict["diff_status"] = "MODIFIED"
                 else:

sentience/text_search.py

@@ -5,6 +5,7 @@ Text search utilities - find text and get pixel coordinates
 from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .browser_evaluator import BrowserEvaluator
 from .models import TextRectSearchResult
+from .sentience_methods import SentienceMethod
 
 
 def find_text_rect(

sentience/trace_event_builder.py

@@ -84,6 +84,7 @@ class TraceEventBuilder:
         exec_data: dict[str, Any],
         verify_data: dict[str, Any],
         pre_elements: list[dict[str, Any]] | None = None,
+        assertions: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any]:
         """
         Build step_end trace event data.
@@ -100,6 +101,7 @@ class TraceEventBuilder:
             exec_data: Action execution data
             verify_data: Verification data
             pre_elements: Optional list of elements from pre-snapshot (with diff_status)
+            assertions: Optional list of assertion results from AgentRuntime
 
         Returns:
             Dictionary with step_end event data
@@ -113,6 +115,23 @@ class TraceEventBuilder:
         if pre_elements is not None:
             pre_data["elements"] = pre_elements
 
+        # Build verify data with assertions if provided
+        final_verify_data = verify_data.copy()
+        if assertions:
+            # Ensure signals dict exists
+            if "signals" not in final_verify_data:
+                final_verify_data["signals"] = {}
+
+            # Add assertions to signals
+            final_verify_data["signals"]["assertions"] = assertions
+
+            # Check for task completion (assertions marked as required that passed)
+            for a in assertions:
+                if a.get("passed") and a.get("required"):
+                    final_verify_data["signals"]["task_done"] = True
+                    final_verify_data["signals"]["task_done_label"] = a.get("label")
+                    break
+
         return {
             "v": 1,
             "step_id": step_id,
@@ -125,5 +144,5 @@ class TraceEventBuilder:
             "post": {
                 "url": post_url,
             },
-            "verify": verify_data,
+            "verify": final_verify_data,
         }

sentience/trace_indexing/indexer.py

@@ -9,6 +9,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
+from ..canonicalization import canonicalize_element
 from .index_schema import (
     ActionInfo,
     SnapshotInfo,
@@ -20,30 +21,6 @@ from .index_schema import (
 )
 
 
-def _normalize_text(text: str | None, max_len: int = 80) -> str:
-    """Normalize text for digest: trim, collapse whitespace, lowercase, cap length."""
-    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 (default: 2px precision)."""
-    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 _compute_snapshot_digest(snapshot_data: dict[str, Any]) -> str:
     """
     Compute stable digest of snapshot for diffing.
@@ -55,31 +32,8 @@ def _compute_snapshot_digest(snapshot_data: dict[str, Any]) -> str:
     viewport = snapshot_data.get("viewport", {})
     elements = snapshot_data.get("elements", [])
 
-    # Canonicalize elements
-    canonical_elements = []
-    for elem in elements:
-        # 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)
-        )
-
-        canonical_elem = {
-            "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,
-        }
-        canonical_elements.append(canonical_elem)
+    # Canonicalize elements using shared helper
+    canonical_elements = [canonicalize_element(elem) for elem in elements]
 
     # Sort by element id for determinism
     canonical_elements.sort(key=lambda e: e.get("id", 0))

sentience/tracer_factory.py

@@ -14,11 +14,9 @@ from typing import Any, Optional
 import requests
 
 from sentience.cloud_tracing import CloudTraceSink, SentienceLogger
+from sentience.constants import SENTIENCE_API_URL
 from sentience.tracing import JsonlTraceSink, Tracer
 
-# Sentience API base URL (constant)
-SENTIENCE_API_URL = "https://api.sentienceapi.com"
-
 
 def create_tracer(
     api_key: str | None = None,