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

gl_browser_use/parsing.py

@@ -0,0 +1,264 @@
+"""Parsing and tool-call helpers for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from browser_use import Agent
+
+from gl_browser_use.parsing_recovery import (
+    extract_balanced_json_value,
+    recover_concatenated_json_objects,
+    repair_json_blob,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def coerce_string(value: Any) -> str:
+    """Return a stable ``str`` representation of ``value`` (``None`` becomes ``""``)."""
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def summarize_terminal_error(error_message: str, *, max_length: int = 200) -> str:
+    """Collapse whitespace in ``error_message`` and truncate to ``max_length`` characters."""
+    normalized = " ".join(coerce_string(error_message).split())
+    if len(normalized) <= max_length:
+        return normalized
+    return normalized[: max_length - 1] + "…"
+
+
+@dataclass
+class ToolCall:
+    """Normalized tool-call snapshot extracted from the underlying agent state."""
+
+    name: str
+    args: dict[str, Any]
+    output: str = ""
+
+
+def read_tool_call(call: Any) -> tuple[str, dict[str, Any], str]:
+    """Return a ``(name, args, output)`` triple for a tool call of any supported shape.
+
+    ``name`` may be an empty string when the underlying payload is missing
+    a name; callers requiring a fallback label should apply one explicitly.
+    """
+    if isinstance(call, dict):
+        name = coerce_string(call.get("name"))
+        args_value = call.get("args", {})
+        output = coerce_string(call.get("output", ""))
+    else:
+        name = coerce_string(getattr(call, "name", ""))
+        args_value = getattr(call, "args", {})
+        output = coerce_string(getattr(call, "output", ""))
+
+    args = args_value if isinstance(args_value, dict) else {"value": args_value}
+    return name, args, output
+
+
+def extract_outputs(last_result: list[Any]) -> list[str]:
+    """Return one display string per entry in ``last_result``."""
+    outputs: list[str] = []
+    for result in last_result or []:
+        extracted = coerce_string(getattr(result, "extracted_content", None))
+        if extracted:
+            outputs.append(extracted)
+        elif getattr(result, "error", None):
+            outputs.append(f"Error: {result.error}")
+        else:
+            outputs.append("")
+    return outputs
+
+
+def extract_tool_calls(agent: Agent) -> list[ToolCall]:
+    """Extract serialized tool-call snapshots from the agent's last model output."""
+    state = getattr(agent, "state", None)
+    if not state:
+        return []
+
+    model_output = getattr(state, "last_model_output", None)
+    action = getattr(model_output, "action", None)
+    if not action:
+        return []
+
+    last_result = getattr(state, "last_result", None) or []
+    outputs = extract_outputs(last_result)
+
+    calls: list[ToolCall] = []
+    for index, action_model in enumerate(action):
+        try:
+            root_action = getattr(action_model, "root", action_model)
+            payload = None
+            if hasattr(root_action, "model_dump"):
+                payload = root_action.model_dump(exclude_unset=True)
+            elif hasattr(root_action, "dict"):
+                payload = root_action.dict(exclude_unset=True)
+            elif isinstance(root_action, dict):
+                payload = root_action
+            else:
+                payload = getattr(root_action, "__dict__", {})
+
+            if isinstance(payload, dict) and payload:
+                name = str(next(iter(payload)))
+                args = payload[name]
+                if not isinstance(args, dict):
+                    args = {"value": args}
+            else:
+                name = "unknown"
+                args = {}
+            output = outputs[index] if index < len(outputs) else ""
+            calls.append(ToolCall(name=name, args=args, output=output))
+        except Exception as exc:
+            output = outputs[index] if index < len(outputs) else ""
+            calls.append(
+                ToolCall(name="parsing_error", args={"error": summarize_terminal_error(str(exc))}, output=output)
+            )
+    return calls
+
+
+def extract_final_output(agent: Agent) -> str:
+    """Return the final textual output from the agent, or an empty string if absent."""
+    state = getattr(agent, "state", None)
+    if not state:
+        return ""
+
+    last_result = getattr(state, "last_result", None) or []
+    if not last_result:
+        return ""
+
+    done_content: str | None = None
+    any_content: str | None = None
+    any_error: str | None = None
+    for result in reversed(list(last_result)):
+        extracted = coerce_string(getattr(result, "extracted_content", None))
+        if extracted and done_content is None and getattr(result, "is_done", False):
+            done_content = extracted
+        if extracted and any_content is None:
+            any_content = extracted
+        if any_error is None:
+            error = getattr(result, "error", None)
+            if error:
+                any_error = coerce_string(error)
+
+    if done_content:
+        return done_content
+    if any_content:
+        return any_content
+    if any_error:
+        return f"Error: {any_error}"
+    return ""
+
+
+def _strip_trailers(remainder: str) -> str:
+    for trailer in ("</extracted_content>", "<file_system>", "</file_system>"):
+        idx = remainder.find(trailer)
+        if idx != -1:
+            remainder = remainder[:idx]
+    return remainder.strip()
+
+
+def _try_repair_and_parse(json_blob: str) -> tuple[dict[str, Any] | list[Any] | None, str | None]:
+    repaired = repair_json_blob(json_blob)
+    if repaired is None:
+        return None, "JSON parsing failed."
+    try:
+        return json.loads(repaired), None
+    except json.JSONDecodeError:
+        return None, "JSON parsing failed after repair."
+
+
+def parse_structured_data(output: str) -> tuple[dict[str, Any] | list[Any] | None, str | None]:
+    """Parse the ``Extracted Content:`` block in ``output`` with fallback recovery.
+
+    The parser (1) trims trailers and slices from the first ``{``/``[``;
+    (2) attempts a direct ``json.loads``; (3) attempts to recover
+    concatenated top-level JSON objects; (4) extracts a balanced-prefix
+    JSON value with a depth-aware scanner that respects string literals
+    and parses it; and finally (5) falls back to ``json_repair.repair_json``.
+    """
+    marker = "Extracted Content:"
+    if marker not in output:
+        return None, None
+    _, remainder = output.split(marker, 1)
+    remainder = _strip_trailers(remainder)
+    if not remainder:
+        return None, None
+
+    candidate = _slice_from_first_opener(remainder)
+    if candidate is None:
+        return None, None
+
+    try:
+        return json.loads(candidate), None
+    except json.JSONDecodeError as error:
+        logger.debug("Primary JSON parse failed for structured extraction output: %s", error)
+
+    recovered = recover_concatenated_json_objects(candidate)
+    if recovered is not None:
+        return recovered, None
+
+    balanced_prefix = extract_balanced_json_value(candidate)
+    if balanced_prefix and balanced_prefix != candidate:
+        try:
+            return json.loads(balanced_prefix), None
+        except json.JSONDecodeError as error:
+            logger.debug("Balanced-prefix JSON parse failed: %s", error)
+
+    return _try_repair_and_parse(candidate)
+
+
+def _slice_from_first_opener(text: str) -> str | None:
+    openers = [text.find(opener) for opener in ("{", "[")]
+    positions = [position for position in openers if position != -1]
+    if not positions:
+        return None
+    return text[min(positions) :].strip() or None
+
+
+def validate_structured_data_output(tool_calls: list[ToolCall]) -> str | None:
+    """Return a user-facing error when structured data extraction failed or yielded no usable entries."""
+    for call in tool_calls:
+        if call.name != "extract_structured_data":
+            continue
+        payload, parse_error = parse_structured_data(call.output)
+        if parse_error:
+            return f"Structured data extraction emitted invalid JSON. {parse_error}"
+        if payload is None:
+            continue
+        if isinstance(payload, dict):
+            status = payload.get("status")
+            if isinstance(status, str) and status.lower() == "error":
+                message = payload.get("message") or payload.get("error") or call.output
+                return f"Structured data extraction failed: {summarize_terminal_error(coerce_string(message))}"
+            if (
+                (isinstance(payload.get("products"), list) and len(payload.get("products", [])) == 0)
+                or payload.get("count") == 0
+                or payload.get("products_found") == 0
+                or payload.get("available") is False
+            ):
+                return "Structured data extraction returned no usable entries."
+    return None
+
+
+__all__ = [
+    "ToolCall",
+    "coerce_string",
+    "extract_final_output",
+    "extract_outputs",
+    "extract_tool_calls",
+    "parse_structured_data",
+    "read_tool_call",
+    "summarize_terminal_error",
+    "validate_structured_data_output",
+]

gl_browser_use/parsing.pyi

@@ -0,0 +1,41 @@
+from browser_use import Agent
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ['ToolCall', 'coerce_string', 'extract_final_output', 'extract_outputs', 'extract_tool_calls', 'parse_structured_data', 'read_tool_call', 'summarize_terminal_error', 'validate_structured_data_output']
+
+def coerce_string(value: Any) -> str:
+    '''Return a stable ``str`` representation of ``value`` (``None`` becomes ``""``).'''
+def summarize_terminal_error(error_message: str, *, max_length: int = 200) -> str:
+    """Collapse whitespace in ``error_message`` and truncate to ``max_length`` characters."""
+
+@dataclass
+class ToolCall:
+    """Normalized tool-call snapshot extracted from the underlying agent state."""
+    name: str
+    args: dict[str, Any]
+    output: str = ...
+
+def read_tool_call(call: Any) -> tuple[str, dict[str, Any], str]:
+    """Return a ``(name, args, output)`` triple for a tool call of any supported shape.
+
+    ``name`` may be an empty string when the underlying payload is missing
+    a name; callers requiring a fallback label should apply one explicitly.
+    """
+def extract_outputs(last_result: list[Any]) -> list[str]:
+    """Return one display string per entry in ``last_result``."""
+def extract_tool_calls(agent: Agent) -> list[ToolCall]:
+    """Extract serialized tool-call snapshots from the agent's last model output."""
+def extract_final_output(agent: Agent) -> str:
+    """Return the final textual output from the agent, or an empty string if absent."""
+def parse_structured_data(output: str) -> tuple[dict[str, Any] | list[Any] | None, str | None]:
+    """Parse the ``Extracted Content:`` block in ``output`` with fallback recovery.
+
+    The parser (1) trims trailers and slices from the first ``{``/``[``;
+    (2) attempts a direct ``json.loads``; (3) attempts to recover
+    concatenated top-level JSON objects; (4) extracts a balanced-prefix
+    JSON value with a depth-aware scanner that respects string literals
+    and parses it; and finally (5) falls back to ``json_repair.repair_json``.
+    """
+def validate_structured_data_output(tool_calls: list[ToolCall]) -> str | None:
+    """Return a user-facing error when structured data extraction failed or yielded no usable entries."""

gl_browser_use/parsing_recovery.py

@@ -0,0 +1,204 @@
+"""Utilities for recovering malformed structured-data payloads emitted by browser-use.
+
+The helpers in this module normalize JSON-like strings that the structured
+data extractor may return when model output is partially corrupted (e.g.
+concatenated top-level JSON objects or trailing commas). They are used
+internally by :mod:`gl_browser_use.parsing`.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from json_repair import repair_json
+
+logger = logging.getLogger(__name__)
+
+_OPENERS: tuple[str, ...] = ("{", "[")
+_MATCHING_CLOSER: dict[str, str] = {"{": "}", "[": "]"}
+
+
+def extract_balanced_json_value(text: str) -> str | None:
+    """Return the first balanced JSON value found in ``text`` (respecting string literals).
+
+    Returns ``None`` when no ``{``/``[`` is found or when the scan never
+    closes cleanly (unbalanced, truncated, or ends inside a string).
+    """
+    start = _find_first_opener(text)
+    if start is None:
+        return None
+    end = _scan_balanced_close(text, start)
+    if end is None:
+        return None
+    return text[start : end + 1]
+
+
+def recover_concatenated_json_objects(json_blob: str) -> dict[str, Any] | None:
+    """Normalize concatenated JSON object strings into a single structured payload.
+
+    Returns ``None`` if ``json_blob`` does not contain multiple top-level JSON
+    objects or they cannot be parsed individually.
+    """
+    segments = _split_top_level_json_objects(json_blob)
+    if len(segments) <= 1:
+        return None
+
+    try:
+        records = [json.loads(segment) for segment in segments]
+    except json.JSONDecodeError:
+        return None
+
+    count = len(records)
+    logger.info("Structured data extractor returned concatenated JSON objects. recovered=%s", count)
+    return {
+        "status": "ok",
+        "items": records,
+        "products": records,
+        "count": count,
+        "products_found": count,
+        "available": bool(records),
+    }
+
+
+def repair_json_blob(json_blob: str) -> str | None:
+    """Apply ``json_repair.repair_json`` to ``json_blob`` and return the mutated payload.
+
+    Returns ``None`` when ``json_repair`` could not repair the input or when
+    the repair produced no changes.
+    """
+    try:
+        repaired = repair_json(json_blob)
+    except Exception:
+        logger.debug("json_repair failed to repair structured data output.", exc_info=True)
+        return None
+
+    if not repaired or repaired == json_blob:
+        return None
+    return repaired
+
+
+def _find_first_opener(text: str) -> int | None:
+    positions = [text.find(opener) for opener in _OPENERS]
+    positions = [position for position in positions if position != -1]
+    return min(positions) if positions else None
+
+
+def _scan_balanced_close(text: str, start: int) -> int | None:
+    """Return the index of the matching closer for the opener at ``start`` or ``None``."""
+    opener = text[start]
+    closer = _MATCHING_CLOSER.get(opener)
+    if closer is None:
+        return None
+
+    depth = 0
+    in_string = False
+    escaping = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if escaping:
+            escaping = False
+            continue
+        if char == "\\":
+            escaping = True
+            continue
+        if char == '"':
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if char == opener:
+            depth += 1
+        elif char == closer:
+            depth -= 1
+            if depth == 0:
+                return index
+    return None
+
+
+def _split_top_level_json_objects(json_blob: str) -> list[str]:
+    splitter = _JsonObjectSplitter(json_blob)
+    return splitter.split_objects()
+
+
+def _has_only_separators(value: str) -> bool:
+    return value.strip(" \t\r\n,") == ""
+
+
+class _JsonObjectSplitter:
+    """Split concatenated top-level JSON objects while respecting string literals."""
+
+    def __init__(self, json_blob: str) -> None:
+        self.json_blob = json_blob
+        self.segments: list[str] = []
+        self.depth = 0
+        self.start: int | None = None
+        self.last_end = 0
+        self.in_string = False
+        self.escaping = False
+
+    def split_objects(self) -> list[str]:
+        if not self._parse_characters():
+            return []
+        if not self._validate_final_state():
+            return []
+        return self.segments
+
+    def _parse_characters(self) -> bool:
+        for index, char in enumerate(self.json_blob):
+            if not self._process_character(char, index):
+                return False
+        return True
+
+    def _process_character(self, char: str, index: int) -> bool:
+        if self.escaping:
+            self.escaping = False
+            return True
+        if char == "\\":
+            self.escaping = True
+            return True
+        if char == '"':
+            self.in_string = not self.in_string
+            return True
+        if self.in_string:
+            return True
+        return self._process_non_string_char(char, index)
+
+    def _process_non_string_char(self, char: str, index: int) -> bool:
+        if char == "{":
+            return self._handle_open_brace(index)
+        if char == "}":
+            return self._handle_close_brace(index)
+        return True
+
+    def _handle_open_brace(self, index: int) -> bool:
+        if self.depth == 0:
+            if not _has_only_separators(self.json_blob[self.last_end : index]):
+                return False
+            self.start = index
+        self.depth += 1
+        return True
+
+    def _handle_close_brace(self, index: int) -> bool:
+        self.depth -= 1
+        if self.depth == 0 and self.start is not None:
+            end = index + 1
+            self.segments.append(self.json_blob[self.start : end])
+            self.last_end = end
+        return True
+
+    def _validate_final_state(self) -> bool:
+        if self.depth != 0 or self.in_string:
+            return False
+        return _has_only_separators(self.json_blob[self.last_end :])
+
+
+__all__ = [
+    "extract_balanced_json_value",
+    "recover_concatenated_json_objects",
+    "repair_json_blob",
+]

gl_browser_use/parsing_recovery.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from typing import Any
+
+__all__ = ['extract_balanced_json_value', 'recover_concatenated_json_objects', 'repair_json_blob']
+
+def extract_balanced_json_value(text: str) -> str | None:
+    """Return the first balanced JSON value found in ``text`` (respecting string literals).
+
+    Returns ``None`` when no ``{``/``[`` is found or when the scan never
+    closes cleanly (unbalanced, truncated, or ends inside a string).
+    """
+def recover_concatenated_json_objects(json_blob: str) -> dict[str, Any] | None:
+    """Normalize concatenated JSON object strings into a single structured payload.
+
+    Returns ``None`` if ``json_blob`` does not contain multiple top-level JSON
+    objects or they cannot be parsed individually.
+    """
+def repair_json_blob(json_blob: str) -> str | None:
+    """Apply ``json_repair.repair_json`` to ``json_blob`` and return the mutated payload.
+
+    Returns ``None`` when ``json_repair`` could not repair the input or when
+    the repair produced no changes.
+    """
+
+class _JsonObjectSplitter:
+    """Split concatenated top-level JSON objects while respecting string literals."""
+    json_blob: Incomplete
+    segments: list[str]
+    depth: int
+    start: int | None
+    last_end: int
+    in_string: bool
+    escaping: bool
+    def __init__(self, json_blob: str) -> None: ...
+    def split_objects(self) -> list[str]: ...

gl_browser_use/session_errors.py

@@ -0,0 +1,72 @@
+"""Session-aware helpers for retry decisions for GL Browser Use SDK.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from gl_browser_use.parsing import coerce_string
+
+
+@dataclass(frozen=True)
+class SessionErrorCategory:
+    """Session error classification for retry decisions."""
+
+    name: str
+    markers: tuple[str, ...]
+    fatal: bool
+    retryable: bool
+
+
+_FATAL_SESSION_ERROR_CATEGORIES: tuple[SessionErrorCategory, ...] = (
+    SessionErrorCategory(
+        name="browser_closed",
+        markers=(
+            "browser has been closed",
+            "target page, context or browser has been closed",
+        ),
+        fatal=True,
+        retryable=True,
+    ),
+    SessionErrorCategory(
+        name="websocket_disconnect",
+        markers=(
+            "code=1006",
+            "websocket was closed before the connection was established",
+            "websocket error",
+        ),
+        fatal=True,
+        retryable=True,
+    ),
+)
+
+_FATAL_SESSION_ERROR_LOOKUP: dict[str, SessionErrorCategory] = {
+    marker.lower(): category for category in _FATAL_SESSION_ERROR_CATEGORIES for marker in category.markers
+}
+
+
+def categorize_fatal_session_message(message: str) -> SessionErrorCategory | None:
+    """Return the matching :class:`SessionErrorCategory` for ``message`` or ``None``."""
+    if not message:
+        return None
+    lowered = coerce_string(message).lower()
+    for marker, category in _FATAL_SESSION_ERROR_LOOKUP.items():
+        if marker in lowered:
+            return category
+    return None
+
+
+def is_recoverable_session_error(message: str) -> bool:
+    """Return True when ``message`` matches a recoverable session-failure category."""
+    category = categorize_fatal_session_message(message)
+    return bool(category and category.retryable)
+
+
+__all__ = [
+    "SessionErrorCategory",
+    "categorize_fatal_session_message",
+    "is_recoverable_session_error",
+]

gl_browser_use/session_errors.pyi

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+__all__ = ['SessionErrorCategory', 'categorize_fatal_session_message', 'is_recoverable_session_error']
+
+@dataclass(frozen=True)
+class SessionErrorCategory:
+    """Session error classification for retry decisions."""
+    name: str
+    markers: tuple[str, ...]
+    fatal: bool
+    retryable: bool
+
+def categorize_fatal_session_message(message: str) -> SessionErrorCategory | None:
+    """Return the matching :class:`SessionErrorCategory` for ``message`` or ``None``."""
+def is_recoverable_session_error(message: str) -> bool:
+    """Return True when ``message`` matches a recoverable session-failure category."""

gl_browser_use/storage/__init__.py

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

gl_browser_use/storage/__init__.pyi

@@ -0,0 +1,6 @@
+from gl_browser_use.storage.base import OBJECT_NAME_PREFIX as OBJECT_NAME_PREFIX, ObjectStorage as ObjectStorage
+
+__all__ = ['OBJECT_NAME_PREFIX', 'ObjectStorage', 'MinIOS3CompatibleStorage']
+
+# Names in __all__ with no definition:
+#   MinIOS3CompatibleStorage