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

gl_browser_use/infrastructure/base.py

@@ -0,0 +1,103 @@
+"""Browser infrastructure abstractions for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from gl_browser_use.storage.base import ObjectStorage
+
+VIDEO_FILE_NAME_PREFIX = "session_"
+
+ClientType = TypeVar("ClientType")
+SessionType = TypeVar("SessionType")
+
+
+@dataclass
+class BrowserInfrastructureContext(Generic[ClientType, SessionType]):
+    """Runtime context for an active browser infrastructure session."""
+
+    client: ClientType
+    session: SessionType
+    session_id: str
+    streaming_url: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class BrowserInfrastructure(ABC, Generic[ClientType, SessionType]):
+    """Abstract contract for browser infrastructure providers.
+
+    Provider-specific configuration (API keys, endpoints, timeouts) belongs to
+    the concrete subclass; this base only defines the behavioral surface.
+    """
+
+    @property
+    @abstractmethod
+    def provider(self) -> str:
+        """Return the human-readable infrastructure provider name."""
+
+    @property
+    def supports_recording(self) -> bool:
+        """Whether this infrastructure can produce session recordings."""
+        return False
+
+    @abstractmethod
+    async def create_session(self) -> BrowserInfrastructureContext[ClientType, SessionType]:
+        """Create a new browser infrastructure session and return the active context."""
+
+    @abstractmethod
+    async def release_session(self, context: BrowserInfrastructureContext[ClientType, SessionType]) -> None:
+        """Release or dispose browser infrastructure session resources."""
+
+    @abstractmethod
+    def cdp_url(self, session_id: str) -> str:
+        """Build a CDP endpoint URL for the provided browser infrastructure session ID."""
+
+    def recording_filename(self, session_id: str) -> str:
+        """Return the preferred recording object name for the provided browser infrastructure session ID."""
+        return f"{VIDEO_FILE_NAME_PREFIX}{session_id}.mp4"
+
+    def resolve_recording_url(self, session_id: str, storage: ObjectStorage | None) -> str | None:
+        """Resolve a recording URL from storage without scheduling any new work."""
+        if storage is None or not storage.is_available or not session_id:
+            return None
+        return storage.get_file_url(self.recording_filename(session_id))
+
+    def can_record(
+        self,
+        context: BrowserInfrastructureContext[ClientType, SessionType] | None,
+        storage: ObjectStorage | None,
+    ) -> bool:
+        """Return True when an active recording can be produced for ``context``.
+
+        This encapsulates the "recording is supported, a live context exists,
+        and storage is available" check that clients use before scheduling a
+        recording or resolving a recording URL.
+        """
+        return (
+            self.supports_recording
+            and context is not None
+            and bool(getattr(context, "session_id", ""))
+            and storage is not None
+            and storage.is_available
+        )
+
+    @abstractmethod
+    def schedule_recording(
+        self,
+        context: BrowserInfrastructureContext[ClientType, SessionType],
+        storage: ObjectStorage | None,
+    ) -> None:
+        """Optionally schedule background recording for the provided context."""
+
+
+__all__ = [
+    "BrowserInfrastructure",
+    "BrowserInfrastructureContext",
+    "VIDEO_FILE_NAME_PREFIX",
+]

gl_browser_use/infrastructure/base.pyi

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from gl_browser_use.storage.base import ObjectStorage
+from typing import Any, Generic, TypeVar
+
+__all__ = ['BrowserInfrastructure', 'BrowserInfrastructureContext', 'VIDEO_FILE_NAME_PREFIX']
+
+VIDEO_FILE_NAME_PREFIX: str
+ClientType = TypeVar('ClientType')
+SessionType = TypeVar('SessionType')
+
+@dataclass
+class BrowserInfrastructureContext(Generic[ClientType, SessionType]):
+    """Runtime context for an active browser infrastructure session."""
+    client: ClientType
+    session: SessionType
+    session_id: str
+    streaming_url: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+class BrowserInfrastructure(ABC, Generic[ClientType, SessionType]):
+    """Abstract contract for browser infrastructure providers.
+
+    Provider-specific configuration (API keys, endpoints, timeouts) belongs to
+    the concrete subclass; this base only defines the behavioral surface.
+    """
+    @property
+    @abstractmethod
+    def provider(self) -> str:
+        """Return the human-readable infrastructure provider name."""
+    @property
+    def supports_recording(self) -> bool:
+        """Whether this infrastructure can produce session recordings."""
+    @abstractmethod
+    async def create_session(self) -> BrowserInfrastructureContext[ClientType, SessionType]:
+        """Create a new browser infrastructure session and return the active context."""
+    @abstractmethod
+    async def release_session(self, context: BrowserInfrastructureContext[ClientType, SessionType]) -> None:
+        """Release or dispose browser infrastructure session resources."""
+    @abstractmethod
+    def cdp_url(self, session_id: str) -> str:
+        """Build a CDP endpoint URL for the provided browser infrastructure session ID."""
+    def recording_filename(self, session_id: str) -> str:
+        """Return the preferred recording object name for the provided browser infrastructure session ID."""
+    def resolve_recording_url(self, session_id: str, storage: ObjectStorage | None) -> str | None:
+        """Resolve a recording URL from storage without scheduling any new work."""
+    def can_record(self, context: BrowserInfrastructureContext[ClientType, SessionType] | None, storage: ObjectStorage | None) -> bool:
+        '''Return True when an active recording can be produced for ``context``.
+
+        This encapsulates the "recording is supported, a live context exists,
+        and storage is available" check that clients use before scheduling a
+        recording or resolving a recording URL.
+        '''
+    @abstractmethod
+    def schedule_recording(self, context: BrowserInfrastructureContext[ClientType, SessionType], storage: ObjectStorage | None) -> None:
+        """Optionally schedule background recording for the provided context."""

gl_browser_use/infrastructure/steel.py

@@ -0,0 +1,296 @@
+"""Steel-backed browser infrastructure for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import shutil
+import tempfile
+import threading
+import time
+from io import BufferedWriter
+from pathlib import Path
+from urllib.parse import urljoin
+
+import requests
+from steel import Steel
+from steel.types.session import Session
+
+from gl_browser_use.errors import BrowserUseConfigurationError
+from gl_browser_use.infrastructure.base import (
+    VIDEO_FILE_NAME_PREFIX,
+    BrowserInfrastructure,
+    BrowserInfrastructureContext,
+)
+from gl_browser_use.storage.base import ObjectStorage
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_STEEL_BASE_URL = "https://api.steel.dev"
+DEFAULT_STEEL_WS_URL = "wss://connect.steel.dev"
+DEFAULT_STEEL_TIMEOUT_IN_MS = 600_000
+
+MANIFEST_TEMP_SUFFIX = ".m3u8"
+
+
+class _SteelSessionRecorder:
+    """Capture Steel HLS sessions and upload recordings to object storage."""
+
+    def __init__(self, base_url: str, api_key: str, *, storage: ObjectStorage | None = None) -> None:
+        self.base_url = base_url
+        self.api_key = api_key
+        self.storage = storage
+        self._manifest_poll_timeout_minutes = 1
+        self._manifest_poll_interval_seconds = 2
+
+    @staticmethod
+    def safe_session_id(session_id: str) -> str:
+        return "".join(char for char in session_id if char.isalnum() or char in {"-", "_"})
+
+    @classmethod
+    def video_filename(cls, session_id: str, extension: str = ".mp4") -> str:
+        safe_session_id = cls.safe_session_id(session_id)
+        normalized_extension = extension if extension.startswith(".") else f".{extension}"
+        return f"{VIDEO_FILE_NAME_PREFIX}{safe_session_id}{normalized_extension}"
+
+    @staticmethod
+    def _parse_manifest_entries(manifest_text: str, manifest_url: str) -> tuple[str | None, list[str]]:
+        init_url = None
+        segments: list[str] = []
+
+        for line in manifest_text.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            if line.startswith("#EXT-X-MAP"):
+                match = re.search(r'URI="([^"]+)"', line)
+                if match:
+                    init_url = match.group(1)
+                continue
+            if line.startswith("#"):
+                continue
+            segments.append(urljoin(manifest_url, line))
+
+        if init_url:
+            init_url = urljoin(manifest_url, init_url)
+
+        return init_url, segments
+
+    @staticmethod
+    def _stream_url(session: requests.Session, url: str, headers: dict[str, str], output_file: BufferedWriter) -> None:
+        with session.get(url, headers=headers, stream=True, timeout=120) as response:
+            response.raise_for_status()
+            for chunk in response.iter_content(chunk_size=64 * 1024):
+                if chunk:
+                    output_file.write(chunk)
+
+    @staticmethod
+    def _cleanup_temp_directory(video_dir: str) -> None:
+        try:
+            shutil.rmtree(video_dir)
+        except OSError:
+            pass
+
+    def _download_manifest(self, session_id: str, dest: Path) -> str | None:
+        if not self.base_url or not self.api_key:
+            return None
+
+        url = f"{self.base_url.rstrip('/')}/v1/sessions/{session_id}/hls"
+        headers = {"steel-api-key": self.api_key}
+        deadline = time.monotonic() + (self._manifest_poll_timeout_minutes * 60)
+
+        while True:
+            response = requests.get(url, headers=headers, timeout=60)
+            if response.ok:
+                dest.write_text(response.text)
+                return response.url
+
+            pollable = response.status_code in {404, 408, 429, 503}
+            if not pollable or time.monotonic() >= deadline:
+                response.raise_for_status()
+
+            time.sleep(self._manifest_poll_interval_seconds)
+
+    def _merge_segments(self, manifest_path: Path, manifest_url: str, output_path: Path) -> bool:
+        if not self.api_key:
+            return False
+
+        headers = {"steel-api-key": self.api_key}
+        manifest_text = manifest_path.read_text()
+        init_url, segments = self._parse_manifest_entries(manifest_text, manifest_url)
+        if not segments:
+            return False
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with requests.Session() as session, open(output_path, "wb") as output_file:
+            if init_url:
+                self._stream_url(session, init_url, headers, output_file)
+            for segment_url in segments:
+                self._stream_url(session, segment_url, headers, output_file)
+        return True
+
+    async def _download_and_merge_manifest(self, session_id: str, output_path: Path) -> bool:
+        manifest_path = Path(tempfile.NamedTemporaryFile(suffix=MANIFEST_TEMP_SUFFIX, delete=False).name)
+
+        try:
+            manifest_url = await asyncio.to_thread(self._download_manifest, session_id, manifest_path)
+            if not manifest_url:
+                return False
+
+            return await asyncio.to_thread(self._merge_segments, manifest_path, manifest_url, output_path)
+        except Exception:
+            logger.debug(
+                "Failed to download/merge Steel HLS manifest for session %s",
+                session_id,
+                exc_info=True,
+            )
+            return False
+        finally:
+            manifest_path.unlink(missing_ok=True)
+
+    async def _upload_to_storage(self, video_path: Path, video_filename: str) -> bool:
+        if self.storage is None or not self.storage.is_available:
+            return False
+        if not video_path.exists():
+            return False
+        return self.storage.upload_file(str(video_path), video_filename) is not None
+
+    async def record_session_to_video(self, session_id: str) -> bool:
+        if not self.storage or not self.storage.is_available or not session_id:
+            return False
+
+        video_dir = tempfile.mkdtemp()
+        try:
+            video_filename = self.video_filename(session_id)
+            output_path = Path(video_dir) / video_filename
+            merged = await self._download_and_merge_manifest(session_id, output_path)
+            if not merged:
+                return False
+            return await self._upload_to_storage(output_path, video_filename)
+        finally:
+            self._cleanup_temp_directory(video_dir)
+
+    @classmethod
+    def schedule_recording_in_background(
+        cls,
+        session_id: str,
+        base_url: str,
+        api_key: str,
+        storage: ObjectStorage | None,
+    ) -> threading.Thread | None:
+        if not session_id or not storage or not storage.is_available:
+            return None
+
+        recorder = cls(base_url=base_url, api_key=api_key, storage=storage)
+
+        def _run() -> None:
+            try:
+                asyncio.run(recorder.record_session_to_video(session_id=session_id))
+            except Exception as error:  # pragma: no cover - defensive logging
+                logger.warning("Background recording failed for session %s: %s", session_id, error, exc_info=True)
+
+        thread_name = f"steel-recording-{cls.safe_session_id(session_id)}"
+        thread = threading.Thread(target=_run, daemon=True, name=thread_name)
+        thread.start()
+        return thread
+
+
+class SteelBrowserInfrastructure(BrowserInfrastructure[Steel, Session]):
+    """Concrete Steel implementation for browser infrastructure sessions."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_STEEL_BASE_URL,
+        ws_url: str = DEFAULT_STEEL_WS_URL,
+        timeout_in_ms: int = DEFAULT_STEEL_TIMEOUT_IN_MS,
+    ) -> None:
+        """Initialize the Steel browser infrastructure.
+
+        ``api_key`` defaults to the ``STEEL_API_KEY`` environment variable
+        resolved at construction time (not import time) when not provided.
+        """
+        resolved_api_key = api_key if api_key is not None else os.getenv("STEEL_API_KEY")
+        if not resolved_api_key:
+            raise BrowserUseConfigurationError("api_key is required.")
+        if timeout_in_ms <= 0:
+            raise BrowserUseConfigurationError("timeout_in_ms must be > 0.")
+
+        self.api_key = resolved_api_key
+        self.base_url = base_url
+        self.ws_url = ws_url
+        self.timeout_in_ms = timeout_in_ms
+
+    @property
+    def provider(self) -> str:
+        """Return the human-readable infrastructure provider name."""
+        return "steel"
+
+    @property
+    def supports_recording(self) -> bool:
+        """Whether this infrastructure can produce session recordings.
+
+        ``True`` indicates Steel supports recording. Recording is only
+        actually started when an available :class:`ObjectStorage` is also
+        provided to the :class:`BrowserUseClient`.
+        """
+        return True
+
+    async def create_session(self) -> BrowserInfrastructureContext[Steel, Session]:
+        """Create a new Steel session and return the active context."""
+        client = Steel(steel_api_key=self.api_key, base_url=self.base_url)
+        session = client.sessions.create(use_proxy=False, api_timeout=self.timeout_in_ms)
+        return BrowserInfrastructureContext(
+            client=client,
+            session=session,
+            session_id=str(getattr(session, "id", "")),
+            streaming_url=str(getattr(session, "debug_url", "")),
+            metadata={"provider": self.provider},
+        )
+
+    async def release_session(self, context: BrowserInfrastructureContext[Steel, Session]) -> None:
+        """Release or dispose Steel session resources."""
+        if not context.client or not context.session:
+            return
+
+        for attempt in range(3):
+            try:
+                context.client.sessions.release(context.session.id)
+                return
+            except Exception:
+                if attempt == 2:
+                    raise
+                await asyncio.sleep(0.5 * (attempt + 1))
+
+    def cdp_url(self, session_id: str) -> str:
+        """Build a CDP endpoint URL for the provided Steel session ID."""
+        return f"{self.ws_url}?apiKey={self.api_key}&sessionId={session_id}"
+
+    def recording_filename(self, session_id: str) -> str:
+        """Return the preferred recording object name for the provided Steel session ID."""
+        return _SteelSessionRecorder.video_filename(session_id)
+
+    def schedule_recording(
+        self, context: BrowserInfrastructureContext[Steel, Session], storage: ObjectStorage | None
+    ) -> None:
+        """Schedule background recording for the provided context."""
+        if not self.supports_recording or not context.session_id:
+            return
+        try:
+            _SteelSessionRecorder.schedule_recording_in_background(
+                session_id=context.session_id,
+                base_url=self.base_url,
+                api_key=self.api_key,
+                storage=storage,
+            )
+        except Exception as error:
+            logger.debug("Failed to start background recording for Steel session %s: %s", context.session_id, error)
+
+
+__all__ = ["SteelBrowserInfrastructure"]

gl_browser_use/infrastructure/steel.pyi

@@ -0,0 +1,56 @@
+import threading
+from _typeshed import Incomplete
+from gl_browser_use.infrastructure.base import BrowserInfrastructure, BrowserInfrastructureContext
+from gl_browser_use.storage.base import ObjectStorage
+from steel import Steel
+from steel.types.session import Session
+
+__all__ = ['SteelBrowserInfrastructure']
+
+class _SteelSessionRecorder:
+    """Capture Steel HLS sessions and upload recordings to object storage."""
+    base_url: Incomplete
+    api_key: Incomplete
+    storage: Incomplete
+    def __init__(self, base_url: str, api_key: str, *, storage: ObjectStorage | None = None) -> None: ...
+    @staticmethod
+    def safe_session_id(session_id: str) -> str: ...
+    @classmethod
+    def video_filename(cls, session_id: str, extension: str = '.mp4') -> str: ...
+    async def record_session_to_video(self, session_id: str) -> bool: ...
+    @classmethod
+    def schedule_recording_in_background(cls, session_id: str, base_url: str, api_key: str, storage: ObjectStorage | None) -> threading.Thread | None: ...
+
+class SteelBrowserInfrastructure(BrowserInfrastructure[Steel, Session]):
+    """Concrete Steel implementation for browser infrastructure sessions."""
+    api_key: Incomplete
+    base_url: Incomplete
+    ws_url: Incomplete
+    timeout_in_ms: Incomplete
+    def __init__(self, api_key: str | None = None, base_url: str = ..., ws_url: str = ..., timeout_in_ms: int = ...) -> None:
+        """Initialize the Steel browser infrastructure.
+
+        ``api_key`` defaults to the ``STEEL_API_KEY`` environment variable
+        resolved at construction time (not import time) when not provided.
+        """
+    @property
+    def provider(self) -> str:
+        """Return the human-readable infrastructure provider name."""
+    @property
+    def supports_recording(self) -> bool:
+        """Whether this infrastructure can produce session recordings.
+
+        ``True`` indicates Steel supports recording. Recording is only
+        actually started when an available :class:`ObjectStorage` is also
+        provided to the :class:`BrowserUseClient`.
+        """
+    async def create_session(self) -> BrowserInfrastructureContext[Steel, Session]:
+        """Create a new Steel session and return the active context."""
+    async def release_session(self, context: BrowserInfrastructureContext[Steel, Session]) -> None:
+        """Release or dispose Steel session resources."""
+    def cdp_url(self, session_id: str) -> str:
+        """Build a CDP endpoint URL for the provided Steel session ID."""
+    def recording_filename(self, session_id: str) -> str:
+        """Return the preferred recording object name for the provided Steel session ID."""
+    def schedule_recording(self, context: BrowserInfrastructureContext[Steel, Session], storage: ObjectStorage | None) -> None:
+        """Schedule background recording for the provided context."""

gl_browser_use/models.py

@@ -0,0 +1,45 @@
+"""Result and event models for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+BrowserUseRunStatus = Literal["success", "error", "cancelled"]
+
+
+@dataclass(frozen=True)
+class BrowserUseStreamEvent:
+    """Structured stream event emitted during ``BrowserUseClient`` execution."""
+
+    event_type: str
+    content: str
+    thinking_and_activity_info: dict[str, Any] = field(default_factory=dict)
+    is_final: bool = False
+    tool_info: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class BrowserUseRunResult:
+    """Final result returned for a completed run."""
+
+    status: BrowserUseRunStatus
+    task: str
+    final_output: str
+    session_id: str | None = None
+    streaming_url: str | None = None
+    recording_url: str | None = None
+    steps: int = 0
+    error: str | None = None
+    events: list[BrowserUseStreamEvent] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_success(self) -> bool:
+        """Return True if the run was successful."""
+        return self.status == "success"

gl_browser_use/models.pyi

@@ -0,0 +1,32 @@
+from _typeshed import Incomplete
+from dataclasses import dataclass, field
+from typing import Any
+
+BrowserUseRunStatus: Incomplete
+
+@dataclass(frozen=True)
+class BrowserUseStreamEvent:
+    """Structured stream event emitted during ``BrowserUseClient`` execution."""
+    event_type: str
+    content: str
+    thinking_and_activity_info: dict[str, Any] = field(default_factory=dict)
+    is_final: bool = ...
+    tool_info: dict[str, Any] | None = ...
+    metadata: dict[str, Any] | None = ...
+
+@dataclass(frozen=True)
+class BrowserUseRunResult:
+    """Final result returned for a completed run."""
+    status: BrowserUseRunStatus
+    task: str
+    final_output: str
+    session_id: str | None = ...
+    streaming_url: str | None = ...
+    recording_url: str | None = ...
+    steps: int = ...
+    error: str | None = ...
+    events: list[BrowserUseStreamEvent] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    @property
+    def is_success(self) -> bool:
+        """Return True if the run was successful."""