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

aiecs/__init__.py

@@ -5,7 +5,7 @@ A powerful Python middleware framework for building AI-powered applications
 with tool orchestration, task execution, and multi-provider LLM support.
 """
 
-__version__ = "1.2.1"
+__version__ = "1.3.1"
 __author__ = "AIECS Team"
 __email__ = "iretbl@gmail.com"
 

aiecs/config/config.py

@@ -54,7 +54,7 @@ class Settings(BaseSettings):
     reload: bool = Field(default=False, alias="RELOAD")
     port: int = Field(default=8000, alias="PORT")
 
-    model_config = ConfigDict(env_file=".env", env_file_encoding="utf-8")
+    model_config = ConfigDict(env_file=".env", env_file_encoding="utf-8", extra="allow")
 
     @property
     def database_config(self) -> dict:
@@ -77,6 +77,7 @@ class Settings(BaseSettings):
             "enable_local_fallback": True,
             "local_storage_path": "./storage"
         }
+
     
     def validate_llm_models_config(self) -> bool:
         """

aiecs/llm/clients/vertex_client.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import os
+import warnings
 from typing import Dict, Any, Optional, List, AsyncGenerator
 import vertexai
 from vertexai.generative_models import GenerativeModel, HarmCategory, HarmBlockThreshold, GenerationConfig, SafetySetting
@@ -9,6 +10,10 @@ from google.oauth2 import service_account
 from aiecs.llm.clients.base_client import BaseLLMClient, LLMMessage, LLMResponse, ProviderNotAvailableError, RateLimitError
 from aiecs.config.config import get_settings
 
+# Suppress Vertex AI SDK deprecation warnings (deprecated June 2025, removal June 2026)
+# TODO: Migrate to Google Gen AI SDK when official migration guide is available
+warnings.filterwarnings('ignore', category=UserWarning, module='vertexai.generative_models._generative_models')
+
 logger = logging.getLogger(__name__)
 
 class VertexAIClient(BaseLLMClient):

aiecs/main.py

@@ -142,7 +142,7 @@ async def lifespan(app: FastAPI):
 app = FastAPI(
     title="AIECS - AI Execute Services",
     description="Middleware service for AI-powered task execution and tool orchestration",
-    version="1.2.1",    
+    version="1.3.1",    
     lifespan=lifespan
 )
 
@@ -167,7 +167,7 @@ async def health_check():
     return {
         "status": "healthy",
         "service": "aiecs",
-        "version": "1.2.1"
+        "version": "1.3.1"
     }
 
 

aiecs/scripts/tools_develop/README.md

@@ -4,7 +4,116 @@
 
 ## 📋 脚本列表
 
-### 1. 类型注解检查器 (`check_type_annotations.py`)
+### 1. 工具验证器 (`verify_tools.py`)
+
+快速验证和展示 aiecs.tools 注册的所有工具和功能，帮助开发者了解工具注册情况。
+
+**用途**：
+- 列出所有注册的工具及其状态
+- 显示每个工具的描述和功能方法
+- 提供工具使用示例
+- 分析工具注册表信息
+- 展示工具继承关系和模块分布
+
+**命令**：
+```bash
+# 从项目根目录运行（推荐）
+python -m aiecs.scripts.tools_develop.verify_tools
+
+# 直接运行脚本
+python aiecs/scripts/tools_develop/verify_tools.py
+```
+
+**输出示例**：
+```
+================================================================================
+AIECS Tools 注册工具验证
+================================================================================
+
+发现 26 个注册的工具
+
+================================================================================
+📁 任务工具 (10 个)
+================================================================================
+
+[1] chart
+    描述: Chart and visualization operations
+    状态: loaded
+
+[2] pandas
+    描述: Data analysis and manipulation
+    状态: loaded
+
+... (更多工具)
+
+================================================================================
+📁 文档工具 (7 个)
+================================================================================
+
+[11] document_parser
+    描述: Document parsing and content extraction
+    状态: loaded
+
+... (更多工具)
+
+================================================================================
+📁 数据统计工具 (9 个)
+================================================================================
+
+[18] data_loader
+    描述: Universal data loading from multiple formats
+    状态: loaded
+
+... (更多工具)
+
+================================================================================
+✅ 工具列表显示完成! 共 26 个工具
+================================================================================
+
+================================================================================
+🎮 交互模式
+================================================================================
+
+提示:
+  - 输入工具序号 (1-26) 查看详细功能
+  - 输入工具名称查看详细功能
+  - 输入 'list' 重新显示工具列表
+  - 输入 'q' 或 'quit' 退出
+
+👉 请选择工具 > pandas
+
+================================================================================
+🔍 加载工具: pandas
+================================================================================
+
+⏳ 正在加载...
+    已触发 task_tools.pandas_tool 模块加载
+
+✅ 工具已成功加载
+    类名: PandasTool
+    模块: aiecs.tools.task_tools.pandas_tool
+
+📋 原子功能列表 (共 41 个方法):
+--------------------------------------------------------------------------------
+
+  [1] apply(records: List, func: str, columns: List, axis: int = 0) -> List
+      Apply a function to specified columns or rows.
+
+  [2] astype(records: List, dtypes: Dict) -> List
+      Convert column types in DataFrame.
+
+  [3] concat(records_list: List, axis: int = 0) -> List
+      Concatenate multiple DataFrames.
+
+  ... (更多方法)
+
+  [41] write_file(records: List, file_path: str, file_type: str = 'csv') -> Dict
+      Write DataFrame to a file.
+
+--------------------------------------------------------------------------------
+```
+
+### 2. 类型注解检查器 (`check_type_annotations.py`)
 
 检查工具方法的类型注解完整性，确保所有方法都有完整的类型注解（参数类型 + 返回类型）。
 
@@ -49,7 +158,7 @@ aiecs-tools-check-annotations pandas --verbose
 ====================================================================================================
 ```
 
-### 2. Schema 质量验证器 (`validate_tool_schemas.py`)
+### 3. Schema 质量验证器 (`validate_tool_schemas.py`)
 
 验证自动生成的 Schema 质量，识别需要改进的文档字符串。
 

aiecs/scripts/tools_develop/TOOL_AUTO_DISCOVERY.md

@@ -0,0 +1,234 @@
+# 工具自动发现机制
+
+## 📋 概述
+
+从现在开始，**无需手动维护工具列表**！系统会自动发现所有使用 `@register_tool` 装饰器注册的工具。
+
+## ✨ 特性
+
+### 1. 自动工具发现
+- ✅ 自动扫描 `aiecs/tools/task_tools/`、`aiecs/tools/docs/`、`aiecs/tools/statistics/` 目录
+- ✅ 自动识别所有 `@register_tool` 装饰器
+- ✅ 自动提取工具名称和描述
+- ✅ 自动分类（task/docs/statistics）
+
+### 2. 零维护成本
+- ✅ 添加新工具：只需在工具类上添加 `@register_tool("tool_name")` 装饰器
+- ✅ 删除工具：直接删除文件或移除装饰器
+- ✅ 重命名工具：修改装饰器参数即可
+- ✅ 无需修改任何配置文件
+
+## 🔧 工作原理
+
+### aiecs/tools/__init__.py
+
+```python
+def _auto_discover_tools():
+    """自动发现所有工具"""
+    # 扫描工具目录
+    for dir_name, category in [('task_tools', 'task'), ('docs', 'docs'), ('statistics', 'statistics')]:
+        # 查找所有 Python 文件
+        for filename in os.listdir(dir_path):
+            # 读取文件内容
+            # 使用正则表达式查找 @register_tool 装饰器
+            pattern = r'@register_tool\([\'"]([^\'"]+)[\'"]\)'
+            matches = re.findall(pattern, content)
+            # 提取工具名称和描述
+            # 注册为占位符，等待懒加载
+```
+
+### verify_tools.py
+
+```python
+def auto_discover_tool_modules():
+    """自动发现工具模块映射"""
+    # 扫描工具目录
+    # 查找 @register_tool 装饰器
+    # 建立工具名称到模块路径的映射
+    # 返回映射表供动态加载使用
+```
+
+## 📝 如何添加新工具
+
+### 步骤 1: 创建工具文件
+
+在合适的目录创建工具文件（例如：`aiecs/tools/task_tools/my_new_tool.py`）
+
+### 步骤 2: 添加装饰器
+
+```python
+from aiecs.tools import register_tool
+from aiecs.tools.base_tool import BaseTool
+
+@register_tool("my_new_tool")
+class MyNewTool(BaseTool):
+    """
+    这是一个新工具的简短描述。
+    
+    这个描述会被自动提取并显示在工具列表中。
+    """
+    
+    def my_method(self, param: str) -> str:
+        """执行某个操作"""
+        return f"Result: {param}"
+```
+
+### 步骤 3: 验证
+
+运行验证脚本查看新工具是否被发现：
+
+```bash
+poetry run python -m aiecs.scripts.tools_develop.verify_tools
+```
+
+就这样！**无需修改任何其他文件**！
+
+## 🎯 支持的目录结构
+
+```
+aiecs/tools/
+├── task_tools/          # 任务工具 (category: task)
+│   ├── chart_tool.py    # @register_tool("chart")
+│   ├── pandas_tool.py   # @register_tool("pandas")
+│   └── ...
+├── docs/                # 文档工具 (category: docs)
+│   ├── document_parser_tool.py    # @register_tool("document_parser")
+│   ├── document_writer_tool.py    # @register_tool("document_writer")
+│   └── ...
+└── statistics/          # 统计工具 (category: statistics)
+    ├── data_loader_tool.py        # @register_tool("data_loader")
+    ├── data_profiler_tool.py      # @register_tool("data_profiler")
+    └── ...
+```
+
+## 🔍 描述提取规则
+
+系统会自动提取类文档字符串的**第一行**作为工具描述：
+
+```python
+@register_tool("example")
+class ExampleTool(BaseTool):
+    """
+    这一行会被用作工具描述 ✅
+    
+    下面的内容不会被提取。
+    可以写详细的文档说明。
+    """
+```
+
+**建议**：
+- 第一行保持简短（< 200 字符）
+- 清晰描述工具的主要功能
+- 避免使用多行描述
+
+## 📊 当前发现的工具统计
+
+截至最后扫描，系统发现了 **26 个工具**：
+
+- **任务工具** (10个)：chart, classifier, image, office, pandas, report, research, scraper, search, stats
+- **文档工具** (7个)：document_parser, document_writer, document_creator, document_layout, content_insertion, ai_document_orchestrator, ai_document_writer_orchestrator
+- **数据统计工具** (9个)：data_loader, data_profiler, data_transformer, data_visualizer, model_trainer, statistical_analyzer, ai_data_analysis_orchestrator, ai_insight_generator, ai_report_orchestrator
+
+## ⚡ 性能优化
+
+### 占位符机制
+- 工具发现时创建轻量级占位符
+- 不导入实际工具模块（避免重依赖）
+- 只在实际使用时才加载工具
+
+### 懒加载
+- `verify_tools.py` 只在用户选择工具时才加载模块
+- 避免启动时加载所有工具
+- 提高响应速度
+
+## 🧪 测试验证
+
+### 验证工具发现
+```bash
+poetry run python -m aiecs.scripts.tools_develop.verify_tools
+```
+
+### 验证特定工具
+在交互模式中输入工具名称或序号：
+```
+👉 请选择工具 > pandas
+👉 请选择工具 > 7
+```
+
+### 验证描述提取
+检查工具列表中的描述是否正确提取自类文档字符串。
+
+## 🔄 兼容性
+
+### 向后兼容
+- 现有工具无需修改
+- 只要有 `@register_tool` 装饰器即可被发现
+- 保持与现有代码的兼容性
+
+### 新增目录支持
+如果未来需要添加新的工具目录（如 `aiecs/tools/ml_tools/`），只需修改两处：
+
+1. **aiecs/tools/__init__.py**
+```python
+tool_dirs = [
+    ('task_tools', 'task'),
+    ('docs', 'docs'),
+    ('statistics', 'statistics'),
+    ('ml_tools', 'ml'),  # 新增
+]
+```
+
+2. **verify_tools.py**
+```python
+tool_dirs = {
+    'task_tools': 'aiecs.tools.task_tools',
+    'docs': 'aiecs.tools.docs',
+    'statistics': 'aiecs.tools.statistics',
+    'ml_tools': 'aiecs.tools.ml_tools',  # 新增
+}
+```
+
+## ❓ 常见问题
+
+### Q: 工具没有被发现？
+**A:** 检查以下几点：
+1. 文件是否在支持的目录中（task_tools/docs/statistics）
+2. 是否使用了 `@register_tool("name")` 装饰器
+3. 文件名是否以 `.py` 结尾且不是 `__init__.py`
+
+### Q: 描述显示不正确？
+**A:** 检查类文档字符串：
+1. 文档字符串必须紧跟类定义
+2. 使用三引号 `"""`
+3. 确保第一行是简短描述
+
+### Q: 如何重命名工具？
+**A:** 只需修改装饰器参数：
+```python
+# 旧
+@register_tool("old_name")
+
+# 新
+@register_tool("new_name")
+```
+
+### Q: 如何临时禁用工具？
+**A:** 两种方法：
+1. 注释掉 `@register_tool` 装饰器
+2. 移动文件到其他目录
+
+## 🎉 优势总结
+
+| 特性 | 手动维护 | 自动发现 |
+|------|---------|---------|
+| 添加工具 | 需修改配置文件 | 只需添加装饰器 ✅ |
+| 删除工具 | 需修改配置文件 | 直接删除文件 ✅ |
+| 维护成本 | 高 | 零 ✅ |
+| 出错风险 | 容易遗漏 | 自动同步 ✅ |
+| 描述准确性 | 可能不一致 | 直接提取 ✅ |
+
+---
+
+**维护者**: AIECS Tools Team  
+**最后更新**: 2025-10-14
+

aiecs/scripts/tools_develop/validate_tool_schemas.py

@@ -104,61 +104,113 @@ def validate_schema_quality(schema: Type[BaseModel], method: callable, method_na
     return issues
 
 
+def find_manual_schema(tool_class: Type, method_name: str) -> Optional[Type[BaseModel]]:
+    """
+    查找手动定义的 Schema（与 langchain_adapter 逻辑一致）
+
+    Args:
+        tool_class: 工具类
+        method_name: 方法名
+
+    Returns:
+        找到的 Schema 类，如果没有则返回 None
+    """
+    schemas = {}
+
+    # 1. 检查类级别的 schemas
+    for attr_name in dir(tool_class):
+        attr = getattr(tool_class, attr_name)
+        if isinstance(attr, type) and issubclass(attr, BaseModel) and attr.__name__.endswith('Schema'):
+            # 标准化：移除 'Schema' 后缀，转小写，移除下划线
+            schema_base_name = attr.__name__.replace('Schema', '')
+            normalized_name = schema_base_name.replace('_', '').lower()
+            schemas[normalized_name] = attr
+
+    # 2. 检查模块级别的 schemas
+    import inspect
+    tool_module = inspect.getmodule(tool_class)
+    if tool_module:
+        for attr_name in dir(tool_module):
+            if attr_name.startswith('_'):
+                continue
+            attr = getattr(tool_module, attr_name)
+            if isinstance(attr, type) and issubclass(attr, BaseModel) and attr.__name__.endswith('Schema'):
+                schema_base_name = attr.__name__.replace('Schema', '')
+                normalized_name = schema_base_name.replace('_', '').lower()
+                if normalized_name not in schemas:
+                    schemas[normalized_name] = attr
+
+    # 标准化方法名：移除下划线并转小写
+    normalized_method_name = method_name.replace('_', '').lower()
+
+    # 查找匹配的 schema
+    return schemas.get(normalized_method_name)
+
+
 def analyze_tool_schemas(tool_name: str, tool_class: Type) -> Dict[str, Any]:
-    """分析工具的 Schema 生成情况"""
-    
+    """分析工具的 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)
-        
+
+        # 首先尝试查找手动定义的 Schema
+        manual_schema = find_manual_schema(tool_class, method_name)
+
+        if manual_schema:
+            schema = manual_schema
+            schema_type = 'manual'
+        else:
+            # 如果没有手动 Schema，则自动生成
+            schema = generate_schema_from_method(method, method_name)
+            schema_type = 'auto'
+
         method_info = {
             'name': method_name,
             'schema': schema,
+            'schema_type': schema_type,
             '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 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
@@ -167,11 +219,15 @@ def analyze_tool_schemas(tool_name: str, tool_class: Type) -> Dict[str, Any]:
 
 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()
-    
+
+    # 统计手动和自动 schema
+    manual_schemas = [m for m in methods if m.get('schema_type') == 'manual']
+    auto_schemas = [m for m in methods if m.get('schema_type') == 'auto']
+
     # 状态图标
     overall = scores['overall_score']
     if overall >= 90:
@@ -186,10 +242,12 @@ def print_tool_report(tool_name: str, result: Dict, verbose: bool = False, show_
     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"    - 手动定义: {len(manual_schemas)} 个")
+    print(f"    - 自动生成: {len(auto_schemas)} 个")
     print(f"  描述质量: {scores['description_quality']:.1f}%")
     print(f"  综合评分: {scores['overall_score']:.1f}% ({grade})")
     
@@ -215,7 +273,8 @@ def print_tool_report(tool_name: str, result: Dict, verbose: bool = False, show_
             print(f"\n  示例 Schema:")
             for method_info in methods_with_schema[:2]:
                 schema = method_info['schema']
-                print(f"\n    {method_info['name']} → {schema.__name__}")
+                schema_type_label = "🔧 手动定义" if method_info.get('schema_type') == 'manual' else "🤖 自动生成"
+                print(f"\n    {method_info['name']} → {schema.__name__} [{schema_type_label}]")
                 print(f"      描述: {schema.__doc__}")
                 print(f"      字段:")
                 for field_name, field_info in list(schema.model_fields.items())[:3]: