aigroup-econ-mcp 0.4.0__py3-none-any.whl → 1.3.3__py3-none-any.whl

aigroup_econ_mcp/tools/__init__.py

@@ -3,16 +3,17 @@
 """
 
 from . import regression, statistics, time_series, machine_learning, panel_data
-from . import validation, cache, monitoring, file_parser
+from . import validation, cache, monitoring, file_parser, tool_descriptions
 
 __all__ = [
-    "regression", 
-    "statistics", 
-    "time_series", 
-    "machine_learning", 
+    "regression",
+    "statistics",
+    "time_series",
+    "machine_learning",
     "panel_data",
     "validation",
-    "cache", 
+    "cache",
     "monitoring",
-    "file_parser"
+    "file_parser",
+    "tool_descriptions"
 ]

aigroup_econ_mcp/tools/base.py

@@ -1,16 +1,26 @@
 """
-工具模块基类
-提供统一的优化组件集成和错误处理
+工具模块基类和装饰器
+整合了工具基类、装饰器、错误处理和优化组件
 """
 
 import functools
 from typing import Any, Dict, List, Optional, Callable, Type
+from functools import wraps
+from mcp.server.session import ServerSession
+from mcp.server.fastmcp import Context
+from mcp.types import CallToolResult, TextContent
+
 from .validation import ValidationError, validate_econometric_data, validate_model_parameters
 from .cache import cache_result, cache_model, global_econometric_cache
 from .monitoring import monitor_performance, track_progress, global_performance_monitor
+from .file_parser import FileParser
 from ..config import get_config, econometric_config
 
 
+# ============================================================================
+# 错误类定义
+# ============================================================================
+
 class EconometricToolError(Exception):
     """计量经济学工具错误基类"""
     
@@ -45,6 +55,177 @@ class ConfigurationError(EconometricToolError):
     pass
 
 
+# ============================================================================
+# 装饰器函数
+# ============================================================================
+
+def with_file_input(tool_type: str):
+    """
+    为工具函数添加文件输入支持的装饰器
+    
+    支持两种输入方式：
+    1. file_path: CSV/JSON文件路径
+    2. file_content: 文件内容字符串
+    
+    Args:
+        tool_type: 工具类型 ('single_var', 'multi_var_dict', 'regression', 'panel', 'time_series')
+    
+    使用示例:
+        @with_file_input('regression')
+        async def my_tool(ctx, y_data=None, x_data=None, file_path=None, file_content=None, file_format='auto', **kwargs):
+            # 如果提供了file_path或file_content，数据会被自动填充
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # 提取上下文和文件参数
+            ctx = args[0] if args else kwargs.get('ctx')
+            file_path = kwargs.get('file_path')
+            file_content = kwargs.get('file_content')
+            file_format = kwargs.get('file_format', 'auto')
+            
+            # 优先处理file_path
+            if file_path:
+                try:
+                    await ctx.info(f"检测到文件路径输入: {file_path}")
+                    
+                    # 从文件路径解析
+                    parsed = FileParser.parse_file_path(file_path, file_format)
+                    
+                    await ctx.info(
+                        f"文件解析成功：{parsed['n_variables']}个变量，"
+                        f"{parsed['n_observations']}个观测"
+                    )
+                    
+                    # 转换为工具格式
+                    converted = FileParser.convert_to_tool_format(parsed, tool_type)
+                    
+                    # 更新kwargs
+                    kwargs.update(converted)
+                    
+                    await ctx.info(f"数据已转换为{tool_type}格式")
+                    
+                except Exception as e:
+                    await ctx.error(f"文件解析失败: {str(e)}")
+                    return CallToolResult(
+                        content=[TextContent(type="text", text=f"文件解析错误: {str(e)}")],
+                        isError=True
+                    )
+            
+            # 如果没有file_path但有file_content，处理文件内容
+            elif file_content:
+                try:
+                    await ctx.info("检测到文件内容输入，开始解析...")
+                    
+                    # 解析文件内容
+                    parsed = FileParser.parse_file_content(file_content, file_format)
+                    
+                    await ctx.info(
+                        f"文件解析成功：{parsed['n_variables']}个变量，"
+                        f"{parsed['n_observations']}个观测"
+                    )
+                    
+                    # 转换为工具格式
+                    converted = FileParser.convert_to_tool_format(parsed, tool_type)
+                    
+                    # 更新kwargs
+                    kwargs.update(converted)
+                    
+                    await ctx.info(f"数据已转换为{tool_type}格式")
+                    
+                except Exception as e:
+                    await ctx.error(f"文件解析失败: {str(e)}")
+                    return CallToolResult(
+                        content=[TextContent(type="text", text=f"文件解析错误: {str(e)}")],
+                        isError=True
+                    )
+            
+            # 调用原函数
+            return await func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+def with_error_handling(func: Callable) -> Callable:
+    """
+    为工具函数添加统一错误处理的装饰器
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        ctx = args[0] if args else kwargs.get('ctx')
+        tool_name = func.__name__
+        
+        try:
+            return await func(*args, **kwargs)
+        except Exception as e:
+            await ctx.error(f"{tool_name}执行出错: {str(e)}")
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"错误: {str(e)}")],
+                isError=True
+            )
+    
+    return wrapper
+
+
+def with_logging(func: Callable) -> Callable:
+    """
+    为工具函数添加日志记录的装饰器
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        ctx = args[0] if args else kwargs.get('ctx')
+        tool_name = func.__name__
+        
+        await ctx.info(f"开始执行 {tool_name}")
+        result = await func(*args, **kwargs)
+        await ctx.info(f"{tool_name} 执行完成")
+        
+        return result
+    
+    return wrapper
+
+
+def with_file_support_decorator(
+    tool_type: str,
+    enable_error_handling: bool = True,
+    enable_logging: bool = True
+):
+    """
+    组合装饰器：为计量经济学工具添加文件支持和其他标准功能
+    
+    Args:
+        tool_type: 工具类型
+        enable_error_handling: 是否启用错误处理
+        enable_logging: 是否启用日志记录
+    
+    使用示例:
+        @with_file_support_decorator('regression')
+        async def ols_regression(ctx, y_data=None, x_data=None, **kwargs):
+            # 只需要编写核心业务逻辑
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        wrapped = func
+        
+        if enable_error_handling:
+            wrapped = with_error_handling(wrapped)
+        
+        wrapped = with_file_input(tool_type)(wrapped)
+        
+        if enable_logging:
+            wrapped = with_logging(wrapped)
+        
+        return wrapped
+    
+    return decorator
+
+
+# ============================================================================
+# 工具基类
+# ============================================================================
+
 class EconometricTool:
     """
     计量经济学工具基类
@@ -206,16 +387,27 @@ class EconometricTool:
         return global_econometric_cache.result_cache.get_function_cache_stats(self.tool_name) or {}
 
 
+# ============================================================================
 # 便捷装饰器函数
-def econometric_tool(tool_name: str = None):
+# ============================================================================
+
+def econometric_tool_with_optimization(tool_name: str = None):
     """
-    计量经济学工具装饰器
+    计量经济学工具装饰器（带优化）
+    
+    应用缓存、性能监控和错误处理
     
     Args:
         tool_name: 工具名称
         
     Returns:
         Callable: 装饰器函数
+        
+    使用示例:
+        @econometric_tool_with_optimization('my_analysis')
+        def my_analysis(data):
+            # 自动获得缓存、监控和错误处理
+            pass
     """
     def decorator(func):
         name = tool_name or func.__name__
@@ -261,11 +453,18 @@ def validate_input(data_type: str = "generic"):
 
 # 导出主要类和函数
 __all__ = [
+    # 错误类
     "EconometricToolError",
     "DataValidationError", 
     "ModelFittingError",
     "ConfigurationError",
+    # 基类
     "EconometricTool",
-    "econometric_tool",
+    # 装饰器
+    "with_file_input",
+    "with_error_handling",
+    "with_logging",
+    "with_file_support_decorator",
+    "econometric_tool_with_optimization",
     "validate_input"
 ]

aigroup_econ_mcp/tools/data_loader.py

@@ -1,11 +1,12 @@
 """
 数据加载辅助模块
-提供通用的CSV文件加载功能
+提供通用的文件加载功能，支持CSV、JSON和TXT格式
 """
 
 from typing import Dict, List, Union
 from pathlib import Path
 import pandas as pd
+from .file_parser import FileParser
 
 
 async def load_data_if_path(
@@ -16,7 +17,7 @@ async def load_data_if_path(
     智能加载数据：如果是字符串则作为文件路径加载，否则直接返回
     
     Args:
-        data: 数据字典或CSV文件路径
+        data: 数据字典或文件路径（支持CSV/JSON/TXT）
         ctx: MCP上下文对象（可选，用于日志）
         
     Returns:
@@ -40,23 +41,28 @@ async def load_data_if_path(
             if not path.exists():
                 raise ValueError(f"文件不存在: {data}")
             
-            # 读取CSV文件
-            df = pd.read_csv(path)
+            # 使用FileParser解析文件（支持CSV/JSON/TXT自动检测）
+            parsed = FileParser.parse_file_path(str(path), "auto")
             
-            # 转换为字典格式
-            result = {col: df[col].tolist() for col in df.columns}
+            # 返回数据字典
+            result = parsed["data"]
             
             if ctx:
-                await ctx.info(f"✅ CSV文件加载成功：{len(df.columns)}个变量，{len(df)}个观测")
+                await ctx.info(
+                    f"✅ {parsed['format'].upper()}文件加载成功："
+                    f"{parsed['n_variables']}个变量，{parsed['n_observations']}个观测"
+                )
             
             return result
             
         except FileNotFoundError:
             raise ValueError(f"文件不存在: {data}")
         except Exception as e:
-            raise ValueError(f"CSV文件读取失败: {str(e)}")
+            raise ValueError(f"文件读取失败: {str(e)}")
     
     # 其他类型报错
+    raise TypeError(f"不支持的数据类型: {type(data)}，期望Dict或str")
+
 
 async def load_single_var_if_path(
     data: Union[List[float], str],
@@ -67,9 +73,9 @@ async def load_single_var_if_path(
     智能加载单变量数据：如果是字符串则作为文件路径加载，否则直接返回
     
     Args:
-        data: 数据列表或CSV文件路径
+        data: 数据列表或文件路径（支持CSV/JSON/TXT）
         ctx: MCP上下文对象（可选，用于日志）
-        column_name: CSV文件中要读取的列名（可选，默认读取第一列）
+        column_name: 文件中要读取的列名（可选，默认读取第一列）
         
     Returns:
         数据列表
@@ -92,32 +98,41 @@ async def load_single_var_if_path(
             if not path.exists():
                 raise ValueError(f"文件不存在: {data}")
             
-            # 读取CSV文件
-            df = pd.read_csv(path)
+            # 使用FileParser解析文件
+            parsed = FileParser.parse_file_path(str(path), "auto")
+            data_dict = parsed["data"]
             
             # 确定要读取的列
             if column_name:
-                if column_name not in df.columns:
-                    raise ValueError(f"列'{column_name}'不存在于CSV文件中。可用列: {list(df.columns)}")
-                result = df[column_name].tolist()
+                if column_name not in data_dict:
+                    raise ValueError(
+                        f"列'{column_name}'不存在于文件中。"
+                        f"可用列: {list(data_dict.keys())}"
+                    )
+                result = data_dict[column_name]
             else:
                 # 默认读取第一列
-                result = df.iloc[:, 0].tolist()
+                first_col = parsed["variables"][0]
+                result = data_dict[first_col]
                 if ctx:
-                    await ctx.info(f"未指定列名，使用第一列: {df.columns[0]}")
+                    await ctx.info(f"未指定列名，使用第一列: {first_col}")
             
             if ctx:
-                await ctx.info(f"✅ CSV文件加载成功：{len(result)}个观测")
+                await ctx.info(
+                    f"✅ {parsed['format'].upper()}文件加载成功：{len(result)}个观测"
+                )
             
             return result
             
         except FileNotFoundError:
             raise ValueError(f"文件不存在: {data}")
         except Exception as e:
-            raise ValueError(f"CSV文件读取失败: {str(e)}")
+            raise ValueError(f"文件读取失败: {str(e)}")
     
     # 其他类型报错
     raise TypeError(f"不支持的数据类型: {type(data)}，期望List或str")
+
+
 async def load_x_data_if_path(
     data: Union[List[List[float]], str],
     ctx = None
@@ -126,7 +141,7 @@ async def load_x_data_if_path(
     智能加载自变量数据：如果是字符串则作为文件路径加载，否则直接返回
     
     Args:
-        data: 自变量数据（二维列表）或CSV文件路径
+        data: 自变量数据（二维列表）或文件路径（支持CSV/JSON/TXT）
         ctx: MCP上下文对象（可选，用于日志）
         
     Returns:
@@ -150,22 +165,31 @@ async def load_x_data_if_path(
             if not path.exists():
                 raise ValueError(f"文件不存在: {data}")
             
-            # 读取CSV文件
-            df = pd.read_csv(path)
+            # 使用FileParser解析文件
+            parsed = FileParser.parse_file_path(str(path), "auto")
+            data_dict = parsed["data"]
             
             # 转换为二维列表格式
-            result = df.values.tolist()
+            variables = parsed["variables"]
+            n_obs = parsed["n_observations"]
+            
+            result = []
+            for i in range(n_obs):
+                row = [data_dict[var][i] for var in variables]
+                result.append(row)
             
             if ctx:
-                await ctx.info(f"✅ 自变量CSV文件加载成功：{len(result)}个观测，{len(result[0]) if result else 0}个自变量")
+                await ctx.info(
+                    f"✅ 自变量{parsed['format'].upper()}文件加载成功："
+                    f"{len(result)}个观测，{len(variables)}个自变量"
+                )
             
             return result
             
         except FileNotFoundError:
             raise ValueError(f"文件不存在: {data}")
         except Exception as e:
-            raise ValueError(f"自变量CSV文件读取失败: {str(e)}")
+            raise ValueError(f"自变量文件读取失败: {str(e)}")
     
     # 其他类型报错
-    raise TypeError(f"不支持的数据类型: {type(data)}，期望List[List[float]]或str")
-    raise TypeError(f"不支持的数据类型: {type(data)}，期望Dict或str")
+    raise TypeError(f"不支持的数据类型: {type(data)}，期望List[List[float]]或str")