langroid 0.33.4__py3-none-any.whl → 0.33.7__py3-none-any.whl

langroid/agent/tools/file_tools.py

@@ -0,0 +1,234 @@
+from contextlib import chdir
+from pathlib import Path
+from textwrap import dedent
+from typing import Callable, List, Tuple, Type
+
+import git
+
+from langroid.agent.tool_message import ToolMessage
+from langroid.agent.xml_tool_message import XMLToolMessage
+from langroid.pydantic_v1 import Field
+from langroid.utils.git_utils import git_commit_file
+from langroid.utils.system import create_file, list_dir, read_file
+
+
+class ReadFileTool(ToolMessage):
+    request: str = "read_file_tool"
+    purpose: str = "Read the contents of a <file_path>"
+    file_path: str
+
+    _line_nums: bool = True  # whether to add line numbers to the content
+    _curr_dir: Callable[[], str] | None = None
+
+    @classmethod
+    def create(
+        cls,
+        get_curr_dir: Callable[[], str] | None,
+    ) -> Type["ReadFileTool"]:
+        """
+        Create a subclass of ReadFileTool for a specific directory
+
+        Args:
+            get_curr_dir (callable): A function that returns the current directory.
+
+        Returns:
+            Type[ReadFileTool]: A subclass of the ReadFileTool class, specifically
+                for the current directory.
+        """
+
+        class CustomReadFileTool(cls):  # type: ignore
+            _curr_dir: Callable[[], str] | None = (
+                staticmethod(get_curr_dir) if get_curr_dir else None
+            )
+
+        return CustomReadFileTool
+
+    @classmethod
+    def examples(cls) -> List[ToolMessage | tuple[str, ToolMessage]]:
+        return [
+            cls(file_path="src/lib.rs"),
+            (
+                "I want to read the contents of src/main.rs",
+                cls(file_path="src/main.rs"),
+            ),
+        ]
+
+    def handle(self) -> str:
+        # return contents as str for LLM to read
+        # ASSUME: file_path should be relative to the curr_dir
+        try:
+            dir = (self._curr_dir and self._curr_dir()) or Path.cwd()
+            with chdir(dir):
+                # if file doesn't exist, return an error message
+                content = read_file(self.file_path, self._line_nums)
+            line_num_str = ""
+            if self._line_nums:
+                line_num_str = "(Line numbers added for reference only!)"
+            return f""" 
+    CONTENTS of {self.file_path}:
+    {line_num_str}
+    ---------------------------
+    {content}
+    """
+        except FileNotFoundError:
+            return f"File not found: {self.file_path}"
+
+
+class WriteFileTool(XMLToolMessage):
+    request: str = "write_file_tool"
+    purpose: str = """
+    Tool for writing <content> in a certain <language> to a <file_path>
+    """
+
+    file_path: str = Field(..., description="The path to the file to write the content")
+
+    language: str = Field(
+        default="",
+        description="""
+        The language of the content; could be human language or programming language
+        """,
+    )
+    content: str = Field(
+        ...,
+        description="The content to write to the file",
+        verbatim=True,  # preserve the content as is; uses CDATA section in XML
+    )
+    _curr_dir: Callable[[], str] | None = None
+    _git_repo: Callable[[], git.Repo] | None = None
+    _commit_message: str = "Agent write file tool"
+
+    @classmethod
+    def create(
+        cls,
+        get_curr_dir: Callable[[], str] | None,
+        get_git_repo: Callable[[], str] | None,
+    ) -> Type["WriteFileTool"]:
+        """
+        Create a subclass of WriteFileTool with the current directory and git repo.
+
+        Args:
+            get_curr_dir (callable): A function that returns the current directory.
+            get_git_repo (callable): A function that returns the git repo.
+
+        Returns:
+            Type[WriteFileTool]: A subclass of the WriteFileTool class, specifically
+                for the current directory and git repo.
+        """
+
+        class CustomWriteFileTool(cls):  # type: ignore
+            _curr_dir: Callable[[], str] | None = (
+                staticmethod(get_curr_dir) if get_curr_dir else None
+            )
+            _git_repo: Callable[[], str] | None = (
+                staticmethod(get_git_repo) if get_git_repo else None
+            )
+
+        return CustomWriteFileTool
+
+    @classmethod
+    def examples(cls) -> List[ToolMessage | Tuple[str, ToolMessage]]:
+        return [
+            (
+                """
+                I want to define a simple hello world python function
+                in a file "mycode/hello.py"
+                """,
+                cls(
+                    file_path="mycode/hello.py",
+                    language="python",
+                    content="""
+def hello():
+    print("Hello, World!")
+""",
+                ),
+            ),
+            cls(
+                file_path="src/lib.rs",
+                language="rust",
+                content="""
+fn main() {
+    println!("Hello, World!");
+}                
+""",
+            ),
+            cls(
+                file_path="docs/intro.txt",
+                content="""
+# Introduction
+This is the first sentence of the introduction.
+                """,
+            ),
+        ]
+
+    def handle(self) -> str:
+        curr_dir = (self._curr_dir and self._curr_dir()) or Path.cwd()
+        with chdir(curr_dir):
+            create_file(self.file_path, self.content)
+            msg = f"Content written to {self.file_path}"
+            # possibly commit the file
+            if self._git_repo:
+                git_commit_file(
+                    self._git_repo(),
+                    self.file_path,
+                    self._commit_message,
+                )
+                msg += " and committed"
+        return msg
+
+
+class ListDirTool(ToolMessage):
+    request: str = "list_dir_tool"
+    purpose: str = "List the contents of a <dir_path>"
+    dir_path: str
+
+    _curr_dir: Callable[[], str] | None = None
+
+    @classmethod
+    def create(
+        cls,
+        get_curr_dir: Callable[[], str] | None,
+    ) -> Type["ReadFileTool"]:
+        """
+        Create a subclass of ListDirTool for a specific directory
+
+        Args:
+            get_curr_dir (callable): A function that returns the current directory.
+
+        Returns:
+            Type[ReadFileTool]: A subclass of the ReadFileTool class, specifically
+                for the current directory.
+        """
+
+        class CustomListDirTool(cls):  # type: ignore
+            _curr_dir: Callable[[], str] | None = (
+                staticmethod(get_curr_dir) if get_curr_dir else None
+            )
+
+        return CustomListDirTool
+
+    @classmethod
+    def examples(cls) -> List[ToolMessage | tuple[str, ToolMessage]]:
+        return [
+            cls(dir_path="src"),
+            (
+                "I want to list the contents of src",
+                cls(dir_path="src"),
+            ),
+        ]
+
+    def handle(self) -> str:
+        # ASSUME: dir_path should be relative to the curr_dir_path
+        dir = (self._curr_dir and self._curr_dir()) or Path.cwd()
+        with chdir(dir):
+            contents = list_dir(self.dir_path)
+
+        if not contents:
+            return f"Directory not found or empty: {self.dir_path}"
+        contents_str = "\n".join(contents)
+        return dedent(
+            f"""
+            LISTING of directory {self.dir_path}:
+            ---------------------------
+            {contents_str}
+            """.strip()
+        )

langroid/agent/tools/google_search_tool.py

@@ -0,0 +1,39 @@
+"""
+A tool to trigger a Google search for a given query, and return the top results with
+their titles, links, summaries. Since the tool is stateless (i.e. does not need
+access to agent state), it can be enabled for any agent, without having to define a
+special method inside the agent: `agent.enable_message(GoogleSearchTool)`
+
+NOTE: Using this tool requires setting the GOOGLE_API_KEY and GOOGLE_CSE_ID
+environment variables in your `.env` file, as explained in the
+[README](https://github.com/langroid/langroid#gear-installation-and-setup).
+"""
+
+from typing import List, Tuple
+
+from langroid.agent.tool_message import ToolMessage
+from langroid.parsing.web_search import google_search
+
+
+class GoogleSearchTool(ToolMessage):
+    request: str = "web_search"
+    purpose: str = """
+            To search the web and return up to <num_results> links relevant to 
+            the given <query>. 
+            """
+    query: str
+    num_results: int
+
+    def handle(self) -> str:
+        search_results = google_search(self.query, self.num_results)
+        # return Title, Link, Summary of each result, separated by two newlines
+        return "\n\n".join(str(result) for result in search_results)
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+                num_results=3,
+            ),
+        ]

langroid/agent/tools/metaphor_search_tool.py

@@ -0,0 +1,68 @@
+"""
+A tool to trigger a Metaphor search for a given query,
+(https://docs.exa.ai/reference/getting-started)
+and return the top results with their titles, links, summaries.
+Since the tool is stateless (i.e. does not need
+access to agent state), it can be enabled for any agent, without having to define a
+special method inside the agent: `agent.enable_message(MetaphorSearchTool)`
+
+NOTE: To use this tool, you need to:
+
+* set the METAPHOR_API_KEY environment variables in
+your `.env` file, e.g. `METAPHOR_API_KEY=your_api_key_here`
+(Note as of 28 Jan 2023, Metaphor renamed to Exa, so you can also use
+`EXA_API_KEY=your_api_key_here`)
+
+* install langroid with the `metaphor` extra, e.g.
+`pip install langroid[metaphor]` or `uv pip install langroid[metaphor]` 
+or `poetry add langroid[metaphor]`  or `uv add langroid[metaphor]`
+(it installs the `metaphor-python` package from pypi).
+
+For more information, please refer to the official docs:
+https://metaphor.systems/
+"""
+
+from typing import List, Tuple
+
+from langroid.agent.tool_message import ToolMessage
+from langroid.parsing.web_search import metaphor_search
+
+
+class MetaphorSearchTool(ToolMessage):
+    request: str = "metaphor_search"
+    purpose: str = """
+            To search the web and return up to <num_results> 
+            links relevant to the given <query>. When using this tool,
+            ONLY show the required JSON, DO NOT SAY ANYTHING ELSE.
+            Wait for the results of the web search, and then use them to
+            compose your response.
+            """
+    query: str
+    num_results: int
+
+    def handle(self) -> str:
+        """
+        Conducts a search using the metaphor API based on the provided query
+        and number of results by triggering a metaphor_search.
+
+        Returns:
+            str: A formatted string containing the titles, links, and
+                summaries of each search result, separated by two newlines.
+        """
+
+        search_results = metaphor_search(self.query, self.num_results)
+        # return Title, Link, Summary of each result, separated by two newlines
+        results_str = "\n\n".join(str(result) for result in search_results)
+        return f"""
+        BELOW ARE THE RESULTS FROM THE WEB SEARCH. USE THESE TO COMPOSE YOUR RESPONSE:
+        {results_str}
+        """
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+                num_results=3,
+            ),
+        ]

langroid/agent/tools/orchestration.py

@@ -0,0 +1,303 @@
+"""
+Various tools to for agents to be able to control flow of Task, e.g.
+termination, routing to another agent, etc.
+"""
+
+from typing import Any, List, Tuple
+
+from langroid.agent.chat_agent import ChatAgent
+from langroid.agent.chat_document import ChatDocument
+from langroid.agent.tool_message import ToolMessage
+from langroid.mytypes import Entity
+from langroid.pydantic_v1 import Extra
+from langroid.utils.types import to_string
+
+
+class AgentDoneTool(ToolMessage):
+    """Tool for AGENT entity (i.e. agent_response or downstream tool handling fns) to
+    signal the current task is done."""
+
+    purpose: str = """
+    To signal the current task is done, along with an optional message <content>
+    of arbitrary type (default None) and an 
+    optional list of <tools> (default empty list).
+    """
+    request: str = "agent_done_tool"
+    content: Any = None
+    tools: List[ToolMessage] = []
+    # only meant for agent_response or tool-handlers, not for LLM generation:
+    _allow_llm_use: bool = False
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        content_str = "" if self.content is None else to_string(self.content)
+        return agent.create_agent_response(
+            content=content_str,
+            content_any=self.content,
+            tool_messages=[self] + self.tools,
+        )
+
+
+class DoneTool(ToolMessage):
+    """Tool for Agent Entity (i.e. agent_response) or LLM entity (i.e. llm_response) to
+    signal the current task is done, with some content as the result."""
+
+    purpose: str = """
+    To signal the current task is done, along with an optional message <content>
+    of arbitrary type (default None).
+    """
+    request: str = "done_tool"
+    content: str = ""
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            content=self.content,
+            content_any=self.content,
+            tool_messages=[self],
+        )
+
+    @classmethod
+    def instructions(cls) -> str:
+        tool_name = cls.default_value("request")
+        return f"""
+        When you determine your task is finished, 
+        use the tool `{tool_name}` to signal this,
+        along with any message or result, in the `content` field. 
+        """
+
+
+class ResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task (similar to (Agent)DoneTool), and
+    (b) be returned as the result of the current task, i.e. this tool would appear
+         in the resulting ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/tool-extract-short-example.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            ResultTool(field1 = val1, ...),
+            where the values can be arbitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of ResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used or handled
+            by an agent.
+        - AgentDoneTool is more restrictive in that you can only send a `content`
+            or `tools` in the result.
+    """
+
+    request: str = "result_tool"
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+
+    class Config:
+        extra = Extra.allow
+        arbitrary_types_allowed = False
+        validate_all = True
+        validate_assignment = True
+        # do not include these fields in the generated schema
+        # since we don't require the LLM to specify them
+        schema_extra = {"exclude": {"purpose", "id", "strict"}}
+
+    def handle(self) -> AgentDoneTool:
+        return AgentDoneTool(tools=[self])
+
+
+class FinalResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task as well as all parent tasks, and
+    (b) be returned as the final result of the root task, i.e. this tool would appear
+         in the final ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/chat-tool-function.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            FinalResultTool(field1 = val1, ...),
+            where the values can be arbitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of FinalResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used by an agent's
+            llm_response, but only by agent_response or tool handlers.
+        - A subclass of this tool can be defined, with specific fields, and
+          with _allow_llm_use = True, to allow the LLM to generate this tool,
+          and have the effect of terminating the current and all parent tasks,
+          with the tool appearing in the final ChatDocument's `tool_messages` list.
+          See examples/basic/multi-agent-return-result.py.
+    """
+
+    request: str = ""
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+    _allow_llm_use: bool = False
+
+    class Config:
+        extra = Extra.allow
+        arbitrary_types_allowed = False
+        validate_all = True
+        validate_assignment = True
+        # do not include these fields in the generated schema
+        # since we don't require the LLM to specify them
+        schema_extra = {"exclude": {"purpose", "id", "strict"}}
+
+
+class PassTool(ToolMessage):
+    """Tool for "passing" on the received msg (ChatDocument),
+    so that an as-yet-unspecified agent can handle it.
+    Similar to ForwardTool, but without specifying the recipient agent.
+    """
+
+    purpose: str = """
+    To pass the current message so that other agents can handle it.
+    """
+    request: str = "pass_tool"
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        """When this tool is enabled for an Agent, this will result in a method
+        added to the Agent with signature:
+        `forward_tool(self, tool: PassTool, chat_doc: ChatDocument) -> ChatDocument:`
+        """
+        # if PassTool is in chat_doc, pass its parent, else pass chat_doc itself
+        doc = chat_doc
+        while True:
+            tools = agent.get_tool_messages(doc)
+            if not any(isinstance(t, type(self)) for t in tools):
+                break
+            if doc.parent is None:
+                break
+            doc = doc.parent
+        assert doc is not None, "PassTool: parent of chat_doc must not be None"
+        new_doc = ChatDocument.deepcopy(doc)
+        new_doc.metadata.sender = Entity.AGENT
+        return new_doc
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        Use the `pass_tool` to PASS the current message 
+        so that another agent can handle it.
+        """
+
+
+class DonePassTool(PassTool):
+    """Tool to signal DONE, AND Pass incoming/current msg as result.
+    Similar to PassTool, except we append a DoneTool to the result tool_messages.
+    """
+
+    purpose: str = """
+    To signal the current task is done, with results set to the current/incoming msg.
+    """
+    request: str = "done_pass_tool"
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        # use PassTool to get the right ChatDocument to pass...
+        new_doc = PassTool.response(self, agent, chat_doc)
+        tools = agent.get_tool_messages(new_doc)
+        # ...then return an AgentDoneTool with content, tools from this ChatDocument
+        return AgentDoneTool(content=new_doc.content, tools=tools)  # type: ignore
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        When you determine your task is finished,
+        and want to pass the current message as the result of the task,  
+        use the `done_pass_tool` to signal this.
+        """
+
+
+class ForwardTool(PassTool):
+    """Tool for forwarding the received msg (ChatDocument) to another agent or entity.
+    Similar to PassTool, but with a specified recipient agent.
+    """
+
+    purpose: str = """
+    To forward the current message to an <agent>, where <agent> 
+    could be the name of an agent, or an entity such as "user", "llm".
+    """
+    request: str = "forward_tool"
+    agent: str
+
+    def response(self, agent: ChatAgent, chat_doc: ChatDocument) -> ChatDocument:
+        """When this tool is enabled for an Agent, this will result in a method
+        added to the Agent with signature:
+        `forward_tool(self, tool: ForwardTool, chat_doc: ChatDocument) -> ChatDocument:`
+        """
+        # if chat_doc contains ForwardTool, then we forward its parent ChatDocument;
+        # else forward chat_doc itself
+        new_doc = PassTool.response(self, agent, chat_doc)
+        new_doc.metadata.recipient = self.agent
+        return new_doc
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        If you need to forward the current message to another agent, 
+        use the `forward_tool` to do so, 
+        setting the `recipient` field to the name of the recipient agent.
+        """
+
+
+class SendTool(ToolMessage):
+    """Tool for agent or LLM to send content to a specified agent.
+    Similar to RecipientTool.
+    """
+
+    purpose: str = """
+    To send message <content> to agent specified in <to> field.
+    """
+    request: str = "send_tool"
+    to: str
+    content: str = ""
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            self.content,
+            recipient=self.to,
+        )
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        If you need to send a message to another agent, 
+        use the `send_tool` to do so, with these field values:
+        - `to` field = name of the recipient agent,
+        - `content` field = the message to send.
+        """
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
+        return [
+            cls(to="agent1", content="Hello, agent1!"),
+            (
+                """
+                I need to send the content 'Who built the Gemini model?', 
+                to the 'Searcher' agent.
+                """,
+                cls(to="Searcher", content="Who built the Gemini model?"),
+            ),
+        ]
+
+
+class AgentSendTool(ToolMessage):
+    """Tool for Agent (i.e. agent_response) to send content or tool_messages
+    to a specified agent. Similar to SendTool except that AgentSendTool is only
+    usable by agent_response (or handler of another tool), to send content or
+    tools to another agent. SendTool does not allow sending tools.
+    """
+
+    purpose: str = """
+    To send message <content> and <tools> to agent specified in <to> field. 
+    """
+    request: str = "agent_send_tool"
+    to: str
+    content: str = ""
+    tools: List[ToolMessage] = []
+    _allow_llm_use: bool = False
+
+    def response(self, agent: ChatAgent) -> ChatDocument:
+        return agent.create_agent_response(
+            self.content,
+            tool_messages=self.tools,
+            recipient=self.to,
+        )