class FileSearchToolsMixin:
"""
Mixin providing shared file search and read operations.
Tools provided:
- search_file: Multi-phase intelligent file search
- search_directory: Directory search by name
- read_file: Type-aware file reading with analysis
- search_file_content: Grep-like content search
- write_file: Generic file writer
"""
@tool
def search_file(
file_pattern: str,
search_all_drives: bool = True,
file_types: str = None
) -> Dict[str, Any]:
"""
Search for files with intelligent 3-phase strategy.
Phase 0: Current working directory (deep, unlimited)
Phase 1: Common document locations (Documents, Downloads, Desktop)
Phase 2: All drives (Windows) or root (Unix)
Args:
file_pattern: Pattern to search (e.g., 'oil', '*.pdf')
search_all_drives: Search all drives on Windows (default: True)
file_types: Filter by extensions (e.g., 'pdf,docx')
Returns:
{
"status": "success",
"files": List[str], # Paths (max 10)
"file_list": List[{ # Formatted for display
"number": int,
"name": str,
"path": str,
"directory": str
}],
"count": int,
"search_context": "current_directory" | "common_locations" | "deep_search",
"display_message": str,
"user_instruction": str # If multiple found
}
"""
pass
@tool
def search_directory(
directory_name: str,
search_root: str = None,
max_depth: int = 4
) -> Dict[str, Any]:
"""
Search for directories by name.
Args:
directory_name: Directory name pattern
search_root: Root to start from (default: home)
max_depth: Max recursion depth (default: 4)
Returns:
{
"status": "success",
"directories": List[str], # Max 10
"count": int,
"message": str
}
"""
pass
@tool
def read_file(file_path: str) -> Dict[str, Any]:
"""
Read file with intelligent type-based analysis.
File Type Support:
- Python (.py): AST validation + symbol extraction (functions/classes)
- Markdown (.md): Headers + code blocks + links extraction
- Binary: Detection with size reporting
- Text: Raw content with line count
Args:
file_path: Path to file
Returns:
{
"status": "success",
"file_path": str,
"file_type": "python" | "markdown" | "binary" | str,
"content": str,
"line_count": int,
"size_bytes": int,
# Python-specific
"is_valid": bool,
"errors": List[str],
"symbols": List[{
"name": str,
"type": "function" | "class",
"line": int
}],
# Markdown-specific
"headers": List[str],
"code_blocks": List[{
"language": str,
"code": str
}],
"links": List[{
"text": str,
"url": str
}],
# Binary-specific
"is_binary": bool
}
"""
pass
@tool
def search_file_content(
pattern: str,
directory: str = ".",
file_pattern: str = None,
case_sensitive: bool = False
) -> Dict[str, Any]:
"""
Grep-like file content search.
Args:
pattern: Text pattern to find
directory: Where to search (default: current)
file_pattern: File glob filter (e.g., '*.py')
case_sensitive: Case sensitivity (default: False)
Returns:
{
"status": "success",
"pattern": str,
"matches": List[{
"file": str,
"line": int,
"content": str # Max 200 chars
}],
"total_matches": int, # Max 100
"files_searched": int,
"message": str
}
"""
pass
@tool
def write_file(
file_path: str,
content: str,
create_dirs: bool = True
) -> Dict[str, Any]:
"""
Write content to file.
Args:
file_path: Target path
content: File content
create_dirs: Create parent dirs (default: True)
Returns:
{
"status": "success",
"file_path": str,
"bytes_written": int,
"line_count": int
}
"""
pass