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

{sentienceapi-0.92.2.dist-info → sentienceapi-0.98.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sentienceapi
-Version: 0.92.2
+Version: 0.98.0
 Summary: Python SDK for Sentience AI Agent Browser Automation
 Author: Sentience Team
 License: MIT OR Apache-2.0
@@ -26,6 +26,20 @@ Requires-Dist: requests>=2.31.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: playwright-stealth>=1.0.6
 Requires-Dist: markdownify>=0.11.6
+Provides-Extra: browser-use
+Requires-Dist: browser-use>=0.1.40; extra == "browser-use"
+Provides-Extra: pydanticai
+Requires-Dist: pydantic-ai; extra == "pydanticai"
+Provides-Extra: langchain
+Requires-Dist: langchain; extra == "langchain"
+Requires-Dist: langgraph; extra == "langchain"
+Provides-Extra: vision-local
+Requires-Dist: pillow>=10.0.0; extra == "vision-local"
+Requires-Dist: torch>=2.2.0; extra == "vision-local"
+Requires-Dist: transformers>=4.46.0; extra == "vision-local"
+Provides-Extra: mlx-vlm
+Requires-Dist: pillow>=10.0.0; extra == "mlx-vlm"
+Requires-Dist: mlx-vlm>=0.1.0; extra == "mlx-vlm"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -33,7 +47,7 @@ Dynamic: license-file
 
 # Sentience Python SDK
 
-**Semantic geometry grounding for deterministic, debuggable AI web agents with time-travel traces.**
+**Semantic snapshots and Jest-style assertions for reliable AI web agents with time-travel traces**
 
 ## 📦 Installation
 
@@ -55,6 +69,106 @@ pip install transformers torch  # For local LLMs
 pip install -e .
 ```
 
+## Jest for AI Web Agent
+
+### Semantic snapshots and assertions that let agents act, verify, and know when they're done.
+
+Use `AgentRuntime` to add Jest-style assertions to your agent loops. Verify browser state, check task completion, and get clear feedback on what's working:
+
+```python
+import asyncio
+from sentience import AsyncSentienceBrowser, AgentRuntime
+from sentience.verification import (
+    url_contains,
+    exists,
+    all_of,
+    is_enabled,
+    is_checked,
+    value_equals,
+)
+from sentience.tracing import Tracer, JsonlTraceSink
+
+async def main():
+    # Create tracer
+    tracer = Tracer(run_id="my-run", sink=JsonlTraceSink("trace.jsonl"))
+
+    # Create browser and runtime
+    async with AsyncSentienceBrowser() as browser:
+        page = await browser.new_page()
+        runtime = await AgentRuntime.from_sentience_browser(
+            browser=browser,
+            page=page,
+            tracer=tracer
+        )
+
+        # Navigate and take snapshot
+        await page.goto("https://example.com")
+        runtime.begin_step("Verify page loaded")
+        await runtime.snapshot()
+
+        # v1: deterministic assertions (Jest-style)
+        runtime.assert_(url_contains("example.com"), label="on_correct_domain")
+        runtime.assert_(exists("role=heading"), label="has_heading")
+        runtime.assert_(all_of([
+            exists("role=button"),
+            exists("role=link")
+        ]), label="has_interactive_elements")
+
+        # v1: state-aware assertions (when Gateway refinement is enabled)
+        runtime.assert_(is_enabled("role=button"), label="button_enabled")
+        runtime.assert_(is_checked("role=checkbox name~'subscribe'"), label="subscribe_checked_if_present")
+        runtime.assert_(value_equals("role=textbox name~'email'", "user@example.com"), label="email_value_if_present")
+
+        # v2: retry loop with snapshot confidence gating + exhaustion
+        ok = await runtime.check(
+            exists("role=heading"),
+            label="heading_eventually_visible",
+            required=True,
+        ).eventually(timeout_s=10.0, poll_s=0.25, min_confidence=0.7, max_snapshot_attempts=3)
+        print("eventually() result:", ok)
+
+        # Check task completion
+        if runtime.assert_done(exists("text~'Example'"), label="task_complete"):
+            print("✅ Task completed!")
+
+        print(f"Task done: {runtime.is_task_done}")
+
+asyncio.run(main())
+```
+
+### Failure Artifact Buffer (Phase 1)
+
+Capture a short ring buffer of screenshots and persist them when a required assertion fails.
+
+```python
+from sentience.failure_artifacts import FailureArtifactsOptions
+
+await runtime.enable_failure_artifacts(
+    FailureArtifactsOptions(buffer_seconds=15, capture_on_action=True, fps=0.0)
+)
+
+# After each action, record it (best-effort).
+await runtime.record_action("CLICK")
+```
+
+### Redaction callback (Phase 3)
+
+Provide a user-defined callback to redact snapshots and decide whether to persist frames. The SDK does not implement image/video redaction.
+
+```python
+from sentience.failure_artifacts import FailureArtifactsOptions, RedactionContext, RedactionResult
+
+def redact(ctx: RedactionContext) -> RedactionResult:
+    # Example: drop frames entirely, keep JSON only.
+    return RedactionResult(drop_frames=True)
+
+await runtime.enable_failure_artifacts(
+    FailureArtifactsOptions(on_before_persist=redact)
+)
+```
+
+**See examples:** [`examples/asserts/`](examples/asserts/)
+
 ## 🚀 Quick Start: Choose Your Abstraction Level
 
 Sentience SDK offers **three abstraction levels** - use what fits your needs:
@@ -135,56 +249,66 @@ with SentienceBrowser(headless=False) as browser:
 
 ---
 
-<details>
-<summary><h2>💼 Real-World Example: Amazon Shopping Bot</h2></summary>
+## 🆕 What's New (2026-01-06)
+
+### Human-like Typing
+Add realistic delays between keystrokes to mimic human typing:
+```python
+from sentience import type_text
 
-This example demonstrates navigating Amazon, finding products, and adding items to cart:
+# Type instantly (default)
+type_text(browser, element_id, "Hello World")
 
+# Type with human-like delay (~10ms between keystrokes)
+type_text(browser, element_id, "Hello World", delay_ms=10)
+```
+
+### Scroll to Element
+Scroll elements into view with smooth animation:
 ```python
-from sentience import SentienceBrowser, snapshot, find, click
-import time
+from sentience import snapshot, find, scroll_to
 
-with SentienceBrowser(headless=False) as browser:
-    # Navigate to Amazon Best Sellers
-    browser.goto("https://www.amazon.com/gp/bestsellers/", wait_until="domcontentloaded")
-    time.sleep(2)  # Wait for dynamic content
+snap = snapshot(browser)
+button = find(snap, 'role=button text~"Submit"')
 
-    # Take snapshot and find products
-    snap = snapshot(browser)
-    print(f"Found {len(snap.elements)} elements")
+# Scroll element into view with smooth animation
+scroll_to(browser, button.id)
 
-    # Find first product in viewport using spatial filtering
-    products = [
-        el for el in snap.elements
-        if el.role == "link"
-        and el.visual_cues.is_clickable
-        and el.in_viewport
-        and not el.is_occluded
-        and el.bbox.y < 600  # First row
-    ]
+# Scroll instantly to top of viewport
+scroll_to(browser, button.id, behavior='instant', block='start')
+```
 
-    if products:
-        # Sort by position (left to right, top to bottom)
-        products.sort(key=lambda e: (e.bbox.y, e.bbox.x))
-        first_product = products[0]
+---
 
-        print(f"Clicking: {first_product.text}")
-        result = click(browser, first_product.id)
+<details>
+<summary><h2>💼 Real-World Example: Assertion-driven navigation</h2></summary>
 
-        # Wait for product page
-        browser.page.wait_for_load_state("networkidle")
-        time.sleep(2)
+This example shows how to use **assertions + `.eventually()`** to make an agent loop resilient:
 
-        # Find and click "Add to Cart" button
-        product_snap = snapshot(browser)
-        add_to_cart = find(product_snap, "role=button text~'add to cart'")
+```python
+import asyncio
+import os
+from sentience import AsyncSentienceBrowser, AgentRuntime
+from sentience.tracing import Tracer, JsonlTraceSink
+from sentience.verification import url_contains, exists
 
-        if add_to_cart:
-            cart_result = click(browser, add_to_cart.id)
-            print(f"Added to cart: {cart_result.success}")
-```
+async def main():
+    tracer = Tracer(run_id="verified-run", sink=JsonlTraceSink("trace_verified.jsonl"))
+    async with AsyncSentienceBrowser(headless=True) as browser:
+        page = await browser.new_page()
+        runtime = await AgentRuntime.from_sentience_browser(browser=browser, page=page, tracer=tracer)
+        runtime.sentience_api_key = os.getenv("SENTIENCE_API_KEY")  # optional, enables Gateway diagnostics
+
+        await page.goto("https://example.com")
+        runtime.begin_step("Verify we're on the right page")
 
-**📖 See the complete tutorial:** [Amazon Shopping Guide](../docs/AMAZON_SHOPPING_GUIDE.md)
+        await runtime.check(url_contains("example.com"), label="on_domain", required=True).eventually(
+            timeout_s=10.0, poll_s=0.25, min_confidence=0.7, max_snapshot_attempts=3
+        )
+        runtime.assert_(exists("role=heading"), label="heading_present")
+
+asyncio.run(main())
+```
 
 </details>
 
@@ -832,6 +956,40 @@ with browser:
 
 </details>
 
+<details>
+<summary><h3>🔍 Agent Runtime Verification</h3></summary>
+
+`AgentRuntime` provides assertion predicates for runtime verification in agent loops, enabling programmatic verification of browser state during execution.
+
+```python
+from sentience import (
+    AgentRuntime, SentienceBrowser,
+    url_contains, exists, all_of
+)
+from sentience.tracer_factory import create_tracer
+
+browser = SentienceBrowser()
+browser.start()
+tracer = create_tracer(run_id="my-run", upload_trace=False)
+runtime = AgentRuntime(browser, browser.page, tracer)
+
+# Navigate and take snapshot
+browser.page.goto("https://example.com")
+runtime.begin_step("Verify page")
+runtime.snapshot()
+
+# Run assertions
+runtime.assert_(url_contains("example.com"), "on_correct_domain")
+runtime.assert_(exists("role=heading"), "has_heading")
+runtime.assert_done(exists("text~'Example'"), "task_complete")
+
+print(f"Task done: {runtime.is_task_done}")
+```
+
+**See example:** [`examples/agent_runtime_verification.py`](examples/agent_runtime_verification.py)
+
+</details>
+
 <details>
 <summary><h3>🧰 Snapshot Utilities</h3></summary>
 

sentienceapi-0.98.0.dist-info/RECORD

@@ -0,0 +1,92 @@
+sentience/__init__.py,sha256=ZzolJfPqb2vnvBwrv7G7MgYJqrB8RuQ1VZsYCK4mgGY,6607
+sentience/_extension_loader.py,sha256=z99Kvwh0bbFEbH04-LJ52t6kIpK9_hh1HG_QBdRg7e4,6118
+sentience/action_executor.py,sha256=8ESWrFPvRDs5pp7Yvih7wkb_-8aY3kL0Ssr0KHRp-ZE,8226
+sentience/actions.py,sha256=UUpmCKxws9tU_ppgITu4-nqUI0piFEkqGV9s_afrf-A,38382
+sentience/agent.py,sha256=xcZ6gRucZRN0La3v5Y6jJRH2js8tgKx4qdwjcgfYVxs,49158
+sentience/agent_config.py,sha256=n6HohW5j4VK3kT23xW7x2Vfz7HvEheb9g4AZ3VWfPpg,1588
+sentience/agent_runtime.py,sha256=ak5CU6X-ig_mvwyt6lNV10XMh7lizlz0qeC97_xJ3Y8,30535
+sentience/async_api.py,sha256=Wh2fE8SQ_9wpCPUyqpMubPbmuzzf83H_ncw21QUnTS8,4077
+sentience/base_agent.py,sha256=5yVXe0S72I7GV4NPYySTvHfUAFvHBD4VjsNKSTo8MFo,5786
+sentience/browser.py,sha256=B6UprJYyIcK4UFdxF8b8BhKwcuivgpwujcqgLK0qDBk,52937
+sentience/browser_evaluator.py,sha256=CRiMsutM68dZWHnMIrFzpVzrkUwxVsXpjBplSIWCkso,9772
+sentience/canonicalization.py,sha256=C7pkxaSgnCI0j_8oZ66yTQu6DGBCTM233IavjhSZgjA,6416
+sentience/cli.py,sha256=R95DgCSJmezuymAdfL6fzUdB1HpCF3iMWcLO73KJ8eY,3851
+sentience/cloud_tracing.py,sha256=ghhgDh9gqF1igEtmlAIFkRsSM7iVQanNhmOsJYhnDCk,32542
+sentience/constants.py,sha256=sGiG_-gnchIW0maA0K9cVaq1-TAkwV4GyEW3kZ_6bhE,110
+sentience/conversational_agent.py,sha256=v3FXczfNZdizQA7ejfgEbhGq_zaOboGb3__UaW7Alpo,18551
+sentience/cursor_policy.py,sha256=36RsH387Y0EMj70_hMNLS6NdVbes6FEIcyB4hWtsypk,4137
+sentience/element_filter.py,sha256=aVFrbTDkH-gtMZt07QfBZH3Oq8_KzwQMz17PD1uQ1h0,4021
+sentience/expect.py,sha256=JIhHJ_UGiPvKWbX5SOmX1irOZlko5N5hhhX6d2Ymem0,6177
+sentience/failure_artifacts.py,sha256=aMbAAZt06MJtCwxJSUw8U9REhUSWXR_j1OcVtzcg66g,7938
+sentience/formatting.py,sha256=rptVpktftZZa5YJu4H2-K5dL8pzdIaPO9ONlEGSWnQw,483
+sentience/generator.py,sha256=Wj--yn6bVo02nABBzrAIKPMmU8TRQm3JHAOER9XXT4Y,8035
+sentience/inspector.py,sha256=D4q_GqXUCV3nUJv8uDv2novDbgnkboHOc9ahGeSYw9Q,14562
+sentience/llm_interaction_handler.py,sha256=elvNtmGwIvoRcdra_fvijSONWzhztgdDmuPFJF2Whkw,7218
+sentience/llm_provider.py,sha256=NZjJOPgbIhTSEzVceCA45-ZTleNzt3R4wTwH3_5_xyA,45685
+sentience/llm_provider_utils.py,sha256=Hkr30MzZ5AvROJxEZHW97FINklzU9xoV8lITUQRoFls,3854
+sentience/llm_response_builder.py,sha256=9lKJcfvD2EY7XcJtTYWTLYkxMVv_6nvlKTcGCO1nB2Q,4935
+sentience/models.py,sha256=Je9Hk_9AOo1L0gFNFgIMT_a4DjxQqST1XPqt4raqq1c,38358
+sentience/ordinal.py,sha256=E6XKLiGPhwavsWOghWwsG00JxOupF5bJnwJ9ctF3rP0,9048
+sentience/overlay.py,sha256=awphkU0ZvkQrxSwQz7S8rvc3gQIqrDhztcQzzjEnR2c,7738
+sentience/protocols.py,sha256=jXAa-RTxdIlMgISxTlIC8P79JqoD4i5T-cjbtgLjuUk,5667
+sentience/query.py,sha256=Dx_OU8gm1BS-Vl9Ks3StLeuGCuZe99D_abzo8kVkNGU,12869
+sentience/read.py,sha256=W0VSh9aBaIOMfUBcmjFubN1Ax1TmpCF1E74SLensy-g,7109
+sentience/recorder.py,sha256=6cJVmjTT7HpRaet6KvdpTFAPVwFmD30eXHtbAKdwoUw,20636
+sentience/screenshot.py,sha256=BJTPsIeE8irP1bhj4Vti2ohsZn5RkkGFTaZJOB855Pk,3147
+sentience/sentience_methods.py,sha256=NmWmf_xfDt8t6RJs5Gf317EDBDrLcOUmHjDhrGpr4ws,2552
+sentience/snapshot.py,sha256=1awUnAmxumo7us_-lYGkHHJh3aqqNzyGTlGPVIcJ6kU,29593
+sentience/snapshot_diff.py,sha256=eh0PAl4PGsfAK8H0JopyQ-WwtPpV24BYV5t_sBqBs18,4716
+sentience/text_search.py,sha256=MIKNn9PG-P4-L_0SzBB5F6O9KM9dzEKB4vRa4wPqoBw,10597
+sentience/trace_event_builder.py,sha256=oj8Wb7mbWwoKRwzRivyVWiBXjy3G2SRMiYX0EaNUmBg,5025
+sentience/trace_file_manager.py,sha256=JxvCx-Hzfyy0wP0DHo9JPnrmFNGtLvdCrPfk0mGiqmE,6311
+sentience/tracer_factory.py,sha256=89gkYF5dTFw44_Db_FKm4vcrSaYhwzhr1jRk13MdnWc,12873
+sentience/tracing.py,sha256=48J-vmtfhXjrJ4UB3i_oHbBmcKs5UsJ8ixfK3MrMt_Q,13885
+sentience/verification.py,sha256=MADOKXSj4MjAmpD8DF6VUyW9UBBv-R2GJF9M-B8s8JM,18571
+sentience/visual_agent.py,sha256=jdBC2YAckJWM2gE2bCW_6-3GXHsmY-CF7sryqyWuWgc,83054
+sentience/wait.py,sha256=sx-87AN1TO_f8UbNP9np8zA0t27zQzQg2c2TltOn2h0,4373
+sentience/asserts/__init__.py,sha256=73TN2aAGrgOkz_wakG4hcd9Cy69MF_3fRWiSFvFh-0o,1898
+sentience/asserts/expect.py,sha256=IXf9yUSVDVFhSwfDGZqKb0raRyvBRkL4PtiWVI27lf4,20831
+sentience/asserts/query.py,sha256=DPnHxEcY8-PenSqd-9J_Kmert3j5ri8xIqYigCwAlvM,11752
+sentience/backends/__init__.py,sha256=HMEqcdp3mYfXYJwO4am4ndlCiRYIVCXcWOJR-OvU2Ic,4040
+sentience/backends/actions.py,sha256=HTJy3xqSH6aZgSMVED5cW5hkCdiNNs_01fp1qo8Jawg,11637
+sentience/backends/browser_use_adapter.py,sha256=bFb1PkPoZws4Ykq08a_ChK2Ms-Xobg94xCmEUmeGJDc,8066
+sentience/backends/cdp_backend.py,sha256=sZJuOpSEhKTfGftbHMglja6AhuXUYlv_-eZS4pi9OY8,12674
+sentience/backends/exceptions.py,sha256=vbvVn62HflMLPOc3YT8SngmjxPTLNL4VoE0eBLDO9cw,6687
+sentience/backends/playwright_backend.py,sha256=XWBxFDGhIWJ6StzKdWNAxDP5aqTW7dzo74JN_qUfUOQ,6707
+sentience/backends/protocol.py,sha256=sL11XDFUnxB-87RdWpN2266Z4WYxv74m1DH-Vsen3-k,5599
+sentience/backends/sentience_context.py,sha256=0fAEpuK-YvD_tlqI0as-sIOXOoIoqFFY14rS1vTAT_w,16689
+sentience/backends/snapshot.py,sha256=YAxaYH3dwaikrMswbhWGsncnBdWUV7lRY2n-oPCfKJo,15476
+sentience/extension/background.js,sha256=Om-Wsu-DP0gjKILWjysW7le_BOCKm5YugUuuTMuic14,3754
+sentience/extension/content.js,sha256=zdVveMeX_2bMupuzehSeAR5xtFzhMRC78hUn0O1oXmA,11249
+sentience/extension/injected_api.js,sha256=pb6CGee5e1r9-DwEMWLsugSH7FpGOL-fxwV1nYpTY-w,66861
+sentience/extension/manifest.json,sha256=FFaImjuIKdON9238WF5YypoPLJn_iWD6BaAt5dRIdvo,897
+sentience/extension/release.json,sha256=w7c7qnB9HfqCgCoONOXkeiw1wSVVOpU484VPKczrQdc,6141
+sentience/extension/pkg/sentience_core.d.ts,sha256=E_rJXQknWuU_8m5Nmt7buXy2J20bvMjBzIir31NBi8U,2011
+sentience/extension/pkg/sentience_core.js,sha256=cUkeYs5FwGkFQ6l5zVWeEdSecFcSd4lAc-JC79DK13U,14623
+sentience/extension/pkg/sentience_core_bg.wasm,sha256=drEsNRJ_s1OlU5CfJV6t_6fIHQggVQ2tl_9iPXmiVM4,112142
+sentience/extension/pkg/sentience_core_bg.wasm.d.ts,sha256=O3c3HaUqmB6Aob6Pt0n3GEtTxM4VGeaClaA_-z2m2J4,517
+sentience/integrations/__init__.py,sha256=TbJiIGTqpv9Bq9Kmq1img5aMlpEbfXPNnWxm5AK5H0w,221
+sentience/integrations/models.py,sha256=TAcZhyvyisUcsTIihWPV1KCG2ylN2TuiwUKbvbkXDYk,1112
+sentience/integrations/langchain/__init__.py,sha256=_8_fkan9_GXo-OLBUOFyUeISvtpza1w385sNQ8gK9zI,460
+sentience/integrations/langchain/context.py,sha256=5iMQmANttMvnI8uuuEgUgfAPGqvgse0bYov4nvr8X-0,418
+sentience/integrations/langchain/core.py,sha256=pFGJQqXkPOciC_CKymLGw0_E4_gmyPeu1tVXALbi8gw,11258
+sentience/integrations/langchain/tools.py,sha256=kZ48jVl_VxSjUVVH7a9RYV2VvZu8ti72fi6NQ6zoYS4,7758
+sentience/integrations/pydanticai/__init__.py,sha256=qeSnhoyAnyYQUC8ERk0FiAijPXHzf76Zpc5i5Zm64KU,464
+sentience/integrations/pydanticai/deps.py,sha256=6uwsc1a2xVjMPV4grsymxLfgVmN25rDoQz4GhO7lFcw,460
+sentience/integrations/pydanticai/toolset.py,sha256=J6uHHikFy5J2qjzh4BzlWL-MUVr_JBt4jb6CRhrxr0E,15378
+sentience/schemas/trace_v1.json,sha256=qhMtb8PcuUwFSmuetkvKFcVOc7fcUpNvun372O6f12E,13487
+sentience/trace_indexing/__init__.py,sha256=urjLuqqXCQE8pnwpYBqoMKnzZSqFJkM1SHmFve9RVE8,499
+sentience/trace_indexing/index_schema.py,sha256=4ovMC_4t55DUkclq8NnBEEnKUZGfIieSkwMU_aBExKA,6262
+sentience/trace_indexing/indexer.py,sha256=zQi8kDHisp5Pb6x42D7odM0Bu5fEL2LPpb74oHwyck4,13974
+sentience/utils/__init__.py,sha256=h8vjeonoe9LF6TeeoJuJ9g6BdsCUP24lhmME7T9jhok,1125
+sentience/utils/browser.py,sha256=pcDlAMgvmkjG13lNXe_LXiHmQs2QRQQBliTZiP7f1wA,1313
+sentience/utils/element.py,sha256=S8AL9T-wqrbSJvJE-qr_Qv2FVk_gRiy6nx30hdRXy4E,6962
+sentience/utils/formatting.py,sha256=IQ-3kLZu1k5ae4rlQ_AxnIkVPeLR9aa8J2NE-dj_eos,1829
+sentienceapi-0.98.0.dist-info/licenses/LICENSE,sha256=jePeclQKwKdmz3jc0Oec6-jQuzwxIcGWPhMfxVII34Q,924
+sentienceapi-0.98.0.dist-info/licenses/LICENSE-APACHE,sha256=YIflUygmGOc0hS_1f6EacrQUrH73G3j8VBQbDoqmY6A,11352
+sentienceapi-0.98.0.dist-info/licenses/LICENSE-MIT,sha256=KiWwku3f8ikn6c8a6t0IdelVEu5GBLLr4tUKdGNNgJ8,1082
+sentienceapi-0.98.0.dist-info/METADATA,sha256=HvsKbnvDI-aTxsD0rfW3od7AFH9Hv3vS3u1-tOS0VDg,32680
+sentienceapi-0.98.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sentienceapi-0.98.0.dist-info/entry_points.txt,sha256=HdW1BvgRJm3ZAbbqrwTvDWE2KbmVz-Ue0wllW-mLmvA,49
+sentienceapi-0.98.0.dist-info/top_level.txt,sha256=A9IKao--8PsFFz5vDfBIXWHgN6oh3HkMQSiQWgUTUBQ,10
+sentienceapi-0.98.0.dist-info/RECORD,,

sentience/utils.py

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