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

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)}"

autogen/tools/function_utils.py

@@ -0,0 +1,411 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Portions derived from  https://github.com/microsoft/autogen are under the MIT License.
+# SPDX-License-Identifier: MIT
+import functools
+import inspect
+import json
+from logging import getLogger
+from typing import Annotated, Any, Callable, ForwardRef, Optional, TypeVar, Union
+
+from packaging.version import parse
+from pydantic import BaseModel, Field, TypeAdapter
+from pydantic import __version__ as pydantic_version
+from pydantic.json_schema import JsonSchemaValue
+from typing_extensions import Literal, get_args, get_origin
+
+from ..doc_utils import export_module
+from .dependency_injection import Field as AG2Field
+
+if parse(pydantic_version) < parse("2.10.2"):
+    from pydantic._internal._typing_extra import eval_type_lenient as try_eval_type
+else:
+    from pydantic._internal._typing_extra import try_eval_type
+
+
+__all__ = ["get_function_schema", "load_basemodels_if_needed", "serialize_to_str"]
+
+logger = getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def get_typed_annotation(annotation: Any, globalns: dict[str, Any]) -> Any:
+    """Get the type annotation of a parameter.
+
+    Args:
+        annotation: The annotation of the parameter
+        globalns: The global namespace of the function
+
+    Returns:
+        The type annotation of the parameter
+    """
+    if isinstance(annotation, AG2Field):
+        annotation = annotation.description
+    if isinstance(annotation, str):
+        annotation = ForwardRef(annotation)
+        annotation, _ = try_eval_type(annotation, globalns, globalns)
+    return annotation
+
+
+def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+    """Get the signature of a function with type annotations.
+
+    Args:
+        call: The function to get the signature for
+
+    Returns:
+        The signature of the function with type annotations
+    """
+    signature = inspect.signature(call)
+    globalns = getattr(call, "__globals__", {})
+    typed_params = [
+        inspect.Parameter(
+            name=param.name,
+            kind=param.kind,
+            default=param.default,
+            annotation=get_typed_annotation(param.annotation, globalns),
+        )
+        for param in signature.parameters.values()
+    ]
+    typed_signature = inspect.Signature(typed_params)
+    return typed_signature
+
+
+def get_typed_return_annotation(call: Callable[..., Any]) -> Any:
+    """Get the return annotation of a function.
+
+    Args:
+        call: The function to get the return annotation for
+
+    Returns:
+        The return annotation of the function
+    """
+    signature = inspect.signature(call)
+    annotation = signature.return_annotation
+
+    if annotation is inspect.Signature.empty:
+        return None
+
+    globalns = getattr(call, "__globals__", {})
+    return get_typed_annotation(annotation, globalns)
+
+
+def get_param_annotations(typed_signature: inspect.Signature) -> dict[str, Union[Annotated[type[Any], str], type[Any]]]:
+    """Get the type annotations of the parameters of a function
+
+    Args:
+        typed_signature: The signature of the function with type annotations
+
+    Returns:
+        A dictionary of the type annotations of the parameters of the function
+    """
+    return {
+        k: v.annotation for k, v in typed_signature.parameters.items() if v.annotation is not inspect.Signature.empty
+    }
+
+
+class Parameters(BaseModel):
+    """Parameters of a function as defined by the OpenAI API"""
+
+    type: Literal["object"] = "object"
+    properties: dict[str, JsonSchemaValue]
+    required: list[str]
+
+
+class Function(BaseModel):
+    """A function as defined by the OpenAI API"""
+
+    description: Annotated[str, Field(description="Description of the function")]
+    name: Annotated[str, Field(description="Name of the function")]
+    parameters: Annotated[Parameters, Field(description="Parameters of the function")]
+
+
+class ToolFunction(BaseModel):
+    """A function under tool as defined by the OpenAI API."""
+
+    type: Literal["function"] = "function"
+    function: Annotated[Function, Field(description="Function under tool")]
+
+
+def get_parameter_json_schema(k: str, v: Any, default_values: dict[str, Any]) -> JsonSchemaValue:
+    """Get a JSON schema for a parameter as defined by the OpenAI API
+
+    Args:
+        k: The name of the parameter
+        v: The type of the parameter
+        default_values: The default values of the parameters of the function
+
+    Returns:
+        A Pydanitc model for the parameter
+    """
+
+    def type2description(k: str, v: Union[Annotated[type[Any], str], type[Any]]) -> str:
+        if not hasattr(v, "__metadata__"):
+            return k
+
+        # handles Annotated
+        retval = v.__metadata__[0]
+        if isinstance(retval, AG2Field):
+            return retval.description  # type: ignore[return-value]
+        else:
+            raise ValueError(f"Invalid {retval} for parameter {k}, should be a DescriptionField, got {type(retval)}")
+
+    schema = TypeAdapter(v).json_schema()
+    if k in default_values:
+        dv = default_values[k]
+        schema["default"] = dv
+
+    schema["description"] = type2description(k, v)
+
+    return schema
+
+
+def get_required_params(typed_signature: inspect.Signature) -> list[str]:
+    """Get the required parameters of a function
+
+    Args:
+        typed_signature: The signature of the function as returned by inspect.signature
+
+    Returns:
+        A list of the required parameters of the function
+    """
+    return [k for k, v in typed_signature.parameters.items() if v.default == inspect.Signature.empty]
+
+
+def get_default_values(typed_signature: inspect.Signature) -> dict[str, Any]:
+    """Get default values of parameters of a function
+
+    Args:
+        typed_signature: The signature of the function as returned by inspect.signature
+
+    Returns:
+        A dictionary of the default values of the parameters of the function
+    """
+    return {k: v.default for k, v in typed_signature.parameters.items() if v.default != inspect.Signature.empty}
+
+
+def get_parameters(
+    required: list[str],
+    param_annotations: dict[str, Union[Annotated[type[Any], str], type[Any]]],
+    default_values: dict[str, Any],
+) -> Parameters:
+    """Get the parameters of a function as defined by the OpenAI API
+
+    Args:
+        required: The required parameters of the function
+        param_annotations: The type annotations of the parameters of the function
+        default_values: The default values of the parameters of the function
+
+    Returns:
+        A Pydantic model for the parameters of the function
+    """
+    return Parameters(
+        properties={
+            k: get_parameter_json_schema(k, v, default_values)
+            for k, v in param_annotations.items()
+            if v is not inspect.Signature.empty
+        },
+        required=required,
+    )
+
+
+def get_missing_annotations(typed_signature: inspect.Signature, required: list[str]) -> tuple[set[str], set[str]]:
+    """Get the missing annotations of a function
+
+    Ignores the parameters with default values as they are not required to be annotated, but logs a warning.
+
+    Args:
+        typed_signature: The signature of the function with type annotations
+        required: The required parameters of the function
+
+    Returns:
+        A set of the missing annotations of the function
+    """
+    all_missing = {k for k, v in typed_signature.parameters.items() if v.annotation is inspect.Signature.empty}
+    missing = all_missing.intersection(set(required))
+    unannotated_with_default = all_missing.difference(missing)
+    return missing, unannotated_with_default
+
+
+@export_module("autogen.tools")
+def get_function_schema(f: Callable[..., Any], *, name: Optional[str] = None, description: str) -> dict[str, Any]:
+    """Get a JSON schema for a function as defined by the OpenAI API
+
+    Args:
+        f: The function to get the JSON schema for
+        name: The name of the function
+        description: The description of the function
+
+    Returns:
+        A JSON schema for the function
+
+    Raises:
+        TypeError: If the function is not annotated
+
+    Examples:
+    ```python
+    def f(a: Annotated[str, "Parameter a"], b: int = 2, c: Annotated[float, "Parameter c"] = 0.1) -> None:
+        pass
+
+
+    get_function_schema(f, description="function f")
+
+    #   {'type': 'function',
+    #    'function': {'description': 'function f',
+    #        'name': 'f',
+    #        'parameters': {'type': 'object',
+    #           'properties': {'a': {'type': 'str', 'description': 'Parameter a'},
+    #               'b': {'type': 'int', 'description': 'b'},
+    #               'c': {'type': 'float', 'description': 'Parameter c'}},
+    #           'required': ['a']}}}
+    ```
+
+    """
+    typed_signature = get_typed_signature(f)
+    required = get_required_params(typed_signature)
+    default_values = get_default_values(typed_signature)
+    param_annotations = get_param_annotations(typed_signature)
+    return_annotation = get_typed_return_annotation(f)
+    missing, unannotated_with_default = get_missing_annotations(typed_signature, required)
+
+    if return_annotation is None:
+        logger.warning(
+            f"The return type of the function '{f.__name__}' is not annotated. Although annotating it is "
+            + "optional, the function should return either a string, a subclass of 'pydantic.BaseModel'."
+        )
+
+    if unannotated_with_default != set():
+        unannotated_with_default_s = [f"'{k}'" for k in sorted(unannotated_with_default)]
+        logger.warning(
+            f"The following parameters of the function '{f.__name__}' with default values are not annotated: "
+            + f"{', '.join(unannotated_with_default_s)}."
+        )
+
+    if missing != set():
+        missing_s = [f"'{k}'" for k in sorted(missing)]
+        raise TypeError(
+            f"All parameters of the function '{f.__name__}' without default values must be annotated. "
+            + f"The annotations are missing for the following parameters: {', '.join(missing_s)}"
+        )
+
+    fname = name if name else f.__name__
+
+    parameters = get_parameters(required, param_annotations, default_values=default_values)
+
+    function = ToolFunction(
+        function=Function(
+            description=description,
+            name=fname,
+            parameters=parameters,
+        )
+    )
+
+    return function.model_dump()
+
+
+def get_load_param_if_needed_function(t: Any) -> Optional[Callable[[dict[str, Any], type[BaseModel]], BaseModel]]:
+    """Get a function to load a parameter if it is a Pydantic model
+
+    Args:
+        t: The type annotation of the parameter
+
+    Returns:
+        A function to load the parameter if it is a Pydantic model, otherwise None
+
+    """
+    origin = get_origin(t)
+
+    if origin is Annotated:
+        args = get_args(t)
+        if args:
+            return get_load_param_if_needed_function(args[0])
+        else:
+            # Invalid Annotated usage
+            return None
+
+    # Handle generic types (list[str], dict[str,Any], Union[...], etc.) or where t is not a type at all
+    # This means it's not a BaseModel subclass
+    if origin is not None or not isinstance(t, type):
+        return None
+
+    def load_base_model(v: dict[str, Any], model_type: type[BaseModel]) -> BaseModel:
+        return model_type(**v)
+
+    # Check if it's a class and a subclass of BaseModel
+    if issubclass(t, BaseModel):
+        return load_base_model
+    else:
+        return None
+
+
+@export_module("autogen.tools")
+def load_basemodels_if_needed(func: Callable[..., Any]) -> Callable[..., Any]:
+    """A decorator to load the parameters of a function if they are Pydantic models
+
+    Args:
+        func: The function with annotated parameters
+
+    Returns:
+        A function that loads the parameters before calling the original function
+
+    """
+    # get the type annotations of the parameters
+    typed_signature = get_typed_signature(func)
+    param_annotations = get_param_annotations(typed_signature)
+
+    # get functions for loading BaseModels when needed based on the type annotations
+    kwargs_mapping_with_nones = {k: get_load_param_if_needed_function(t) for k, t in param_annotations.items()}
+
+    # remove the None values
+    kwargs_mapping = {k: f for k, f in kwargs_mapping_with_nones.items() if f is not None}
+
+    # a function that loads the parameters before calling the original function
+    @functools.wraps(func)
+    def _load_parameters_if_needed(*args: Any, **kwargs: Any) -> Any:
+        # load the BaseModels if needed
+        for k, f in kwargs_mapping.items():
+            kwargs[k] = f(kwargs[k], param_annotations[k])
+
+        # call the original function
+        return func(*args, **kwargs)
+
+    @functools.wraps(func)
+    async def _a_load_parameters_if_needed(*args: Any, **kwargs: Any) -> Any:
+        # load the BaseModels if needed
+        for k, f in kwargs_mapping.items():
+            kwargs[k] = f(kwargs[k], param_annotations[k])
+
+        # call the original function
+        return await func(*args, **kwargs)
+
+    if inspect.iscoroutinefunction(func):
+        return _a_load_parameters_if_needed
+    else:
+        return _load_parameters_if_needed
+
+
+class _SerializableResult(BaseModel):
+    result: Any
+
+
+@export_module("autogen.tools")
+def serialize_to_str(x: Any) -> str:
+    if isinstance(x, str):
+        return x
+    if isinstance(x, BaseModel):
+        return x.model_dump_json()
+
+    retval_model = _SerializableResult(result=x)
+    try:
+        return str(retval_model.model_dump()["result"])
+    except Exception:
+        pass
+
+    # try json.dumps() and then just return str(x) if that fails too
+    try:
+        return json.dumps(x, ensure_ascii=False)
+    except Exception:
+        return str(x)