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

gl_browser_use/config.py

@@ -0,0 +1,169 @@
+"""Configuration model for :class:`BrowserUseClient`.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from openai.types.shared_params.chat_model import ChatModel
+from openai.types.shared_params.reasoning_effort import ReasoningEffort
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from gl_browser_use.errors import BrowserUseConfigurationError
+
+VisionDetailLevel = Literal["auto", "low", "high"]
+
+_SECRET_MARKER: dict[str, Any] = {"secret": True}
+
+
+class BrowserUseClientConfig(BaseModel):
+    """Typed runtime configuration for :class:`BrowserUseClient`."""
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True, validate_assignment=True)
+
+    llm_openai_api_key: str | None = Field(
+        default_factory=lambda: os.getenv("OPENAI_API_KEY"),
+        description="Primary LLM API key for browser-control reasoning.",
+        json_schema_extra=_SECRET_MARKER,
+    )
+    llm_openai_model: ChatModel | str = Field(
+        default="o3",
+        description="Primary model for browser-control reasoning.",
+    )
+    llm_openai_temperature: float | None = Field(
+        default=None,
+        description="Primary model temperature. Use None to defer to provider defaults.",
+    )
+    llm_openai_reasoning_effort: ReasoningEffort = Field(
+        default="low",
+        description="Primary reasoning intensity.",
+    )
+    llm_openai_base_url: str | None = Field(
+        default=None,
+        description="Override base URL for the primary LLM API (http/https only).",
+    )
+
+    page_extraction_llm_openai_api_key: str | None = Field(
+        default_factory=lambda: os.getenv("OPENAI_API_KEY"),
+        description="LLM API key for page extraction.",
+        json_schema_extra=_SECRET_MARKER,
+    )
+    page_extraction_llm_openai_model: ChatModel | str = Field(
+        default="gpt-5-mini",
+        description="Model for page extraction.",
+    )
+    page_extraction_llm_openai_temperature: float | None = Field(
+        default=None,
+        description="Extraction model temperature. Use None to defer to provider defaults.",
+    )
+    page_extraction_llm_openai_reasoning_effort: ReasoningEffort = Field(
+        default="minimal",
+        description="Extraction reasoning intensity.",
+    )
+    page_extraction_llm_openai_base_url: str | None = Field(
+        default=None,
+        description="Override base URL for the extraction LLM API (http/https only).",
+    )
+
+    extend_system_message: str | None = Field(
+        default=None,
+        description="Optional system prompt extension.",
+    )
+    vision_detail_level: VisionDetailLevel = Field(
+        default="auto",
+        description="Vision detail level for multimodal steps.",
+    )
+    llm_timeout_in_s: int | None = Field(
+        default=None,
+        gt=0,
+        description="Timeout for LLM calls, in seconds.",
+    )
+    step_timeout_in_s: int = Field(
+        default=180,
+        gt=0,
+        description="Timeout per browser step, in seconds.",
+    )
+
+    enable_cloud_sync: bool = Field(
+        default=False,
+        description="Whether browser-use cloud sync is enabled.",
+    )
+    logging_level: Literal["debug", "info", "warning", "error", "result"] = Field(
+        default="info",
+        description="Verbosity for browser-use internals.",
+    )
+    max_session_retries: int = Field(
+        default=2,
+        ge=0,
+        description="How many session recovery attempts to make after recoverable failures.",
+    )
+    session_retry_delay_in_s: float = Field(
+        default=3.0,
+        ge=0.0,
+        description="Delay between recoverable session retries.",
+    )
+
+    @field_validator("llm_openai_base_url", "page_extraction_llm_openai_base_url")
+    @classmethod
+    def _validate_supported_url(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        if "://" not in value:
+            raise ValueError("URL must include an explicit http:// or https:// scheme")
+        parsed = urlparse(value)
+        if parsed.scheme not in {"http", "https"}:
+            raise ValueError("URL scheme must be one of http, https")
+        if not parsed.netloc:
+            raise ValueError("URL must include a host")
+        return value
+
+    def validate(self, *, strict: bool = False) -> list[str]:
+        """Validate required runtime values.
+
+        Returns a list of field-level validation issues. If ``strict`` is
+        ``True``, raise :class:`BrowserUseConfigurationError` on any issues.
+        """
+        issues: list[str] = []
+        if not self.llm_openai_api_key:
+            issues.append("llm_openai_api_key is required to run the browser agent")
+        if not self.page_extraction_llm_openai_api_key:
+            issues.append("page_extraction_llm_openai_api_key is required for page extraction")
+
+        if self.llm_timeout_in_s is not None and self.llm_timeout_in_s <= 0:
+            issues.append("llm_timeout_in_s must be > 0 when set")
+        if self.step_timeout_in_s <= 0:
+            issues.append("step_timeout_in_s must be > 0")
+
+        if self.max_session_retries < 0:
+            issues.append("max_session_retries must be >= 0")
+        if self.session_retry_delay_in_s < 0:
+            issues.append("session_retry_delay_in_s must be >= 0")
+
+        if strict and issues:
+            raise BrowserUseConfigurationError(
+                "Invalid BrowserUseClientConfig",
+                details={"errors": issues, "config": self.redacted_dict()},
+            )
+
+        return issues
+
+    def redacted_dict(self, *, include_secrets: bool = False) -> dict[str, Any]:
+        """Return a config dictionary safe to log.
+
+        Fields marked with ``json_schema_extra={"secret": True}`` are replaced
+        with ``"***"`` unless ``include_secrets`` is ``True``.
+        """
+        data = self.model_dump()
+        if include_secrets:
+            return data
+        for name, field_info in type(self).model_fields.items():
+            extra = field_info.json_schema_extra
+            extra_dict = extra if isinstance(extra, dict) else {}
+            if extra_dict.get("secret") and data.get(name):
+                data[name] = "***"
+        return data

gl_browser_use/config.pyi

@@ -0,0 +1,42 @@
+from _typeshed import Incomplete
+from gl_browser_use.errors import BrowserUseConfigurationError as BrowserUseConfigurationError
+from openai.types.shared_params.chat_model import ChatModel
+from openai.types.shared_params.reasoning_effort import ReasoningEffort
+from pydantic import BaseModel
+from typing import Any, Literal
+
+VisionDetailLevel: Incomplete
+
+class BrowserUseClientConfig(BaseModel):
+    """Typed runtime configuration for :class:`BrowserUseClient`."""
+    model_config: Incomplete
+    llm_openai_api_key: str | None
+    llm_openai_model: ChatModel | str
+    llm_openai_temperature: float | None
+    llm_openai_reasoning_effort: ReasoningEffort
+    llm_openai_base_url: str | None
+    page_extraction_llm_openai_api_key: str | None
+    page_extraction_llm_openai_model: ChatModel | str
+    page_extraction_llm_openai_temperature: float | None
+    page_extraction_llm_openai_reasoning_effort: ReasoningEffort
+    page_extraction_llm_openai_base_url: str | None
+    extend_system_message: str | None
+    vision_detail_level: VisionDetailLevel
+    llm_timeout_in_s: int | None
+    step_timeout_in_s: int
+    enable_cloud_sync: bool
+    logging_level: Literal['debug', 'info', 'warning', 'error', 'result']
+    max_session_retries: int
+    session_retry_delay_in_s: float
+    def validate(self, *, strict: bool = False) -> list[str]:
+        """Validate required runtime values.
+
+        Returns a list of field-level validation issues. If ``strict`` is
+        ``True``, raise :class:`BrowserUseConfigurationError` on any issues.
+        """
+    def redacted_dict(self, *, include_secrets: bool = False) -> dict[str, Any]:
+        '''Return a config dictionary safe to log.
+
+        Fields marked with ``json_schema_extra={"secret": True}`` are replaced
+        with ``"***"`` unless ``include_secrets`` is ``True``.
+        '''

gl_browser_use/errors.py

@@ -0,0 +1,119 @@
+"""Errors for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+PACKAGE_NAME: Final[str] = "gl-browser-use"
+
+STEEL_EXTRA: Final[str] = "steel"
+MINIO_EXTRA: Final[str] = "minio"
+
+
+def install_hint(extra: str) -> str:
+    """Return a ``pip install`` hint for the given optional extra."""
+    return f"pip install {PACKAGE_NAME}[{extra}]"
+
+
+def _merge_details(base: dict[str, Any] | None, **extras: Any) -> dict[str, Any]:
+    """Merge ``base`` with ``extras`` into a new details dict, dropping ``None`` values."""
+    merged: dict[str, Any] = {k: v for k, v in (base or {}).items() if v is not None}
+    merged.update({k: v for k, v in extras.items() if v is not None})
+    return merged
+
+
+class BrowserUseSDKError(RuntimeError):
+    """Base exception for all SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+        origin: BaseException | None = None,
+    ) -> None:
+        """Initialize the error."""
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+        self.origin = origin
+
+    def __str__(self) -> str:
+        """Return the error message."""
+        if self.origin is not None:
+            return f"{self.message} (caused by {self.origin!s})"
+        return self.message
+
+
+class BrowserUseDependencyError(BrowserUseSDKError):
+    """Raised when required optional dependencies are unavailable."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        missing_dependency: str | None = None,
+        package_hint: str | None = None,
+        details: dict[str, Any] | None = None,
+        origin: BaseException | None = None,
+    ) -> None:
+        """Initialize the error."""
+        super().__init__(
+            message,
+            details=_merge_details(details, missing_dependency=missing_dependency, package_hint=package_hint),
+            origin=origin,
+        )
+        self.missing_dependency = missing_dependency
+        self.package_hint = package_hint
+
+
+class BrowserUseMissingDependencyError(BrowserUseDependencyError):
+    """Raised when an optional extra dependency is not installed."""
+
+
+class BrowserUseConfigurationError(BrowserUseSDKError):
+    """Raised when required configuration values are missing or invalid."""
+
+
+class BrowserUseExecutionError(BrowserUseSDKError):
+    """Raised when execution of a run fails."""
+
+
+class BrowserUseRetryExhaustedError(BrowserUseExecutionError):
+    """Raised when session retries are exhausted after recoverable errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        attempt: int,
+        max_attempts: int,
+        details: dict[str, Any] | None = None,
+        origin: BaseException | None = None,
+    ) -> None:
+        """Initialize the error."""
+        super().__init__(
+            message,
+            details=_merge_details(details, attempt=attempt, max_attempts=max_attempts),
+            origin=origin,
+        )
+        self.attempt = attempt
+        self.max_attempts = max_attempts
+
+
+__all__ = [
+    "MINIO_EXTRA",
+    "PACKAGE_NAME",
+    "STEEL_EXTRA",
+    "BrowserUseConfigurationError",
+    "BrowserUseDependencyError",
+    "BrowserUseExecutionError",
+    "BrowserUseMissingDependencyError",
+    "BrowserUseRetryExhaustedError",
+    "BrowserUseSDKError",
+    "install_hint",
+]

gl_browser_use/errors.pyi

@@ -0,0 +1,40 @@
+from _typeshed import Incomplete
+from typing import Any, Final
+
+__all__ = ['MINIO_EXTRA', 'PACKAGE_NAME', 'STEEL_EXTRA', 'BrowserUseConfigurationError', 'BrowserUseDependencyError', 'BrowserUseExecutionError', 'BrowserUseMissingDependencyError', 'BrowserUseRetryExhaustedError', 'BrowserUseSDKError', 'install_hint']
+
+PACKAGE_NAME: Final[str]
+STEEL_EXTRA: Final[str]
+MINIO_EXTRA: Final[str]
+
+def install_hint(extra: str) -> str:
+    """Return a ``pip install`` hint for the given optional extra."""
+
+class BrowserUseSDKError(RuntimeError):
+    """Base exception for all SDK errors."""
+    message: Incomplete
+    details: Incomplete
+    origin: Incomplete
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None, origin: BaseException | None = None) -> None:
+        """Initialize the error."""
+
+class BrowserUseDependencyError(BrowserUseSDKError):
+    """Raised when required optional dependencies are unavailable."""
+    missing_dependency: Incomplete
+    package_hint: Incomplete
+    def __init__(self, message: str, *, missing_dependency: str | None = None, package_hint: str | None = None, details: dict[str, Any] | None = None, origin: BaseException | None = None) -> None:
+        """Initialize the error."""
+
+class BrowserUseMissingDependencyError(BrowserUseDependencyError):
+    """Raised when an optional extra dependency is not installed."""
+class BrowserUseConfigurationError(BrowserUseSDKError):
+    """Raised when required configuration values are missing or invalid."""
+class BrowserUseExecutionError(BrowserUseSDKError):
+    """Raised when execution of a run fails."""
+
+class BrowserUseRetryExhaustedError(BrowserUseExecutionError):
+    """Raised when session retries are exhausted after recoverable errors."""
+    attempt: Incomplete
+    max_attempts: Incomplete
+    def __init__(self, message: str, *, attempt: int, max_attempts: int, details: dict[str, Any] | None = None, origin: BaseException | None = None) -> None:
+        """Initialize the error."""

gl_browser_use/events.py

@@ -0,0 +1,147 @@
+"""Event helpers for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from textwrap import shorten
+from typing import Any
+
+from gl_browser_use.models import BrowserUseStreamEvent
+from gl_browser_use.parsing import read_tool_call
+
+EVENT_ID = "default_thinking_id"
+TASK_COMPLETED_MESSAGE = "Task completed"
+PROCESSING_MESSAGE = "Working on your request..."
+STREAMING_MESSAGE = "Receive streaming URL"
+RECORDING_MESSAGE = "Receive recording URL"
+
+
+def build_activity_event(url: str, content: str) -> BrowserUseStreamEvent:
+    """Return an activity event carrying ``url`` in the standard iframe payload."""
+    return BrowserUseStreamEvent(
+        event_type="status_update",
+        content=content,
+        thinking_and_activity_info={
+            "data_type": "activity",
+            "id": EVENT_ID,
+            "data_value": json.dumps({"type": "iframe", "message": url}),
+        },
+        is_final=False,
+        tool_info=None,
+        metadata={"kind": "agent_thinking_step", "status": "running"},
+    )
+
+
+def build_thinking_event(marker: str, *, content: str, final: bool = False) -> BrowserUseStreamEvent:
+    """Return a thinking-marker event for ``thinking_start``/``thinking_end``/``thinking``."""
+    data_type = marker if marker in {"thinking_start", "thinking_end"} else "thinking"
+    payload: dict[str, Any] = {"data_type": data_type, "data_value": "", "id": EVENT_ID}
+    if data_type == "thinking":
+        payload["data_value"] = content
+    return BrowserUseStreamEvent(
+        event_type="status_update",
+        content=content,
+        thinking_and_activity_info=payload,
+        is_final=final,
+        tool_info={"tool_calls": []},
+        metadata={"kind": "agent_thinking_step", "status": "running"},
+    )
+
+
+def build_step_event(tool_calls: list[Any], content: str, *, is_final: bool) -> BrowserUseStreamEvent:
+    """Return a step event summarizing ``tool_calls`` with a fallback thinking narration."""
+    serialized: list[dict[str, Any]] = []
+    for call in tool_calls:
+        name, args, output = read_tool_call(call)
+        serialized.append({"name": name or "tool", "args": args, "output": output})
+
+    thinking = build_fallback_thinking_message(content, serialized)
+    return BrowserUseStreamEvent(
+        event_type="status_update",
+        content=content if not is_final else TASK_COMPLETED_MESSAGE,
+        thinking_and_activity_info={"data_type": "thinking", "data_value": thinking, "id": EVENT_ID},
+        is_final=is_final,
+        tool_info={"tool_calls": serialized, "status": "finished" if is_final else "running"},
+        metadata={"kind": "agent_thinking_step", "status": "finished" if is_final else "running"},
+    )
+
+
+def build_error_event(error_message: str, *, recording_url: str = "") -> BrowserUseStreamEvent:
+    """Return a terminal tool-result error event with optional ``recording_url``.
+
+    ``error_message`` is expected to be already summarized by the caller via
+    :func:`gl_browser_use.parsing.summarize_terminal_error`.
+    """
+    metadata: dict[str, Any] = {"kind": "agent_thinking_step", "status": "error"}
+    if recording_url:
+        metadata["recording_url"] = recording_url
+    return BrowserUseStreamEvent(
+        event_type="tool_result",
+        content=f"Error: {error_message}",
+        thinking_and_activity_info={
+            "data_type": "error",
+            "data_value": error_message,
+            "id": EVENT_ID,
+        },
+        is_final=True,
+        tool_info={"tool_calls": []},
+        metadata=metadata,
+    )
+
+
+def build_retry_event(attempt: int, max_attempts: int, reason: str) -> BrowserUseStreamEvent:
+    """Return a retry status event carrying attempt counters and the recoverable reason."""
+    content = f"Retrying after session disconnect ({attempt}/{max_attempts}): {reason}"
+    return BrowserUseStreamEvent(
+        event_type="status_update",
+        content=content,
+        thinking_and_activity_info={"data_type": "thinking", "data_value": content, "id": EVENT_ID},
+        is_final=False,
+        tool_info={"tool_calls": []},
+        metadata={"kind": "agent_thinking_step", "status": "running", "attempt": attempt, "max_attempts": max_attempts},
+    )
+
+
+def build_fallback_thinking_message(content: str, tool_calls: list[Any]) -> str:
+    """Build a fallback thinking narration that lists recent tool-call outputs."""
+    if not tool_calls:
+        return "**" + content + "**\n\n- Awaiting tool output"
+
+    lines = []
+    for call in tool_calls:
+        name, _, output = read_tool_call(call)
+        snippet = shorten(" ".join(output.split()), width=240, placeholder="…") if output.strip() else "running"
+        lines.append(f"- {name or 'tool'}: {snippet}")
+    return "**" + content + "**\n\n" + "\n".join(lines)
+
+
+def build_step_content(tool_calls: list[Any], is_done: bool) -> str:
+    """Return a user-visible content string for a step event based on ``tool_calls``."""
+    if is_done:
+        return TASK_COMPLETED_MESSAGE
+    if not tool_calls:
+        return PROCESSING_MESSAGE
+    names = [name for name, _, _ in (read_tool_call(call) for call in tool_calls) if name]
+    if names:
+        return f"Completed {', '.join(names)}"
+    return PROCESSING_MESSAGE
+
+
+__all__ = [
+    "EVENT_ID",
+    "PROCESSING_MESSAGE",
+    "RECORDING_MESSAGE",
+    "STREAMING_MESSAGE",
+    "TASK_COMPLETED_MESSAGE",
+    "build_activity_event",
+    "build_error_event",
+    "build_fallback_thinking_message",
+    "build_retry_event",
+    "build_step_content",
+    "build_step_event",
+    "build_thinking_event",
+]

gl_browser_use/events.pyi

@@ -0,0 +1,29 @@
+from gl_browser_use.models import BrowserUseStreamEvent
+from typing import Any
+
+__all__ = ['EVENT_ID', 'PROCESSING_MESSAGE', 'RECORDING_MESSAGE', 'STREAMING_MESSAGE', 'TASK_COMPLETED_MESSAGE', 'build_activity_event', 'build_error_event', 'build_fallback_thinking_message', 'build_retry_event', 'build_step_content', 'build_step_event', 'build_thinking_event']
+
+EVENT_ID: str
+TASK_COMPLETED_MESSAGE: str
+PROCESSING_MESSAGE: str
+STREAMING_MESSAGE: str
+RECORDING_MESSAGE: str
+
+def build_activity_event(url: str, content: str) -> BrowserUseStreamEvent:
+    """Return an activity event carrying ``url`` in the standard iframe payload."""
+def build_thinking_event(marker: str, *, content: str, final: bool = False) -> BrowserUseStreamEvent:
+    """Return a thinking-marker event for ``thinking_start``/``thinking_end``/``thinking``."""
+def build_step_event(tool_calls: list[Any], content: str, *, is_final: bool) -> BrowserUseStreamEvent:
+    """Return a step event summarizing ``tool_calls`` with a fallback thinking narration."""
+def build_error_event(error_message: str, *, recording_url: str = '') -> BrowserUseStreamEvent:
+    """Return a terminal tool-result error event with optional ``recording_url``.
+
+    ``error_message`` is expected to be already summarized by the caller via
+    :func:`gl_browser_use.parsing.summarize_terminal_error`.
+    """
+def build_retry_event(attempt: int, max_attempts: int, reason: str) -> BrowserUseStreamEvent:
+    """Return a retry status event carrying attempt counters and the recoverable reason."""
+def build_fallback_thinking_message(content: str, tool_calls: list[Any]) -> str:
+    """Build a fallback thinking narration that lists recent tool-call outputs."""
+def build_step_content(tool_calls: list[Any], is_done: bool) -> str:
+    """Return a user-visible content string for a step event based on ``tool_calls``."""

gl_browser_use/infrastructure/__init__.py

@@ -0,0 +1,39 @@
+"""Browser infrastructure abstractions and implementations.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from gl_browser_use.errors import STEEL_EXTRA, BrowserUseMissingDependencyError, install_hint
+from gl_browser_use.infrastructure.base import BrowserInfrastructure, BrowserInfrastructureContext
+
+__all__ = [
+    "BrowserInfrastructure",
+    "BrowserInfrastructureContext",
+    "SteelBrowserInfrastructure",
+]
+
+
+def __getattr__(name: str):
+    """Lazy-load infrastructure providers behind optional dependencies."""
+    if name == "SteelBrowserInfrastructure":
+        try:
+            from gl_browser_use.infrastructure.steel import SteelBrowserInfrastructure
+        except ImportError as exc:
+            hint = install_hint(STEEL_EXTRA)
+            raise BrowserUseMissingDependencyError(
+                f"The Steel infrastructure provider requires optional dependencies that are not installed. "
+                f"Install them via `{hint}`.",
+                missing_dependency="steel-sdk",
+                package_hint=hint,
+                origin=exc,
+            ) from exc
+        return SteelBrowserInfrastructure
+
+    raise AttributeError(f"module 'gl_browser_use.infrastructure' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

gl_browser_use/infrastructure/__init__.pyi

@@ -0,0 +1,6 @@
+from gl_browser_use.infrastructure.base import BrowserInfrastructure as BrowserInfrastructure, BrowserInfrastructureContext as BrowserInfrastructureContext
+
+__all__ = ['BrowserInfrastructure', 'BrowserInfrastructureContext', 'SteelBrowserInfrastructure']
+
+# Names in __all__ with no definition:
+#   SteelBrowserInfrastructure