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

autogen/token_count_utils.py

@@ -0,0 +1,267 @@
+# 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 json
+import logging
+import re
+from typing import Any, Union
+
+import tiktoken
+
+from .agentchat.contrib.img_utils import num_tokens_from_gpt_image
+from .import_utils import optional_import_block
+
+# if PIL is not imported, we will redefine num_tokens_from_gpt_image to return 0 tokens for images
+# Otherwise, it would raise an ImportError
+with optional_import_block() as result:
+    import PIL  # noqa: F401
+
+pil_imported = result.is_successful
+if not pil_imported:
+
+    def num_tokens_from_gpt_image(*args, **kwargs):
+        return 0
+
+
+logger = logging.getLogger(__name__)
+logger.img_dependency_warned = False  # member variable to track if the warning has been logged
+
+
+def get_max_token_limit(model: str = "gpt-3.5-turbo-0613") -> int:
+    # Handle common azure model names/aliases
+    model = re.sub(r"^gpt\-?35", "gpt-3.5", model)
+    model = re.sub(r"^gpt4", "gpt-4", model)
+
+    max_token_limit = {
+        "gpt-3.5-turbo": 16385,
+        "gpt-3.5-turbo-0125": 16385,
+        "gpt-3.5-turbo-0301": 4096,
+        "gpt-3.5-turbo-0613": 4096,
+        "gpt-3.5-turbo-instruct": 4096,
+        "gpt-3.5-turbo-16k": 16385,
+        "gpt-3.5-turbo-16k-0613": 16385,
+        "gpt-3.5-turbo-1106": 16385,
+        "gpt-4": 8192,
+        "gpt-4-turbo": 128000,
+        "gpt-4-turbo-2024-04-09": 128000,
+        "gpt-4-32k": 32768,
+        "gpt-4-32k-0314": 32768,  # deprecate in Sep
+        "gpt-4-0314": 8192,  # deprecate in Sep
+        "gpt-4-0613": 8192,
+        "gpt-4-32k-0613": 32768,
+        "gpt-4-1106-preview": 128000,
+        "gpt-4-0125-preview": 128000,
+        "gpt-4-turbo-preview": 128000,
+        "gpt-4-vision-preview": 128000,
+        "gpt-4o": 128000,
+        "gpt-4o-2024-05-13": 128000,
+        "gpt-4o-2024-08-06": 128000,
+        "gpt-4o-2024-11-20": 128000,
+        "gpt-4o-mini": 128000,
+        "gpt-4o-mini-2024-07-18": 128000,
+    }
+    return max_token_limit[model]
+
+
+def percentile_used(input, model="gpt-3.5-turbo-0613"):
+    return count_token(input) / get_max_token_limit(model)
+
+
+def token_left(input: Union[str, list[str], dict[str, Any]], model="gpt-3.5-turbo-0613") -> int:
+    """Count number of tokens left for an OpenAI model.
+
+    Args:
+        input: (str, list, dict): Input to the model.
+        model: (str): Model name.
+
+    Returns:
+        int: Number of tokens left that the model can use for completion.
+    """
+    return get_max_token_limit(model) - count_token(input, model=model)
+
+
+def count_token(input: Union[str, list[str], dict[str, Any]], model: str = "gpt-3.5-turbo-0613") -> int:
+    """Count number of tokens used by an OpenAI model.
+
+    Args:
+        input: (str, list, dict): Input to the model.
+        model: (str): Model name.
+
+    Returns:
+        int: Number of tokens from the input.
+    """
+    if isinstance(input, str):
+        return _num_token_from_text(input, model=model)
+    elif isinstance(input, (list, dict)):
+        return _num_token_from_messages(input, model=model)
+    else:
+        raise ValueError(f"input must be str, list or dict, but we got {type(input)}")
+
+
+def _num_token_from_text(text: str, model: str = "gpt-3.5-turbo-0613"):
+    """Return the number of tokens used by a string."""
+    try:
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        logger.warning(f"Model {model} not found. Using cl100k_base encoding.")
+        encoding = tiktoken.get_encoding("cl100k_base")
+    return len(encoding.encode(text))
+
+
+def _num_token_from_messages(messages: Union[list[str], dict[str, Any]], model="gpt-3.5-turbo-0613"):
+    """Return the number of tokens used by a list of messages.
+
+    retrieved from https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb/
+    """
+    if isinstance(messages, dict):
+        messages = [messages]
+
+    try:
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        logger.warning(f"Model {model} not found. Using cl100k_base encoding.")
+        encoding = tiktoken.get_encoding("cl100k_base")
+    if model in {
+        "gpt-3.5-turbo-0613",
+        "gpt-3.5-turbo-16k-0613",
+        "gpt-4-0314",
+        "gpt-4-32k-0314",
+        "gpt-4-0613",
+        "gpt-4-32k-0613",
+        "gpt-4-turbo-preview",
+        "gpt-4-vision-preview",
+        "gpt-4o",
+        "gpt-4o-2024-05-13",
+        "gpt-4o-2024-08-06",
+        "gpt-4o-2024-11-20",
+        "gpt-4o-mini",
+        "gpt-4o-mini-2024-07-18",
+    }:
+        tokens_per_message = 3
+        tokens_per_name = 1
+    elif model == "gpt-3.5-turbo-0301":
+        tokens_per_message = 4  # every message follows <|start|>{role/name}\n{content}<|end|>\n
+        tokens_per_name = -1  # if there's a name, the role is omitted
+    elif "gpt-3.5-turbo" in model:
+        logger.info("gpt-3.5-turbo may update over time. Returning num tokens assuming gpt-3.5-turbo-0613.")
+        return _num_token_from_messages(messages, model="gpt-3.5-turbo-0613")
+    elif "gpt-4" in model:
+        logger.info("gpt-4 may update over time. Returning num tokens assuming gpt-4-0613.")
+        return _num_token_from_messages(messages, model="gpt-4-0613")
+    elif "gemini" in model:
+        logger.info("Gemini is not supported in tiktoken. Returning num tokens assuming gpt-4-0613.")
+        return _num_token_from_messages(messages, model="gpt-4-0613")
+    elif "claude" in model:
+        logger.info("Claude is not supported in tiktoken. Returning num tokens assuming gpt-4-0613.")
+        return _num_token_from_messages(messages, model="gpt-4-0613")
+    elif "mistral-" in model or "mixtral-" in model:
+        logger.info("Mistral.AI models are not supported in tiktoken. Returning num tokens assuming gpt-4-0613.")
+        return _num_token_from_messages(messages, model="gpt-4-0613")
+    elif "deepseek" in model:
+        logger.info("Deepseek models are not supported in tiktoken. Returning num tokens assuming gpt-4-0613.")
+        return _num_token_from_messages(messages, model="gpt-4-0613")
+    else:
+        raise NotImplementedError(
+            f"""_num_token_from_messages() is not implemented for model {model}. See https://github.com/openai/openai-python/blob/main/chatml.md for information on how messages are converted to tokens."""
+        )
+    num_tokens = 0
+    for message in messages:
+        num_tokens += tokens_per_message
+        for key, value in message.items():
+            if value is None:
+                continue
+
+            # handle content if images are in GPT-4-vision
+            if key == "content" and isinstance(value, list):
+                for part in value:
+                    if not isinstance(part, dict) or "type" not in part:
+                        continue
+                    if part["type"] == "text":
+                        num_tokens += len(encoding.encode(part["text"]))
+                    if "image_url" in part:
+                        assert "url" in part["image_url"]
+                        if not pil_imported and not logger.img_dependency_warned:
+                            logger.warning(
+                                "img_utils or PIL not imported. Skipping image token count."
+                                "Please install autogen with [lmm] option.",
+                            )
+                            logger.img_dependency_warned = True
+                        is_low_quality = "detail" in part["image_url"] and part["image_url"]["detail"] == "low"
+                        try:
+                            num_tokens += num_tokens_from_gpt_image(
+                                image_data=part["image_url"]["url"], model=model, low_quality=is_low_quality
+                            )
+                        except ValueError as e:
+                            logger.warning(f"Error in num_tokens_from_gpt_image: {e}")
+                continue
+
+            # function calls
+            if not isinstance(value, str):
+                try:
+                    value = json.dumps(value)
+                except TypeError:
+                    logger.warning(
+                        f"Value {value} is not a string and cannot be converted to json. It is a type: {type(value)} Skipping."
+                    )
+                    continue
+
+            num_tokens += len(encoding.encode(value))
+            if key == "name":
+                num_tokens += tokens_per_name
+    num_tokens += 3  # every reply is primed with <|start|>assistant<|message|>
+    return num_tokens
+
+
+def num_tokens_from_functions(functions, model="gpt-3.5-turbo-0613") -> int:
+    """Return the number of tokens used by a list of functions.
+
+    Args:
+        functions: (list): List of function descriptions that will be passed in model.
+        model: (str): Model name.
+
+    Returns:
+        int: Number of tokens from the function descriptions.
+    """
+    try:
+        encoding = tiktoken.encoding_for_model(model)
+    except KeyError:
+        logger.warning(f"Model {model} not found. Using cl100k_base encoding.")
+        encoding = tiktoken.get_encoding("cl100k_base")
+
+    num_tokens = 0
+    for function in functions:
+        function_tokens = len(encoding.encode(function["name"]))
+        function_tokens += len(encoding.encode(function["description"]))
+        function_tokens -= 2
+        if "parameters" in function:
+            parameters = function["parameters"]
+            if "properties" in parameters:
+                for properties_key in parameters["properties"]:
+                    function_tokens += len(encoding.encode(properties_key))
+                    v = parameters["properties"][properties_key]
+                    for field in v:
+                        if field == "type":
+                            function_tokens += 2
+                            function_tokens += len(encoding.encode(v["type"]))
+                        elif field == "description":
+                            function_tokens += 2
+                            function_tokens += len(encoding.encode(v["description"]))
+                        elif field == "enum":
+                            function_tokens -= 3
+                            for o in v["enum"]:
+                                function_tokens += 3
+                                function_tokens += len(encoding.encode(o))
+                        else:
+                            logger.warning(f"Not supported field {field}")
+                function_tokens += 11
+                if len(parameters["properties"]) == 0:
+                    function_tokens -= 2
+
+        num_tokens += function_tokens
+
+    num_tokens += 12
+    return num_tokens

autogen/tools/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .dependency_injection import BaseContext, ChatContext, Depends
+from .function_utils import get_function_schema, load_basemodels_if_needed, serialize_to_str
+from .tool import Tool, tool
+from .toolkit import Toolkit
+
+__all__ = [
+    "BaseContext",
+    "ChatContext",
+    "Depends",
+    "Tool",
+    "Toolkit",
+    "get_function_schema",
+    "load_basemodels_if_needed",
+    "serialize_to_str",
+    "tool",
+]

autogen/tools/contrib/__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 .time import TimeTool
+
+__all__ = [
+    "TimeTool",
+]

autogen/tools/contrib/time/__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 .time import TimeTool
+
+__all__ = ["TimeTool"]

autogen/tools/contrib/time/time.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import datetime
+from typing import Annotated
+
+from autogen.tools import Tool
+
+from ....doc_utils import export_module
+
+__all__ = ["TimeTool"]
+
+
+@export_module("autogen.tools.contrib")  # API Reference: autogen > tools > contrib > TimeAgent
+class TimeTool(Tool):
+    """Outputs the current date and time of the computer."""
+
+    def __init__(
+        self,
+        *,
+        date_time_format: str = "%Y-%m-%d %H:%M:%S",  # This is a parameter that is unique to this tool
+    ):
+        """Get the date and time of the computer.
+
+        Args:
+            date_time_format (str, optional): The format of the date and time. Defaults to "%Y-%m-%d %H:%M:%S".
+        """
+
+        self._date_time_format = date_time_format
+
+        async def get_date_and_time(
+            date_time_format: Annotated[str, "date/time Python format"] = self._date_time_format,
+        ) -> str:
+            return datetime.now().strftime(date_time_format)
+
+        super().__init__(
+            name="date_time",
+            description="Get the current computer's date and time.",
+            func_or_tool=get_date_and_time,
+        )

autogen/tools/dependency_injection.py

@@ -0,0 +1,254 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import inspect
+import sys
+from abc import ABC
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Optional, TypeVar, Union, get_type_hints
+
+from ..agentchat import Agent
+from ..doc_utils import export_module
+from ..fast_depends import Depends as FastDepends
+from ..fast_depends import inject
+from ..fast_depends.dependencies import model
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = [
+    "BaseContext",
+    "ChatContext",
+    "Depends",
+    "Field",
+    "get_context_params",
+    "inject_params",
+    "on",
+    "remove_params",
+]
+
+
+@export_module("autogen.tools")
+class BaseContext(ABC):
+    """Base class for context classes.
+
+    This is the base class for defining various context types that may be used
+    throughout the application. It serves as a parent for specific context classes.
+    """
+
+    pass
+
+
+@export_module("autogen.tools")
+class ChatContext(BaseContext):
+    """ChatContext class that extends BaseContext.
+
+    This class is used to represent a chat context that holds a list of messages.
+    It inherits from `BaseContext` and adds the `messages` attribute.
+    """
+
+    def __init__(self, agent: "ConversableAgent") -> None:
+        """Initializes the ChatContext with an agent.
+
+        Args:
+            agent: The agent to use for retrieving chat messages.
+        """
+        self._agent = agent
+
+    @property
+    def chat_messages(self) -> dict[Agent, list[dict[Any, Any]]]:
+        """The messages in the chat.
+
+        Returns:
+            A dictionary of agents and their messages.
+        """
+        return self._agent.chat_messages
+
+    @property
+    def last_message(self) -> Optional[dict[str, Any]]:
+        """The last message in the chat.
+
+        Returns:
+            The last message in the chat.
+        """
+        return self._agent.last_message()
+
+
+T = TypeVar("T")
+
+
+def on(x: T) -> Callable[[], T]:
+    def inner(ag2_x: T = x) -> T:
+        return ag2_x
+
+    return inner
+
+
+@export_module("autogen.tools")
+def Depends(x: Any) -> Any:  # noqa: N802
+    """Creates a dependency for injection based on the provided context or type.
+
+    Args:
+        x: The context or dependency to be injected.
+
+    Returns:
+        A FastDepends object that will resolve the dependency for injection.
+    """
+    if isinstance(x, BaseContext):
+        return FastDepends(lambda: x)
+
+    return FastDepends(x)
+
+
+def get_context_params(func: Callable[..., Any], subclass: Union[type[BaseContext], type[ChatContext]]) -> list[str]:
+    """Gets the names of the context parameters in a function signature.
+
+    Args:
+        func: The function to inspect for context parameters.
+        subclass: The subclass to search for.
+
+    Returns:
+        A list of parameter names that are instances of the specified subclass.
+    """
+    sig = inspect.signature(func)
+    return [p.name for p in sig.parameters.values() if _is_context_param(p, subclass=subclass)]
+
+
+def _is_context_param(
+    param: inspect.Parameter, subclass: Union[type[BaseContext], type[ChatContext]] = BaseContext
+) -> bool:
+    # param.annotation.__args__[0] is used to handle Annotated[MyContext, Depends(MyContext(b=2))]
+    param_annotation = param.annotation.__args__[0] if hasattr(param.annotation, "__args__") else param.annotation
+    try:
+        return isinstance(param_annotation, type) and issubclass(param_annotation, subclass)
+    except TypeError:
+        return False
+
+
+def _is_depends_param(param: inspect.Parameter) -> bool:
+    return isinstance(param.default, model.Depends) or (
+        hasattr(param.annotation, "__metadata__")
+        and type(param.annotation.__metadata__) == tuple
+        and isinstance(param.annotation.__metadata__[0], model.Depends)
+    )
+
+
+def remove_params(func: Callable[..., Any], sig: inspect.Signature, params: Iterable[str]) -> None:
+    new_signature = sig.replace(parameters=[p for p in sig.parameters.values() if p.name not in params])
+    func.__signature__ = new_signature  # type: ignore[attr-defined]
+
+
+def _remove_injected_params_from_signature(func: Callable[..., Any]) -> Callable[..., Any]:
+    # This is a workaround for Python 3.9+ where staticmethod.__func__ is accessible
+    if sys.version_info >= (3, 9) and isinstance(func, staticmethod) and hasattr(func, "__func__"):
+        func = _fix_staticmethod(func)
+
+    sig = inspect.signature(func)
+    params_to_remove = [p.name for p in sig.parameters.values() if _is_context_param(p) or _is_depends_param(p)]
+    remove_params(func, sig, params_to_remove)
+    return func
+
+
+class Field:
+    """Represents a description field for use in type annotations.
+
+    This class is used to store a description for an annotated field, often used for
+    documenting or validating fields in a context or data model.
+    """
+
+    def __init__(self, description: str) -> None:
+        """Initializes the Field with a description.
+
+        Args:
+            description: The description text for the field.
+        """
+        self._description = description
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+
+def _string_metadata_to_description_field(func: Callable[..., Any]) -> Callable[..., Any]:
+    type_hints = get_type_hints(func, include_extras=True)
+
+    for _, annotation in type_hints.items():
+        # Check if the annotation itself has metadata (using __metadata__)
+        if hasattr(annotation, "__metadata__"):
+            metadata = annotation.__metadata__
+            if metadata and isinstance(metadata[0], str):
+                # Replace string metadata with Field
+                annotation.__metadata__ = (Field(description=metadata[0]),)
+        # For Python < 3.11, annotations like `Optional` are stored as `Union`, so metadata
+        # would be in the first element of __args__ (e.g., `__args__[0]` for `int` in `Optional[int]`)
+        elif hasattr(annotation, "__args__") and hasattr(annotation.__args__[0], "__metadata__"):
+            metadata = annotation.__args__[0].__metadata__
+            if metadata and isinstance(metadata[0], str):
+                # Replace string metadata with Field
+                annotation.__args__[0].__metadata__ = (Field(description=metadata[0]),)
+    return func
+
+
+def _fix_staticmethod(f: Callable[..., Any]) -> Callable[..., Any]:
+    # This is a workaround for Python 3.9+ where staticmethod.__func__ is accessible
+    if sys.version_info >= (3, 9) and isinstance(f, staticmethod) and hasattr(f, "__func__"):
+
+        @wraps(f.__func__)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return f.__func__(*args, **kwargs)  # type: ignore[attr-defined]
+
+        wrapper.__name__ = f.__func__.__name__
+
+        f = wrapper
+    return f
+
+
+def _set_return_annotation_to_any(f: Callable[..., Any]) -> Callable[..., Any]:
+    if inspect.iscoroutinefunction(f):
+
+        @functools.wraps(f)
+        async def _a_wrapped_func(*args: Any, **kwargs: Any) -> Any:
+            return await f(*args, **kwargs)
+
+        wrapped_func = _a_wrapped_func
+
+    else:
+
+        @functools.wraps(f)
+        def _wrapped_func(*args: Any, **kwargs: Any) -> Any:
+            return f(*args, **kwargs)
+
+        wrapped_func = _wrapped_func
+
+    sig = inspect.signature(f)
+
+    # Change the return annotation directly on the signature of the wrapper
+    wrapped_func.__signature__ = sig.replace(return_annotation=Any)  # type: ignore[attr-defined]
+
+    return wrapped_func
+
+
+def inject_params(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Injects parameters into a function, removing injected dependencies from its signature.
+
+    This function is used to modify a function by injecting dependencies and removing
+    injected parameters from the function's signature.
+
+    Args:
+        f: The function to modify with dependency injection.
+
+    Returns:
+        The modified function with injected dependencies and updated signature.
+    """
+    # This is a workaround for Python 3.9+ where staticmethod.__func__ is accessible
+    if sys.version_info >= (3, 9) and isinstance(f, staticmethod) and hasattr(f, "__func__"):
+        f = _fix_staticmethod(f)
+
+    f = _string_metadata_to_description_field(f)
+    f = _set_return_annotation_to_any(f)
+    f = inject(f)
+    f = _remove_injected_params_from_signature(f)
+
+    return f

autogen/tools/experimental/__init__.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 .browser_use import BrowserUseTool
+from .crawl4ai import Crawl4AITool
+from .deep_research import DeepResearchTool
+from .duckduckgo import DuckDuckGoSearchTool
+from .google_search import GoogleSearchTool, YoutubeSearchTool
+from .messageplatform import (
+    DiscordRetrieveTool,
+    DiscordSendTool,
+    SlackRetrieveRepliesTool,
+    SlackRetrieveTool,
+    SlackSendTool,
+    TelegramRetrieveTool,
+    TelegramSendTool,
+)
+from .perplexity import PerplexitySearchTool
+from .tavily import TavilySearchTool
+from .web_search_preview import WebSearchPreviewTool
+from .wikipedia import WikipediaPageLoadTool, WikipediaQueryRunTool
+
+__all__ = [
+    "BrowserUseTool",
+    "Crawl4AITool",
+    "DeepResearchTool",
+    "DiscordRetrieveTool",
+    "DiscordSendTool",
+    "DuckDuckGoSearchTool",
+    "GoogleSearchTool",
+    "PerplexitySearchTool",
+    "SlackRetrieveRepliesTool",
+    "SlackRetrieveTool",
+    "SlackSendTool",
+    "TavilySearchTool",
+    "TelegramRetrieveTool",
+    "TelegramSendTool",
+    "WebSearchPreviewTool",
+    "WikipediaPageLoadTool",
+    "WikipediaQueryRunTool",
+    "YoutubeSearchTool",
+]

autogen/tools/experimental/browser_use/__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 .browser_use import BrowserUseResult, BrowserUseTool, ExtractedContent
+
+__all__ = ["BrowserUseResult", "BrowserUseTool", "ExtractedContent"]