Squashed 'packages/tools/' content from commit 78317b9c

git-subtree-dir: packages/tools
git-subtree-split: 78317b9c127f18bd040c1d77e3c0840cdc9a5b38

crewai_tools/tools/file_read_tool/README.md

@@ -0,0 +1,40 @@
+# FileReadTool
+
+## Description
+
+The FileReadTool is a versatile component of the crewai_tools package, designed to streamline the process of reading and retrieving content from files. It is particularly useful in scenarios such as batch text file processing, runtime configuration file reading, and data importation for analytics. This tool supports various text-based file formats including `.txt`, `.csv`, `.json`, and adapts its functionality based on the file type, for instance, converting JSON content into a Python dictionary for easy use.
+
+The tool also supports reading specific chunks of a file by specifying a starting line and the number of lines to read, which is helpful when working with large files that don't need to be loaded entirely into memory.
+
+## Installation
+
+Install the crewai_tools package to use the FileReadTool in your projects:
+
+```shell
+pip install 'crewai[tools]'
+```
+
+## Example
+
+To get started with the FileReadTool:
+
+```python
+from crewai_tools import FileReadTool
+
+# Initialize the tool to read any files the agents knows or lean the path for
+file_read_tool = FileReadTool()
+
+# OR
+
+# Initialize the tool with a specific file path, so the agent can only read the content of the specified file
+file_read_tool = FileReadTool(file_path='path/to/your/file.txt')
+
+# Read a specific chunk of the file (lines 100-149)
+partial_content = file_read_tool.run(file_path='path/to/your/file.txt', start_line=100, line_count=50)
+```
+
+## Arguments
+
+- `file_path`: The path to the file you want to read. It accepts both absolute and relative paths. Ensure the file exists and you have the necessary permissions to access it.
+- `start_line`: (Optional) The line number to start reading from (1-indexed). Defaults to 1 (the first line).
+- `line_count`: (Optional) The number of lines to read. If not provided, reads from the start_line to the end of the file.

crewai_tools/tools/file_read_tool/file_read_tool.py

@@ -0,0 +1,97 @@
+from typing import Any, Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class FileReadToolSchema(BaseModel):
+    """Input for FileReadTool."""
+
+    file_path: str = Field(..., description="Mandatory file full path to read the file")
+    start_line: Optional[int] = Field(1, description="Line number to start reading from (1-indexed)")
+    line_count: Optional[int] = Field(None, description="Number of lines to read. If None, reads the entire file")
+
+
+class FileReadTool(BaseTool):
+    """A tool for reading file contents.
+
+    This tool inherits its schema handling from BaseTool to avoid recursive schema
+    definition issues. The args_schema is set to FileReadToolSchema which defines
+    the required file_path parameter. The schema should not be overridden in the
+    constructor as it would break the inheritance chain and cause infinite loops.
+
+    The tool supports two ways of specifying the file path:
+    1. At construction time via the file_path parameter
+    2. At runtime via the file_path parameter in the tool's input
+
+    Args:
+        file_path (Optional[str]): Path to the file to be read. If provided,
+            this becomes the default file path for the tool.
+        **kwargs: Additional keyword arguments passed to BaseTool.
+
+    Example:
+        >>> tool = FileReadTool(file_path="/path/to/file.txt")
+        >>> content = tool.run()  # Reads /path/to/file.txt
+        >>> content = tool.run(file_path="/path/to/other.txt")  # Reads other.txt
+        >>> content = tool.run(file_path="/path/to/file.txt", start_line=100, line_count=50)  # Reads lines 100-149
+    """
+
+    name: str = "Read a file's content"
+    description: str = "A tool that reads the content of a file. To use this tool, provide a 'file_path' parameter with the path to the file you want to read. Optionally, provide 'start_line' to start reading from a specific line and 'line_count' to limit the number of lines read."
+    args_schema: Type[BaseModel] = FileReadToolSchema
+    file_path: Optional[str] = None
+
+    def __init__(self, file_path: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize the FileReadTool.
+
+        Args:
+            file_path (Optional[str]): Path to the file to be read. If provided,
+                this becomes the default file path for the tool.
+            **kwargs: Additional keyword arguments passed to BaseTool.
+        """
+        if file_path is not None:
+            kwargs["description"] = (
+                f"A tool that reads file content. The default file is {file_path}, but you can provide a different 'file_path' parameter to read another file. You can also specify 'start_line' and 'line_count' to read specific parts of the file."
+            )
+
+        super().__init__(**kwargs)
+        self.file_path = file_path
+
+    def _run(
+        self,
+        file_path: Optional[str] = None,
+        start_line: Optional[int] = 1,
+        line_count: Optional[int] = None,
+    ) -> str:
+        file_path = file_path or self.file_path
+        start_line = start_line or 1
+        line_count = line_count or None
+
+        if file_path is None:
+            return (
+                "Error: No file path provided. Please provide a file path either in the constructor or as an argument."
+            )
+
+        try:
+            with open(file_path, "r") as file:
+                if start_line == 1 and line_count is None:
+                    return file.read()
+
+                start_idx = max(start_line - 1, 0)
+
+                selected_lines = [
+                    line
+                    for i, line in enumerate(file)
+                    if i >= start_idx and (line_count is None or i < start_idx + line_count)
+                ]
+
+                if not selected_lines and start_idx > 0:
+                    return f"Error: Start line {start_line} exceeds the number of lines in the file."
+
+                return "".join(selected_lines)
+        except FileNotFoundError:
+            return f"Error: File not found at path: {file_path}"
+        except PermissionError:
+            return f"Error: Permission denied when trying to read file: {file_path}"
+        except Exception as e:
+            return f"Error: Failed to read file {file_path}. {str(e)}"