agno 2.0.0rc2__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/tools/file.py

@@ -1,9 +1,9 @@
 import json
 from pathlib import Path
-from typing import Any, List, Optional
+from typing import Any, List, Optional, Tuple
 
 from agno.tools import Toolkit
-from agno.utils.log import log_debug, log_error, log_info
+from agno.utils.log import log_debug, log_error
 
 
 class FileTools(Toolkit):
@@ -12,14 +12,26 @@ class FileTools(Toolkit):
         base_dir: Optional[Path] = None,
         enable_save_file: bool = True,
         enable_read_file: bool = True,
+        enable_delete_file: bool = False,
         enable_list_files: bool = True,
         enable_search_files: bool = True,
+        enable_read_file_chunk: bool = True,
+        enable_replace_file_chunk: bool = True,
+        expose_base_directory: bool = False,
+        max_file_length: int = 10000000,
+        max_file_lines: int = 100000,
+        line_separator: str = "\n",
         all: bool = False,
         **kwargs,
     ):
         self.base_dir: Path = base_dir or Path.cwd()
+        self.base_dir = self.base_dir.resolve()
 
         tools: List[Any] = []
+        self.max_file_length = max_file_length
+        self.max_file_lines = max_file_lines
+        self.line_separator = line_separator
+        self.expose_base_directory = expose_base_directory
         if all or enable_save_file:
             tools.append(self.save_file)
         if all or enable_read_file:
@@ -28,10 +40,16 @@ class FileTools(Toolkit):
             tools.append(self.list_files)
         if all or enable_search_files:
             tools.append(self.search_files)
+        if all or enable_delete_file:
+            tools.append(self.delete_file)
+        if all or enable_read_file_chunk:
+            tools.append(self.read_file_chunk)
+        if all or enable_replace_file_chunk:
+            tools.append(self.replace_file_chunk)
 
         super().__init__(name="file_tools", tools=tools, **kwargs)
 
-    def save_file(self, contents: str, file_name: str, overwrite: bool = True) -> str:
+    def save_file(self, contents: str, file_name: str, overwrite: bool = True, encoding: str = "utf-8") -> str:
         """Saves the contents to a file called `file_name` and returns the file name if successful.
 
         :param contents: The contents to save.
@@ -40,42 +58,146 @@ class FileTools(Toolkit):
         :return: The file name if successful, otherwise returns an error message.
         """
         try:
-            file_path = self.base_dir.joinpath(file_name)
+            safe, file_path = self.check_escape(file_name)
+            if not (safe):
+                log_error(f"Attempted to save file: {file_name}")
+                return "Error saving file"
             log_debug(f"Saving contents to {file_path}")
             if not file_path.parent.exists():
                 file_path.parent.mkdir(parents=True, exist_ok=True)
             if file_path.exists() and not overwrite:
                 return f"File {file_name} already exists"
-            file_path.write_text(contents)
-            log_info(f"Saved: {file_path}")
+            file_path.write_text(contents, encoding=encoding)
+            log_debug(f"Saved: {file_path}")
             return str(file_name)
         except Exception as e:
             log_error(f"Error saving to file: {e}")
             return f"Error saving to file: {e}"
 
-    def read_file(self, file_name: str) -> str:
+    def read_file_chunk(self, file_name: str, start_line: int, end_line: int, encoding: str = "utf-8") -> str:
+        """Reads the contents of the file `file_name` and returns lines from start_line to end_line.
+
+        :param file_name: The name of the file to read.
+        :param start_line: Number of first line in the returned chunk
+        :param end_line: Number of the last line in the returned chunk
+        :param encoding: Encoding to use, default - utf-8
+
+        :return: The contents of the selected chunk
+        """
+        try:
+            log_debug(f"Reading file: {file_name}")
+            safe, file_path = self.check_escape(file_name)
+            if not (safe):
+                log_error(f"Attempted to read file: {file_name}")
+                return "Error reading file"
+            contents = file_path.read_text(encoding=encoding)
+            lines = contents.split(self.line_separator)
+            return self.line_separator.join(lines[start_line : end_line + 1])
+        except Exception as e:
+            log_error(f"Error reading file: {e}")
+            return f"Error reading file: {e}"
+
+    def replace_file_chunk(
+        self, file_name: str, start_line: int, end_line: int, chunk: str, encoding: str = "utf-8"
+    ) -> str:
+        """Reads the contents of the file, replaces lines
+        between start_line and end_line with chunk and writes the file
+
+        :param file_name: The name of the file to process.
+        :param start_line: Number of first line in the replaced chunk
+        :param end_line: Number of the last line in the replaced chunk
+        :param chunk: String to be inserted instead of lines from start_line to end_line. Can have multiple lines.
+        :param encoding: Encoding to use, default - utf-8
+
+        :return: file name if successfull, error message otherwise
+        """
+        try:
+            log_debug(f"Patching file: {file_name}")
+            safe, file_path = self.check_escape(file_name)
+            if not (safe):
+                log_error(f"Attempted to read file: {file_name}")
+                return "Error reading file"
+            contents = file_path.read_text(encoding=encoding)
+            lines = contents.split(self.line_separator)
+            start = lines[0:start_line]
+            end = lines[end_line + 1 :]
+            return self.save_file(
+                file_name=file_name, contents=self.line_separator.join(start + [chunk] + end), encoding=encoding
+            )
+        except Exception as e:
+            log_error(f"Error patching file: {e}")
+            return f"Error patching file: {e}"
+
+    def read_file(self, file_name: str, encoding: str = "utf-8") -> str:
         """Reads the contents of the file `file_name` and returns the contents if successful.
 
         :param file_name: The name of the file to read.
+        :param encoding: Encoding to use, default - utf-8
         :return: The contents of the file if successful, otherwise returns an error message.
         """
         try:
-            log_info(f"Reading file: {file_name}")
-            file_path = self.base_dir.joinpath(file_name)
-            contents = file_path.read_text(encoding="utf-8")
+            log_debug(f"Reading file: {file_name}")
+            safe, file_path = self.check_escape(file_name)
+            if not (safe):
+                log_error(f"Attempted to read file: {file_name}")
+                return "Error reading file"
+            contents = file_path.read_text(encoding=encoding)
+            if len(contents) > self.max_file_length:
+                return "Error reading file: file too long. Use read_file_chunk instead"
+            if len(contents.split(self.line_separator)) > self.max_file_lines:
+                return "Error reading file: file too long. Use read_file_chunk instead"
+
             return str(contents)
         except Exception as e:
             log_error(f"Error reading file: {e}")
             return f"Error reading file: {e}"
 
-    def list_files(self) -> str:
-        """Returns a list of files in the base directory
+    def delete_file(self, file_name: str) -> str:
+        """Deletes a file
+        :param file_name: Name of the file to delete
+
+        :return: Empty string, if operation succeeded, otherwise returns an error message
+        """
+        safe, path = self.check_escape(file_name)
+        try:
+            if safe:
+                if path.is_dir():
+                    path.rmdir()
+                    return ""
+                path.unlink()
+                return ""
+            else:
+                log_error(f"Attempt to delete file outside {self.base_dir}: {file_name}")
+                return "Incorrect file_name"
+        except Exception as e:
+            log_error(f"Error removing {file_name}: {e}")
+            return f"Error removing file: {e}"
+
+    def check_escape(self, relative_path: str) -> Tuple[bool, Path]:
+        d = self.base_dir.joinpath(Path(relative_path)).resolve()
+        if self.base_dir == d:
+            return True, d
+        try:
+            d.relative_to(self.base_dir)
+        except ValueError:
+            log_error("Attempted to escape base_dir")
+            return False, self.base_dir
+        return True, d
+
+    def list_files(self, **kwargs) -> str:
+        """Returns a list of files in directory
+        :param directory: (Optional) name of directory to list.
 
         :return: The contents of the file if successful, otherwise returns an error message.
         """
+        directory = kwargs.get("directory", ".")
         try:
-            log_info(f"Reading files in : {self.base_dir}")
-            return json.dumps([str(file_path) for file_path in self.base_dir.iterdir()], indent=4)
+            log_debug(f"Reading files in : {self.base_dir}/{directory}")
+            safe, d = self.check_escape(directory)
+            if safe:
+                return json.dumps([str(file_path.relative_to(self.base_dir)) for file_path in d.iterdir()], indent=4)
+            else:
+                return "{}"
         except Exception as e:
             log_error(f"Error reading files: {e}")
             return f"Error reading files: {e}"
@@ -92,15 +214,23 @@ class FileTools(Toolkit):
 
             log_debug(f"Searching files in {self.base_dir} with pattern {pattern}")
             matching_files = list(self.base_dir.glob(pattern))
-
-            file_paths = [str(file_path) for file_path in matching_files]
-
-            result = {
-                "pattern": pattern,
-                "base_directory": str(self.base_dir),
-                "matches_found": len(file_paths),
-                "files": file_paths,
-            }
+            result = None
+            if self.expose_base_directory:
+                file_paths = [str(file_path) for file_path in matching_files]
+                result = {
+                    "pattern": pattern,
+                    "matches_found": len(file_paths),
+                    "base_directory": str(self.base_dir),
+                    "files": file_paths,
+                }
+            else:
+                file_paths = [str(file_path.relative_to(self.base_dir)) for file_path in matching_files]
+
+                result = {
+                    "pattern": pattern,
+                    "matches_found": len(file_paths),
+                    "files": file_paths,
+                }
             log_debug(f"Found {len(file_paths)} files matching pattern {pattern}")
             return json.dumps(result, indent=2)
 

agno/tools/file_generation.py

@@ -0,0 +1,350 @@
+import csv
+import io
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+from uuid import uuid4
+
+from agno.media import File
+from agno.tools import Toolkit
+from agno.tools.function import ToolResult
+from agno.utils.log import log_debug, logger
+
+try:
+    from reportlab.lib.pagesizes import letter
+    from reportlab.lib.styles import getSampleStyleSheet
+    from reportlab.lib.units import inch
+    from reportlab.platypus import Paragraph, SimpleDocTemplate, Spacer
+
+    PDF_AVAILABLE = True
+except ImportError:
+    PDF_AVAILABLE = False
+    logger.warning("reportlab not installed. PDF generation will not be available. Install with: pip install reportlab")
+
+
+class FileGenerationTools(Toolkit):
+    def __init__(
+        self,
+        enable_json_generation: bool = True,
+        enable_csv_generation: bool = True,
+        enable_pdf_generation: bool = True,
+        enable_txt_generation: bool = True,
+        output_directory: Optional[str] = None,
+        all: bool = False,
+        **kwargs,
+    ):
+        self.enable_json_generation = enable_json_generation
+        self.enable_csv_generation = enable_csv_generation
+        self.enable_pdf_generation = enable_pdf_generation and PDF_AVAILABLE
+        self.enable_txt_generation = enable_txt_generation
+        self.output_directory = Path(output_directory) if output_directory else None
+
+        # Create output directory if specified
+        if self.output_directory:
+            self.output_directory.mkdir(parents=True, exist_ok=True)
+            log_debug(f"Files will be saved to: {self.output_directory}")
+
+        if enable_pdf_generation and not PDF_AVAILABLE:
+            logger.warning("PDF generation requested but reportlab is not installed. Disabling PDF generation.")
+            self.enable_pdf_generation = False
+
+        tools: List[Any] = []
+        if all or enable_json_generation:
+            tools.append(self.generate_json_file)
+        if all or enable_csv_generation:
+            tools.append(self.generate_csv_file)
+        if all or (enable_pdf_generation and PDF_AVAILABLE):
+            tools.append(self.generate_pdf_file)
+        if all or enable_txt_generation:
+            tools.append(self.generate_text_file)
+
+        super().__init__(name="file_generation", tools=tools, **kwargs)
+
+    def _save_file_to_disk(self, content: Union[str, bytes], filename: str) -> Optional[str]:
+        """Save file to disk if output_directory is set. Return file path or None."""
+        if not self.output_directory:
+            return None
+
+        file_path = self.output_directory / filename
+
+        if isinstance(content, str):
+            file_path.write_text(content, encoding="utf-8")
+        else:
+            file_path.write_bytes(content)
+
+        log_debug(f"File saved to: {file_path}")
+        return str(file_path)
+
+    def generate_json_file(self, data: Union[Dict, List, str], filename: Optional[str] = None) -> ToolResult:
+        """Generate a JSON file from the provided data.
+
+        Args:
+            data: The data to write to the JSON file. Can be a dictionary, list, or JSON string.
+            filename: Optional filename for the generated file. If not provided, a UUID will be used.
+
+        Returns:
+            ToolResult: Result containing the generated JSON file as a FileArtifact.
+        """
+        try:
+            log_debug(f"Generating JSON file with data: {type(data)}")
+
+            # Handle different input types
+            if isinstance(data, str):
+                try:
+                    json.loads(data)
+                    json_content = data  # Use the original string if it's valid JSON
+                except json.JSONDecodeError:
+                    # If it's not valid JSON, treat as plain text and wrap it
+                    json_content = json.dumps({"content": data}, indent=2)
+            else:
+                json_content = json.dumps(data, indent=2, ensure_ascii=False)
+
+            # Generate filename if not provided
+            if not filename:
+                filename = f"generated_file_{str(uuid4())[:8]}.json"
+            elif not filename.endswith(".json"):
+                filename += ".json"
+
+            # Save file to disk (if output_directory is set)
+            file_path = self._save_file_to_disk(json_content, filename)
+
+            # Create FileArtifact
+            file_artifact = File(
+                id=str(uuid4()),
+                content=json_content,
+                mime_type="application/json",
+                file_type="json",
+                filename=filename,
+                size=len(json_content.encode("utf-8")),
+                filepath=file_path if file_path else None,
+            )
+
+            log_debug("JSON file generated successfully")
+            success_msg = f"JSON file '{filename}' has been generated successfully with {len(json_content)} characters."
+            if file_path:
+                success_msg += f" File saved to: {file_path}"
+            else:
+                success_msg += " File is available in response."
+
+            return ToolResult(content=success_msg, files=[file_artifact])
+
+        except Exception as e:
+            logger.error(f"Failed to generate JSON file: {e}")
+            return ToolResult(content=f"Error generating JSON file: {e}")
+
+    def generate_csv_file(
+        self,
+        data: Union[List[List], List[Dict], str],
+        filename: Optional[str] = None,
+        headers: Optional[List[str]] = None,
+    ) -> ToolResult:
+        """Generate a CSV file from the provided data.
+
+        Args:
+            data: The data to write to the CSV file. Can be a list of lists, list of dictionaries, or CSV string.
+            filename: Optional filename for the generated file. If not provided, a UUID will be used.
+            headers: Optional headers for the CSV. Used when data is a list of lists.
+
+        Returns:
+            ToolResult: Result containing the generated CSV file as a FileArtifact.
+        """
+        try:
+            log_debug(f"Generating CSV file with data: {type(data)}")
+
+            # Create CSV content
+            output = io.StringIO()
+
+            if isinstance(data, str):
+                # If it's already a CSV string, use it directly
+                csv_content = data
+            elif isinstance(data, list) and len(data) > 0:
+                writer = csv.writer(output)
+
+                if isinstance(data[0], dict):
+                    # List of dictionaries - use keys as headers
+                    if data:
+                        fieldnames = list(data[0].keys())
+                        writer.writerow(fieldnames)
+                        for row in data:
+                            if isinstance(row, dict):
+                                writer.writerow([row.get(field, "") for field in fieldnames])
+                            else:
+                                writer.writerow([str(row)] + [""] * (len(fieldnames) - 1))
+                elif isinstance(data[0], list):
+                    # List of lists
+                    if headers:
+                        writer.writerow(headers)
+                    writer.writerows(data)
+                else:
+                    # List of other types
+                    if headers:
+                        writer.writerow(headers)
+                    for item in data:
+                        writer.writerow([str(item)])
+
+                csv_content = output.getvalue()
+            else:
+                csv_content = ""
+
+            # Generate filename if not provided
+            if not filename:
+                filename = f"generated_file_{str(uuid4())[:8]}.csv"
+            elif not filename.endswith(".csv"):
+                filename += ".csv"
+
+            # Save file to disk (if output_directory is set)
+            file_path = self._save_file_to_disk(csv_content, filename)
+
+            # Create FileArtifact
+            file_artifact = File(
+                id=str(uuid4()),
+                content=csv_content,
+                mime_type="text/csv",
+                file_type="csv",
+                filename=filename,
+                size=len(csv_content.encode("utf-8")),
+                filepath=file_path if file_path else None,
+            )
+
+            log_debug("CSV file generated successfully")
+            success_msg = f"CSV file '{filename}' has been generated successfully with {len(csv_content)} characters."
+            if file_path:
+                success_msg += f" File saved to: {file_path}"
+            else:
+                success_msg += " File is available in response."
+
+            return ToolResult(content=success_msg, files=[file_artifact])
+
+        except Exception as e:
+            logger.error(f"Failed to generate CSV file: {e}")
+            return ToolResult(content=f"Error generating CSV file: {e}")
+
+    def generate_pdf_file(
+        self, content: str, filename: Optional[str] = None, title: Optional[str] = None
+    ) -> ToolResult:
+        """Generate a PDF file from the provided content.
+
+        Args:
+            content: The text content to write to the PDF file.
+            filename: Optional filename for the generated file. If not provided, a UUID will be used.
+            title: Optional title for the PDF document.
+
+        Returns:
+            ToolResult: Result containing the generated PDF file as a FileArtifact.
+        """
+        if not PDF_AVAILABLE:
+            return ToolResult(
+                content="PDF generation is not available. Please install reportlab: pip install reportlab"
+            )
+
+        try:
+            log_debug(f"Generating PDF file with content length: {len(content)}")
+
+            # Create PDF content in memory
+            buffer = io.BytesIO()
+            doc = SimpleDocTemplate(buffer, pagesize=letter, topMargin=1 * inch)
+
+            # Get styles
+            styles = getSampleStyleSheet()
+            title_style = styles["Title"]
+            normal_style = styles["Normal"]
+
+            # Build story (content elements)
+            story = []
+
+            if title:
+                story.append(Paragraph(title, title_style))
+                story.append(Spacer(1, 20))
+
+            # Split content into paragraphs and add to story
+            paragraphs = content.split("\n\n")
+            for para in paragraphs:
+                if para.strip():
+                    # Clean the paragraph text for PDF
+                    clean_para = para.strip().replace("<", "&lt;").replace(">", "&gt;")
+                    story.append(Paragraph(clean_para, normal_style))
+                    story.append(Spacer(1, 10))
+
+            # Build PDF
+            doc.build(story)
+            pdf_content = buffer.getvalue()
+            buffer.close()
+
+            # Generate filename if not provided
+            if not filename:
+                filename = f"generated_file_{str(uuid4())[:8]}.pdf"
+            elif not filename.endswith(".pdf"):
+                filename += ".pdf"
+
+            # Save file to disk (if output_directory is set)
+            file_path = self._save_file_to_disk(pdf_content, filename)
+
+            # Create FileArtifact
+            file_artifact = File(
+                id=str(uuid4()),
+                content=pdf_content,
+                mime_type="application/pdf",
+                file_type="pdf",
+                filename=filename,
+                size=len(pdf_content),
+                filepath=file_path if file_path else None,
+            )
+
+            log_debug("PDF file generated successfully")
+            success_msg = f"PDF file '{filename}' has been generated successfully with {len(pdf_content)} bytes."
+            if file_path:
+                success_msg += f" File saved to: {file_path}"
+            else:
+                success_msg += " File is available in response."
+
+            return ToolResult(content=success_msg, files=[file_artifact])
+
+        except Exception as e:
+            logger.error(f"Failed to generate PDF file: {e}")
+            return ToolResult(content=f"Error generating PDF file: {e}")
+
+    def generate_text_file(self, content: str, filename: Optional[str] = None) -> ToolResult:
+        """Generate a text file from the provided content.
+
+        Args:
+            content: The text content to write to the file.
+            filename: Optional filename for the generated file. If not provided, a UUID will be used.
+
+        Returns:
+            ToolResult: Result containing the generated text file as a FileArtifact.
+        """
+        try:
+            log_debug(f"Generating text file with content length: {len(content)}")
+
+            # Generate filename if not provided
+            if not filename:
+                filename = f"generated_file_{str(uuid4())[:8]}.txt"
+            elif not filename.endswith(".txt"):
+                filename += ".txt"
+
+            # Save file to disk (if output_directory is set)
+            file_path = self._save_file_to_disk(content, filename)
+
+            # Create FileArtifact
+            file_artifact = File(
+                id=str(uuid4()),
+                content=content,
+                mime_type="text/plain",
+                file_type="txt",
+                filename=filename,
+                size=len(content.encode("utf-8")),
+                filepath=file_path if file_path else None,
+            )
+
+            log_debug("Text file generated successfully")
+            success_msg = f"Text file '{filename}' has been generated successfully with {len(content)} characters."
+            if file_path:
+                success_msg += f" File saved to: {file_path}"
+            else:
+                success_msg += " File is available in response."
+
+            return ToolResult(content=success_msg, files=[file_artifact])
+
+        except Exception as e:
+            logger.error(f"Failed to generate text file: {e}")
+            return ToolResult(content=f"Error generating text file: {e}")

agno/tools/firecrawl.py

@@ -3,7 +3,7 @@ from os import getenv
 from typing import Any, Dict, List, Optional
 
 from agno.tools import Toolkit
-from agno.utils.log import logger
+from agno.utils.log import log_error
 
 try:
     from firecrawl import FirecrawlApp  # type: ignore[attr-defined]
@@ -57,7 +57,7 @@ class FirecrawlTools(Toolkit):
     ):
         self.api_key: Optional[str] = api_key or getenv("FIRECRAWL_API_KEY")
         if not self.api_key:
-            logger.error("FIRECRAWL_API_KEY not set. Please set the FIRECRAWL_API_KEY environment variable.")
+            log_error("FIRECRAWL_API_KEY not set. Please set the FIRECRAWL_API_KEY environment variable.")
 
         self.formats: Optional[List[str]] = formats
         self.limit: int = limit
@@ -73,7 +73,7 @@ class FirecrawlTools(Toolkit):
         if all or enable_mapping:
             tools.append(self.map_website)
         if all or enable_search:
-            tools.append(self.search)
+            tools.append(self.search_web)
 
         super().__init__(name="firecrawl_tools", tools=tools, **kwargs)
 
@@ -121,7 +121,7 @@ class FirecrawlTools(Toolkit):
         map_result = self.app.map(url)
         return json.dumps(map_result.model_dump(), cls=CustomJSONEncoder)
 
-    def search(self, query: str, limit: Optional[int] = None):
+    def search_web(self, query: str, limit: Optional[int] = None):
         """Use this function to search for the web using Firecrawl.
 
         Args: