sentienceapi 0.90.17__py3-none-any.whl

sentience/tracing.py

@@ -0,0 +1,285 @@
+"""
+Trace event writer for Sentience agents.
+
+Provides abstract interface and JSONL implementation for emitting trace events.
+"""
+
+import json
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TraceEvent:
+    """
+    Trace event data structure.
+
+    Represents a single event in the agent execution trace.
+    """
+
+    v: int  # Schema version
+    type: str  # Event type
+    ts: str  # ISO 8601 timestamp
+    run_id: str  # UUID for the run
+    seq: int  # Sequence number
+    data: dict[str, Any]  # Event payload
+    step_id: str | None = None  # UUID for the step (if step-scoped)
+    ts_ms: int | None = None  # Unix timestamp in milliseconds
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "v": self.v,
+            "type": self.type,
+            "ts": self.ts,
+            "run_id": self.run_id,
+            "seq": self.seq,
+            "data": self.data,
+        }
+
+        if self.step_id is not None:
+            result["step_id"] = self.step_id
+
+        if self.ts_ms is not None:
+            result["ts_ms"] = self.ts_ms
+
+        return result
+
+
+class TraceSink(ABC):
+    """
+    Abstract interface for trace event sink.
+
+    Implementations can write to files, databases, or remote services.
+    """
+
+    @abstractmethod
+    def emit(self, event: dict[str, Any]) -> None:
+        """
+        Emit a trace event.
+
+        Args:
+            event: Event dictionary (from TraceEvent.to_dict())
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close the sink and flush any buffered data."""
+        pass
+
+
+class JsonlTraceSink(TraceSink):
+    """
+    JSONL file sink for trace events.
+
+    Writes one JSON object per line to a file.
+    """
+
+    def __init__(self, path: str | Path):
+        """
+        Initialize JSONL sink.
+
+        Args:
+            path: File path to write traces to
+        """
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open file in append mode with line buffering
+        self._file = open(self.path, "a", encoding="utf-8", buffering=1)
+
+    def emit(self, event: dict[str, Any]) -> None:
+        """
+        Emit event as JSONL line.
+
+        Args:
+            event: Event dictionary
+        """
+        json_str = json.dumps(event, ensure_ascii=False)
+        self._file.write(json_str + "\n")
+
+    def close(self) -> None:
+        """Close the file and generate index."""
+        if hasattr(self, "_file") and not self._file.closed:
+            self._file.close()
+
+        # Generate index after closing file
+        self._generate_index()
+
+    def _generate_index(self) -> None:
+        """Generate trace index file (automatic on close)."""
+        try:
+            from .trace_indexing import write_trace_index
+
+            write_trace_index(str(self.path))
+        except Exception as e:
+            # Non-fatal: log but don't crash
+            print(f"⚠️  Failed to generate trace index: {e}")
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager cleanup."""
+        self.close()
+        return False
+
+
+@dataclass
+class Tracer:
+    """
+    Trace event builder and emitter.
+
+    Manages sequence numbers and provides convenient methods for emitting events.
+    """
+
+    run_id: str
+    sink: TraceSink
+    seq: int = field(default=0, init=False)
+
+    def emit(
+        self,
+        event_type: str,
+        data: dict[str, Any],
+        step_id: str | None = None,
+    ) -> None:
+        """
+        Emit a trace event.
+
+        Args:
+            event_type: Type of event (e.g., 'run_start', 'step_end')
+            data: Event-specific payload
+            step_id: Step UUID (if step-scoped event)
+        """
+        self.seq += 1
+
+        # Generate timestamps
+        ts_ms = int(time.time() * 1000)
+        ts = time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+
+        event = TraceEvent(
+            v=1,
+            type=event_type,
+            ts=ts,
+            ts_ms=ts_ms,
+            run_id=self.run_id,
+            seq=self.seq,
+            step_id=step_id,
+            data=data,
+        )
+
+        self.sink.emit(event.to_dict())
+
+    def emit_run_start(
+        self,
+        agent: str,
+        llm_model: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Emit run_start event.
+
+        Args:
+            agent: Agent name (e.g., 'SentienceAgent')
+            llm_model: LLM model name
+            config: Agent configuration
+        """
+        data: dict[str, Any] = {"agent": agent}
+        if llm_model is not None:
+            data["llm_model"] = llm_model
+        if config is not None:
+            data["config"] = config
+
+        self.emit("run_start", data)
+
+    def emit_step_start(
+        self,
+        step_id: str,
+        step_index: int,
+        goal: str,
+        attempt: int = 0,
+        pre_url: str | None = None,
+    ) -> None:
+        """
+        Emit step_start event.
+
+        Args:
+            step_id: Step UUID
+            step_index: Step number (1-indexed)
+            goal: Step goal description
+            attempt: Attempt number (0-indexed)
+            pre_url: URL before step
+        """
+        data = {
+            "step_id": step_id,
+            "step_index": step_index,
+            "goal": goal,
+            "attempt": attempt,
+        }
+        if pre_url is not None:
+            data["pre_url"] = pre_url
+
+        self.emit("step_start", data, step_id=step_id)
+
+    def emit_run_end(self, steps: int) -> None:
+        """
+        Emit run_end event.
+
+        Args:
+            steps: Total number of steps executed
+        """
+        self.emit("run_end", {"steps": steps})
+
+    def emit_error(
+        self,
+        step_id: str,
+        error: str,
+        attempt: int = 0,
+    ) -> None:
+        """
+        Emit error event.
+
+        Args:
+            step_id: Step UUID
+            error: Error message
+            attempt: Attempt number when error occurred
+        """
+        data = {
+            "step_id": step_id,
+            "error": error,
+            "attempt": attempt,
+        }
+        self.emit("error", data, step_id=step_id)
+
+    def close(self, **kwargs) -> None:
+        """
+        Close the underlying sink.
+
+        Args:
+            **kwargs: Passed through to sink.close() (e.g., blocking=True for CloudTraceSink)
+        """
+        # Check if sink.close() accepts kwargs (CloudTraceSink does, JsonlTraceSink doesn't)
+        import inspect
+
+        sig = inspect.signature(self.sink.close)
+        if any(
+            p.kind in (inspect.Parameter.VAR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+            for p in sig.parameters.values()
+        ):
+            self.sink.close(**kwargs)
+        else:
+            self.sink.close()
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager cleanup."""
+        self.close()
+        return False

sentience/utils.py

@@ -0,0 +1,296 @@
+"""
+Digest utilities for snapshot canonicalization and hashing.
+
+Provides functions to compute stable digests of snapshots for determinism diff.
+Two digest strategies:
+- strict: includes structure + normalized text
+- loose: structure only (no text) - detects layout changes vs content changes
+"""
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from playwright.sync_api import BrowserContext
+
+
+@dataclass
+class BBox:
+    """Bounding box with normalized coordinates."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @classmethod
+    def from_dict(cls, bbox_dict: dict[str, Any]) -> "BBox":
+        """Create BBox from dictionary."""
+        return cls(
+            x=int(bbox_dict.get("x", 0)),
+            y=int(bbox_dict.get("y", 0)),
+            width=int(bbox_dict.get("width", 0)),
+            height=int(bbox_dict.get("height", 0)),
+        )
+
+    def to_normalized(self, bucket_size: int = 2) -> list[int]:
+        """
+        Normalize bbox to fixed-size buckets to ignore minor jitter.
+
+        Args:
+            bucket_size: Pixel bucket size (default 2px)
+
+        Returns:
+            List of [x, y, width, height] rounded to buckets
+        """
+        return [
+            round(self.x / bucket_size) * bucket_size,
+            round(self.y / bucket_size) * bucket_size,
+            round(self.width / bucket_size) * bucket_size,
+            round(self.height / bucket_size) * bucket_size,
+        ]
+
+
+@dataclass
+class ElementFingerprint:
+    """Normalized element data for digest computation."""
+
+    id: int
+    role: str
+    bbox: list[int]  # Normalized
+    clickable: int  # 0 or 1
+    primary: int  # 0 or 1
+    text: str = ""  # Empty for loose digest
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        data = {
+            "id": self.id,
+            "role": self.role,
+            "bbox": self.bbox,
+            "clickable": self.clickable,
+            "primary": self.primary,
+        }
+        if self.text:  # Only include text if non-empty
+            data["text"] = self.text
+        return data
+
+
+def normalize_text_strict(text: str | None, max_length: int = 80) -> str:
+    """
+    Normalize text for strict digest (structure + content).
+
+    Rules:
+    - Lowercase
+    - Trim and collapse whitespace
+    - Cap length at max_length
+    - Replace digit runs with '#'
+    - Normalize currency: $79.99 -> $#
+    - Normalize time patterns: 12:34 -> #:#
+
+    Args:
+        text: Input text
+        max_length: Maximum text length (default 80)
+
+    Returns:
+        Normalized text string
+    """
+    if not text:
+        return ""
+
+    # Lowercase and trim
+    text = text.strip().lower()
+
+    # Collapse whitespace
+    text = " ".join(text.split())
+
+    # Cap length
+    text = text[:max_length]
+
+    # Replace digit runs with #
+    text = re.sub(r"\d+", "#", text)
+
+    # Normalize currency
+    text = re.sub(r"\$\s*#", "$#", text)
+
+    # Normalize time patterns (HH:MM or similar)
+    text = re.sub(r"#:#", "#:#", text)
+
+    # Normalize date patterns (YYYY-MM-DD or similar)
+    text = re.sub(r"#-#-#", "#-#-#", text)
+
+    return text
+
+
+def normalize_bbox(bbox: dict[str, Any] | BBox, bucket_size: int = 2) -> list[int]:
+    """
+    Round bbox to fixed-size buckets to ignore jitter.
+
+    Args:
+        bbox: BBox object or dict with x, y, width, height
+        bucket_size: Pixel bucket size (default 2px)
+
+    Returns:
+        List of [x, y, width, height] rounded to buckets
+    """
+    if isinstance(bbox, BBox):
+        return bbox.to_normalized(bucket_size)
+
+    bbox_obj = BBox.from_dict(bbox)
+    return bbox_obj.to_normalized(bucket_size)
+
+
+def extract_element_fingerprint(
+    element: dict[str, Any],
+    include_text: bool = True,
+) -> ElementFingerprint:
+    """
+    Extract normalized fingerprint from element dict.
+
+    Args:
+        element: Element dict from snapshot
+        include_text: Whether to include normalized text (False for loose digest)
+
+    Returns:
+        ElementFingerprint with normalized data
+    """
+    # Extract basic fields
+    element_id = element.get("id", 0)
+    role = element.get("role", "unknown")
+
+    # Extract and normalize bbox
+    bbox_data = element.get("bbox", {})
+    bbox_normalized = normalize_bbox(bbox_data)
+
+    # Extract visual cues
+    visual_cues = element.get("visual_cues", {})
+    clickable = 1 if visual_cues.get("is_clickable", False) else 0
+    primary = 1 if visual_cues.get("is_primary", False) else 0
+
+    # Extract and normalize text (if requested)
+    text = ""
+    if include_text:
+        raw_text = element.get("text", "")
+        text = normalize_text_strict(raw_text)
+
+    return ElementFingerprint(
+        id=element_id,
+        role=role,
+        bbox=bbox_normalized,
+        clickable=clickable,
+        primary=primary,
+        text=text,
+    )
+
+
+def canonical_snapshot_strict(elements: list[dict[str, Any]]) -> str:
+    """
+    Create strict snapshot digest (structure + normalized text).
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Canonical JSON string for hashing
+    """
+    fingerprints = []
+
+    for element in sorted(elements, key=lambda e: e.get("id", 0)):
+        fingerprint = extract_element_fingerprint(element, include_text=True)
+        fingerprints.append(fingerprint.to_dict())
+
+    return json.dumps(fingerprints, sort_keys=True, ensure_ascii=False)
+
+
+def canonical_snapshot_loose(elements: list[dict[str, Any]]) -> str:
+    """
+    Create loose snapshot digest (structure only, no text).
+
+    This is more resistant to content churn (prices, ads, timestamps).
+    Use for detecting structural changes vs content changes.
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Canonical JSON string for hashing
+    """
+    fingerprints = []
+
+    for element in sorted(elements, key=lambda e: e.get("id", 0)):
+        fingerprint = extract_element_fingerprint(element, include_text=False)
+        fingerprints.append(fingerprint.to_dict())
+
+    return json.dumps(fingerprints, sort_keys=True, ensure_ascii=False)
+
+
+def sha256_digest(canonical_str: str) -> str:
+    """
+    Compute SHA256 hash with 'sha256:' prefix.
+
+    Args:
+        canonical_str: Canonical string to hash
+
+    Returns:
+        Hash string with format: "sha256:<hex>"
+    """
+    hash_obj = hashlib.sha256(canonical_str.encode("utf-8"))
+    return f"sha256:{hash_obj.hexdigest()}"
+
+
+def compute_snapshot_digests(elements: list[dict[str, Any]]) -> dict[str, str]:
+    """
+    Compute both strict and loose digests for a snapshot.
+
+    Args:
+        elements: List of element dicts from snapshot
+
+    Returns:
+        Dict with 'strict' and 'loose' digest strings
+    """
+    canonical_strict = canonical_snapshot_strict(elements)
+    canonical_loose = canonical_snapshot_loose(elements)
+
+    return {
+        "strict": sha256_digest(canonical_strict),
+        "loose": sha256_digest(canonical_loose),
+    }
+
+
+def save_storage_state(context: BrowserContext, file_path: str | Path) -> None:
+    """
+    Save current browser storage state (cookies + localStorage) to a file.
+
+    This is useful for capturing a logged-in session to reuse later.
+
+    Args:
+        context: Playwright BrowserContext
+        file_path: Path to save the storage state JSON file
+
+    Example:
+        ```python
+        from sentience import SentienceBrowser, save_storage_state
+
+        browser = SentienceBrowser()
+        browser.start()
+
+        # User logs in manually or via agent
+        browser.goto("https://example.com")
+        # ... login happens ...
+
+        # Save session for later
+        save_storage_state(browser.context, "auth.json")
+        ```
+
+    Raises:
+        IOError: If file cannot be written
+    """
+    storage_state = context.storage_state()
+    file_path_obj = Path(file_path)
+    file_path_obj.parent.mkdir(parents=True, exist_ok=True)
+    with open(file_path_obj, "w") as f:
+        json.dump(storage_state, f, indent=2)
+    print(f"✅ [Sentience] Saved storage state to {file_path_obj}")

sentience/wait.py

@@ -0,0 +1,137 @@
+"""
+Wait functionality - wait_for element matching selector
+"""
+
+import asyncio
+import time
+
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .models import SnapshotOptions, WaitResult
+from .query import find
+from .snapshot import snapshot, snapshot_async
+
+
+def wait_for(
+    browser: SentienceBrowser,
+    selector: str | dict,
+    timeout: float = 10.0,
+    interval: float | None = None,
+    use_api: bool | None = None,
+) -> WaitResult:
+    """
+    Wait for element matching selector to appear
+
+    Args:
+        browser: SentienceBrowser instance
+        selector: String DSL or dict query
+        timeout: Maximum time to wait (seconds)
+        interval: Polling interval (seconds). If None, auto-detects:
+                  - 0.25s for local extension (use_api=False, fast)
+                  - 1.5s for remote API (use_api=True or default, network latency)
+        use_api: Force use of server-side API if True, local extension if False.
+                 If None, uses API if api_key is set, otherwise uses local extension.
+
+    Returns:
+        WaitResult
+    """
+    # Auto-detect optimal interval based on API usage
+    if interval is None:
+        # Determine if using API
+        will_use_api = use_api if use_api is not None else (browser.api_key is not None)
+        if will_use_api:
+            interval = 1.5  # Longer interval for API calls (network latency)
+        else:
+            interval = 0.25  # Shorter interval for local extension (fast)
+
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        # Take snapshot (may be local extension or remote API)
+        snap = snapshot(browser, SnapshotOptions(use_api=use_api))
+
+        # Try to find element
+        element = find(snap, selector)
+
+        if element:
+            duration_ms = int((time.time() - start_time) * 1000)
+            return WaitResult(
+                found=True,
+                element=element,
+                duration_ms=duration_ms,
+                timeout=False,
+            )
+
+        # Wait before next poll
+        time.sleep(interval)
+
+    # Timeout
+    duration_ms = int((time.time() - start_time) * 1000)
+    return WaitResult(
+        found=False,
+        element=None,
+        duration_ms=duration_ms,
+        timeout=True,
+    )
+
+
+async def wait_for_async(
+    browser: AsyncSentienceBrowser,
+    selector: str | dict,
+    timeout: float = 10.0,
+    interval: float | None = None,
+    use_api: bool | None = None,
+) -> WaitResult:
+    """
+    Wait for element matching selector to appear (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        selector: String DSL or dict query
+        timeout: Maximum time to wait (seconds)
+        interval: Polling interval (seconds). If None, auto-detects:
+                  - 0.25s for local extension (use_api=False, fast)
+                  - 1.5s for remote API (use_api=True or default, network latency)
+        use_api: Force use of server-side API if True, local extension if False.
+                 If None, uses API if api_key is set, otherwise uses local extension.
+
+    Returns:
+        WaitResult
+    """
+    # Auto-detect optimal interval based on API usage
+    if interval is None:
+        # Determine if using API
+        will_use_api = use_api if use_api is not None else (browser.api_key is not None)
+        if will_use_api:
+            interval = 1.5  # Longer interval for API calls (network latency)
+        else:
+            interval = 0.25  # Shorter interval for local extension (fast)
+
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        # Take snapshot (may be local extension or remote API)
+        snap = await snapshot_async(browser, SnapshotOptions(use_api=use_api))
+
+        # Try to find element
+        element = find(snap, selector)
+
+        if element:
+            duration_ms = int((time.time() - start_time) * 1000)
+            return WaitResult(
+                found=True,
+                element=element,
+                duration_ms=duration_ms,
+                timeout=False,
+            )
+
+        # Wait before next poll
+        await asyncio.sleep(interval)
+
+    # Timeout
+    duration_ms = int((time.time() - start_time) * 1000)
+    return WaitResult(
+        found=False,
+        element=None,
+        duration_ms=duration_ms,
+        timeout=True,
+    )