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

sentience/tracing.py

@@ -4,12 +4,16 @@ 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 collections.abc import Callable
 from dataclasses import dataclass, field
+from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
+
+from .models import TraceStats
+from .trace_file_manager import TraceFileManager
 
 
 @dataclass
@@ -87,7 +91,7 @@ class JsonlTraceSink(TraceSink):
             path: File path to write traces to
         """
         self.path = Path(path)
-        self.path.parent.mkdir(parents=True, exist_ok=True)
+        TraceFileManager.ensure_directory(self.path)
 
         # Open file in append mode with line buffering
         self._file = open(self.path, "a", encoding="utf-8", buffering=1)
@@ -99,8 +103,7 @@ class JsonlTraceSink(TraceSink):
         Args:
             event: Event dictionary
         """
-        json_str = json.dumps(event, ensure_ascii=False)
-        self._file.write(json_str + "\n")
+        TraceFileManager.write_event(self._file, event)
 
     def close(self) -> None:
         """Close the file and generate index."""
@@ -110,12 +113,36 @@ class JsonlTraceSink(TraceSink):
         # Generate index after closing file
         self._generate_index()
 
+    def get_stats(self) -> TraceStats:
+        """
+        Extract execution statistics from trace file (for local traces).
+
+        Returns:
+            TraceStats with execution statistics
+        """
+        try:
+            # Read trace file to extract stats
+            events = TraceFileManager.read_events(self.path)
+            return TraceFileManager.extract_stats(events)
+        except Exception:
+            return TraceStats(
+                total_steps=0,
+                total_events=0,
+                duration_ms=None,
+                final_status="unknown",
+                started_at=None,
+                ended_at=None,
+            )
+
     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))
+            # Use frontend format to ensure 'step' field is present (1-based)
+            # Frontend derives sequence from step.step - 1, so step must be valid
+            index_path = Path(self.path).with_suffix(".index.json")
+            write_trace_index(str(self.path), str(index_path), frontend_format=True)
         except Exception as e:
             # Non-fatal: log but don't crash
             print(f"⚠️  Failed to generate trace index: {e}")
@@ -136,11 +163,48 @@ class Tracer:
     Trace event builder and emitter.
 
     Manages sequence numbers and provides convenient methods for emitting events.
+    Tracks execution statistics and final status for trace completion.
+
+    Args:
+        run_id: Unique identifier for this trace run
+        sink: TraceSink implementation for writing events
+        screenshot_processor: Optional function to process screenshots before emission.
+                            Takes base64 string, returns processed base64 string.
+                            Useful for PII redaction or custom image processing.
+
+    Example:
+        >>> from sentience import Tracer, JsonlTraceSink
+        >>>
+        >>> # Basic usage
+        >>> sink = JsonlTraceSink("trace.jsonl")
+        >>> tracer = Tracer(run_id="abc123", sink=sink)
+        >>>
+        >>> # With screenshot processor for PII redaction
+        >>> def redact_pii(screenshot_base64: str) -> str:
+        ...     # Your custom redaction logic
+        ...     return redacted_screenshot
+        >>>
+        >>> tracer = Tracer(
+        ...     run_id="abc123",
+        ...     sink=sink,
+        ...     screenshot_processor=redact_pii
+        ... )
     """
 
     run_id: str
     sink: TraceSink
+    screenshot_processor: Callable[[str], str] | None = None
     seq: int = field(default=0, init=False)
+    # Stats tracking
+    total_steps: int = field(default=0, init=False)
+    total_events: int = field(default=0, init=False)
+    started_at: datetime | None = field(default=None, init=False)
+    ended_at: datetime | None = field(default=None, init=False)
+    final_status: str = field(default="unknown", init=False)
+    # Track step outcomes for automatic status inference
+    _step_successes: int = field(default=0, init=False)
+    _step_failures: int = field(default=0, init=False)
+    _has_errors: bool = field(default=False, init=False)
 
     def emit(
         self,
@@ -157,6 +221,12 @@ class Tracer:
             step_id: Step UUID (if step-scoped event)
         """
         self.seq += 1
+        self.total_events += 1
+
+        # Apply screenshot processor if configured and screenshot is present
+        if self.screenshot_processor and "screenshot_base64" in data:
+            data = data.copy()  # Don't modify the original dict
+            data["screenshot_base64"] = self.screenshot_processor(data["screenshot_base64"])
 
         # Generate timestamps
         ts_ms = int(time.time() * 1000)
@@ -175,6 +245,16 @@ class Tracer:
 
         self.sink.emit(event.to_dict())
 
+        # Track step outcomes for automatic status inference
+        if event_type == "step_end":
+            success = data.get("success", False)
+            if success:
+                self._step_successes += 1
+            else:
+                self._step_failures += 1
+        elif event_type == "error":
+            self._has_errors = True
+
     def emit_run_start(
         self,
         agent: str,
@@ -189,6 +269,9 @@ class Tracer:
             llm_model: LLM model name
             config: Agent configuration
         """
+        # Track start time
+        self.started_at = datetime.utcnow()
+
         data: dict[str, Any] = {"agent": agent}
         if llm_model is not None:
             data["llm_model"] = llm_model
@@ -215,6 +298,10 @@ class Tracer:
             attempt: Attempt number (0-indexed)
             pre_url: URL before step
         """
+        # Track step count (only count first attempt of each step)
+        if attempt == 0:
+            self.total_steps = max(self.total_steps, step_index)
+
         data = {
             "step_id": step_id,
             "step_index": step_index,
@@ -226,14 +313,29 @@ class Tracer:
 
         self.emit("step_start", data, step_id=step_id)
 
-    def emit_run_end(self, steps: int) -> None:
+    def emit_run_end(self, steps: int, status: str | None = None) -> None:
         """
         Emit run_end event.
 
         Args:
             steps: Total number of steps executed
+            status: Optional final status ("success", "failure", "partial", "unknown")
+                    If not provided, infers from tracked outcomes or uses self.final_status
         """
-        self.emit("run_end", {"steps": steps})
+        # Track end time
+        self.ended_at = datetime.utcnow()
+
+        # Auto-infer status if not provided and not explicitly set
+        if status is None and self.final_status == "unknown":
+            self._infer_final_status()
+
+        # Use provided status or fallback to self.final_status
+        final_status = status if status is not None else self.final_status
+
+        # Ensure total_steps is at least the provided steps value
+        self.total_steps = max(self.total_steps, steps)
+
+        self.emit("run_end", {"steps": steps, "status": final_status})
 
     def emit_error(
         self,
@@ -256,6 +358,62 @@ class Tracer:
         }
         self.emit("error", data, step_id=step_id)
 
+    def set_final_status(self, status: str) -> None:
+        """
+        Set the final status of the trace run.
+
+        Args:
+            status: Final status ("success", "failure", "partial", "unknown")
+        """
+        if status not in ("success", "failure", "partial", "unknown"):
+            raise ValueError(
+                f"Invalid status: {status}. Must be one of: success, failure, partial, unknown"
+            )
+        self.final_status = status
+
+    def get_stats(self) -> TraceStats:
+        """
+        Get execution statistics for trace completion.
+
+        Returns:
+            TraceStats with execution statistics
+        """
+        duration_ms: int | None = None
+        if self.started_at and self.ended_at:
+            delta = self.ended_at - self.started_at
+            duration_ms = int(delta.total_seconds() * 1000)
+
+        return TraceStats(
+            total_steps=self.total_steps,
+            total_events=self.total_events,
+            duration_ms=duration_ms,
+            final_status=self.final_status,
+            started_at=self.started_at.isoformat() + "Z" if self.started_at else None,
+            ended_at=self.ended_at.isoformat() + "Z" if self.ended_at else None,
+        )
+
+    def _infer_final_status(self) -> None:
+        """
+        Automatically infer final_status from tracked step outcomes if not explicitly set.
+
+        This is called automatically in close() if final_status is still "unknown".
+        """
+        if self.final_status != "unknown":
+            # Status already set explicitly, don't override
+            return
+
+        # Infer from tracked outcomes
+        if self._has_errors:
+            # Has errors - check if there were successful steps too
+            if self._step_successes > 0:
+                self.final_status = "partial"
+            else:
+                self.final_status = "failure"
+        elif self._step_successes > 0:
+            # Has successful steps and no errors
+            self.final_status = "success"
+        # Otherwise stays "unknown" (no steps executed or no clear outcome)
+
     def close(self, **kwargs) -> None:
         """
         Close the underlying sink.
@@ -263,6 +421,12 @@ class Tracer:
         Args:
             **kwargs: Passed through to sink.close() (e.g., blocking=True for CloudTraceSink)
         """
+        # Auto-infer final_status if not explicitly set and we have step outcomes
+        if self.final_status == "unknown" and (
+            self._step_successes > 0 or self._step_failures > 0 or self._has_errors
+        ):
+            self._infer_final_status()
+
         # Check if sink.close() accepts kwargs (CloudTraceSink does, JsonlTraceSink doesn't)
         import inspect
 

sentience/utils/__init__.py

@@ -0,0 +1,40 @@
+"""
+Utility functions for Sentience SDK.
+
+This module re-exports all utility functions from submodules for backward compatibility.
+Users can continue using:
+    from sentience.utils import compute_snapshot_digests, canonical_snapshot_strict
+    from sentience import canonical_snapshot_strict, format_snapshot_for_llm
+"""
+
+# Re-export all functions from submodules for backward compatibility
+from .browser import save_storage_state
+from .element import (
+    BBox,
+    ElementFingerprint,
+    canonical_snapshot_loose,
+    canonical_snapshot_strict,
+    compute_snapshot_digests,
+    extract_element_fingerprint,
+    normalize_bbox,
+    normalize_text_strict,
+    sha256_digest,
+)
+from .formatting import format_snapshot_for_llm
+
+__all__ = [
+    # Browser utilities
+    "save_storage_state",
+    # Element/digest utilities
+    "BBox",
+    "ElementFingerprint",
+    "canonical_snapshot_loose",
+    "canonical_snapshot_strict",
+    "compute_snapshot_digests",
+    "extract_element_fingerprint",
+    "normalize_bbox",
+    "normalize_text_strict",
+    "sha256_digest",
+    # Formatting utilities
+    "format_snapshot_for_llm",
+]

sentience/utils/browser.py

@@ -0,0 +1,46 @@
+"""
+Browser-related utilities for Sentience SDK.
+
+Provides functions for managing browser storage state (cookies, localStorage).
+"""
+
+import json
+from pathlib import Path
+
+from playwright.sync_api import BrowserContext
+
+
+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/{utils.py → utils/element.py}

@@ -1,7 +1,7 @@
 """
-Digest utilities for snapshot canonicalization and hashing.
+Element manipulation and digest utilities for Sentience SDK.
 
-Provides functions to compute stable digests of snapshots for determinism diff.
+Provides functions to compute stable digests of snapshots for deterministic diff.
 Two digest strategies:
 - strict: includes structure + normalized text
 - loose: structure only (no text) - detects layout changes vs content changes
@@ -11,10 +11,7 @@ import hashlib
 import json
 import re
 from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-from playwright.sync_api import BrowserContext
+from typing import Any, Optional
 
 
 @dataclass
@@ -258,39 +255,3 @@ def compute_snapshot_digests(elements: list[dict[str, Any]]) -> dict[str, str]:
         "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/utils/formatting.py

@@ -0,0 +1,59 @@
+"""
+Snapshot formatting utilities for LLM prompts.
+
+Provides functions to convert Sentience snapshots into text format suitable
+for LLM consumption.
+"""
+
+from typing import List
+
+from ..models import Snapshot
+
+
+def format_snapshot_for_llm(snap: Snapshot, limit: int = 50) -> str:
+    """
+    Convert snapshot elements to text format for LLM consumption.
+
+    This is the canonical way Sentience formats DOM state for LLMs.
+    The format includes element ID, role, text preview, visual cues,
+    position, and importance score.
+
+    Args:
+        snap: Snapshot object with elements
+        limit: Maximum number of elements to include (default: 50)
+
+    Returns:
+        Formatted string with one element per line
+
+    Example:
+        >>> snap = snapshot(browser)
+        >>> formatted = format_snapshot_for_llm(snap, limit=10)
+        >>> print(formatted)
+        [1] <button> "Sign In" {PRIMARY,CLICKABLE} @ (100,50) (Imp:10)
+        [2] <input> "Email address" @ (100,100) (Imp:8)
+        ...
+    """
+    lines: list[str] = []
+
+    for el in snap.elements[:limit]:
+        # Build visual cues string
+        cues = []
+        if getattr(el.visual_cues, "is_primary", False):
+            cues.append("PRIMARY")
+        if getattr(el.visual_cues, "is_clickable", False):
+            cues.append("CLICKABLE")
+
+        cues_str = f" {{{','.join(cues)}}}" if cues else ""
+
+        # Format text preview (truncate to 50 chars)
+        text_preview = el.text or ""
+        if len(text_preview) > 50:
+            text_preview = text_preview[:50] + "..."
+
+        # Build element line: [ID] <role> "text" {cues} @ (x,y) (Imp:score)
+        lines.append(
+            f'[{el.id}] <{el.role}> "{text_preview}"{cues_str} '
+            f"@ ({int(el.bbox.x)},{int(el.bbox.y)}) (Imp:{el.importance})"
+        )
+
+    return "\n".join(lines)