ag2 0.10.2__py3-none-any.whl

autogen/tools/experimental/google_search/youtube_search.py

@@ -0,0 +1,181 @@
+# 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
+
+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():
+    import googleapiclient.errors
+    from googleapiclient.discovery import build
+
+
+@require_optional_import(
+    ["googleapiclient"],
+    "google-search",
+)
+def _execute_search_query(query: str, youtube_api_key: str, max_results: int) -> Any:
+    """Execute a YouTube search query using the YouTube Data API.
+
+    Args:
+        query: The search query string.
+        youtube_api_key: The API key for the YouTube Data API.
+        max_results: The maximum number of results to return.
+
+    Returns:
+        The search response from the YouTube Data API.
+    """
+    youtube = build("youtube", "v3", developerKey=youtube_api_key)
+
+    try:
+        search_response = (
+            youtube.search().list(q=query, part="id,snippet", maxResults=max_results, type="video").execute()
+        )
+
+        return search_response
+    except googleapiclient.errors.HttpError as e:
+        logging.error(f"An HTTP error occurred: {e}")
+        raise
+
+
+@require_optional_import(
+    ["googleapiclient"],
+    "google-search",
+)
+def _get_video_details(video_ids: list[str], youtube_api_key: str) -> Any:
+    """Get detailed information about specific YouTube videos.
+
+    Args:
+        video_ids: List of YouTube video IDs.
+        youtube_api_key: The API key for the YouTube Data API.
+
+    Returns:
+        The video details response from the YouTube Data API.
+    """
+    if not video_ids:
+        return {"items": []}
+
+    youtube = build("youtube", "v3", developerKey=youtube_api_key)
+
+    try:
+        videos_response = (
+            youtube.videos().list(id=",".join(video_ids), part="snippet,contentDetails,statistics").execute()
+        )
+
+        return videos_response
+    except googleapiclient.errors.HttpError as e:
+        logging.error(f"An HTTP error occurred: {e}")
+        raise
+
+
+def _youtube_search(
+    query: str,
+    youtube_api_key: str,
+    max_results: int,
+    include_video_details: bool = True,
+) -> list[dict[str, Any]]:
+    """Search YouTube videos based on a query.
+
+    Args:
+        query: The search query string.
+        youtube_api_key: The API key for the YouTube Data API.
+        max_results: The maximum number of results to return.
+        include_video_details: Whether to include detailed video information.
+
+    Returns:
+        A list of dictionaries containing information about the videos.
+    """
+    search_response = _execute_search_query(query=query, youtube_api_key=youtube_api_key, max_results=max_results)
+
+    results = []
+    video_ids = []
+
+    # Extract basic info from search results
+    for item in search_response.get("items", []):
+        if item["id"]["kind"] == "youtube#video":
+            video_ids.append(item["id"]["videoId"])
+            video_info = {
+                "title": item["snippet"]["title"],
+                "description": item["snippet"]["description"],
+                "publishedAt": item["snippet"]["publishedAt"],
+                "channelTitle": item["snippet"]["channelTitle"],
+                "videoId": item["id"]["videoId"],
+                "url": f"https://www.youtube.com/watch?v={item['id']['videoId']}",
+            }
+            results.append(video_info)
+
+    # If detailed info requested, get it
+    if include_video_details and video_ids:
+        video_details = _get_video_details(video_ids, youtube_api_key)
+
+        # Create a mapping of videoId to details
+        details_map = {item["id"]: item for item in video_details.get("items", [])}
+
+        # Update results with additional details
+        for result in results:
+            video_id = result["videoId"]
+            if video_id in details_map:
+                details = details_map[video_id]
+                result.update({
+                    "viewCount": details["statistics"].get("viewCount"),
+                    "likeCount": details["statistics"].get("likeCount"),
+                    "commentCount": details["statistics"].get("commentCount"),
+                    "duration": details["contentDetails"].get("duration"),
+                    "definition": details["contentDetails"].get("definition"),
+                })
+
+    return results
+
+
+@export_module("autogen.tools.experimental")
+class YoutubeSearchTool(Tool):
+    """YoutubeSearchTool is a tool that uses the YouTube Data API to search for videos."""
+
+    def __init__(
+        self,
+        *,
+        youtube_api_key: str | None = None,
+    ):
+        """Initialize a YouTube search tool.
+
+        Args:
+            youtube_api_key: The API key for the YouTube Data API.
+        """
+        self.youtube_api_key = youtube_api_key
+
+        if youtube_api_key is None:
+            raise ValueError("youtube_api_key must be provided")
+
+        def youtube_search(
+            query: Annotated[str, "The search query for YouTube videos."],
+            youtube_api_key: Annotated[str, Depends(on(youtube_api_key))],
+            max_results: Annotated[int, "The maximum number of results to return."] = 5,
+            include_video_details: Annotated[bool, "Whether to include detailed video information."] = True,
+        ) -> list[dict[str, Any]]:
+            """Search for YouTube videos based on a query.
+
+            Args:
+                query: The search query string.
+                youtube_api_key: The API key for the YouTube Data API.
+                max_results: The maximum number of results to return.
+                include_video_details: Whether to include detailed video information.
+
+            Returns:
+                A list of dictionaries containing information about the videos.
+            """
+            if youtube_api_key is None:
+                raise ValueError("YouTube API key is required")
+
+            return _youtube_search(query, youtube_api_key, max_results, include_video_details)
+
+        super().__init__(
+            name="youtube_search",
+            description="Search for YouTube videos based on a query, optionally including detailed information.",
+            func_or_tool=youtube_search,
+        )

autogen/tools/experimental/messageplatform/__init__.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 .discord import DiscordRetrieveTool, DiscordSendTool
+from .slack import SlackRetrieveRepliesTool, SlackRetrieveTool, SlackSendTool
+from .telegram import TelegramRetrieveTool, TelegramSendTool
+
+__all__ = [
+    "DiscordRetrieveTool",
+    "DiscordSendTool",
+    "SlackRetrieveRepliesTool",
+    "SlackRetrieveTool",
+    "SlackSendTool",
+    "TelegramRetrieveTool",
+    "TelegramSendTool",
+]

autogen/tools/experimental/messageplatform/discord/__init__.py

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

autogen/tools/experimental/messageplatform/discord/discord.py

@@ -0,0 +1,284 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Annotated, Any
+
+from .....doc_utils import export_module
+from .....import_utils import optional_import_block, require_optional_import
+from .... import Tool
+from ....dependency_injection import Depends, on
+
+__all__ = ["DiscordRetrieveTool", "DiscordSendTool"]
+
+with optional_import_block():
+    from discord import Client, Intents, utils
+
+MAX_MESSAGE_LENGTH = 2000
+MAX_BATCH_RETRIEVE_MESSAGES = 100  # Discord's max per request
+
+
+@require_optional_import(["discord"], "commsagent-discord")
+@export_module("autogen.tools.experimental")
+class DiscordSendTool(Tool):
+    """Sends a message to a Discord channel."""
+
+    def __init__(self, *, bot_token: str, channel_name: str, guild_name: str) -> None:
+        """Initialize the DiscordSendTool.
+
+        Args:
+            bot_token: The bot token to use for sending messages.
+            channel_name: The name of the channel to send messages to.
+            guild_name: The name of the guild for the channel.
+        """
+
+        # Function that sends the message, uses dependency injection for bot token / channel / guild
+        async def discord_send_message(
+            message: Annotated[str, "Message to send to the channel."],
+            bot_token: Annotated[str, Depends(on(bot_token))],
+            guild_name: Annotated[str, Depends(on(guild_name))],
+            channel_name: Annotated[str, Depends(on(channel_name))],
+        ) -> Any:
+            """Sends a message to a Discord channel.
+
+            Args:
+                message: The message to send to the channel.
+                bot_token: The bot token to use for Discord. (uses dependency injection)
+                guild_name: The name of the server. (uses dependency injection)
+                channel_name: The name of the channel. (uses dependency injection)
+            """
+            intents = Intents.default()
+            intents.message_content = True
+            intents.guilds = True
+            intents.guild_messages = True
+
+            client = Client(intents=intents)
+            result_future: asyncio.Future[str] = asyncio.Future()  # Stores the result of the send
+
+            # When the client is ready, we'll send the message
+            @client.event  # type: ignore[misc]
+            async def on_ready() -> None:
+                try:
+                    # Server
+                    guild = utils.get(client.guilds, name=guild_name)
+                    if guild:
+                        # Channel
+                        channel = utils.get(guild.text_channels, name=channel_name)
+                        if channel:
+                            # Send the message
+                            if len(message) > MAX_MESSAGE_LENGTH:
+                                chunks = [
+                                    message[i : i + (MAX_MESSAGE_LENGTH - 1)]
+                                    for i in range(0, len(message), (MAX_MESSAGE_LENGTH - 1))
+                                ]
+                                for i, chunk in enumerate(chunks):
+                                    sent = await channel.send(chunk)
+
+                                    # Store ID for the first chunk
+                                    if i == 0:
+                                        sent_message_id = str(sent.id)
+
+                                result_future.set_result(
+                                    f"Message sent successfully ({len(chunks)} chunks, first ID: {sent_message_id}):\n{message}"
+                                )
+                            else:
+                                sent = await channel.send(message)
+                                result_future.set_result(f"Message sent successfully (ID: {sent.id}):\n{message}")
+                        else:
+                            result_future.set_result(f"Message send failed, could not find channel: {channel_name}")
+                    else:
+                        result_future.set_result(f"Message send failed, could not find guild: {guild_name}")
+
+                except Exception as e:
+                    result_future.set_exception(e)
+                finally:
+                    try:
+                        await client.close()
+                    except Exception as e:
+                        raise Exception(f"Unable to close Discord client: {e}")
+
+            # Start the client and when it's ready it'll send the message in on_ready
+            try:
+                await client.start(bot_token)
+
+                # Capture the result of the send
+                return await result_future
+            except Exception as e:
+                raise Exception(f"Failed to start Discord client: {e}")
+
+        super().__init__(
+            name="discord_send",
+            description="Sends a message to a Discord channel.",
+            func_or_tool=discord_send_message,
+        )
+
+
+@require_optional_import(["discord"], "commsagent-discord")
+@export_module("autogen.tools.experimental")
+class DiscordRetrieveTool(Tool):
+    """Retrieves messages from a Discord channel."""
+
+    def __init__(self, *, bot_token: str, channel_name: str, guild_name: str) -> None:
+        """Initialize the DiscordRetrieveTool.
+
+        Args:
+            bot_token: The bot token to use for retrieving messages.
+            channel_name: The name of the channel to retrieve messages from.
+            guild_name: The name of the guild for the channel.
+        """
+
+        async def discord_retrieve_messages(
+            bot_token: Annotated[str, Depends(on(bot_token))],
+            guild_name: Annotated[str, Depends(on(guild_name))],
+            channel_name: Annotated[str, Depends(on(channel_name))],
+            messages_since: Annotated[
+                str | None,
+                "Date to retrieve messages from (ISO format) OR Discord snowflake ID. If None, retrieves latest messages.",
+            ] = None,
+            maximum_messages: Annotated[
+                int | None, "Maximum number of messages to retrieve. If None, retrieves all messages since date."
+            ] = None,
+        ) -> Any:
+            """Retrieves messages from a Discord channel.
+
+            Args:
+                bot_token: The bot token to use for Discord. (uses dependency injection)
+                guild_name: The name of the server. (uses dependency injection)
+                channel_name: The name of the channel. (uses dependency injection)
+                messages_since: ISO format date string OR Discord snowflake ID, to retrieve messages from. If None, retrieves latest messages.
+                maximum_messages: Maximum number of messages to retrieve. If None, retrieves all messages since date.
+            """
+            intents = Intents.default()
+            intents.message_content = True
+            intents.guilds = True
+            intents.guild_messages = True
+
+            client = Client(intents=intents)
+            result_future: asyncio.Future[list[dict[str, Any]]] = asyncio.Future()
+
+            messages_since_date: str | None = None
+            if messages_since is not None:
+                if DiscordRetrieveTool._is_snowflake(messages_since):
+                    messages_since_date = DiscordRetrieveTool._snowflake_to_iso(messages_since)
+                else:
+                    messages_since_date = messages_since
+
+            @client.event  # type: ignore[misc]
+            async def on_ready() -> None:
+                try:
+                    messages = []
+
+                    # Get guild and channel
+                    guild = utils.get(client.guilds, name=guild_name)
+                    if not guild:
+                        result_future.set_result([{"error": f"Could not find guild: {guild_name}"}])
+                        return
+
+                    channel = utils.get(guild.text_channels, name=channel_name)
+                    if not channel:
+                        result_future.set_result([{"error": f"Could not find channel: {channel_name}"}])
+                        return
+
+                    # Setup retrieval parameters
+                    last_message_id = None
+                    messages_retrieved = 0
+
+                    # Convert to ISO format
+                    after_date = None
+                    if messages_since_date:
+                        try:
+                            from datetime import datetime
+
+                            after_date = datetime.fromisoformat(messages_since_date)
+                        except ValueError:
+                            result_future.set_result([
+                                {"error": f"Invalid date format: {messages_since_date}. Use ISO format."}
+                            ])
+                            return
+
+                    while True:
+                        # Setup fetch options
+                        fetch_options = {
+                            "limit": MAX_BATCH_RETRIEVE_MESSAGES,
+                            "before": last_message_id if last_message_id else None,
+                            "after": after_date if after_date else None,
+                        }
+
+                        # Fetch batch of messages
+                        message_batch = []
+                        async for message in channel.history(**fetch_options):  # type: ignore[arg-type]
+                            message_batch.append(message)
+                            messages_retrieved += 1
+
+                            # Check if we've reached the maximum
+                            if maximum_messages and messages_retrieved >= maximum_messages:
+                                break
+
+                        if not message_batch:
+                            break
+
+                        # Process messages
+                        for msg in message_batch:
+                            messages.append({
+                                "id": str(msg.id),
+                                "content": msg.content,
+                                "author": str(msg.author),
+                                "timestamp": msg.created_at.isoformat(),
+                            })
+
+                        # Update last message ID for pagination
+                        last_message_id = message_batch[-1]  # Use message object directly as 'before' parameter
+
+                        # Break if we've reached the maximum
+                        if maximum_messages and messages_retrieved >= maximum_messages:
+                            break
+
+                    result_future.set_result(messages)
+
+                except Exception as e:
+                    result_future.set_exception(e)
+                finally:
+                    try:
+                        await client.close()
+                    except Exception as e:
+                        raise Exception(f"Unable to close Discord client: {e}")
+
+            try:
+                await client.start(bot_token)
+                return await result_future
+            except Exception as e:
+                raise Exception(f"Failed to start Discord client: {e}")
+
+        super().__init__(
+            name="discord_retrieve",
+            description="Retrieves messages from a Discord channel based datetime/message ID and/or number of latest messages.",
+            func_or_tool=discord_retrieve_messages,
+        )
+
+    @staticmethod
+    def _is_snowflake(value: str) -> bool:
+        """Check if a string is a valid Discord snowflake ID."""
+        # Must be numeric and 17-20 digits
+        if not value.isdigit():
+            return False
+
+        digit_count = len(value)
+        return 17 <= digit_count <= 20
+
+    @staticmethod
+    def _snowflake_to_iso(snowflake: str) -> str:
+        """Convert a Discord snowflake ID to ISO timestamp string."""
+        if not DiscordRetrieveTool._is_snowflake(snowflake):
+            raise ValueError(f"Invalid snowflake ID: {snowflake}")
+
+        # Discord epoch (2015-01-01)
+        discord_epoch = 1420070400000
+
+        # Convert ID to int and shift right 22 bits to get timestamp
+        timestamp_ms = (int(snowflake) >> 22) + discord_epoch
+
+        # Convert to datetime and format as ISO string
+        dt = datetime.fromtimestamp(timestamp_ms / 1000.0, tz=timezone.utc)
+        return dt.isoformat()

autogen/tools/experimental/messageplatform/slack/__init__.py

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