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

aigroup_econ_mcp/tools/tool_registry.py

@@ -1,478 +0,0 @@
-"""
-工具注册器模块
-简化MCP工具的注册和管理
-"""
-
-from typing import Dict, Any, Optional, List, Callable
-from pydantic import Field
-from typing import Annotated
-
-from .base import with_file_support_decorator as econometric_tool
-
-
-# 标准文件输入参数定义
-FILE_INPUT_PARAMS = {
-    "file_content": Annotated[
-        Optional[str],
-        Field(
-            default=None,
-            description="""CSV、JSON或TXT文件内容
-
-📁 支持格式：
-- CSV: 带表头的列数据，自动检测分隔符（逗号、制表符、分号等）
-- JSON: {"变量名": [数据], ...} 或 [{"变量1": 值, ...}, ...]
-- TXT: 支持多种格式
-  * 单列数值：每行一个数值
-  * 多列数值：空格或制表符分隔，可带表头
-  * 键值对：变量名: 值列表 或 变量名 = 值列表
-
-💡 使用方式：
-- 提供文件内容字符串（可以是base64编码）
-- 系统会自动解析并识别变量和数据格式
-- 优先使用file_content，如果提供则忽略其他数据参数
-- 也可以直接传入文件路径（.csv/.json/.txt）
-
-📝 示例：
-CSV: "变量1,变量2\\n1.2,3.4\\n2.3,4.5"
-JSON: "{\\"x\\": [1,2,3], \\"y\\": [4,5,6]}"
-TXT单列: "1.5\\n2.3\\n3.1"
-TXT多列: "x y\\n1 2\\n3 4"
-TXT键值对: "x: 1 2 3\\ny: 4 5 6"
-"""
-        )
-    ],
-    "file_format": Annotated[
-        str,
-        Field(
-            default="auto",
-            description="""文件格式类型
-
-可选值：
-- "auto": 自动检测（默认，推荐）- 根据文件内容智能识别格式
-- "csv": CSV格式 - 逗号、制表符或分号分隔的表格数据
-- "json": JSON格式 - 结构化JSON数据
-- "txt": TXT格式 - 纯文本数据，支持多种子格式
-
-🔍 自动检测规则：
-1. 尝试解析JSON格式
-2. 检测CSV特征（逗号、制表符）
-3. 检测TXT特征（纯数值、键值对、空格分隔）
-4. 根据文件扩展名（.csv/.json/.txt）
-
-💡 建议：
-- 大多数情况使用"auto"即可
-- 当自动检测失败时，手动指定格式
-- TXT格式会自动识别具体子格式（单列/多列/键值对）"""
-        )
-    ]
-}
-
-
-class ToolConfig:
-    """工具配置类"""
-    
-    def __init__(
-        self,
-        name: str,
-        impl_func: Callable,
-        tool_type: str,
-        description: str = "",
-        extra_params: Dict[str, Any] = None
-    ):
-        self.name = name
-        self.impl_func = impl_func
-        self.tool_type = tool_type
-        self.description = description
-        self.extra_params = extra_params or {}
-
-
-def create_tool_wrapper(config: ToolConfig):
-    """
-    创建工具包装器，自动添加文件输入支持
-    
-    Args:
-        config: 工具配置对象
-    
-    Returns:
-        包装后的工具函数
-    """
-    @econometric_tool(config.tool_type)
-    async def tool_wrapper(ctx, **kwargs):
-        """动态生成的工具包装器"""
-        # 调用实际的实现函数
-        return await config.impl_func(ctx, **kwargs)
-    
-    # 设置函数名和文档
-    tool_wrapper.__name__ = config.name
-    tool_wrapper.__doc__ = config.description
-    
-    return tool_wrapper
-
-
-# 工具类型到参数映射
-TOOL_TYPE_PARAMS = {
-    "multi_var_dict": {
-        "data": Annotated[
-            Optional[Dict[str, List[float]]],
-            Field(
-                default=None, 
-                description="""多变量数据字典
-
-📊 数据格式：
-- 键：变量名（字符串）
-- 值：数值列表（浮点数数组）
-- 结构：{"变量1": [值1, 值2, ...], "变量2": [值1, 值2, ...]}
-
-📝 要求：
-- 所有变量的数据长度必须相同
-- 数值必须是浮点数或可转换为浮点数
-- 变量名建议使用有意义的描述性名称
-- 至少需要1个变量
-
-💡 示例：
-{"GDP": [100.5, 102.3, 104.1], "CPI": [2.1, 2.3, 2.2]}
-
-🔧 用途：
-- 描述性统计分析
-- 相关性分析
-- 多变量时间序列分析"""
-            )
-        ]
-    },
-    "regression": {
-        "y_data": Annotated[
-            Optional[List[float]],
-            Field(
-                default=None, 
-                description="""因变量（被解释变量）数据
-
-📊 数据格式：
-- 一维数值列表
-- 元素类型：浮点数
-- 长度：必须与x_data的观测数一致
-
-📝 要求：
-- 不能包含缺失值（NaN）
-- 建议数据已做适当的预处理
-- 至少需要 n+2 个观测（n为自变量个数）
-
-💡 示例：
-[12.5, 13.2, 14.1, 13.8, 15.0]  # 销售额数据
-
-🔧 用途：
-- OLS回归分析的被解释变量
-- 机器学习回归的目标变量
-- 各类回归模型的预测目标"""
-            )
-        ],
-        "x_data": Annotated[
-            Optional[List[List[float]]],
-            Field(
-                default=None, 
-                description="""自变量（解释变量）数据矩阵
-
-📊 数据格式：
-- 二维数值列表
-- 外层列表：每个元素代表一个观测
-- 内层列表：每个元素代表一个自变量的值
-- 结构：[[x1_1, x2_1, ...], [x1_2, x2_2, ...], ...]
-
-📝 要求：
-- 行数（观测数）必须与y_data长度一致
-- 列数（变量数）必须在所有行保持一致
-- 不能包含缺失值
-- 数值型变量，分类变量需要先编码
-
-💡 示例：
-[[100, 50, 3],    # 观测1: 广告支出=100, 价格=50, 竞争者=3
- [120, 48, 3],    # 观测2: 广告支出=120, 价格=48, 竞争者=3
- [110, 52, 4]]    # 观测3: 广告支出=110, 价格=52, 竞争者=4
-
-🔧 用途：
-- OLS回归的自变量矩阵
-- 机器学习模型的特征矩阵
-- 多元回归分析的解释变量"""
-            )
-        ],
-        "feature_names": Annotated[
-            Optional[List[str]],
-            Field(
-                default=None, 
-                description="""自变量名称列表
-
-📝 格式：
-- 字符串列表
-- 长度必须与x_data的列数一致
-- 建议使用描述性名称
-
-💡 示例：
-["广告支出", "价格", "竞争对手数量", "促销活动"]
-
-🔧 用途：
-- 提高结果可读性
-- 便于解释模型系数
-- 用于生成可视化标签
-- 如果不提供，系统会自动生成（x1, x2, x3...）
-
-⚠️ 注意：
-- 避免使用特殊字符
-- 中英文均可
-- 建议简洁明了"""
-            )
-        ]
-    },
-    "single_var": {
-        "data": Annotated[
-            Optional[List[float]],
-            Field(
-                default=None, 
-                description="""单变量时间序列数据
-
-📊 数据格式：
-- 一维数值列表
-- 按时间顺序排列
-- 元素类型：浮点数
-
-📝 要求：
-- 数据必须按时间顺序排列
-- 不能包含缺失值
-- 建议时间间隔均匀（等间隔）
-- 至少需要5个观测点进行基本分析
-- 复杂模型（如ARIMA）建议30+观测点
-
-💡 示例：
-[100.5, 102.3, 101.8, 103.5, 104.2, 103.8, 105.1]  # 股票价格序列
-
-🔧 用途：
-- 时间序列分析
-- 平稳性检验（ADF、KPSS）
-- 自相关分析（ACF、PACF）
-- ARIMA/GARCH模型
-- 预测和趋势分析
-
-⚠️ 注意事项：
-- 确保数据按时间顺序
-- 处理缺失值和异常值
-- 考虑季节性调整
-- 检查数据平稳性"""
-            )
-        ]
-    },
-    "panel": {
-        "y_data": Annotated[
-            Optional[List[float]],
-            Field(
-                default=None, 
-                description="""面板数据因变量
-
-📊 数据格式：
-- 一维数值列表
-- 包含所有个体所有时期的观测
-- 长度 = 个体数 × 时期数
-
-📝 排列方式（可选其一）：
-1. 按个体排列：[个体1的所有时期, 个体2的所有时期, ...]
-2. 按时期排列：[时期1的所有个体, 时期2的所有个体, ...]
-3. 需与entity_ids和time_periods的排列方式一致
-
-💡 示例（3个公司，2个年份）：
-[1000, 1100, 800, 900, 1200, 1300]  # 按个体排列
-公司1: 2020=1000, 2021=1100
-公司2: 2020=800,  2021=900
-公司3: 2020=1200, 2021=1300
-
-🔧 用途：
-- 固定效应模型
-- 随机效应模型
-- 面板数据回归分析"""
-            )
-        ],
-        "x_data": Annotated[
-            Optional[List[List[float]]],
-            Field(
-                default=None, 
-                description="""面板数据自变量矩阵
-
-📊 数据格式：
-- 二维数值列表
-- 行数 = 个体数 × 时期数
-- 列数 = 自变量个数
-- 排列顺序必须与y_data一致
-
-📝 要求：
-- 与y_data的观测顺序完全对应
-- 所有行的列数必须相同
-- 不能包含缺失值
-
-💡 示例（3个公司，2年，2个自变量）：
-[[50, 100],   # 公司1-2020: 员工=50, 投资=100
- [52, 110],   # 公司1-2021: 员工=52, 投资=110
- [40, 80],    # 公司2-2020
- [42, 90],    # 公司2-2021
- [60, 150],   # 公司3-2020
- [62, 160]]   # 公司3-2021
-
-🔧 用途：
-- 面板回归的解释变量
-- 控制时变特征"""
-            )
-        ],
-        "entity_ids": Annotated[
-            Optional[List[str]],
-            Field(
-                default=None, 
-                description="""个体标识符列表
-
-📝 格式：
-- 字符串列表
-- 标识每个观测所属的个体（如公司、国家、个人）
-- 长度 = y_data长度
-
-📊 要求：
-- 每个个体的标识符在所有时期保持一致
-- 与y_data、x_data的顺序完全对应
-- 建议使用清晰的标识符
-
-💡 示例（3个公司，各2年）：
-["公司A", "公司A", "公司B", "公司B", "公司C", "公司C"]
-或
-["1", "1", "2", "2", "3", "3"]
-
-🔧 用途：
-- 识别面板数据的横截面维度
-- 计算固定效应
-- 分组和聚合
-- Hausman检验
-
-⚠️ 注意：
-- ID可以是数字或字符串
-- 但必须以字符串形式传入
-- 保持格式一致性"""
-            )
-        ],
-        "time_periods": Annotated[
-            Optional[List[str]],
-            Field(
-                default=None, 
-                description="""时间标识符列表
-
-📝 格式：
-- 字符串列表
-- 标识每个观测所属的时期
-- 长度 = y_data长度
-
-📊 要求：
-- 每个时期的标识符在所有个体保持一致
-- 与y_data、x_data的顺序完全对应
-- 建议使用标准时间格式
-
-💡 示例（3个公司，各2年）：
-["2020", "2021", "2020", "2021", "2020", "2021"]
-或
-["2020-01", "2020-02", "2020-01", "2020-02", "2020-01", "2020-02"]
-
-🔧 用途：
-- 识别面板数据的时间维度
-- 计算时间固定效应
-- 识别时间趋势
-- 面板单位根检验
-
-⚠️ 注意：
-- 可以是年份、季度、月份等
-- 必须以字符串形式传入
-- 保持格式统一"""
-            )
-        ],
-        "feature_names": Annotated[
-            Optional[List[str]],
-            Field(
-                default=None, 
-                description="""自变量名称列表（同regression类型）
-
-📝 格式：
-- 字符串列表
-- 长度 = x_data的列数
-
-💡 示例：
-["员工数", "研发投资", "市场份额", "行业集中度"]
-
-🔧 用途：
-- 提高结果可读性
-- 便于解释回归系数
-- 如不提供会自动生成"""
-            )
-        ]
-    },
-    "time_series": {
-        "data": Annotated[
-            Optional[Dict[str, List[float]]],
-            Field(
-                default=None, 
-                description="""多变量时间序列数据字典
-
-📊 数据格式：
-- 键：变量名（字符串）
-- 值：时间序列数据（浮点数列表）
-- 所有变量长度必须相同
-- 数据按时间顺序排列
-
-📝 要求：
-- 至少2个变量（VAR、VECM模型）
-- 单变量请使用single_var类型
-- 所有序列等长且按时间对齐
-- 时间间隔均匀
-- VAR模型建议40+观测
-- VECM模型建议60+观测
-
-💡 示例：
-{
-    "GDP": [100.5, 102.3, 104.1, 105.8],     # GDP增长率序列
-    "CPI": [2.1, 2.3, 2.2, 2.4],             #  CPI通胀率序列
-    "利率": [3.5, 3.6, 3.4, 3.7]             # 利率序列
-}
-
-🔧 用途：
-- VAR模型分析
-- VECM模型分析
-- 脉冲响应函数
-- 方差分解
-- Granger因果检验
-- 协整分析
-
-⚠️ 注意事项：
-- 确保所有序列时间对齐
-- 检查序列平稳性
-- VAR要求所有序列平稳
-- VECM允许非平稳序列（需协整）
-- 注意滞后阶数选择"""
-            )
-        ]
-    }
-}
-
-
-def get_tool_params(tool_type: str, extra_params: Dict[str, Any] = None) -> Dict[str, Any]:
-    """
-    获取工具的完整参数定义
-    
-    Args:
-        tool_type: 工具类型
-        extra_params: 额外的参数定义
-    
-    Returns:
-        完整的参数字典
-    """
-    params = {}
-    
-    # 添加基础参数
-    if tool_type in TOOL_TYPE_PARAMS:
-        params.update(TOOL_TYPE_PARAMS[tool_type])
-    
-    # 添加文件输入参数
-    params.update(FILE_INPUT_PARAMS)
-    
-    # 添加额外参数
-    if extra_params:
-        params.update(extra_params)
-    
-    return params