aiecs 1.0.1__py3-none-any.whl → 1.7.17__py3-none-any.whl

aiecs/tools/__init__.py

@@ -5,190 +5,312 @@ import inspect
 import logging
 import os
 import pkgutil
-from typing import Any, Dict, List, Optional, Type
+from typing import Dict, Any
 
 from aiecs.tools.base_tool import BaseTool
 
 logger = logging.getLogger(__name__)
 
-# 全局工具注册表
-TOOL_REGISTRY = {}
-TOOL_CLASSES = {}
-TOOL_CONFIGS = {}
+# Global tool registry
+TOOL_REGISTRY: Dict[str, Any] = {}
+TOOL_CLASSES: Dict[str, Any] = {}
+# TOOL_CONFIGS: Legacy configuration dictionary.
+# Values here are passed as explicit config to tools (highest precedence).
+# Prefer using YAML config files (config/tools/{tool_name}.yaml) or .env files instead.
+TOOL_CONFIGS: Dict[str, Any] = {}
+
 
 def register_tool(name):
     """
-    装饰器，用于注册工具类
+    Decorator for registering tool classes
 
     Args:
-        name: 工具名称
+        name: Tool name
 
     Returns:
-        装饰后的类
+        Decorated class
     """
+
     def wrapper(cls):
-        # 存储工具类，但不立即实例化
+        # Store tool class but don't instantiate immediately
         TOOL_CLASSES[name] = cls
-        # 兼容旧版本：如果类继承自BaseTool，则不立即实例化
+        # Backward compatibility: if class inherits from BaseTool, don't
+        # instantiate immediately
         if not issubclass(cls, BaseTool):
             TOOL_REGISTRY[name] = cls()
         return cls
+
     return wrapper
 
+
 def get_tool(name):
     """
-    获取工具实例
+    Get tool instance
 
     Args:
-        name: 工具名称
+        name: Tool name
 
     Returns:
-        工具实例
+        Tool instance
 
     Raises:
-        ValueError: 如果工具未注册
+        ValueError: If tool is not registered
     """
-    if name not in TOOL_REGISTRY and name in TOOL_CLASSES:
-        # 延迟实例化BaseTool子类
-        tool_class = TOOL_CLASSES[name]
-        config = TOOL_CONFIGS.get(name, {})
-        TOOL_REGISTRY[name] = tool_class(config)
+    # Check if placeholder needs to be replaced or lazy instantiation is needed
+    if name in TOOL_CLASSES:
+        # If TOOL_REGISTRY contains placeholder or doesn't exist, instantiate
+        # real tool class
+        current_tool = TOOL_REGISTRY.get(name)
+        is_placeholder = getattr(current_tool, "is_placeholder", False)
+
+        if current_tool is None or is_placeholder:
+            # Lazy instantiation of BaseTool subclasses, replace placeholder
+            # Configuration is loaded automatically by BaseTool using ToolConfigLoader:
+            # 1. TOOL_CONFIGS values (explicit config, highest precedence)
+            # 2. YAML config files (config/tools/{tool_name}.yaml or config/tools.yaml)
+            # 3. Environment variables (via dotenv from .env files)
+            # 4. Tool defaults (lowest priority)
+            tool_class = TOOL_CLASSES[name]
+            config = TOOL_CONFIGS.get(name, {})
+            # Pass tool name to BaseTool for config file discovery (used for YAML file lookup)
+            # Check if tool class accepts tool_name parameter (for backward compatibility)
+            sig = inspect.signature(tool_class.__init__)
+            if "tool_name" in sig.parameters or any(
+                p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+            ):
+                TOOL_REGISTRY[name] = tool_class(config=config, tool_name=name)
+            else:
+                # Tool class doesn't accept tool_name, only pass config
+                TOOL_REGISTRY[name] = tool_class(config=config)
+            logger.debug(f"Instantiated tool '{name}' from class {tool_class.__name__}")
 
     if name not in TOOL_REGISTRY:
         raise ValueError(f"Tool '{name}' is not registered")
 
     return TOOL_REGISTRY[name]
 
+
 def list_tools():
     """
-    列出所有已注册的工具
+    List all registered tools
 
     Returns:
-        工具信息字典列表
+        List of tool information dictionaries
     """
     tools = []
     all_tool_names = list(set(list(TOOL_REGISTRY.keys()) + list(TOOL_CLASSES.keys())))
-    
+
     for tool_name in all_tool_names:
         try:
-            # 优先使用已有实例的信息
+            # Prefer using information from existing instances
             if tool_name in TOOL_REGISTRY:
                 tool_instance = TOOL_REGISTRY[tool_name]
                 tool_info = {
                     "name": tool_name,
-                    "description": getattr(tool_instance, 'description', f'{tool_name} tool'),
-                    "category": getattr(tool_instance, 'category', 'general'),
+                    "description": getattr(tool_instance, "description", f"{tool_name} tool"),
+                    "category": getattr(tool_instance, "category", "general"),
                     "class_name": tool_instance.__class__.__name__,
                     "module": tool_instance.__class__.__module__,
-                    "status": "loaded"
+                    "status": "loaded",
                 }
             elif tool_name in TOOL_CLASSES:
-                # 从类定义获取信息，但不实例化
+                # Get information from class definition but don't instantiate
                 tool_class = TOOL_CLASSES[tool_name]
                 tool_info = {
                     "name": tool_name,
-                    "description": getattr(tool_class, 'description', f'{tool_name} tool'),
-                    "category": getattr(tool_class, 'category', 'general'),
+                    "description": getattr(tool_class, "description", f"{tool_name} tool"),
+                    "category": getattr(tool_class, "category", "general"),
                     "class_name": tool_class.__name__,
                     "module": tool_class.__module__,
-                    "status": "available"
+                    "status": "available",
                 }
             else:
                 continue
-            
+
             tools.append(tool_info)
-            
+
         except Exception as e:
             logger.warning(f"Failed to get info for tool {tool_name}: {e}")
-            # 提供基本信息
-            tools.append({
-                "name": tool_name,
-                "description": f"{tool_name} (info unavailable)",
-                "category": "unknown",
-                "class_name": "Unknown",
-                "module": "unknown",
-                "status": "error"
-            })
-    
+            # Provide basic information
+            tools.append(
+                {
+                    "name": tool_name,
+                    "description": f"{tool_name} (info unavailable)",
+                    "category": "unknown",
+                    "class_name": "Unknown",
+                    "module": "unknown",
+                    "status": "error",
+                }
+            )
+
     return tools
 
+
 def discover_tools(package_path: str = "aiecs.tools"):
     """
-    发现并注册包中的所有工具
+    Discover and register all tools in the package
 
     Args:
-        package_path: 要搜索的包路径
+        package_path: Package path to search
     """
     package = importlib.import_module(package_path)
+    if package.__file__ is None:
+        return
     package_dir = os.path.dirname(package.__file__)
 
     for _, module_name, is_pkg in pkgutil.iter_modules([package_dir]):
         if is_pkg:
-            # 递归搜索子包中的工具
+            # Recursively search for tools in subpackages
             discover_tools(f"{package_path}.{module_name}")
         else:
-            # 导入模块
+            # Import module
             try:
                 importlib.import_module(f"{package_path}.{module_name}")
             except Exception as e:
                 logger.error(f"Error importing module {module_name}: {e}")
 
-# 导入基础工具类供继承使用
-from aiecs.tools.base_tool import BaseTool
 
 # Lazy loading strategy: don't import all tools at package init
 # Tools will be loaded on-demand when requested
 
+
 def _ensure_task_tools_available():
     """Ensure task_tools module is available for lazy loading"""
     try:
-        from . import task_tools
         return True
     except ImportError as e:
         logger.error(f"Failed to import task_tools: {e}")
         return False
 
+
+def _auto_discover_tools():
+    """Automatically discover all tools by scanning tool directories"""
+    import re
+
+    # Define tool directories and their categories
+    tool_dirs = [
+        ("task_tools", "task"),
+        ("docs", "docs"),
+        ("statistics", "statistics"),
+        ("search_tool", "task"),  # Enhanced search tool
+        ("api_sources", "task"),  # API data sources (legacy)
+        ("apisource", "task"),  # API Source Tool (new modular version)
+    ]
+
+    discovered_tools = []
+
+    for dir_name, category in tool_dirs:
+        dir_path = os.path.join(os.path.dirname(__file__), dir_name)
+        if not os.path.exists(dir_path):
+            continue
+
+        # Check if this is a package (has __init__.py) or a directory of
+        # modules
+        init_file = os.path.join(dir_path, "__init__.py")
+        files_to_scan = []
+
+        if os.path.isfile(init_file):
+            # Scan __init__.py for package-level registrations
+            files_to_scan.append(("__init__.py", init_file))
+
+        # Scan all other Python files in the directory
+        for filename in os.listdir(dir_path):
+            if filename.endswith(".py") and not filename.startswith("__"):
+                file_path = os.path.join(dir_path, filename)
+                files_to_scan.append((filename, file_path))
+
+        # Process all files
+        for filename, file_path in files_to_scan:
+            try:
+                with open(file_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+
+                    # Find @register_tool decorators (two patterns)
+                    # Pattern 1: @register_tool("name") decorator syntax
+                    decorator_pattern = r'@register_tool\([\'"]([^\'"]+)[\'"]\)'
+                    decorator_matches = re.findall(decorator_pattern, content)
+
+                    # Pattern 2: register_tool("name")(ClassName) function call
+                    # syntax
+                    function_pattern = r'register_tool\([\'"]([^\'"]+)[\'"]\)\([A-Za-z_][A-Za-z0-9_]*\)'
+                    function_matches = re.findall(function_pattern, content)
+
+                    # Combine all matches
+                    all_matches = list(set(decorator_matches + function_matches))
+
+                    for tool_name in all_matches:
+                        # Try to extract description from class docstring or
+                        # module docstring
+                        description = f"{tool_name} tool"
+
+                        # Method 1: Look for class definition after the
+                        # decorator
+                        class_pattern = rf'@register_tool\([\'"]({tool_name})[\'"]\)\s*class\s+\w+.*?"""(.*?)"""'
+                        class_match = re.search(class_pattern, content, re.DOTALL)
+                        if class_match:
+                            doc = class_match.group(2).strip()
+                            # Get first line of docstring
+                            first_line = doc.split("\n")[0].strip()
+                            if first_line and len(first_line) < 200:
+                                description = first_line
+
+                        # Method 2: For __init__.py files, try to extract from
+                        # module docstring
+                        if not class_match and filename == "__init__.py":
+                            module_doc_pattern = r'^"""(.*?)"""'
+                            module_doc_match = re.search(
+                                module_doc_pattern,
+                                content,
+                                re.DOTALL | re.MULTILINE,
+                            )
+                            if module_doc_match:
+                                doc = module_doc_match.group(1).strip()
+                                # Get first non-empty line
+                                for line in doc.split("\n"):
+                                    line = line.strip()
+                                    if line and not line.startswith("#") and len(line) < 200:
+                                        description = line
+                                        break
+
+                        discovered_tools.append((tool_name, description, category))
+            except Exception as e:
+                logger.debug(f"Error scanning {filename}: {e}")
+
+    return discovered_tools
+
+
 def _register_known_tools():
     """Register known tools without importing heavy dependencies"""
-    # Pre-register tool classes for discovery without importing modules
-    # This allows list_tools() to work before actual tool loading
-    
-    known_tools = [
-        ("chart_tool", "Chart and visualization operations"),
-        ("classfire_tool", "Text classification and keyword extraction"),
-        ("image_tool", "Image processing and OCR operations"),
-        ("office_tool", "Office document processing"),
-        ("pandas_tool", "Data analysis and manipulation"), 
-        ("report_tool", "Report generation and formatting"),
-        ("research_tool", "Research and information gathering"),
-        ("scraper_tool", "Web scraping and data extraction"),
-        ("search_api", "Search API integration"),
-        ("stats_tool", "Statistical analysis and computation")
-    ]
-    
+    # Automatically discover all tools
+    discovered_tools = _auto_discover_tools()
+
+    logger.info(f"Auto-discovered {len(discovered_tools)} tools")
+
     # Register as placeholder until actually loaded
-    for tool_name, description in known_tools:
+    for tool_info in discovered_tools:
+        tool_name, description, category = tool_info
         if tool_name not in TOOL_REGISTRY and tool_name not in TOOL_CLASSES:
             # Create a placeholder class for discovery
             class ToolPlaceholder:
-                def __init__(self, name, desc):
+                def __init__(self, name, desc, cat):
                     self.name = name
                     self.description = desc
-                    self.category = "task"
+                    self.category = cat
                     self.is_placeholder = True
-            
-            TOOL_REGISTRY[tool_name] = ToolPlaceholder(tool_name, description)
+
+            TOOL_REGISTRY[tool_name] = ToolPlaceholder(tool_name, description, category)
+
 
 # Register known tools for discovery
 _register_known_tools()
 
 try:
-    from . import db_api
+    pass
 except ImportError:
     pass
 
 try:
-    from . import vector_search
+    pass
 except ImportError:
     pass
 

aiecs/tools/apisource/__init__.py

@@ -0,0 +1,99 @@
+"""
+APISource Tool - Unified API Data Source Interface
+
+A comprehensive tool for querying external API data sources with advanced features:
+- Multi-provider support (FRED, World Bank, News API, Census Bureau)
+- Intelligent query understanding and parameter enhancement
+- Cross-provider data fusion
+- Automatic fallback and retry logic
+- Advanced search with relevance ranking
+- Comprehensive metrics and health monitoring
+
+Usage:
+    from aiecs.tools.apisource import APISourceTool
+
+    tool = APISourceTool({
+        'fred_api_key': 'YOUR_KEY',
+        'enable_fallback': True,
+        'enable_query_enhancement': True
+    })
+
+    # Query with natural language
+    result = tool.query(
+        provider='fred',
+        operation='get_series_observations',
+        params={'series_id': 'GDP'},
+        query_text="Get GDP data for last 5 years"
+    )
+
+    # Multi-provider search with fusion
+    results = tool.search(
+        query="unemployment trends",
+        enable_fusion=True
+    )
+"""
+
+from aiecs.tools.apisource.tool import (
+    APISourceTool,
+    APISourceError,
+    ProviderNotFoundError,
+    APIRateLimitError,
+    APIAuthenticationError,
+)
+
+# Import providers for convenience
+from aiecs.tools.apisource.providers import (
+    BaseAPIProvider,
+    get_provider,
+    list_providers,
+    PROVIDER_REGISTRY,
+)
+
+# Import intelligence components
+from aiecs.tools.apisource.intelligence import (
+    QueryIntentAnalyzer,
+    QueryEnhancer,
+    DataFusionEngine,
+    SearchEnhancer,
+)
+
+# Import reliability components
+from aiecs.tools.apisource.reliability import (
+    SmartErrorHandler,
+    FallbackStrategy,
+)
+
+# Import monitoring components
+from aiecs.tools.apisource.monitoring import DetailedMetrics
+
+# Import utilities
+from aiecs.tools.apisource.utils import DataValidator
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # Main tool
+    "APISourceTool",
+    # Exceptions
+    "APISourceError",
+    "ProviderNotFoundError",
+    "APIRateLimitError",
+    "APIAuthenticationError",
+    # Providers
+    "BaseAPIProvider",
+    "get_provider",
+    "list_providers",
+    "PROVIDER_REGISTRY",
+    # Intelligence
+    "QueryIntentAnalyzer",
+    "QueryEnhancer",
+    "DataFusionEngine",
+    "SearchEnhancer",
+    # Reliability
+    "SmartErrorHandler",
+    "FallbackStrategy",
+    # Monitoring
+    "DetailedMetrics",
+    # Utils
+    "DataValidator",
+]

aiecs/tools/apisource/intelligence/__init__.py

@@ -0,0 +1,19 @@
+"""
+Intelligence Module
+
+Contains query analysis, data fusion, and search enhancement components.
+"""
+
+from aiecs.tools.apisource.intelligence.query_analyzer import (
+    QueryIntentAnalyzer,
+    QueryEnhancer,
+)
+from aiecs.tools.apisource.intelligence.data_fusion import DataFusionEngine
+from aiecs.tools.apisource.intelligence.search_enhancer import SearchEnhancer
+
+__all__ = [
+    "QueryIntentAnalyzer",
+    "QueryEnhancer",
+    "DataFusionEngine",
+    "SearchEnhancer",
+]