intent-base-sdk 0.4.0__tar.gz

intent_base_sdk-0.4.0/.gitignore

@@ -0,0 +1,54 @@
+# Rust
+/target
+**/target
+# Cargo.lock is committed for reproducible application builds
+
+# Node
+node_modules
+dist
+.pnpm-store
+*.tsbuildinfo
+
+# Tauri
+apps/desktop/src-tauri/target
+apps/desktop/src-tauri/gen
+
+# Runtime data (local only)
+runtime/*
+!runtime/.gitkeep
+
+# Validation evidence (local only)
+reports/*
+!reports/.gitkeep
+!reports/samples/
+!reports/samples/**
+
+# Internal validation (artifacts local; scripts + ci config committed for monorepo)
+validation/*
+!validation/scripts/
+!validation/scripts/**
+!validation/ci/
+!validation/ci/**
+validation/artifacts/
+validation/**/node_modules/
+
+# Env
+.env
+
+# Local tooling bootstrap (vendored pnpm, icon generator, etc.)
+.tooling
+
+# Python
+__pycache__/
+*.py[cod]
+.venv
+*.egg-info
+
+# Chromium patch island (local only, not published)
+# Kept in monorepo at chromium/src/intentbase — do not commit to the public repo.
+kernel/
+
+# Editor / OS
+.DS_Store
+.idea
+.vscode

intent_base_sdk-0.4.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — intent-base-sdk
+
+## 0.4.0 — 2026-07-06
+
+- First public PyPI release as `intent-base-sdk` (import: `intent_base`).
+- Sync and async `launch_profile` over Profile Service + Playwright CDP.
+- Typed exceptions mirroring profile-service error codes.
+
+## 0.1.0
+
+- Monorepo editable-install preview (`intent-base` package name).

intent_base_sdk-0.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/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_sdk-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_sdk-0.4.0/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_sdk-0.4.0/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_sdk-0.4.0/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_sdk-0.4.0/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_sdk-0.4.0/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_sdk-0.4.0/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/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "intent-base-sdk"
+version = "0.4.0"
+description = "intent-base Python SDK: launch isolated Profiles via the local Profile Service and drive them with Playwright over CDP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.45"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21", "build>=1.2", "twine>=5"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["intent_base"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

intent_base_sdk-0.4.0/tests/test_cdp.py

@@ -0,0 +1,33 @@
+import pytest
+
+from intent_base._cdp import is_websocket_endpoint, normalize_cdp_endpoint
+from intent_base.errors import CdpConnectError
+
+
+def test_normalize_websocket_endpoint_passthrough():
+    ws = "ws://127.0.0.1:52341/devtools/browser/abc-123"
+    assert normalize_cdp_endpoint(ws) == ws
+    assert is_websocket_endpoint(ws) is True
+
+
+def test_normalize_wss_endpoint_passthrough():
+    wss = "wss://example.com:443/devtools/browser/x"
+    assert normalize_cdp_endpoint(wss) == wss
+
+
+def test_normalize_http_endpoint_strips_trailing_slash():
+    assert normalize_cdp_endpoint("http://127.0.0.1:9222/") == "http://127.0.0.1:9222"
+    assert is_websocket_endpoint("http://127.0.0.1:9222") is False
+
+
+def test_empty_endpoint_raises_cdp_connect_failed():
+    with pytest.raises(CdpConnectError) as exc:
+        normalize_cdp_endpoint("", profile_id="p1")
+    assert exc.value.code == "CDP_CONNECT_FAILED"
+    assert exc.value.profile_id == "p1"
+
+
+def test_unsupported_scheme_raises():
+    with pytest.raises(CdpConnectError) as exc:
+        normalize_cdp_endpoint("tcp://127.0.0.1:9222")
+    assert exc.value.code == "CDP_CONNECT_FAILED"

intent_base_sdk-0.4.0/tests/test_client.py

@@ -0,0 +1,113 @@
+import httpx
+import pytest
+import respx
+
+from intent_base._http import IntentBaseHttpClient
+from intent_base.errors import (
+    ProfileAlreadyRunningError,
+    ProfileNotFoundError,
+    RequestTimeoutError,
+    ServiceBadResponseError,
+    ServiceUnavailableError,
+)
+
+SERVICE = "http://127.0.0.1:17390"
+LAUNCH_URL = f"{SERVICE}/api/v1/profiles/profile_123/launch"
+
+LAUNCH_BODY = {
+    "profileId": "profile_123",
+    "status": "running",
+    "pid": 4242,
+    "cdpEndpoint": "ws://127.0.0.1:52341/devtools/browser/abc-123",
+    "devtoolsPort": 52341,
+    "userDataPath": "C:/data/profiles/profile_123/user_data",
+    "browserLogPath": "C:/data/profiles/profile_123/logs/browser.log",
+}
+
+
+@respx.mock
+def test_launch_profile_calls_correct_url_and_parses():
+    route = respx.post(LAUNCH_URL).mock(
+        return_value=httpx.Response(200, json=LAUNCH_BODY)
+    )
+    client = IntentBaseHttpClient(SERVICE)
+    meta = client.launch_profile("profile_123", extra_args=["--lang=en-US"])
+
+    assert route.called
+    request = route.calls.last.request
+    import json
+
+    assert json.loads(request.content) == {"extraArgs": ["--lang=en-US"]}
+    assert meta.profile_id == "profile_123"
+    assert meta.pid == 4242
+    assert meta.cdp_endpoint == "ws://127.0.0.1:52341/devtools/browser/abc-123"
+    assert meta.devtools_port == 52341
+
+
+@respx.mock
+def test_non_2xx_maps_to_typed_error():
+    respx.post(LAUNCH_URL).mock(
+        return_value=httpx.Response(
+            409, json={"code": "PROFILE_ALREADY_RUNNING", "message": "running"}
+        )
+    )
+    with pytest.raises(ProfileAlreadyRunningError) as exc:
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+    assert exc.value.code == "PROFILE_ALREADY_RUNNING"
+    assert exc.value.status == 409
+
+
+@respx.mock
+def test_not_found_maps_to_profile_not_found():
+    respx.post(LAUNCH_URL).mock(
+        return_value=httpx.Response(
+            404, json={"code": "PROFILE_NOT_FOUND", "message": "nope"}
+        )
+    )
+    with pytest.raises(ProfileNotFoundError):
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+
+
+@respx.mock
+def test_connection_error_maps_to_service_unavailable():
+    respx.post(LAUNCH_URL).mock(side_effect=httpx.ConnectError("refused"))
+    with pytest.raises(ServiceUnavailableError) as exc:
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+    assert exc.value.code == "SERVICE_UNAVAILABLE"
+
+
+@respx.mock
+def test_timeout_maps_to_request_timeout():
+    respx.post(LAUNCH_URL).mock(side_effect=httpx.ReadTimeout("slow"))
+    with pytest.raises(RequestTimeoutError) as exc:
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+    assert exc.value.code == "REQUEST_TIMEOUT"
+
+
+@respx.mock
+def test_invalid_json_2xx_maps_to_bad_response():
+    respx.post(LAUNCH_URL).mock(
+        return_value=httpx.Response(200, content=b"not json")
+    )
+    with pytest.raises(ServiceBadResponseError):
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+
+
+@respx.mock
+def test_error_status_without_body_maps_to_bad_response():
+    respx.post(LAUNCH_URL).mock(return_value=httpx.Response(500))
+    with pytest.raises(ServiceBadResponseError) as exc:
+        IntentBaseHttpClient(SERVICE).launch_profile("profile_123")
+    assert exc.value.status == 500
+
+
+def test_service_url_resolution_from_env(monkeypatch):
+    monkeypatch.setenv("INTENT_BASE_SERVICE_URL", "http://10.0.0.1:9999/")
+    client = IntentBaseHttpClient()
+    assert client.service_url == "http://10.0.0.1:9999"
+
+
+def test_timeout_resolution_from_env(monkeypatch):
+    monkeypatch.setenv("INTENT_BASE_TIMEOUT_MS", "5000")
+    client = IntentBaseHttpClient()
+    assert client.timeout_ms == 5000

intent_base_sdk-0.4.0/tests/test_errors.py

@@ -0,0 +1,41 @@
+from intent_base.errors import (
+    CdpConnectError,
+    IntentBaseError,
+    ProfileAlreadyRunningError,
+    ProfileNotFoundError,
+    ProxyCheckFailedError,
+    ServiceUnavailableError,
+    map_api_error,
+)
+
+
+def test_map_known_codes_to_typed_errors():
+    assert isinstance(map_api_error("PROFILE_NOT_FOUND", "x"), ProfileNotFoundError)
+    assert isinstance(
+        map_api_error("PROFILE_ALREADY_RUNNING", "x"), ProfileAlreadyRunningError
+    )
+    assert isinstance(map_api_error("PROXY_CHECK_FAILED", "x"), ProxyCheckFailedError)
+    assert isinstance(map_api_error("CDP_CONNECT_FAILED", "x"), CdpConnectError)
+    assert isinstance(
+        map_api_error("SERVICE_UNAVAILABLE", "x"), ServiceUnavailableError
+    )
+
+
+def test_profile_running_alias_maps_to_already_running():
+    assert isinstance(
+        map_api_error("PROFILE_RUNNING", "x"), ProfileAlreadyRunningError
+    )
+
+
+def test_unknown_code_falls_back_to_base_but_preserves_code():
+    err = map_api_error("SOME_NEW_CODE", "boom", 500, profile_id="p1")
+    assert isinstance(err, IntentBaseError)
+    assert err.code == "SOME_NEW_CODE"
+    assert err.message == "boom"
+    assert err.status == 500
+    assert err.profile_id == "p1"
+
+
+def test_error_str_is_message():
+    err = map_api_error("PROFILE_NOT_FOUND", "missing profile")
+    assert str(err) == "missing profile"