aip-agents-binary 0.5.24__py3-none-any.whl → 0.5.25b1__py3-none-any.whl

aip_agents/storage/providers/base.pyi

@@ -0,0 +1,88 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+class StorageError(Exception):
+    """Base exception for storage operations."""
+
+class BaseStorageProvider(ABC):
+    """Base interface for storage providers.
+
+    This abstract class defines the contract that all storage providers
+    must implement to store and retrieve tool outputs.
+    """
+    @abstractmethod
+    def store(self, key: str, data: Any) -> None:
+        """Store data with the given key.
+
+        Args:
+            key: Unique identifier for the data
+            data: Data to store (must be serializable)
+
+        Raises:
+            StorageError: If storage operation fails
+        """
+    @abstractmethod
+    def retrieve(self, key: str) -> Any:
+        """Retrieve data by key.
+
+        Args:
+            key: Unique identifier for the data
+
+        Returns:
+            The stored data
+
+        Raises:
+            KeyError: If key not found
+            StorageError: If retrieval operation fails
+        """
+    @abstractmethod
+    def exists(self, key: str) -> bool:
+        """Check if key exists.
+
+        Args:
+            key: Unique identifier to check
+
+        Returns:
+            True if key exists, False otherwise
+        """
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete data by key.
+
+        Args:
+            key: Unique identifier for the data
+
+        Note:
+            Should not raise error if key doesn't exist
+        """
+    @abstractmethod
+    def list_keys(self, prefix: str = '') -> list[str]:
+        """List all keys with optional prefix filter.
+
+        Args:
+            prefix: Optional prefix to filter keys
+
+        Returns:
+            List of matching keys
+        """
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear all stored data.
+
+        Warning:
+            This operation is irreversible
+        """
+    def get_presigned_url(self, key: str, expires_hours: int = 24) -> str | None:
+        """Generate presigned URL for direct access (optional).
+
+        Args:
+            key: Storage key
+            expires_hours: URL expiration in hours
+
+        Returns:
+            Presigned URL if supported, None otherwise
+        """

aip_agents/storage/providers/memory.pyi

@@ -0,0 +1,79 @@
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from typing import Any
+
+class InMemoryStorageProvider(BaseStorageProvider):
+    """In-memory storage provider for fast access to small data.
+
+    This provider stores all data in memory, providing the fastest
+    access times but limited by available RAM.
+
+    Best for:
+    - Small to medium datasets
+    - Temporary storage
+    - Development and testing
+    - High-frequency access patterns
+    """
+    def __init__(self) -> None:
+        """Initialize in-memory storage."""
+    def store(self, key: str, data: Any) -> None:
+        """Store data in memory.
+
+        Args:
+            key: Unique identifier for the data
+            data: Data to store
+
+        Raises:
+            StorageError: If storage operation fails
+        """
+    def retrieve(self, key: str) -> Any:
+        """Retrieve data from memory.
+
+        Args:
+            key: Unique identifier for the data
+
+        Returns:
+            The stored data
+
+        Raises:
+            KeyError: If key not found
+        """
+    def exists(self, key: str) -> bool:
+        """Check if key exists in memory.
+
+        Args:
+            key: Unique identifier to check
+
+        Returns:
+            True if key exists, False otherwise
+        """
+    def delete(self, key: str) -> None:
+        """Delete data from memory.
+
+        Args:
+            key: Unique identifier for the data
+        """
+    def list_keys(self, prefix: str = '') -> list[str]:
+        """List all keys with optional prefix.
+
+        Args:
+            prefix: Optional prefix to filter keys
+
+        Returns:
+            List of matching keys
+        """
+    def clear(self) -> None:
+        """Clear all data from memory."""
+    @property
+    def size_bytes(self) -> int:
+        """Get approximate memory usage in bytes.
+
+        Returns:
+            Approximate memory usage in bytes
+        """
+    @property
+    def count(self) -> int:
+        """Get number of stored items.
+
+        Returns:
+            Number of items in storage
+        """

aip_agents/storage/providers/object_storage.pyi

@@ -0,0 +1,98 @@
+from _typeshed import Incomplete
+from aip_agents.storage.base import BaseObjectStorageClient as BaseObjectStorageClient
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+class ObjectStorageProvider(BaseStorageProvider):
+    """Object storage provider for S3-compatible storage.
+
+    Works with any S3-compatible storage including AWS S3, MinIO,
+    Google Cloud Storage (with S3 compatibility), etc.
+
+    Best for:
+    - Very large datasets
+    - Distributed systems
+    - Cloud deployments
+    - Long-term storage
+    - Multi-region access
+    """
+    client: Incomplete
+    prefix: Incomplete
+    use_json: Incomplete
+    def __init__(self, client: BaseObjectStorageClient, prefix: str = '', use_json: bool = False) -> None:
+        """Initialize object storage provider.
+
+        Args:
+            client: Object storage client instance
+            prefix: Prefix for all keys (like a directory)
+            use_json: Use JSON format (True) or pickle (False)
+        """
+    def store(self, key: str, data: Any) -> None:
+        """Store data in object storage.
+
+        Args:
+            key: Unique identifier for the data
+            data: Data to store
+
+        Raises:
+            StorageError: If storage operation fails
+        """
+    def retrieve(self, key: str) -> Any:
+        """Retrieve data from object storage.
+
+        Args:
+            key: Unique identifier for the data
+
+        Returns:
+            The stored data
+
+        Raises:
+            KeyError: If key not found
+            StorageError: If retrieval operation fails
+        """
+    def exists(self, key: str) -> bool:
+        """Check if object exists.
+
+        Args:
+            key: Unique identifier to check
+
+        Returns:
+            True if key exists, False otherwise
+        """
+    def delete(self, key: str) -> None:
+        """Delete object.
+
+        Args:
+            key: Unique identifier for the data
+        """
+    def list_keys(self, prefix: str = '') -> list[str]:
+        """List all keys with optional prefix.
+
+        Args:
+            prefix: Optional prefix to filter keys
+
+        Raises:
+            NotImplementedError: list_keys is not implemented
+        """
+    def clear(self) -> None:
+        """Clear all objects with the configured prefix.
+
+        Warning:
+            This is a dangerous operation!
+        """
+    def get_presigned_url(self, key: str, expires_hours: int = 24) -> str | None:
+        """Generate presigned URL for direct access.
+
+        Args:
+            key: Storage key
+            expires_hours: URL expiration in hours
+
+        Returns:
+            Presigned URL for direct access
+
+        Raises:
+            StorageError: If URL generation fails
+        """

aip_agents/tools/__init__.pyi

@@ -0,0 +1,9 @@
+from aip_agents.tools.browser_use import BrowserUseTool as BrowserUseTool
+from aip_agents.tools.code_sandbox import E2BCodeSandboxTool as E2BCodeSandboxTool
+from aip_agents.tools.document_loader import DocxReaderTool as DocxReaderTool, ExcelReaderTool as ExcelReaderTool, PDFReaderTool as PDFReaderTool
+from aip_agents.tools.gl_connector import GLConnectorTool as GLConnectorTool
+from aip_agents.tools.gl_connector_tools import BOSA_AUTOMATED_TOOLS as BOSA_AUTOMATED_TOOLS, GL_CONNECTORS_AUTOMATED_TOOLS as GL_CONNECTORS_AUTOMATED_TOOLS
+from aip_agents.tools.time_tool import TimeTool as TimeTool
+from aip_agents.tools.web_search import GoogleSerperTool as GoogleSerperTool
+
+__all__ = ['BOSA_AUTOMATED_TOOLS', 'GL_CONNECTORS_AUTOMATED_TOOLS', 'GLConnectorTool', 'GoogleSerperTool', 'TimeTool', 'BrowserUseTool', 'E2BCodeSandboxTool', 'DocxReaderTool', 'ExcelReaderTool', 'PDFReaderTool']

aip_agents/tools/browser_use/__init__.pyi

@@ -0,0 +1,14 @@
+from enum import StrEnum
+
+__all__ = [<ImportableName.BROWSER_USE_TOOL: 'BrowserUseTool'>, <ImportableName.BROWSER_USE_TOOL_INPUT: 'BrowserUseToolInput'>, <ImportableName.BROWSER_USE_TOOL_CONFIG: 'BrowserUseToolConfig'>]
+
+class ImportableName(StrEnum):
+    """Names of the importable attributes."""
+    BROWSER_USE_TOOL: str
+    BROWSER_USE_TOOL_INPUT: str
+    BROWSER_USE_TOOL_CONFIG: str
+
+# Names in __all__ with no definition:
+#   BrowserUseTool
+#   BrowserUseToolConfig
+#   BrowserUseToolInput

aip_agents/tools/browser_use/action_parser.pyi

@@ -0,0 +1,18 @@
+from aip_agents.tools.browser_use.types import ToolCallInfo
+from browser_use.agent.views import ActionResult, AgentOutput
+
+__all__ = ['ActionParser']
+
+class ActionParser:
+    """Dedicated class for parsing agent actions with improved error handling."""
+    @staticmethod
+    def extract_actions(model_output: AgentOutput | None, last_result: list[ActionResult] | None = None) -> list[ToolCallInfo]:
+        """Extract action information from model output.
+
+        Args:
+            model_output: The model output containing action information.
+            last_result: The last result from the agent state for output extraction.
+
+        Returns:
+            list[ToolCallInfo]: Structured action information.
+        """

aip_agents/tools/browser_use/browser_use_tool.pyi

@@ -0,0 +1,50 @@
+from _typeshed import Incomplete
+from aip_agents.tools.browser_use import session_errors as session_errors
+from aip_agents.tools.browser_use.action_parser import ActionParser as ActionParser
+from aip_agents.tools.browser_use.llm_config import build_browser_use_llm as build_browser_use_llm, configure_browser_use_environment as configure_browser_use_environment
+from aip_agents.tools.browser_use.schemas import BrowserUseToolConfig as BrowserUseToolConfig, BrowserUseToolInput as BrowserUseToolInput
+from aip_agents.tools.browser_use.session import BrowserSession as BrowserSession
+from aip_agents.tools.browser_use.steel_session_recording import SteelSessionRecorder as SteelSessionRecorder
+from aip_agents.tools.browser_use.streaming import create_error_response as create_error_response, create_step_response as create_step_response, generate_step_content as generate_step_content, generate_thinking_message as generate_thinking_message, yield_iframe_activity as yield_iframe_activity, yield_status_message as yield_status_message, yield_thinking_marker as yield_thinking_marker
+from aip_agents.tools.browser_use.structured_data_parser import detect_structured_data_failure as detect_structured_data_failure
+from aip_agents.tools.browser_use.types import BrowserUseFatalError as BrowserUseFatalError, RetryDecision as RetryDecision, StreamingResponse as StreamingResponse, StreamingState as StreamingState, ToolCallInfo as ToolCallInfo
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel as BaseModel
+
+logger: Incomplete
+
+class BrowserUseTool(BaseTool):
+    """Tool to execute web automation tasks using browser-use framework.
+
+    This tool provides step-by-step execution of browser automation tasks with detailed
+    logging of intermediate steps, including the agent's thinking process, goals, and
+    results at each step.
+    """
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]
+    MAX_SESSION_RELEASE_RETRIES: int
+    SESSION_RELEASE_SLEEP_TIME_IN_S: int
+    async def arun_streaming(self, task: str = None, config: RunnableConfig | None = None, **kwargs):
+        """Execute a web automation task using browser-use asynchronously with streaming output.
+
+        This method creates a Steel browser session, initializes a browser-use agent with
+        the specified task, and executes the automation step by step, yielding results
+        in streaming fashion. Starts background recording after completion.
+
+        Args:
+            task (str, optional): The task prompt for the AI agent to execute in the browser.
+                                 If not provided, will attempt to extract from kwargs.
+            config (RunnableConfig): RunnableConfig containing tool configuration.
+            **kwargs: Additional parameters that may contain the task or other tool-specific arguments.
+
+        Yields:
+            dict: Step-by-step results in standardized StreamingResponse format.
+
+        Raises:
+            Exception: Any exception that occurs during task execution will be caught
+                and yielded as an error message.
+        """

aip_agents/tools/browser_use/llm_config.pyi

@@ -0,0 +1,52 @@
+from browser_use.llm import ChatOpenAI
+from typing import Any
+
+__all__ = ['build_browser_use_llm', 'configure_browser_use_environment', 'model_disallows_tunable_params', 'supports_frequency_penalty', 'supports_temperature_override']
+
+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.
+    """
+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.
+    """
+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.
+    """
+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.
+    """
+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.
+    """

aip_agents/tools/browser_use/minio_storage.pyi

@@ -0,0 +1,109 @@
+from _typeshed import Incomplete
+
+OBJECT_NAME_PREFIX: str
+
+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.
+    """
+    endpoint: Incomplete
+    access_key: Incomplete
+    secret_key: Incomplete
+    secure: Incomplete
+    bucket_name: Incomplete
+    directory_prefix: Incomplete
+    client: Incomplete
+    def __init__(self) -> None:
+        """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.
+        """
+    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.
+        '''
+    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.
+        '''
+    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.
+        """

aip_agents/tools/browser_use/schemas.pyi

@@ -0,0 +1,32 @@
+from openai.types.shared.chat_model import ChatModel
+from pydantic import BaseModel
+from typing import Literal
+
+class BrowserUseToolInput(BaseModel):
+    """Input schema for Browser Use tool."""
+    task: str
+
+class BrowserUseToolConfig(BaseModel):
+    """Tool configuration schema for Browser Use tool."""
+    steel_api_key: str
+    steel_base_url: str
+    steel_ws_url: str
+    steel_timeout_in_ms: int
+    browser_use_llm_openai_api_key: str
+    browser_use_llm_openai_model: ChatModel | str
+    browser_use_llm_openai_temperature: float | None
+    browser_use_llm_openai_reasoning_effort: Literal['minimal', 'low', 'medium', 'high']
+    browser_use_llm_openai_base_url: str | None
+    browser_use_page_extraction_llm_openai_api_key: str
+    browser_use_page_extraction_llm_openai_model: ChatModel | str
+    browser_use_page_extraction_llm_openai_temperature: float | None
+    browser_use_page_extraction_llm_openai_reasoning_effort: Literal['minimal', 'low', 'medium', 'high']
+    browser_use_page_extraction_llm_openai_base_url: str | None
+    browser_use_extend_system_message: str | None
+    browser_use_vision_detail_level: Literal['auto', 'low', 'high']
+    browser_use_enable_cloud_sync: bool
+    browser_use_logging_level: Literal['debug', 'info', 'warning', 'error', 'result']
+    browser_use_llm_timeout_in_s: int
+    browser_use_step_timeout_in_s: int
+    browser_use_max_session_retries: int
+    browser_use_session_retry_delay_in_s: float

aip_agents/tools/browser_use/session.pyi

@@ -0,0 +1,4 @@
+from browser_use.browser.session import BrowserSession as BrowserUseSession
+
+class BrowserSession(BrowserUseSession):
+    """Represents an active browser session with a running browser process somewhere."""

aip_agents/tools/browser_use/session_errors.pyi

@@ -0,0 +1,53 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+__all__ = ['SessionErrorCategory', 'categorize_fatal_message', 'categorize_warning_message', 'find_fatal_message', 'is_recoverable_message']
+
+@dataclass(frozen=True)
+class SessionErrorCategory:
+    """Represents a fatal Steel/browser disconnect classification."""
+    name: str
+    markers: tuple[str, ...]
+    fatal: bool
+    retryable: bool
+
+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.
+    """
+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.
+    """
+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.
+    """
+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.
+    """

aip_agents/tools/browser_use/steel_session_recording.pyi

@@ -0,0 +1,63 @@
+from _typeshed import Incomplete
+from aip_agents.tools.browser_use.minio_storage import MinIOStorage as MinIOStorage
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+VIDEO_FILE_NAME_PREFIX: str
+MANIFEST_TEMP_SUFFIX: str
+
+class SteelSessionRecorder:
+    """High-level helper to export Steel sessions via their HLS manifests.
+
+    This class provides a high-level interface for exporting Steel sessions via their HLS manifests.
+    It provides methods for sanitizing session IDs, building safe filenames, and generating video filenames.
+    It also provides methods for downloading and merging HLS manifests, and uploading videos to MinIO.
+    """
+    @staticmethod
+    def safe_session_id(session_id: str) -> str:
+        """Sanitize a session ID for filename usage.
+
+        Args:
+            session_id: The session ID to sanitize.
+
+        Returns:
+            str: The sanitized session ID.
+        """
+    @staticmethod
+    def safe_session_filename(session_id: str, extension: str) -> str:
+        """Build a safe filename for a session recording.
+
+        Args:
+            session_id: The session ID to build a filename for.
+            extension: The extension of the filename.
+
+        Returns:
+            str: The safe filename.
+        """
+    @staticmethod
+    def generate_video_filename(session_id: str, extension: str = '.mp4') -> str:
+        """Generate a filename for a session recording.
+
+        Args:
+            session_id: The session ID to generate a filename for.
+            extension: The extension of the filename.
+
+        Returns:
+            str: The generated filename.
+        """
+    base_url: Incomplete
+    api_key: Incomplete
+    minio_storage: Incomplete
+    def __init__(self, base_url: str, api_key: str) -> None:
+        """Initialize the recorder.
+
+        Args:
+            base_url: Steel API base URL.
+            api_key: Steel API key for authentication.
+        """
+    async def record_session_to_video(self, session_id: str) -> None:
+        """Download the HLS manifest and upload the merged video to MinIO.
+
+        Args:
+            session_id: The session ID to record.
+        """