langroid 0.33.6__py3-none-any.whl → 0.33.8__py3-none-any.whl

langroid/agent/tools/recipient_tool.py

@@ -0,0 +1,235 @@
+"""
+The `recipient_tool` is used to send a message to a specific recipient.
+Various methods from the RecipientTool and AddRecipientTool class
+are inserted into the Agent as methods (see `langroid/agent/base.py`,
+the method `_get_tool_list()`).
+
+See usage examples in `tests/main/test_multi_agent_complex.py` and
+`tests/main/test_recipient_tool.py`.
+
+A simpler alternative to this tool is `SendTool`, see here:
+https://github.com/langroid/langroid/blob/main/langroid/agent/tools/orchestration.py
+
+You can also define your own XML-based variant of this tool:
+https://github.com/langroid/langroid/blob/main/examples/basic/xml-tool.py
+which uses XML rather than JSON, and can be more reliable than JSON,
+especially with weaker LLMs.
+
+"""
+
+from typing import List, Type
+
+from rich import print
+
+from langroid.agent.chat_agent import ChatAgent
+from langroid.agent.chat_document import ChatDocMetaData, ChatDocument
+from langroid.agent.tool_message import ToolMessage
+from langroid.mytypes import Entity
+from langroid.utils.pydantic_utils import has_field
+
+
+class AddRecipientTool(ToolMessage):
+    """
+    Used by LLM to add a recipient to the previous message, when it has
+    forgotten to specify a recipient. This avoids having to re-generate the
+    previous message (and thus saves token-cost and time).
+    """
+
+    request: str = "add_recipient"
+    purpose: str = (
+        "To clarify that the <intended_recipient> when I forgot to specify it, "
+        "to clarify who the message is intended for."
+    )
+    intended_recipient: str
+    _saved_content: str = ""
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        """
+        Returns:
+            (ChatDocument): with content set to self.content and
+                metadata.recipient set to self.recipient.
+        """
+        print(
+            "[red]RecipientTool: "
+            f"Added recipient {self.intended_recipient} to message."
+        )
+        if self.__class__._saved_content == "":
+            recipient_request_name = RecipientTool.default_value("request")
+            content = f"""
+                Recipient specified but content is empty!
+                This could be because the `{self.request}` tool/function was used 
+                before using `{recipient_request_name}` tool/function.
+                Resend the message using `{recipient_request_name}` tool/function.
+                """
+        else:
+            content = self.__class__._saved_content  # use class-level attrib value
+            # erase content since we just used it.
+            self.__class__._saved_content = ""
+        return ChatDocument(
+            content=content,
+            metadata=ChatDocMetaData(
+                recipient=self.intended_recipient,
+                # we are constructing this so it looks as it msg is from LLM
+                sender=Entity.LLM,
+            ),
+        )
+
+
+class RecipientTool(ToolMessage):
+    """
+    Used by LLM to send a message to a specific recipient.
+
+    Useful in cases where an LLM is talking to 2 or more
+    agents (or an Agent and human user), and needs to specify which agent (task)
+    its message is intended for. The recipient name should be the name of a task
+    (which is normally the name of the agent that the task wraps, although the task
+    can have its own name).
+
+    To use this tool/function-call, LLM must generate a JSON structure
+    with these fields:
+    {
+        "request": "recipient_message", # also the function name when using fn-calling
+        "intended_recipient": <name_of_recipient_task_or_entity>,
+        "content": <content>
+    }
+    The effect of this is that `content` will be sent to the `intended_recipient` task.
+    """
+
+    request: str = "recipient_message"
+    purpose: str = "To send message <content> to a specific <intended_recipient>."
+    intended_recipient: str
+    content: str
+
+    @classmethod
+    def create(cls, recipients: List[str], default: str = "") -> Type["RecipientTool"]:
+        """Create a restricted version of RecipientTool that
+        only allows certain recipients, and possibly sets a default recipient."""
+
+        class RecipientToolRestricted(cls):  # type: ignore
+            allowed_recipients = recipients
+            default_recipient = default
+
+        return RecipientToolRestricted
+
+    @classmethod
+    def instructions(cls) -> str:
+        """
+        Generate instructions for using this tool/function.
+        These are intended to be appended to the system message of the LLM.
+        """
+        recipients = []
+        if has_field(cls, "allowed_recipients"):
+            recipients = cls.default_value("allowed_recipients")
+        if len(recipients) > 0:
+            recipients_str = ", ".join(recipients)
+            return f"""
+            Since you will be talking to multiple recipients, 
+            you must clarify who your intended recipient is, using 
+            the `{cls.default_value("request")}` tool/function-call, by setting the 
+            'intended_recipient' field to one of the following:
+            {recipients_str},
+            and setting the 'content' field to your message.
+            """
+        else:
+            return f"""
+            Since you will be talking to multiple recipients, 
+            you must clarify who your intended recipient is, using 
+            the `{cls.default_value("request")}` tool/function-call, by setting the 
+            'intended_recipient' field to the name of the recipient, 
+            and setting the 'content' field to your message.
+            """
+
+    def response(self, agent: ChatAgent) -> str | ChatDocument:
+        """
+        When LLM has correctly used this tool,
+        construct a ChatDocument with an explicit recipient,
+        and make it look like it is from the LLM.
+
+        Returns:
+            (ChatDocument): with content set to self.content and
+                metadata.recipient set to self.intended_recipient.
+        """
+        default_recipient = self.__class__.default_value("default_recipient")
+        if self.intended_recipient == "" and default_recipient not in ["", None]:
+            self.intended_recipient = default_recipient
+        elif self.intended_recipient == "":
+            # save the content as a class-variable, so that
+            # we can construct the ChatDocument once the LLM specifies a recipient.
+            # This avoids having to re-generate the entire message, saving time + cost.
+            AddRecipientTool._saved_content = self.content
+            agent.enable_message(AddRecipientTool)
+            return ChatDocument(
+                content="""
+                Empty recipient field!
+                Please use the 'add_recipient' tool/function-call to specify who your 
+                message is intended for.
+                DO NOT REPEAT your original message; ONLY specify the recipient via this
+                tool/function-call.
+                """,
+                metadata=ChatDocMetaData(
+                    sender=Entity.AGENT,
+                    recipient=Entity.LLM,
+                ),
+            )
+
+        print("[red]RecipientTool: Validated properly addressed message")
+
+        return ChatDocument(
+            content=self.content,
+            metadata=ChatDocMetaData(
+                recipient=self.intended_recipient,
+                # we are constructing this so it looks as if msg is from LLM
+                sender=Entity.LLM,
+            ),
+        )
+
+    @staticmethod
+    def handle_message_fallback(
+        agent: ChatAgent, msg: str | ChatDocument
+    ) -> str | ChatDocument | None:
+        """
+        Response of agent if this tool is not used, e.g.
+        the LLM simply sends a message without using this tool.
+        This method has two purposes:
+        (a) Alert the LLM that it has forgotten to specify a recipient, and prod it
+            to use the `add_recipient` tool to specify just the recipient
+            (and not re-generate the entire message).
+        (b) Save the content of the message in the agent's `content` field,
+            so the agent can construct a ChatDocument with this content once LLM
+            later specifies a recipient using the `add_recipient` tool.
+
+        This method is used to set the agent's handle_message_fallback() method.
+
+        Returns:
+            (str): reminder to LLM to use the `add_recipient` tool.
+        """
+        # Note: once the LLM specifies a missing recipient, the task loop
+        # mechanism will not allow any of the "native" responders to respond,
+        # since the recipient will differ from the task name.
+        # So if this method is called, we can be sure that the recipient has not
+        # been specified.
+        if (
+            isinstance(msg, str)
+            or msg.metadata.sender != Entity.LLM
+            or msg.metadata.recipient != ""  # there IS an explicit recipient
+        ):
+            return None
+        content = msg if isinstance(msg, str) else msg.content
+        # save the content as a class-variable, so that
+        # we can construct the ChatDocument once the LLM specifies a recipient.
+        # This avoids having to re-generate the entire message, saving time + cost.
+        AddRecipientTool._saved_content = content
+        agent.enable_message(AddRecipientTool)
+        print("[red]RecipientTool: Recipient not specified, asking LLM to clarify.")
+        return ChatDocument(
+            content="""
+            Please use the 'add_recipient' tool/function-call to specify who your 
+            `intended_recipient` is.
+            DO NOT REPEAT your original message; ONLY specify the 
+            `intended_recipient` via this tool/function-call.
+            """,
+            metadata=ChatDocMetaData(
+                sender=Entity.AGENT,
+                recipient=Entity.LLM,
+            ),
+        )

langroid/agent/tools/retrieval_tool.py

@@ -0,0 +1,32 @@
+from typing import List, Tuple
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class RetrievalTool(ToolMessage):
+    """
+    Retrieval tool, only to be used by a DocChatAgent.
+    The handler method is defined in DocChatAgent.retrieval_tool
+    """
+
+    request: str = "retrieval_tool"
+    purpose: str = """
+            To retrieve up to <num_results> passages from a document-set, that are 
+            relevant to a <query>, which could be a question or simply a topic or 
+            search phrase. 
+            """
+    query: str
+    num_results: int
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(
+                query="What are the eligibility criteria for the scholarship?",
+                num_results=3,
+            ),
+            cls(
+                query="Self-Attention mechanism in RNNs",
+                num_results=5,
+            ),
+        ]

langroid/agent/tools/rewind_tool.py

@@ -0,0 +1,137 @@
+"""
+The `rewind_tool` is used to rewind to the `n`th previous Assistant message
+and replace it with a new `content`. This is useful in several scenarios and
+- saves token-cost + inference time,
+- reduces distracting clutter in chat history, which helps improve response quality.
+
+This is intended to mimic how a human user might use a chat interface, where they
+go down a conversation path, and want to go back in history to "edit and re-submit"
+a previous message, to get a better response.
+
+See usage examples in `tests/main/test_rewind_tool.py`.
+"""
+
+from typing import List, Tuple
+
+import langroid.language_models as lm
+from langroid.agent.chat_agent import ChatAgent
+from langroid.agent.chat_document import ChatDocument
+from langroid.agent.tool_message import ToolMessage
+
+
+def prune_messages(agent: ChatAgent, idx: int) -> ChatDocument | None:
+    """
+    Clear the message history of agent, starting at index `idx`,
+    taking care to first clear all dependent messages (possibly from other agents'
+    message histories) that are linked to the message at `idx`, via the `child_id` field
+    of the `metadata` field of the ChatDocument linked from the message at `idx`.
+
+    Args:
+        agent (ChatAgent): The agent whose message history is to be pruned.
+        idx (int): The index from which to start clearing the message history.
+
+    Returns:
+        The parent ChatDocument of the ChatDocument linked from the message at `idx`,
+        if it exists, else None.
+
+    """
+    assert idx >= 0, "Invalid index for message history!"
+    chat_doc_id = agent.message_history[idx].chat_document_id
+    chat_doc = ChatDocument.from_id(chat_doc_id)
+    assert chat_doc is not None, "ChatDocument not found in registry!"
+
+    parent = ChatDocument.from_id(chat_doc.metadata.parent_id)  # may be None
+    # We're invaliding the msg at idx,
+    # so starting with chat_doc, go down the child links
+    # and clear history of each agent, to the msg_idx
+    curr_doc = chat_doc
+    while child_doc := curr_doc.metadata.child:
+        if child_doc.metadata.msg_idx >= 0:
+            child_agent = ChatAgent.from_id(child_doc.metadata.agent_id)
+            if child_agent is not None:
+                child_agent.clear_history(child_doc.metadata.msg_idx)
+        curr_doc = child_doc
+
+    # Clear out ObjectRegistry entries for this ChatDocuments
+    # and all descendants (in case they weren't already cleared above)
+    ChatDocument.delete_id(chat_doc.id())
+
+    # Finally, clear this agent's history back to idx,
+    # and replace the msg at idx with the new content
+    agent.clear_history(idx)
+    return parent
+
+
+class RewindTool(ToolMessage):
+    """
+    Used by LLM to rewind (i.e. backtrack) to the `n`th Assistant message
+    and replace with a new msg.
+    """
+
+    request: str = "rewind_tool"
+    purpose: str = """
+        To rewind the conversation and replace the 
+        <n>'th Assistant message with <content>
+        """
+    n: int
+    content: str
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(n=1, content="What are the 3 major causes of heart disease?"),
+            (
+                """
+                Based on the conversation so far, I realize I would get a better
+                response from Bob if rephrase my 2nd message to him to: 
+                'Who wrote the book Grime and Banishment?'
+                """,
+                cls(n=2, content="who wrote the book 'Grime and Banishment'?"),
+            ),
+        ]
+
+    def response(self, agent: ChatAgent) -> str | ChatDocument:
+        """
+        Define the tool-handler method for this tool here itself,
+        since it is a generic tool whose functionality should be the
+        same for any agent.
+
+        When LLM has correctly used this tool, rewind this agent's
+        `message_history` to the `n`th assistant msg, and replace it with `content`.
+        We need to mock it as if the LLM is sending this message.
+
+        Within a multi-agent scenario, this also means that any other messages dependent
+        on this message will need to be invalidated --
+        so go down the chain of child messages and clear each agent's history
+        back to the `msg_idx` corresponding to the child message.
+
+        Returns:
+            (ChatDocument): with content set to self.content.
+        """
+        idx = agent.nth_message_idx_with_role(lm.Role.ASSISTANT, self.n)
+        if idx < 0:
+            # set up a corrective message from AGENT
+            msg = f"""
+                Could not rewind to {self.n}th Assistant message!
+                Please check the value of `n` and try again.
+                Or it may be too early to use the `rewind_tool`.
+                """
+            return agent.create_agent_response(msg)
+
+        parent = prune_messages(agent, idx)
+
+        # create ChatDocument with new content, to be returned as result of this tool
+        result_doc = agent.create_llm_response(self.content)
+        result_doc.metadata.parent_id = "" if parent is None else parent.id()
+        result_doc.metadata.agent_id = agent.id
+        result_doc.metadata.msg_idx = idx
+
+        # replace the message at idx with this new message
+        agent.message_history.extend(ChatDocument.to_LLMMessage(result_doc))
+
+        # set the replaced doc's parent's child to this result_doc
+        if parent is not None:
+            # first remove the this parent's child from registry
+            ChatDocument.delete_id(parent.metadata.child_id)
+            parent.metadata.child_id = result_doc.id()
+        return result_doc

langroid/agent/tools/segment_extract_tool.py

@@ -0,0 +1,41 @@
+"""
+A tool to extract segment numbers from the last user message,
+containing numbered segments.
+
+The idea is that when an LLM wants to (or is asked to) simply extract
+portions of a message verbatim, it should use this tool/function to
+SPECIFY what should be extracted, rather than actually extracting it.
+The output will be in the form of a list of segment numbers or ranges.
+This will usually be much cheaper and faster than actually writing out the extracted
+text. The handler of this tool/function will then extract the text and send it back.
+"""
+
+from typing import List, Tuple
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class SegmentExtractTool(ToolMessage):
+    request: str = "extract_segments"
+    purpose: str = """
+            To extract segments from a body of text containing numbered 
+            segments, in the form of a <segment_list> which is a list of segment 
+            numbers or ranges, like "10,12,14-17".
+            """
+    segment_list: str
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            (
+                "I want to extract segments 1, 3, and 5 thru 7",
+                cls(segment_list="1,3,5-7"),
+            )
+        ]
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        Use this tool/function to indicate certain segments from 
+        a body of text containing numbered segments.
+        """