ag2 0.9.1a1__py3-none-any.whl → 0.9.2__py3-none-any.whl

autogen/tools/experimental/tavily/__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 .tavily_search import TavilySearchTool
+
+__all__ = ["TavilySearchTool"]

autogen/tools/experimental/tavily/tavily_search.py

@@ -0,0 +1,183 @@
+# 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 Annotated, Any, Optional, Union
+
+from ....doc_utils import export_module
+from ....import_utils import optional_import_block, require_optional_import
+from ....llm_config import LLMConfig
+from ... import Depends, Tool
+from ...dependency_injection import on
+
+with optional_import_block():
+    from tavily import TavilyClient
+
+
+@require_optional_import(
+    [
+        "tavily",
+    ],
+    "tavily",
+)
+def _execute_tavily_query(
+    query: str,
+    tavily_api_key: str,
+    search_depth: str = "basic",
+    topic: str = "general",
+    include_answer: str = "basic",
+    include_raw_content: bool = False,
+    include_domains: list[str] = [],
+    num_results: int = 5,
+) -> Any:
+    """
+    Execute a search query using the Tavily API.
+
+    Args:
+        query (str): The search query string.
+        tavily_api_key (str): The API key for Tavily.
+        search_depth (str, optional): The depth of the search ('basic' or 'advanced'). Defaults to "basic".
+        topic (str, optional): The topic of the search. Defaults to "general".
+        include_answer (str, optional): Whether to include an AI-generated answer ('basic' or 'advanced'). Defaults to "basic".
+        include_raw_content (bool, optional): Whether to include raw content in the results. Defaults to False.
+        include_domains (list[str], optional): A list of domains to include in the search. Defaults to [].
+        num_results (int, optional): The maximum number of results to return. Defaults to 5.
+
+    Returns:
+        Any: The raw response object from the Tavily API client.
+    """
+    tavily_client = TavilyClient(api_key=tavily_api_key)
+    return tavily_client.search(
+        query=query,
+        search_depth=search_depth,
+        topic=topic,
+        include_answer=include_answer,
+        include_raw_content=include_raw_content,
+        include_domains=include_domains,
+        max_results=num_results,
+    )
+
+
+def _tavily_search(
+    query: str,
+    tavily_api_key: str,
+    search_depth: str = "basic",
+    topic: str = "general",
+    include_answer: str = "basic",
+    include_raw_content: bool = False,
+    include_domains: list[str] = [],
+    num_results: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Perform a Tavily search and format the results.
+
+    This function takes search parameters, executes the query using `_execute_tavily_query`,
+    and formats the results into a list of dictionaries containing title, link, and snippet.
+
+    Args:
+        query (str): The search query string.
+        tavily_api_key (str): The API key for Tavily.
+        search_depth (str, optional): The depth of the search ('basic' or 'advanced'). Defaults to "basic".
+        topic (str, optional): The topic of the search. Defaults to "general".
+        include_answer (str, optional): Whether to include an AI-generated answer ('basic' or 'advanced'). Defaults to "basic".
+        include_raw_content (bool, optional): Whether to include raw content in the results. Defaults to False.
+        include_domains (list[str], optional): A list of domains to include in the search. Defaults to [].
+        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_tavily_query(
+        query=query,
+        tavily_api_key=tavily_api_key,
+        search_depth=search_depth,
+        topic=topic,
+        include_answer=include_answer,
+        include_raw_content=include_raw_content,
+        include_domains=include_domains,
+        num_results=num_results,
+    )
+
+    return [
+        {"title": item.get("title", ""), "link": item.get("url", ""), "snippet": item.get("content", "")}
+        for item in res.get("results", [])
+    ]
+
+
+@export_module("autogen.tools.experimental")
+class TavilySearchTool(Tool):
+    """
+    TavilySearchTool is a tool that uses the Tavily Search API to perform a search.
+
+    This tool allows agents to leverage the Tavily search engine for information retrieval.
+    It requires a Tavily API key, which can be provided during initialization or set as
+    an environment variable `TAVILY_API_KEY`.
+
+    Attributes:
+        tavily_api_key (str): The API key used for authenticating with the Tavily API.
+    """
+
+    def __init__(
+        self, *, llm_config: Optional[Union[LLMConfig, dict[str, Any]]] = None, tavily_api_key: Optional[str] = None
+    ):
+        """
+        Initializes the TavilySearchTool.
+
+        Args:
+            llm_config (Optional[Union[LLMConfig, dict[str, Any]]]): LLM configuration. (Currently unused but kept for potential future integration).
+            tavily_api_key (Optional[str]): The API key for the Tavily Search API. If not provided,
+                it attempts to read from the `TAVILY_API_KEY` environment variable.
+
+        Raises:
+            ValueError: If `tavily_api_key` is not provided either directly or via the environment variable.
+        """
+        self.tavily_api_key = tavily_api_key or os.getenv("TAVILY_API_KEY")
+
+        if self.tavily_api_key is None:
+            raise ValueError("tavily_api_key must be provided either as an argument or via TAVILY_API_KEY env var")
+
+        def tavily_search(
+            query: Annotated[str, "The search query."],
+            tavily_api_key: Annotated[Optional[str], Depends(on(self.tavily_api_key))],
+            search_depth: Annotated[Optional[str], "Either 'advanced' or 'basic'"] = "basic",
+            include_answer: Annotated[Optional[str], "Either 'advanced' or 'basic'"] = "basic",
+            include_raw_content: Annotated[Optional[bool], "Include the raw contents"] = False,
+            include_domains: Annotated[Optional[list[str]], "Specific web domains to search"] = [],
+            num_results: Annotated[int, "The number of results to return."] = 5,
+        ) -> list[dict[str, Any]]:
+            """
+            Performs a search using the Tavily API and returns formatted results.
+
+            Args:
+                query: The search query string.
+                tavily_api_key: The API key for Tavily (injected dependency).
+                search_depth: The depth of the search ('basic' or 'advanced'). Defaults to "basic".
+                include_answer: Whether to include an AI-generated answer ('basic' or 'advanced'). Defaults to "basic".
+                include_raw_content: Whether to include raw content in the results. Defaults to False.
+                include_domains: A list of domains to include in the search. Defaults to [].
+                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.
+
+            Raises:
+                ValueError: If the Tavily API key is not available.
+            """
+            if tavily_api_key is None:
+                raise ValueError("Tavily API key is missing.")
+            return _tavily_search(
+                query=query,
+                tavily_api_key=tavily_api_key,
+                search_depth=search_depth or "basic",
+                include_answer=include_answer or "basic",
+                include_raw_content=include_raw_content or False,
+                include_domains=include_domains or [],
+                num_results=num_results,
+            )
+
+        super().__init__(
+            name="tavily_search",
+            description="Use the Tavily Search API to perform a search.",
+            func_or_tool=tavily_search,
+        )

autogen/tools/experimental/web_search_preview/__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 .web_search_preview import WebSearchPreviewTool
+
+__all__ = ["WebSearchPreviewTool"]

autogen/tools/experimental/web_search_preview/web_search_preview.py

@@ -0,0 +1,114 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+import copy
+import logging
+import os
+from typing import Annotated, Any, Literal, Optional, Type, Union
+
+from pydantic import BaseModel
+
+from ....doc_utils import export_module
+from ....import_utils import optional_import_block, require_optional_import
+from ....llm_config import LLMConfig
+from ... import Tool
+
+with optional_import_block():
+    from openai import OpenAI
+    from openai.types.responses import WebSearchToolParam
+    from openai.types.responses.web_search_tool import UserLocation
+
+
+@require_optional_import("openai>=1.66.2", "openai")
+@export_module("autogen.tools.experimental")
+class WebSearchPreviewTool(Tool):
+    """WebSearchPreviewTool is a tool that uses OpenAI's web_search_preview tool to perform a search."""
+
+    def __init__(
+        self,
+        *,
+        llm_config: Union[LLMConfig, dict[str, Any]],
+        search_context_size: Literal["low", "medium", "high"] = "medium",
+        user_location: Optional[dict[str, str]] = None,
+        instructions: Optional[str] = None,
+        text_format: Optional[Type[BaseModel]] = None,
+    ):
+        """Initialize the WebSearchPreviewTool.
+
+        Args:
+            llm_config: The LLM configuration to use. This should be a dictionary
+                containing the model name and other parameters.
+            search_context_size: The size of the search context. One of `low`, `medium`, or `high`.
+                `medium` is the default.
+            user_location: The location of the user. This should be a dictionary containing
+                the city, country, region, and timezone.
+            instructions: Inserts a system (or developer) message as the first item in the model's context.
+            text_format: The format of the text to be returned. This should be a subclass of `BaseModel`.
+                The default is `None`, which means the text will be returned as a string.
+        """
+        self.web_search_tool_param = WebSearchToolParam(
+            type="web_search_preview",
+            search_context_size=search_context_size,
+            user_location=UserLocation(**user_location) if user_location else None,  # type: ignore[typeddict-item]
+        )
+        self.instructions = instructions
+        self.text_format = text_format
+
+        if isinstance(llm_config, LLMConfig):
+            llm_config = llm_config.model_dump()
+
+        llm_config = copy.deepcopy(llm_config)
+
+        if "config_list" not in llm_config:
+            raise ValueError("llm_config must contain 'config_list' key")
+
+        # Find first OpenAI model which starts with "gpt-4"
+        self.model = None
+        self.api_key = None
+        for model in llm_config["config_list"]:
+            if model["model"].startswith("gpt-4") and model.get("api_type", "openai") == "openai":
+                self.model = model["model"]
+                self.api_key = model.get("api_key", os.getenv("OPENAI_API_KEY"))
+                break
+        if self.model is None:
+            raise ValueError(
+                "No OpenAI model starting with 'gpt-4' found in llm_config, other models do not support web_search_preview"
+            )
+
+        if not self.model.startswith("gpt-4.1") and not self.model.startswith("gpt-4o-search-preview"):
+            logging.warning(
+                f"We recommend using a model starting with 'gpt-4.1' or 'gpt-4o-search-preview' for web_search_preview, but found {self.model}. "
+                "This may result in suboptimal performance."
+            )
+
+        def web_search_preview(
+            query: Annotated[str, "The search query. Add all relevant context to the query."],
+        ) -> Union[str, Optional[BaseModel]]:
+            client = OpenAI()
+
+            if not self.text_format:
+                response = client.responses.create(
+                    model=self.model,  # type: ignore[arg-type]
+                    tools=[self.web_search_tool_param],
+                    input=query,
+                    instructions=self.instructions,
+                )
+                return response.output_text
+
+            else:
+                response = client.responses.parse(
+                    model=self.model,  # type: ignore[arg-type]
+                    tools=[self.web_search_tool_param],
+                    input=query,
+                    instructions=self.instructions,
+                    text_format=self.text_format,
+                )
+                return response.output_parsed
+
+        super().__init__(
+            name="web_search_preview",
+            description="Tool used to perform a web search. It can be used as google search or directly searching a specific website.",
+            func_or_tool=web_search_preview,
+        )

autogen/tools/experimental/wikipedia/__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 .wikipedia import WikipediaPageLoadTool, WikipediaQueryRunTool
+
+__all__ = ["WikipediaPageLoadTool", "WikipediaQueryRunTool"]

autogen/tools/experimental/wikipedia/wikipedia.py

@@ -0,0 +1,287 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any, Optional, Union
+
+import requests
+from pydantic import BaseModel
+
+from autogen.import_utils import optional_import_block, require_optional_import
+from autogen.tools import Tool
+
+with optional_import_block():
+    import wikipediaapi
+
+# Maximum allowed length for a query string.
+MAX_QUERY_LENGTH = 300
+# Maximum number of pages to retrieve from a search.
+MAX_PAGE_RETRIEVE = 100
+# Maximum number of characters to return from a Wikipedia page.
+MAX_ARTICLE_LENGTH = 10000
+
+
+class Document(BaseModel):
+    """Pydantic model representing a Wikipedia document.
+
+    Attributes:
+        page_content (str): Textual content of the Wikipedia page
+            (possibly truncated).
+        metadata (dict[str, str]): Additional info, including:
+            - source URL
+            - title
+            - pageid
+            - timestamp
+            - word count
+            - size
+    """
+
+    page_content: str
+    metadata: dict[str, str]
+
+
+class WikipediaClient:
+    """Client for interacting with the Wikipedia API.
+
+    Supports searching and page retrieval on a specified language edition.
+
+    Public methods:
+        search(query: str, limit: int) -> list[dict[str, Any]]
+        get_page(title: str) -> Optional[wikipediaapi.WikipediaPage]
+
+    Attributes:
+        base_url (str): URL of the MediaWiki API endpoint.
+        headers (dict[str, str]): HTTP headers, including User-Agent.
+        wiki (wikipediaapi.Wikipedia): Low-level Wikipedia API client.
+    """
+
+    def __init__(self, language: str = "en", tool_name: str = "wikipedia-client") -> None:
+        """Initialize the WikipediaClient.
+
+        Args:
+            language (str): ISO code of the Wikipedia edition (e.g., 'en', 'es').
+            tool_name (str): Identifier for User-Agent header.
+        """
+        self.base_url = f"https://{language}.wikipedia.org/w/api.php"
+        self.headers = {"User-Agent": f"autogen.Agent ({tool_name})"}
+        self.wiki = wikipediaapi.Wikipedia(
+            language=language,
+            extract_format=wikipediaapi.ExtractFormat.WIKI,
+            user_agent=f"autogen.Agent ({tool_name})",
+        )
+
+    def search(self, query: str, limit: int = 3) -> Any:
+        """Search Wikipedia for pages matching a query string.
+
+        Args:
+            query (str): The search keywords.
+            limit (int): Max number of results to return.
+
+        Returns:
+            list[dict[str, Any]]: Each dict has keys:
+                - 'title' (str)
+                - 'size' (int)
+                - 'wordcount' (int)
+                - 'timestamp' (str)
+
+        Raises:
+            requests.HTTPError: If the HTTP request to the API fails.
+        """
+        params = {
+            "action": "query",
+            "format": "json",
+            "list": "search",
+            "srsearch": query,
+            "srlimit": str(limit),
+            "srprop": "size|wordcount|timestamp",
+        }
+
+        response = requests.get(url=self.base_url, params=params, headers=self.headers)
+        response.raise_for_status()
+        data = response.json()
+        search_data = data.get("query", {}).get("search", [])
+        return search_data
+
+    def get_page(self, title: str) -> Optional[Any]:
+        """Retrieve a WikipediaPage object by title.
+
+        Args:
+            title (str): Title of the Wikipedia page.
+
+        Returns:
+            wikipediaapi.WikipediaPage | None: The page object if it exists,
+            otherwise None.
+
+        Raises:
+            wikipediaapi.WikipediaException: On lower‑level API errors.
+        """
+        page = self.wiki.page(title)
+        if not page.exists():
+            return None
+        return page
+
+
+@require_optional_import(["wikipediaapi"], "wikipedia")
+class WikipediaQueryRunTool(Tool):
+    """Tool for querying Wikipedia and returning summarized page results.
+
+    This tool uses the `wikipediaapi` package to perform searches
+    against a specified language edition of Wikipedia and returns
+    up to `top_k` page summaries.
+
+    Public methods:
+        query_run(query: str) -> list[str] | str
+
+    Attributes:
+        language (str): Language code for the Wikipedia edition (e.g., 'en', 'es').
+        top_k (int): Max number of page summaries returned (≤ MAX_PAGE_RETRIEVE).
+        verbose (bool): If True, enables debug logging to stdout.
+        wiki_cli (WikipediaClient): Internal client for Wikipedia API calls.
+    """
+
+    def __init__(self, language: str = "en", top_k: int = 3, verbose: bool = False) -> None:
+        """Initialize the WikipediaQueryRunTool.
+
+        Args:
+            language (str): ISO code of the Wikipedia edition to query.
+            top_k (int): Desired number of summaries (capped by MAX_PAGE_RETRIEVE).
+            verbose (bool): If True, print debug information during searches.
+        """
+        self.language = language
+        self.tool_name = "wikipedia-query-run"
+        self.wiki_cli = WikipediaClient(language, self.tool_name)
+        self.top_k = min(top_k, MAX_PAGE_RETRIEVE)
+        self.verbose = verbose
+        super().__init__(
+            name=self.tool_name,
+            description="Run a Wikipedia query and return page summaries.",
+            func_or_tool=self.query_run,
+        )
+
+    def query_run(self, query: str) -> Union[list[str], str]:
+        """Search Wikipedia and return formatted page summaries.
+
+        Truncates `query` to MAX_QUERY_LENGTH before searching.
+
+        Args:
+            query (str): Search term(s) to look up in Wikipedia.
+
+        Returns:
+            list[str]: Each element is "Page: <title>\nSummary: <text>".
+            str: Error message if no results are found or on exception.
+
+        Note:
+            Automatically handles API exceptions and returns error strings for robust operation
+        """
+        try:
+            if self.verbose:
+                print(f"INFO\t [{self.tool_name}] search query='{query[:MAX_QUERY_LENGTH]}' top_k={self.top_k}")
+            search_results = self.wiki_cli.search(query[:MAX_QUERY_LENGTH], limit=self.top_k)
+            summaries: list[str] = []
+            for item in search_results:
+                title = item["title"]
+                page = self.wiki_cli.get_page(title)
+                # Only format the summary if the page exists and has a summary.
+                if page is not None and page.summary:
+                    summary = f"Page: {title}\nSummary: {page.summary}"
+                    summaries.append(summary)
+            if not summaries:
+                return "No good Wikipedia Search Result was found"
+            return summaries
+        except Exception as e:
+            return f"wikipedia search failed: {str(e)}"
+
+
+@require_optional_import(["wikipediaapi"], "wikipedia")
+class WikipediaPageLoadTool(Tool):
+    """
+    A tool to load up to N characters of Wikipedia page content along with metadata.
+
+    This tool uses a language-specific Wikipedia client to search for relevant articles
+    and returns a list of Document objects containing truncated page content and metadata
+    (source URL, title, page ID, timestamp, word count, and size). Ideal for agents
+    requiring structured Wikipedia data for research, summarization, or contextual enrichment.
+
+    Attributes:
+        language (str): Wikipedia language code (default: "en").
+        top_k (int): Maximum number of pages to retrieve per query (default: 3).
+        truncate (int): Maximum number of characters of content per page (default: 4000).
+        verbose (bool): If True, prints debug information (default: False).
+        tool_name (str): Identifier used in User-Agent header.
+        wiki_cli (WikipediaClient): Client for interacting with the Wikipedia API.
+    """
+
+    def __init__(self, language: str = "en", top_k: int = 3, truncate: int = 4000, verbose: bool = False) -> None:
+        """
+        Initializes the WikipediaPageLoadTool with configurable language, result count, and content length.
+
+        Args:
+            language (str): The language code for the Wikipedia edition (default is "en").
+            top_k (int): The maximum number of pages to retrieve per query (default is 3;
+                         capped at MAX_PAGE_RETRIEVE).
+            truncate (int): The maximum number of characters to extract from each page (default is 4000;
+                            capped at MAX_ARTICLE_LENGTH).
+            verbose (bool): If True, enables verbose/debug logging (default is False).
+        """
+        self.language = language
+        self.top_k = min(top_k, MAX_PAGE_RETRIEVE)
+        self.truncate = min(truncate, MAX_ARTICLE_LENGTH)
+        self.verbose = verbose
+        self.tool_name = "wikipedia-page-load"
+        self.wiki_cli = WikipediaClient(language, self.tool_name)
+        super().__init__(
+            name=self.tool_name,
+            description=(
+                "Search Wikipedia for relevant pages using a language-specific client. "
+                "Returns a list of documents with truncated content and metadata including title, URL, "
+                "page ID, timestamp, word count, and page size. Configure number of results with the 'top_k' parameter "
+                "and content length with 'truncate'. Useful for research, summarization, or contextual enrichment."
+            ),
+            func_or_tool=self.content_search,
+        )
+
+    def content_search(self, query: str) -> Union[list[Document], str]:
+        """
+        Executes a Wikipedia search and returns page content plus metadata.
+
+        Args:
+            query (str): The search term to query Wikipedia.
+
+        Returns:
+            Union[list[Document], str]:
+                - list[Document]: Documents with up to `truncate` characters of page text
+                  and metadata if pages are found.
+                - str: Error message if the search fails or no pages are found.
+
+        Notes:
+            - Errors are caught internally and returned as strings.
+            - If no matching pages have text content, returns
+              "No good Wikipedia Search Result was found".
+        """
+        try:
+            if self.verbose:
+                print(f"INFO\t [{self.tool_name}] search query='{query[:MAX_QUERY_LENGTH]}' top_k={self.top_k}")
+            search_results = self.wiki_cli.search(query[:MAX_QUERY_LENGTH], limit=self.top_k)
+            docs: list[Document] = []
+            for item in search_results:
+                page = self.wiki_cli.get_page(item["title"])
+                # Only process pages that exist and have text content.
+                if page is not None and page.text:
+                    document = Document(
+                        page_content=page.text[: self.truncate],
+                        metadata={
+                            "source": f"https://{self.language}.wikipedia.org/?curid={item['pageid']}",
+                            "title": item["title"],
+                            "pageid": str(item["pageid"]),
+                            "timestamp": str(item["timestamp"]),
+                            "wordcount": str(item["wordcount"]),
+                            "size": str(item["size"]),
+                        },
+                    )
+                    docs.append(document)
+            if not docs:
+                return "No good Wikipedia Search Result was found"
+            return docs
+
+        except Exception as e:
+            return f"wikipedia search failed: {str(e)}"