anchorbrowser 0.1.0__py3-none-any.whl

anchorbrowser/lib/browser.py

@@ -0,0 +1,186 @@
+from typing import TYPE_CHECKING, Any, Dict, Callable, Optional, TypedDict
+from contextlib import contextmanager, asynccontextmanager, _GeneratorContextManager, _AsyncGeneratorContextManager
+
+from pydantic import BaseModel
+from playwright.sync_api import Page, Worker, Browser, BrowserContext
+from playwright.async_api import (
+    Page as AsyncPage,
+    Worker as AsyncWorker,
+    Browser as AsyncBrowser,
+    BrowserContext as AsyncBrowserContext,
+)
+
+if TYPE_CHECKING:
+    from collections import Generator, AsyncGenerator
+
+
+@contextmanager
+def get_playwright_chromium_from_cdp_url(
+    api_base_url: str, session_id: str, api_key: str
+) -> "Generator[Browser, Any, None]":
+    from playwright.sync_api import sync_playwright
+
+    browser = None
+    playwright = sync_playwright().start()
+    try:
+        browser = playwright.chromium.connect_over_cdp(get_cdp_url(api_base_url, session_id, api_key))
+        yield browser
+    finally:
+        if browser:
+            browser.close()
+        playwright.stop()
+
+
+@asynccontextmanager
+async def get_async_playwright_chromium_from_cdp_url(
+    api_base_url: str, session_id: str, api_key: str
+) -> "AsyncGenerator[AsyncBrowser, None]":
+    from playwright.async_api import async_playwright
+
+    browser = None
+    playwright = await async_playwright().start()
+    try:
+        browser = await playwright.chromium.connect_over_cdp(get_cdp_url(api_base_url, session_id, api_key))
+        yield browser
+    finally:
+        if browser:
+            await browser.close()
+        await playwright.stop()
+
+
+def get_cdp_url(api_base_url: str, session_id: str, api_key: str) -> str:
+    return f"{api_base_url.replace('https://', 'wss://').replace('api.', 'connect.')}?apiKey={api_key}&sessionId={session_id}"
+
+
+def get_agent_ws_url(api_base_url: str, session_id: str) -> str:
+    return f"{api_base_url.replace('https://', 'wss://')}/ws?sessionId={session_id}"
+
+
+def get_ai_service_worker(browser_context: "BrowserContext") -> Optional["Worker"]:
+    return next(
+        (
+            sw
+            for sw in browser_context.service_workers
+            if "chrome-extension://bppehibnhionalpjigdjdilknbljaeai/background.js" in sw.url
+        ),
+        None,
+    )
+
+
+async def get_ai_service_worker_async(browser_context: "AsyncBrowserContext") -> Optional["AsyncWorker"]:
+    return next(
+        (
+            sw
+            for sw in browser_context.service_workers
+            if "chrome-extension://bppehibnhionalpjigdjdilknbljaeai/background.js" in sw.url
+        ),
+        None,
+    )
+
+
+class BrowserSetup(BaseModel):
+    session_id: str
+    base_url: str
+    api_key: str
+    _browser: Optional[Browser] = None
+    _async_browser: Optional[AsyncBrowser] = None
+    _context_manager: Optional[_GeneratorContextManager[Browser]] = None
+    _async_context_manager: Optional[_AsyncGeneratorContextManager[AsyncBrowser]] = None
+
+    async def __aenter__(self) -> "BrowserSetup":
+        self._async_context_manager = get_async_playwright_chromium_from_cdp_url(
+            self.base_url,
+            self.session_id,
+            self.api_key,
+        )
+        self._async_browser = await self._async_context_manager.__aenter__()
+        return self
+
+    def __enter__(self) -> "BrowserSetup":
+        self._context_manager = get_playwright_chromium_from_cdp_url(
+            self.base_url,
+            self.session_id,
+            self.api_key,
+        )
+        self._browser = self._context_manager.__enter__()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Optional[bool]:
+        if self._context_manager:
+            return self._context_manager.__exit__(exc_type, exc_val, exc_tb)
+        return None
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Optional[bool]:
+        if self._async_context_manager:
+            return await self._async_context_manager.__aexit__(exc_type, exc_val, exc_tb)
+        return None
+
+    @property
+    def browser_generator(self) -> _GeneratorContextManager[Browser]:
+        return get_playwright_chromium_from_cdp_url(
+            self.base_url,
+            self.session_id,
+            self.api_key,
+        )
+
+    @property
+    def async_browser_generator(self) -> _AsyncGeneratorContextManager[AsyncBrowser]:
+        return get_async_playwright_chromium_from_cdp_url(
+            self.base_url,
+            self.session_id,
+            self.api_key,
+        )
+
+    @property
+    def browser(self) -> Browser:
+        if self._browser is None:
+            raise RuntimeError("BrowserSetup must be used as a context manager")
+        return self._browser
+
+    @property
+    async def async_browser(self) -> AsyncBrowser:
+        if self._async_browser is None:
+            raise RuntimeError("BrowserSetup must be used as a context manager")
+        return self._async_browser
+
+    @property
+    def context(self) -> BrowserContext:
+        return self.browser.contexts[0]
+
+    @property
+    async def async_context(self) -> AsyncBrowserContext:
+        return (await self.async_browser).contexts[0]
+
+    @property
+    def page(self) -> Page:
+        return self.context.pages[0]
+
+    @property
+    async def async_page(self) -> AsyncPage:
+        return (await self.async_context).pages[0]
+
+    @property
+    def ai(self) -> Worker:
+        ai_service_worker = get_ai_service_worker(self.context)
+        if not ai_service_worker:
+            raise ValueError("AI service worker not found")
+        return ai_service_worker
+
+    @property
+    async def async_ai(self) -> AsyncWorker:
+        ai_service_worker = await get_ai_service_worker_async(await self.async_context)
+        if not ai_service_worker:
+            raise ValueError("AI service worker not found")
+        return ai_service_worker
+
+
+class AgentTaskParams(TypedDict, total=False):
+    url: Optional[str]
+    output_schema: Optional[Dict[str, Any]]
+    on_agent_step: Optional[Callable[[str], None]]
+
+
+class BrowserTaskResponse(TypedDict):
+    session_id: str
+    task_result_task: Any
+    playwright_browser: Any

anchorbrowser/resources/__init__.py

@@ -0,0 +1,61 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from .tools import (
+    ToolsResource,
+    AsyncToolsResource,
+    ToolsResourceWithRawResponse,
+    AsyncToolsResourceWithRawResponse,
+    ToolsResourceWithStreamingResponse,
+    AsyncToolsResourceWithStreamingResponse,
+)
+from .profiles import (
+    ProfilesResource,
+    AsyncProfilesResource,
+    ProfilesResourceWithRawResponse,
+    AsyncProfilesResourceWithRawResponse,
+    ProfilesResourceWithStreamingResponse,
+    AsyncProfilesResourceWithStreamingResponse,
+)
+from .sessions import (
+    SessionsResource,
+    AsyncSessionsResource,
+    SessionsResourceWithRawResponse,
+    AsyncSessionsResourceWithRawResponse,
+    SessionsResourceWithStreamingResponse,
+    AsyncSessionsResourceWithStreamingResponse,
+)
+from .extensions import (
+    ExtensionsResource,
+    AsyncExtensionsResource,
+    ExtensionsResourceWithRawResponse,
+    AsyncExtensionsResourceWithRawResponse,
+    ExtensionsResourceWithStreamingResponse,
+    AsyncExtensionsResourceWithStreamingResponse,
+)
+
+__all__ = [
+    "ProfilesResource",
+    "AsyncProfilesResource",
+    "ProfilesResourceWithRawResponse",
+    "AsyncProfilesResourceWithRawResponse",
+    "ProfilesResourceWithStreamingResponse",
+    "AsyncProfilesResourceWithStreamingResponse",
+    "SessionsResource",
+    "AsyncSessionsResource",
+    "SessionsResourceWithRawResponse",
+    "AsyncSessionsResourceWithRawResponse",
+    "SessionsResourceWithStreamingResponse",
+    "AsyncSessionsResourceWithStreamingResponse",
+    "ToolsResource",
+    "AsyncToolsResource",
+    "ToolsResourceWithRawResponse",
+    "AsyncToolsResourceWithRawResponse",
+    "ToolsResourceWithStreamingResponse",
+    "AsyncToolsResourceWithStreamingResponse",
+    "ExtensionsResource",
+    "AsyncExtensionsResource",
+    "ExtensionsResourceWithRawResponse",
+    "AsyncExtensionsResourceWithRawResponse",
+    "ExtensionsResourceWithStreamingResponse",
+    "AsyncExtensionsResourceWithStreamingResponse",
+]

anchorbrowser/resources/agent.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .._compat import cached_property
+from .._resource import SyncAPIResource, AsyncAPIResource
+from .._response import (
+    to_raw_response_wrapper,
+    to_streamed_response_wrapper,
+    async_to_raw_response_wrapper,
+    async_to_streamed_response_wrapper,
+)
+from ..lib.agent import on_agent_step_sync, create_task_payload, on_agent_step_async
+from ..lib.browser import (
+    BrowserSetup,
+    AgentTaskParams,
+    BrowserTaskResponse,
+)
+from ..types.session_create_params import Session
+
+__all__ = ["AgentResource", "AsyncAgentResource"]
+
+
+class AgentResource(SyncAPIResource):
+    @cached_property
+    def with_raw_response(self) -> AgentResourceWithRawResponse:
+        """
+        This property can be used as a prefix for any HTTP method call to return
+        the raw response object instead of the parsed content.
+
+        For more information, see https://www.github.com/anchorbrowser/AnchorBrowser-SDK-Python#accessing-raw-response-data-eg-headers
+        """
+        return AgentResourceWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> AgentResourceWithStreamingResponse:
+        """
+        An alternative to `.with_raw_response` that doesn't eagerly read the response body.
+
+        For more information, see https://www.github.com/anchorbrowser/AnchorBrowser-SDK-Python#with_streaming_response
+        """
+        return AgentResourceWithStreamingResponse(self)
+
+    def task(
+        self,
+        prompt: str,
+        *,
+        session_options: Optional[Session] = None,
+        task_options: Optional[AgentTaskParams] = None,
+    ) -> str:
+        """Execute an AI agent task within a browser session.
+
+        Creates a new browser session and executes the given prompt as an AI agent task.
+        The agent can optionally navigate to a specific URL and use a structured output schema.
+
+        Args:
+            prompt (str): The task prompt/instruction for the AI agent to execute.
+            session_options (Optional[Session], optional): Configuration options for the
+                browser session. Defaults to None, which creates a session with default settings.
+            task_options (Optional[AgentTaskParams], optional): Additional task configuration
+
+        Returns:
+            str: The result of the AI agent task execution.
+        """
+        session = self._client.sessions.create(session=session_options or {})
+        if not session.data or not session.data.id:
+            raise ValueError("Failed to create session: No session ID returned")
+
+        with BrowserSetup(
+            session_id=session.data.id,
+            base_url=str(self._client.base_url),
+            api_key=self._client.api_key,
+        ) as browser_setup:
+            output_schema = None
+            if task_options:
+                output_schema = task_options.get("output_schema")
+                url = task_options.get("url")
+                if url:
+                    browser_setup.page.goto(url)
+                on_agent_step = task_options.get("on_agent_step")
+                if on_agent_step:
+                    on_agent_step_sync(on_agent_step, browser_setup)
+            task_payload = create_task_payload(prompt, output_schema)
+            task_result = str(browser_setup.ai.evaluate(task_payload))
+            return task_result
+
+    def browser_task(
+        self,
+        prompt: str,
+        *,
+        session_options: Optional[Session] = None,
+        task_options: Optional[AgentTaskParams] = None,
+    ) -> BrowserTaskResponse:
+        """Execute an AI agent task and return a browser task response with session control.
+
+        Creates a new browser session, executes the given prompt as an AI agent task \n
+        returns a object that includes the session ID, task result, and browser instance for continued interaction by the caller. \n
+        This method differs from `task()` by returning control of the browser session to the caller rather than automatically closing it after task completion. \n
+        Args:
+            prompt (str): The task prompt/instruction for the AI agent to execute. \n
+            session_options (Optional[Session], optional): Configuration options for the browser session. Defaults to None, which creates a session with default settings. \n
+            task_options (Optional[AgentTaskParams], optional): Additional task configuration including: \n
+        - output_schema: Schema for structured output formatting
+        - url: URL to navigate to before executing the task
+        - on_agent_step: Callback function for agent step events
+                Defaults to None.
+
+        Returns:
+            Response object containing:
+                - session_id: The ID of the created browser session
+                - task_result_task: The result of the AI agent task execution
+                - playwright_browser: Browser instance for continued interaction
+        """
+        session = self._client.sessions.create(session=session_options or {})
+        if not session.data or not session.data.id:
+            raise ValueError("Failed to create session: No session ID returned")
+
+        with BrowserSetup(
+            session_id=session.data.id,
+            base_url=str(self._client.base_url),
+            api_key=self._client.api_key,
+        ) as browser_setup:
+            output_schema = None
+            if task_options:
+                output_schema = task_options.get("output_schema")
+                url = task_options.get("url")
+                if url:
+                    browser_setup.page.goto(url)
+                on_agent_step = task_options.get("on_agent_step")
+                if on_agent_step:
+                    on_agent_step_sync(on_agent_step, browser_setup)
+            task_payload = create_task_payload(prompt, output_schema)
+            task_result = str(browser_setup.ai.evaluate(task_payload))
+            return BrowserTaskResponse(
+                session_id=session.data.id,
+                task_result_task=task_result,
+                playwright_browser=browser_setup.browser_generator,
+            )
+
+
+class AsyncAgentResource(AsyncAPIResource):
+    @cached_property
+    def with_raw_response(self) -> AsyncAgentResourceWithRawResponse:
+        """
+        This property can be used as a prefix for any HTTP method call to return
+        the raw response object instead of the parsed content.
+
+        For more information, see https://www.github.com/anchorbrowser/AnchorBrowser-SDK-Python#accessing-raw-response-data-eg-headers
+        """
+        return AsyncAgentResourceWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> AsyncAgentResourceWithStreamingResponse:
+        """
+        An alternative to `.with_raw_response` that doesn't eagerly read the response body.
+
+        For more information, see https://www.github.com/anchorbrowser/AnchorBrowser-SDK-Python#with_streaming_response
+        """
+        return AsyncAgentResourceWithStreamingResponse(self)
+
+    async def task(
+        self,
+        prompt: str,
+        *,
+        session_options: Optional[Session] = None,
+        task_options: Optional[AgentTaskParams] = None,
+    ) -> str:
+        """Execute an AI agent task within a browser session.
+
+        Creates a new browser session and executes the given prompt as an AI agent task.
+        The agent can optionally navigate to a specific URL and use a structured output schema.
+
+        Args:
+            prompt (str): The task prompt/instruction for the AI agent to execute.
+            session_options (Optional[Session], optional): Configuration options for the
+                browser session. Defaults to None, which creates a session with default settings.
+            task_options (Optional[AgentTaskParams], optional): Additional task configuration
+
+        Returns:
+            str: The result of the AI agent task execution.
+        """
+        session = await self._client.sessions.create(session=session_options or {})
+        if not session.data or not session.data.id:
+            raise ValueError("Failed to create session: No session ID returned")
+
+        browser_setup = BrowserSetup(
+            session_id=session.data.id,
+            base_url=str(self._client.base_url),
+            api_key=self._client.api_key,
+        )
+
+        async with browser_setup:
+            output_schema = None
+            if task_options:
+                output_schema = task_options.get("output_schema")
+                url = task_options.get("url")
+                if url:
+                    await (await browser_setup.async_page).goto(url)
+                on_agent_step = task_options.get("on_agent_step")
+                if on_agent_step:
+                    on_agent_step_async(on_agent_step, browser_setup)
+            task_payload = create_task_payload(prompt, output_schema)
+            task_result = await (await browser_setup.async_ai).evaluate(task_payload)
+            return str(task_result)
+
+    async def browser_task(
+        self,
+        prompt: str,
+        *,
+        session_options: Optional[Session] = None,
+        task_options: Optional[AgentTaskParams] = None,
+    ) -> BrowserTaskResponse:
+        """Execute an AI agent task and return a browser task response with session control.
+
+        Creates a new browser session, executes the given prompt as an AI agent task \n
+        returns a object that includes the session ID, task result, and browser instance for continued interaction by the caller. \n
+        This method differs from `task()` by returning control of the browser session to the caller rather than automatically closing it after task completion. \n
+        Args:
+            prompt (str): The task prompt/instruction for the AI agent to execute. \n
+            session_options (Optional[Session], optional): Configuration options for the browser session. Defaults to None, which creates a session with default settings. \n
+            task_options (Optional[AgentTaskParams], optional): Additional task configuration including: \n
+        - output_schema: Schema for structured output formatting
+        - url: URL to navigate to before executing the task
+        - on_agent_step: Callback function for agent step events
+                Defaults to None.
+
+        Returns:
+            Response object containing:
+                - session_id: The ID of the created browser session
+                - task_result_task: The result of the AI agent task execution
+                - playwright_browser: Browser instance for continued interaction
+        """
+        session = await self._client.sessions.create(session=session_options or {})
+        if not session.data or not session.data.id:
+            raise ValueError("Failed to create session: No session ID returned")
+
+        async with BrowserSetup(
+            session_id=session.data.id,
+            base_url=str(self._client.base_url),
+            api_key=self._client.api_key,
+        ) as browser_setup:
+            output_schema = None
+            if task_options:
+                output_schema = task_options.get("output_schema")
+                url = task_options.get("url")
+                if url:
+                    await (await browser_setup.async_page).goto(url)
+                on_agent_step = task_options.get("on_agent_step")
+                if on_agent_step:
+                    on_agent_step_async(on_agent_step, browser_setup)
+            task_payload = create_task_payload(prompt, output_schema)
+            task_result = await (await browser_setup.async_ai).evaluate(task_payload)
+            return BrowserTaskResponse(
+                session_id=session.data.id,
+                task_result_task=task_result,
+                playwright_browser=browser_setup.async_browser_generator,
+            )
+
+
+class AgentResourceWithRawResponse:
+    def __init__(self, agent: AgentResource) -> None:
+        self._agent = agent
+
+        self.task = to_raw_response_wrapper(
+            agent.task,
+        )
+        self.browser_task = to_raw_response_wrapper(
+            agent.browser_task,
+        )
+
+
+class AsyncAgentResourceWithRawResponse:
+    def __init__(self, agent: AsyncAgentResource) -> None:
+        self._agent = agent
+
+        self.task = async_to_raw_response_wrapper(
+            agent.task,
+        )
+        self.browser_task = async_to_raw_response_wrapper(
+            agent.browser_task,
+        )
+
+
+class AgentResourceWithStreamingResponse:
+    def __init__(self, agent: AgentResource) -> None:
+        self._agent = agent
+
+        self.task = to_streamed_response_wrapper(
+            agent.task,
+        )
+        self.browser_task = to_streamed_response_wrapper(
+            agent.browser_task,
+        )
+
+
+class AsyncAgentResourceWithStreamingResponse:
+    def __init__(self, agent: AsyncAgentResource) -> None:
+        self._agent = agent
+
+        self.task = async_to_streamed_response_wrapper(
+            agent.task,
+        )
+        self.browser_task = async_to_streamed_response_wrapper(
+            agent.browser_task,
+        )