Phase 1: completed PyndanticAI

Author: rcholic

examples/pydantic_ai_self_correcting_click.py

@@ -0,0 +1,44 @@
+"""
+Example: PydanticAI + Sentience self-correcting action loop using URL guards.
+
+Run:
+  pip install sentienceapi[pydanticai]
+  python examples/pydantic_ai_self_correcting_click.py
+"""
+
+from __future__ import annotations
+
+from sentience import AsyncSentienceBrowser
+from sentience.integrations.pydanticai import SentiencePydanticDeps, register_sentience_tools
+
+
+async def main() -> None:
+    from pydantic_ai import Agent
+
+    browser = AsyncSentienceBrowser(headless=False)
+    await browser.start()
+    await browser.page.goto("https://example.com")  # replace with a real target
+
+    agent = Agent(
+        "openai:gpt-5",
+        deps_type=SentiencePydanticDeps,
+        output_type=str,
+        instructions=(
+            "Navigate on the site and click the appropriate link/button. "
+            "After clicking, use assert_eventually_url_matches to confirm the URL changed as expected."
+        ),
+    )
+    register_sentience_tools(agent)
+
+    deps = SentiencePydanticDeps(browser=browser)
+    result = await agent.run("Click something that navigates, then confirm URL changed.", deps=deps)
+    print(result.output)
+
+    await browser.close()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())
+

examples/pydantic_ai_typed_extraction.py

@@ -0,0 +1,48 @@
+"""
+Example: PydanticAI + Sentience typed extraction (Phase 1 integration).
+
+Run:
+  pip install sentienceapi[pydanticai]
+  python examples/pydantic_ai_typed_extraction.py
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from sentience import AsyncSentienceBrowser
+from sentience.integrations.pydanticai import SentiencePydanticDeps, register_sentience_tools
+
+
+class ProductInfo(BaseModel):
+    title: str = Field(..., description="Product title")
+    price: str = Field(..., description="Displayed price string")
+
+
+async def main() -> None:
+    from pydantic_ai import Agent
+
+    browser = AsyncSentienceBrowser(headless=False)
+    await browser.start()
+    await browser.page.goto("https://example.com")  # replace with a real target
+
+    agent = Agent(
+        "openai:gpt-5",
+        deps_type=SentiencePydanticDeps,
+        output_type=ProductInfo,
+        instructions="Extract the product title and price from the page.",
+    )
+    register_sentience_tools(agent)
+
+    deps = SentiencePydanticDeps(browser=browser)
+    result = await agent.run("Extract title and price.", deps=deps)
+    print(result.output)
+
+    await browser.close()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())
+

sentience/integrations/__init__.py

@@ -4,4 +4,3 @@
 This package is intended for framework integrations (e.g., PydanticAI, LangChain/LangGraph).
 Public APIs should be introduced deliberately once the integration surface is stable.
 """
-

sentience/integrations/models.py

@@ -44,4 +44,3 @@ class AssertionResult(BaseModel):
     passed: bool
     reason: str = ""
     details: dict[str, Any] = {}
-

sentience/integrations/pydanticai/__init__.py

@@ -0,0 +1,16 @@
+"""
+PydanticAI integration helpers (optional).
+
+This module does NOT import `pydantic_ai` at import time so the base SDK can be
+installed without the optional dependency. Users should install:
+
+    pip install sentienceapi[pydanticai]
+
+and then use `register_sentience_tools(...)` with a PydanticAI `Agent`.
+"""
+
+from .deps import SentiencePydanticDeps
+from .toolset import register_sentience_tools
+
+__all__ = ["SentiencePydanticDeps", "register_sentience_tools"]
+

sentience/integrations/pydanticai/deps.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from sentience.browser import AsyncSentienceBrowser
+
+
+@dataclass
+class SentiencePydanticDeps:
+    """
+    Dependencies passed into PydanticAI tools via ctx.deps.
+
+    At minimum we carry the live `AsyncSentienceBrowser`.
+    """
+
+    browser: AsyncSentienceBrowser
+    runtime: Any | None = None
+    tracer: Any | None = None
+

sentience/integrations/pydanticai/toolset.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from typing import Any, Literal
+
+from sentience.actions import click_async, press_async, type_text_async
+from sentience.integrations.models import AssertionResult, BrowserState, ElementSummary
+from sentience.models import ReadResult, SnapshotOptions, TextRectSearchResult
+from sentience.read import read_async
+from sentience.snapshot import snapshot_async
+from sentience.text_search import find_text_rect_async
+
+from .deps import SentiencePydanticDeps
+
+
+def register_sentience_tools(agent: Any) -> dict[str, Any]:
+    """
+    Register Sentience tools on a PydanticAI agent.
+
+    This function is intentionally lightweight and avoids importing `pydantic_ai`
+    at module import time. It expects `agent` to provide a `.tool` decorator
+    compatible with PydanticAI's `Agent.tool`.
+
+    Returns:
+        Mapping of tool name -> underlying coroutine function (useful for tests).
+    """
+
+    @agent.tool
+    async def snapshot_state(
+        ctx: Any,
+        limit: int = 50,
+        include_screenshot: bool = False,
+    ) -> BrowserState:
+        """
+        Take a bounded snapshot of the current page and return a small typed summary.
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        opts = SnapshotOptions(limit=limit, screenshot=include_screenshot)
+        snap = await snapshot_async(deps.browser, opts)
+        elements = [
+            ElementSummary(
+                id=e.id,
+                role=e.role,
+                text=e.text,
+                importance=e.importance,
+                bbox=e.bbox,
+            )
+            for e in snap.elements
+        ]
+        return BrowserState(url=snap.url, elements=elements)
+
+    @agent.tool
+    async def read_page(
+        ctx: Any,
+        format: Literal["raw", "text", "markdown"] = "text",
+        enhance_markdown: bool = True,
+    ) -> ReadResult:
+        """
+        Read page content as raw HTML, text, or markdown.
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        return await read_async(deps.browser, output_format=format, enhance_markdown=enhance_markdown)
+
+    @agent.tool
+    async def click(
+        ctx: Any,
+        element_id: int,
+    ):
+        """
+        Click an element by Sentience element id (from snapshot).
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        return await click_async(deps.browser, element_id)
+
+    @agent.tool
+    async def type_text(
+        ctx: Any,
+        element_id: int,
+        text: str,
+    ):
+        """
+        Type text into an element by Sentience element id (from snapshot).
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        return await type_text_async(deps.browser, element_id, text)
+
+    @agent.tool
+    async def press_key(
+        ctx: Any,
+        key: str,
+    ):
+        """
+        Press a keyboard key (Enter, Escape, Tab, etc.).
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        return await press_async(deps.browser, key)
+
+    @agent.tool
+    async def find_text_rect(
+        ctx: Any,
+        text: str,
+        case_sensitive: bool = False,
+        whole_word: bool = False,
+        max_results: int = 10,
+    ) -> TextRectSearchResult:
+        """
+        Find text occurrences and return pixel coordinates.
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        return await find_text_rect_async(
+            deps.browser,
+            text,
+            case_sensitive=case_sensitive,
+            whole_word=whole_word,
+            max_results=max_results,
+        )
+
+    @agent.tool
+    async def verify_url_matches(
+        ctx: Any,
+        pattern: str,
+        flags: int = 0,
+    ) -> AssertionResult:
+        """
+        Verify the current page URL matches a regex pattern.
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        if not deps.browser.page:
+            return AssertionResult(passed=False, reason="Browser not started (page is None)")
+
+        url = deps.browser.page.url
+        ok = re.search(pattern, url, flags) is not None
+        return AssertionResult(
+            passed=ok,
+            reason="" if ok else f"URL did not match pattern. url={url!r} pattern={pattern!r}",
+            details={"url": url, "pattern": pattern},
+        )
+
+    @agent.tool
+    async def verify_text_present(
+        ctx: Any,
+        text: str,
+        *,
+        format: Literal["text", "markdown", "raw"] = "text",
+        case_sensitive: bool = False,
+    ) -> AssertionResult:
+        """
+        Verify a text substring is present in `read_page()` output.
+        """
+        deps: SentiencePydanticDeps = ctx.deps
+        result = await read_async(deps.browser, output_format=format, enhance_markdown=True)
+        if result.status != "success":
+            return AssertionResult(passed=False, reason=f"read failed: {result.error}", details={})
+
+        haystack = result.content if case_sensitive else result.content.lower()
+        needle = text if case_sensitive else text.lower()
+        ok = needle in haystack
+        return AssertionResult(
+            passed=ok,
+            reason="" if ok else f"Text not present: {text!r}",
+            details={"format": format, "query": text, "length": result.length},
+        )
+
+    @agent.tool
+    async def assert_eventually_url_matches(
+        ctx: Any,
+        pattern: str,
+        *,
+        timeout_s: float = 10.0,
+        poll_s: float = 0.25,
+        flags: int = 0,
+    ) -> AssertionResult:
+        """
+        Retry until the page URL matches `pattern` or timeout is reached.
+        """
+        deadline = time.monotonic() + timeout_s
+        last = None
+        while time.monotonic() <= deadline:
+            last = await verify_url_matches(ctx, pattern, flags)
+            if last.passed:
+                return last
+            await asyncio.sleep(poll_s)
+        return last or AssertionResult(passed=False, reason="No attempts executed", details={})
+
+    return {
+        "snapshot_state": snapshot_state,
+        "read_page": read_page,
+        "click": click,
+        "type_text": type_text,
+        "press_key": press_key,
+        "find_text_rect": find_text_rect,
+        "verify_url_matches": verify_url_matches,
+        "verify_text_present": verify_text_present,
+        "assert_eventually_url_matches": assert_eventually_url_matches,
+    }
+

tests/unit/conftest.py

@@ -65,4 +65,3 @@ def _sync_playwright():
 # Expose submodules on the top-level module for completeness
 playwright_mod.async_api = async_api_mod
 playwright_mod.sync_api = sync_api_mod
-

tests/unit/test_integration_phase0_contracts.py

@@ -1,9 +1,9 @@
 import pytest
 
+from sentience.models import SnapshotOptions
 from sentience.read import read
 from sentience.snapshot import snapshot
 from sentience.text_search import find_text_rect
-from sentience.models import SnapshotOptions
 
 
 class _FakePage:
@@ -95,7 +95,9 @@ def test_read_passes_requested_format():
     result = read(browser, output_format="text", enhance_markdown=False)  # type: ignore[arg-type]
     assert result.format == "text"
 
-    read_calls = [(expr, arg) for (expr, arg) in page.evaluate_calls if "window.sentience.read" in expr]
+    read_calls = [
+        (expr, arg) for (expr, arg) in page.evaluate_calls if "window.sentience.read" in expr
+    ]
     assert len(read_calls) == 1
     _, options = read_calls[0]
     assert options == {"format": "text"}
@@ -117,4 +119,3 @@ def test_find_text_rect_unavailable_raises(monkeypatch):
         find_text_rect(browser, "Sign In")  # type: ignore[arg-type]
 
     assert "window.sentience.findTextRect is not available" in str(e.value)
-