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

autogen/agentchat/utils.py

@@ -0,0 +1,206 @@
+# 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 re
+from typing import Any, Optional, Union
+
+from ..doc_utils import export_module
+from .agent import Agent
+
+
+def consolidate_chat_info(
+    chat_info: Union[dict[str, Any], list[dict[str, Any]]], uniform_sender: Optional[Agent] = None
+) -> None:
+    if isinstance(chat_info, dict):
+        chat_info = [chat_info]
+    for c in chat_info:
+        if uniform_sender is None:
+            assert "sender" in c, "sender must be provided."
+            sender = c["sender"]
+        else:
+            sender = uniform_sender
+        assert "recipient" in c, "recipient must be provided."
+        summary_method = c.get("summary_method")
+        assert (
+            summary_method is None or callable(summary_method) or summary_method in ("last_msg", "reflection_with_llm")
+        ), "summary_method must be a string chosen from 'reflection_with_llm' or 'last_msg' or a callable, or None."
+        if summary_method == "reflection_with_llm":
+            assert sender.client is not None or c["recipient"].client is not None, (
+                "llm client must be set in either the recipient or sender when summary_method is reflection_with_llm."
+            )
+
+
+@export_module("autogen")
+def gather_usage_summary(agents: list[Agent]) -> dict[str, dict[str, Any]]:
+    r"""Gather usage summary from all agents.
+
+    Args:
+        agents: (list): List of agents.
+
+    Returns:
+        dictionary: A dictionary containing two keys:
+            - "usage_including_cached_inference": Cost information on the total usage, including the tokens in cached inference.
+            - "usage_excluding_cached_inference": Cost information on the usage of tokens, excluding the tokens in cache. No larger than "usage_including_cached_inference".
+
+    Example:
+    ```python
+    {
+        "usage_including_cached_inference": {
+            "total_cost": 0.0006090000000000001,
+            "gpt-35-turbo": {
+                "cost": 0.0006090000000000001,
+                "prompt_tokens": 242,
+                "completion_tokens": 123,
+                "total_tokens": 365,
+            },
+        },
+        "usage_excluding_cached_inference": {
+            "total_cost": 0.0006090000000000001,
+            "gpt-35-turbo": {
+                "cost": 0.0006090000000000001,
+                "prompt_tokens": 242,
+                "completion_tokens": 123,
+                "total_tokens": 365,
+            },
+        },
+    }
+    ```
+
+    Note:
+    If none of the agents incurred any cost (not having a client), then the usage_including_cached_inference and usage_excluding_cached_inference will be `{'total_cost': 0}`.
+    """
+
+    def aggregate_summary(usage_summary: dict[str, Any], agent_summary: dict[str, Any]) -> None:
+        if agent_summary is None:
+            return
+        usage_summary["total_cost"] += agent_summary.get("total_cost", 0)
+        for model, data in agent_summary.items():
+            if model != "total_cost":
+                if model not in usage_summary:
+                    usage_summary[model] = data.copy()
+                else:
+                    usage_summary[model]["cost"] += data.get("cost", 0)
+                    usage_summary[model]["prompt_tokens"] += data.get("prompt_tokens", 0)
+                    usage_summary[model]["completion_tokens"] += data.get("completion_tokens", 0)
+                    usage_summary[model]["total_tokens"] += data.get("total_tokens", 0)
+
+    usage_including_cached_inference = {"total_cost": 0}
+    usage_excluding_cached_inference = {"total_cost": 0}
+
+    for agent in agents:
+        if getattr(agent, "client", None):
+            aggregate_summary(usage_including_cached_inference, agent.client.total_usage_summary)  # type: ignore[attr-defined]
+            aggregate_summary(usage_excluding_cached_inference, agent.client.actual_usage_summary)  # type: ignore[attr-defined]
+
+    return {
+        "usage_including_cached_inference": usage_including_cached_inference,
+        "usage_excluding_cached_inference": usage_excluding_cached_inference,
+    }
+
+
+def parse_tags_from_content(tag: str, content: Union[str, list[dict[str, Any]]]) -> list[dict[str, Any]]:
+    """Parses HTML style tags from message contents.
+
+    The parsing is done by looking for patterns in the text that match the format of HTML tags. The tag to be parsed is
+    specified as an argument to the function. The function looks for this tag in the text and extracts its content. The
+    content of a tag is everything that is inside the tag, between the opening and closing angle brackets. The content
+    can be a single string or a set of attribute-value pairs.
+
+    Examples:
+        `<img http://example.com/image.png> -> [{"tag": "img", "attr": {"src": "http://example.com/image.png"}, "match": re.Match}]`
+        ```<audio text="Hello I'm a robot" prompt="whisper"> ->
+                [{"tag": "audio", "attr": {"text": "Hello I'm a robot", "prompt": "whisper"}, "match": re.Match}]```
+
+    Args:
+        tag (str): The HTML style tag to be parsed.
+        content (Union[str, list[dict[str, Any]]]): The message content to parse. Can be a string or a list of content
+            items.
+
+    Returns:
+        list[dict[str, str]]: A list of dictionaries, where each dictionary represents a parsed tag. Each dictionary
+            contains three key-value pairs: 'type' which is the tag, 'attr' which is a dictionary of the parsed attributes,
+            and 'match' which is a regular expression match object.
+
+    Raises:
+        ValueError: If the content is not a string or a list.
+    """
+    results = []
+    if isinstance(content, str):
+        results.extend(_parse_tags_from_text(tag, content))
+    # Handles case for multimodal messages.
+    elif isinstance(content, list):
+        for item in content:
+            if item.get("type") == "text":
+                results.extend(_parse_tags_from_text(tag, item["text"]))
+    else:
+        raise ValueError(f"content must be str or list, but got {type(content)}")
+
+    return results
+
+
+def _parse_tags_from_text(tag: str, text: str) -> list[dict[str, Any]]:
+    pattern = re.compile(f"<{tag} (.*?)>")
+
+    results = []
+    for match in re.finditer(pattern, text):
+        tag_attr = match.group(1).strip()
+        attr = _parse_attributes_from_tags(tag_attr)
+
+        results.append({"tag": tag, "attr": attr, "match": match})
+    return results
+
+
+def _parse_attributes_from_tags(tag_content: str) -> dict[str, str]:
+    pattern = r"([^ ]+)"
+    attrs = re.findall(pattern, tag_content)
+    reconstructed_attrs = _reconstruct_attributes(attrs)
+
+    def _append_src_value(content: dict[str, str], value: Any) -> None:
+        if "src" in content:
+            content["src"] += f" {value}"
+        else:
+            content["src"] = value
+
+    content: dict[str, str] = {}
+    for attr in reconstructed_attrs:
+        if "=" not in attr:
+            _append_src_value(content, attr)
+            continue
+
+        key, value = attr.split("=", 1)
+        if value.startswith("'") or value.startswith('"'):
+            content[key] = value[1:-1]  # remove quotes
+        else:
+            _append_src_value(content, attr)
+
+    return content
+
+
+def _reconstruct_attributes(attrs: list[str]) -> list[str]:
+    """Reconstructs attributes from a list of strings where some attributes may be split across multiple elements."""
+
+    def is_attr(attr: str) -> bool:
+        if "=" in attr:
+            _, value = attr.split("=", 1)
+            if value.startswith("'") or value.startswith('"'):
+                return True
+        return False
+
+    reconstructed = []
+    found_attr = False
+    for attr in attrs:
+        if is_attr(attr):
+            reconstructed.append(attr)
+            found_attr = True
+        else:
+            if found_attr:
+                reconstructed[-1] += f" {attr}"
+                found_attr = True
+            elif reconstructed:
+                reconstructed[-1] += f" {attr}"
+            else:
+                reconstructed.append(attr)
+    return reconstructed

autogen/agents/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0

autogen/agents/contrib/__init__.py

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

autogen/agents/contrib/time/__init__.py

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

autogen/agents/contrib/time/time_reply_agent.py

@@ -0,0 +1,73 @@
+# 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
+
+from .... import Agent, ConversableAgent, OpenAIWrapper
+from ....doc_utils import export_module
+
+__all__ = ["TimeReplyAgent"]
+
+
+@export_module("autogen.agents.contrib")  # API Reference: autogen > agents > contrib > TimeReplyAgent
+class TimeReplyAgent(ConversableAgent):
+    """A simple agent that returns the current time.
+
+    Use it is as a reference for creating new agents with a reply-based approach (as opposed to tool-based).
+
+    This agent will return the date and time whenever it needs to reply."""
+
+    DEFAULT_SYSTEM_MESSAGE = "You are a calendar agent that just returns the date and time."
+
+    def __init__(
+        self,
+        date_time_format: str = "%Y-%m-%d %H:%M:%S",  # This is a parameter that is unique to this agent
+        output_prefix: str = "Tick, tock, the current date/time is ",
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the TimeReplyAgent.
+
+        Args:
+            date_time_format: The format in which the date and time should be returned.
+            output_prefix: The prefix to add to the output message.
+            **kwargs: Additional parameters to pass to the base
+        """
+        # Here we handle a ConversableAgent parameter through the kwargs
+        # We will pass this through when we run init() the base class
+        # Note: For this TimeReplyAgent, the LLM is not used so this won't affect the behavior of this agent
+        system_message = kwargs.pop("system_message", self.DEFAULT_SYSTEM_MESSAGE)
+
+        # Store the date and time format on the agent, prefixed with an underscore to indicate it's a private variable
+        self._date_time_format = date_time_format
+
+        self._output_prefix = output_prefix
+
+        # Initialise the base class, passing through the system_message parameter
+        super().__init__(system_message=system_message, **kwargs)
+
+        # Our reply function.
+        # This one is simple, but yours will be more complex and
+        # may even contain another AG2 workflow inside it
+        def get_date_time_reply(
+            agent: ConversableAgent,
+            messages: Optional[list[dict[str, Any]]] = None,
+            sender: Optional[Agent] = None,
+            config: Optional[OpenAIWrapper] = None,
+        ) -> tuple[bool, dict[str, Any]]:
+            from datetime import datetime
+
+            now = datetime.now()
+
+            # Format the date and time as a string (e.g., "2025-02-25 14:30:00")
+            current_date_time = now.strftime(self._date_time_format)
+
+            # Final reply, with the date/time as the message
+            return True, {"content": f"{self._output_prefix}{current_date_time}."}
+
+        # Register our reply function with the agent
+        self.register_reply(
+            trigger=[Agent, None],
+            reply_func=get_date_time_reply,  # This is the function that will be called when the agent needs to reply
+            remove_other_reply_funcs=True,  # Removing all other reply functions so only this one will be used
+        )

autogen/agents/contrib/time/time_tool_agent.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from .... import ConversableAgent
+from ....doc_utils import export_module
+from ....tools.contrib import TimeTool
+
+__all__ = ["TimeToolAgent"]
+
+
+@export_module("autogen.agents.contrib")  # API Reference: autogen > agents > contrib > TimeToolAgent
+class TimeToolAgent(ConversableAgent):
+    """A simple agent that returns the current time using tools
+
+    Use it is as a reference for creating new agents with a tool-based approach (as opposed to reply-based).
+
+    This agent will call the TimeTool and return the date and time whenever it needs to reply."""
+
+    DEFAULT_SYSTEM_MESSAGE = (
+        "You are a calendar agent that uses tools to return the date and time. "
+        "When you reply, say 'Tick, tock, the current date/time is ' followed by the date and time in the exact format the tool provided."
+    )
+
+    def __init__(
+        self,
+        date_time_format: str = "%Y-%m-%d %H:%M:%S",  # This is a parameter that is unique to this agent
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the TimeToolAgent.
+
+        Args:
+            date_time_format: The format in which the date and time should be returned.
+            **kwargs: Additional keyword arguments passed to the parent ConversableAgent class.
+        """
+        # Here we handle a ConversableAgent parameter through the kwargs
+        # We will pass this through when we run init() the base class
+        # Use this to tailor the return message
+        system_message = kwargs.pop("system_message", self.DEFAULT_SYSTEM_MESSAGE)
+
+        # Store the date and time format on the agent, prefixed with an underscore to indicate it's a private variable
+        self._date_time_format = date_time_format
+
+        self._time_tool = TimeTool(date_time_format=self._date_time_format)
+
+        # Initialise the base class, passing through the system_message parameter
+        super().__init__(system_message=system_message, **kwargs)
+
+        self.register_for_llm()(self._time_tool)

autogen/agents/experimental/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .deep_research import DeepResearchAgent
+from .discord import DiscordAgent
+from .document_agent import DocAgent, DoclingDocIngestAgent, InMemoryQueryEngine, VectorChromaQueryEngine
+from .reasoning import ReasoningAgent, ThinkNode
+from .slack import SlackAgent
+from .telegram import TelegramAgent
+from .websurfer import WebSurferAgent
+from .wikipedia import WikipediaAgent
+
+__all__ = [
+    "DeepResearchAgent",
+    "DiscordAgent",
+    "DocAgent",
+    "DoclingDocIngestAgent",
+    "InMemoryQueryEngine",
+    "ReasoningAgent",
+    "SlackAgent",
+    "TelegramAgent",
+    "ThinkNode",
+    "VectorChromaQueryEngine",
+    "WebSurferAgent",
+    "WikipediaAgent",
+]

autogen/agents/experimental/deep_research/__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 .deep_research import DeepResearchAgent
+
+__all__ = ["DeepResearchAgent"]

autogen/agents/experimental/deep_research/deep_research.py

@@ -0,0 +1,52 @@
+# 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
+
+from .... import ConversableAgent
+from ....doc_utils import export_module
+from ....llm_config import LLMConfig
+from ....tools.experimental import DeepResearchTool
+
+__all__ = ["DeepResearchAgent"]
+
+
+@export_module("autogen.agents.experimental")
+class DeepResearchAgent(ConversableAgent):
+    """An agent that performs deep research tasks."""
+
+    DEFAULT_PROMPT = "You are a deep research agent. You have the ability to get information from the web and perform research tasks."
+
+    def __init__(
+        self,
+        name: str,
+        llm_config: Optional[Union[LLMConfig, dict[str, Any]]] = None,
+        system_message: Optional[Union[str, list[str]]] = DEFAULT_PROMPT,
+        max_web_steps: int = 30,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the DeepResearchAgent.
+
+        Args:
+            name: The name of the agent.
+            llm_config: The LLM configuration.
+            system_message: The system message. Defaults to DEFAULT_PROMPT.
+            max_web_steps: The maximum number of web steps. Defaults to 30.
+            **kwargs: Additional keyword arguments to pass to the ConversableAgent.
+        """
+        llm_config = LLMConfig.get_current_llm_config(llm_config)  # type: ignore[arg-type]
+
+        super().__init__(
+            name=name,
+            system_message=system_message,
+            llm_config=llm_config,
+            **kwargs,
+        )
+
+        self.tool = DeepResearchTool(
+            llm_config=llm_config,  # type: ignore[arg-type]
+            max_web_steps=max_web_steps,
+        )
+
+        self.register_for_llm()(self.tool)

autogen/agents/experimental/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 DiscordAgent
+
+__all__ = ["DiscordAgent"]

autogen/agents/experimental/discord/discord.py

@@ -0,0 +1,66 @@
+# 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
+
+from .... import ConversableAgent
+from ....doc_utils import export_module
+from ....tools.experimental import DiscordRetrieveTool, DiscordSendTool
+
+__all__ = ["DiscordAgent"]
+
+
+@export_module("autogen.agents.experimental")
+class DiscordAgent(ConversableAgent):
+    """An agent that can send messages and retrieve messages on Discord."""
+
+    DEFAULT_SYSTEM_MESSAGE = (
+        "You are a helpful AI assistant that communicates through Discord. "
+        "Remember that Discord uses Markdown for formatting and has a character limit. "
+        "Keep messages clear and concise, and consider using appropriate formatting when helpful."
+    )
+
+    def __init__(
+        self,
+        name: str,
+        system_message: Optional[str] = None,
+        *,
+        bot_token: str,
+        channel_name: str,
+        guild_name: str,
+        has_writing_instructions: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the DiscordAgent.
+
+        Args:
+            name: name of the agent.
+            system_message: system message for the ChatCompletion inference.
+            bot_token: Discord bot token
+            channel_name: Channel name where messages will be sent / retrieved
+            guild_name: Guild (server) name where the channel is located
+            has_writing_instructions: Whether to add writing instructions to the system message. Defaults to True.
+            **kwargs: Additional keyword arguments passed to the parent ConversableAgent class.
+        """
+        discord_system_message = system_message or self.DEFAULT_SYSTEM_MESSAGE
+
+        self._send_tool = DiscordSendTool(bot_token=bot_token, channel_name=channel_name, guild_name=guild_name)
+        self._retrieve_tool = DiscordRetrieveTool(bot_token=bot_token, channel_name=channel_name, guild_name=guild_name)
+
+        # Add formatting instructions
+        if has_writing_instructions:
+            formatting_instructions = (
+                "\nFormat guidelines for Discord:\n"
+                "1. Max message length: 2000 characters\n"
+                "2. Supports Markdown formatting\n"
+                "3. Can use ** for bold, * for italic, ``` for code blocks\n"
+                "4. Consider using appropriate emojis when suitable\n"
+            )
+
+            discord_system_message = discord_system_message + formatting_instructions
+
+        super().__init__(name=name, system_message=discord_system_message, **kwargs)
+
+        self.register_for_llm()(self._send_tool)
+        self.register_for_llm()(self._retrieve_tool)

autogen/agents/experimental/document_agent/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .chroma_query_engine import VectorChromaQueryEngine
+from .docling_doc_ingest_agent import DoclingDocIngestAgent
+from .document_agent import DocAgent
+from .document_utils import handle_input
+from .inmemory_query_engine import InMemoryQueryEngine
+from .parser_utils import docling_parse_docs
+
+__all__ = [
+    "DocAgent",
+    "DoclingDocIngestAgent",
+    "InMemoryQueryEngine",
+    "VectorChromaQueryEngine",
+    "docling_parse_docs",
+    "handle_input",
+]