narada 0.1.31__tar.gz → 0.1.33a1__tar.gz

{narada-0.1.31 → narada-0.1.33a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: narada
-Version: 0.1.31
+Version: 0.1.33a1
 Summary: Python client SDK for Narada
 Project-URL: Homepage, https://github.com/NaradaAI/narada-python-sdk/narada
 Project-URL: Repository, https://github.com/NaradaAI/narada-python-sdk
@@ -9,7 +9,7 @@ Author-email: Narada <support@narada.ai>
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.12.13
-Requires-Dist: narada-core==0.0.9
+Requires-Dist: narada-core==0.0.10
 Requires-Dist: playwright>=1.53.0
 Requires-Dist: rich>=14.0.0
 Requires-Dist: semver>=3.0.4

{narada-0.1.31 → narada-0.1.33a1}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "narada"
-version = "0.1.31"
+version = "0.1.33a1"
 description = "Python client SDK for Narada"
 license = "Apache-2.0"
 readme = "README.md"
 authors = [{ name = "Narada", email = "support@narada.ai" }]
 requires-python = ">=3.12"
 dependencies = [
-    "narada-core==0.0.9",
+    "narada-core==0.0.10",
     "aiohttp>=3.12.13",
     "playwright>=1.53.0",
     "rich>=14.0.0",

{narada-0.1.31 → narada-0.1.33a1}/src/narada/__init__.py

@@ -1,3 +1,8 @@
+from narada.client import Narada
+from narada.config import BrowserConfig, ProxyConfig
+from narada.utils import download_file, render_html
+from narada.version import __version__
+from narada.window import CloudBrowserWindow, LocalBrowserWindow, RemoteBrowserWindow
 from narada_core.errors import (
     NaradaError,
     NaradaExtensionMissingError,
@@ -8,16 +13,11 @@ from narada_core.errors import (
 )
 from narada_core.models import Agent, File, Response, ResponseContent
 
-from narada.client import Narada
-from narada.config import BrowserConfig, ProxyConfig
-from narada.utils import download_file, render_html
-from narada.version import __version__
-from narada.window import LocalBrowserWindow, RemoteBrowserWindow
-
 __all__ = [
     "__version__",
     "Agent",
     "BrowserConfig",
+    "CloudBrowserWindow",
     "download_file",
     "File",
     "LocalBrowserWindow",

{narada-0.1.31 → narada-0.1.33a1}/src/narada/client.py

@@ -11,6 +11,14 @@ from uuid import uuid4
 
 import aiohttp
 import semver
+from narada.config import BrowserConfig, ProxyConfig
+from narada.utils import assert_never
+from narada.version import __version__
+from narada.window import (
+    LocalBrowserWindow,
+    CloudBrowserWindow,
+    create_side_panel_url,
+)
 from narada_core.errors import (
     NaradaExtensionMissingError,
     NaradaExtensionUnauthenticatedError,
@@ -26,19 +34,14 @@ from playwright.async_api import (
     ElementHandle,
     Page,
     Playwright,
-    async_playwright,
 )
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
 from playwright.async_api import (
-    TimeoutError as PlaywrightTimeoutError,
+    async_playwright,
 )
 from playwright.async_api._context_manager import PlaywrightContextManager
 from rich.console import Console
 
-from narada.config import BrowserConfig, ProxyConfig
-from narada.utils import assert_never
-from narada.version import __version__
-from narada.window import LocalBrowserWindow, create_side_panel_url
-
 
 @dataclass
 class _LaunchBrowserResult:
@@ -58,10 +61,12 @@ class Narada:
     _console: Console
     _playwright_context_manager: PlaywrightContextManager | None = None
     _playwright: Playwright | None = None
+    _cloud_windows: set[CloudBrowserWindow]
 
     def __init__(self, *, api_key: str | None = None) -> None:
         self._api_key = api_key or os.environ["NARADA_API_KEY"]
         self._console = Console()
+        self._cloud_windows = set()
 
     async def __aenter__(self) -> Narada:
         await self._validate_sdk_config()
@@ -71,6 +76,11 @@ class Narada:
         return self
 
     async def __aexit__(self, *args: Any) -> None:
+        async with asyncio.TaskGroup() as tg:
+            for cloud_window in self._cloud_windows:
+                tg.create_task(cloud_window.cleanup())
+        self._cloud_windows.clear()
+
         if self._playwright_context_manager is None:
             return
 
@@ -134,6 +144,121 @@ class Narada:
             context=side_panel_page.context,
         )
 
+    async def open_and_initialize_cloud_browser_window(
+        self,
+        config: BrowserConfig | None = None,
+        session_name: str | None = None,
+        session_timeout: int | None = None,
+    ) -> CloudBrowserWindow:
+        """Creates a cloud browser by calling the backend.
+
+        The backend creates a cloud browser session and returns
+        a CDP WebSocket URL. This method connects to it, initializes the extension,
+        and returns a CloudBrowserWindow instance.
+        """
+        assert self._playwright is not None
+        playwright = self._playwright
+
+        config = config or BrowserConfig()
+        base_url = os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2")
+        request_body = {
+            "session_name": session_name,
+            "session_timeout": session_timeout,
+        }
+        endpoint_url = f"{base_url}/cloud-browser/create-cloud-browser-session"
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                endpoint_url,
+                headers={"x-api-key": self._api_key},
+                json=request_body,
+                timeout=aiohttp.ClientTimeout(
+                    total=180
+                ),  # 3 minutes for session startup
+            ) as resp:
+                if not resp.ok:
+                    error_text = await resp.text()
+                    raise RuntimeError(
+                        f"Failed to create cloud browser session: {resp.status} {error_text}\n"
+                        f"Endpoint URL: {endpoint_url}"
+                    )
+                response_data = await resp.json()
+
+        cdp_websocket_url = response_data["cdp_websocket_url"]
+        session_id = response_data["session_id"]
+        login_url = response_data["login_url"]
+        cdp_auth_headers = response_data.get("cdp_auth_headers")
+
+        # Connect to browser via CDP with authentication headers
+        try:
+            browser = await playwright.chromium.connect_over_cdp(
+                cdp_websocket_url, headers=cdp_auth_headers
+            )
+        except Exception:
+            # Clean up the session if CDP connection fails
+            try:
+                async with aiohttp.ClientSession() as cleanup_session:
+                    async with cleanup_session.post(
+                        f"{base_url}/cloud-browser/stop-cloud-browser-session",
+                        headers={"x-api-key": self._api_key},
+                        json={"session_id": session_id},
+                        timeout=aiohttp.ClientTimeout(total=10),
+                    ) as resp:
+                        if resp.ok:
+                            logging.info(
+                                f"Cleaned up session {session_id} after CDP connection failure"
+                            )
+                        else:
+                            logging.warning(
+                                f"Failed to cleanup session {session_id}: {resp.status}"
+                            )
+            except Exception as cleanup_error:
+                logging.warning(
+                    f"Error cleaning up session {session_id}: {cleanup_error}"
+                )
+            # Re-raise the original connection error
+            raise
+        context = (
+            browser.contexts[0] if browser.contexts else await browser.new_context()
+        )
+
+        # Navigate to login URL (provided by backend with custom token)
+        initialization_page = await context.new_page()
+        await initialization_page.goto(
+            login_url, wait_until="domcontentloaded", timeout=60_000
+        )
+
+        # Wait for sign-in to process to complete.
+        await asyncio.sleep(15)  # TODO: improve it in the future
+        await initialization_page.reload(wait_until="domcontentloaded", timeout=60_000)
+
+        # Wait for browser window ID
+        browser_window_id = await self._wait_for_browser_window_id(
+            initialization_page, config
+        )
+
+        # TODO: consider this
+        # Get side panel page
+        # side_panel_url = create_side_panel_url(config, browser_window_id)
+        # side_panel_page = next(
+        #     (p for p in context.pages if p.url == side_panel_url), None
+        # )
+        # await self._fix_download_behavior(side_panel_page)
+
+        cloud_window = CloudBrowserWindow(
+            browser_window_id=browser_window_id,
+            session_id=session_id,
+            api_key=self._api_key,
+        )
+
+        # Track the window for cleanup in __aexit__
+        self._cloud_windows.add(cloud_window)
+
+        if config.interactive:
+            self._print_success_message(browser_window_id)
+
+        return cloud_window
+
     async def initialize_in_existing_browser_window(
         self, config: BrowserConfig | None = None
     ) -> LocalBrowserWindow:

{narada-0.1.31 → narada-0.1.33a1}/src/narada/window.py

@@ -1,37 +1,39 @@
 import asyncio
+import logging
 import os
 import time
 from abc import ABC
 from http import HTTPStatus
 from pathlib import Path
-from typing import IO, Any, Optional, TypeVar, overload
+from typing import IO, Any, TypeVar, overload
 
 import aiohttp
+from narada.config import BrowserConfig
 from narada_core.actions.models import (
-    ActionTraceItem,
+    AgenticMouseAction,
+    AgenticMouseActionRequest,
     AgenticSelectorAction,
     AgenticSelectorRequest,
     AgenticSelectorResponse,
-    AgenticMouseActionRequest,
-    AgenticMouseAction,
     AgenticSelectors,
     AgentResponse,
     AgentUsage,
     CloseWindowRequest,
     ExtensionActionRequest,
     ExtensionActionResponse,
+    GetFullHtmlRequest,
+    GetFullHtmlResponse,
+    GetScreenshotRequest,
+    GetScreenshotResponse,
+    GetSimplifiedHtmlRequest,
+    GetSimplifiedHtmlResponse,
     GoToUrlRequest,
     PrintMessageRequest,
     ReadGoogleSheetRequest,
     ReadGoogleSheetResponse,
-    WriteGoogleSheetRequest,
     RecordedClick,
-    GetFullHtmlRequest,
-    GetFullHtmlResponse,
-    GetSimplifiedHtmlRequest,
-    GetSimplifiedHtmlResponse,
-    GetScreenshotRequest,
-    GetScreenshotResponse,
+    WriteGoogleSheetRequest,
+    parse_action_trace,
 )
 from narada_core.errors import (
     NaradaAgentTimeoutError_INTERNAL_DO_NOT_USE,
@@ -41,14 +43,17 @@ from narada_core.errors import (
 from narada_core.models import (
     Agent,
     File,
+    McpServer,
     RemoteDispatchChatHistoryItem,
     Response,
     UserResourceCredentials,
 )
-from playwright.async_api import BrowserContext
+from playwright.async_api import (
+    BrowserContext,
+)
 from pydantic import BaseModel
 
-from narada.config import BrowserConfig
+logger = logging.getLogger(__name__)
 
 _StructuredOutput = TypeVar("_StructuredOutput", bound=BaseModel)
 
@@ -129,6 +134,7 @@ class BaseBrowserWindow(ABC):
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
         user_resource_credentials: UserResourceCredentials | None = None,
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
@@ -151,6 +157,7 @@ class BaseBrowserWindow(ABC):
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
         user_resource_credentials: UserResourceCredentials | None = None,
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
@@ -172,6 +179,7 @@ class BaseBrowserWindow(ABC):
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
         user_resource_credentials: UserResourceCredentials | None = None,
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         callback_url: str | None = None,
         callback_secret: str | None = None,
@@ -213,6 +221,10 @@ class BaseBrowserWindow(ABC):
             body["attachment"] = attachment
         if user_resource_credentials is not None:
             body["userResourceCredentials"] = user_resource_credentials
+        if mcp_servers is not None:
+            body["mcpServers"] = [
+                server.model_dump(mode="json") for server in mcp_servers
+            ]
         if variables is not None:
             body["variables"] = variables
         if callback_url is not None:
@@ -278,6 +290,7 @@ class BaseBrowserWindow(ABC):
         output_schema: None = None,
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         timeout: int = 1000,
     ) -> AgentResponse[None]: ...
@@ -293,6 +306,7 @@ class BaseBrowserWindow(ABC):
         output_schema: type[_StructuredOutput],
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         timeout: int = 1000,
     ) -> AgentResponse[_StructuredOutput]: ...
@@ -307,6 +321,7 @@ class BaseBrowserWindow(ABC):
         output_schema: type[BaseModel] | None = None,
         attachment: File | None = None,
         time_zone: str = "America/Los_Angeles",
+        mcp_servers: list[McpServer] | None = None,
         variables: dict[str, str] | None = None,
         timeout: int = 1000,
     ) -> AgentResponse:
@@ -319,6 +334,7 @@ class BaseBrowserWindow(ABC):
             output_schema=output_schema,
             attachment=attachment,
             time_zone=time_zone,
+            mcp_servers=mcp_servers,
             variables=variables,
             timeout=timeout,
         )
@@ -327,7 +343,7 @@ class BaseBrowserWindow(ABC):
 
         action_trace_raw = response_content.get("actionTrace")
         action_trace = (
-            [ActionTraceItem.model_validate(item) for item in action_trace_raw]
+            parse_action_trace(action_trace_raw)
             if action_trace_raw is not None
             else None
         )
@@ -362,14 +378,13 @@ class BaseBrowserWindow(ABC):
             AgenticSelectorRequest(
                 action=action,
                 selectors=selectors,
-                response_model=response_model,
                 fallback_operator_query=fallback_operator_query,
             ),
             timeout=timeout,
         )
 
         if result is None:
-            return {"value": None}
+            return AgenticSelectorResponse(value=None)
 
         return result
 
@@ -542,9 +557,10 @@ class LocalBrowserWindow(BaseBrowserWindow):
         config: BrowserConfig,
         context: BrowserContext,
     ) -> None:
+        base_url = os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2")
         super().__init__(
             api_key=api_key,
-            base_url=os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2"),
+            base_url=base_url,
             browser_window_id=browser_window_id,
         )
         self._browser_process_id = browser_process_id
@@ -576,9 +592,10 @@ class LocalBrowserWindow(BaseBrowserWindow):
 
 class RemoteBrowserWindow(BaseBrowserWindow):
     def __init__(self, *, browser_window_id: str, api_key: str | None = None) -> None:
+        base_url = os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2")
         super().__init__(
             api_key=api_key or os.environ["NARADA_API_KEY"],
-            base_url=os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2"),
+            base_url=base_url,
             browser_window_id=browser_window_id,
         )
 
@@ -586,5 +603,51 @@ class RemoteBrowserWindow(BaseBrowserWindow):
         return f"RemoteBrowserWindow(browser_window_id={self.browser_window_id})"
 
 
+class CloudBrowserWindow(BaseBrowserWindow):
+    """A browser window that connects to a backend-cloud browser session via CDP.
+
+    This class connects to a cloud browser session created by the backend API and provides
+    the same interface as other browser window classes for agent operations.
+    """
+
+    def __init__(
+        self,
+        *,
+        browser_window_id: str,
+        session_id: str,
+        api_key: str | None = None,
+    ) -> None:
+        base_url = os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2")
+        super().__init__(
+            api_key=api_key or os.environ["NARADA_API_KEY"],
+            base_url=base_url,
+            browser_window_id=browser_window_id,
+        )
+        self._session_id = session_id
+
+    async def cleanup(self) -> None:
+        """Stop the cloud browser session."""
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self._base_url}/cloud-browser/stop-cloud-browser-session",
+                    headers={"x-api-key": self._api_key},
+                    json={
+                        "session_id": self._session_id,
+                    },
+                    timeout=aiohttp.ClientTimeout(total=10),
+                ) as resp:
+                    if resp.ok:
+                        response_data = await resp.json()
+                        if not response_data.get("success"):
+                            logger.warning(
+                                f"Failed to stop session: {response_data.get('message')}"
+                            )
+                    else:
+                        logger.warning(f"Failed to stop session: {resp.status}")
+        except Exception as e:
+            logger.warning(f"Error calling stop session endpoint: {e}")
+
+
 def create_side_panel_url(config: BrowserConfig, browser_window_id: str) -> str:
     return f"chrome-extension://{config.extension_id}/sidepanel.html?browserWindowId={browser_window_id}"