aip-agents-binary 0.5.18__py3-none-any.whl → 0.5.19__py3-none-any.whl

aip_agents/storage/clients/minio_client.pyi

@@ -0,0 +1,137 @@
+from _typeshed import Incomplete
+from aip_agents.storage.base import BaseObjectStorageClient as BaseObjectStorageClient
+from dataclasses import dataclass
+from typing import BinaryIO
+
+S3_ERR_NO_SUCH_KEY: str
+S3_ERR_NO_SUCH_BUCKET: str
+S3_ERR_ACCESS_DENIED: str
+
+@dataclass
+class MinioConfig:
+    """Configuration for MinIO object storage client.
+
+    Attributes:
+        endpoint: MinIO server endpoint URL
+        access_key: Access key for authentication
+        secret_key: Secret key for authentication
+        bucket: Bucket name to use for storage
+        secure: Whether to use HTTPS (defaults to True)
+    """
+    endpoint: str
+    access_key: str
+    secret_key: str
+    bucket: str
+    secure: bool = ...
+    @classmethod
+    def from_env(cls) -> MinioConfig:
+        """Create MinioConfig from environment variables.
+
+        Expected environment variables:
+        - OBJECT_STORAGE_URL
+        - OBJECT_STORAGE_USER
+        - OBJECT_STORAGE_PASSWORD
+        - OBJECT_STORAGE_BUCKET
+        - OBJECT_STORAGE_SECURE (optional, defaults to True)
+
+        Returns:
+            MinioConfig instance
+
+        Raises:
+            ValueError: If required environment variables are not set
+        """
+
+class MinioObjectStorage(BaseObjectStorageClient):
+    """Implementation of ObjectStorageInterface using Minio."""
+    config: Incomplete
+    client: Incomplete
+    bucket: Incomplete
+    def __init__(self, config: MinioConfig | None = None, ensure_bucket: bool = True) -> None:
+        """Initialize MinioObjectStorage with configuration.
+
+        Args:
+            config: MinioConfig instance. If None, will attempt to load from environment variables.
+            ensure_bucket: Whether to ensure bucket exists during initialization (optional). Defaults to True.
+
+        Raises:
+            ValueError: If configuration is invalid or incomplete
+        """
+    def upload(self, object_key: str, file_stream: bytes | BinaryIO, filename: str | None = None, content_type: str | None = None, metadata: dict[str, str] | None = None) -> str:
+        """Upload data to Minio object storage.
+
+        Args:
+            object_key: The key to store the object under
+            file_stream: The data to upload (bytes or file-like object)
+            filename: The filename of the data (optional)
+            content_type: The content type of the data (optional)
+            metadata: Additional metadata to store with the object (optional)
+
+        Returns:
+            The object key of the uploaded data
+
+        Raises:
+            ValueError: If the file stream is empty or invalid
+            ConnectionError: If there's an issue connecting to Minio
+            Exception: For other unexpected errors during upload
+        """
+    def get(self, object_key: str) -> bytes:
+        """Get data from Minio object storage.
+
+        Args:
+            object_key: The key of the object to retrieve
+
+        Returns:
+            The object data as bytes
+
+        Raises:
+            KeyError: If the object is not found
+            ConnectionError: If there's a network or connection issue
+        """
+    def delete(self, object_key: str) -> None:
+        """Delete data from Minio object storage.
+
+        Args:
+            object_key: The key of the object to delete
+
+        Raises:
+            ConnectionError: If there's a network or connection issue
+        """
+    def object_exists(self, object_key: str) -> bool:
+        """Check if an object exists in the MinIO bucket.
+
+        Args:
+            object_key: The key of the object to check.
+
+        Returns:
+            True if the object exists, False otherwise.
+
+        Raises:
+            ConnectionError: If there's a network or connection issue (excluding not found errors)
+        """
+    def list_objects(self, prefix: str = '') -> list[str]:
+        """List objects in the bucket with optional prefix filter.
+
+        Args:
+            prefix: Optional prefix to filter objects
+
+        Returns:
+            List of object keys
+
+        Raises:
+            ConnectionError: If there's an issue listing objects
+        """
+    def generate_presigned_url(self, object_key: str, expires: int = 24, response_headers: dict[str, str] | None = None) -> str:
+        """Generate a presigned URL for accessing the object.
+
+        Args:
+            object_key: The key of the object
+            expires: Expiration time in hours (defaults to 24)
+            response_headers: Additional response headers (optional)
+
+        Returns:
+            A presigned URL
+
+        Raises:
+            ValueError: If expiration time is not positive
+            ConnectionError: If there's an issue generating the URL
+        """

aip_agents/storage/config.pyi

@@ -0,0 +1,29 @@
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX as OBJECT_STORAGE_PREFIX, StorageConfig as StorageConfig, StorageType as StorageType
+from aip_agents.storage.base import BaseObjectStorageClient
+from aip_agents.storage.providers.base import BaseStorageProvider
+
+__all__ = ['OBJECT_STORAGE_PREFIX', 'StorageConfig', 'StorageType', 'StorageProviderFactory']
+
+class StorageProviderFactory:
+    """Factory for creating storage providers based on configuration."""
+    @staticmethod
+    def create(config: StorageConfig, object_storage_client: BaseObjectStorageClient | None = None) -> BaseStorageProvider:
+        """Create storage provider based on configuration.
+
+        Args:
+            config (StorageConfig): Storage configuration object.
+            object_storage_client (BaseObjectStorageClient | None, optional): Optional object storage client for object storage type.
+
+        Returns:
+            BaseStorageProvider: The created storage provider instance.
+        """
+    @staticmethod
+    def create_from_env(object_storage_client: BaseObjectStorageClient | None = None) -> BaseStorageProvider:
+        """Create storage provider from environment variables.
+
+        Args:
+            object_storage_client (BaseObjectStorageClient | None, optional): Optional object storage client for object storage type.
+
+        Returns:
+            BaseStorageProvider: The created storage provider instance.
+        """

aip_agents/storage/providers/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider as InMemoryStorageProvider
+from aip_agents.storage.providers.object_storage import ObjectStorageProvider as ObjectStorageProvider
+
+__all__ = ['BaseStorageProvider', 'StorageError', 'InMemoryStorageProvider', 'ObjectStorageProvider']

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,4 @@
+from aip_agents.tools.bosa_tools import BOSA_AUTOMATED_TOOLS as BOSA_AUTOMATED_TOOLS
+from aip_agents.tools.gl_connector import GLConnectorTool as GLConnectorTool
+
+__all__ = ['BOSA_AUTOMATED_TOOLS', 'GLConnectorTool']

aip_agents/tools/bosa_tools.pyi

@@ -0,0 +1,37 @@
+from _typeshed import Incomplete
+from aip_agents.tools.constants import BOSA_API_BASE_URL as BOSA_API_BASE_URL, BOSA_API_KEY as BOSA_API_KEY, BOSA_FETCH_MAX_RETRIES as BOSA_FETCH_MAX_RETRIES, ToolType as ToolType
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool as BaseTool
+
+logger: Incomplete
+
+def get_bosa_modules_with_retry() -> list[str]:
+    """Try to get available modules with retries.
+
+    Returns:
+        List of available modules.
+    """
+
+class LazyBosaToolsDict(dict):
+    """Lazy dictionary for BOSA tools."""
+    def __missing__(self, app):
+        """When a key is missing, create the tools and store them in the dictionary.
+
+        Args:
+            app: Name of the BOSA connector.
+
+        Returns:
+            List of tools generated by BOSAConnectorToolGenerator.
+        """
+
+def get_bosa_modules() -> list[str]:
+    """Lazily fetch and cache BOSA modules.
+
+    This is for backwards compatibility with the old BOSA modules.
+
+    Returns:
+        List of BOSA modules.
+    """
+
+BOSA_MODULES: Incomplete
+BOSA_AUTOMATED_TOOLS: dict[str, list[BaseTool]]

aip_agents/tools/browser_use/__init__.py

@@ -19,7 +19,7 @@ try:
 except ImportError:
     _TOOL_AVAILABLE = False
     warnings.warn(
-        "Browser use tools not available. Install with: pip install aip-agents[browser-use-tool]",
+        "Browser use tools not available. Install with: pip install aip-agents[local]",
         ImportWarning,
         stacklevel=2,
     )

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.
+    """