aip-agents-binary 0.5.20__py3-none-any.whl

aip_agents/tools/browser_use/llm_config.py

@@ -0,0 +1,120 @@
+"""Helpers for configuring browser-use LLM instances and environment flags.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from browser_use.llm import ChatOpenAI
+from browser_use.logging_config import setup_logging
+
+
+def model_disallows_tunable_params(model: Any) -> bool:
+    """Return True if the provider forbids temperature/frequency overrides for the model.
+
+    Args:
+        model: The model name or identifier to check.
+
+    Returns:
+        bool: True if the model disallows tunable parameters, False otherwise.
+    """
+    model_name = str(model).lower()
+
+    if model_name.startswith("gpt-5"):
+        return True
+
+    short_name = model_name.split("-", 1)[0]
+    return short_name.startswith("o") and short_name[1:].isdigit()
+
+
+def supports_temperature_override(model: Any) -> bool:
+    """Return True when the given model supports setting a custom temperature.
+
+    Args:
+        model: The model name or identifier to check.
+
+    Returns:
+        bool: True if the model supports temperature override, False otherwise.
+    """
+    return not model_disallows_tunable_params(model)
+
+
+def supports_frequency_penalty(model: Any) -> bool:
+    """Return True when the given model supports custom frequency penalties.
+
+    Args:
+        model: The model name or identifier to check.
+
+    Returns:
+        bool: True if the model supports frequency penalty override, False otherwise.
+    """
+    return not model_disallows_tunable_params(model)
+
+
+def build_browser_use_llm(
+    *,
+    model: Any,
+    reasoning_effort: Any,
+    temperature: float | None,
+    api_key: str,
+    base_url: str | None = None,
+) -> ChatOpenAI:
+    """Construct a ChatOpenAI instance with browser-use specific safeguards.
+
+    Args:
+        model: The model name or identifier to use.
+        reasoning_effort: The reasoning effort level for the model.
+        temperature: Optional temperature setting for the model. Can be None.
+        api_key: The API key for authentication.
+        base_url: The base URL for the model.
+
+    Returns:
+        ChatOpenAI: The configured ChatOpenAI instance.
+    """
+    llm_kwargs: dict[str, Any] = {
+        "model": model,
+        "reasoning_effort": reasoning_effort,
+        "api_key": api_key,
+        "base_url": base_url,
+    }
+
+    if temperature is not None and supports_temperature_override(model):
+        llm_kwargs["temperature"] = temperature
+    else:
+        llm_kwargs["temperature"] = None
+
+    if not supports_frequency_penalty(model):
+        llm_kwargs["frequency_penalty"] = None
+
+    return ChatOpenAI(**llm_kwargs)
+
+
+def configure_browser_use_environment(enable_cloud_sync: bool, logging_level: str) -> None:
+    """Ensure Browser Use environment flags are aligned with tool configuration.
+
+    Args:
+        enable_cloud_sync: Whether to enable cloud synchronization for browser sessions.
+        logging_level: The desired logging level for browser use operations.
+    """
+    desired_sync = "true" if enable_cloud_sync else "false"
+    if os.environ.get("BROWSER_USE_CLOUD_SYNC") != desired_sync:
+        os.environ["BROWSER_USE_CLOUD_SYNC"] = desired_sync
+
+    desired_level = logging_level.lower()
+    current_level = os.environ.get("BROWSER_USE_LOGGING_LEVEL")
+    if not current_level or current_level.lower() != desired_level:
+        os.environ["BROWSER_USE_LOGGING_LEVEL"] = desired_level
+        setup_logging(log_level=desired_level, force_setup=True)
+
+
+__all__ = [
+    "build_browser_use_llm",
+    "configure_browser_use_environment",
+    "model_disallows_tunable_params",
+    "supports_frequency_penalty",
+    "supports_temperature_override",
+]

aip_agents/tools/browser_use/minio_storage.py

@@ -0,0 +1,198 @@
+"""MinIO Storage Handler for Steel Session Recording.
+
+This module provides MinIO cloud storage functionality for uploading and managing
+video files from Steel session recordings. It handles file uploads, bucket management,
+and presigned URL generation for secure file access.
+
+The module supports:
+- Automatic bucket creation and validation
+- Secure file uploads with proper content types
+- Presigned URL generation for temporary file access
+- Directory prefix support for organized storage
+- Comprehensive error handling and logging
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+import os
+
+from dotenv import load_dotenv
+from minio import Minio
+from minio.error import S3Error
+
+load_dotenv()
+
+OBJECT_NAME_PREFIX = "steel-recordings/"
+
+
+class MinIOStorage:
+    """Handles MinIO cloud storage operations for video files.
+
+    This class provides a complete interface for MinIO operations including:
+    - Connection management with authentication
+    - Bucket existence validation and creation
+    - File upload with proper metadata
+    - Presigned URL generation for secure access
+
+    Attributes:
+        endpoint: MinIO server endpoint URL.
+        access_key: MinIO access key for authentication.
+        secret_key: MinIO secret key for authentication.
+        secure: Whether to use HTTPS/TLS for connections.
+        bucket_name: Target bucket for file storage.
+        directory_prefix: Optional directory prefix for organized storage.
+        client: MinIO client instance for API operations.
+    """
+
+    def __init__(self):
+        """Initialize MinIO storage with configuration from environment variables.
+
+        Reads configuration from the following environment variables:
+        - OBJECT_STORAGE_URL: MinIO server endpoint
+        - OBJECT_STORAGE_USER: MinIO access key
+        - OBJECT_STORAGE_PASSWORD: MinIO secret key
+        - OBJECT_STORAGE_SECURE: Whether to use HTTPS (default: False)
+        - OBJECT_STORAGE_BUCKET: Target bucket name
+        - OBJECT_STORAGE_DIRECTORY_PREFIX: Optional directory prefix
+
+        Raises:
+            ValueError: If required environment variables are missing.
+            Exception: If bucket creation or validation fails.
+
+        Note:
+            The method automatically ensures the target bucket exists,
+            creating it if necessary.
+        """
+        self.endpoint = os.getenv("OBJECT_STORAGE_URL")
+        self.access_key = os.getenv("OBJECT_STORAGE_USER")
+        self.secret_key = os.getenv("OBJECT_STORAGE_PASSWORD")
+        self.secure = os.getenv("OBJECT_STORAGE_SECURE", "False").lower() == "true"
+        self.bucket_name = os.getenv("OBJECT_STORAGE_BUCKET")
+        self.directory_prefix = os.getenv("OBJECT_STORAGE_DIRECTORY_PREFIX")
+
+        if not all([self.endpoint, self.access_key, self.secret_key, self.bucket_name]):
+            raise ValueError(
+                "MinIO configuration incomplete. Set OBJECT_STORAGE_URL, OBJECT_STORAGE_USER, OBJECT_STORAGE_PASSWORD,"
+                "and OBJECT_STORAGE_BUCKET."
+            )
+
+        self.client = Minio(
+            self.endpoint,
+            access_key=self.access_key,
+            secret_key=self.secret_key,
+            secure=self.secure,
+        )
+
+        # Ensure bucket exists
+        self._ensure_bucket_exists()
+
+    def _ensure_bucket_exists(self):
+        """Ensure the configured bucket exists, create if it doesn't.
+
+        This method checks if the target bucket exists and creates it if necessary.
+        It's called during initialization to ensure the storage is ready for use.
+
+        Raises:
+            Exception: If bucket creation or validation fails.
+
+        Note:
+            Bucket creation failures are logged as warnings but don't prevent
+            the class from being usable (existing buckets can still be accessed).
+        """
+        try:
+            if not self.client.bucket_exists(self.bucket_name):
+                self.client.make_bucket(self.bucket_name)
+        except S3Error as e:
+            raise Exception(f"Warning: Could not ensure bucket exists: {e}") from e
+
+    def get_object_name(self, object_name: str) -> str:
+        """Get the object name with the directory prefix.
+
+        This method constructs the full object path by combining the directory
+        prefix with the base object name. It ensures consistent path structure
+        for all stored files.
+
+        Args:
+            object_name: Name of the object in MinIO.
+
+        Returns:
+            str: Object name with the directory prefix and steel-recordings subdirectory.
+                Format: {prefix}/steel-recordings/{object_name} or steel-recordings/{object_name}
+
+        Note:
+            The method automatically adds a "steel-recordings" subdirectory to
+            organize video files separately from other content.
+        """
+        object_name = f"{OBJECT_NAME_PREFIX}{object_name}"
+        if self.directory_prefix:
+            return f"{self.directory_prefix}/{object_name}"
+        return object_name
+
+    def upload_file(self, file_path: str, object_name: str) -> None:
+        """Upload a file to MinIO bucket.
+
+        This method handles the complete file upload process including:
+        - File existence validation
+        - Proper content type setting for video files
+        - Error handling and logging
+        - Structured object naming with prefixes
+
+        Args:
+            file_path: Local path to the file to upload.
+            object_name: Name to use for the object in MinIO.
+
+        Raises:
+            Exception: If the file doesn't exist or upload fails.
+                Specific S3Error details are included in the exception message.
+
+        Note:
+            The method automatically sets the content type to "video/webm"
+            for proper video file handling in browsers and applications.
+        """
+        try:
+            if not os.path.exists(file_path):
+                raise Exception(f"File not found: {file_path}")
+
+            # Upload the file
+            self.client.fput_object(
+                self.bucket_name,
+                self.get_object_name(object_name),
+                file_path,
+                content_type="video/webm",
+            )
+
+        except S3Error as e:
+            raise Exception(f"Error uploading to MinIO: {e}") from e
+        except Exception as e:
+            raise Exception(f"Unexpected error during upload: {e}") from e
+
+    def get_file_url(self, object_name: str) -> str:
+        """Generate a presigned URL for accessing the uploaded file.
+
+        This method creates a temporary, secure URL that allows access to the
+        uploaded file without requiring MinIO credentials. The URL is valid
+        for a limited time and provides secure, direct access to the file.
+
+        Args:
+            object_name: Name of the object in MinIO.
+
+        Returns:
+            str: Presigned URL for secure file access.
+                The URL includes authentication tokens and is valid for a limited time.
+
+        Raises:
+            Exception: If presigned URL generation fails.
+                S3Error details are included in the exception message.
+
+        Note:
+            Presigned URLs are useful for sharing files temporarily without
+            exposing MinIO credentials or requiring users to have storage access.
+        """
+        try:
+            return self.client.presigned_get_object(
+                self.bucket_name,
+                self.get_object_name(object_name),
+            )
+        except S3Error as e:
+            raise Exception(f"Error generating presigned URL: {e}") from e

aip_agents/tools/browser_use/schemas.py

@@ -0,0 +1,119 @@
+"""Configuration schemas for Browser Use tool.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+import os
+from typing import Literal
+
+from openai.types.shared.chat_model import ChatModel
+from pydantic import BaseModel, Field
+
+
+class BrowserUseToolInput(BaseModel):
+    """Input schema for Browser Use tool."""
+
+    task: str = Field(..., description="Task prompt for the AI agent to execute in the browser")
+
+
+class BrowserUseToolConfig(BaseModel):
+    """Tool configuration schema for Browser Use tool."""
+
+    steel_api_key: str = Field(
+        default_factory=lambda: os.getenv("STEEL_API_KEY"),
+        description="Steel API key for Steel access",
+    )
+    steel_base_url: str = Field(
+        default="https://api.steel.dev",
+        description="Steel API base URL",
+    )
+    steel_ws_url: str = Field(
+        default="wss://connect.steel.dev",
+        description="Steel WebSocket URL for browser connection",
+    )
+    steel_timeout_in_ms: int = Field(
+        default=600_000,
+        description="Timeout for Steel operations in milliseconds",
+    )
+
+    browser_use_llm_openai_api_key: str = Field(
+        default_factory=lambda: os.getenv("OPENAI_API_KEY"),
+        description="OpenAI API key for browser-use access",
+    )
+    browser_use_llm_openai_model: ChatModel | str = Field(
+        default="o3",
+        description="OpenAI model to use for browser-use agent",
+    )
+    browser_use_llm_openai_temperature: float | None = Field(
+        default=None,
+        description="Temperature setting for OpenAI model (None uses provider default)",
+    )
+    browser_use_llm_openai_reasoning_effort: Literal["minimal", "low", "medium", "high"] = Field(
+        default="low",
+        description="Reasoning effort for OpenAI model",
+    )
+    browser_use_llm_openai_base_url: str | None = Field(
+        default=None,
+        description="Base URL for OpenAI model (None uses provider default)",
+    )
+
+    browser_use_page_extraction_llm_openai_api_key: str = Field(
+        default_factory=lambda: os.getenv("OPENAI_API_KEY"),
+        description="OpenAI API key for page extraction access",
+    )
+    browser_use_page_extraction_llm_openai_model: ChatModel | str = Field(
+        default="gpt-5-mini",
+        description="OpenAI model to use for page extraction",
+    )
+    browser_use_page_extraction_llm_openai_temperature: float | None = Field(
+        default=None,
+        description="Temperature setting for OpenAI model (None uses provider default)",
+    )
+    browser_use_page_extraction_llm_openai_reasoning_effort: Literal["minimal", "low", "medium", "high"] = Field(
+        default="minimal",
+        description="Reasoning effort for OpenAI model",
+    )
+    browser_use_page_extraction_llm_openai_base_url: str | None = Field(
+        default=None,
+        description="Base URL for OpenAI model (None uses provider default)",
+    )
+
+    browser_use_extend_system_message: str | None = Field(
+        default=None,
+        description="Extend system message for browser-use agent",
+    )
+
+    browser_use_vision_detail_level: Literal["auto", "low", "high"] = Field(
+        default="auto",
+        description="Detail level for vision",
+    )
+
+    browser_use_enable_cloud_sync: bool = Field(
+        default=False,
+        description="Enable Browser Use cloud sync and telemetry events",
+    )
+
+    browser_use_logging_level: Literal["debug", "info", "warning", "error", "result"] = Field(
+        default="info",
+        description="Logging verbosity for browser-use internals",
+    )
+
+    browser_use_llm_timeout_in_s: int = Field(
+        default=60,
+        description="Timeout for LLM in seconds",
+    )
+    browser_use_step_timeout_in_s: int = Field(
+        default=180,
+        description="Timeout for step in seconds",
+    )
+    browser_use_max_session_retries: int = Field(
+        default=2,
+        ge=0,
+        description="How many times to recreate the Steel session after recoverable disconnects.",
+    )
+    browser_use_session_retry_delay_in_s: float = Field(
+        default=3.0,
+        ge=0.0,
+        description="Delay (in seconds) before attempting to recover from a lost Steel session.",
+    )

aip_agents/tools/browser_use/session.py

@@ -0,0 +1,76 @@
+"""Session management for browser-use framework.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+
+References:
+    https://github.com/browser-use/browser-use/blob/0.5.9/browser_use/browser/session.py
+"""
+
+import asyncio
+
+from browser_use.agent.views import DOMElementNode
+from browser_use.browser.session import BrowserSession as BrowserUseSession
+from browser_use.browser.session import require_healthy_browser
+from browser_use.browser.views import BrowserError
+from browser_use.observability import observe_debug
+from browser_use.utils import _log_pretty_url, time_execution_async
+
+
+class BrowserSession(BrowserUseSession):
+    """Represents an active browser session with a running browser process somewhere."""
+
+    @require_healthy_browser(usable_page=True, reopen_page=True)
+    @time_execution_async("--input_text_element_node")
+    @observe_debug(ignore_input=True, name="input_text_element_node")
+    async def _input_text_element_node(self, element_node: DOMElementNode, text: str):
+        """Input text into an element with proper error handling and state management.
+
+        Args:
+            element_node (DOMElementNode): The element node to input text into.
+            text (str): The text to input into the element.
+        """
+        try:
+            element_handle = await self.get_locate_element(element_node)
+
+            if element_handle is None:
+                raise BrowserError(f"Element: {repr(element_node)} not found")
+
+            # Ensure element is ready for input
+            try:
+                await element_handle.wait_for_element_state("stable", timeout=1_000)
+                is_visible = await self._is_visible(element_handle)
+                if is_visible:
+                    await element_handle.scroll_into_view_if_needed(timeout=1_000)
+            except Exception as state_error:
+                self.logger.debug(
+                    "Skipping pre-input visibility preparation for %s due to %s",
+                    repr(element_node),
+                    state_error,
+                )
+
+            # let's first try to click and type
+            try:
+                await element_handle.evaluate('el => {el.textContent = ""; el.value = "";}')
+                await element_handle.click()
+                await asyncio.sleep(0.1)  # Increased sleep time
+                page = await self.get_current_page()
+                await page.keyboard.insert_text(text)
+                return
+            except Exception as e:
+                self.logger.debug(f"Input text with click and type failed, trying element handle method: {e}")
+                # fall through to BrowserUseSession fallback below
+
+        except Exception as e:
+            # Get current page URL safely for error message
+            try:
+                page = await self.get_current_page()
+                page_url = _log_pretty_url(page.url)
+            except Exception:
+                page_url = "unknown page"
+
+            self.logger.debug(
+                f"❌ Failed to input text into element: {repr(element_node)} "
+                f"on page {page_url}: {type(e).__name__}: {e}"
+            )
+            raise BrowserError(f"Failed to input text into index {element_node.highlight_index}") from e

aip_agents/tools/browser_use/session_errors.py

@@ -0,0 +1,132 @@
+"""Centralized Steel/browser session error policies used by BrowserUseTool.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SessionErrorCategory:
+    """Represents a fatal Steel/browser disconnect classification."""
+
+    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,
+    ),
+)
+
+_WARNING_MARKERS: dict[str, str] = {
+    "502 bad gateway": "page_load_warning",
+    "page link: about:blank": "blank_page_warning",
+    "no webpage content": "blank_page_warning",
+    "scroll_into_view_if_needed": "element_interaction_warning",
+}
+
+_FATAL_LOOKUP: dict[str, SessionErrorCategory] = {
+    marker.lower(): category for category in _FATAL_SESSION_ERROR_CATEGORIES for marker in category.markers
+}
+
+
+def categorize_fatal_message(message: str) -> SessionErrorCategory | None:
+    """Return the fatal session category associated with the given message, if any.
+
+    Args:
+        message: The error message to categorize.
+
+    Returns:
+        The SessionErrorCategory if the message matches a fatal error pattern,
+        None otherwise.
+    """
+    if not message:
+        return None
+
+    lowered = message.lower()
+    for marker, category in _FATAL_LOOKUP.items():
+        if marker in lowered:
+            return category
+    return None
+
+
+def categorize_warning_message(message: str) -> str | None:
+    """Return the name of a known non-fatal warning when present in the message.
+
+    Args:
+        message: The error message to check for warning patterns.
+
+    Returns:
+        The warning name if the message matches a known warning pattern,
+        None otherwise.
+    """
+    if not message:
+        return None
+
+    lowered = message.lower()
+    for marker, warning_name in _WARNING_MARKERS.items():
+        if marker in lowered:
+            return warning_name
+    return None
+
+
+def find_fatal_message(messages: Iterable[str]) -> tuple[str, SessionErrorCategory] | None:
+    """Return the first fatal message detected in the iterable.
+
+    Args:
+        messages: An iterable of error messages to search through.
+
+    Returns:
+        A tuple of (message, category) for the first fatal message found,
+        None if no fatal messages are detected.
+    """
+    for message in messages:
+        category = categorize_fatal_message(message)
+        if category:
+            return message, category
+    return None
+
+
+def is_recoverable_message(message: str) -> bool:
+    """Return True when the message maps to a retryable session disconnect.
+
+    Args:
+        message: The error message to check for recoverability.
+
+    Returns:
+        True if the message corresponds to a retryable fatal error,
+        False otherwise.
+    """
+    category = categorize_fatal_message(message)
+    return bool(category and category.retryable)
+
+
+__all__ = [
+    "SessionErrorCategory",
+    "categorize_fatal_message",
+    "categorize_warning_message",
+    "find_fatal_message",
+    "is_recoverable_message",
+]