quantalogic 0.33.4__py3-none-any.whl → 0.40.0__py3-none-any.whl

quantalogic/tools/sql_query_tool.py

@@ -23,7 +23,7 @@ class SQLQueryTool(Tool):
             arg_type="string",
             description="The SQL query to execute",
             required=True,
-            example="SELECT * FROM customers WHERE country = 'France'"
+            example="SELECT * FROM customers WHERE country = 'France'",
         ),
         ToolArgument(
             name="start_row",
@@ -31,7 +31,7 @@ class SQLQueryTool(Tool):
             description="1-based starting row number for results",
             required=True,
             example="1",
-            default="1"
+            default="1",
         ),
         ToolArgument(
             name="end_row",
@@ -39,27 +39,27 @@ class SQLQueryTool(Tool):
             description="1-based ending row number for results",
             required=True,
             example="100",
-            default="100"
+            default="100",
         ),
     ]
     connection_string: str = Field(
         ...,
         description="SQLAlchemy-compatible database connection string",
-        example="postgresql://user:password@localhost/mydb"
+        example="postgresql://user:password@localhost/mydb",
     )
 
     def execute(self, query: str, start_row: Any, end_row: Any) -> str:
         """
         Executes a SQL query and returns formatted results.
-        
+
         Args:
             query: SQL query to execute
             start_row: 1-based starting row number (supports various numeric types)
             end_row: 1-based ending row number (supports various numeric types)
-            
+
         Returns:
             str: Markdown-formatted results with pagination metadata
-            
+
         Raises:
             ValueError: For invalid parameters or query errors
             RuntimeError: For database connection issues
@@ -68,7 +68,7 @@ class SQLQueryTool(Tool):
             # Convert and validate row numbers
             start = self._convert_row_number(start_row, "start_row")
             end = self._convert_row_number(end_row, "end_row")
-            
+
             if start > end:
                 raise ValueError(f"start_row ({start}) must be <= end_row ({end})")
 
@@ -83,23 +83,25 @@ class SQLQueryTool(Tool):
             total_rows = len(all_rows)
             actual_start = max(1, start)
             actual_end = min(end, total_rows)
-            
+
             if actual_start > total_rows:
                 return f"No results found (total rows: {total_rows})"
 
             # Slice results (convert to 0-based index)
-            displayed_rows = all_rows[actual_start-1:actual_end]
+            displayed_rows = all_rows[actual_start - 1 : actual_end]
 
             # Format results
             markdown = [
                 f"**Query Results:** `{actual_start}-{actual_end}` of `{total_rows}` rows",
-                self._format_table(columns, displayed_rows)
+                self._format_table(columns, displayed_rows),
             ]
 
             # Add pagination notice
             if actual_end < total_rows:
                 remaining = total_rows - actual_end
-                markdown.append(f"\n*Showing first {actual_end} rows - {remaining} more row{'s' if remaining > 1 else ''} available*")
+                markdown.append(
+                    f"\n*Showing first {actual_end} rows - {remaining} more row{'s' if remaining > 1 else ''} available*"
+                )
 
             return "\n".join(markdown)
 
@@ -125,10 +127,10 @@ class SQLQueryTool(Tool):
             converted = int(num)
             if converted != num:  # Check if float had decimal part
                 raise ValueError("Decimal values are not allowed for row numbers")
-                
+
             if converted <= 0:
                 raise ValueError(f"{field_name} must be a positive integer")
-                
+
             return converted
         except (ValueError, TypeError) as e:
             raise ValueError(f"Invalid value for {field_name}: {repr(value)}") from e
@@ -141,7 +143,7 @@ class SQLQueryTool(Tool):
         # Create header
         header = "| " + " | ".join(columns) + " |"
         separator = "| " + " | ".join(["---"] * len(columns)) + " |"
-        
+
         # Create rows with truncation
         body = []
         for row in rows:
@@ -155,7 +157,6 @@ class SQLQueryTool(Tool):
         return "\n".join([header, separator] + body)
 
 
-
 if __name__ == "__main__":
     from quantalogic.tools.utils.create_sample_database import create_sample_database
 
@@ -164,6 +165,3 @@ if __name__ == "__main__":
     tool = SQLQueryTool(connection_string="sqlite:///sample.db")
     print(tool.execute("select * from customers", 1, 10))
     print(tool.execute("select * from customers", 11, 20))
-     
-    
-    

quantalogic/tools/tool.py

@@ -4,6 +4,7 @@ This module provides base classes and data models for creating configurable tool
 with type-validated arguments and execution methods.
 """
 
+import asyncio  # Added for asynchronous support
 from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
@@ -129,9 +130,7 @@ class ToolDefinition(BaseModel):
                     value_info = f" (default: `{arg.default}`)"
 
                 parameters += (
-                    f"  - `{arg.name}`: "
-                    f"({required_status}{value_info})\n"
-                    f"    {arg.description or ''}\n"
+                    f"  - `{arg.name}`: " f"({required_status}{value_info})\n" f"    {arg.description or ''}\n"
                 )
             if len(parameters) > 0:
                 markdown += parameters + "\n\n"
@@ -164,9 +163,17 @@ class ToolDefinition(BaseModel):
         """
         properties_injectable = self.get_injectable_properties_in_execution()
 
-        return [
-            arg for arg in self.arguments if properties_injectable.get(arg.name) is None
-        ]
+        return [arg for arg in self.arguments if properties_injectable.get(arg.name) is None]
+
+    def get_injectable_properties_in_execution(self) -> dict[str, Any]:
+        """Get injectable properties excluding tool arguments.
+
+        Returns:
+            A dictionary of property names and values, excluding tool arguments and None values.
+        """
+        # This method is defined here in ToolDefinition and overridden in Tool
+        # For ToolDefinition, it returns an empty dict since it has no execution context yet
+        return {}
 
 
 class Tool(ToolDefinition):
@@ -200,33 +207,50 @@ class Tool(ToolDefinition):
     def execute(self, **kwargs) -> str:
         """Execute the tool with provided arguments.
 
+        If not implemented by a subclass, falls back to the asynchronous execute_async method.
+
         Args:
             **kwargs: Keyword arguments for tool execution.
 
-        Raises:
-            NotImplementedError: If the method is not implemented by a subclass.
+        Returns:
+            A string representing the result of tool execution.
+        """
+        # Check if execute is implemented in the subclass
+        if self.__class__.execute is Tool.execute:
+            # If not implemented, run the async version synchronously
+            return asyncio.run(self.async_execute(**kwargs))
+        raise NotImplementedError("This method should be implemented by subclasses.")
+
+    async def async_execute(self, **kwargs) -> str:
+        """Asynchronous version of execute.
+
+        By default, runs the synchronous execute method in a separate thread using asyncio.to_thread.
+        Subclasses can override this method to provide a native asynchronous implementation for
+        operations that benefit from async I/O (e.g., network requests).
+
+        Args:
+            **kwargs: Keyword arguments for tool execution.
 
         Returns:
             A string representing the result of tool execution.
         """
+        # Check if execute_async is implemented in the subclass
+        if self.__class__.async_execute is Tool.async_execute:
+            return await asyncio.to_thread(self.execute, **kwargs)
         raise NotImplementedError("This method should be implemented by subclasses.")
 
     def get_injectable_properties_in_execution(self) -> dict[str, Any]:
         """Get injectable properties excluding tool arguments.
-        
+
         Returns:
             A dictionary of property names and values, excluding tool arguments and None values.
         """
         # Get argument names from tool definition
         argument_names = {arg.name for arg in self.arguments}
-        
+
         # Get properties excluding arguments and filter out None values
         properties = self.get_properties(exclude=["arguments"])
-        return {
-            name: value 
-            for name, value in properties.items() 
-            if value is not None and name in argument_names
-        }
+        return {name: value for name, value in properties.items() if value is not None and name in argument_names}
 
 
 if __name__ == "__main__":

quantalogic/tools/unified_diff_tool.py

@@ -304,7 +304,7 @@ class UnifiedDiffTool(Tool):
 
     name: str = "unified_diff"
     description: str = "Applies a unified diff patch to update a file."
-    need_validation: bool = True
+    need_validation: bool = False
     lenient: bool = True
     tolerance: int = 5
     arguments: list[ToolArgument] = [

quantalogic/tools/utilities/csv_processor_tool.py

@@ -0,0 +1,234 @@
+"""Tool for processing CSV files with pandas."""
+
+from pathlib import Path
+from typing import Dict, List, Any
+import json
+import re
+
+import pandas as pd
+from loguru import logger
+
+from quantalogic.tools.tool import Tool, ToolArgument
+
+
+class CSVProcessorTool(Tool):
+    """Tool for reading, processing and writing CSV files."""
+
+    name: str = "csv_processor_tool"
+    description: str = """
+    Process CSV files with operations like:
+    - read: Display CSV content and info
+    - add_column: Add a new column with values
+    - update_column: Update existing column values
+    - process_rows: Process rows with custom conditions
+    - filter_rows: Filter rows based on conditions
+    - describe: Get statistical description of the data
+    """
+    need_validation: bool = False
+    arguments: list = [
+        ToolArgument(
+            name="input_path",
+            arg_type="string",
+            description="Path to the input CSV file",
+            required=True,
+            example="/path/to/input.csv",
+        ),
+        ToolArgument(
+            name="operation",
+            arg_type="string",
+            description="""Operation to perform:
+            - read: Display CSV content
+            - add_column: Add new column
+            - update_column: Update column values
+            - process_rows: Process specific rows
+            - filter_rows: Filter rows by condition
+            - describe: Get data statistics
+            """,
+            required=True,
+            example="read",
+        ),
+        ToolArgument(
+            name="column_name",
+            arg_type="string", 
+            description="Name of the column to add/update",
+            required=False,
+            example="description",
+            default="",
+        ),
+        ToolArgument(
+            name="column_value",
+            arg_type="string",
+            description="""Value for the column. Supports:
+            - Simple value: "some text"
+            - Template with variables: "User $name$ with email $email$"
+            - JSON format for complex operations: {"condition": "price > 100", "value": "premium"}
+            Variables in templates must be in $variable$ format and match column names.""",
+            required=False,
+            example="Hello $name$! Your email is $email$",
+            default="",
+        ),
+        ToolArgument(
+            name="output_path",
+            arg_type="string",
+            description="Path to save the processed CSV file. If not provided, will overwrite input file",
+            required=False,
+            example="/path/to/output.csv",
+            default="",
+        ),
+    ]
+
+    def _read_csv(self, df: pd.DataFrame) -> str:
+        """Display CSV content and information."""
+        info = {
+            "shape": df.shape,
+            "columns": df.columns.tolist(),
+            "data_types": df.dtypes.astype(str).to_dict(),
+            "preview": df.head().to_dict(orient="records"),
+            "total_rows": len(df),
+        }
+        return f"CSV Information:\n{json.dumps(info, indent=2)}"
+
+    def _parse_value(self, value: str) -> Dict[str, Any]:
+        """Parse the column_value string into a dictionary."""
+        if not value:
+            return {"value": ""}
+            
+        try:
+            # Try parsing as JSON first
+            return json.loads(value)
+        except json.JSONDecodeError:
+            # If not valid JSON, treat as template or simple value
+            return {"value": value, "is_template": bool(re.search(r'\$\w+\$', value))}
+
+    def _apply_template(self, template: str, row: pd.Series) -> str:
+        """Apply template replacing $variable$ with values from row."""
+        result = template
+        for match in re.finditer(r'\$(\w+)\$', template):
+            var_name = match.group(1)
+            if var_name in row.index:
+                value = str(row[var_name])
+                result = result.replace(f"${var_name}$", value)
+        return result
+
+    def _process_rows(self, df: pd.DataFrame, condition: Dict[str, Any]) -> pd.DataFrame:
+        """Process rows based on condition."""
+        try:
+            if "filter" in condition:
+                query = condition["filter"]
+                df = df.query(query)
+            
+            if "update" in condition:
+                updates = condition["update"]
+                for col, value in updates.items():
+                    if "filter" in condition:
+                        df.loc[df.eval(condition["filter"]), col] = value
+                    else:
+                        df[col] = value
+            
+            return df
+        except Exception as e:
+            logger.error(f"Error in _process_rows: {str(e)}")
+            raise
+
+    def execute(
+        self,
+        input_path: str,
+        operation: str,
+        column_name: str = "",
+        column_value: str = "",
+        output_path: str = "",
+    ) -> str:
+        """Process the CSV file according to specified operation."""
+        try:
+            input_path = Path(input_path)
+            if not input_path.exists():
+                return f"Error: Input file {input_path} does not exist"
+
+            logger.info(f"Reading CSV file: {input_path}")
+            df = pd.read_csv(input_path)
+            initial_shape = df.shape
+
+            if operation == "read":
+                return self._read_csv(df)
+                
+            elif operation == "describe":
+                stats = df.describe().to_dict()
+                return f"Statistical Description:\n{json.dumps(stats, indent=2)}"
+                
+            elif operation == "add_column":
+                if not column_name:
+                    return "Error: column_name is required for add_column operation"
+                if column_name in df.columns:
+                    return f"Error: Column {column_name} already exists"
+                    
+                value_dict = self._parse_value(column_value)
+                
+                if value_dict.get("is_template", False):
+                    # Handle template string with variables
+                    df[column_name] = df.apply(
+                        lambda row: self._apply_template(value_dict["value"], row),
+                        axis=1
+                    )
+                elif "formula" in value_dict:
+                    # Handle formula-based column addition
+                    df[column_name] = df.eval(value_dict["formula"])
+                else:
+                    # Handle static value
+                    df[column_name] = value_dict.get("value", "")
+                
+            elif operation == "update_column":
+                if not column_name:
+                    return "Error: column_name required for update_column"
+                if column_name not in df.columns:
+                    return f"Error: Column {column_name} does not exist"
+                    
+                value_dict = self._parse_value(column_value)
+                
+                if value_dict.get("is_template", False):
+                    # Handle template string with variables
+                    df[column_name] = df.apply(
+                        lambda row: self._apply_template(value_dict["value"], row),
+                        axis=1
+                    )
+                elif "condition" in value_dict:
+                    # Update based on condition
+                    mask = df.eval(value_dict["condition"])
+                    df.loc[mask, column_name] = value_dict.get("value", "")
+                else:
+                    # Update all rows
+                    df[column_name] = value_dict.get("value", "")
+                
+            elif operation == "process_rows" or operation == "filter_rows":
+                if not column_value:
+                    return f"Error: column_value with conditions required for {operation}"
+                conditions = self._parse_value(column_value)
+                df = self._process_rows(df, conditions)
+                
+            else:
+                return f"Error: Unknown operation {operation}"
+
+            # Save if output path provided or if data was modified
+            if operation != "read" and operation != "describe":
+                save_path = output_path if output_path else input_path
+                save_path = Path(save_path)
+                logger.info(f"Saving processed CSV to: {save_path}")
+                df.to_csv(save_path, index=False)
+                
+                return (
+                    f"Successfully processed CSV:\n"
+                    f"- Input shape: {initial_shape}\n"
+                    f"- Output shape: {df.shape}\n"
+                    f"- Operation: {operation}\n"
+                    f"- Saved to: {save_path}"
+                )
+            
+            return "Operation completed successfully"
+
+        except Exception as e:
+            logger.error(f"Error processing CSV: {str(e)}")
+            return f"Error processing CSV: {str(e)}"
+
+
+if __name__ == "__main__":
+    tool = CSVProcessorTool()
+    print(tool.to_markdown())

quantalogic/tools/utilities/download_file_tool.py

@@ -0,0 +1,179 @@
+"""Tool for preparing files or directories for download through the existing file server."""
+
+import os
+import shutil
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+from loguru import logger
+
+from quantalogic.tools.tool import Tool, ToolArgument
+
+
+class PrepareDownloadTool(Tool):
+    """Tool for preparing files or directories for download through the existing file server."""
+
+    name: str = "prepare_download_tool"
+    description: str = (
+        "Prepares a local file or directory for download. "
+        "If it's a directory, it will be zipped. "
+        "Returns an HTML link for downloading."
+    )
+    need_validation: bool = True
+    arguments: list = [
+        ToolArgument(
+            name="path",
+            arg_type="string",
+            description="The local path of the file or directory to prepare for download",
+            required=True,
+            example="/path/to/local/file.pdf",
+        ),
+        ToolArgument(
+            name="filename",
+            arg_type="string",
+            description="Optional custom filename for download. If not provided, uses original name.",
+            required=False,
+            example="custom_name.pdf",
+        ),
+        ToolArgument(
+            name="link_text",
+            arg_type="string",
+            description="Optional custom text for the download link. If not provided, uses a default.",
+            required=False,
+            example="Download Report",
+        ),
+    ]
+
+    def __init__(self, upload_dir: str = "/tmp/data", base_url: str = "http://localhost:8082"):
+        """Initialize the tool with upload directory path.
+        
+        Args:
+            upload_dir: Directory where files are served from. Defaults to /tmp/data.
+            base_url: Base URL of the server. Defaults to http://localhost:8082.
+        """
+        super().__init__()
+        self.upload_dir = upload_dir
+        self.base_url = base_url.rstrip('/')
+        # Ensure upload directory exists
+        os.makedirs(upload_dir, exist_ok=True)
+
+    def _zip_directory(self, dir_path: str, zip_path: str) -> None:
+        """Zip a directory.
+        
+        Args:
+            dir_path: Path to the directory to zip
+            zip_path: Path where to save the zip file
+        """
+        with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            base_path = os.path.basename(dir_path)
+            for root, _, files in os.walk(dir_path):
+                for file in files:
+                    file_path = os.path.join(root, file)
+                    arcname = os.path.relpath(file_path, os.path.dirname(dir_path))
+                    zipf.write(file_path, arcname)
+        logger.info(f"Directory zipped successfully: {zip_path}")
+
+    def _generate_html_link(self, url: str, text: str, filename: str) -> str:
+        """Generate an HTML link with custom styling.
+        
+        Args:
+            url: The download URL
+            text: Text to display in the link
+            filename: Name of the file (for logging)
+            
+        Returns:
+            HTML formatted link
+        """
+        # CSS styling for the download link
+        style = (
+            "color: #0066cc; "
+            "text-decoration: none; "
+            "padding: 8px 16px; "
+            "border: 1px solid #0066cc; "
+            "border-radius: 4px; "
+            "display: inline-block; "
+            "font-family: system-ui, -apple-system, sans-serif; "
+            "transition: all 0.2s;"
+        )
+        
+        hover_style = (
+            "background-color: #0066cc; "
+            "color: white; "
+            "cursor: pointer;"
+        )
+        
+        # Create the HTML link with embedded styles
+        html = f'''<a href="{url}" 
+            style="{style}" 
+            onmouseover="this.style.backgroundColor='#0066cc'; this.style.color='white';" 
+            onmouseout="this.style.backgroundColor='transparent'; this.style.color='#0066cc';" 
+            download="{filename}">{text}</a>'''
+            
+        return html
+
+    def execute(self, path: str, filename: str = None, link_text: str = None) -> str:
+        """Prepares a file or directory for download.
+
+        Args:
+            path: The local path of the file or directory to prepare.
+            filename: Optional custom filename for download.
+            link_text: Optional custom text for the download link.
+
+        Returns:
+            HTML link for downloading the file.
+
+        Raises:
+            Exception: If file operations fail.
+        """
+        try:
+            path = os.path.abspath(path)
+            
+            # Verify path exists
+            if not os.path.exists(path):
+                error_msg = f"Path not found: {path}"
+                logger.error(error_msg)
+                return error_msg
+
+            # Handle directory case - create zip file
+            if os.path.isdir(path):
+                source_name = os.path.basename(path)
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                zip_filename = filename or f"{source_name}_{timestamp}.zip"
+                if not zip_filename.endswith('.zip'):
+                    zip_filename += '.zip'
+                
+                zip_path = os.path.join(self.upload_dir, zip_filename)
+                self._zip_directory(path, zip_path)
+                target_path = zip_path
+                target_filename = zip_filename
+            else:
+                # Handle single file case
+                source_filename = os.path.basename(path)
+                target_filename = filename or source_filename
+                target_path = os.path.join(self.upload_dir, target_filename)
+                shutil.copy2(path, target_path)
+                logger.success(f"File copied to upload directory: {target_path}")
+
+            # Generate download URL
+            download_url = f"{self.base_url}/api/agent/download/{target_filename}"
+            
+            # Generate link text
+            if not link_text:
+                if os.path.isdir(path):
+                    link_text = f"Download {os.path.basename(path)} (ZIP)"
+                else:
+                    link_text = f"Download {os.path.basename(path)}"
+
+            # Generate and return HTML link
+            return self._generate_html_link(download_url, link_text, target_filename)
+
+        except Exception as e:
+            error_msg = f"Error while preparing download: {str(e)}"
+            logger.error(error_msg)
+            return error_msg
+
+
+if __name__ == "__main__":
+    tool = PrepareDownloadTool()
+    print(tool.to_markdown())