narada 0.1.27__py3-none-any.whl → 0.1.29__py3-none-any.whl

narada/__init__.py

@@ -1,5 +1,3 @@
-import importlib.metadata
-
 from narada_core.errors import (
     NaradaError,
     NaradaExtensionMissingError,
@@ -11,17 +9,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
+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
 
-# Get version from package metadata
-try:
-    __version__ = importlib.metadata.version("narada")
-except Exception:
-    # Fallback version if package metadata is not available
-    __version__ = "unknown"
-
 __all__ = [
     "__version__",
     "Agent",
@@ -36,6 +28,7 @@ __all__ = [
     "NaradaInitializationError",
     "NaradaTimeoutError",
     "NaradaUnsupportedBrowserError",
+    "ProxyConfig",
     "RemoteBrowserWindow",
     "render_html",
     "Response",

narada/client.py

@@ -9,6 +9,8 @@ from dataclasses import dataclass
 from typing import Any
 from uuid import uuid4
 
+import aiohttp
+import semver
 from narada_core.errors import (
     NaradaExtensionMissingError,
     NaradaExtensionUnauthenticatedError,
@@ -16,8 +18,11 @@ from narada_core.errors import (
     NaradaTimeoutError,
     NaradaUnsupportedBrowserError,
 )
+from narada_core.models import _SdkConfig
 from playwright._impl._errors import Error as PlaywrightError
 from playwright.async_api import (
+    Browser,
+    CDPSession,
     ElementHandle,
     Page,
     Playwright,
@@ -29,8 +34,9 @@ from playwright.async_api import (
 from playwright.async_api._context_manager import PlaywrightContextManager
 from rich.console import Console
 
-from narada.config import BrowserConfig
+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
 
 
@@ -58,6 +64,8 @@ class Narada:
         self._console = Console()
 
     async def __aenter__(self) -> Narada:
+        await self._validate_sdk_config()
+
         self._playwright_context_manager = async_playwright()
         self._playwright = await self._playwright_context_manager.__aenter__()
         return self
@@ -70,6 +78,40 @@ class Narada:
         self._playwright_context_manager = None
         self._playwright = None
 
+    async def _fetch_sdk_config(self) -> _SdkConfig | None:
+        base_url = os.getenv("NARADA_API_BASE_URL", "https://api.narada.ai/fast/v2")
+        url = f"{base_url}/sdk/config"
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    url, headers={"x-api-key": self._api_key}
+                ) as resp:
+                    if not resp.ok:
+                        logging.warning(
+                            "Failed to fetch SDK config: %s %s",
+                            resp.status,
+                            await resp.text(),
+                        )
+                        return None
+
+                    return _SdkConfig.model_validate(await resp.json())
+        except Exception as e:
+            logging.warning("Failed to fetch SDK config: %s", e)
+            return None
+
+    async def _validate_sdk_config(self) -> None:
+        config = await self._fetch_sdk_config()
+        if config is None:
+            return
+
+        package_config = config.packages["narada"]
+        if semver.compare(__version__, package_config.min_required_version) < 0:
+            raise RuntimeError(
+                f"narada<={__version__} is not supported. Please upgrade to version "
+                f"{package_config.min_required_version} or higher."
+            )
+
     async def open_and_initialize_browser_window(
         self, config: BrowserConfig | None = None
     ) -> LocalBrowserWindow:
@@ -106,6 +148,13 @@ class Narada:
 
         config = config or BrowserConfig()
 
+        if config.proxy is not None:
+            raise ValueError(
+                "Proxy configuration is not supported for `initialize_in_existing_browser_window`. "
+                "Proxy settings must be specified when launching Chrome. "
+                "Use `open_and_initialize_browser_window` instead."
+            )
+
         browser = await playwright.chromium.connect_over_cdp(config.cdp_url)
 
         # Generate a unique tag for the initialization URL
@@ -153,6 +202,13 @@ class Narada:
         window_tag = uuid4().hex
         tagged_initialization_url = f"{config.initialization_url}?t={window_tag}"
 
+        # When proxy auth is needed, launch with about:blank to avoid Chrome's startup auth prompt.
+        # We'll set up the CDP auth handler and then navigate to the init URL.
+        proxy_requires_auth = (
+            config.proxy is not None and config.proxy.requires_authentication
+        )
+        launch_url = "about:blank" if proxy_requires_auth else tagged_initialization_url
+
         browser_args = [
             f"--user-data-dir={config.user_data_dir}",
             f"--profile-directory={config.profile_directory}",
@@ -160,11 +216,20 @@ class Narada:
             "--no-default-browser-check",
             "--no-first-run",
             "--new-window",
-            tagged_initialization_url,
-            # TODO: This is needed if we don't use CDP but let Playwright manage the browser.
-            # "--disable-blink-features=AutomationControlled",
+            launch_url,
         ]
 
+        # Add proxy arguments if configured.
+        if config.proxy is not None:
+            config.proxy.validate()
+            browser_args.append(f"--proxy-server={config.proxy.server}")
+
+            if config.proxy.bypass:
+                browser_args.append(f"--proxy-bypass-list={config.proxy.bypass}")
+
+            if config.proxy.ignore_cert_errors:
+                browser_args.append("--ignore-certificate-errors")
+
         # Launch an independent browser process which will not be killed when the current program
         # exits.
         if sys.platform == "win32":
@@ -195,6 +260,14 @@ class Narada:
         browser_window_id = None
         side_panel_page = None
         max_cdp_connect_attempts = 10
+
+        # Track whether we've already navigated from about:blank to the initialization URL.
+        # This is only relevant when proxy auth is enabled, where we launch with about:blank
+        # to set up CDP auth handlers before any network traffic. We must only navigate once,
+        # because on retry iterations context.pages[0] could be any page (side panel, devtools,
+        # etc.) and navigating it would break the initialization flow.
+        did_initial_navigation = False
+
         for attempt in range(max_cdp_connect_attempts):
             try:
                 browser = await playwright.chromium.connect_over_cdp(config.cdp_url)
@@ -206,8 +279,23 @@ class Narada:
                 await asyncio.sleep(2)
                 continue
 
-            # Grab the browser window ID from the page we just opened.
             context = browser.contexts[0]
+
+            # If proxy auth is needed, set up the handler at browser level then navigate to the
+            # initialization page. After navigation succeeds, Chrome has cached the proxy
+            # credentials, so we can detach the CDP session.
+            if proxy_requires_auth and not did_initial_navigation:
+                proxy_cdp_session = (
+                    await self._setup_proxy_authentication_browser_level(
+                        browser, config.proxy
+                    )
+                )
+                blank_page = context.pages[0]
+                await blank_page.goto(tagged_initialization_url)
+                await proxy_cdp_session.detach()
+                did_initial_navigation = True
+
+            # Grab the browser window ID from the page we just opened.
             initialization_page = next(
                 (p for p in context.pages if p.url == tagged_initialization_url), None
             )
@@ -375,6 +463,73 @@ class Narada:
                 initialization_page
             )
 
+    async def _setup_proxy_authentication_browser_level(
+        self, browser: Browser, proxy_config: ProxyConfig
+    ) -> CDPSession:
+        """Sets up proxy authentication handling via CDP at the browser level.
+
+        This uses a browser-level CDP session which can intercept auth challenges before they reach
+        individual pages, preventing Chrome from showing the proxy authentication dialog.
+
+        Chrome caches proxy credentials for the session after the first successful authentication.
+        The caller should detach the returned CDP session after the first navigation succeeds.
+        """
+        cdp_session = await browser.new_browser_cdp_session()
+
+        # Enable Fetch domain with a catch-all pattern to intercept auth challenges.
+        await cdp_session.send(
+            "Fetch.enable",
+            {
+                "handleAuthRequests": True,
+                "patterns": [{"urlPattern": "*"}],
+            },
+        )
+
+        async def handle_auth(params: dict[str, Any]) -> None:
+            request_id = params.get("requestId")
+            auth_challenge = params.get("authChallenge", {})
+
+            # Only handle proxy auth challenges
+            if auth_challenge.get("source") != "Proxy":
+                return
+
+            try:
+                await cdp_session.send(
+                    "Fetch.continueWithAuth",
+                    {
+                        "requestId": request_id,
+                        "authChallengeResponse": {
+                            "response": "ProvideCredentials",
+                            "username": proxy_config.username,
+                            "password": proxy_config.password,
+                        },
+                    },
+                )
+                logging.debug("Browser-level proxy authentication credentials provided")
+            except Exception as e:
+                logging.error("Failed to respond to proxy auth challenge: %s", e)
+
+        async def handle_request_paused(params: dict[str, Any]) -> None:
+            # Continue all paused requests immediately
+            request_id = params.get("requestId")
+            try:
+                await cdp_session.send(
+                    "Fetch.continueRequest", {"requestId": request_id}
+                )
+            except Exception:
+                pass
+
+        cdp_session.on(
+            "Fetch.authRequired",
+            lambda params: asyncio.create_task(handle_auth(params)),
+        )
+        cdp_session.on(
+            "Fetch.requestPaused",
+            lambda params: asyncio.create_task(handle_request_paused(params)),
+        )
+
+        return cdp_session
+
     async def _fix_download_behavior(self, side_panel_page: Page) -> None:
         """Reverts the download behavior to the default behavior for the extension, otherwise our
         extension cannot download files.

narada/config.py

@@ -22,6 +22,50 @@ def _default_user_data_dir() -> str:
     return str(Path("~/.config/narada/user-data-dirs/default").expanduser())
 
 
+@dataclass
+class ProxyConfig:
+    """Configuration for HTTP/HTTPS/SOCKS5 proxy.
+
+    Args:
+        server: Proxy server URL. HTTP and SOCKS proxies are supported, for example
+                "http://myproxy.com:3128" or "socks5://myproxy.com:3128".
+                Short form "myproxy.com:3128" is considered an HTTP proxy.
+        username: Optional username for proxy authentication.
+        password: Optional password for proxy authentication.
+        bypass: Optional comma-separated domains to bypass proxy,
+                for example ".com, chromium.org, .domain.com".
+        ignore_cert_errors: If True, ignore SSL certificate errors. Required for proxies that
+                            perform HTTPS inspection (MITM). Use with caution.
+    """
+
+    server: str
+    username: str | None = None
+    password: str | None = None
+    bypass: str | None = None
+    ignore_cert_errors: bool = False
+
+    @property
+    def requires_authentication(self) -> bool:
+        """Returns True if proxy requires authentication."""
+        return self.username is not None and self.password is not None
+
+    def validate(self) -> None:
+        """Validates the proxy configuration.
+
+        Raises:
+            ValueError: If configuration is invalid.
+        """
+        if not self.server:
+            raise ValueError("Proxy server cannot be empty")
+
+        # Validate that if one credential is provided, both are provided
+        if (self.username is None) != (self.password is None):
+            raise ValueError(
+                "Both username and password must be provided for proxy authentication, "
+                "or neither should be provided"
+            )
+
+
 @dataclass
 class BrowserConfig:
     executable_path: str = field(default_factory=_default_executable_path)
@@ -32,6 +76,7 @@ class BrowserConfig:
     initialization_url: str = "https://app.narada.ai/initialize"
     extension_id: str = "bhioaidlggjdkheaajakomifblpjmokn"
     interactive: bool = True
+    proxy: ProxyConfig | None = None
 
     @property
     def cdp_url(self) -> str:

narada/version.py

@@ -0,0 +1,7 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("narada")
+except Exception:
+    # Fallback version if package metadata is not available
+    __version__ = "unknown"

narada/window.py

@@ -4,12 +4,15 @@ import time
 from abc import ABC
 from http import HTTPStatus
 from pathlib import Path
-from typing import IO, Any, TypeVar, overload
+from typing import IO, Any, Optional, TypeVar, overload
 
 import aiohttp
 from narada_core.actions.models import (
     AgenticSelectorAction,
     AgenticSelectorRequest,
+    AgenticSelectorResponse,
+    AgenticMouseActionRequest,
+    AgenticMouseAction,
     AgenticSelectors,
     AgentResponse,
     AgentUsage,
@@ -21,6 +24,7 @@ from narada_core.actions.models import (
     ReadGoogleSheetRequest,
     ReadGoogleSheetResponse,
     WriteGoogleSheetRequest,
+    RecordedClick,
 )
 from narada_core.errors import (
     NaradaAgentTimeoutError_INTERNAL_DO_NOT_USE,
@@ -325,14 +329,47 @@ class BaseBrowserWindow(ABC):
         fallback_operator_query: str,
         # Larger default timeout because Operator can take a bit to run.
         timeout: int | None = 60,
-    ) -> None:
+    ) -> AgenticSelectorResponse:
         """Performs an action on an element specified by the given selectors, falling back to using
         the Operator agent if the selectors fail to match a unique element.
         """
-        return await self._run_extension_action(
+        response_model = (
+            AgenticSelectorResponse
+            if action["type"] in {"get_text", "get_property"}
+            else None
+        )
+        result = await self._run_extension_action(
             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 result
+
+    async def agentic_mouse_action(
+        self,
+        *,
+        action: AgenticMouseAction,
+        recorded_click: RecordedClick,
+        fallback_operator_query: str,
+        resize_window: bool = True,
+        timeout: int | None = 60,
+    ) -> None:
+        """Performs a mouse action at the specified click coordinates, falling back to using
+        the Operator agent if the click fails.
+        """
+        return await self._run_extension_action(
+            AgenticMouseActionRequest(
+                action=action,
+                recorded_click=recorded_click,
+                resize_window=resize_window,
                 fallback_operator_query=fallback_operator_query,
             ),
             timeout=timeout,

{narada-0.1.27.dist-info → narada-0.1.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: narada
-Version: 0.1.27
+Version: 0.1.29
 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,9 +9,10 @@ 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.5
+Requires-Dist: narada-core==0.0.7
 Requires-Dist: playwright>=1.53.0
 Requires-Dist: rich>=14.0.0
+Requires-Dist: semver>=3.0.4
 Description-Content-Type: text/markdown
 
 <p align="center">

narada-0.1.29.dist-info/RECORD

@@ -0,0 +1,10 @@
+narada/__init__.py,sha256=2AnpZVQpkh4-onnvbgHX1Wlq1Fa8ya4vAzy2fbS0bCY,968
+narada/client.py,sha256=_nTRHkiYt7lmUgO0HibVagrPXf523LCbWx8JmuVGgoo,21622
+narada/config.py,sha256=S0B8GNd-0td_69oKaPN60WAq_ODeYU7avE_KAxN5vCg,3052
+narada/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+narada/utils.py,sha256=gdLwNMXPpRohDcIIe0cB3KhvZ8X1QfAlKVh1sXWeJmk,1284
+narada/version.py,sha256=kwW6yy0_4Pf3kt888eeCG0VwBb2L2rCkrkpdZEC_3rA,193
+narada/window.py,sha256=hWkL637Aj7ZoJNFkvg92lSHRBaK72FY2WcCoyxzXKyk,18928
+narada-0.1.29.dist-info/METADATA,sha256=ZRJ6lY2UYwj-kMsCOL5peS1mjni9Kr0Y5ROOfK4uBPE,5146
+narada-0.1.29.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+narada-0.1.29.dist-info/RECORD,,

{narada-0.1.27.dist-info → narada-0.1.29.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

narada-0.1.27.dist-info/RECORD

@@ -1,9 +0,0 @@
-narada/__init__.py,sha256=TFEfS_6cCaD2mLUDBTUOUar3wJqjz1wyyd7sx43MYUk,1127
-narada/client.py,sha256=jksBBWdSJP88fP1DpLYoyJNNdgkUMrEKlcuYenARzaI,15265
-narada/config.py,sha256=tvj16P_qAHOFB2O_VlrcizA8SrbmS_Nmkm2r7ltG-VM,1345
-narada/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-narada/utils.py,sha256=gdLwNMXPpRohDcIIe0cB3KhvZ8X1QfAlKVh1sXWeJmk,1284
-narada/window.py,sha256=OGuEs778xjxHivzWlJIIHKZPqGd4Sn9_YVArt_8TYoU,17762
-narada-0.1.27.dist-info/METADATA,sha256=_qPEc-3NJIO04Jt9sGUSLeoFTG-ZeoQxJ-5iKhwaPP4,5117
-narada-0.1.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-narada-0.1.27.dist-info/RECORD,,