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

langroid/agent/tools/file_tools.py

@@ -1,234 +0,0 @@
-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

@@ -1,39 +0,0 @@
-"""
-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

@@ -1,67 +0,0 @@
-"""
-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 `poetry 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

@@ -1,303 +0,0 @@
-"""
-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,
-        )