intent-base-sdk 0.4.0__py3-none-any.whl

intent_base/__init__.py

@@ -0,0 +1,74 @@
+"""intent-base Python SDK.
+
+Launch an isolated Profile through the local Profile Service and drive it with
+Playwright over CDP::
+
+    from intent_base import launch_profile
+
+    result = launch_profile("profile_123")
+    result.page.goto("https://example.com")
+    print(result.page.title())
+    result.close()
+"""
+
+from ._http import (
+    DEFAULT_SERVICE_URL,
+    DEFAULT_TIMEOUT_MS,
+    IntentBaseAsyncHttpClient,
+    IntentBaseHttpClient,
+)
+from .async_client import (
+    AsyncLaunchProfileResult,
+    launch_profile_async,
+    profile_status_async,
+    stop_profile_async,
+)
+from .client import launch_profile, profile_status, stop_profile
+from .errors import (
+    CdpConnectError,
+    CdpEndpointTimeoutError,
+    ChromiumLaunchFailedError,
+    ChromiumNotFoundError,
+    IntentBaseError,
+    ProfileAlreadyRunningError,
+    ProfileNotFoundError,
+    ProfileValidationError,
+    ProxyCheckFailedError,
+    RequestTimeoutError,
+    ServiceBadResponseError,
+    ServiceUnavailableError,
+    map_api_error,
+)
+from .models import LaunchProfileResponse, LaunchProfileResult
+
+__all__ = [
+    "launch_profile",
+    "stop_profile",
+    "profile_status",
+    "launch_profile_async",
+    "stop_profile_async",
+    "profile_status_async",
+    "AsyncLaunchProfileResult",
+    "LaunchProfileResponse",
+    "LaunchProfileResult",
+    "IntentBaseHttpClient",
+    "IntentBaseAsyncHttpClient",
+    "DEFAULT_SERVICE_URL",
+    "DEFAULT_TIMEOUT_MS",
+    "map_api_error",
+    "IntentBaseError",
+    "ProfileNotFoundError",
+    "ProfileAlreadyRunningError",
+    "ProfileValidationError",
+    "ProxyCheckFailedError",
+    "ChromiumNotFoundError",
+    "ChromiumLaunchFailedError",
+    "CdpEndpointTimeoutError",
+    "CdpConnectError",
+    "ServiceUnavailableError",
+    "ServiceBadResponseError",
+    "RequestTimeoutError",
+    "__version__",
+]
+
+__version__ = "0.4.0"

intent_base/_cdp.py

@@ -0,0 +1,43 @@
+"""CDP endpoint normalization helpers.
+
+The Profile Service returns a websocket browser endpoint
+(``ws://127.0.0.1:<port>/devtools/browser/<uuid>``). Playwright's
+``connect_over_cdp`` accepts either that websocket URL or an ``http://`` base
+URL, so normalization is mostly validation plus stripping a trailing slash.
+"""
+
+from __future__ import annotations
+
+from .errors import CdpConnectError
+
+
+def is_websocket_endpoint(endpoint: str) -> bool:
+    return endpoint.startswith("ws://") or endpoint.startswith("wss://")
+
+
+def normalize_cdp_endpoint(endpoint: str, *, profile_id: str | None = None) -> str:
+    """Validate and normalize a CDP endpoint for Playwright/Puppeteer.
+
+    Raises :class:`CdpConnectError` (code ``CDP_CONNECT_FAILED``) when the
+    endpoint is empty or uses an unsupported scheme.
+    """
+
+    value = (endpoint or "").strip()
+    if not value:
+        raise CdpConnectError(
+            "CDP_CONNECT_FAILED",
+            "service returned an empty CDP endpoint",
+            profile_id=profile_id,
+        )
+
+    if is_websocket_endpoint(value):
+        return value
+
+    if value.startswith("http://") or value.startswith("https://"):
+        return value.rstrip("/")
+
+    raise CdpConnectError(
+        "CDP_CONNECT_FAILED",
+        f"unsupported CDP endpoint scheme: {value}",
+        profile_id=profile_id,
+    )

intent_base/_http.py

@@ -0,0 +1,294 @@
+"""HTTP client for the local Profile Service.
+
+This layer has no Playwright dependency: it only speaks the Profile Service
+REST API and maps every failure to a typed :class:`IntentBaseError`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .errors import (
+    IntentBaseError,
+    RequestTimeoutError,
+    ServiceBadResponseError,
+    ServiceUnavailableError,
+    map_api_error,
+)
+from .models import LaunchProfileResponse
+
+DEFAULT_SERVICE_URL = "http://127.0.0.1:17390"
+DEFAULT_TIMEOUT_MS = 30000
+
+
+def resolve_service_url(service_url: Optional[str]) -> str:
+    if service_url:
+        return service_url.rstrip("/")
+    env = os.environ.get("INTENT_BASE_SERVICE_URL")
+    if env:
+        return env.rstrip("/")
+    return DEFAULT_SERVICE_URL
+
+
+def resolve_timeout_ms(timeout_ms: Optional[int]) -> int:
+    if timeout_ms is not None:
+        return timeout_ms
+    env = os.environ.get("INTENT_BASE_TIMEOUT_MS")
+    if env:
+        try:
+            return int(env)
+        except ValueError:
+            pass
+    return DEFAULT_TIMEOUT_MS
+
+
+class IntentBaseHttpClient:
+    """Synchronous Profile Service client built on httpx."""
+
+    def __init__(
+        self,
+        service_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> None:
+        self.service_url = resolve_service_url(service_url)
+        self.timeout_ms = resolve_timeout_ms(timeout_ms)
+
+    def _url(self, profile_id: str, suffix: str) -> str:
+        return f"{self.service_url}/api/v1/profiles/{profile_id}/{suffix}"
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        profile_id: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        timeout = self.timeout_ms / 1000.0
+        try:
+            response = httpx.request(method, url, json=json_body, timeout=timeout)
+        except httpx.TimeoutException as exc:
+            raise RequestTimeoutError(
+                "REQUEST_TIMEOUT",
+                f"request to {url} timed out after {self.timeout_ms}ms",
+                profile_id=profile_id,
+                cause=exc,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ServiceUnavailableError(
+                "SERVICE_UNAVAILABLE",
+                f"cannot reach Profile Service at {self.service_url}: {exc}",
+                profile_id=profile_id,
+                cause=exc,
+            ) from exc
+
+        return self._parse(response, profile_id=profile_id)
+
+    def _parse(self, response: httpx.Response, *, profile_id: str) -> Any:
+        status = response.status_code
+        text = response.text
+        body: Any = None
+        if text:
+            try:
+                body = json.loads(text)
+            except json.JSONDecodeError as exc:
+                if 200 <= status < 300:
+                    raise ServiceBadResponseError(
+                        "SERVICE_BAD_RESPONSE",
+                        f"Profile Service returned invalid JSON ({status})",
+                        status=status,
+                        profile_id=profile_id,
+                        cause=exc,
+                    ) from exc
+                body = None
+
+        if 200 <= status < 300:
+            return body
+
+        if isinstance(body, dict) and "code" in body:
+            raise map_api_error(
+                str(body.get("code")),
+                str(body.get("message", "")),
+                status,
+                profile_id=profile_id,
+            )
+
+        raise ServiceBadResponseError(
+            "SERVICE_BAD_RESPONSE",
+            f"Profile Service returned HTTP {status}",
+            status=status,
+            profile_id=profile_id,
+        )
+
+    def launch_profile(
+        self,
+        profile_id: str,
+        extra_args: Optional[List[str]] = None,
+    ) -> LaunchProfileResponse:
+        body: Dict[str, Any] = {}
+        if extra_args:
+            body["extraArgs"] = extra_args
+        result = self._request(
+            "POST",
+            self._url(profile_id, "launch"),
+            profile_id=profile_id,
+            json_body=body,
+        )
+        if not isinstance(result, dict):
+            raise ServiceBadResponseError(
+                "SERVICE_BAD_RESPONSE",
+                "launch response was not a JSON object",
+                profile_id=profile_id,
+            )
+        return LaunchProfileResponse.from_api(result)
+
+    def stop_profile(self, profile_id: str) -> Dict[str, Any]:
+        result = self._request(
+            "POST",
+            self._url(profile_id, "stop"),
+            profile_id=profile_id,
+        )
+        return result if isinstance(result, dict) else {}
+
+    def status(self, profile_id: str) -> Dict[str, Any]:
+        result = self._request(
+            "GET",
+            self._url(profile_id, "status"),
+            profile_id=profile_id,
+        )
+        return result if isinstance(result, dict) else {}
+
+
+class IntentBaseAsyncHttpClient:
+    """Asynchronous Profile Service client built on httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        service_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+    ) -> None:
+        self.service_url = resolve_service_url(service_url)
+        self.timeout_ms = resolve_timeout_ms(timeout_ms)
+
+    def _url(self, profile_id: str, suffix: str) -> str:
+        return f"{self.service_url}/api/v1/profiles/{profile_id}/{suffix}"
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        profile_id: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        timeout = self.timeout_ms / 1000.0
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                response = await client.request(method, url, json=json_body)
+        except httpx.TimeoutException as exc:
+            raise RequestTimeoutError(
+                "REQUEST_TIMEOUT",
+                f"request to {url} timed out after {self.timeout_ms}ms",
+                profile_id=profile_id,
+                cause=exc,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ServiceUnavailableError(
+                "SERVICE_UNAVAILABLE",
+                f"cannot reach Profile Service at {self.service_url}: {exc}",
+                profile_id=profile_id,
+                cause=exc,
+            ) from exc
+
+        return _parse_response(response, profile_id=profile_id)
+
+    async def launch_profile(
+        self,
+        profile_id: str,
+        extra_args: Optional[List[str]] = None,
+    ) -> LaunchProfileResponse:
+        body: Dict[str, Any] = {}
+        if extra_args:
+            body["extraArgs"] = extra_args
+        result = await self._request(
+            "POST",
+            self._url(profile_id, "launch"),
+            profile_id=profile_id,
+            json_body=body,
+        )
+        if not isinstance(result, dict):
+            raise ServiceBadResponseError(
+                "SERVICE_BAD_RESPONSE",
+                "launch response was not a JSON object",
+                profile_id=profile_id,
+            )
+        return LaunchProfileResponse.from_api(result)
+
+    async def stop_profile(self, profile_id: str) -> Dict[str, Any]:
+        result = await self._request(
+            "POST",
+            self._url(profile_id, "stop"),
+            profile_id=profile_id,
+        )
+        return result if isinstance(result, dict) else {}
+
+    async def status(self, profile_id: str) -> Dict[str, Any]:
+        result = await self._request(
+            "GET",
+            self._url(profile_id, "status"),
+            profile_id=profile_id,
+        )
+        return result if isinstance(result, dict) else {}
+
+
+def _parse_response(response: httpx.Response, *, profile_id: str) -> Any:
+    """Shared response parser for the async client (mirrors the sync logic)."""
+    status = response.status_code
+    text = response.text
+    body: Any = None
+    if text:
+        try:
+            body = json.loads(text)
+        except json.JSONDecodeError as exc:
+            if 200 <= status < 300:
+                raise ServiceBadResponseError(
+                    "SERVICE_BAD_RESPONSE",
+                    f"Profile Service returned invalid JSON ({status})",
+                    status=status,
+                    profile_id=profile_id,
+                    cause=exc,
+                ) from exc
+            body = None
+
+    if 200 <= status < 300:
+        return body
+
+    if isinstance(body, dict) and "code" in body:
+        raise map_api_error(
+            str(body.get("code")),
+            str(body.get("message", "")),
+            status,
+            profile_id=profile_id,
+        )
+
+    raise ServiceBadResponseError(
+        "SERVICE_BAD_RESPONSE",
+        f"Profile Service returned HTTP {status}",
+        status=status,
+        profile_id=profile_id,
+    )
+
+
+__all__ = [
+    "IntentBaseHttpClient",
+    "IntentBaseAsyncHttpClient",
+    "IntentBaseError",
+    "resolve_service_url",
+    "resolve_timeout_ms",
+    "DEFAULT_SERVICE_URL",
+    "DEFAULT_TIMEOUT_MS",
+]

intent_base/async_client.py

@@ -0,0 +1,98 @@
+"""Public asynchronous API for the intent-base Python SDK.
+
+Shares DTOs and error mapping with the sync client; only the Playwright and
+HTTP transport are async. The returned :class:`LaunchProfileResult` exposes a
+coroutine ``aclose()`` plus a synchronous ``close()`` for symmetry.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from ._http import IntentBaseAsyncHttpClient
+from .models import LaunchProfileResponse
+from .playwright import connect_playwright_async
+
+
+@dataclass(frozen=True)
+class AsyncLaunchProfileResult:
+    browser: Any
+    context: Any
+    page: Any
+    metadata: LaunchProfileResponse
+    _driver: Any = None
+    _http: Any = None
+    _profile_id: str = ""
+    _auto_stop: bool = False
+
+    @property
+    def profile_id(self) -> str:
+        return self.metadata.profile_id
+
+    @property
+    def cdp_endpoint(self) -> str:
+        return self.metadata.cdp_endpoint
+
+    async def aclose(self) -> None:
+        try:
+            await self.browser.close()
+        finally:
+            if self._driver is not None:
+                try:
+                    await self._driver.stop()
+                finally:
+                    if self._auto_stop and self._http is not None:
+                        try:
+                            await self._http.stop_profile(self._profile_id)
+                        except Exception:  # noqa: BLE001
+                            pass
+
+
+async def launch_profile_async(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    extra_args: Optional[List[str]] = None,
+    timeout_ms: Optional[int] = None,
+    auto_stop: bool = False,
+) -> AsyncLaunchProfileResult:
+    """Async variant of :func:`intent_base.launch_profile`."""
+
+    http = IntentBaseAsyncHttpClient(service_url, timeout_ms)
+    metadata = await http.launch_profile(profile_id, extra_args)
+
+    browser, context, page, driver = await connect_playwright_async(
+        metadata.cdp_endpoint, profile_id=profile_id
+    )
+
+    return AsyncLaunchProfileResult(
+        browser=browser,
+        context=context,
+        page=page,
+        metadata=metadata,
+        _driver=driver,
+        _http=http,
+        _profile_id=profile_id,
+        _auto_stop=auto_stop,
+    )
+
+
+async def stop_profile_async(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    timeout_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    return await IntentBaseAsyncHttpClient(service_url, timeout_ms).stop_profile(
+        profile_id
+    )
+
+
+async def profile_status_async(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    timeout_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    return await IntentBaseAsyncHttpClient(service_url, timeout_ms).status(profile_id)

intent_base/client.py

@@ -0,0 +1,79 @@
+"""Public synchronous API for the intent-base Python SDK.
+
+``launch_profile`` asks the local Profile Service to start the Profile's
+Chromium, then connects Playwright to the returned CDP endpoint. The SDK never
+launches Chromium itself and never passes isolation-critical browser args.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._http import IntentBaseHttpClient
+from .errors import CdpConnectError
+from .models import LaunchProfileResponse, LaunchProfileResult
+from .playwright import connect_playwright
+
+
+def launch_profile(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    extra_args: Optional[List[str]] = None,
+    timeout_ms: Optional[int] = None,
+    auto_stop: bool = False,
+) -> LaunchProfileResult:
+    """Launch ``profile_id`` and return a connected Playwright handle.
+
+    Set ``auto_stop=True`` to also stop the Profile on ``result.close()``;
+    otherwise only the CDP connection and Playwright driver are torn down and
+    the Profile keeps running.
+    """
+
+    http = IntentBaseHttpClient(service_url, timeout_ms)
+    metadata: LaunchProfileResponse = http.launch_profile(profile_id, extra_args)
+
+    browser, context, page, driver = connect_playwright(
+        metadata.cdp_endpoint, profile_id=profile_id
+    )
+
+    def _close() -> None:
+        try:
+            browser.close()
+        finally:
+            try:
+                driver.stop()
+            finally:
+                if auto_stop:
+                    try:
+                        http.stop_profile(profile_id)
+                    except Exception:  # noqa: BLE001 - best effort on close
+                        pass
+
+    return LaunchProfileResult(
+        browser=browser,
+        context=context,
+        page=page,
+        metadata=metadata,
+        _closer=_close,
+    )
+
+
+def stop_profile(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    timeout_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Stop a running Profile via the Profile Service."""
+    return IntentBaseHttpClient(service_url, timeout_ms).stop_profile(profile_id)
+
+
+def profile_status(
+    profile_id: str,
+    *,
+    service_url: Optional[str] = None,
+    timeout_ms: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Fetch the current lifecycle status of a Profile."""
+    return IntentBaseHttpClient(service_url, timeout_ms).status(profile_id)

intent_base/errors.py

@@ -0,0 +1,132 @@
+"""Typed errors for the intent-base Python SDK.
+
+Every failure raised by the SDK is an :class:`IntentBaseError` (or subclass)
+that preserves the machine-readable ``code`` from the Profile Service so callers
+can branch on it without parsing messages.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class IntentBaseError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        profile_id: Optional[str] = None,
+        cause: Optional[BaseException] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.profile_id = profile_id
+        self.cause = cause
+        self.details = details or {}
+        if cause is not None:
+            self.__cause__ = cause
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return (
+            f"{type(self).__name__}(code={self.code!r}, message={self.message!r}, "
+            f"status={self.status!r}, profile_id={self.profile_id!r})"
+        )
+
+
+class ProfileNotFoundError(IntentBaseError):
+    pass
+
+
+class ProfileAlreadyRunningError(IntentBaseError):
+    pass
+
+
+class ProfileValidationError(IntentBaseError):
+    pass
+
+
+class ProxyCheckFailedError(IntentBaseError):
+    pass
+
+
+class ChromiumNotFoundError(IntentBaseError):
+    pass
+
+
+class ChromiumLaunchFailedError(IntentBaseError):
+    pass
+
+
+class CdpEndpointTimeoutError(IntentBaseError):
+    pass
+
+
+class CdpConnectError(IntentBaseError):
+    pass
+
+
+class ServiceUnavailableError(IntentBaseError):
+    pass
+
+
+class ServiceBadResponseError(IntentBaseError):
+    pass
+
+
+class RequestTimeoutError(IntentBaseError):
+    pass
+
+
+# Service-side codes (see services/profile-service/src/error.rs) plus the
+# SDK-only transport codes the document mandates.
+_CODE_TO_CLASS: Dict[str, type] = {
+    "PROFILE_NOT_FOUND": ProfileNotFoundError,
+    "PROFILE_ALREADY_RUNNING": ProfileAlreadyRunningError,
+    "PROFILE_RUNNING": ProfileAlreadyRunningError,
+    "PROFILE_VALIDATION": ProfileValidationError,
+    "BROWSER_ARG_FORBIDDEN": ProfileValidationError,
+    "PROXY_CHECK_FAILED": ProxyCheckFailedError,
+    "PROXY_CONFIG_MISSING": ProxyCheckFailedError,
+    "CHROMIUM_NOT_FOUND": ChromiumNotFoundError,
+    "CHROMIUM_LAUNCH_FAILED": ChromiumLaunchFailedError,
+    "CHROMIUM_EXITED_EARLY": ChromiumLaunchFailedError,
+    "CDP_ENDPOINT_TIMEOUT": CdpEndpointTimeoutError,
+    "CDP_ENDPOINT_INVALID": CdpConnectError,
+    "CDP_CONNECT_FAILED": CdpConnectError,
+    "SERVICE_UNAVAILABLE": ServiceUnavailableError,
+    "SERVICE_BAD_RESPONSE": ServiceBadResponseError,
+    "REQUEST_TIMEOUT": RequestTimeoutError,
+}
+
+
+def map_api_error(
+    code: str,
+    message: str,
+    status: Optional[int] = None,
+    *,
+    profile_id: Optional[str] = None,
+    cause: Optional[BaseException] = None,
+    details: Optional[Dict[str, Any]] = None,
+) -> IntentBaseError:
+    """Build the typed error for a service ``code``.
+
+    Unknown codes fall back to the base :class:`IntentBaseError` while still
+    preserving the original code so callers never lose information.
+    """
+
+    cls = _CODE_TO_CLASS.get(code, IntentBaseError)
+    return cls(
+        code,
+        message,
+        status=status,
+        profile_id=profile_id,
+        cause=cause,
+        details=details,
+    )

intent_base/models.py

@@ -0,0 +1,67 @@
+"""DTOs for the intent-base Python SDK.
+
+These mirror the Profile Service API contract defined in
+``crates/intent-base-types/src/browser.rs``. The HTTP layer speaks camelCase
+on the wire; these dataclasses use snake_case and are built via
+``LaunchProfileResponse.from_api``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+
+@dataclass(frozen=True)
+class LaunchProfileResponse:
+    """Successful ``POST /api/v1/profiles/:id/launch`` body."""
+
+    profile_id: str
+    status: str
+    pid: int
+    cdp_endpoint: str
+    devtools_port: int
+    user_data_path: str
+    browser_log_path: str
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> "LaunchProfileResponse":
+        return cls(
+            profile_id=str(body.get("profileId", "")),
+            status=str(body.get("status", "")),
+            pid=int(body.get("pid", 0)),
+            cdp_endpoint=str(body.get("cdpEndpoint", "")),
+            devtools_port=int(body.get("devtoolsPort", 0)),
+            user_data_path=str(body.get("userDataPath", "")),
+            browser_log_path=str(body.get("browserLogPath", "")),
+        )
+
+
+@dataclass(frozen=True)
+class LaunchProfileResult:
+    """Handles returned by ``launch_profile``.
+
+    ``browser`` / ``context`` / ``page`` are Playwright objects (typed as
+    ``Any`` so the base SDK does not depend on Playwright). Call ``close()`` to
+    disconnect from the browser and stop the Playwright driver; the underlying
+    Profile keeps running unless ``auto_stop`` was requested at launch time.
+    """
+
+    browser: Any
+    context: Any
+    page: Any
+    metadata: LaunchProfileResponse
+    _closer: Optional[Any] = None
+
+    @property
+    def profile_id(self) -> str:
+        return self.metadata.profile_id
+
+    @property
+    def cdp_endpoint(self) -> str:
+        return self.metadata.cdp_endpoint
+
+    def close(self) -> None:
+        """Disconnect from the browser and tear down the Playwright driver."""
+        if self._closer is not None:
+            self._closer()

intent_base/playwright.py

@@ -0,0 +1,101 @@
+"""Playwright connection helpers.
+
+Playwright is an optional dependency. Importing this module without Playwright
+installed raises a clear :class:`CdpConnectError` telling the user to install
+it, rather than a bare ``ModuleNotFoundError``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from ._cdp import normalize_cdp_endpoint
+from .errors import CdpConnectError
+
+
+def _require_sync_playwright(profile_id: str | None = None):
+    try:
+        from playwright.sync_api import sync_playwright  # type: ignore
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise CdpConnectError(
+            "CDP_CONNECT_FAILED",
+            "Playwright is required for launch_profile. Install it with "
+            "`pip install \"intent-base[playwright]\"` then run `playwright install chromium`.",
+            profile_id=profile_id,
+            cause=exc,
+        ) from exc
+    return sync_playwright
+
+
+def _require_async_playwright(profile_id: str | None = None):
+    try:
+        from playwright.async_api import async_playwright  # type: ignore
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise CdpConnectError(
+            "CDP_CONNECT_FAILED",
+            "Playwright is required for launch_profile_async. Install it with "
+            "`pip install \"intent-base[playwright]\"` then run `playwright install chromium`.",
+            profile_id=profile_id,
+            cause=exc,
+        ) from exc
+    return async_playwright
+
+
+def connect_playwright(
+    cdp_endpoint: str,
+    *,
+    profile_id: str | None = None,
+) -> Tuple[Any, Any, Any, Any]:
+    """Connect to an already-launched browser over CDP (sync API).
+
+    Returns ``(browser, context, page, driver)`` where ``driver`` is the
+    started Playwright instance the caller must stop on close.
+    """
+
+    endpoint = normalize_cdp_endpoint(cdp_endpoint, profile_id=profile_id)
+    sync_playwright = _require_sync_playwright(profile_id)
+
+    driver = sync_playwright().start()
+    try:
+        browser = driver.chromium.connect_over_cdp(endpoint)
+    except Exception as exc:  # noqa: BLE001 - normalize any connect failure
+        driver.stop()
+        raise CdpConnectError(
+            "CDP_CONNECT_FAILED",
+            f"failed to connect to CDP endpoint: {exc}",
+            profile_id=profile_id,
+            cause=exc,
+        ) from exc
+
+    context = browser.contexts[0] if browser.contexts else browser.new_context()
+    page = context.pages[0] if context.pages else context.new_page()
+    return browser, context, page, driver
+
+
+async def connect_playwright_async(
+    cdp_endpoint: str,
+    *,
+    profile_id: str | None = None,
+) -> Tuple[Any, Any, Any, Any]:
+    """Connect to an already-launched browser over CDP (async API)."""
+
+    endpoint = normalize_cdp_endpoint(cdp_endpoint, profile_id=profile_id)
+    async_playwright = _require_async_playwright(profile_id)
+
+    driver = await async_playwright().start()
+    try:
+        browser = await driver.chromium.connect_over_cdp(endpoint)
+    except Exception as exc:  # noqa: BLE001
+        await driver.stop()
+        raise CdpConnectError(
+            "CDP_CONNECT_FAILED",
+            f"failed to connect to CDP endpoint: {exc}",
+            profile_id=profile_id,
+            cause=exc,
+        ) from exc
+
+    contexts = browser.contexts
+    context = contexts[0] if contexts else await browser.new_context()
+    pages = context.pages
+    page = pages[0] if pages else await context.new_page()
+    return browser, context, page, driver

intent_base_sdk-0.4.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: intent-base-sdk
+Version: 0.4.0
+Summary: intent-base Python SDK: launch isolated Profiles via the local Profile Service and drive them with Playwright over CDP.
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.45; extra == 'playwright'
+Description-Content-Type: text/markdown
+
+# intent-base-sdk
+
+Python SDK for [intent-base](https://github.com/YOUR_ORG/intent-base): launch an
+isolated Profile through the local Profile Service and drive it with Playwright
+over CDP. The SDK never launches Chromium itself — only the Profile Service
+does.
+
+## Install (PyPI)
+
+Requires Profile Service running (default `http://127.0.0.1:17390`).
+
+```bash
+pip install intent-base-sdk==0.4.0
+pip install "intent-base-sdk[playwright]==0.4.0"
+playwright install chromium
+```
+
+The base package only needs `httpx`. Playwright is an optional extra.
+
+## Configuration
+
+| Option        | Default                     | Environment variable        |
+| ------------- | --------------------------- | --------------------------- |
+| `service_url` | `http://127.0.0.1:17390`    | `INTENT_BASE_SERVICE_URL`   |
+| `timeout_ms`  | `30000`                     | `INTENT_BASE_TIMEOUT_MS`    |
+
+## Sync usage
+
+```python
+from intent_base import launch_profile
+
+result = launch_profile("profile_123")
+result.page.goto("https://example.com")
+print(result.page.title())
+result.close()
+```
+
+Pass `auto_stop=True` to also stop the Profile on `close()`.
+
+## Async usage
+
+```python
+import asyncio
+from intent_base import launch_profile_async
+
+async def main():
+    result = await launch_profile_async("profile_123")
+    await result.page.goto("https://example.com")
+    print(await result.page.title())
+    await result.aclose()
+
+asyncio.run(main())
+```
+
+## Errors
+
+```python
+from intent_base import launch_profile, ProfileAlreadyRunningError, IntentBaseError
+
+try:
+    result = launch_profile("profile_123")
+except ProfileAlreadyRunningError as err:
+    print("already running:", err.code)
+except IntentBaseError as err:
+    print(err.code, err.message, err.status)
+```
+
+## Monorepo development
+
+```bash
+pip install -e "sdks/python[dev,playwright]"
+python -m pytest sdks/python/tests
+```
+
+See [docs/PUBLISH.md](../../docs/PUBLISH.md) for PyPI release steps.

intent_base_sdk-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+intent_base/__init__.py,sha256=rbtoO3kxOQjaxndyjpZGSRIlS4D-lyaO4NEMU_3B4rg,1852
+intent_base/_cdp.py,sha256=wZ99I3MMwLOVwWcnBejF5LA61Op-WCVvOCeOXTN4vg8,1342
+intent_base/_http.py,sha256=xgiVYYnZdVGJe-HxunEewwYuLMmXTsCnisO_tNhlzCA,9080
+intent_base/async_client.py,sha256=3FPI1oMoNCUNQB5DT02NYfQsTbuDAlz904uidGoxLjQ,2785
+intent_base/client.py,sha256=IquvNjzRSAKvYytt8sdLfVMWfTegmdc7Jf3-iOw0-vg,2398
+intent_base/errors.py,sha256=z9NyJWxwp6cY6OHoWsw2OrRL2Un0GSmquaGMWWbBIfY,3497
+intent_base/models.py,sha256=0aj9q0amT8PEuFl4VgLq4CeUadj_pAKyq9tfrAq-AyQ,2061
+intent_base/playwright.py,sha256=Qjq4CY5LqWQrMXiYVat0IH9bdbkAQLN29q0kBRYlFRg,3539
+intent_base_sdk-0.4.0.dist-info/METADATA,sha256=Jt6BAiJrBcrL0ToPvEIlGN-i8VJ5e27CoXBzQzm5Lk8,2549
+intent_base_sdk-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+intent_base_sdk-0.4.0.dist-info/RECORD,,

intent_base_sdk-0.4.0.dist-info/WHEEL

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