pomera-ai-commander 0.1.0

package/tools/tool_loader.py

@@ -0,0 +1,710 @@
+"""
+Tool Loader - Centralized tool registration and lazy loading.
+
+This module replaces the 38+ try/except import blocks in pomera.py with a cleaner
+registry-based approach that supports lazy loading.
+
+Author: Pomera AI Commander Team
+"""
+
+import importlib
+import logging
+from typing import Dict, Any, Optional, Callable, Type, List, Tuple
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCategory(Enum):
+    """Tool categories for organization."""
+    CORE = "Core Tools"
+    AI = "AI Tools"
+    EXTRACTION = "Extraction Tools"
+    CONVERSION = "Conversion Tools"
+    TEXT_MANIPULATION = "Text Manipulation"
+    GENERATORS = "Generators"
+    ANALYSIS = "Analysis Tools"
+    UTILITY = "Utility Tools"
+    MCP = "MCP Tools"
+
+
+@dataclass
+class ToolSpec:
+    """
+    Specification for a loadable tool.
+    
+    Attributes:
+        name: Display name of the tool (used in UI)
+        module_path: Python module path (e.g., "tools.case_tool")
+        class_name: Name of the class to import (e.g., "CaseTool")
+        category: Tool category for organization
+        widget_class: Optional separate widget class name
+        dependencies: Optional list of required pip packages
+        description: Tool description for UI/help
+        is_widget: True if the class is a full widget (not just a tool class)
+        available_flag: Legacy flag name for backwards compatibility
+    """
+    name: str
+    module_path: str
+    class_name: str
+    category: ToolCategory = ToolCategory.UTILITY
+    widget_class: Optional[str] = None
+    dependencies: List[str] = field(default_factory=list)
+    description: str = ""
+    is_widget: bool = False
+    available_flag: str = ""  # e.g., "CASE_TOOL_MODULE_AVAILABLE"
+
+
+# Complete tool specifications registry
+TOOL_SPECS: Dict[str, ToolSpec] = {
+    # Core Tools
+    "Case Tool": ToolSpec(
+        name="Case Tool",
+        module_path="tools.case_tool",
+        class_name="CaseTool",
+        category=ToolCategory.CORE,
+        description="Transform text case (uppercase, lowercase, title case, etc.)",
+        available_flag="CASE_TOOL_MODULE_AVAILABLE"
+    ),
+    "Find & Replace": ToolSpec(
+        name="Find & Replace",
+        module_path="tools.find_replace",
+        class_name="FindReplaceWidget",
+        category=ToolCategory.CORE,
+        is_widget=True,
+        description="Find and replace text with regex support",
+        available_flag="FIND_REPLACE_MODULE_AVAILABLE"
+    ),
+    "Diff Viewer": ToolSpec(
+        name="Diff Viewer",
+        module_path="tools.diff_viewer",
+        class_name="DiffViewerWidget",
+        widget_class="DiffViewerSettingsWidget",
+        category=ToolCategory.CORE,
+        is_widget=True,
+        description="Compare and view differences between texts",
+        available_flag="DIFF_VIEWER_MODULE_AVAILABLE"
+    ),
+    
+    # AI Tools
+    "AI Tools": ToolSpec(
+        name="AI Tools",
+        module_path="tools.ai_tools",
+        class_name="AIToolsWidget",
+        category=ToolCategory.AI,
+        is_widget=True,
+        description="AI-powered text processing with multiple providers",
+        available_flag="AI_TOOLS_AVAILABLE"
+    ),
+    
+    # Extraction Tools
+    "Email Extraction": ToolSpec(
+        name="Email Extraction",
+        module_path="tools.email_extraction_tool",
+        class_name="EmailExtractionTool",
+        category=ToolCategory.EXTRACTION,
+        description="Extract email addresses from text",
+        available_flag="EMAIL_EXTRACTION_MODULE_AVAILABLE"
+    ),
+    "Email Header Analyzer": ToolSpec(
+        name="Email Header Analyzer",
+        module_path="tools.email_header_analyzer",
+        class_name="EmailHeaderAnalyzer",
+        category=ToolCategory.EXTRACTION,
+        description="Analyze email headers for routing and authentication info",
+        available_flag="EMAIL_HEADER_ANALYZER_MODULE_AVAILABLE"
+    ),
+    "URL Link Extractor": ToolSpec(
+        name="URL Link Extractor",
+        module_path="tools.url_link_extractor",
+        class_name="URLLinkExtractor",
+        category=ToolCategory.EXTRACTION,
+        description="Extract URLs and links from text",
+        available_flag="URL_LINK_EXTRACTOR_MODULE_AVAILABLE"
+    ),
+    "Regex Extractor": ToolSpec(
+        name="Regex Extractor",
+        module_path="tools.regex_extractor",
+        class_name="RegexExtractor",
+        category=ToolCategory.EXTRACTION,
+        description="Extract text patterns using regular expressions",
+        available_flag="REGEX_EXTRACTOR_MODULE_AVAILABLE"
+    ),
+    "URL Parser": ToolSpec(
+        name="URL Parser",
+        module_path="tools.url_parser",
+        class_name="URLParser",
+        category=ToolCategory.EXTRACTION,
+        description="Parse and analyze URL components",
+        available_flag="URL_PARSER_MODULE_AVAILABLE"
+    ),
+    "HTML Tool": ToolSpec(
+        name="HTML Tool",
+        module_path="tools.html_tool",
+        class_name="HTMLExtractionTool",
+        category=ToolCategory.EXTRACTION,
+        description="Extract content from HTML",
+        available_flag="HTML_EXTRACTION_TOOL_MODULE_AVAILABLE"
+    ),
+    "Extraction Tools": ToolSpec(
+        name="Extraction Tools",
+        module_path="tools.extraction_tools",
+        class_name="ExtractionTools",
+        category=ToolCategory.EXTRACTION,
+        description="General purpose extraction utilities",
+        available_flag="EXTRACTION_TOOLS_MODULE_AVAILABLE"
+    ),
+    
+    # Conversion Tools
+    "Base64 Tools": ToolSpec(
+        name="Base64 Tools",
+        module_path="tools.base64_tools",
+        class_name="Base64Tools",
+        widget_class="Base64ToolsWidget",
+        category=ToolCategory.CONVERSION,
+        description="Encode and decode Base64",
+        available_flag="BASE64_TOOLS_MODULE_AVAILABLE"
+    ),
+    "JSON/XML Tool": ToolSpec(
+        name="JSON/XML Tool",
+        module_path="tools.jsonxml_tool",
+        class_name="JSONXMLTool",
+        category=ToolCategory.CONVERSION,
+        description="Convert between JSON and XML formats",
+        available_flag="JSONXML_TOOL_MODULE_AVAILABLE"
+    ),
+    "Hash Generator": ToolSpec(
+        name="Hash Generator",
+        module_path="tools.hash_generator",
+        class_name="HashGenerator",
+        category=ToolCategory.CONVERSION,
+        description="Generate MD5, SHA1, SHA256 and other hashes",
+        available_flag="HASH_GENERATOR_MODULE_AVAILABLE"
+    ),
+    "Number Base Converter": ToolSpec(
+        name="Number Base Converter",
+        module_path="tools.number_base_converter",
+        class_name="NumberBaseConverter",
+        category=ToolCategory.CONVERSION,
+        description="Convert numbers between binary, octal, decimal, hex",
+        available_flag="NUMBER_BASE_CONVERTER_MODULE_AVAILABLE"
+    ),
+    "Timestamp Converter": ToolSpec(
+        name="Timestamp Converter",
+        module_path="tools.timestamp_converter",
+        class_name="TimestampConverter",
+        category=ToolCategory.CONVERSION,
+        description="Convert between timestamp formats",
+        available_flag="TIMESTAMP_CONVERTER_MODULE_AVAILABLE"
+    ),
+    "String Escape Tool": ToolSpec(
+        name="String Escape Tool",
+        module_path="tools.string_escape_tool",
+        class_name="StringEscapeTool",
+        category=ToolCategory.CONVERSION,
+        description="Escape/unescape strings for various formats",
+        available_flag="STRING_ESCAPE_TOOL_MODULE_AVAILABLE"
+    ),
+    
+    # Text Manipulation Tools
+    "Sorter Tools": ToolSpec(
+        name="Sorter Tools",
+        module_path="tools.sorter_tools",
+        class_name="SorterTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Sort lines alphabetically or numerically",
+        available_flag="SORTER_TOOLS_MODULE_AVAILABLE"
+    ),
+    "Line Tools": ToolSpec(
+        name="Line Tools",
+        module_path="tools.line_tools",
+        class_name="LineTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Line manipulation (remove duplicates, number lines, etc.)",
+        available_flag="LINE_TOOLS_MODULE_AVAILABLE"
+    ),
+    "Whitespace Tools": ToolSpec(
+        name="Whitespace Tools",
+        module_path="tools.whitespace_tools",
+        class_name="WhitespaceTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Trim, normalize whitespace and line endings",
+        available_flag="WHITESPACE_TOOLS_MODULE_AVAILABLE"
+    ),
+    "Column Tools": ToolSpec(
+        name="Column Tools",
+        module_path="tools.column_tools",
+        class_name="ColumnTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="CSV and column manipulation",
+        available_flag="COLUMN_TOOLS_MODULE_AVAILABLE"
+    ),
+    "Text Wrapper": ToolSpec(
+        name="Text Wrapper",
+        module_path="tools.text_wrapper",
+        class_name="TextWrapper",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Wrap text to specified width",
+        available_flag="TEXT_WRAPPER_MODULE_AVAILABLE"
+    ),
+    "Markdown Tools": ToolSpec(
+        name="Markdown Tools",
+        module_path="tools.markdown_tools",
+        class_name="MarkdownTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Process and extract from Markdown",
+        available_flag="MARKDOWN_TOOLS_MODULE_AVAILABLE"
+    ),
+    "Slug Generator": ToolSpec(
+        name="Slug Generator",
+        module_path="tools.slug_generator",
+        class_name="SlugGenerator",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Generate URL-friendly slugs",
+        available_flag="SLUG_GENERATOR_MODULE_AVAILABLE"
+    ),
+    "Translator Tools": ToolSpec(
+        name="Translator Tools",
+        module_path="tools.translator_tools",
+        class_name="TranslatorTools",
+        category=ToolCategory.TEXT_MANIPULATION,
+        description="Translate to/from Morse code and binary",
+        available_flag="TRANSLATOR_TOOLS_MODULE_AVAILABLE"
+    ),
+    
+    # Generator Tools
+    "Generator Tools": ToolSpec(
+        name="Generator Tools",
+        module_path="tools.generator_tools",
+        class_name="GeneratorTools",
+        widget_class="GeneratorToolsWidget",
+        category=ToolCategory.GENERATORS,
+        description="Generate passwords, UUIDs, Lorem Ipsum",
+        available_flag="GENERATOR_TOOLS_MODULE_AVAILABLE"
+    ),
+    "ASCII Art Generator": ToolSpec(
+        name="ASCII Art Generator",
+        module_path="tools.ascii_art_generator",
+        class_name="ASCIIArtGenerator",
+        category=ToolCategory.GENERATORS,
+        description="Generate ASCII art from text",
+        available_flag="ASCII_ART_GENERATOR_MODULE_AVAILABLE"
+    ),
+    
+    # Analysis Tools
+    "Word Frequency Counter": ToolSpec(
+        name="Word Frequency Counter",
+        module_path="tools.word_frequency_counter",
+        class_name="WordFrequencyCounter",
+        category=ToolCategory.ANALYSIS,
+        description="Count word frequencies in text",
+        available_flag="WORD_FREQUENCY_COUNTER_MODULE_AVAILABLE"
+    ),
+    "Text Statistics": ToolSpec(
+        name="Text Statistics",
+        module_path="tools.text_statistics_tool",
+        class_name="TextStatistics",
+        category=ToolCategory.ANALYSIS,
+        description="Calculate text statistics (chars, words, lines)",
+        available_flag="TEXT_STATISTICS_MODULE_AVAILABLE"
+    ),
+    "Cron Tool": ToolSpec(
+        name="Cron Tool",
+        module_path="tools.cron_tool",
+        class_name="CronTool",
+        category=ToolCategory.ANALYSIS,
+        description="Parse and explain cron expressions",
+        available_flag="CRON_TOOL_MODULE_AVAILABLE"
+    ),
+    
+    # Utility Tools
+    "cURL Tool": ToolSpec(
+        name="cURL Tool",
+        module_path="tools.curl_tool",
+        class_name="CurlToolWidget",
+        category=ToolCategory.UTILITY,
+        is_widget=True,
+        description="Make HTTP requests",
+        available_flag="CURL_TOOL_MODULE_AVAILABLE"
+    ),
+    "List Comparator": ToolSpec(
+        name="List Comparator",
+        module_path="tools.list_comparator",
+        class_name="DiffApp",
+        category=ToolCategory.UTILITY,
+        description="Compare two lists and find differences",
+        available_flag="LIST_COMPARATOR_MODULE_AVAILABLE"
+    ),
+    "Notes Widget": ToolSpec(
+        name="Notes Widget",
+        module_path="tools.notes_widget",
+        class_name="NotesWidget",
+        category=ToolCategory.UTILITY,
+        is_widget=True,
+        description="Save and manage notes",
+        available_flag="NOTES_WIDGET_MODULE_AVAILABLE"
+    ),
+    "Folder File Reporter": ToolSpec(
+        name="Folder File Reporter",
+        module_path="tools.folder_file_reporter_adapter",
+        class_name="FolderFileReporterAdapter",
+        category=ToolCategory.UTILITY,
+        description="Generate reports of folder contents",
+        available_flag="FOLDER_FILE_REPORTER_MODULE_AVAILABLE"
+    ),
+    
+    # MCP Tools
+    "MCP Manager": ToolSpec(
+        name="MCP Manager",
+        module_path="tools.mcp_widget",
+        class_name="MCPManager",
+        category=ToolCategory.MCP,
+        is_widget=True,
+        description="Model Context Protocol server management",
+        available_flag="MCP_WIDGET_MODULE_AVAILABLE"
+    ),
+}
+
+
+class ToolLoader:
+    """
+    Centralized tool loading with lazy initialization.
+    
+    Benefits:
+    - Single place to manage all tool imports
+    - Lazy loading - tools only loaded when first accessed
+    - Clean availability checking
+    - Reduces startup time
+    - Caches loaded modules and classes
+    
+    Usage:
+        loader = get_tool_loader()
+        
+        # Check if tool is available
+        if loader.is_available("Case Tool"):
+            # Get the tool class
+            CaseTool = loader.get_tool_class("Case Tool")
+            tool = CaseTool()
+            
+        # Or create instance directly
+        tool = loader.create_instance("Case Tool")
+        
+        # Get all available tools
+        available = loader.get_available_tools()
+    """
+    
+    def __init__(self, tool_specs: Optional[Dict[str, ToolSpec]] = None):
+        """
+        Initialize the tool loader.
+        
+        Args:
+            tool_specs: Optional custom tool specifications (uses TOOL_SPECS if None)
+        """
+        self._specs = tool_specs or TOOL_SPECS.copy()
+        self._loaded_modules: Dict[str, Any] = {}
+        self._loaded_classes: Dict[str, Type] = {}
+        self._availability_cache: Dict[str, bool] = {}
+        self._load_errors: Dict[str, str] = {}
+        self._widget_classes: Dict[str, Type] = {}
+    
+    def register_tool(self, spec: ToolSpec) -> None:
+        """
+        Register a new tool specification.
+        
+        Args:
+            spec: Tool specification to register
+        """
+        self._specs[spec.name] = spec
+        # Clear caches for this tool
+        self._availability_cache.pop(spec.name, None)
+        self._loaded_classes.pop(spec.name, None)
+        self._load_errors.pop(spec.name, None)
+        logger.debug(f"Registered tool: {spec.name}")
+    
+    def unregister_tool(self, name: str) -> bool:
+        """
+        Unregister a tool.
+        
+        Args:
+            name: Tool name to unregister
+            
+        Returns:
+            True if tool was found and removed
+        """
+        if name in self._specs:
+            del self._specs[name]
+            self._availability_cache.pop(name, None)
+            self._loaded_classes.pop(name, None)
+            self._load_errors.pop(name, None)
+            return True
+        return False
+    
+    def is_available(self, tool_name: str) -> bool:
+        """
+        Check if a tool is available (can be imported).
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            True if tool module can be imported
+        """
+        if tool_name in self._availability_cache:
+            return self._availability_cache[tool_name]
+        
+        if tool_name not in self._specs:
+            self._availability_cache[tool_name] = False
+            return False
+        
+        spec = self._specs[tool_name]
+        try:
+            importlib.import_module(spec.module_path)
+            self._availability_cache[tool_name] = True
+            return True
+        except ImportError as e:
+            self._availability_cache[tool_name] = False
+            self._load_errors[tool_name] = str(e)
+            logger.debug(f"Tool '{tool_name}' not available: {e}")
+            return False
+    
+    def get_tool_class(self, tool_name: str) -> Optional[Type]:
+        """
+        Get the tool class (lazy loaded).
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            The tool class, or None if not available
+        """
+        if tool_name in self._loaded_classes:
+            return self._loaded_classes[tool_name]
+        
+        if not self.is_available(tool_name):
+            return None
+        
+        spec = self._specs[tool_name]
+        try:
+            module = self._get_module(spec.module_path)
+            tool_class = getattr(module, spec.class_name)
+            self._loaded_classes[tool_name] = tool_class
+            logger.info(f"Loaded tool class: {tool_name}")
+            return tool_class
+        except (ImportError, AttributeError) as e:
+            self._load_errors[tool_name] = str(e)
+            logger.error(f"Failed to load tool class '{tool_name}': {e}")
+            return None
+    
+    def get_widget_class(self, tool_name: str) -> Optional[Type]:
+        """
+        Get the widget class for a tool (if it has a separate one).
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            The widget class, or None if not available
+        """
+        if tool_name in self._widget_classes:
+            return self._widget_classes[tool_name]
+        
+        if tool_name not in self._specs:
+            return None
+        
+        spec = self._specs[tool_name]
+        
+        # If no separate widget class, return the main class
+        if not spec.widget_class:
+            return self.get_tool_class(tool_name)
+        
+        try:
+            module = self._get_module(spec.module_path)
+            widget_class = getattr(module, spec.widget_class)
+            self._widget_classes[tool_name] = widget_class
+            return widget_class
+        except (ImportError, AttributeError) as e:
+            logger.error(f"Failed to load widget class for '{tool_name}': {e}")
+            return None
+    
+    def create_instance(self, tool_name: str, *args, **kwargs) -> Optional[Any]:
+        """
+        Create an instance of a tool.
+        
+        Args:
+            tool_name: Name of the tool
+            *args, **kwargs: Arguments to pass to the constructor
+            
+        Returns:
+            Tool instance, or None if not available
+        """
+        tool_class = self.get_tool_class(tool_name)
+        if tool_class is None:
+            return None
+        
+        try:
+            return tool_class(*args, **kwargs)
+        except Exception as e:
+            logger.error(f"Failed to instantiate tool '{tool_name}': {e}")
+            return None
+    
+    def _get_module(self, module_path: str) -> Any:
+        """Get a module (cached)."""
+        if module_path not in self._loaded_modules:
+            self._loaded_modules[module_path] = importlib.import_module(module_path)
+        return self._loaded_modules[module_path]
+    
+    def get_available_tools(self) -> List[str]:
+        """
+        Get list of all available tool names.
+        
+        Returns:
+            List of tool names that can be loaded
+        """
+        return [name for name in self._specs.keys() if self.is_available(name)]
+    
+    def get_all_tool_names(self) -> List[str]:
+        """
+        Get list of all registered tool names.
+        
+        Returns:
+            List of all tool names (whether available or not)
+        """
+        return list(self._specs.keys())
+    
+    def get_tools_by_category(self, category: ToolCategory) -> List[str]:
+        """
+        Get tools in a specific category.
+        
+        Args:
+            category: Tool category
+            
+        Returns:
+            List of tool names in that category
+        """
+        return [
+            name for name, spec in self._specs.items()
+            if spec.category == category and self.is_available(name)
+        ]
+    
+    def get_tool_spec(self, tool_name: str) -> Optional[ToolSpec]:
+        """
+        Get the specification for a tool.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            ToolSpec or None if not found
+        """
+        return self._specs.get(tool_name)
+    
+    def get_load_error(self, tool_name: str) -> Optional[str]:
+        """
+        Get the error message if a tool failed to load.
+        
+        Args:
+            tool_name: Name of the tool
+            
+        Returns:
+            Error message, or None if no error
+        """
+        return self._load_errors.get(tool_name)
+    
+    def get_availability_report(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get a report of all tools and their availability.
+        
+        Returns:
+            Dictionary with tool availability information
+        """
+        report = {}
+        for name, spec in self._specs.items():
+            available = self.is_available(name)
+            report[name] = {
+                'available': available,
+                'category': spec.category.value,
+                'module': spec.module_path,
+                'class': spec.class_name,
+                'is_widget': spec.is_widget,
+                'error': self._load_errors.get(name) if not available else None
+            }
+        return report
+    
+    def preload_tools(self, tool_names: Optional[List[str]] = None) -> Dict[str, bool]:
+        """
+        Preload specified tools (or all if none specified).
+        
+        Args:
+            tool_names: List of tool names to preload, or None for all
+            
+        Returns:
+            Dictionary of tool names to load success status
+        """
+        names = tool_names or list(self._specs.keys())
+        results = {}
+        for name in names:
+            results[name] = self.get_tool_class(name) is not None
+        return results
+    
+    def clear_cache(self) -> None:
+        """Clear all cached modules and classes."""
+        self._loaded_modules.clear()
+        self._loaded_classes.clear()
+        self._availability_cache.clear()
+        self._load_errors.clear()
+        self._widget_classes.clear()
+        logger.debug("Tool loader cache cleared")
+    
+    def get_legacy_flags(self) -> Dict[str, bool]:
+        """
+        Get legacy availability flags for backwards compatibility.
+        
+        Returns:
+            Dictionary of flag names to boolean values
+        """
+        flags = {}
+        for name, spec in self._specs.items():
+            if spec.available_flag:
+                flags[spec.available_flag] = self.is_available(name)
+        return flags
+
+
+# Global instance
+_tool_loader: Optional[ToolLoader] = None
+
+
+def get_tool_loader() -> ToolLoader:
+    """
+    Get the global tool loader instance.
+    
+    Returns:
+        Global ToolLoader instance
+    """
+    global _tool_loader
+    if _tool_loader is None:
+        _tool_loader = ToolLoader()
+    return _tool_loader
+
+
+def init_tool_loader(tool_specs: Optional[Dict[str, ToolSpec]] = None) -> ToolLoader:
+    """
+    Initialize the global tool loader.
+    
+    Args:
+        tool_specs: Optional custom tool specifications
+        
+    Returns:
+        Initialized ToolLoader
+    """
+    global _tool_loader
+    _tool_loader = ToolLoader(tool_specs)
+    return _tool_loader
+
+
+def reset_tool_loader() -> None:
+    """Reset the global tool loader."""
+    global _tool_loader
+    _tool_loader = None
+