langroid 0.16.7__tar.gz → 0.17.0__tar.gz

{langroid-0.16.7 → langroid-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langroid
-Version: 0.16.7
+Version: 0.17.0
 Summary: Harness LLMs with Multi-Agent Programming
 License: MIT
 Author: Prasad Chalasani
@@ -48,6 +48,7 @@ Requires-Dist: faker (>=18.9.0,<19.0.0)
 Requires-Dist: fakeredis (>=2.12.1,<3.0.0)
 Requires-Dist: fastembed (>=0.3.1,<0.4.0) ; extra == "all" or extra == "fastembed"
 Requires-Dist: fire (>=0.5.0,<0.6.0)
+Requires-Dist: gitpython (>=3.1.43,<4.0.0)
 Requires-Dist: google-api-python-client (>=2.95.0,<3.0.0)
 Requires-Dist: google-generativeai (>=0.5.2,<0.6.0)
 Requires-Dist: groq (>=0.5.0,<0.6.0)
@@ -55,7 +56,7 @@ Requires-Dist: grpcio (>=1.62.1,<2.0.0)
 Requires-Dist: halo (>=0.0.31,<0.0.32)
 Requires-Dist: huggingface-hub (>=0.21.2,<0.22.0) ; extra == "hf-transformers" or extra == "all" or extra == "transformers"
 Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
-Requires-Dist: json-repair (>=0.29.0,<0.30.0)
+Requires-Dist: json-repair (>=0.29.9,<0.30.0)
 Requires-Dist: lancedb (>=0.8.2,<0.9.0) ; extra == "vecdbs" or extra == "lancedb"
 Requires-Dist: litellm (>=1.30.1,<2.0.0) ; extra == "all" or extra == "litellm"
 Requires-Dist: lxml (>=4.9.3,<5.0.0)
@@ -143,7 +144,7 @@ Description-Content-Type: text/markdown
 </h3>
 
 `Langroid` is an intuitive, lightweight, extensible and principled
-Python framework to easily build LLM-powered applications, from ex-CMU and UW-Madison researchers. 
+Python framework to easily build LLM-powered applications, from CMU and UW-Madison researchers. 
 You set up Agents, equip them with optional components (LLM, 
 vector-store and tools/functions), assign them tasks, and have them 
 collaboratively solve a problem by exchanging messages. 
@@ -242,6 +243,8 @@ teacher_task.run()
 <details>
 <summary> <b>Click to expand</b></summary>
 
+- **Oct 2024:**
+  - **[0.17.0]** XML-based tools, see [docs](https://langroid.github.io/langroid/tutorials/xml-tools/).
 - **Sep 2024:**
   - **[0.16.0](https://github.com/langroid/langroid/releases/tag/0.16.0)**  Support for OpenAI `o1-mini` and `o1-preview` models.
   - **[0.15.0](https://github.com/langroid/langroid/releases/tag/0.15.0)** Cerebras API support -- run llama-3.1 models hosted on Cerebras Cloud (very fast inference).

{langroid-0.16.7 → langroid-0.17.0}/README.md

@@ -35,7 +35,7 @@
 </h3>
 
 `Langroid` is an intuitive, lightweight, extensible and principled
-Python framework to easily build LLM-powered applications, from ex-CMU and UW-Madison researchers. 
+Python framework to easily build LLM-powered applications, from CMU and UW-Madison researchers. 
 You set up Agents, equip them with optional components (LLM, 
 vector-store and tools/functions), assign them tasks, and have them 
 collaboratively solve a problem by exchanging messages. 
@@ -134,6 +134,8 @@ teacher_task.run()
 <details>
 <summary> <b>Click to expand</b></summary>
 
+- **Oct 2024:**
+  - **[0.17.0]** XML-based tools, see [docs](https://langroid.github.io/langroid/tutorials/xml-tools/).
 - **Sep 2024:**
   - **[0.16.0](https://github.com/langroid/langroid/releases/tag/0.16.0)**  Support for OpenAI `o1-mini` and `o1-preview` models.
   - **[0.15.0](https://github.com/langroid/langroid/releases/tag/0.15.0)** Cerebras API support -- run llama-3.1 models hosted on Cerebras Cloud (very fast inference).

{langroid-0.16.7 → langroid-0.17.0}/langroid/agent/base.py

@@ -32,6 +32,7 @@ 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.language_models.base import (
     LanguageModel,
     LLMConfig,
@@ -55,7 +56,13 @@ from langroid.pydantic_v1 import (
     validator,
 )
 from langroid.utils.configuration import settings
-from langroid.utils.constants import DONE, NO_ANSWER, PASS, PASS_TO, SEND_TO
+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
@@ -910,7 +917,7 @@ class Agent(ABC):
             return []
 
         if isinstance(msg, str):
-            json_tools = self.get_json_tool_messages(msg)
+            json_tools = self.get_formatted_tool_messages(msg)
             if all_tools:
                 return json_tools
             else:
@@ -938,7 +945,7 @@ class Agent(ABC):
             and msg.function_call is None
         ):
 
-            tools = self.get_json_tool_messages(msg.content)
+            tools = self.get_formatted_tool_messages(msg.content)
             msg.all_tool_messages = tools
             my_tools = [t for t in tools if self._tool_recipient_match(t)]
             msg.tool_messages = my_tools
@@ -966,9 +973,16 @@ class Agent(ABC):
         else:
             return my_tools
 
-    def get_json_tool_messages(self, input_str: str) -> List[ToolMessage]:
+    def get_formatted_tool_messages(self, input_str: str) -> List[ToolMessage]:
         """
-        Returns ToolMessage objects (tools) corresponding to JSON substrings, if any.
+        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
@@ -976,10 +990,15 @@ class Agent(ABC):
         Returns:
             List[ToolMessage]: list of ToolMessage objects
         """
-        json_substrings = extract_top_level_json(input_str)
-        if len(json_substrings) == 0:
-            return []
-        results = [self._get_one_tool_message(j) for j in json_substrings]
+        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]
         return [r for r in results if r is not None]
 
     def get_function_call_class(self, msg: ChatDocument) -> Optional[ToolMessage]:
@@ -1200,17 +1219,22 @@ class Agent(ABC):
         """
         return None
 
-    def _get_one_tool_message(self, json_str: str) -> Optional[ToolMessage]:
+    def _get_one_tool_message(
+        self, tool_candidate_str: str, is_json: bool = True
+    ) -> Optional[ToolMessage]:
         """
-        Parse the json str into ANY ToolMessage KNOWN to agent --
+        Parse the tool_candidate_str into ANY ToolMessage KNOWN to agent --
         This includes non-used/handled tools, i.e. any tool in self.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 JSON --
+        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.
         """
-        json_data = json.loads(json_str)
-        # check if the json_data contains a "properties" field
+        if is_json:
+            maybe_tool_dict = json.loads(tool_candidate_str)
+        else:
+            maybe_tool_dict = XMLToolMessage.extract_field_values(tool_candidate_str)
+        # 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: {
@@ -1225,17 +1249,17 @@ class Agent(ABC):
         #     ]
         # }
 
-        if not isinstance(json_data, dict):
+        if not isinstance(maybe_tool_dict, dict):
             return None
 
-        properties = json_data.get("properties")
+        properties = maybe_tool_dict.get("properties")
         if isinstance(properties, dict):
-            json_data = properties
-        request = json_data.get("request")
+            maybe_tool_dict = properties
+        request = maybe_tool_dict.get("request")
         if request is None:
             possible = [self.llm_tools_map[r] for r in self.llm_tools_handled]
             default_keys = set(ToolMessage.__fields__.keys())
-            request_keys = set(json_data.keys())
+            request_keys = set(maybe_tool_dict.keys())
 
             def maybe_parse(tool: type[ToolMessage]) -> Optional[ToolMessage]:
                 all_keys = set(tool.__fields__.keys())
@@ -1250,7 +1274,7 @@ class Agent(ABC):
                     return None
 
                 try:
-                    return tool.parse_obj(json_data)
+                    return tool.parse_obj(maybe_tool_dict)
                 except ValidationError:
                     return None
 
@@ -1277,7 +1301,7 @@ class Agent(ABC):
             return None
 
         try:
-            message = message_class.parse_obj(json_data)
+            message = message_class.parse_obj(maybe_tool_dict)
         except ValidationError as ve:
             raise ve
         return message

{langroid-0.16.7 → langroid-0.17.0}/langroid/agent/chat_agent.py

@@ -12,6 +12,7 @@ from rich.markup import escape
 from langroid.agent.base import Agent, AgentConfig, noop_fn
 from langroid.agent.chat_document import ChatDocument
 from langroid.agent.tool_message import ToolMessage
+from langroid.agent.xml_tool_message import XMLToolMessage
 from langroid.language_models.base import (
     LLMFunctionSpec,
     LLMMessage,
@@ -141,7 +142,7 @@ class ChatAgent(Agent):
         #   if they are specified in a ToolMessage class as a classmethod `instructions`
         self.system_tool_instructions: str = ""
         # (b) these are only for the builtin in Langroid TOOLS mechanism:
-        self.system_json_tool_instructions: str = ""
+        self.system_tool_format_instructions: str = ""
 
         self.llm_functions_map: Dict[str, LLMFunctionSpec] = {}
         self.llm_functions_handled: Set[str] = set()
@@ -207,7 +208,7 @@ class ChatAgent(Agent):
         config_copy.name = f"{config_copy.name}-{i}"
         new_agent = agent_cls(config_copy)
         new_agent.system_tool_instructions = self.system_tool_instructions
-        new_agent.system_json_tool_instructions = self.system_json_tool_instructions
+        new_agent.system_tool_format_instructions = self.system_tool_format_instructions
         new_agent.llm_tools_map = self.llm_tools_map
         new_agent.llm_functions_map = self.llm_functions_map
         new_agent.llm_functions_handled = self.llm_functions_handled
@@ -303,10 +304,11 @@ class ChatAgent(Agent):
             ]
         )
 
-    def json_format_rules(self) -> str:
+    def tool_format_rules(self) -> str:
         """
-        Specification of JSON formatting rules, based on the currently enabled
-        usable `ToolMessage`s
+        Specification of tool formatting rules
+        (typically JSON-based but can be non-JSON, e.g. XMLToolMessage),
+        based on the currently enabled usable `ToolMessage`s
 
         Returns:
             str: formatting rules
@@ -320,9 +322,9 @@ class ChatAgent(Agent):
 
         if len(usable_tool_classes) == 0:
             return "You can ask questions in natural language."
-        json_instructions = "\n\n".join(
+        format_instructions = "\n\n".join(
             [
-                msg_cls.json_instructions(tool=self.config.use_tools)
+                msg_cls.format_instructions(tool=self.config.use_tools)
                 for msg_cls in usable_tool_classes
             ]
         )
@@ -332,11 +334,11 @@ class ChatAgent(Agent):
             if hasattr(msg_cls, "json_group_instructions") and callable(
                 getattr(msg_cls, "json_group_instructions")
             ):
-                return msg_cls.json_group_instructions().format(
-                    json_instructions=json_instructions
+                return msg_cls.group_format_instructions().format(
+                    format_instructions=format_instructions
                 )
-        return ToolMessage.json_group_instructions().format(
-            json_instructions=json_instructions
+        return ToolMessage.group_format_instructions().format(
+            format_instructions=format_instructions
         )
 
     def tool_instructions(self) -> str:
@@ -358,7 +360,7 @@ class ChatAgent(Agent):
                 and inspect.ismethod(msg_cls.instructions)
                 and msg_cls.default_value("request") in self.llm_tools_usable
             ):
-                # example will be shown in json_format_rules() when using TOOLs,
+                # example will be shown in tool_format_rules() when using TOOLs,
                 # so we don't need to show it here.
                 example = "" if self.config.use_tools else (msg_cls.usage_examples())
                 if example != "":
@@ -457,7 +459,7 @@ class ChatAgent(Agent):
             
             {self.system_tool_instructions}
             
-            {self.system_json_tool_instructions}
+            {self.system_tool_format_instructions}
             
             """.lstrip()
         )
@@ -520,6 +522,12 @@ class ChatAgent(Agent):
             return None
         if require_recipient and message_class is not None:
             message_class = message_class.require_recipient()
+        if isinstance(message_class, XMLToolMessage):
+            # XMLToolMessage is not compatible with OpenAI's Tools/functions API,
+            # so we disable use of functions API, enable langroid-native Tools,
+            # which are prompt-based.
+            self.config.use_functions_api = False
+            self.config.use_tools = True
         super().enable_message_handling(message_class)  # enables handling only
         tools = self._get_tool_list(message_class)
         if message_class is not None:
@@ -570,7 +578,7 @@ class ChatAgent(Agent):
 
         # Set tool instructions and JSON format instructions
         if self.config.use_tools:
-            self.system_json_tool_instructions = self.json_format_rules()
+            self.system_tool_format_instructions = self.tool_format_rules()
         self.system_tool_instructions = self.tool_instructions()
 
     def disable_message_handling(

{langroid-0.16.7 → langroid-0.17.0}/langroid/agent/chat_document.py

@@ -7,6 +7,7 @@ from enum import Enum
 from typing import Any, Dict, List, Optional, Union, cast
 
 from langroid.agent.tool_message import ToolMessage
+from langroid.agent.xml_tool_message import XMLToolMessage
 from langroid.language_models.base import (
     LLMFunctionCall,
     LLMMessage,
@@ -181,21 +182,29 @@ class ChatDocument(Document):
             f"{recipient_str}{tool_str}{fields.content}"
         )
 
-    def get_json_tools(self) -> List[str]:
+    def get_tool_names(self) -> List[str]:
         """
-        Get names of attempted JSON tool usages in the content
+        Get names of attempted tool usages (JSON or non-JSON) in the content
             of the message.
         Returns:
-            List[str]: list of JSON tool names
+            List[str]: list of *attempted* tool names
+            (We say "attempted" since we ONLY look at the `request` component of the
+            tool-call representation, and we're not fully parsing it into the
+            corresponding tool message class)
+
         """
-        jsons = extract_top_level_json(self.content)
-        tools = []
-        for j in jsons:
-            json_data = json.loads(j)
-            tool = json_data.get("request")
-            if tool is not None:
-                tools.append(str(tool))
-        return tools
+        tool_candidates = XMLToolMessage.find_candidates(self.content)
+        if len(tool_candidates) == 0:
+            tool_candidates = extract_top_level_json(self.content)
+            if len(tool_candidates) == 0:
+                return []
+            tools = [json.loads(tc).get("request") for tc in tool_candidates]
+        else:
+            tool_dicts = [
+                XMLToolMessage.extract_field_values(tc) for tc in tool_candidates
+            ]
+            tools = [td.get("request") for td in tool_dicts if td is not None]
+        return [str(tool) for tool in tools if tool is not None]
 
     def log_fields(self) -> ChatDocLoggerFields:
         """
@@ -208,9 +217,9 @@ class ChatDocument(Document):
         if self.function_call is not None:
             tool_type = "FUNC"
             tool = self.function_call.name
-        elif self.get_json_tools() != []:
+        elif (json_tools := self.get_tool_names()) != []:
             tool_type = "TOOL"
-            tool = self.get_json_tools()[0]
+            tool = json_tools[0]
         recipient = self.metadata.recipient
         content = self.content
         sender_entity = self.metadata.sender

{langroid-0.16.7 → langroid-0.17.0}/langroid/agent/tool_message.py

@@ -72,7 +72,7 @@ class ToolMessage(ABC, BaseModel):
     @classmethod
     def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
         """
-        Examples to use in few-shot demos with JSON formatting instructions.
+        Examples to use in few-shot demos with formatting instructions.
         Each example can be either:
         - just a ToolMessage instance, e.g. MyTool(param1=1, param2="hello"), or
         - a tuple (description, ToolMessage instance), where the description is
@@ -104,20 +104,20 @@ class ToolMessage(ABC, BaseModel):
             examples = [choice(cls.examples())]
         else:
             examples = cls.examples()
-        examples_jsons = [
+        formatted_examples = [
             (
-                f"EXAMPLE {i}: (THOUGHT: {ex[0]}) => \n{ex[1].json_example()}"
+                f"EXAMPLE {i}: (THOUGHT: {ex[0]}) => \n{ex[1].format_example()}"
                 if isinstance(ex, tuple)
-                else f"EXAMPLE {i}:\n {ex.json_example()}"
+                else f"EXAMPLE {i}:\n {ex.format_example()}"
             )
             for i, ex in enumerate(examples, 1)
         ]
-        return "\n\n".join(examples_jsons)
+        return "\n\n".join(formatted_examples)
 
     def to_json(self) -> str:
         return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
 
-    def json_example(self) -> str:
+    def format_example(self) -> str:
         return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
 
     def dict_example(self) -> Dict[str, Any]:
@@ -148,7 +148,7 @@ class ToolMessage(ABC, BaseModel):
         return properties.get(f, {}).get("default", None)
 
     @classmethod
-    def json_instructions(cls, tool: bool = False) -> str:
+    def format_instructions(cls, tool: bool = False) -> str:
         """
         Default Instructions to the LLM showing how to use the tool/function-call.
         Works for GPT4 but override this for weaker LLMs if needed.
@@ -181,19 +181,19 @@ class ToolMessage(ABC, BaseModel):
         )
 
     @staticmethod
-    def json_group_instructions() -> str:
+    def group_format_instructions() -> str:
         """Template for instructions for a group of tools.
         Works with GPT4 but override this for weaker LLMs if needed.
         """
         return textwrap.dedent(
             """
-            === ALL AVAILABLE TOOLS and THEIR JSON FORMAT INSTRUCTIONS ===
+            === ALL AVAILABLE TOOLS and THEIR FORMAT INSTRUCTIONS ===
             You have access to the following TOOLS to accomplish your task:
 
-            {json_instructions}
+            {format_instructions}
             
             When one of the above TOOLs is applicable, you must express your 
-            request as "TOOL:" followed by the request in the above JSON format.
+            request as "TOOL:" followed by the request in the above format.
             """
         )
 

langroid-0.17.0/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()
+        )