langroid 0.31.2__py3-none-any.whl → 0.33.3__py3-none-any.whl

langroid/agent/base.py

@@ -1,1981 +0,0 @@
-import asyncio
-import copy
-import inspect
-import json
-import logging
-import re
-from abc import ABC
-from collections import OrderedDict
-from contextlib import ExitStack
-from types import SimpleNamespace
-from typing import (
-    Any,
-    Callable,
-    Coroutine,
-    Dict,
-    List,
-    Optional,
-    Set,
-    Tuple,
-    Type,
-    TypeVar,
-    cast,
-    get_args,
-    get_origin,
-    no_type_check,
-)
-
-from rich import print
-from rich.console import Console
-from rich.markup import escape
-from rich.prompt import Prompt
-
-from langroid.agent.chat_document import ChatDocMetaData, ChatDocument
-from langroid.agent.tool_message import ToolMessage
-from langroid.agent.xml_tool_message import XMLToolMessage
-from langroid.exceptions import XMLException
-from langroid.language_models.base import (
-    LanguageModel,
-    LLMConfig,
-    LLMFunctionCall,
-    LLMMessage,
-    LLMResponse,
-    LLMTokenUsage,
-    OpenAIToolCall,
-    StreamingIfAllowed,
-    ToolChoiceTypes,
-)
-from langroid.language_models.openai_gpt import OpenAIGPT, OpenAIGPTConfig
-from langroid.mytypes import Entity
-from langroid.parsing.parse_json import extract_top_level_json
-from langroid.parsing.parser import Parser, ParsingConfig
-from langroid.prompts.prompts_config import PromptsConfig
-from langroid.pydantic_v1 import (
-    BaseSettings,
-    Field,
-    ValidationError,
-    validator,
-)
-from langroid.utils.configuration import settings
-from langroid.utils.constants import (
-    DONE,
-    NO_ANSWER,
-    PASS,
-    PASS_TO,
-    SEND_TO,
-)
-from langroid.utils.object_registry import ObjectRegistry
-from langroid.utils.output import status
-from langroid.utils.types import from_string, to_string
-from langroid.vector_store.base import VectorStore, VectorStoreConfig
-
-ORCHESTRATION_STRINGS = [DONE, PASS, PASS_TO, SEND_TO]
-console = Console(quiet=settings.quiet)
-
-logger = logging.getLogger(__name__)
-
-T = TypeVar("T")
-
-
-class AgentConfig(BaseSettings):
-    """
-    General config settings for an LLM agent. This is nested, combining configs of
-    various components.
-    """
-
-    name: str = "LLM-Agent"
-    debug: bool = False
-    vecdb: Optional[VectorStoreConfig] = None
-    llm: Optional[LLMConfig] = OpenAIGPTConfig()
-    parsing: Optional[ParsingConfig] = ParsingConfig()
-    prompts: Optional[PromptsConfig] = PromptsConfig()
-    show_stats: bool = True  # show token usage/cost stats?
-    add_to_registry: bool = True  # register agent in ObjectRegistry?
-    respond_tools_only: bool = False  # respond only to tool messages (not plain text)?
-    # allow multiple tool messages in a single response?
-    allow_multiple_tools: bool = True
-    human_prompt: str = (
-        "Human (respond or q, x to exit current level, " "or hit enter to continue)"
-    )
-
-    @validator("name")
-    def check_name_alphanum(cls, v: str) -> str:
-        if not re.match(r"^[a-zA-Z0-9_-]+$", v):
-            raise ValueError(
-                "The name must only contain alphanumeric characters, "
-                "underscores, or hyphens, with no spaces"
-            )
-        return v
-
-
-def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
-    pass
-
-
-async def async_noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
-    pass
-
-
-async def async_lambda_noop_fn() -> Callable[..., Coroutine[Any, Any, None]]:
-    return async_noop_fn
-
-
-class Agent(ABC):
-    """
-    An Agent is an abstraction that encapsulates mainly two components:
-
-    - a language model (LLM)
-    - a vector store (vecdb)
-
-    plus associated components such as a parser, and variables that hold
-    information about any tool/function-calling messages that have been defined.
-    """
-
-    id: str = Field(default_factory=lambda: ObjectRegistry.new_id())
-    # OpenAI tool-calls awaiting response; update when a tool result with Role.TOOL
-    # is added to self.message_history
-    oai_tool_calls: List[OpenAIToolCall] = []
-    # Index of ALL tool calls generated by the agent
-    oai_tool_id2call: Dict[str, OpenAIToolCall] = {}
-
-    def __init__(self, config: AgentConfig = AgentConfig()):
-        self.config = config
-        self.lock = asyncio.Lock()  # for async access to update self.llm.usage_cost
-        self.dialog: List[Tuple[str, str]] = []  # seq of LLM (prompt, response) tuples
-        self.llm_tools_map: Dict[str, Type[ToolMessage]] = {}
-        self.llm_tools_handled: Set[str] = set()
-        self.llm_tools_usable: Set[str] = set()
-        self.llm_tools_known: Set[str] = set()  # all known tools, handled/used or not
-        # Indicates which tool-names are allowed to be inferred when
-        # the LLM "forgets" to include the request field in its
-        # tool-call.
-        self.enabled_requests_for_inference: Optional[Set[str]] = (
-            None  # If None, we allow all
-        )
-        self.interactive: bool = True  # may be modified by Task wrapper
-        self.token_stats_str = ""
-        self.default_human_response: Optional[str] = None
-        self._indent = ""
-        self.llm = LanguageModel.create(config.llm)
-        self.vecdb = VectorStore.create(config.vecdb) if config.vecdb else None
-        self.tool_error = False
-        if config.parsing is not None and self.config.llm is not None:
-            # token_encoding_model is used to obtain the tokenizer,
-            # so in case it's an OpenAI model, we ensure that the tokenizer
-            # corresponding to the model is used.
-            if isinstance(self.llm, OpenAIGPT) and self.llm.is_openai_chat_model():
-                config.parsing.token_encoding_model = self.llm.config.chat_model
-        self.parser: Optional[Parser] = (
-            Parser(config.parsing) if config.parsing else None
-        )
-        if config.add_to_registry:
-            ObjectRegistry.register_object(self)
-
-        self.callbacks = SimpleNamespace(
-            start_llm_stream=lambda: noop_fn,
-            start_llm_stream_async=async_lambda_noop_fn,
-            cancel_llm_stream=noop_fn,
-            finish_llm_stream=noop_fn,
-            show_llm_response=noop_fn,
-            show_agent_response=noop_fn,
-            get_user_response=None,
-            get_user_response_async=None,
-            get_last_step=noop_fn,
-            set_parent_agent=noop_fn,
-            show_error_message=noop_fn,
-            show_start_response=noop_fn,
-        )
-        Agent.init_state(self)
-
-    def init_state(self) -> None:
-        """Initialize all state vars. Called by Task.run() if restart is True"""
-        self.total_llm_token_cost = 0.0
-        self.total_llm_token_usage = 0
-
-    @staticmethod
-    def from_id(id: str) -> "Agent":
-        return cast(Agent, ObjectRegistry.get(id))
-
-    @staticmethod
-    def delete_id(id: str) -> None:
-        ObjectRegistry.remove(id)
-
-    def entity_responders(
-        self,
-    ) -> List[
-        Tuple[Entity, Callable[[None | str | ChatDocument], None | ChatDocument]]
-    ]:
-        """
-        Sequence of (entity, response_method) pairs. This sequence is used
-            in a `Task` to respond to the current pending message.
-            See `Task.step()` for details.
-        Returns:
-            Sequence of (entity, response_method) pairs.
-        """
-        return [
-            (Entity.AGENT, self.agent_response),
-            (Entity.LLM, self.llm_response),
-            (Entity.USER, self.user_response),
-        ]
-
-    def entity_responders_async(
-        self,
-    ) -> List[
-        Tuple[
-            Entity,
-            Callable[
-                [None | str | ChatDocument], Coroutine[Any, Any, None | ChatDocument]
-            ],
-        ]
-    ]:
-        """
-        Async version of `entity_responders`. See there for details.
-        """
-        return [
-            (Entity.AGENT, self.agent_response_async),
-            (Entity.LLM, self.llm_response_async),
-            (Entity.USER, self.user_response_async),
-        ]
-
-    @property
-    def indent(self) -> str:
-        """Indentation to print before any responses from the agent's entities."""
-        return self._indent
-
-    @indent.setter
-    def indent(self, value: str) -> None:
-        self._indent = value
-
-    def update_dialog(self, prompt: str, output: str) -> None:
-        self.dialog.append((prompt, output))
-
-    def get_dialog(self) -> List[Tuple[str, str]]:
-        return self.dialog
-
-    def clear_dialog(self) -> None:
-        self.dialog = []
-
-    def _get_tool_list(
-        self, message_class: Optional[Type[ToolMessage]] = None
-    ) -> List[str]:
-        """
-        If `message_class` is None, return a list of all known tool names.
-        Otherwise, first add the tool name corresponding to the message class
-        (which is the value of the `request` field of the message class),
-        to the `self.llm_tools_map` dict, and then return a list
-        containing this tool name.
-
-        Args:
-            message_class (Optional[Type[ToolMessage]]): The message class whose tool
-                name is to be returned; Optional, default is None.
-                if None, return a list of all known tool names.
-
-        Returns:
-            List[str]: List of tool names: either just the tool name corresponding
-                to the message class, or all known tool names
-                (when `message_class` is None).
-
-        """
-        if message_class is None:
-            return list(self.llm_tools_map.keys())
-
-        if not issubclass(message_class, ToolMessage):
-            raise ValueError("message_class must be a subclass of ToolMessage")
-        tool = message_class.default_value("request")
-
-        """
-        if tool has handler method explicitly defined - use it,
-        otherwise use the tool name as the handler
-        """
-        if hasattr(message_class, "_handler"):
-            handler = getattr(message_class, "_handler", tool)
-        else:
-            handler = tool
-
-        self.llm_tools_map[tool] = message_class
-        if (
-            hasattr(message_class, "handle")
-            and inspect.isfunction(message_class.handle)
-            and not hasattr(self, handler)
-        ):
-            """
-            If the message class has a `handle` method,
-            and agent does NOT have a tool handler method,
-            then we create a method for the agent whose name
-            is the value of `handler`, and whose body is the `handle` method.
-            This removes a separate step of having to define this method
-            for the agent, and also keeps the tool definition AND handling
-            in one place, i.e. in the message class.
-            See `tests/main/test_stateless_tool_messages.py` for an example.
-            """
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.handle).parameters) > 1
-            )
-            if has_chat_doc_arg:
-                setattr(self, handler, lambda obj, chat_doc: obj.handle(chat_doc))
-            else:
-                setattr(self, handler, lambda obj: obj.handle())
-        elif (
-            hasattr(message_class, "response")
-            and inspect.isfunction(message_class.response)
-            and not hasattr(self, handler)
-        ):
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.response).parameters) > 2
-            )
-            if has_chat_doc_arg:
-                setattr(
-                    self, handler, lambda obj, chat_doc: obj.response(self, chat_doc)
-                )
-            else:
-                setattr(self, handler, lambda obj: obj.response(self))
-
-        if hasattr(message_class, "handle_message_fallback") and (
-            inspect.isfunction(message_class.handle_message_fallback)
-        ):
-            setattr(
-                self,
-                "handle_message_fallback",
-                lambda msg: message_class.handle_message_fallback(self, msg),
-            )
-
-        async_handler_name = f"{handler}_async"
-        if (
-            hasattr(message_class, "handle_async")
-            and inspect.isfunction(message_class.handle_async)
-            and not hasattr(self, async_handler_name)
-        ):
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.handle_async).parameters) > 1
-            )
-
-            if has_chat_doc_arg:
-
-                @no_type_check
-                async def handler(obj, chat_doc):
-                    return await obj.handle_async(chat_doc)
-
-            else:
-
-                @no_type_check
-                async def handler(obj):
-                    return await obj.handle_async()
-
-            setattr(self, async_handler_name, handler)
-        elif (
-            hasattr(message_class, "response_async")
-            and inspect.isfunction(message_class.response_async)
-            and not hasattr(self, async_handler_name)
-        ):
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.response_async).parameters) > 2
-            )
-
-            if has_chat_doc_arg:
-
-                @no_type_check
-                async def handler(obj, chat_doc):
-                    return await obj.response_async(self, chat_doc)
-
-            else:
-
-                @no_type_check
-                async def handler(obj):
-                    return await obj.response_async(self)
-
-            setattr(self, async_handler_name, handler)
-
-        return [tool]
-
-    def enable_message_handling(
-        self, message_class: Optional[Type[ToolMessage]] = None
-    ) -> None:
-        """
-        Enable an agent to RESPOND (i.e. handle) a "tool" message of a specific type
-            from LLM. Also "registers" (i.e. adds) the `message_class` to the
-            `self.llm_tools_map` dict.
-
-        Args:
-            message_class (Optional[Type[ToolMessage]]): The message class to enable;
-                Optional; if None, all known message classes are enabled for handling.
-
-        """
-        for t in self._get_tool_list(message_class):
-            self.llm_tools_handled.add(t)
-
-    def disable_message_handling(
-        self,
-        message_class: Optional[Type[ToolMessage]] = None,
-    ) -> None:
-        """
-        Disable a message class from being handled by this Agent.
-
-        Args:
-            message_class (Optional[Type[ToolMessage]]): The message class to disable.
-                If None, all message classes are disabled.
-        """
-        for t in self._get_tool_list(message_class):
-            self.llm_tools_handled.discard(t)
-
-    def sample_multi_round_dialog(self) -> str:
-        """
-        Generate a sample multi-round dialog based on enabled message classes.
-        Returns:
-            str: The sample dialog string.
-        """
-        enabled_classes: List[Type[ToolMessage]] = list(self.llm_tools_map.values())
-        # use at most 2 sample conversations, no need to be exhaustive;
-        sample_convo = [
-            msg_cls().usage_examples(random=True)  # type: ignore
-            for i, msg_cls in enumerate(enabled_classes)
-            if i < 2
-        ]
-        return "\n\n".join(sample_convo)
-
-    def create_agent_response(
-        self,
-        content: str | None = None,
-        content_any: Any = None,
-        tool_messages: List[ToolMessage] = [],
-        oai_tool_calls: Optional[List[OpenAIToolCall]] = None,
-        oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto",
-        oai_tool_id2result: OrderedDict[str, str] | None = None,
-        function_call: LLMFunctionCall | None = None,
-        recipient: str = "",
-    ) -> ChatDocument:
-        """Template for agent_response."""
-        return self.response_template(
-            Entity.AGENT,
-            content=content,
-            content_any=content_any,
-            tool_messages=tool_messages,
-            oai_tool_calls=oai_tool_calls,
-            oai_tool_choice=oai_tool_choice,
-            oai_tool_id2result=oai_tool_id2result,
-            function_call=function_call,
-            recipient=recipient,
-        )
-
-    def _agent_response_final(
-        self,
-        msg: Optional[str | ChatDocument],
-        results: Optional[str | OrderedDict[str, str] | ChatDocument],
-    ) -> Optional[ChatDocument]:
-        """
-        Convert results to final response.
-        """
-        if results is None:
-            return None
-        if isinstance(results, str):
-            results_str = results
-        elif isinstance(results, ChatDocument):
-            results_str = results.content
-        elif isinstance(results, dict):
-            results_str = json.dumps(results, indent=2)
-        if not settings.quiet:
-            console.print(f"[red]{self.indent}", end="")
-            print(f"[red]Agent: {escape(results_str)}")
-        maybe_json = len(extract_top_level_json(results_str)) > 0
-        self.callbacks.show_agent_response(
-            content=results_str,
-            language="json" if maybe_json else "text",
-        )
-        if isinstance(results, ChatDocument):
-            # Preserve trail of tool_ids for OpenAI Assistant fn-calls
-            results.metadata.tool_ids = (
-                [] if msg is None or isinstance(msg, str) else msg.metadata.tool_ids
-            )
-            return results
-        sender_name = self.config.name
-        if isinstance(msg, ChatDocument) and msg.function_call is not None:
-            # if result was from handling an LLM `function_call`,
-            # set sender_name to name of the function_call
-            sender_name = msg.function_call.name
-
-        results_str, id2result, oai_tool_id = self.process_tool_results(
-            results if isinstance(results, str) else "",
-            id2result=None if isinstance(results, str) else results,
-            tool_calls=(msg.oai_tool_calls if isinstance(msg, ChatDocument) else None),
-        )
-        return ChatDocument(
-            content=results_str,
-            oai_tool_id2result=id2result,
-            metadata=ChatDocMetaData(
-                source=Entity.AGENT,
-                sender=Entity.AGENT,
-                sender_name=sender_name,
-                oai_tool_id=oai_tool_id,
-                # preserve trail of tool_ids for OpenAI Assistant fn-calls
-                tool_ids=(
-                    [] if msg is None or isinstance(msg, str) else msg.metadata.tool_ids
-                ),
-            ),
-        )
-
-    async def agent_response_async(
-        self,
-        msg: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        Asynch version of `agent_response`. See there for details.
-        """
-        if msg is None:
-            return None
-
-        results = await self.handle_message_async(msg)
-
-        return self._agent_response_final(msg, results)
-
-    def agent_response(
-        self,
-        msg: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        Response from the "agent itself", typically (but not only)
-        used to handle LLM's "tool message" or `function_call`
-        (e.g. OpenAI `function_call`).
-        Args:
-            msg (str|ChatDocument): the input to respond to: if msg is a string,
-                and it contains a valid JSON-structured "tool message", or
-                if msg is a ChatDocument, and it contains a `function_call`.
-        Returns:
-            Optional[ChatDocument]: the response, packaged as a ChatDocument
-
-        """
-        if msg is None:
-            return None
-
-        results = self.handle_message(msg)
-
-        return self._agent_response_final(msg, results)
-
-    def process_tool_results(
-        self,
-        results: str,
-        id2result: OrderedDict[str, str] | None,
-        tool_calls: List[OpenAIToolCall] | None = None,
-    ) -> Tuple[str, Dict[str, str] | None, str | None]:
-        """
-        Process results from a response, based on whether
-        they are results of OpenAI tool-calls from THIS agent, so that
-        we can construct an appropriate LLMMessage that contains tool results.
-
-        Args:
-            results (str): A possible string result from handling tool(s)
-            id2result (OrderedDict[str,str]|None): A dict of OpenAI tool id -> result,
-                if there are multiple tool results.
-            tool_calls (List[OpenAIToolCall]|None): List of OpenAI tool-calls that the
-                results are a response to.
-
-        Return:
-            - str: The response string
-            - Dict[str,str]|None: A dict of OpenAI tool id -> result, if there are
-                multiple tool results.
-            - str|None: tool_id if there was a single tool result
-
-        """
-        id2result_ = copy.deepcopy(id2result) if id2result is not None else None
-        results_str = ""
-        oai_tool_id = None
-
-        if results != "":
-            # in this case ignore id2result
-            assert (
-                id2result is None
-            ), "id2result should be None when results string is non-empty!"
-            results_str = results
-            if len(self.oai_tool_calls) > 0:
-                # We only have one result, so in case there is a
-                # "pending" OpenAI tool-call, we expect no more than 1 such.
-                assert (
-                    len(self.oai_tool_calls) == 1
-                ), "There are multiple pending tool-calls, but only one result!"
-                # We record the tool_id of the tool-call that
-                # the result is a response to, so that ChatDocument.to_LLMMessage
-                # can properly set the `tool_call_id` field of the LLMMessage.
-                oai_tool_id = self.oai_tool_calls[0].id
-        elif id2result is not None and id2result_ is not None:  # appease mypy
-            if len(id2result_) == len(self.oai_tool_calls):
-                # if the number of pending tool calls equals the number of results,
-                # then ignore the ids in id2result, and use the results in order,
-                # which is preserved since id2result is an OrderedDict.
-                assert len(id2result_) > 1, "Expected to see > 1 result in id2result!"
-                results_str = ""
-                id2result_ = OrderedDict(
-                    zip(
-                        [tc.id or "" for tc in self.oai_tool_calls], id2result_.values()
-                    )
-                )
-            else:
-                assert (
-                    tool_calls is not None
-                ), "tool_calls cannot be None when id2result is not None!"
-                # This must be an OpenAI tool id -> result map;
-                # However some ids may not correspond to the tool-calls in the list of
-                # pending tool-calls (self.oai_tool_calls).
-                # Such results are concatenated into a simple string, to store in the
-                # ChatDocument.content, and the rest
-                # (i.e. those that DO correspond to tools in self.oai_tool_calls)
-                # are stored as a dict in ChatDocument.oai_tool_id2result.
-
-                # OAI tools from THIS agent, awaiting response
-                pending_tool_ids = [tc.id for tc in self.oai_tool_calls]
-                # tool_calls that the results are a response to
-                # (but these may have been sent from another agent, hence may not be in
-                # self.oai_tool_calls)
-                parent_tool_id2name = {
-                    tc.id: tc.function.name
-                    for tc in tool_calls or []
-                    if tc.function is not None
-                }
-
-                # (id, result) for result NOT corresponding to self.oai_tool_calls,
-                # i.e. these are results of EXTERNAL tool-calls from another agent.
-                external_tool_id_results = []
-
-                for tc_id, result in id2result.items():
-                    if tc_id not in pending_tool_ids:
-                        external_tool_id_results.append((tc_id, result))
-                        id2result_.pop(tc_id)
-                if len(external_tool_id_results) == 0:
-                    results_str = ""
-                elif len(external_tool_id_results) == 1:
-                    results_str = external_tool_id_results[0][1]
-                else:
-                    results_str = "\n\n".join(
-                        [
-                            f"Result from tool/function "
-                            f"{parent_tool_id2name[id]}: {result}"
-                            for id, result in external_tool_id_results
-                        ]
-                    )
-
-                if len(id2result_) == 0:
-                    id2result_ = None
-                elif len(id2result_) == 1 and len(external_tool_id_results) == 0:
-                    results_str = list(id2result_.values())[0]
-                    oai_tool_id = list(id2result_.keys())[0]
-                    id2result_ = None
-
-        return results_str, id2result_, oai_tool_id
-
-    def response_template(
-        self,
-        e: Entity,
-        content: str | None = None,
-        content_any: Any = None,
-        tool_messages: List[ToolMessage] = [],
-        oai_tool_calls: Optional[List[OpenAIToolCall]] = None,
-        oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto",
-        oai_tool_id2result: OrderedDict[str, str] | None = None,
-        function_call: LLMFunctionCall | None = None,
-        recipient: str = "",
-    ) -> ChatDocument:
-        """Template for response from entity `e`."""
-        return ChatDocument(
-            content=content or "",
-            content_any=content_any,
-            tool_messages=tool_messages,
-            oai_tool_calls=oai_tool_calls,
-            oai_tool_id2result=oai_tool_id2result,
-            function_call=function_call,
-            oai_tool_choice=oai_tool_choice,
-            metadata=ChatDocMetaData(
-                source=e, sender=e, sender_name=self.config.name, recipient=recipient
-            ),
-        )
-
-    def create_user_response(
-        self,
-        content: str | None = None,
-        content_any: Any = None,
-        tool_messages: List[ToolMessage] = [],
-        oai_tool_calls: List[OpenAIToolCall] | None = None,
-        oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto",
-        oai_tool_id2result: OrderedDict[str, str] | None = None,
-        function_call: LLMFunctionCall | None = None,
-        recipient: str = "",
-    ) -> ChatDocument:
-        """Template for user_response."""
-        return self.response_template(
-            e=Entity.USER,
-            content=content,
-            content_any=content_any,
-            tool_messages=tool_messages,
-            oai_tool_calls=oai_tool_calls,
-            oai_tool_choice=oai_tool_choice,
-            oai_tool_id2result=oai_tool_id2result,
-            function_call=function_call,
-            recipient=recipient,
-        )
-
-    def user_can_respond(self, msg: Optional[str | ChatDocument] = None) -> bool:
-        """
-        Whether the user can respond to a message.
-
-        Args:
-            msg (str|ChatDocument): the string to respond to.
-
-        Returns:
-
-        """
-        # When msg explicitly addressed to user, this means an actual human response
-        # is being sought.
-        need_human_response = (
-            isinstance(msg, ChatDocument) and msg.metadata.recipient == Entity.USER
-        )
-
-        if not self.interactive and not need_human_response:
-            return False
-
-        return True
-
-    def _user_response_final(
-        self, msg: Optional[str | ChatDocument], user_msg: str
-    ) -> Optional[ChatDocument]:
-        """
-        Convert user_msg to final response.
-        """
-        if not user_msg:
-            need_human_response = (
-                isinstance(msg, ChatDocument) and msg.metadata.recipient == Entity.USER
-            )
-            user_msg = (
-                (self.default_human_response or "null") if need_human_response else ""
-            )
-        user_msg = user_msg.strip()
-
-        tool_ids = []
-        if msg is not None and isinstance(msg, ChatDocument):
-            tool_ids = msg.metadata.tool_ids
-
-        # only return non-None result if user_msg not empty
-        if not user_msg:
-            return None
-        else:
-            if user_msg.startswith("SYSTEM"):
-                user_msg = user_msg.replace("SYSTEM", "").strip()
-                source = Entity.SYSTEM
-                sender = Entity.SYSTEM
-            else:
-                source = Entity.USER
-                sender = Entity.USER
-            return ChatDocument(
-                content=user_msg,
-                metadata=ChatDocMetaData(
-                    source=source,
-                    sender=sender,
-                    # preserve trail of tool_ids for OpenAI Assistant fn-calls
-                    tool_ids=tool_ids,
-                ),
-            )
-
-    async def user_response_async(
-        self,
-        msg: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        Asynch version of `user_response`. See there for details.
-        """
-        if not self.user_can_respond(msg):
-            return None
-
-        if self.default_human_response is not None:
-            user_msg = self.default_human_response
-        else:
-            if (
-                self.callbacks.get_user_response_async is not None
-                and self.callbacks.get_user_response_async is not async_noop_fn
-            ):
-                user_msg = await self.callbacks.get_user_response_async(prompt="")
-            elif self.callbacks.get_user_response is not None:
-                user_msg = self.callbacks.get_user_response(prompt="")
-            else:
-                user_msg = Prompt.ask(
-                    f"[blue]{self.indent}"
-                    + self.config.human_prompt
-                    + f"\n{self.indent}"
-                )
-
-        return self._user_response_final(msg, user_msg)
-
-    def user_response(
-        self,
-        msg: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        Get user response to current message. Could allow (human) user to intervene
-        with an actual answer, or quit using "q" or "x"
-
-        Args:
-            msg (str|ChatDocument): the string to respond to.
-
-        Returns:
-            (str) User response, packaged as a ChatDocument
-
-        """
-
-        if not self.user_can_respond(msg):
-            return None
-
-        if self.default_human_response is not None:
-            user_msg = self.default_human_response
-        else:
-            if self.callbacks.get_user_response is not None:
-                # ask user with empty prompt: no need for prompt
-                # since user has seen the conversation so far.
-                # But non-empty prompt can be useful when Agent
-                # uses a tool that requires user input, or in other scenarios.
-                user_msg = self.callbacks.get_user_response(prompt="")
-            else:
-                user_msg = Prompt.ask(
-                    f"[blue]{self.indent}"
-                    + self.config.human_prompt
-                    + f"\n{self.indent}"
-                )
-
-        return self._user_response_final(msg, user_msg)
-
-    @no_type_check
-    def llm_can_respond(self, message: Optional[str | ChatDocument] = None) -> bool:
-        """
-        Whether the LLM can respond to a message.
-        Args:
-            message (str|ChatDocument): message or ChatDocument object to respond to.
-
-        Returns:
-
-        """
-        if self.llm is None:
-            return False
-
-        if message is not None and len(self.try_get_tool_messages(message)) > 0:
-            # if there is a valid "tool" message (either JSON or via `function_call`)
-            # then LLM cannot respond to it
-            return False
-
-        return True
-
-    def can_respond(self, message: Optional[str | ChatDocument] = None) -> bool:
-        """
-        Whether the agent can respond to a message.
-        Used in Task.py to skip a sub-task when we know it would not respond.
-        Args:
-            message (str|ChatDocument): message or ChatDocument object to respond to.
-        """
-        tools = self.try_get_tool_messages(message)
-        if len(tools) == 0 and self.config.respond_tools_only:
-            return False
-        if message is not None and self.has_only_unhandled_tools(message):
-            # The message has tools that are NOT enabled to be handled by this agent,
-            # which means the agent cannot respond to it.
-            return False
-        return True
-
-    def create_llm_response(
-        self,
-        content: str | None = None,
-        content_any: Any = None,
-        tool_messages: List[ToolMessage] = [],
-        oai_tool_calls: None | List[OpenAIToolCall] = None,
-        oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto",
-        oai_tool_id2result: OrderedDict[str, str] | None = None,
-        function_call: LLMFunctionCall | None = None,
-        recipient: str = "",
-    ) -> ChatDocument:
-        """Template for llm_response."""
-        return self.response_template(
-            Entity.LLM,
-            content=content,
-            content_any=content_any,
-            tool_messages=tool_messages,
-            oai_tool_calls=oai_tool_calls,
-            oai_tool_choice=oai_tool_choice,
-            oai_tool_id2result=oai_tool_id2result,
-            function_call=function_call,
-            recipient=recipient,
-        )
-
-    @no_type_check
-    async def llm_response_async(
-        self,
-        message: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        Asynch version of `llm_response`. See there for details.
-        """
-        if message is None or not self.llm_can_respond(message):
-            return None
-
-        if isinstance(message, ChatDocument):
-            prompt = message.content
-        else:
-            prompt = message
-
-        output_len = self.config.llm.max_output_tokens
-        if self.num_tokens(prompt) + output_len > self.llm.completion_context_length():
-            output_len = self.llm.completion_context_length() - self.num_tokens(prompt)
-            if output_len < self.config.llm.min_output_tokens:
-                raise ValueError(
-                    """
-                Token-length of Prompt + Output is longer than the
-                completion context length of the LLM!
-                """
-                )
-            else:
-                logger.warning(
-                    f"""
-                Requested output length has been shortened to {output_len}
-                so that the total length of Prompt + Output is less than
-                the completion context length of the LLM.
-                """
-                )
-
-        with StreamingIfAllowed(self.llm, self.llm.get_stream()):
-            response = await self.llm.agenerate(prompt, output_len)
-
-        if not self.llm.get_stream() or response.cached and not settings.quiet:
-            # We would have already displayed the msg "live" ONLY if
-            # streaming was enabled, AND we did not find a cached response.
-            # If we are here, it means the response has not yet been displayed.
-            cached = f"[red]{self.indent}(cached)[/red]" if response.cached else ""
-            print(cached + "[green]" + escape(response.message))
-        async with self.lock:
-            self.update_token_usage(
-                response,
-                prompt,
-                self.llm.get_stream(),
-                chat=False,  # i.e. it's a completion model not chat model
-                print_response_stats=self.config.show_stats and not settings.quiet,
-            )
-        cdoc = ChatDocument.from_LLMResponse(response, displayed=True)
-        # Preserve trail of tool_ids for OpenAI Assistant fn-calls
-        cdoc.metadata.tool_ids = (
-            [] if isinstance(message, str) else message.metadata.tool_ids
-        )
-        return cdoc
-
-    @no_type_check
-    def llm_response(
-        self,
-        message: Optional[str | ChatDocument] = None,
-    ) -> Optional[ChatDocument]:
-        """
-        LLM response to a prompt.
-        Args:
-            message (str|ChatDocument): prompt string, or ChatDocument object
-
-        Returns:
-            Response from LLM, packaged as a ChatDocument
-        """
-        if message is None or not self.llm_can_respond(message):
-            return None
-
-        if isinstance(message, ChatDocument):
-            prompt = message.content
-        else:
-            prompt = message
-
-        with ExitStack() as stack:  # for conditionally using rich spinner
-            if not self.llm.get_stream():
-                # show rich spinner only if not streaming!
-                cm = status("LLM responding to message...")
-                stack.enter_context(cm)
-            output_len = self.config.llm.max_output_tokens
-            if (
-                self.num_tokens(prompt) + output_len
-                > self.llm.completion_context_length()
-            ):
-                output_len = self.llm.completion_context_length() - self.num_tokens(
-                    prompt
-                )
-                if output_len < self.config.llm.min_output_tokens:
-                    raise ValueError(
-                        """
-                    Token-length of Prompt + Output is longer than the
-                    completion context length of the LLM!
-                    """
-                    )
-                else:
-                    logger.warning(
-                        f"""
-                    Requested output length has been shortened to {output_len}
-                    so that the total length of Prompt + Output is less than
-                    the completion context length of the LLM.
-                    """
-                    )
-            if self.llm.get_stream() and not settings.quiet:
-                console.print(f"[green]{self.indent}", end="")
-            response = self.llm.generate(prompt, output_len)
-
-        if not self.llm.get_stream() or response.cached and not settings.quiet:
-            # we would have already displayed the msg "live" ONLY if
-            # streaming was enabled, AND we did not find a cached response
-            # If we are here, it means the response has not yet been displayed.
-            cached = f"[red]{self.indent}(cached)[/red]" if response.cached else ""
-            console.print(f"[green]{self.indent}", end="")
-            print(cached + "[green]" + escape(response.message))
-        self.update_token_usage(
-            response,
-            prompt,
-            self.llm.get_stream(),
-            chat=False,  # i.e. it's a completion model not chat model
-            print_response_stats=self.config.show_stats and not settings.quiet,
-        )
-        cdoc = ChatDocument.from_LLMResponse(response, displayed=True)
-        # Preserve trail of tool_ids for OpenAI Assistant fn-calls
-        cdoc.metadata.tool_ids = (
-            [] if isinstance(message, str) else message.metadata.tool_ids
-        )
-        return cdoc
-
-    def has_tool_message_attempt(self, msg: str | ChatDocument | None) -> bool:
-        """
-        Check whether msg contains a Tool/fn-call attempt (by the LLM).
-
-        CAUTION: This uses self.get_tool_messages(msg) which as a side-effect
-        may update msg.tool_messages when msg is a ChatDocument, if there are
-        any tools in msg.
-        """
-        if msg is None:
-            return False
-        try:
-            tools = self.get_tool_messages(msg)
-            return len(tools) > 0
-        except (ValidationError, XMLException):
-            # there is a tool/fn-call attempt but had a validation error,
-            # so we still consider this a tool message "attempt"
-            return True
-        return False
-
-    def _tool_recipient_match(self, tool: ToolMessage) -> bool:
-        """Is tool is handled by this agent
-        and an explicit `recipient` field doesn't preclude this agent from handling it?
-        """
-        if tool.default_value("request") not in self.llm_tools_handled:
-            return False
-        if hasattr(tool, "recipient") and isinstance(tool.recipient, str):
-            return tool.recipient == "" or tool.recipient == self.config.name
-        return True
-
-    def has_only_unhandled_tools(self, msg: str | ChatDocument) -> bool:
-        """
-        Does the msg have at least one tool, and ALL tools are
-        disabled for handling by this agent?
-        """
-        if msg is None:
-            return False
-        tools = self.try_get_tool_messages(msg, all_tools=True)
-        if len(tools) == 0:
-            return False
-        return all(not self._tool_recipient_match(t) for t in tools)
-
-    def try_get_tool_messages(
-        self,
-        msg: str | ChatDocument | None,
-        all_tools: bool = False,
-    ) -> List[ToolMessage]:
-        try:
-            return self.get_tool_messages(msg, all_tools)
-        except (ValidationError, XMLException):
-            return []
-
-    def get_tool_messages(
-        self,
-        msg: str | ChatDocument | None,
-        all_tools: bool = False,
-    ) -> List[ToolMessage]:
-        """
-        Get ToolMessages recognized in msg, handle-able by this agent.
-        NOTE: as a side-effect, this will update msg.tool_messages
-        when msg is a ChatDocument and msg contains tool messages.
-        The intent here is that update=True should be set ONLY within agent_response()
-        or agent_response_async() methods. In other words, we want to persist the
-        msg.tool_messages only AFTER the agent has had a chance to handle the tools.
-
-        Args:
-            msg (str|ChatDocument): the message to extract tools from.
-            all_tools (bool):
-                - if True, return all tools,
-                    i.e. any recognized tool in self.llm_tools_known,
-                    whether it is handled by this agent or not;
-                - otherwise, return only the tools handled by this agent.
-
-        Returns:
-            List[ToolMessage]: list of ToolMessage objects
-        """
-
-        if msg is None:
-            return []
-
-        if isinstance(msg, str):
-            json_tools = self.get_formatted_tool_messages(msg)
-            if all_tools:
-                return json_tools
-            else:
-                return [
-                    t
-                    for t in json_tools
-                    if self._tool_recipient_match(t) and t.default_value("request")
-                ]
-
-        if all_tools and len(msg.all_tool_messages) > 0:
-            # We've already identified all_tool_messages in the msg;
-            # return the corresponding ToolMessage objects
-            return msg.all_tool_messages
-        if len(msg.tool_messages) > 0:
-            # We've already found tool_messages,
-            # (either via OpenAI Fn-call or Langroid-native ToolMessage);
-            # or they were added by an agent_response.
-            # note these could be from a forwarded msg from another agent,
-            # so return ONLY the messages THIS agent to enabled to handle.
-            return msg.tool_messages
-        assert isinstance(msg, ChatDocument)
-        if (
-            msg.content != ""
-            and msg.oai_tool_calls is None
-            and msg.function_call is None
-        ):
-
-            tools = self.get_formatted_tool_messages(msg.content)
-            msg.all_tool_messages = tools
-            # filter for actually handle-able tools, and recipient is this agent
-            my_tools = [t for t in tools if self._tool_recipient_match(t)]
-            msg.tool_messages = my_tools
-
-            if all_tools:
-                return tools
-            else:
-                return my_tools
-
-        # otherwise, we look for `tool_calls` (possibly multiple)
-        tools = self.get_oai_tool_calls_classes(msg)
-        msg.all_tool_messages = tools
-        my_tools = [t for t in tools if self._tool_recipient_match(t)]
-        msg.tool_messages = my_tools
-
-        if len(tools) == 0:
-            # otherwise, we look for a `function_call`
-            fun_call_cls = self.get_function_call_class(msg)
-            tools = [fun_call_cls] if fun_call_cls is not None else []
-            msg.all_tool_messages = tools
-            my_tools = [t for t in tools if self._tool_recipient_match(t)]
-            msg.tool_messages = my_tools
-        if all_tools:
-            return tools
-        else:
-            return my_tools
-
-    def get_formatted_tool_messages(self, input_str: str) -> List[ToolMessage]:
-        """
-        Returns ToolMessage objects (tools) corresponding to
-        tool-formatted substrings, if any.
-        ASSUMPTION - These tools are either ALL JSON-based, or ALL XML-based
-        (i.e. not a mix of both).
-        Terminology: a "formatted tool msg" is one which the LLM generates as
-            part of its raw string output, rather than within a JSON object
-            in the API response (i.e. this method does not extract tools/fns returned
-            by OpenAI's tools/fns API or similar APIs).
-
-        Args:
-            input_str (str): input string, typically a message sent by an LLM
-
-        Returns:
-            List[ToolMessage]: list of ToolMessage objects
-        """
-        self.tool_error = False
-        substrings = XMLToolMessage.find_candidates(input_str)
-        is_json = False
-        if len(substrings) == 0:
-            substrings = extract_top_level_json(input_str)
-            is_json = len(substrings) > 0
-            if not is_json:
-                return []
-
-        results = [self._get_one_tool_message(j, is_json) for j in substrings]
-        valid_results = [r for r in results if r is not None]
-        # If any tool is correctly formed we do not set the flag
-        if len(valid_results) > 0:
-            self.tool_error = False
-        return valid_results
-
-    def get_function_call_class(self, msg: ChatDocument) -> Optional[ToolMessage]:
-        """
-        From ChatDocument (constructed from an LLM Response), get the `ToolMessage`
-        corresponding to the `function_call` if it exists.
-        """
-        if msg.function_call is None:
-            return None
-        tool_name = msg.function_call.name
-        tool_msg = msg.function_call.arguments or {}
-        if tool_name not in self.llm_tools_handled:
-            logger.warning(
-                f"""
-                The function_call '{tool_name}' is not handled
-                by the agent named '{self.config.name}'!
-                If you intended this agent to handle this function_call,
-                either the fn-call name is incorrectly generated by the LLM,
-                (in which case you may need to adjust your LLM instructions),
-                or you need to enable this agent to handle this fn-call.
-                """
-            )
-            if tool_name not in self.all_llm_tools_known:
-                self.tool_error = True
-            return None
-        self.tool_error = False
-        tool_class = self.llm_tools_map[tool_name]
-        tool_msg.update(dict(request=tool_name))
-        tool = tool_class.parse_obj(tool_msg)
-        return tool
-
-    def get_oai_tool_calls_classes(self, msg: ChatDocument) -> List[ToolMessage]:
-        """
-        From ChatDocument (constructed from an LLM Response), get
-         a list of ToolMessages corresponding to the `tool_calls`, if any.
-        """
-
-        if msg.oai_tool_calls is None:
-            return []
-        tools = []
-        all_errors = True
-        for tc in msg.oai_tool_calls:
-            if tc.function is None:
-                continue
-            tool_name = tc.function.name
-            tool_msg = tc.function.arguments or {}
-            if tool_name not in self.llm_tools_handled:
-                logger.warning(
-                    f"""
-                    The tool_call '{tool_name}' is not handled
-                    by the agent named '{self.config.name}'!
-                    If you intended this agent to handle this function_call,
-                    either the fn-call name is incorrectly generated by the LLM,
-                    (in which case you may need to adjust your LLM instructions),
-                    or you need to enable this agent to handle this fn-call.
-                    """
-                )
-                continue
-            all_errors = False
-            tool_class = self.llm_tools_map[tool_name]
-            tool_msg.update(dict(request=tool_name))
-            tool = tool_class.parse_obj(tool_msg)
-            tool.id = tc.id or ""
-            tools.append(tool)
-        # When no tool is valid, set the recovery flag
-        self.tool_error = all_errors
-        return tools
-
-    def tool_validation_error(self, ve: ValidationError) -> str:
-        """
-        Handle a validation error raised when parsing a tool message,
-            when there is a legit tool name used, but it has missing/bad fields.
-        Args:
-            tool (ToolMessage): The tool message that failed validation
-            ve (ValidationError): The exception raised
-
-        Returns:
-            str: The error message to send back to the LLM
-        """
-        tool_name = cast(ToolMessage, ve.model).default_value("request")
-        bad_field_errors = "\n".join(
-            [f"{e['loc']}: {e['msg']}" for e in ve.errors() if "loc" in e]
-        )
-        return f"""
-        There were one or more errors in your attempt to use the
-        TOOL or function_call named '{tool_name}':
-        {bad_field_errors}
-        Please write your message again, correcting the errors.
-        """
-
-    def _get_multiple_orch_tool_errs(
-        self, tools: List[ToolMessage]
-    ) -> List[str | ChatDocument | None]:
-        """
-        Return error document if the message contains multiple orchestration tools
-        """
-        # check whether there are multiple orchestration-tools (e.g. DoneTool etc),
-        # in which case set result to error-string since we don't yet support
-        # multi-tools with one or more orch tools.
-        from langroid.agent.tools.orchestration import (
-            AgentDoneTool,
-            AgentSendTool,
-            DonePassTool,
-            DoneTool,
-            ForwardTool,
-            PassTool,
-            SendTool,
-        )
-        from langroid.agent.tools.recipient_tool import RecipientTool
-
-        ORCHESTRATION_TOOLS = (
-            AgentDoneTool,
-            DoneTool,
-            PassTool,
-            DonePassTool,
-            ForwardTool,
-            RecipientTool,
-            SendTool,
-            AgentSendTool,
-        )
-
-        has_orch = any(isinstance(t, ORCHESTRATION_TOOLS) for t in tools)
-        if has_orch and len(tools) > 1:
-            err_str = "ERROR: Use ONE tool at a time!"
-            return [err_str for _ in tools]
-
-        return []
-
-    def _handle_message_final(
-        self, tools: List[ToolMessage], results: List[str | ChatDocument | None]
-    ) -> None | str | OrderedDict[str, str] | ChatDocument:
-        """
-        Convert results to final response
-        """
-        # extract content from ChatDocument results so we have all str|None
-        results = [r.content if isinstance(r, ChatDocument) else r for r in results]
-
-        tool_names = [t.default_value("request") for t in tools]
-
-        has_ids = all([t.id != "" for t in tools])
-        if has_ids:
-            id2result = OrderedDict(
-                (t.id, r)
-                for t, r in zip(tools, results)
-                if r is not None and isinstance(r, str)
-            )
-            result_values = list(id2result.values())
-            if len(id2result) > 1 and any(
-                orch_str in r
-                for r in result_values
-                for orch_str in ORCHESTRATION_STRINGS
-            ):
-                # Cannot support multi-tool results containing orchestration strings!
-                # Replace results with err string to force LLM to retry
-                err_str = "ERROR: Please use ONE tool at a time!"
-                id2result = OrderedDict((id, err_str) for id in id2result.keys())
-
-        name_results_list = [
-            (name, r) for name, r in zip(tool_names, results) if r is not None
-        ]
-        if len(name_results_list) == 0:
-            return None
-
-        # there was a non-None result
-
-        if has_ids and len(id2result) > 1:
-            # if there are multiple OpenAI Tool results, return them as a dict
-            return id2result
-
-        # multi-results: prepend the tool name to each result
-        str_results = [f"Result from {name}: {r}" for name, r in name_results_list]
-        final = "\n\n".join(str_results)
-        return final
-
-    async def handle_message_async(
-        self, msg: str | ChatDocument
-    ) -> None | str | OrderedDict[str, str] | ChatDocument:
-        """
-        Asynch version of `handle_message`. See there for details.
-        """
-        try:
-            tools = self.get_tool_messages(msg)
-            tools = [t for t in tools if self._tool_recipient_match(t)]
-        except ValidationError as ve:
-            # correct tool name but bad fields
-            return self.tool_validation_error(ve)
-        except XMLException as xe:  # from XMLToolMessage parsing
-            return str(xe)
-        except ValueError:
-            # invalid tool name
-            # We return None since returning "invalid tool name" would
-            # be considered a valid result in task loop, and would be treated
-            # as a response to the tool message even though the tool was not intended
-            # for this agent.
-            return None
-        if len(tools) > 1 and not self.config.allow_multiple_tools:
-            return self.to_ChatDocument("ERROR: Use ONE tool at a time!")
-        if len(tools) == 0:
-            fallback_result = self.handle_message_fallback(msg)
-            if fallback_result is None:
-                return None
-            return self.to_ChatDocument(
-                fallback_result,
-                chat_doc=msg if isinstance(msg, ChatDocument) else None,
-            )
-        chat_doc = msg if isinstance(msg, ChatDocument) else None
-
-        results = self._get_multiple_orch_tool_errs(tools)
-        if not results:
-            results = [
-                await self.handle_tool_message_async(t, chat_doc=chat_doc)
-                for t in tools
-            ]
-            # if there's a solitary ChatDocument|str result, return it as is
-            if len(results) == 1 and isinstance(results[0], (str, ChatDocument)):
-                return results[0]
-
-        return self._handle_message_final(tools, results)
-
-    def handle_message(
-        self, msg: str | ChatDocument
-    ) -> None | str | OrderedDict[str, str] | ChatDocument:
-        """
-        Handle a "tool" message either a string containing one or more
-        valid "tool" JSON substrings,  or a
-        ChatDocument containing a `function_call` attribute.
-        Handle with the corresponding handler method, and return
-        the results as a combined string.
-
-        Args:
-            msg (str | ChatDocument): The string or ChatDocument to handle
-
-        Returns:
-            The result of the handler method can be:
-             - None if no tools successfully handled, or no tools present
-             - str if langroid-native JSON tools were handled, and results concatenated,
-                 OR there's a SINGLE OpenAI tool-call.
-                (We do this so the common scenario of a single tool/fn-call
-                 has a simple behavior).
-             - Dict[str, str] if multiple OpenAI tool-calls were handled
-                 (dict is an id->result map)
-             - ChatDocument if a handler returned a ChatDocument, intended to be the
-                 final response of the `agent_response` method.
-        """
-        try:
-            tools = self.get_tool_messages(msg)
-            tools = [t for t in tools if self._tool_recipient_match(t)]
-        except ValidationError as ve:
-            # correct tool name but bad fields
-            return self.tool_validation_error(ve)
-        except XMLException as xe:  # from XMLToolMessage parsing
-            return str(xe)
-        except ValueError:
-            # invalid tool name
-            # We return None since returning "invalid tool name" would
-            # be considered a valid result in task loop, and would be treated
-            # as a response to the tool message even though the tool was not intended
-            # for this agent.
-            return None
-        if len(tools) > 1 and not self.config.allow_multiple_tools:
-            return self.to_ChatDocument("ERROR: Use ONE tool at a time!")
-        if len(tools) == 0:
-            fallback_result = self.handle_message_fallback(msg)
-            if fallback_result is None:
-                return None
-            return self.to_ChatDocument(
-                fallback_result,
-                chat_doc=msg if isinstance(msg, ChatDocument) else None,
-            )
-        chat_doc = msg if isinstance(msg, ChatDocument) else None
-
-        results = self._get_multiple_orch_tool_errs(tools)
-        if not results:
-            results = [self.handle_tool_message(t, chat_doc=chat_doc) for t in tools]
-            # if there's a solitary ChatDocument|str result, return it as is
-            if len(results) == 1 and isinstance(results[0], (str, ChatDocument)):
-                return results[0]
-
-        return self._handle_message_final(tools, results)
-
-    @property
-    def all_llm_tools_known(self) -> set[str]:
-        """All known tools; this may extend self.llm_tools_known."""
-        return self.llm_tools_known
-
-    def handle_message_fallback(self, msg: str | ChatDocument) -> Any:
-        """
-        Fallback method for the "no-tools" scenario.
-        This method can be overridden by subclasses, e.g.,
-        to create a "reminder" message when a tool is expected but the LLM "forgot"
-        to generate one.
-
-        Args:
-            msg (str | ChatDocument): The input msg to handle
-        Returns:
-            Any: The result of the handler method
-        """
-        return None
-
-    def _get_one_tool_message(
-        self, tool_candidate_str: str, is_json: bool = True
-    ) -> Optional[ToolMessage]:
-        """
-        Parse the tool_candidate_str into ANY ToolMessage KNOWN to agent --
-        This includes non-used/handled tools, i.e. any tool in self.all_llm_tools_known.
-        The exception to this is below where we try our best to infer the tool
-        when the LLM has "forgotten" to include the "request" field in the tool str ---
-        in this case we ONLY look at the possible set of HANDLED tools, i.e.
-        self.llm_tools_handled.
-        """
-        if is_json:
-            maybe_tool_dict = json.loads(tool_candidate_str)
-        else:
-            try:
-                maybe_tool_dict = XMLToolMessage.extract_field_values(
-                    tool_candidate_str
-                )
-            except Exception as e:
-                from langroid.exceptions import XMLException
-
-                raise XMLException(f"Error extracting XML fields:\n {str(e)}")
-        # check if the maybe_tool_dict contains a "properties" field
-        # which further contains the actual tool-call
-        # (some weak LLMs do this). E.g. gpt-4o sometimes generates this:
-        # TOOL: {
-        #     "type": "object",
-        #     "properties": {
-        #         "request": "square",
-        #         "number": 9
-        #     },
-        #     "required": [
-        #         "number",
-        #         "request"
-        #     ]
-        # }
-
-        if not isinstance(maybe_tool_dict, dict):
-            self.tool_error = True
-            return None
-
-        properties = maybe_tool_dict.get("properties")
-        if isinstance(properties, dict):
-            maybe_tool_dict = properties
-        request = maybe_tool_dict.get("request")
-        if request is None:
-            if self.enabled_requests_for_inference is None:
-                possible = [self.llm_tools_map[r] for r in self.llm_tools_handled]
-            else:
-                allowable = self.enabled_requests_for_inference.intersection(
-                    self.llm_tools_handled
-                )
-                possible = [self.llm_tools_map[r] for r in allowable]
-
-            default_keys = set(ToolMessage.__fields__.keys())
-            request_keys = set(maybe_tool_dict.keys())
-
-            def maybe_parse(tool: type[ToolMessage]) -> Optional[ToolMessage]:
-                all_keys = set(tool.__fields__.keys())
-                non_inherited_keys = all_keys.difference(default_keys)
-                # If the request has any keys not valid for the tool and
-                # does not specify some key specific to the type
-                # (e.g. not just `purpose`), the LLM must explicitly specify `request`
-                if not (
-                    request_keys.issubset(all_keys)
-                    and len(request_keys.intersection(non_inherited_keys)) > 0
-                ):
-                    return None
-
-                try:
-                    return tool.parse_obj(maybe_tool_dict)
-                except ValidationError:
-                    return None
-
-            candidate_tools = list(
-                filter(
-                    lambda t: t is not None,
-                    map(maybe_parse, possible),
-                )
-            )
-
-            # If only one valid candidate exists, we infer
-            # "request" to be the only possible value
-            if len(candidate_tools) == 1:
-                return candidate_tools[0]
-            else:
-                self.tool_error = True
-                return None
-
-        if not isinstance(request, str) or request not in self.all_llm_tools_known:
-            self.tool_error = True
-            return None
-
-        message_class = self.llm_tools_map.get(request)
-        if message_class is None:
-            logger.warning(f"No message class found for request '{request}'")
-            self.tool_error = True
-            return None
-
-        try:
-            message = message_class.parse_obj(maybe_tool_dict)
-        except ValidationError as ve:
-            self.tool_error = True
-            raise ve
-        return message
-
-    def to_ChatDocument(
-        self,
-        msg: Any,
-        orig_tool_name: str | None = None,
-        chat_doc: Optional[ChatDocument] = None,
-        author_entity: Entity = Entity.AGENT,
-    ) -> Optional[ChatDocument]:
-        """
-        Convert result of a responder (agent_response or llm_response, or task.run()),
-        or tool handler, or handle_message_fallback,
-        to a ChatDocument, to enable handling by other
-        responders/tasks in a task loop possibly involving multiple agents.
-
-        Args:
-            msg (Any): The result of a responder or tool handler or task.run()
-            orig_tool_name (str): The original tool name that generated the response,
-                if any.
-            chat_doc (ChatDocument): The original ChatDocument object that `msg`
-                is a response to.
-            author_entity (Entity): The intended author of the result ChatDocument
-        """
-        if msg is None or isinstance(msg, ChatDocument):
-            return msg
-
-        is_agent_author = author_entity == Entity.AGENT
-
-        if isinstance(msg, str):
-            return self.response_template(author_entity, content=msg, content_any=msg)
-        elif isinstance(msg, ToolMessage):
-            # result is a ToolMessage, so...
-            result_tool_name = msg.default_value("request")
-            if (
-                is_agent_author
-                and result_tool_name in self.llm_tools_handled
-                and (orig_tool_name is None or orig_tool_name != result_tool_name)
-            ):
-                # TODO: do we need to remove the tool message from the chat_doc?
-                # if (chat_doc is not None and
-                #     msg in chat_doc.tool_messages):
-                #    chat_doc.tool_messages.remove(msg)
-                # if we can handle it, do so
-                result = self.handle_tool_message(msg, chat_doc=chat_doc)
-                if result is not None and isinstance(result, ChatDocument):
-                    return result
-            else:
-                # else wrap it in an agent response and return it so
-                # orchestrator can find a respondent
-                return self.response_template(author_entity, tool_messages=[msg])
-        else:
-            result = to_string(msg)
-
-        return (
-            None
-            if result is None
-            else self.response_template(author_entity, content=result, content_any=msg)
-        )
-
-    def from_ChatDocument(self, msg: ChatDocument, output_type: Type[T]) -> Optional[T]:
-        """
-        Extract a desired output_type from a ChatDocument object.
-        We use this fallback order:
-        - if `msg.content_any` exists and matches the output_type, return it
-        - if `msg.content` exists and output_type is str return it
-        - if output_type is a ToolMessage, return the first tool in `msg.tool_messages`
-        - if output_type is a list of ToolMessage,
-            return all tools in `msg.tool_messages`
-        - search for a tool in `msg.tool_messages` that has a field of output_type,
-             and if found, return that field value
-        - return None if all the above fail
-        """
-        content = msg.content
-        if output_type is str and content != "":
-            return cast(T, content)
-        content_any = msg.content_any
-        if content_any is not None and isinstance(content_any, output_type):
-            return cast(T, content_any)
-
-        tools = self.try_get_tool_messages(msg, all_tools=True)
-
-        if get_origin(output_type) is list:
-            list_element_type = get_args(output_type)[0]
-            if issubclass(list_element_type, ToolMessage):
-                # list_element_type is a subclass of ToolMessage:
-                # We output a list of objects derived from list_element_type
-                return cast(
-                    T,
-                    [t for t in tools if isinstance(t, list_element_type)],
-                )
-        elif get_origin(output_type) is None and issubclass(output_type, ToolMessage):
-            # output_type is a subclass of ToolMessage:
-            # return the first tool that has this specific output_type
-            for tool in tools:
-                if isinstance(tool, output_type):
-                    return cast(T, tool)
-            return None
-        elif get_origin(output_type) is None and output_type in (str, int, float, bool):
-            # attempt to get the output_type from the content,
-            # if it's a primitive type
-            primitive_value = from_string(content, output_type)  # type: ignore
-            if primitive_value is not None:
-                return cast(T, primitive_value)
-
-        # then search for output_type as a field in a tool
-        for tool in tools:
-            value = tool.get_value_of_type(output_type)
-            if value is not None:
-                return cast(T, value)
-        return None
-
-    def _maybe_truncate_result(
-        self, result: str | ChatDocument | None, max_tokens: int | None
-    ) -> str | ChatDocument | None:
-        """
-        Truncate the result string to `max_tokens` tokens.
-        """
-        if result is None or max_tokens is None:
-            return result
-        result_str = result.content if isinstance(result, ChatDocument) else result
-        num_tokens = (
-            self.parser.num_tokens(result_str)
-            if self.parser is not None
-            else len(result_str) / 4.0
-        )
-        if num_tokens <= max_tokens:
-            return result
-        truncate_warning = f"""
-        The TOOL result was large, so it was truncated to {max_tokens} tokens.
-        To get the full result, the TOOL must be called again.
-        """
-        if isinstance(result, str):
-            return (
-                self.parser.truncate_tokens(result, max_tokens)
-                if self.parser is not None
-                else result[: max_tokens * 4]  # approx truncate
-            ) + truncate_warning
-        elif isinstance(result, ChatDocument):
-            result.content = (
-                self.parser.truncate_tokens(result.content, max_tokens)
-                if self.parser is not None
-                else result.content[: max_tokens * 4]  # approx truncate
-            ) + truncate_warning
-            return result
-
-    async def handle_tool_message_async(
-        self,
-        tool: ToolMessage,
-        chat_doc: Optional[ChatDocument] = None,
-    ) -> None | str | ChatDocument:
-        """
-        Asynch version of `handle_tool_message`. See there for details.
-        """
-        tool_name = tool.default_value("request")
-        if hasattr(tool, "_handler"):
-            handler_name = getattr(tool, "_handler", tool_name)
-        else:
-            handler_name = tool_name
-        handler_method = getattr(self, handler_name + "_async", None)
-        if handler_method is None:
-            return self.handle_tool_message(tool, chat_doc=chat_doc)
-        has_chat_doc_arg = (
-            chat_doc is not None
-            and "chat_doc" in inspect.signature(handler_method).parameters
-        )
-        try:
-            if has_chat_doc_arg:
-                maybe_result = await handler_method(tool, chat_doc=chat_doc)
-            else:
-                maybe_result = await handler_method(tool)
-            result = self.to_ChatDocument(maybe_result, tool_name, chat_doc)
-        except Exception as e:
-            # raise the error here since we are sure it's
-            # not a pydantic validation error,
-            # which we check in `handle_message`
-            raise e
-        return self._maybe_truncate_result(
-            result, tool._max_result_tokens
-        )  # type: ignore
-
-    def handle_tool_message(
-        self,
-        tool: ToolMessage,
-        chat_doc: Optional[ChatDocument] = None,
-    ) -> None | str | ChatDocument:
-        """
-        Respond to a tool request from the LLM, in the form of an ToolMessage object.
-        Args:
-            tool: ToolMessage object representing the tool request.
-            chat_doc: Optional ChatDocument object containing the tool request.
-                This is passed to the tool-handler method only if it has a `chat_doc`
-                argument.
-
-        Returns:
-
-        """
-        tool_name = tool.default_value("request")
-        if hasattr(tool, "_handler"):
-            handler_name = getattr(tool, "_handler", tool_name)
-        else:
-            handler_name = tool_name
-        handler_method = getattr(self, handler_name, None)
-        if handler_method is None:
-            return None
-        has_chat_doc_arg = (
-            chat_doc is not None
-            and "chat_doc" in inspect.signature(handler_method).parameters
-        )
-        try:
-            if has_chat_doc_arg:
-                maybe_result = handler_method(tool, chat_doc=chat_doc)
-            else:
-                maybe_result = handler_method(tool)
-            result = self.to_ChatDocument(maybe_result, tool_name, chat_doc)
-        except Exception as e:
-            # raise the error here since we are sure it's
-            # not a pydantic validation error,
-            # which we check in `handle_message`
-            raise e
-        return self._maybe_truncate_result(
-            result, tool._max_result_tokens
-        )  # type: ignore
-
-    def num_tokens(self, prompt: str | List[LLMMessage]) -> int:
-        if self.parser is None:
-            raise ValueError("Parser must be set, to count tokens")
-        if isinstance(prompt, str):
-            return self.parser.num_tokens(prompt)
-        else:
-            return sum(
-                [
-                    self.parser.num_tokens(m.content)
-                    + self.parser.num_tokens(str(m.function_call or ""))
-                    for m in prompt
-                ]
-            )
-
-    def _get_response_stats(
-        self, chat_length: int, tot_cost: float, response: LLMResponse
-    ) -> str:
-        """
-        Get LLM response stats as a string
-
-        Args:
-            chat_length (int): number of messages in the chat
-            tot_cost (float): total cost of the chat so far
-            response (LLMResponse): LLMResponse object
-        """
-
-        if self.config.llm is None:
-            logger.warning("LLM config is None, cannot get response stats")
-            return ""
-        if response.usage:
-            in_tokens = response.usage.prompt_tokens
-            out_tokens = response.usage.completion_tokens
-            llm_response_cost = format(response.usage.cost, ".4f")
-            cumul_cost = format(tot_cost, ".4f")
-            assert isinstance(self.llm, LanguageModel)
-            context_length = self.llm.chat_context_length()
-            max_out = self.config.llm.max_output_tokens
-
-            llm_model = (
-                "no-LLM" if self.config.llm is None else self.llm.config.chat_model
-            )
-            # tot cost across all LLMs, agents
-            all_cost = format(self.llm.tot_tokens_cost()[1], ".4f")
-            return (
-                f"[bold]Stats:[/bold] [magenta]N_MSG={chat_length}, "
-                f"TOKENS: in={in_tokens}, out={out_tokens}, "
-                f"max={max_out}, ctx={context_length}, "
-                f"COST: now=${llm_response_cost}, cumul=${cumul_cost}, "
-                f"tot=${all_cost} "
-                f"[bold]({llm_model})[/bold][/magenta]"
-            )
-        return ""
-
-    def update_token_usage(
-        self,
-        response: LLMResponse,
-        prompt: str | List[LLMMessage],
-        stream: bool,
-        chat: bool = True,
-        print_response_stats: bool = True,
-    ) -> None:
-        """
-        Updates `response.usage` obj (token usage and cost fields).the usage memebr
-        It updates the cost after checking the cache and updates the
-        tokens (prompts and completion) if the response stream is True, because OpenAI
-        doesn't returns these fields.
-
-        Args:
-            response (LLMResponse): LLMResponse object
-            prompt (str | List[LLMMessage]): prompt or list of LLMMessage objects
-            stream (bool): whether to update the usage in the response object
-                if the response is not cached.
-            chat (bool): whether this is a chat model or a completion model
-            print_response_stats (bool): whether to print the response stats
-        """
-        if response is None or self.llm is None:
-            return
-
-        # Note: If response was not streamed, then
-        # `response.usage` would already have been set by the API,
-        # so we only need to update in the stream case.
-        if stream:
-            # usage, cost = 0 when response is from cache
-            prompt_tokens = 0
-            completion_tokens = 0
-            cost = 0.0
-            if not response.cached:
-                prompt_tokens = self.num_tokens(prompt)
-                completion_tokens = self.num_tokens(response.message)
-                if response.function_call is not None:
-                    completion_tokens += self.num_tokens(str(response.function_call))
-                cost = self.compute_token_cost(prompt_tokens, completion_tokens)
-            response.usage = LLMTokenUsage(
-                prompt_tokens=prompt_tokens,
-                completion_tokens=completion_tokens,
-                cost=cost,
-            )
-
-        # update total counters
-        if response.usage is not None:
-            self.total_llm_token_cost += response.usage.cost
-            self.total_llm_token_usage += response.usage.total_tokens
-            self.llm.update_usage_cost(
-                chat,
-                response.usage.prompt_tokens,
-                response.usage.completion_tokens,
-                response.usage.cost,
-            )
-            chat_length = 1 if isinstance(prompt, str) else len(prompt)
-            self.token_stats_str = self._get_response_stats(
-                chat_length, self.total_llm_token_cost, response
-            )
-            if print_response_stats:
-                print(self.indent + self.token_stats_str)
-
-    def compute_token_cost(self, prompt: int, completion: int) -> float:
-        price = cast(LanguageModel, self.llm).chat_cost()
-        return (price[0] * prompt + price[1] * completion) / 1000
-
-    def ask_agent(
-        self,
-        agent: "Agent",
-        request: str,
-        no_answer: str = NO_ANSWER,
-        user_confirm: bool = True,
-    ) -> Optional[str]:
-        """
-        Send a request to another agent, possibly after confirming with the user.
-        This is not currently used, since we rely on the task loop and
-        `RecipientTool` to address requests to other agents. It is generally best to
-        avoid using this method.
-
-        Args:
-            agent (Agent): agent to ask
-            request (str): request to send
-            no_answer (str): expected response when agent does not know the answer
-            user_confirm (bool): whether to gate the request with a human confirmation
-
-        Returns:
-            str: response from agent
-        """
-        agent_type = type(agent).__name__
-        if user_confirm:
-            user_response = Prompt.ask(
-                f"""[magenta]Here is the request or message:
-                {request}
-                Should I forward this to {agent_type}?""",
-                default="y",
-                choices=["y", "n"],
-            )
-            if user_response not in ["y", "yes"]:
-                return None
-        answer = agent.llm_response(request)
-        if answer != no_answer:
-            return (f"{agent_type} says: " + str(answer)).strip()
-        return None