Phase 4: Modularize code

Author: rcholic

sentience/__init__.py

@@ -16,7 +16,7 @@
 from .expect import expect
 
 # Formatting (v0.12.0+)
-from .formatting import format_snapshot_for_llm
+from .utils.formatting import format_snapshot_for_llm
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
 from .llm_provider import (
@@ -62,6 +62,7 @@
 from .tracing import JsonlTraceSink, TraceEvent, Tracer, TraceSink
 
 # Utilities (v0.12.0+)
+# Import from utils package (re-exports from submodules for backward compatibility)
 from .utils import (
     canonical_snapshot_loose,
     canonical_snapshot_strict,

sentience/element_filter.py

@@ -64,7 +64,7 @@ def filter_by_importance(
     @staticmethod
     def filter_by_goal(
         snapshot: Snapshot,
-        goal: str | None,
+        goal: Optional[str],
         max_elements: int = 50,
     ) -> list[Element]:
         """

sentience/formatting.py

@@ -1,59 +1,15 @@
 """
 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.
+DEPRECATED: This module is maintained for backward compatibility only.
+New code should import from sentience.utils.formatting or sentience directly:
 
-    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] + "..."
+    from sentience.utils.formatting import format_snapshot_for_llm
+    # or
+    from sentience import format_snapshot_for_llm
+"""
 
-        # 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})"
-        )
+# Re-export from new location for backward compatibility
+from .utils.formatting import format_snapshot_for_llm
 
-    return "\n".join(lines)
+__all__ = ["format_snapshot_for_llm"]

sentience/utils/__init__.py

@@ -0,0 +1,41 @@
+"""
+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,47 @@
+"""
+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}")
+