gl-browser-use-binary 0.0.0b5__py3-none-any.whl

gl_browser_use/client.py

@@ -0,0 +1,639 @@
+"""Client implementation for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import dataclasses
+import inspect
+import logging
+import os
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Any
+
+from browser_use import Agent
+from browser_use.browser import BrowserSession
+from browser_use.llm import ChatOpenAI
+from browser_use.logging_config import setup_logging
+from bubus import EventBus
+from openai.types.shared_params.chat_model import ChatModel
+from openai.types.shared_params.reasoning_effort import ReasoningEffort
+
+from gl_browser_use.config import BrowserUseClientConfig
+from gl_browser_use.errors import (
+    BrowserUseConfigurationError,
+    BrowserUseExecutionError,
+    BrowserUseRetryExhaustedError,
+)
+from gl_browser_use.events import (
+    RECORDING_MESSAGE,
+    STREAMING_MESSAGE,
+    TASK_COMPLETED_MESSAGE,
+    build_activity_event,
+    build_error_event,
+    build_retry_event,
+    build_step_content,
+    build_step_event,
+    build_thinking_event,
+)
+from gl_browser_use.infrastructure.base import (
+    BrowserInfrastructure,
+    BrowserInfrastructureContext,
+)
+from gl_browser_use.models import (
+    BrowserUseRunResult,
+    BrowserUseRunStatus,
+    BrowserUseStreamEvent,
+)
+from gl_browser_use.parsing import (
+    coerce_string,
+    extract_final_output,
+    extract_tool_calls,
+    summarize_terminal_error,
+    validate_structured_data_output,
+)
+from gl_browser_use.session_errors import is_recoverable_session_error
+from gl_browser_use.storage.base import ObjectStorage
+
+logger = logging.getLogger(__name__)
+
+_AGENT_EVENTBUS_STOP_TIMEOUT_IN_S = 5.0
+
+EmitCallable = Callable[[BrowserUseStreamEvent | None], Awaitable[None] | None]
+
+
+async def _maybe_await(value: Any) -> None:
+    if inspect.isawaitable(value):
+        await value
+
+
+def recording_metadata(
+    *,
+    infrastructure: BrowserInfrastructure | None,
+    storage: ObjectStorage | None,
+    browser_context: BrowserInfrastructureContext | None,
+) -> dict[str, Any]:
+    """Return recording status metadata aligned with implementation behavior."""
+    if infrastructure is None:
+        return {
+            "recording_status": "disabled",
+            "recording_message": "Browser infrastructure is not configured.",
+        }
+
+    if not infrastructure.supports_recording:
+        return {
+            "recording_status": "unsupported",
+            "recording_message": f"Infrastructure '{infrastructure.provider}' does not support recording.",
+        }
+
+    if storage is None:
+        return {
+            "recording_status": "disabled",
+            "recording_message": "Object storage is not configured.",
+        }
+
+    if not storage.is_available:
+        return {
+            "recording_status": "unavailable",
+            "recording_message": f"Object storage {storage.provider} is not available: {getattr(storage, 'last_error', None)}",
+        }
+
+    if browser_context is None:
+        return {
+            "recording_status": "disabled",
+            "recording_message": "Browser context is not available.",
+        }
+
+    return {
+        "recording_status": "scheduled",
+        "recording_message": "Recording has been scheduled as a background task.",
+    }
+
+
+class BrowserUseClient:
+    """Facade for running browser automation tasks.
+
+    Note: ``infrastructure`` and ``storage`` attributes are read by ``run``/
+    ``run_once``/``run_sync`` on each call. Swapping them while a run is in
+    flight is undefined behavior.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: BrowserUseClientConfig,
+        infrastructure: BrowserInfrastructure | None = None,
+        storage: ObjectStorage | None = None,
+    ) -> None:
+        """Initialize the client."""
+        config.validate(strict=True)
+        self.config = config
+        self.infrastructure = infrastructure
+        self.storage = storage
+
+    async def run(self, task: str) -> AsyncGenerator[BrowserUseStreamEvent, None]:
+        """Run the client."""
+        queue: asyncio.Queue[BrowserUseStreamEvent | None] = asyncio.Queue()
+        emit_lock = asyncio.Lock()
+
+        async def emit(event: BrowserUseStreamEvent | None) -> None:
+            async with emit_lock:
+                await queue.put(event)
+
+        async def run_and_signal() -> BrowserUseRunResult:
+            try:
+                return await self._run_with_events(task, emit)
+            finally:
+                await emit(None)
+
+        run_task = asyncio.create_task(run_and_signal())
+        try:
+            while True:
+                event = await queue.get()
+                if event is None:
+                    break
+                yield event
+            await run_task
+        finally:
+            if not run_task.done():
+                run_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await run_task
+
+    async def run_once(self, task: str) -> BrowserUseRunResult:
+        """Run the client once and return a single aggregated result.
+
+        Raises:
+        ------
+        BrowserUseExecutionError
+            When the task input is invalid.
+        BrowserUseConfigurationError
+            When required configuration is missing.
+        BrowserUseRetryExhaustedError
+            When all recoverable session retries are exhausted.
+        """
+        events: list[BrowserUseStreamEvent] = []
+
+        async def emit(event: BrowserUseStreamEvent | None) -> None:
+            if event is not None:
+                events.append(event)
+
+        result = await self._run_with_events(task, emit)
+        return dataclasses.replace(result, events=events)
+
+    def run_sync(self, task: str) -> BrowserUseRunResult:
+        """Run the client synchronously.
+
+        Raises:
+        ------
+        BrowserUseExecutionError
+            When invoked from a thread that already has a running event loop,
+            or when task validation fails.
+        BrowserUseConfigurationError
+            When required configuration is missing.
+        BrowserUseRetryExhaustedError
+            When all recoverable session retries are exhausted.
+        """
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            raise BrowserUseExecutionError(
+                "run_sync must not be called from a running event loop"
+            )
+        return asyncio.run(self.run_once(task))
+
+    async def _run_with_events(
+        self, task: str, emit: EmitCallable
+    ) -> BrowserUseRunResult:
+        task = self._validate_task(task)
+        max_attempts = self.config.max_session_retries + 1
+
+        for attempt in range(1, max_attempts + 1):
+            try:
+                result = await self._run_single_attempt(task, emit, attempt=attempt)
+                await _maybe_await(emit(None))
+                return dataclasses.replace(
+                    result,
+                    metadata={**result.metadata, "max_attempts": max_attempts},
+                )
+            except BrowserUseExecutionError as exc:
+                raw_reason = str(exc)
+                display_reason = summarize_terminal_error(raw_reason)
+                recoverable = is_recoverable_session_error(raw_reason)
+
+                if recoverable and attempt < max_attempts:
+                    await _maybe_await(
+                        emit(build_retry_event(attempt, max_attempts, display_reason))
+                    )
+                    delay = max(0.0, self.config.session_retry_delay_in_s)
+                    if delay:
+                        await asyncio.sleep(delay)
+                    continue
+
+                details = exc.details if isinstance(exc.details, dict) else {}
+                recording_url_from_details = coerce_string(details.get("recording_url"))
+                resolved_recording_url = (
+                    recording_url_from_details
+                    or self._resolve_recording_url_from_details(details)
+                )
+
+                await _maybe_await(
+                    emit(
+                        build_error_event(
+                            display_reason, recording_url=resolved_recording_url or ""
+                        )
+                    )
+                )
+                await _maybe_await(emit(None))
+
+                if recoverable:
+                    raise BrowserUseRetryExhaustedError(
+                        f"Session retries exhausted after {max_attempts} attempts: {display_reason}",
+                        attempt=attempt,
+                        max_attempts=max_attempts,
+                        details={
+                            "streaming_url": details.get("streaming_url"),
+                            "recording_url": resolved_recording_url,
+                        },
+                        origin=exc,
+                    ) from exc
+
+                return self._build_terminal_result(
+                    task=task,
+                    attempt=attempt,
+                    max_attempts=max_attempts,
+                    reason=display_reason,
+                    details=details,
+                    resolved_recording_url=resolved_recording_url,
+                )
+            except Exception as exc:
+                display_reason = summarize_terminal_error(str(exc))
+                await _maybe_await(emit(build_error_event(display_reason)))
+                await _maybe_await(emit(None))
+                return self._build_terminal_result(
+                    task=task,
+                    attempt=attempt,
+                    max_attempts=max_attempts,
+                    reason=display_reason,
+                    details={},
+                    resolved_recording_url=None,
+                )
+
+        # Defensive: the loop always returns or raises; this guard keeps
+        # type-checkers happy about the return contract.
+        await _maybe_await(emit(None))
+        raise BrowserUseRetryExhaustedError(
+            "run attempt loop exhausted unexpectedly",
+            attempt=max_attempts,
+            max_attempts=max_attempts,
+        )
+
+    def _build_terminal_result(
+        self,
+        *,
+        task: str,
+        attempt: int,
+        max_attempts: int,
+        reason: str,
+        details: dict[str, Any],
+        resolved_recording_url: str | None,
+    ) -> BrowserUseRunResult:
+        """Build a terminal error :class:`BrowserUseRunResult` from attempt metadata.
+
+        Note: when the triggering exception was not a :class:`BrowserUseExecutionError`,
+        ``details`` is empty and browser context cannot be recovered. In that case,
+        emit ``recording_status="unknown"`` to avoid misleadingly reporting
+        ``"disabled"`` when a recording side effect may still have been started.
+        """
+        browser_context: BrowserInfrastructureContext | None = None
+        streaming_url: str | None = None
+
+        browser_context_candidate = details.get("browser_context")
+        if isinstance(browser_context_candidate, BrowserInfrastructureContext):
+            browser_context = browser_context_candidate
+
+        streaming_url_candidate = details.get("streaming_url")
+        if streaming_url_candidate is not None:
+            streaming_url = coerce_string(streaming_url_candidate)
+
+        metadata = recording_metadata(
+            infrastructure=self.infrastructure,
+            storage=self.storage,
+            browser_context=browser_context,
+        )
+
+        if (
+            self.infrastructure is not None
+            and self.storage is not None
+            and browser_context is None
+            and details == {}
+            and metadata.get("recording_status") == "disabled"
+            and metadata.get("recording_message") == "Browser context is not available."
+        ):
+            metadata.update(
+                {
+                    "recording_status": "unknown",
+                    "recording_message": "Recording status could not be determined from terminal error context.",
+                }
+            )
+
+        return BrowserUseRunResult(
+            status="error",
+            task=task,
+            final_output="",
+            session_id=browser_context.session_id
+            if browser_context is not None
+            else None,
+            streaming_url=streaming_url,
+            recording_url=resolved_recording_url,
+            steps=0,
+            error=reason,
+            events=[],
+            metadata={
+                "attempt": attempt,
+                "max_attempts": max_attempts,
+                **metadata,
+            },
+        )
+
+    def _resolve_recording_url_from_details(
+        self, details: dict[str, Any] | Any
+    ) -> str | None:
+        if not isinstance(details, dict):
+            return None
+        candidate = details.get("browser_context")
+        if not isinstance(candidate, BrowserInfrastructureContext):
+            return None
+        if not self._can_record(candidate):
+            return None
+        assert self.infrastructure is not None
+        url = self.infrastructure.resolve_recording_url(
+            session_id=candidate.session_id, storage=self.storage
+        )
+        return coerce_string(url) if url is not None else None
+
+    async def _run_single_attempt(
+        self, task: str, emit: EmitCallable, *, attempt: int
+    ) -> BrowserUseRunResult:
+        if not self.config.llm_openai_api_key:
+            raise BrowserUseConfigurationError(
+                "llm_openai_api_key is required for browser execution."
+            )
+        if not self.config.page_extraction_llm_openai_api_key:
+            raise BrowserUseConfigurationError(
+                "page_extraction_llm_openai_api_key is required for extraction."
+            )
+
+        if self.infrastructure is None:
+            logger.debug("Browser infrastructure is not configured.")
+        if self.storage is None:
+            logger.debug("Object storage is not configured.")
+
+        if self.storage is not None and not self.storage.is_available:
+            logger.debug(
+                "Object storage is not available: %s",
+                getattr(self.storage, "last_error", None),
+            )
+
+        # NOTE: browser-use reads these variables at module import / setup time.
+        # Writing them here is a process-global side effect; concurrent
+        # BrowserUseClient instances configured with different values will race.
+        os.environ["BROWSER_USE_CLOUD_SYNC"] = (
+            "true" if self.config.enable_cloud_sync else "false"
+        )
+        os.environ["BROWSER_USE_LOGGING_LEVEL"] = self.config.logging_level
+        with contextlib.suppress(Exception):
+            setup_logging(log_level=self.config.logging_level, force_setup=True)
+
+        browser_context = None
+        browser_session = None
+        agent = None
+        streaming_url = None
+        recording_url = None
+        step_count = 0
+        status: BrowserUseRunStatus = "error"
+
+        def _build_execution_error(
+            message: str, *, origin: BaseException | None = None
+        ) -> BrowserUseExecutionError:
+            details = {
+                "browser_context": browser_context,
+                "streaming_url": streaming_url,
+                "recording_url": recording_url,
+            }
+            return BrowserUseExecutionError(message, details=details, origin=origin)
+
+        try:
+            if self.infrastructure is not None:
+                browser_context = await self.infrastructure.create_session()
+                streaming_url = coerce_string(browser_context.streaming_url)
+                if streaming_url:
+                    await _maybe_await(
+                        emit(build_activity_event(streaming_url, STREAMING_MESSAGE))
+                    )
+
+                cdp_url = self.infrastructure.cdp_url(
+                    session_id=browser_context.session_id
+                )
+                browser_session = BrowserSession(cdp_url=cdp_url)
+                # TODO(upstream: browser_use): `_owns_browser_resources` is a private
+                # attribute of BrowserSession; if it is renamed in 0.12+ this flag
+                # will silently become a no-op.
+                with contextlib.suppress(Exception):
+                    setattr(browser_session, "_owns_browser_resources", True)
+
+            llm = self._build_llm(
+                model=self.config.llm_openai_model,
+                reasoning_effort=self.config.llm_openai_reasoning_effort,
+                temperature=self.config.llm_openai_temperature,
+                api_key=self.config.llm_openai_api_key,
+                base_url=self.config.llm_openai_base_url,
+            )
+            page_extraction_llm = self._build_llm(
+                model=self.config.page_extraction_llm_openai_model,
+                reasoning_effort=self.config.page_extraction_llm_openai_reasoning_effort,
+                temperature=self.config.page_extraction_llm_openai_temperature,
+                api_key=self.config.page_extraction_llm_openai_api_key,
+                base_url=self.config.page_extraction_llm_openai_base_url,
+            )
+
+            agent = Agent(
+                task=task,
+                llm=llm,
+                page_extraction_llm=page_extraction_llm,
+                browser_session=browser_session,
+                extend_system_message=self.config.extend_system_message,
+                vision_detail_level=self.config.vision_detail_level,
+                llm_timeout=self.config.llm_timeout_in_s,
+                step_timeout=self.config.step_timeout_in_s,
+            )
+
+            if browser_session is not None:
+                with contextlib.suppress(Exception):
+                    await browser_session.start()
+
+            while True:
+                try:
+                    is_done, _ = await agent.take_step()
+                    step_count += 1
+                except Exception as exc:
+                    raise _build_execution_error(
+                        f"Error in step execution: {exc}", origin=exc
+                    ) from exc
+
+                tool_calls = extract_tool_calls(agent)
+                extraction_error = validate_structured_data_output(tool_calls)
+                if extraction_error:
+                    raise _build_execution_error(extraction_error)
+
+                step_content = build_step_content(tool_calls, is_done=is_done)
+                step_event = build_step_event(
+                    tool_calls, step_content, is_final=is_done
+                )
+
+                if is_done:
+                    await _maybe_await(emit(step_event))
+                    status = "success"
+                    break
+
+                await _maybe_await(
+                    emit(
+                        build_thinking_event("thinking_start", content="Thinking start")
+                    )
+                )
+                await _maybe_await(emit(step_event))
+                await _maybe_await(
+                    emit(build_thinking_event("thinking_end", content="Thinking end"))
+                )
+
+            final_output = extract_final_output(agent)
+            if not final_output:
+                final_output = TASK_COMPLETED_MESSAGE
+
+            if self._can_record(browser_context):
+                assert self.infrastructure is not None
+                recording_url = self.infrastructure.resolve_recording_url(
+                    session_id=browser_context.session_id, storage=self.storage
+                )
+                if recording_url:
+                    await _maybe_await(
+                        emit(build_activity_event(recording_url, RECORDING_MESSAGE))
+                    )
+
+            metadata = recording_metadata(
+                infrastructure=self.infrastructure,
+                storage=self.storage,
+                browser_context=browser_context,
+            )
+            return BrowserUseRunResult(
+                status=status,
+                task=task,
+                final_output=final_output,
+                session_id=browser_context.session_id
+                if browser_context is not None
+                else None,
+                streaming_url=streaming_url,
+                recording_url=recording_url,
+                steps=step_count,
+                error=None,
+                events=[],
+                metadata={
+                    "attempt": attempt,
+                    **metadata,
+                },
+            )
+        finally:
+            if self._can_record(browser_context):
+                assert self.infrastructure is not None
+                self.infrastructure.schedule_recording(
+                    browser_context, storage=self.storage
+                )
+
+            if agent is not None:
+                agent_eventbus: EventBus | None = getattr(agent, "eventbus", None)
+                if agent_eventbus is not None:
+                    try:
+                        await agent_eventbus.stop(
+                            clear=True, timeout=_AGENT_EVENTBUS_STOP_TIMEOUT_IN_S
+                        )
+                    except Exception as exc:
+                        logger.debug(
+                            "Failed to stop agent event bus during cleanup: %s",
+                            exc,
+                            exc_info=True,
+                        )
+                try:
+                    await agent.close()
+                except Exception as exc:
+                    logger.debug(
+                        "Failed to close agent during cleanup: %s", exc, exc_info=True
+                    )
+            elif browser_session is not None:
+                try:
+                    await browser_session.kill()
+                except Exception as exc:
+                    logger.debug(
+                        "Failed to stop browser session during cleanup: %s",
+                        exc,
+                        exc_info=True,
+                    )
+
+            if self.infrastructure is not None and browser_context is not None:
+                try:
+                    await self.infrastructure.release_session(browser_context)
+                except Exception as exc:
+                    logger.debug(
+                        "Failed to release browser infrastructure session %s during cleanup: %s",
+                        browser_context.session_id,
+                        exc,
+                        exc_info=True,
+                    )
+
+    def _build_llm(
+        self,
+        *,
+        model: ChatModel | str,
+        reasoning_effort: ReasoningEffort,
+        temperature: float | None,
+        api_key: str,
+        base_url: str | None,
+    ) -> ChatOpenAI:
+        llm_kwargs: dict[str, Any] = {
+            "model": model,
+            "reasoning_effort": reasoning_effort,
+            "api_key": api_key,
+            "base_url": base_url,
+        }
+        if self._supports_tunable_params(model):
+            llm_kwargs["temperature"] = temperature
+        else:
+            llm_kwargs["temperature"] = None
+            llm_kwargs["frequency_penalty"] = None
+        return ChatOpenAI(**llm_kwargs)
+
+    def _supports_tunable_params(self, model: ChatModel | str) -> bool:
+        model_name = coerce_string(model).lower()
+        if model_name.startswith("gpt-5"):
+            return False
+        short_name = model_name.split("-", 1)[0]
+        return not (short_name.startswith("o") and short_name[1:].isdigit())
+
+    def _can_record(self, browser_context: BrowserInfrastructureContext | None) -> bool:
+        return self.infrastructure is not None and self.infrastructure.can_record(
+            browser_context, self.storage
+        )
+
+    @staticmethod
+    def _validate_task(task: str) -> str:
+        if not isinstance(task, str):
+            raise BrowserUseExecutionError("task must be a non-empty string")
+        value = task.strip()
+        if not value:
+            raise BrowserUseExecutionError("task must be a non-empty string")
+        return value

gl_browser_use/client.pyi

@@ -0,0 +1,57 @@
+from _typeshed import Incomplete
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from gl_browser_use.config import BrowserUseClientConfig as BrowserUseClientConfig
+from gl_browser_use.errors import BrowserUseConfigurationError as BrowserUseConfigurationError, BrowserUseExecutionError as BrowserUseExecutionError, BrowserUseRetryExhaustedError as BrowserUseRetryExhaustedError
+from gl_browser_use.events import RECORDING_MESSAGE as RECORDING_MESSAGE, STREAMING_MESSAGE as STREAMING_MESSAGE, TASK_COMPLETED_MESSAGE as TASK_COMPLETED_MESSAGE, build_activity_event as build_activity_event, build_error_event as build_error_event, build_retry_event as build_retry_event, build_step_content as build_step_content, build_step_event as build_step_event, build_thinking_event as build_thinking_event
+from gl_browser_use.infrastructure.base import BrowserInfrastructure as BrowserInfrastructure, BrowserInfrastructureContext as BrowserInfrastructureContext
+from gl_browser_use.models import BrowserUseRunResult as BrowserUseRunResult, BrowserUseRunStatus as BrowserUseRunStatus, BrowserUseStreamEvent as BrowserUseStreamEvent
+from gl_browser_use.parsing import coerce_string as coerce_string, extract_final_output as extract_final_output, extract_tool_calls as extract_tool_calls, summarize_terminal_error as summarize_terminal_error, validate_structured_data_output as validate_structured_data_output
+from gl_browser_use.session_errors import is_recoverable_session_error as is_recoverable_session_error
+from gl_browser_use.storage.base import ObjectStorage as ObjectStorage
+from typing import Any
+
+logger: Incomplete
+EmitCallable = Callable[[BrowserUseStreamEvent | None], Awaitable[None] | None]
+
+def recording_metadata(*, infrastructure: BrowserInfrastructure | None, storage: ObjectStorage | None, browser_context: BrowserInfrastructureContext | None) -> dict[str, Any]:
+    """Return recording status metadata aligned with implementation behavior."""
+
+class BrowserUseClient:
+    """Facade for running browser automation tasks.
+
+    Note: ``infrastructure`` and ``storage`` attributes are read by ``run``/
+    ``run_once``/``run_sync`` on each call. Swapping them while a run is in
+    flight is undefined behavior.
+    """
+    config: Incomplete
+    infrastructure: Incomplete
+    storage: Incomplete
+    def __init__(self, *, config: BrowserUseClientConfig, infrastructure: BrowserInfrastructure | None = None, storage: ObjectStorage | None = None) -> None:
+        """Initialize the client."""
+    async def run(self, task: str) -> AsyncGenerator[BrowserUseStreamEvent, None]:
+        """Run the client."""
+    async def run_once(self, task: str) -> BrowserUseRunResult:
+        """Run the client once and return a single aggregated result.
+
+        Raises:
+        ------
+        BrowserUseExecutionError
+            When the task input is invalid.
+        BrowserUseConfigurationError
+            When required configuration is missing.
+        BrowserUseRetryExhaustedError
+            When all recoverable session retries are exhausted.
+        """
+    def run_sync(self, task: str) -> BrowserUseRunResult:
+        """Run the client synchronously.
+
+        Raises:
+        ------
+        BrowserUseExecutionError
+            When invoked from a thread that already has a running event loop,
+            or when task validation fails.
+        BrowserUseConfigurationError
+            When required configuration is missing.
+        BrowserUseRetryExhaustedError
+            When all recoverable session retries are exhausted.
+        """