# DataMineAna

数学建模 MCP 工具包 -- 为大模型/Agent 提供数据预处理、数据分析、数学建模、数据可视化能力。

## 架构

```
+-----------------------------------------------+
|            Modeling Skill (上层)               |
+-----------------------------------------------+
|         MCP Client (中层)                      |
|    - 与大模型交互                              |
|    - 智能文档传递（先常用，再全量）            |
|    - 工具调用解析与转发                        |
+-----------------------------------------------+
|         MCP Server (底层)                      |
|    - 工具注册与分发（37 个工具）               |
|    - 数据预处理（38 个方法）                   |
|    - 数据分析（29 个方法）                     |
|    - 数学建模（47 个方法）                     |
|    - 数据可视化（10 种图表）                   |
|    - 高级扩展（动态方法创建）                  |
|    - 数据档案追踪（核心）                      |
|    - 缓存管理                                  |
+-----------------------------------------------+
|         UI Module (可选)                       |
|    - 交互式数据建模工作台                      |
|    - 逐步向导：加载->预处理->分析->可视化->建模->报告 |
|    - Gradio Web UI                             |
|    - 基于 MCP Server（非直接调用）             |
+-----------------------------------------------+
```

## 核心特性

### 插件化方法架构
每个方法类继承 `BaseMethod`，通过 `MethodLoader` 加载和执行。方法类不对外暴露，仅通过 Interface 访问。

```
module/
  methods/           # 方法类（隐藏）
    cleaning.py      # 相关方法分组
    transformation.py
  loader.py          # MethodLoader 子类（注册所有方法）
  interface.py       # 公开接口（集成 tracker）
```

### 数据档案追踪系统（核心）
- 每次函数调用前后自动记录输入/输出信息
- 维护全局数据档案（形状、列、类型、缺失值、统计量、列详情）
- 从数据加载到建模结束全程追踪
- `get_pipeline_report` 生成完整调用步骤（用于写论文）

### 智能文档传递
1. 初始传递：MCP_USAGE.md + COMMON_API.md（20 个常用工具）
2. 按需传递：FULL_API.md（37 个工具 + 114 个方法）

### return_mode 控制返回
每个工具支持 `return_mode` 参数控制返回内容：
- `summary`（默认）、`full`、`data`、`head`、`tail`、`sample`、`path`

### 动态方法扩展
- **高级扩展**：通过 `create_method` 传入 Python 代码字符串，动态创建新方法
- **外部扩展**：在 `src/advanced/methods/` 或 `cache/advanced/` 放入方法类文件，自动加载
- **UI 自定义**：UI 用户也可以在界面编写自定义方法

### 数据可视化
- 10 种图表类型：分布图、箱线图、散点图、热力图、混淆矩阵、ROC 曲线等
- 支持前后对比（处理前 vs 处理后）
- 图片自动保存到 `cache/plotting/`

## 目录结构

```
DataMineAna/
  src/
    common/              # 公共函数库
      base_method.py     # 方法基类（ParameterDef 支持 UI 自动表单）
      base_interface.py  # 接口基类（共享 _get_df, _make_serializable 等）
      method_loader.py   # 方法加载器
      types.py           # 类型定义
      validators.py      # 参数校验
      json_utils.py      # JSON 工具
    tracker/             # 数据档案与追踪系统（核心）
      data_profile.py    # 数据档案（含 parent_id/lineage）
      profile_manager.py # 档案管理器
      call_tracker.py    # 调用追踪器
    cache_manager/       # 缓存管理
    preprocessing/       # 数据预处理（38 个方法）
    analysis/            # 数据分析（29 个方法）
    modeling/            # 数学建模（47 个方法）
    plotting/            # 数据可视化（10 种图表）
      plotter.py         # 核心绘图引擎
      interface.py       # 可视化接口
    advanced/            # 高级扩展
      loader.py          # 动态方法加载器
      template.py        # 扩展模板
      methods/           # 内置扩展方法
    mcp_server/          # MCP Server（底层接口）
    mcp_client/          # MCP Client（中层）
    ui/                  # 交互式 UI 模块
      app.py             # Gradio 主应用
      state.py           # 会话状态（基于 MCP Server，暴露 preprocessing/analysis/modeling）
      pages/
        page_load.py     # 1. 数据加载
        page_preprocess.py # 2. 数据预处理
        page_analysis.py # 3. 数据分析
        page_plot.py     # 4. 数据可视化
        page_model.py    # 5. 模型构建
        page_report.py   # 6. 流水线报告
        components.py    # 共享 UI 组件
  cache/                 # 临时文件目录
    preprocessing/       # 预处理临时文件
    analysis/            # 分析临时文件
    modeling/            # 建模临时文件
    plotting/            # 图表临时文件
    advanced/            # 动态方法文件
    tracker/             # 追踪临时文件
    ui/                  # UI 临时文件
  docs/                  # 文档
    MCP_USAGE.md         # MCP 使用说明（传给大模型）
    COMMON_API.md        # 常用接口文档（20 个常用工具）
    FULL_API.md          # 完整接口文档（37 个工具 + 114 个方法）
  test.py               # 集成测试（26 个测试）
  test_ui.py            # UI 专项测试（4 个测试）
  run_ui.py             # UI 启动入口（含端口冲突检测）
```

## 快速开始

### MCP Server（供 Agent 使用）

```python
from src.mcp_server import MCPServer

server = MCPServer()

# 加载数据
r = server.call_tool("load_data", path="data.csv")

# 数据清洗
r = server.call_tool("clean_data", dataset_id="ds_xxx", missing_strategy="mean")

# 数据可视化
r = server.call_tool("plot_distribution", dataset_id="ds_xxx")
r = server.call_tool("plot_box", dataset_id="ds_xxx")

# 建模
r = server.call_tool("regression", dataset_id="ds_xxx", target_column="y")

# 获取完整报告
r = server.call_tool("get_pipeline_report")
```

### 交互式 UI（供人类使用）

```bash
python run_ui.py              # 默认端口 7860
python run_ui.py --port 8080  # 自定义端口
python run_ui.py --no-open    # 不自动打开浏览器
```

如果端口被占用，`run_ui.py` 会给出清晰提示而不是 traceback：
```
ERROR: Port 7860 is already in use on 127.0.0.1.
  - Stop the other process, or
  - Use a different port:  python run_ui.py --port 7861
```

UI 工作流：
1. **Load Data** - 上传数据文件
2. **Preprocess** - 清洗、变换、降维、拆分
3. **Analyze** - 描述统计、相关性、分布、假设检验
4. **Visualize** - 分布图、箱线图、散点图、热力图、前后对比
5. **Model** - 回归/分类/聚类/交叉验证/网格搜索
6. **Report** - 生成完整流水线报告

## 方法数量统计

| 模块 | 方法数 | 工具数 |
|------|--------|--------|
| 数据预处理 | 38 | 9 |
| 数据分析 | 29 | 6 |
| 数学建模 | 47 | 8 |
| 数据可视化 | 10 | 6 |
| 高级扩展 | 动态 | 2 |
| 系统工具 | - | 6 |
| **合计** | **124+** | **37** |

## 测试

```bash
# 运行完整集成测试（26 个测试：MCP 工具 + 可视化 + 高级扩展 + UI）
python test.py

# 运行 UI 专项测试（4 个测试：导入、状态、创建、启动/退出）
python test_ui.py
```

## 扩展方法

### 方式 1：继承 BaseMethod

```python
from src.common.base_method import BaseMethod, MethodResult, ParameterDef

class MyMethod(BaseMethod):
    @property
    def name(self): return "my_method"
    @property
    def description(self): return "My custom method"
    @property
    def category(self): return "custom"
    @property
    def parameters(self):
        return [
            ParameterDef(name="threshold", type="float", default=0.5, description="Threshold value"),
        ]

    def execute(self, df, **kwargs):
        threshold = kwargs.get("threshold", 0.5)
        # your logic here
        return MethodResult(df=df, success=True, message="done")
```

### 方式 2：动态创建（通过 MCP）

```python
server.call_tool("create_method", code='''
class MyMethod(BaseMethod):
    @property
    def name(self): return "my_method"
    @property
    def description(self): return "My custom method"
    def execute(self, df, **kwargs):
        return MethodResult(df=df, success=True, message="done")
''', module="preprocessing")
```

### 方式 3：放入高级扩展目录

将方法文件放入 `src/advanced/methods/`（持久化）或 `cache/advanced/`（临时），自动加载。

## 依赖

- Python >= 3.10
- pandas >= 2.0
- numpy >= 1.24
- scikit-learn >= 1.3
- scipy >= 1.11
- matplotlib >= 3.7
- seaborn >= 0.12
- gradio >= 4.0 (UI 模块)

## 许可证

MIT License