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

aigroup_econ_mcp/tools/tool_registry.py

@@ -7,7 +7,7 @@ from typing import Dict, Any, Optional, List, Callable
 from pydantic import Field
 from typing import Annotated
 
-from .decorators import econometric_tool
+from .base import with_file_support_decorator as econometric_tool
 
 
 # 标准文件输入参数定义
@@ -16,28 +16,53 @@ FILE_INPUT_PARAMS = {
         Optional[str],
         Field(
             default=None,
-            description="""CSV或JSON文件内容
+            description="""CSV、JSON或TXT文件内容
 
 📁 支持格式：
-- CSV: 带表头的列数据，自动检测分隔符
+- CSV: 带表头的列数据，自动检测分隔符（逗号、制表符、分号等）
 - JSON: {"变量名": [数据], ...} 或 [{"变量1": 值, ...}, ...]
+- TXT: 支持多种格式
+  * 单列数值：每行一个数值
+  * 多列数值：空格或制表符分隔，可带表头
+  * 键值对：变量名: 值列表 或 变量名 = 值列表
 
 💡 使用方式：
-- 提供文件内容字符串
-- 系统会自动解析并识别变量
-- 优先使用file_content，如果提供则忽略其他数据参数"""
+- 提供文件内容字符串（可以是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="""文件格式
+            description="""文件格式类型
 
 可选值：
-- "auto": 自动检测（默认）
-- "csv": CSV格式
-- "json": JSON格式"""
+- "auto": 自动检测（默认，推荐）- 根据文件内容智能识别格式
+- "csv": CSV格式 - 逗号、制表符或分号分隔的表格数据
+- "json": JSON格式 - 结构化JSON数据
+- "txt": TXT格式 - 纯文本数据，支持多种子格式
+
+🔍 自动检测规则：
+1. 尝试解析JSON格式
+2. 检测CSV特征（逗号、制表符）
+3. 检测TXT特征（纯数值、键值对、空格分隔）
+4. 根据文件扩展名（.csv/.json/.txt）
+
+💡 建议：
+- 大多数情况使用"auto"即可
+- 当自动检测失败时，手动指定格式
+- TXT格式会自动识别具体子格式（单列/多列/键值对）"""
         )
     ]
 }
@@ -89,55 +114,338 @@ TOOL_TYPE_PARAMS = {
     "multi_var_dict": {
         "data": Annotated[
             Optional[Dict[str, List[float]]],
-            Field(default=None, description="数据字典，格式为 {变量名: [数值列表]}")
+            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="因变量数据")
+            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="自变量数据")
+            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="特征名称")
+            Field(
+                default=None, 
+                description="""自变量名称列表
+
+📝 格式：
+- 字符串列表
+- 长度必须与x_data的列数一致
+- 建议使用描述性名称
+
+💡 示例：
+["广告支出", "价格", "竞争对手数量", "促销活动"]
+
+🔧 用途：
+- 提高结果可读性
+- 便于解释模型系数
+- 用于生成可视化标签
+- 如果不提供，系统会自动生成（x1, x2, x3...）
+
+⚠️ 注意：
+- 避免使用特殊字符
+- 中英文均可
+- 建议简洁明了"""
+            )
         ]
     },
     "single_var": {
         "data": Annotated[
             Optional[List[float]],
-            Field(default=None, description="时间序列数据")
+            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="因变量数据")
+            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="自变量数据")
+            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="个体标识符")
+            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="时间标识符")
+            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="特征名称")
+            Field(
+                default=None, 
+                description="""自变量名称列表（同regression类型）
+
+📝 格式：
+- 字符串列表
+- 长度 = x_data的列数
+
+💡 示例：
+["员工数", "研发投资", "市场份额", "行业集中度"]
+
+🔧 用途：
+- 提高结果可读性
+- 便于解释回归系数
+- 如不提供会自动生成"""
+            )
         ]
     },
     "time_series": {
         "data": Annotated[
             Optional[Dict[str, List[float]]],
-            Field(default=None, description="多变量时间序列数据")
+            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允许非平稳序列（需协整）
+- 注意滞后阶数选择"""
+            )
         ]
     }
 }