ag2 0.9.1__py3-none-any.whl → 0.9.1.post0__py3-none-any.whl

autogen/tools/experimental/duckduckgo/duckduckgo_search.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+from typing import Annotated, Any
+
+from ....doc_utils import export_module
+from ....import_utils import optional_import_block, require_optional_import
+from ... import Tool
+
+with optional_import_block():
+    from duckduckgo_search import DDGS
+
+
+@require_optional_import(
+    [
+        "duckduckgo_search",
+    ],
+    "duckduckgo_search",
+)
+def _execute_duckduckgo_query(
+    query: str,
+    num_results: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Execute a search query using the DuckDuckGo Search API.
+
+    Args:
+        query (str): The search query string.
+        num_results (int, optional): The maximum number of results to return. Defaults to 5.
+
+    Returns:
+        list[dict[str, Any]]: A list of search results from the DuckDuckGo API.
+    """
+    with DDGS() as ddgs:
+        try:
+            # region='wt-wt' means worldwide
+            results = list(ddgs.text(query, region="wt-wt", max_results=num_results))
+        except Exception as e:
+            print(f"DuckDuckGo Search failed: {e}")
+            results = []
+    return results
+
+
+def _duckduckgo_search(
+    query: str,
+    num_results: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Perform a DuckDuckGo search and format the results.
+
+    This function takes search parameters, executes the query using `_execute_duckduckgo_query`,
+    and formats the results into a list of dictionaries containing title, link, and snippet.
+
+    Args:
+        query (str): The search query string.
+        num_results (int, optional): The maximum number of results to return. Defaults to 5.
+
+    Returns:
+        list[dict[str, Any]]: A list of dictionaries, where each dictionary represents a search result
+            with keys 'title', 'link', and 'snippet'. Returns an empty list if no results are found.
+    """
+    res = _execute_duckduckgo_query(
+        query=query,
+        num_results=num_results,
+    )
+
+    return [
+        {"title": item.get("title", ""), "link": item.get("href", ""), "snippet": item.get("body", "")} for item in res
+    ]
+
+
+@export_module("autogen.tools.experimental")
+class DuckDuckGoSearchTool(Tool):
+    """
+    DuckDuckGoSearchTool is a tool that uses DuckDuckGo to perform a search.
+
+    This tool allows agents to leverage the DuckDuckGo search engine for information retrieval.
+    DuckDuckGo does not require an API key, making it easy to use.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes the DuckDuckGoSearchTool.
+        """
+
+        def duckduckgo_search(
+            query: Annotated[str, "The search query."],
+            num_results: Annotated[int, "The number of results to return."] = 5,
+        ) -> list[dict[str, Any]]:
+            """
+            Performs a search using the DuckDuckGo Search API and returns formatted results.
+
+            Args:
+                query: The search query string.
+                num_results: The maximum number of results to return. Defaults to 5.
+
+            Returns:
+                A list of dictionaries, each containing 'title', 'link', and 'snippet' of a search result.
+            """
+            return _duckduckgo_search(
+                query=query,
+                num_results=num_results,
+            )
+
+        super().__init__(
+            name="duckduckgo_search",
+            description="Use the DuckDuckGo Search API to perform a search.",
+            func_or_tool=duckduckgo_search,
+        )

autogen/tools/experimental/google/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .authentication import GoogleCredentialsLocalProvider, GoogleCredentialsProvider
+from .drive import GoogleDriveToolkit
+from .toolkit_protocol import GoogleToolkitProtocol
+
+__all__ = [
+    "GoogleCredentialsLocalProvider",
+    "GoogleCredentialsProvider",
+    "GoogleDriveToolkit",
+    "GoogleToolkitProtocol",
+]

autogen/tools/experimental/google/authentication/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .credentials_local_provider import GoogleCredentialsLocalProvider
+from .credentials_provider import GoogleCredentialsProvider
+
+__all__ = [
+    "GoogleCredentialsLocalProvider",
+    "GoogleCredentialsProvider",
+]

autogen/tools/experimental/google/authentication/credentials_hosted_provider.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from .....doc_utils import export_module
+from .....import_utils import optional_import_block
+from .credentials_provider import GoogleCredentialsProvider
+
+with optional_import_block():
+    from google.oauth2.credentials import Credentials
+
+
+__all__ = ["GoogleCredenentialsHostedProvider"]
+
+
+@export_module("autogen.tools.experimental.google.authentication")
+class GoogleCredenentialsHostedProvider(GoogleCredentialsProvider):
+    def __init__(
+        self,
+        host: str,
+        port: int = 8080,
+        *,
+        kwargs: dict[str, str],
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._kwargs = kwargs
+
+        raise NotImplementedError("This class is not implemented yet.")
+
+    @property
+    def host(self) -> str:
+        """The host from which to get the credentials."""
+        return self._host
+
+    @property
+    def port(self) -> int:
+        """The port from which to get the credentials."""
+        return self._port
+
+    def get_credentials(self) -> "Credentials":  # type: ignore[no-any-unimported]
+        raise NotImplementedError("This class is not implemented yet.")

autogen/tools/experimental/google/authentication/credentials_local_provider.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+import os
+from typing import Optional
+
+from .....doc_utils import export_module
+from .....import_utils import optional_import_block, require_optional_import
+from .credentials_provider import GoogleCredentialsProvider
+
+with optional_import_block():
+    from google.auth.transport.requests import Request
+    from google.oauth2.credentials import Credentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+
+__all__ = ["GoogleCredentialsLocalProvider"]
+
+
+@export_module("autogen.tools.experimental.google.authentication")
+class GoogleCredentialsLocalProvider(GoogleCredentialsProvider):
+    def __init__(
+        self,
+        client_secret_file: str,
+        scopes: list[str],  # e.g. ['https://www.googleapis.com/auth/drive/readonly']
+        token_file: Optional[str] = None,
+        port: int = 8080,
+    ) -> None:
+        """A Google credentials provider that gets the credentials locally.
+
+        Args:
+            client_secret_file (str): The path to the client secret file.
+            scopes (list[str]): The scopes to request.
+            token_file (str): Optional path to the token file. If not provided, the token will not be saved.
+            port (int): The port from which to get the credentials.
+        """
+        self.client_secret_file = client_secret_file
+        self.scopes = scopes
+        self.token_file = token_file
+        self._port = port
+
+    @property
+    def host(self) -> str:
+        """Localhost is the default host."""
+        return "localhost"
+
+    @property
+    def port(self) -> int:
+        """The port from which to get the credentials."""
+        return self._port
+
+    @require_optional_import(
+        [
+            "google_auth_httplib2",
+            "google_auth_oauthlib",
+        ],
+        "google-api",
+    )
+    def _refresh_or_get_new_credentials(self, creds: Optional["Credentials"]) -> "Credentials":  # type: ignore[no-any-unimported]
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())  # type: ignore[no-untyped-call]
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(self.client_secret_file, self.scopes)
+            creds = flow.run_local_server(host=self.host, port=self.port)
+        return creds  # type: ignore[return-value]
+
+    @require_optional_import(
+        [
+            "google_auth_httplib2",
+            "google_auth_oauthlib",
+        ],
+        "google-api",
+    )
+    def get_credentials(self) -> "Credentials":  # type: ignore[no-any-unimported]
+        """Get the Google credentials."""
+        creds = None
+        if self.token_file and os.path.exists(self.token_file):
+            creds = Credentials.from_authorized_user_file(self.token_file)  # type: ignore[no-untyped-call]
+
+        # If there are no (valid) credentials available, let the user log in.
+        if not creds or not creds.valid:
+            creds = self._refresh_or_get_new_credentials(creds)
+
+            if self.token_file:
+                # Save the credentials for the next run
+                with open(self.token_file, "w") as token:
+                    token.write(creds.to_json())  # type: ignore[no-untyped-call]
+
+        return creds  # type: ignore[no-any-return]

autogen/tools/experimental/google/authentication/credentials_provider.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from typing import Optional, Protocol, runtime_checkable
+
+from .....doc_utils import export_module
+from .....import_utils import optional_import_block
+
+with optional_import_block():
+    from google.oauth2.credentials import Credentials
+
+
+__all__ = ["GoogleCredentialsProvider"]
+
+
+@runtime_checkable
+@export_module("autogen.tools.experimental.google.authentication")
+class GoogleCredentialsProvider(Protocol):
+    """A protocol for Google credentials provider."""
+
+    def get_credentials(self) -> Optional["Credentials"]:  # type: ignore[no-any-unimported]
+        """Get the Google credentials."""
+        ...
+
+    @property
+    def host(self) -> str:
+        """The host from which to get the credentials."""
+        ...
+
+    @property
+    def port(self) -> int:
+        """The port from which to get the credentials."""
+        ...

autogen/tools/experimental/google/drive/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .toolkit import GoogleDriveToolkit
+
+__all__ = [
+    "GoogleDriveToolkit",
+]

autogen/tools/experimental/google/drive/drive_functions.py

@@ -0,0 +1,124 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import io
+from pathlib import Path
+from typing import Any, Optional
+
+from .....import_utils import optional_import_block, require_optional_import
+from ..model import GoogleFileInfo
+
+with optional_import_block():
+    from googleapiclient.http import MediaIoBaseDownload
+
+
+__all__ = [
+    "download_file",
+    "list_files_and_folders",
+]
+
+
+@require_optional_import(
+    [
+        "googleapiclient",
+    ],
+    "google-api",
+)
+def list_files_and_folders(service: Any, page_size: int, folder_id: Optional[str]) -> list[GoogleFileInfo]:
+    kwargs = {
+        "pageSize": page_size,
+        "fields": "nextPageToken, files(id, name, mimeType)",
+    }
+    if folder_id:
+        kwargs["q"] = f"'{folder_id}' in parents and trashed=false"  # Search for files in the folder
+    response = service.files().list(**kwargs).execute()
+    result = response.get("files", [])
+    if not isinstance(result, list):
+        raise ValueError(f"Expected a list of files, but got {result}")
+    result = [GoogleFileInfo(**file_info) for file_info in result]
+    return result
+
+
+def _get_file_extension(mime_type: str) -> Optional[str]:
+    """Returns the correct file extension for a given MIME type."""
+    mime_extensions = {
+        "application/vnd.google-apps.document": "docx",  # Google Docs → Word
+        "application/vnd.google-apps.spreadsheet": "csv",  # Google Sheets → CSV
+        "application/vnd.google-apps.presentation": "pptx",  # Google Slides → PowerPoint
+        "video/quicktime": "mov",
+        "application/vnd.google.colaboratory": "ipynb",
+        "application/pdf": "pdf",
+        "image/jpeg": "jpg",
+        "image/png": "png",
+        "text/plain": "txt",
+        "application/zip": "zip",
+    }
+
+    return mime_extensions.get(mime_type)
+
+
+@require_optional_import(
+    [
+        "googleapiclient",
+    ],
+    "google-api",
+)
+def download_file(
+    service: Any,
+    file_id: str,
+    file_name: str,
+    mime_type: str,
+    download_folder: Path,
+    subfolder_path: Optional[str] = None,
+) -> str:
+    """Download or export file based on its MIME type, optionally saving to a subfolder."""
+    file_extension = _get_file_extension(mime_type)
+    if file_extension and (not file_name.lower().endswith(file_extension.lower())):
+        file_name = f"{file_name}.{file_extension}"
+
+    # Define export formats for Google Docs, Sheets, and Slides
+    export_mime_types = {
+        "application/vnd.google-apps.document": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",  # Google Docs → Word
+        "application/vnd.google-apps.spreadsheet": "text/csv",  # Google Sheets → CSV
+        "application/vnd.google-apps.presentation": "application/vnd.openxmlformats-officedocument.presentationml.presentation",  # Google Slides → PowerPoint
+    }
+
+    # Google Docs, Sheets, and Slides cannot be downloaded directly using service.files().get_media() because they are Google-native files
+    if mime_type in export_mime_types:
+        request = service.files().export(fileId=file_id, mimeType=export_mime_types[mime_type])
+    else:
+        # Download normal files (videos, images, etc.)
+        request = service.files().get_media(fileId=file_id)
+
+    # Determine the final destination directory
+    destination_dir = download_folder
+    if subfolder_path:
+        destination_dir = download_folder / subfolder_path
+        # Ensure the subfolder exists, create it if necessary
+        destination_dir.mkdir(parents=True, exist_ok=True)
+
+    # Construct the full path for the file
+    file_path = destination_dir / file_name
+
+    # Save file
+    try:
+        with io.BytesIO() as buffer:
+            downloader = MediaIoBaseDownload(buffer, request)
+            done = False
+            while not done:
+                _, done = downloader.next_chunk()
+
+            buffer.seek(0)
+
+            with open(file_path, "wb") as f:
+                f.write(buffer.getvalue())
+
+        # Print out the relative path of the downloaded file
+        relative_path = Path(subfolder_path) / file_name if subfolder_path else Path(file_name)
+        return f"✅ Downloaded: {relative_path}"
+
+    except Exception as e:
+        # Error message if unable to download
+        relative_path = Path(subfolder_path) / file_name if subfolder_path else Path(file_name)
+        return f"❌ FAILED to download {relative_path}: {e}"

autogen/tools/experimental/google/drive/toolkit.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+from typing import Annotated, Literal, Optional, Union
+
+from .....doc_utils import export_module
+from .....import_utils import optional_import_block
+from .... import Toolkit, tool
+from ..model import GoogleFileInfo
+from ..toolkit_protocol import GoogleToolkitProtocol
+from .drive_functions import download_file, list_files_and_folders
+
+with optional_import_block():
+    from google.oauth2.credentials import Credentials
+    from googleapiclient.discovery import build
+
+__all__ = [
+    "GoogleDriveToolkit",
+]
+
+
+@export_module("autogen.tools.experimental.google.drive")
+class GoogleDriveToolkit(Toolkit, GoogleToolkitProtocol):
+    """A tool map for Google Drive."""
+
+    def __init__(  # type: ignore[no-any-unimported]
+        self,
+        *,
+        credentials: "Credentials",
+        download_folder: Union[Path, str],
+        exclude: Optional[list[Literal["list_drive_files_and_folders", "download_file_from_drive"]]] = None,
+        api_version: str = "v3",
+    ) -> None:
+        """Initialize the Google Drive tool map.
+
+        Args:
+            credentials: The Google OAuth2 credentials.
+            download_folder: The folder to download files to.
+            exclude: The tool names to exclude.
+            api_version: The Google Drive API version to use."
+        """
+        self.service = build(serviceName="drive", version=api_version, credentials=credentials)
+
+        if isinstance(download_folder, str):
+            download_folder = Path(download_folder)
+        download_folder.mkdir(parents=True, exist_ok=True)
+
+        @tool(description="List files and folders in a Google Drive")
+        def list_drive_files_and_folders(
+            page_size: Annotated[int, "The number of files to list per page."] = 10,
+            folder_id: Annotated[
+                Optional[str],
+                "The ID of the folder to list files from. If not provided, lists all files in the root folder.",
+            ] = None,
+        ) -> list[GoogleFileInfo]:
+            return list_files_and_folders(service=self.service, page_size=page_size, folder_id=folder_id)
+
+        @tool(description="download a file from Google Drive")
+        def download_file_from_drive(
+            file_info: Annotated[GoogleFileInfo, "The file info to download."],
+            subfolder_path: Annotated[
+                Optional[str],
+                "The subfolder path to save the file in. If not provided, saves in the main download folder.",
+            ] = None,
+        ) -> str:
+            return download_file(
+                service=self.service,
+                file_id=file_info.id,
+                file_name=file_info.name,
+                mime_type=file_info.mime_type,
+                download_folder=download_folder,
+                subfolder_path=subfolder_path,
+            )
+
+        if exclude is None:
+            exclude = []
+
+        tools = [tool for tool in [list_drive_files_and_folders, download_file_from_drive] if tool.name not in exclude]
+        super().__init__(tools=tools)
+
+    @classmethod
+    def recommended_scopes(cls) -> list[str]:
+        """Return the recommended scopes manatory for using tools from this tool map."""
+        return [
+            "https://www.googleapis.com/auth/drive.readonly",
+        ]

autogen/tools/experimental/google/model.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "GoogleFileInfo",
+]
+
+
+class GoogleFileInfo(BaseModel):
+    name: Annotated[str, Field(description="The name of the file.")]
+    id: Annotated[str, Field(description="The ID of the file.")]
+    mime_type: Annotated[str, Field(alias="mimeType", description="The MIME type of the file.")]

autogen/tools/experimental/google/toolkit_protocol.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Protocol, runtime_checkable
+
+__all__ = [
+    "GoogleToolkitProtocol",
+]
+
+
+@runtime_checkable
+class GoogleToolkitProtocol(Protocol):
+    """A protocol for Google tool maps."""
+
+    @classmethod
+    def recommended_scopes(cls) -> list[str]:
+        """Defines a required static method without implementation."""
+        ...

autogen/tools/experimental/google_search/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .google_search import GoogleSearchTool
+from .youtube_search import YoutubeSearchTool
+
+__all__ = ["GoogleSearchTool", "YoutubeSearchTool"]

autogen/tools/experimental/google_search/google_search.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+import logging
+from typing import Annotated, Any, Optional
+
+from ....doc_utils import export_module
+from ....import_utils import optional_import_block, require_optional_import
+from ... import Depends, Tool
+from ...dependency_injection import on
+
+with optional_import_block():
+    from googleapiclient.discovery import build
+
+
+@require_optional_import(
+    [
+        "googleapiclient",
+    ],
+    "google-search",
+)
+def _execute_query(query: str, search_api_key: str, search_engine_id: str, num_results: int) -> Any:
+    service = build("customsearch", "v1", developerKey=search_api_key)
+    return service.cse().list(q=query, cx=search_engine_id, num=num_results).execute()
+
+
+def _google_search(
+    query: str,
+    search_api_key: str,
+    search_engine_id: str,
+    num_results: int,
+) -> list[dict[str, Any]]:
+    res = _execute_query(
+        query=query, search_api_key=search_api_key, search_engine_id=search_engine_id, num_results=num_results
+    )
+
+    return [
+        {"title": item.get("title", ""), "link": item.get("link", ""), "snippet": item.get("snippet", "")}
+        for item in res.get("items", [])
+    ]
+
+
+@export_module("autogen.tools.experimental")
+class GoogleSearchTool(Tool):
+    """GoogleSearchTool is a tool that uses the Google Search API to perform a search."""
+
+    def __init__(
+        self,
+        *,
+        search_api_key: Optional[str] = None,
+        search_engine_id: Optional[str] = None,
+        use_internal_llm_tool_if_available: bool = True,
+    ):
+        """GoogleSearchTool is a tool that uses the Google Search API to perform a search.
+
+        Args:
+            search_api_key: The API key for the Google Search API.
+            search_engine_id: The search engine ID for the Google Search API.
+            use_internal_llm_tool_if_available: Whether to use the predefined (e.g. Gemini GenaAI) search tool. Currently, this can only be used for agents with the Gemini (GenAI) configuration.
+        """
+        self.search_api_key = search_api_key
+        self.search_engine_id = search_engine_id
+        self.use_internal_llm_tool_if_available = use_internal_llm_tool_if_available
+
+        if not use_internal_llm_tool_if_available and (search_api_key is None or search_engine_id is None):
+            raise ValueError(
+                "search_api_key and search_engine_id must be provided if use_internal_llm_tool_if_available is False"
+            )
+
+        if use_internal_llm_tool_if_available and (search_api_key is not None or search_engine_id is not None):
+            logging.warning("search_api_key and search_engine_id will be ignored if internal LLM tool is available")
+
+        def google_search(
+            query: Annotated[str, "The search query."],
+            search_api_key: Annotated[Optional[str], Depends(on(search_api_key))],
+            search_engine_id: Annotated[Optional[str], Depends(on(search_engine_id))],
+            num_results: Annotated[int, "The number of results to return."] = 10,
+        ) -> list[dict[str, Any]]:
+            if search_api_key is None or search_engine_id is None:
+                raise ValueError(
+                    "Your LLM is not configured to use prebuilt google-search tool.\n"
+                    "Please provide search_api_key and search_engine_id.\n"
+                )
+            return _google_search(query, search_api_key, search_engine_id, num_results)
+
+        super().__init__(
+            # GeminiClient will look for a tool with the name "prebuilt_google_search"
+            name="prebuilt_google_search" if use_internal_llm_tool_if_available else "google_search",
+            description="Use the Google Search API to perform a search.",
+            func_or_tool=google_search,
+        )