aigroup-econ-mcp 0.6.0__tar.gz → 0.8.0__tar.gz

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: aigroup-econ-mcp
-Version: 0.6.0
-Summary: 专业计量经济学MCP工具 - 让大模型直接进行数据分析（优化版：增强工具描述，提升大模型调用体验）
+Version: 0.8.0
+Summary: 专业计量经济学MCP工具 - 让大模型直接进行数据分析（优化版：统一输出格式，增强模型说明）
 Project-URL: Homepage, https://github.com/aigroup/aigroup-econ-mcp
 Project-URL: Repository, https://github.com/aigroup/aigroup-econ-mcp.git
 Project-URL: Issues, https://github.com/aigroup/aigroup-econ-mcp/issues

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aigroup-econ-mcp"
-version = "0.6.0"
-description = "专业计量经济学MCP工具 - 让大模型直接进行数据分析（优化版：增强工具描述，提升大模型调用体验）"
+version = "0.8.0"
+description = "专业计量经济学MCP工具 - 让大模型直接进行数据分析（优化版：统一输出格式，增强模型说明）"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/src/aigroup_econ_mcp/__init__.py

@@ -10,7 +10,7 @@ AIGroup 计量经济学 MCP 服务
 - 模型诊断
 """
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 __author__ = "AIGroup"
 __description__ = "专业计量经济学MCP工具 - 让大模型直接进行数据分析（重构版：工具描述模块化）"
 

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/src/aigroup_econ_mcp/tools/ml_regularization.py

@@ -130,36 +130,50 @@ def _regularized_regression(
     elif len(feature_names) != X.shape[1]:
         raise ValueError(f"特征名称数量({len(feature_names)})与自变量数量({X.shape[1]})不匹配")
     
-    # 数据标准化
+    # 检查数据质量
+    if len(y) < 5:
+        warnings.warn(f"⚠️ 警告：样本数量较少（{len(y)}个），正则化回归可能不稳定")
+    
+    # 数据标准化 - 只标准化自变量，不标准化因变量
     scaler = StandardScaler()
     X_scaled = scaler.fit_transform(X)
-    y_scaled = (y - np.mean(y)) / np.std(y)  # 标准化因变量
     
     # 选择模型
     if model_type == "lasso":
-        model = Lasso(alpha=alpha, random_state=random_state, max_iter=10000)
+        model = Lasso(alpha=alpha, random_state=random_state, max_iter=10000, tol=1e-4)
+        # 对于Lasso，如果alpha过大，建议使用更小的值
+        if alpha > 10:
+            warnings.warn(f"⚠️ 警告：Lasso正则化参数alpha={alpha}可能过大，建议尝试更小的值（如0.1-1.0）")
     elif model_type == "ridge":
         model = Ridge(alpha=alpha, random_state=random_state)
     else:
         raise ValueError(f"不支持的模型类型: {model_type}")
     
     # 训练模型
-    model.fit(X_scaled, y_scaled)
+    try:
+        model.fit(X_scaled, y)
+    except Exception as e:
+        raise ValueError(f"{model_type}模型拟合失败: {str(e)}。建议：1) 检查数据质量 2) 尝试不同的alpha值 3) 增加样本数量")
     
     # 预测
-    y_pred_scaled = model.predict(X_scaled)
-    
-    # 将预测值转换回原始尺度
-    y_pred = y_pred_scaled * np.std(y) + np.mean(y)
+    y_pred = model.predict(X_scaled)
     
     # 计算评估指标
     r2 = r2_score(y, y_pred)
     mse = mean_squared_error(y, y_pred)
     mae = mean_absolute_error(y, y_pred)
     
+    # 检查R²是否为负值
+    if r2 < 0:
+        warnings.warn(f"⚠️ 警告：{model_type}模型的R²为负值({r2:.4f})，表明模型性能比简单均值预测更差。可能原因：1) 数据噪声过大 2) 特征与目标变量无关 3) 正则化参数过大 4) 样本量过小")
+    
     # 系数（注意：由于标准化，系数需要适当解释）
     coefficients = dict(zip(feature_names, model.coef_))
     
+    # 检查系数是否全为0（Lasso过度压缩）
+    if model_type == "lasso" and all(abs(coef) < 1e-10 for coef in model.coef_):
+        warnings.warn(f"⚠️ 警告：Lasso模型所有系数都被压缩为0，表明正则化参数alpha={alpha}可能过大，建议减小alpha值")
+    
     return RegularizedRegressionResult(
         model_type=model_type,
         r2_score=r2,

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/src/aigroup_econ_mcp/tools/panel_data.py

@@ -63,6 +63,23 @@ def prepare_panel_data(
     """
     准备面板数据格式
     
+    📊 数据格式要求：
+    - 因变量(y_data): 数值列表，如 [1.2, 3.4, 5.6, ...]
+    - 自变量(X_data): 二维数值列表，如 [[1, 2], [3, 4], [5, 6], ...]
+    - 实体ID(entity_ids): 字符串列表，标识不同个体，如 ['A', 'A', 'B', 'B', ...]
+    - 时间标识符(time_periods): 字符串或数值列表，标识时间点，如 ['2020', '2020', '2021', '2021', ...]
+    
+    💡 使用示例：
+    y_data = [10, 12, 8, 9]  # 4个观测值
+    X_data = [[1, 2], [2, 3], [1, 1], [2, 2]]  # 2个自变量，4个观测值
+    entity_ids = ['A', 'A', 'B', 'B']  # 2个实体，每个实体2个时间点
+    time_periods = ['2020', '2021', '2020', '2021']  # 2个时间点
+    
+    ⚠️ 注意事项：
+    - 确保每个实体有相同的时间点数量（平衡面板）
+    - 实体ID和时间标识符的组合必须唯一
+    - 建议至少3个实体，每个实体至少2个时间点
+    
     Args:
         y_data: 因变量数据
         X_data: 自变量数据，二维列表
@@ -73,13 +90,62 @@ def prepare_panel_data(
     Returns:
         pd.DataFrame: 面板数据格式的DataFrame
     """
-    # 数据验证
+    # 数据验证 - 提供更详细的错误信息
+    if not y_data or not X_data or not entity_ids or not time_periods:
+        raise ValueError("所有输入数据都不能为空。请提供：因变量(y_data)、自变量(X_data)、实体ID(entity_ids)、时间标识符(time_periods)")
+    
     if len(y_data) != len(X_data):
-        raise ValueError("因变量和自变量的观测数量不一致")
+        raise ValueError(f"因变量和自变量的观测数量不一致：因变量有{len(y_data)}个观测值，自变量有{len(X_data)}个观测值")
+    
     if len(y_data) != len(entity_ids):
-        raise ValueError("因变量和个体标识符数量不一致")
+        raise ValueError(f"因变量和个体标识符数量不一致：因变量有{len(y_data)}个观测值，实体ID有{len(entity_ids)}个")
+    
     if len(y_data) != len(time_periods):
-        raise ValueError("因变量和时间标识符数量不一致")
+        raise ValueError(f"因变量和时间标识符数量不一致：因变量有{len(y_data)}个观测值，时间标识符有{len(time_periods)}个")
+    
+    # 检查自变量维度一致性
+    if len(X_data) > 0:
+        first_dim = len(X_data[0])
+        for i, x_row in enumerate(X_data):
+            if len(x_row) != first_dim:
+                raise ValueError(f"自变量维度不一致：第{i}行有{len(x_row)}个变量，但第一行有{first_dim}个变量")
+    
+    # 检查面板数据平衡性
+    entity_time_counts = {}
+    for entity, time_period in zip(entity_ids, time_periods):
+        key = (entity, time_period)
+        if key in entity_time_counts:
+            raise ValueError(f"重复的实体-时间组合：实体 '{entity}' 在时间 '{time_period}' 有多个观测值")
+        entity_time_counts[key] = True
+    
+    # 检查每个实体的时间点数量
+    entity_counts = {}
+    for entity in entity_ids:
+        entity_counts[entity] = entity_counts.get(entity, 0) + 1
+    
+    unique_entities = len(entity_counts)
+    if unique_entities < 2:
+        raise ValueError(f"面板数据需要至少2个不同的实体，当前只有{unique_entities}个")
+    
+    # 检查时间点数量
+    time_counts = {}
+    for time_period in time_periods:
+        time_counts[time_period] = time_counts.get(time_period, 0) + 1
+    
+    unique_times = len(time_counts)
+    if unique_times < 2:
+        raise ValueError(f"面板数据需要至少2个不同的时间点，当前只有{unique_times}个")
+    
+    # 检查是否为平衡面板
+    time_counts_per_entity = {}
+    for entity in set(entity_ids):
+        entity_times = [time for e, time in zip(entity_ids, time_periods) if e == entity]
+        time_counts_per_entity[entity] = len(set(entity_times))
+    
+    min_times = min(time_counts_per_entity.values())
+    max_times = max(time_counts_per_entity.values())
+    if min_times != max_times:
+        warnings.warn(f"⚠️ 警告：面板数据不平衡。不同实体的时间点数量不同（最少{min_times}个，最多{max_times}个）。建议使用平衡面板数据以获得更可靠的结果。")
     
     # 处理时间标识符格式兼容性
     processed_time_periods = []

{aigroup_econ_mcp-0.6.0 → aigroup_econ_mcp-0.8.0}/src/aigroup_econ_mcp/tools/tool_descriptions.py

@@ -570,47 +570,193 @@ VARIANCE_DECOMPOSITION_ANALYSIS = ToolDescription(
 
 RANDOM_FOREST_REGRESSION_ANALYSIS = ToolDescription(
     name="random_forest_regression_analysis",
-    description="随机森林回归 - 支持文件输入",
+    description="""随机森林回归分析
+
+📊 功能说明：
+随机森林通过构建多个决策树并集成结果，能够处理复杂的非线性关系和特征交互。
+
+📈 算法特点：
+- 集成学习：多个决策树投票或平均结果
+- 稳健性：对异常值和噪声数据稳健
+- 特征重要性：自动计算特征重要性分数
+- 袋外评估：使用袋外样本进行模型评估
+- 并行训练：支持并行化训练加速
+
+💡 适用场景：
+- 复杂非线性关系建模
+- 特征交互分析
+- 稳健预测需求
+- 特征重要性评估
+- 大数据集处理
+
+⚠️ 注意事项：
+- 黑盒模型，可解释性较差
+- 内存消耗较大（树的数量多时）
+- 训练时间随树数量增加
+- 可能过度拟合噪声数据
+
+🔧 参数建议：
+- n_estimators: 树的数量，默认100
+  - 小数据集: 50-100
+  - 大数据集: 100-500
+- max_depth: 最大深度，默认None（无限制）
+  - 控制过拟合: 5-15
+  - 复杂关系: None（无限制）
+
+📋 数据要求：
+- 至少10个样本
+- 数值型和类别型数据
+- 支持缺失值处理""",
     field_descriptions={
-        "file_path": "文件路径",
-        "file_content": "文件内容",
-        "file_format": "文件格式",
-        "y_data": "因变量数据",
-        "x_data": "自变量数据",
-        "feature_names": "特征名称",
-        "n_estimators": "树的数量",
-        "max_depth": "最大深度"
-    }
+        "file_path": "CSV/JSON文件路径。CSV格式: 最后一列为因变量，其余列为自变量",
+        "file_content": "文件内容字符串。JSON格式: {'y': [因变量], 'x1': [自变量1], ...}",
+        "file_format": "文件格式: csv/json/auto",
+        "y_data": "因变量数据列表，数值格式，如 [1.2, 3.4, 5.6, ...]",
+        "x_data": "自变量数据矩阵，二维列表格式，如 [[1, 2], [3, 4], [5, 6], ...]",
+        "feature_names": "自变量名称列表，如 ['GDP', 'Population', 'Investment']",
+        "n_estimators": "决策树数量，控制模型复杂度和稳定性，默认100",
+        "max_depth": "决策树最大深度，控制过拟合，默认None（无限制）"
+    },
+    examples=[
+        "预测房价与房屋特征的非线性关系",
+        "分析消费者行为与营销变量的复杂交互",
+        "评估经济指标对股票收益的影响"
+    ],
+    use_cases=[
+        "复杂非线性关系建模",
+        "特征重要性分析",
+        "稳健预测建模",
+        "大数据集处理",
+        "集成学习应用"
+    ]
 )
 
 GRADIENT_BOOSTING_REGRESSION_ANALYSIS = ToolDescription(
     name="gradient_boosting_regression_analysis",
-    description="梯度提升树回归 - 支持文件输入",
+    description="""梯度提升树回归分析
+
+📊 功能说明：
+梯度提升树通过顺序构建决策树，每棵树修正前一棵树的错误，能够处理复杂的非线性关系。
+
+📈 算法特点：
+- 顺序学习：每棵树学习前一棵树的残差
+- 高精度：通常具有很高的预测精度
+- 特征重要性：自动计算特征重要性
+- 灵活性强：可处理各种类型的数据
+- 正则化：内置正则化防止过拟合
+
+💡 适用场景：
+- 高精度预测需求
+- 复杂非线性关系
+- 小样本高维数据
+- 竞赛和性能要求高的场景
+- 特征重要性分析
+
+⚠️ 注意事项：
+- 对参数敏感，需要仔细调优
+- 训练时间较长
+- 可能过度拟合噪声数据
+- 内存消耗较大
+
+🔧 参数建议：
+- n_estimators: 树的数量，默认100
+  - 小数据集: 50-200
+  - 大数据集: 200-1000
+- learning_rate: 学习率，默认0.1
+  - 保守学习: 0.01-0.1
+  - 快速收敛: 0.1-0.3
+- max_depth: 最大深度，默认3
+  - 简单关系: 2-4
+  - 复杂关系: 5-8
+
+📋 数据要求：
+- 至少10个样本
+- 数值型和类别型数据
+- 建议进行数据标准化""",
     field_descriptions={
-        "file_path": "文件路径",
-        "file_content": "文件内容",
-        "file_format": "文件格式",
-        "y_data": "因变量数据",
-        "x_data": "自变量数据",
-        "feature_names": "特征名称",
-        "n_estimators": "树的数量",
-        "learning_rate": "学习率",
-        "max_depth": "最大深度"
-    }
+        "file_path": "CSV/JSON文件路径。CSV格式: 最后一列为因变量，其余列为自变量",
+        "file_content": "文件内容字符串。JSON格式: {'y': [因变量], 'x1': [自变量1], ...}",
+        "file_format": "文件格式: csv/json/auto",
+        "y_data": "因变量数据列表，数值格式，如 [1.2, 3.4, 5.6, ...]",
+        "x_data": "自变量数据矩阵，二维列表格式，如 [[1, 2], [3, 4], [5, 6], ...]",
+        "feature_names": "自变量名称列表，如 ['GDP', 'Population', 'Investment']",
+        "n_estimators": "提升阶段执行的树数量，控制模型复杂度，默认100",
+        "learning_rate": "学习率，控制每棵树的贡献程度，默认0.1",
+        "max_depth": "单个回归估计器的最大深度，控制过拟合，默认3"
+    },
+    examples=[
+        "高精度预测股票价格走势",
+        "分析复杂的经济指标关系",
+        "预测消费者购买行为的精确概率",
+        "竞赛级别的预测建模"
+    ],
+    use_cases=[
+        "高精度预测建模",
+        "复杂非线性关系分析",
+        "特征重要性评估",
+        "小样本高维数据处理",
+        "竞赛级别模型构建"
+    ]
 )
 
 LASSO_REGRESSION_ANALYSIS = ToolDescription(
     name="lasso_regression_analysis",
-    description="Lasso回归 - 支持文件输入",
+    description="""Lasso回归分析
+
+📊 功能说明：
+Lasso回归使用L1正则化进行特征选择和稀疏建模，能够自动将不重要的特征系数压缩为0。
+
+📈 算法特点：
+- 特征选择：自动识别重要特征，压缩冗余特征系数为0
+- 稀疏解：产生稀疏的系数向量，提高模型可解释性
+- 处理多重共线性：对高度相关的特征进行选择
+- 正则化强度控制：通过alpha参数控制特征选择的严格程度
+
+💡 适用场景：
+- 高维数据特征选择（特征数量 > 样本数量）
+- 多重共线性问题
+- 稀疏建模需求
+- 可解释性要求高的场景
+- 变量筛选和降维
+
+⚠️ 注意事项：
+- 对alpha参数敏感，建议尝试多个值（如0.01, 0.1, 1.0, 10.0）
+- 可能过度压缩重要特征，导致信息损失
+- 需要数据标准化
+- R²为负值时表明模型性能比简单均值预测更差
+- 样本量过小时可能不稳定
+
+🔧 参数建议：
+- alpha: 正则化强度，默认1.0
+  - 小alpha(0.01-0.1): 轻微正则化，保留更多特征
+  - 中等alpha(0.1-1.0): 平衡特征选择和模型拟合
+  - 大alpha(>1.0): 强正则化，压缩更多特征
+
+📋 数据要求：
+- 至少5个样本
+- 数值型数据
+- 建议特征数量不超过样本数量的80%""",
     field_descriptions={
-        "file_path": "文件路径",
-        "file_content": "文件内容",
-        "file_format": "文件格式",
-        "y_data": "因变量数据",
-        "x_data": "自变量数据",
-        "feature_names": "特征名称",
-        "alpha": "正则化参数"
-    }
+        "file_path": "CSV/JSON文件路径。CSV格式: 最后一列为因变量，其余列为自变量",
+        "file_content": "文件内容字符串。JSON格式: {'y': [因变量], 'x1': [自变量1], ...}",
+        "file_format": "文件格式: csv/json/auto",
+        "y_data": "因变量数据列表，数值格式，如 [1.2, 3.4, 5.6, ...]",
+        "x_data": "自变量数据矩阵，二维列表格式，如 [[1, 2], [3, 4], [5, 6], ...]",
+        "feature_names": "自变量名称列表，如 ['GDP', 'Population', 'Investment']",
+        "alpha": "正则化强度参数，控制特征选择的严格程度，默认1.0。建议尝试多个值进行调优"
+    },
+    examples=[
+        "从100个经济指标中选择影响GDP增长的关键因素",
+        "在消费者行为数据中识别最重要的预测变量",
+        "处理高度相关的宏观经济变量进行预测建模"
+    ],
+    use_cases=[
+        "高维数据特征选择",
+        "变量重要性排序",
+        "多重共线性处理",
+        "稀疏线性建模",
+        "可解释机器学习"
+    ]
 )
 
 RIDGE_REGRESSION_ANALYSIS = ToolDescription(