aiecs 1.2.1__py3-none-any.whl → 1.3.1__py3-none-any.whl

aiecs/scripts/tools_develop/verify_tools.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+快速验证脚本：展示 aiecs.tools 注册的所有工具和功能
+
+使用方法:
+    poetry run python -m aiecs.scripts.tools_develop.verify_tools
+
+功能:
+    1. 列出所有注册的工具（按类别分组）
+    2. 交互式选择工具查看详细功能
+    3. 实际加载指定工具，展示真实的原子功能
+"""
+
+import sys
+import os
+import inspect
+from typing import List, Dict
+from collections import defaultdict
+
+# 添加项目根目录到 Python 路径
+current_dir = os.path.dirname(os.path.abspath(__file__))
+project_root = os.path.abspath(os.path.join(current_dir, '../../../'))
+sys.path.insert(0, project_root)
+
+
+def get_tool_methods(tool_instance) -> List[str]:
+    """获取工具实例的所有公共方法（原子功能）"""
+    methods = []
+    for name, method in inspect.getmembers(tool_instance, predicate=inspect.ismethod):
+        # 只获取公共方法，排除私有方法和特殊方法
+        if not name.startswith('_'):
+            methods.append(name)
+    return sorted(methods)
+
+
+def display_tools_by_category(tools: List[Dict]):
+    """按类别分组显示工具"""
+    # 按类别分组
+    categories = defaultdict(list)
+    for tool in tools:
+        category = tool.get('category', 'unknown')
+        categories[category].append(tool)
+    
+    # 显示每个类别
+    category_names = {
+        'task': '任务工具',
+        'docs': '文档工具',
+        'statistics': '数据统计工具',
+        'unknown': '其他工具'
+    }
+    
+    tool_index = 1
+    tool_map = {}  # 用于存储序号到工具名的映射
+    
+    for category in ['task', 'docs', 'statistics', 'unknown']:
+        if category not in categories:
+            continue
+            
+        category_tools = categories[category]
+        category_display = category_names.get(category, category.upper())
+        
+        print(f"\n{'=' * 80}")
+        print(f"📁 {category_display} ({len(category_tools)} 个)")
+        print(f"{'=' * 80}")
+        
+        for tool in category_tools:
+            tool_name = tool['name']
+            tool_map[tool_index] = tool_name
+            
+            print(f"\n[{tool_index}] {tool_name}")
+            print(f"    描述: {tool.get('description', '无描述')}")
+            print(f"    状态: {tool.get('status', '未知')}")
+            
+            tool_index += 1
+    
+    return tool_map
+
+
+def auto_discover_tool_modules():
+    """自动发现工具模块映射，无需手动维护"""
+    import os
+    import re
+    
+    tool_module_map = {}
+    
+    # 扫描 aiecs/tools 目录
+    tools_dir = os.path.join(project_root, 'aiecs', 'tools')
+    
+    # 定义工具目录
+    tool_dirs = {
+        'task_tools': 'aiecs.tools.task_tools',
+        'docs': 'aiecs.tools.docs',
+        'statistics': 'aiecs.tools.statistics',
+        'api_sources': 'aiecs.tools.api_sources',  # 旧的 API sources (如果存在)
+        'apisource': 'aiecs.tools.apisource',      # 新的 APISource Tool
+        'search_tool': 'aiecs.tools.search_tool',
+    }
+    
+    for dir_name, package_name in tool_dirs.items():
+        dir_path = os.path.join(tools_dir, 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):
+            # For packages, scan __init__.py and use package name directly
+            files_to_scan.append(('__init__.py', init_file, package_name))
+
+        # 扫描目录中的所有其他 Python 文件
+        for filename in os.listdir(dir_path):
+            if filename.endswith('.py') and not filename.startswith('__'):
+                file_path = os.path.join(dir_path, filename)
+                module_name = filename[:-3]  # 去掉 .py 扩展名
+                module_path = f"{package_name}.{module_name}"
+                files_to_scan.append((filename, file_path, module_path))
+
+        # Process all files
+        for filename, file_path, module_path in files_to_scan:
+            try:
+                with open(file_path, 'r', encoding='utf-8') as f:
+                    content = f.read()
+
+                    # 查找 @register_tool 装饰器 (两种模式)
+                    # 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:
+                        tool_module_map[tool_name] = {
+                            'module_file': filename[:-3] if filename != '__init__.py' else '__init__',
+                            'package': package_name,
+                            'module_path': module_path,
+                            'category': dir_name,
+                        }
+            except Exception:
+                pass
+    
+    return tool_module_map
+
+
+def load_and_inspect_tool(tool_name: str):
+    """加载并检查指定工具的详细功能"""
+    from aiecs.tools import get_tool
+    import importlib
+    
+    print(f"\n{'=' * 80}")
+    print(f"🔍 加载工具: {tool_name}")
+    print(f"{'=' * 80}")
+    
+    try:
+        # 自动发现工具模块
+        print(f"\n⏳ 正在加载...")
+        
+        tool_module_map = auto_discover_tool_modules()
+        
+        # 如果找到了工具的模块信息，预加载模块
+        if tool_name in tool_module_map:
+            info = tool_module_map[tool_name]
+            module_path = info.get('module_path') or f"{info['package']}.{info['module_file']}"
+
+            try:
+                importlib.import_module(module_path)
+                print(f"    已触发 {module_path} 模块加载")
+            except Exception as e:
+                print(f"    警告: 无法预加载模块 ({e})")
+        else:
+            print(f"    未找到工具模块映射，尝试直接加载...")
+        
+        # 获取工具实例
+        tool = get_tool(tool_name)
+        
+        # 检查是否为占位符
+        is_placeholder = getattr(tool, 'is_placeholder', False)
+        
+        if is_placeholder:
+            print(f"\n⚠️  工具仍处于占位符状态")
+            print(f"    描述: {tool.description}")
+            print(f"    提示: 此工具需要在调用具体方法时才会完全实例化")
+            return
+        
+        # 显示工具基本信息
+        print(f"\n✅ 工具已成功加载")
+        print(f"    类名: {tool.__class__.__name__}")
+        print(f"    模块: {tool.__class__.__module__}")
+        
+        if hasattr(tool, 'description'):
+            print(f"    描述: {tool.description}")
+        
+        if hasattr(tool, 'category'):
+            print(f"    类别: {tool.category}")
+        
+        # 获取所有方法（原子功能）
+        methods = get_tool_methods(tool)
+        
+        if not methods:
+            print(f"\n❌ 未发现公共方法")
+            return
+        
+        print(f"\n📋 原子功能列表 (共 {len(methods)} 个方法):")
+        print(f"{'-' * 80}")
+        
+        for i, method_name in enumerate(methods, 1):
+            try:
+                method = getattr(tool, method_name)
+                
+                # 获取方法签名
+                sig = inspect.signature(method)
+                params = []
+                for param_name, param in sig.parameters.items():
+                    if param_name == 'self':
+                        continue
+                    
+                    # 构建参数字符串
+                    param_str = param_name
+                    if param.annotation != inspect.Parameter.empty:
+                        param_str += f": {param.annotation.__name__ if hasattr(param.annotation, '__name__') else str(param.annotation)}"
+                    if param.default != inspect.Parameter.empty:
+                        param_str += f" = {param.default!r}"
+                    params.append(param_str)
+                
+                # 获取返回类型
+                return_annotation = ""
+                if sig.return_annotation != inspect.Signature.empty:
+                    return_type = sig.return_annotation
+                    return_annotation = f" -> {return_type.__name__ if hasattr(return_type, '__name__') else str(return_type)}"
+                
+                # 显示方法签名
+                print(f"\n  [{i}] {method_name}({', '.join(params)}){return_annotation}")
+                
+                # 获取文档字符串
+                if method.__doc__:
+                    doc_lines = method.__doc__.strip().split('\n')
+                    first_line = doc_lines[0].strip()
+                    if first_line:
+                        print(f"      {first_line}")
+                
+            except Exception as e:
+                print(f"\n  [{i}] {method_name}")
+                print(f"      (无法获取详细信息: {e})")
+        
+        print(f"\n{'-' * 80}")
+        
+    except Exception as e:
+        print(f"\n❌ 加载工具失败: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+def interactive_mode(tool_map: Dict[int, str]):
+    """交互式模式"""
+    print(f"\n{'=' * 80}")
+    print("🎮 交互模式")
+    print(f"{'=' * 80}")
+    print("\n提示:")
+    print("  - 输入工具序号 (1-{}) 查看详细功能".format(len(tool_map)))
+    print("  - 输入工具名称查看详细功能")
+    print("  - 输入 'list' 重新显示工具列表")
+    print("  - 输入 'q' 或 'quit' 退出")
+    
+    while True:
+        try:
+            user_input = input("\n👉 请选择工具 > ").strip()
+            
+            if not user_input:
+                continue
+            
+            if user_input.lower() in ['q', 'quit', 'exit']:
+                print("\n👋 再见!")
+                break
+            
+            if user_input.lower() == 'list':
+                from aiecs.tools import list_tools
+                tools = list_tools()
+                display_tools_by_category(tools)
+                continue
+            
+            # 尝试作为序号解析
+            tool_name = None
+            try:
+                index = int(user_input)
+                if index in tool_map:
+                    tool_name = tool_map[index]
+                else:
+                    print(f"❌ 无效的序号: {index}")
+                    continue
+            except ValueError:
+                # 作为工具名称
+                tool_name = user_input
+            
+            if tool_name:
+                load_and_inspect_tool(tool_name)
+        
+        except KeyboardInterrupt:
+            print("\n\n👋 再见!")
+            break
+        except EOFError:
+            print("\n\n👋 再见!")
+            break
+        except Exception as e:
+            print(f"\n❌ 错误: {e}")
+
+
+def main():
+    """主函数：验证和展示所有注册的工具"""
+    print("=" * 80)
+    print("AIECS Tools 注册工具验证")
+    print("=" * 80)
+    
+    try:
+        from aiecs.tools import list_tools
+        
+        # 获取所有注册的工具
+        tools = list_tools()
+        
+        print(f"\n发现 {len(tools)} 个注册的工具")
+        
+        # 按类别显示工具
+        tool_map = display_tools_by_category(tools)
+        
+        print(f"\n{'=' * 80}")
+        print(f"✅ 工具列表显示完成! 共 {len(tools)} 个工具")
+        print(f"{'=' * 80}")
+        
+        # 进入交互模式
+        interactive_mode(tool_map)
+        
+    except ImportError as e:
+        print(f"❌ 导入错误: {e}")
+        print("请确保在正确的项目目录中运行此脚本")
+    except Exception as e:
+        print(f"❌ 运行错误: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

aiecs/tools/__init__.py

@@ -155,48 +155,112 @@ def _ensure_task_tools_available():
         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
-    # 
-    # NOTE: Tool names must match the names used in @register_tool decorators:
-    # - chart (not chart_tool)
-    # - classifier (not classfire_tool) 
-    # - image (not image_tool)
-    # - office (not office_tool)
-    # - pandas (not pandas_tool)
-    # - report (not report_tool)
-    # - research (not research_tool)
-    # - scraper (not scraper_tool)
-    # - search_api (same)
-    # - stats (not stats_tool)
+    # Automatically discover all tools
+    discovered_tools = _auto_discover_tools()
     
-    known_tools = [
-        ("chart", "Chart and visualization operations"),
-        ("classifier", "Text classification and keyword extraction"),
-        ("image", "Image processing and OCR operations"),
-        ("office", "Office document processing"),
-        ("pandas", "Data analysis and manipulation"), 
-        ("report", "Report generation and formatting"),
-        ("research", "Research and information gathering"),
-        ("scraper", "Web scraping and data extraction"),
-        ("search_api", "Search API integration"),
-        ("stats", "Statistical analysis and computation")
-    ]
+    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()

aiecs/tools/apisource/__init__.py

@@ -0,0 +1,106 @@
+"""
+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,20 @@
+"""
+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'
+]
+