aiecs 1.0.8__py3-none-any.whl → 1.2.0__py3-none-any.whl

aiecs/scripts/tools_develop/validate_tool_schemas.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""
+工具 Schema 质量验证器
+
+用于工具开发和维护，验证自动生成的 Schema 质量。
+帮助开发者识别需要改进的文档字符串，提升 Schema 描述质量。
+
+使用方法:
+    # 验证所有工具
+    aiecs tools validate-schemas
+    
+    # 验证特定工具
+    aiecs tools validate-schemas pandas
+    
+    # 显示详细的改进建议
+    aiecs tools validate-schemas pandas --verbose
+    
+    # 显示示例 Schema
+    aiecs tools validate-schemas pandas --show-examples
+"""
+
+import sys
+import inspect
+from typing import Dict, List, Any, Type, Optional, get_type_hints
+from pydantic import BaseModel
+
+# 确保可以导入 aiecs
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__)))))
+
+from aiecs.tools import discover_tools, TOOL_CLASSES
+from aiecs.tools.schema_generator import generate_schema_from_method
+
+
+class SchemaQualityMetrics:
+    """Schema 质量指标"""
+    
+    def __init__(self):
+        self.total_methods = 0
+        self.schemas_generated = 0
+        self.schemas_failed = 0
+        self.total_fields = 0
+        self.fields_with_meaningful_descriptions = 0
+        self.fields_with_types = 0
+        self.quality_issues = []
+    
+    def add_method(self, has_schema: bool):
+        """添加方法统计"""
+        self.total_methods += 1
+        if has_schema:
+            self.schemas_generated += 1
+        else:
+            self.schemas_failed += 1
+    
+    def add_field(self, has_type: bool, has_meaningful_desc: bool):
+        """添加字段统计"""
+        self.total_fields += 1
+        if has_type:
+            self.fields_with_types += 1
+        if has_meaningful_desc:
+            self.fields_with_meaningful_descriptions += 1
+    
+    def add_issue(self, issue: str):
+        """添加质量问题"""
+        self.quality_issues.append(issue)
+    
+    def get_scores(self) -> Dict[str, float]:
+        """计算质量分数"""
+        generation_rate = (self.schemas_generated / self.total_methods * 100) if self.total_methods > 0 else 0
+        description_rate = (self.fields_with_meaningful_descriptions / self.total_fields * 100) if self.total_fields > 0 else 0
+        type_coverage = (self.fields_with_types / self.total_fields * 100) if self.total_fields > 0 else 0
+        
+        return {
+            'generation_rate': generation_rate,
+            'description_quality': description_rate,
+            'type_coverage': type_coverage,
+            'overall_score': (generation_rate + description_rate + type_coverage) / 3
+        }
+
+
+def validate_schema_quality(schema: Type[BaseModel], method: callable, method_name: str) -> List[str]:
+    """
+    验证单个 Schema 的质量
+    
+    Returns:
+        质量问题列表（改进建议）
+    """
+    issues = []
+    
+    # 1. 检查 Schema 描述
+    if not schema.__doc__ or schema.__doc__.strip() == f"Execute {method_name} operation":
+        issues.append(f"💡 在方法文档字符串的第一行添加有意义的描述")
+    
+    # 2. 检查字段
+    if not schema.model_fields:
+        return issues
+    
+    for field_name, field_info in schema.model_fields.items():
+        # 检查字段描述
+        description = field_info.description
+        if not description or description == f"Parameter {field_name}":
+            issues.append(f"💡 在文档字符串的 Args 部分为参数 '{field_name}' 添加描述")
+    
+    return issues
+
+
+def analyze_tool_schemas(tool_name: str, tool_class: Type) -> Dict[str, Any]:
+    """分析工具的 Schema 生成情况"""
+    
+    metrics = SchemaQualityMetrics()
+    methods_info = []
+    
+    for method_name in dir(tool_class):
+        # 跳过私有方法和特殊方法
+        if method_name.startswith('_'):
+            continue
+        
+        # 跳过基类方法
+        if method_name in ['run', 'run_async', 'run_batch']:
+            continue
+        
+        method = getattr(tool_class, method_name)
+        
+        # 跳过非方法属性
+        if not callable(method) or isinstance(method, type):
+            continue
+        
+        # 生成 Schema
+        schema = generate_schema_from_method(method, method_name)
+        
+        method_info = {
+            'name': method_name,
+            'schema': schema,
+            'issues': []
+        }
+        
+        if schema:
+            metrics.add_method(True)
+            
+            # 验证质量
+            issues = validate_schema_quality(schema, method, method_name)
+            method_info['issues'] = issues
+            
+            # 统计字段
+            for field_name, field_info in schema.model_fields.items():
+                has_type = field_info.annotation is not None
+                has_meaningful_desc = (
+                    field_info.description and 
+                    field_info.description != f"Parameter {field_name}"
+                )
+                metrics.add_field(has_type, has_meaningful_desc)
+            
+            # 记录问题
+            for issue in issues:
+                metrics.add_issue(f"{tool_name}.{method_name}: {issue}")
+        else:
+            metrics.add_method(False)
+            method_info['issues'] = ['⚠️  无法生成 Schema（可能是无参数方法）']
+        
+        methods_info.append(method_info)
+    
+    return {
+        'metrics': metrics,
+        'methods': methods_info
+    }
+
+
+def print_tool_report(tool_name: str, result: Dict, verbose: bool = False, show_examples: bool = False):
+    """打印工具报告"""
+    
+    metrics = result['metrics']
+    methods = result['methods']
+    scores = metrics.get_scores()
+    
+    # 状态图标
+    overall = scores['overall_score']
+    if overall >= 90:
+        status = "✅"
+        grade = "A (优秀)"
+    elif overall >= 80:
+        status = "⚠️"
+        grade = "B (良好)"
+    elif overall >= 70:
+        status = "⚠️"
+        grade = "C (中等)"
+    else:
+        status = "❌"
+        grade = "D (需改进)"
+    
+    print(f"\n{status} {tool_name}")
+    print(f"  方法数: {metrics.total_methods}")
+    print(f"  成功生成 Schema: {metrics.schemas_generated} ({scores['generation_rate']:.1f}%)")
+    print(f"  描述质量: {scores['description_quality']:.1f}%")
+    print(f"  综合评分: {scores['overall_score']:.1f}% ({grade})")
+    
+    # 显示需要改进的方法
+    methods_with_issues = [m for m in methods if m['issues'] and m['schema']]
+    
+    if methods_with_issues and (verbose or scores['description_quality'] < 80):
+        print(f"\n  需要改进的方法 ({len(methods_with_issues)} 个):")
+        
+        for method_info in methods_with_issues[:5 if not verbose else None]:
+            print(f"\n    {method_info['name']}:")
+            for issue in method_info['issues']:
+                print(f"      {issue}")
+        
+        if not verbose and len(methods_with_issues) > 5:
+            print(f"\n    ... 还有 {len(methods_with_issues) - 5} 个方法需要改进")
+            print(f"    使用 --verbose 查看全部")
+    
+    # 显示示例 Schema
+    if show_examples:
+        methods_with_schema = [m for m in methods if m['schema']]
+        if methods_with_schema:
+            print(f"\n  示例 Schema:")
+            for method_info in methods_with_schema[:2]:
+                schema = method_info['schema']
+                print(f"\n    {method_info['name']} → {schema.__name__}")
+                print(f"      描述: {schema.__doc__}")
+                print(f"      字段:")
+                for field_name, field_info in list(schema.model_fields.items())[:3]:
+                    required = "必需" if field_info.is_required() else "可选"
+                    print(f"        - {field_name}: {field_info.description} [{required}]")
+
+
+def validate_schemas(tool_names: Optional[List[str]] = None, verbose: bool = False, show_examples: bool = False):
+    """
+    验证工具的 Schema 质量
+    
+    Args:
+        tool_names: 要验证的工具名称列表，None 表示验证所有工具
+        verbose: 是否显示详细信息
+        show_examples: 是否显示示例 Schema
+    """
+    print("=" * 100)
+    print("工具 Schema 质量验证器")
+    print("=" * 100)
+    
+    discover_tools()
+    
+    # 确定要验证的工具
+    if tool_names:
+        tools_to_check = {}
+        for name in tool_names:
+            if name in TOOL_CLASSES:
+                tools_to_check[name] = TOOL_CLASSES[name]
+            else:
+                print(f"\n❌ 工具 '{name}' 不存在")
+        
+        if not tools_to_check:
+            print("\n没有找到要验证的工具")
+            return
+    else:
+        tools_to_check = TOOL_CLASSES
+    
+    # 验证每个工具
+    all_results = {}
+    for tool_name in sorted(tools_to_check.keys()):
+        tool_class = tools_to_check[tool_name]
+        result = analyze_tool_schemas(tool_name, tool_class)
+        all_results[tool_name] = result
+        
+        print_tool_report(tool_name, result, verbose, show_examples)
+    
+    # 总体统计
+    if len(all_results) > 1:
+        total_methods = sum(r['metrics'].total_methods for r in all_results.values())
+        total_generated = sum(r['metrics'].schemas_generated for r in all_results.values())
+        total_fields = sum(r['metrics'].total_fields for r in all_results.values())
+        total_meaningful = sum(r['metrics'].fields_with_meaningful_descriptions for r in all_results.values())
+        
+        overall_generation = (total_generated / total_methods * 100) if total_methods > 0 else 0
+        overall_description = (total_meaningful / total_fields * 100) if total_fields > 0 else 0
+        
+        print("\n" + "=" * 100)
+        print(f"总体统计:")
+        print(f"  方法数: {total_methods}")
+        print(f"  Schema 生成率: {total_generated}/{total_methods} ({overall_generation:.1f}%)")
+        print(f"  描述质量: {overall_description:.1f}%")
+        print("=" * 100)
+    
+    print("\n💡 改进建议:")
+    print("  1. 在方法的文档字符串第一行添加简短描述")
+    print("  2. 在 Args 部分为每个参数添加详细描述")
+    print("  3. 使用 Google 或 NumPy 风格的文档字符串")
+    print("\n示例:")
+    print('  def filter(self, records: List[Dict], condition: str) -> List[Dict]:')
+    print('      """')
+    print('      Filter DataFrame based on a condition.')
+    print('      ')
+    print('      Args:')
+    print('          records: List of records to filter')
+    print('          condition: Filter condition (pandas query syntax)')
+    print('      """')
+
+
+def main():
+    """命令行入口"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description='验证工具 Schema 的生成质量',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  # 验证所有工具
+  aiecs tools validate-schemas
+  
+  # 验证特定工具
+  aiecs tools validate-schemas pandas
+  
+  # 显示详细的改进建议
+  aiecs tools validate-schemas pandas --verbose
+  
+  # 显示示例 Schema
+  aiecs tools validate-schemas pandas --show-examples
+        """
+    )
+    
+    parser.add_argument(
+        'tools',
+        nargs='*',
+        help='要验证的工具名称（不指定则验证所有工具）'
+    )
+    
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='显示详细的改进建议'
+    )
+    
+    parser.add_argument(
+        '-e', '--show-examples',
+        action='store_true',
+        help='显示示例 Schema'
+    )
+    
+    args = parser.parse_args()
+    
+    tool_names = args.tools if args.tools else None
+    validate_schemas(tool_names, args.verbose, args.show_examples)
+
+
+if __name__ == '__main__':
+    main()
+

aiecs/tools/__init__.py

@@ -11,25 +11,25 @@ from aiecs.tools.base_tool import BaseTool
 
 logger = logging.getLogger(__name__)
 
-# 全局工具注册表
+# Global tool registry
 TOOL_REGISTRY = {}
 TOOL_CLASSES = {}
 TOOL_CONFIGS = {}
 
 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
@@ -37,22 +37,29 @@ def register_tool(name):
 
 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
+            tool_class = TOOL_CLASSES[name]
+            config = TOOL_CONFIGS.get(name, {})
+            TOOL_REGISTRY[name] = tool_class(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")
@@ -61,17 +68,17 @@ def get_tool(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 = {
@@ -83,7 +90,7 @@ def list_tools():
                     "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,
@@ -100,7 +107,7 @@ def list_tools():
             
         except Exception as e:
             logger.warning(f"Failed to get info for tool {tool_name}: {e}")
-            # 提供基本信息
+            # Provide basic information
             tools.append({
                 "name": tool_name,
                 "description": f"{tool_name} (info unavailable)",
@@ -114,26 +121,26 @@ def list_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)
     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}")
 
-# 导入基础工具类供继承使用
+# Import base tool class for inheritance
 from aiecs.tools.base_tool import BaseTool
 
 # Lazy loading strategy: don't import all tools at package init
@@ -152,18 +159,30 @@ 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)
     
     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"),
+        ("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_tool", "Statistical analysis and computation")
+        ("stats", "Statistical analysis and computation")
     ]
     
     # Register as placeholder until actually loaded

aiecs/tools/docs/__init__.py

@@ -0,0 +1,106 @@
+# python-middleware/aiecs/tools/docs/__init__.py
+
+"""
+Document Tools Module
+
+This module contains specialized tools for document processing and analysis:
+- document_parser_tool: Modern high-performance document parsing with AI
+- ai_document_orchestrator: AI-powered document processing orchestrator
+"""
+
+# Lazy import all document tools to avoid heavy dependencies at import time
+import os
+
+# Define available document tools for lazy loading
+_AVAILABLE_DOC_TOOLS = [
+    'document_parser_tool',
+    'ai_document_orchestrator', 
+    'document_writer_tool',
+    'ai_document_writer_orchestrator',
+    'document_creator_tool',
+    'document_layout_tool',
+    'content_insertion_tool'
+]
+
+# Track which tools have been loaded
+_LOADED_DOC_TOOLS = set()
+
+def _lazy_load_doc_tool(tool_name: str):
+    """Lazy load a specific document tool module"""
+    if tool_name in _LOADED_DOC_TOOLS:
+        return
+    
+    # Mark as loading to prevent infinite recursion
+    _LOADED_DOC_TOOLS.add(tool_name)
+    
+    try:
+        if tool_name == 'document_parser_tool':
+            from . import document_parser_tool
+            globals()['document_parser_tool'] = document_parser_tool
+        elif tool_name == 'ai_document_orchestrator':
+            from . import ai_document_orchestrator
+            globals()['ai_document_orchestrator'] = ai_document_orchestrator
+        elif tool_name == 'document_writer_tool':
+            from . import document_writer_tool
+            globals()['document_writer_tool'] = document_writer_tool
+        elif tool_name == 'ai_document_writer_orchestrator':
+            from . import ai_document_writer_orchestrator
+            globals()['ai_document_writer_orchestrator'] = ai_document_writer_orchestrator
+        elif tool_name == 'document_creator_tool':
+            from . import document_creator_tool
+            globals()['document_creator_tool'] = document_creator_tool
+        elif tool_name == 'document_layout_tool':
+            from . import document_layout_tool
+            globals()['document_layout_tool'] = document_layout_tool
+        elif tool_name == 'content_insertion_tool':
+            from . import content_insertion_tool
+            globals()['content_insertion_tool'] = content_insertion_tool
+        
+    except ImportError as e:
+        # Remove from loaded set if import failed
+        _LOADED_DOC_TOOLS.discard(tool_name)
+        print(f"Warning: Could not import {tool_name}: {e}")
+
+def __getattr__(name: str):
+    """
+    Lazy loading mechanism for document tools.
+    
+    This allows importing tools like:
+    from aiecs.tools.docs import document_parser_tool
+    """
+    if name in _AVAILABLE_DOC_TOOLS:
+        _lazy_load_doc_tool(name)
+        if name in globals():
+            return globals()[name]
+    
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+def list_doc_tools():
+    """List all available document tools"""
+    return _AVAILABLE_DOC_TOOLS.copy()
+
+def load_all_doc_tools():
+    """Load all available document tools"""
+    for tool_name in _AVAILABLE_DOC_TOOLS:
+        _lazy_load_doc_tool(tool_name)
+
+# Auto-discovery of tool modules in this directory
+def _discover_doc_tools():
+    """Discover document tool modules in the current directory"""
+    current_dir = os.path.dirname(__file__)
+    if not current_dir:
+        return
+    
+    for filename in os.listdir(current_dir):
+        if filename.endswith('_tool.py') and not filename.startswith('__'):
+            tool_name = filename[:-3]  # Remove .py extension
+            if tool_name not in _AVAILABLE_DOC_TOOLS:
+                _AVAILABLE_DOC_TOOLS.append(tool_name)
+
+# Discover tools on import
+_discover_doc_tools()
+
+__all__ = [
+    'list_doc_tools',
+    'load_all_doc_tools',
+] + _AVAILABLE_DOC_TOOLS