# AI-Driven Data Analysis Framework

全自动 AI 数据分析框架。给一个 CSV 文件，AI 自主完成从数据理解到报告生成的全流程。

## 核心理念

**框架只提供引擎和工具，AI 在运行时做所有决策。**

- 没有硬编码的列名规则、数据类型判断或分析策略
- AI 只能看到元数据（表头、统计摘要、样本值），永远不接触原始数据行
- 对任意 CSV 文件自动适配，无需修改代码

## 工作流程

```
CSV 文件
  │
  ▼
[1] AI 数据理解 ─── AI 看元数据，推断数据类型、关键字段、质量评分
  │
  ▼
[2] 需求理解 ─────── 解析自然语言需求 + 可选模板，生成分析目标
  │
  ▼
[3] AI 分析规划 ──── AI 根据数据特征和工具库，生成具体任务列表
  │
  ▼
[4] AI 任务执行 ──── ReAct 模式：AI 选工具 → 调用 → 观察结果 → 决定下一步
  │
  ▼
[5] 报告生成 ─────── AI 生成图文结合的 Markdown 报告
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

创建 `.env` 文件：

```env
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4
```

支持任何 OpenAI 兼容 API（如自定义 base_url）。

### 3. 运行分析

```bash
# 最简用法 — AI 自动决定分析什么、怎么分析
python run_analysis_en.py --data your_data.csv

# 指定分析需求
python run_analysis_en.py --data sales.csv --requirement "分析各产品线的销售趋势和异常"

# 使用报告模板
python run_analysis_en.py --data tickets.csv --template templates/ticket_analysis.md

# 指定输出目录
python run_analysis_en.py --data data.csv --output my_output
```

### 4. 查看结果

每次运行会在输出目录下创建带时间戳的子目录：

```
analysis_output/
  └── run_20260309_143025/
        ├── analysis_report.md    ← 图文结合的分析报告
        └── charts/
              ├── bar_chart.png
              ├── pie_chart.png
              └── ...
```

## 项目结构

```
├── run_analysis_en.py          # 主入口（5 阶段 pipeline）
├── src/
│   ├── config.py               # 配置管理（环境变量 / JSON / .env）
│   ├── data_access.py          # 数据访问层（隐私保护，AI 不可见原始数据）
│   ├── engines/
│   │   ├── ai_data_understanding.py   # [阶段1] AI 数据理解
│   │   ├── requirement_understanding.py # [阶段2] 需求解析
│   │   ├── analysis_planning.py       # [阶段3] AI 分析规划
│   │   ├── task_execution.py          # [阶段4] ReAct 任务执行
│   │   └── report_generation.py       # [阶段5] 报告生成
│   ├── tools/
│   │   ├── base.py             # 工具抽象基类 + 注册表
│   │   ├── tool_manager.py     # 工具筛选（按数据特征过滤）
│   │   ├── query_tools.py      # 查询工具（分布、计数、时间序列、相关性）
│   │   ├── stats_tools.py      # 统计工具（描述统计、分组聚合、异常检测、趋势）
│   │   └── viz_tools.py        # 可视化工具（柱状图、折线图、饼图、热力图）
│   └── models/                 # 数据模型
│       ├── data_profile.py     # DataProfile, ColumnInfo
│       ├── requirement_spec.py # RequirementSpec, AnalysisObjective
│       ├── analysis_plan.py    # AnalysisPlan, AnalysisTask
│       └── analysis_result.py  # AnalysisResult
├── templates/                  # 报告模板（可选）
├── test_data/                  # 示例数据
└── examples/                   # 使用示例
```

## 内置工具

框架提供 12 个分析工具，AI 在运行时自主选择和组合：

| 类别 | 工具 | 说明 |
|------|------|------|
| 查询 | `get_column_distribution` | 列分布统计（值计数、百分比） |
| 查询 | `get_value_counts` | 唯一值计数 |
| 查询 | `get_time_series` | 时间序列聚合 |
| 查询 | `get_correlation` | 相关性矩阵 |
| 统计 | `calculate_statistics` | 描述性统计（均值、中位数、偏度等） |
| 统计 | `perform_groupby` | 分组聚合 |
| 统计 | `detect_outliers` | 异常值检测（IQR / Z-score） |
| 统计 | `calculate_trend` | 趋势分析（线性回归） |
| 可视化 | `create_bar_chart` | 柱状图 |
| 可视化 | `create_line_chart` | 折线图 |
| 可视化 | `create_pie_chart` | 饼图 |
| 可视化 | `create_heatmap` | 热力图 |

## 隐私保护

数据访问层（`DataAccessLayer`）是核心安全边界：

- AI **永远看不到**原始数据行
- AI 只能通过工具获取**聚合结果**（统计值、分布、图表）
- 数据画像只包含元数据：列名、数据类型、缺失率、唯一值数、样本值（最多 5 个）
- 工具返回结果自动截断（最多 100 行），防止数据泄露

## 配置

### 环境变量（推荐）

通过 `.env` 文件或系统环境变量配置：

```env
# LLM 配置（必填）
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

# 可选配置
LLM_TEMPERATURE=0.7
LLM_TIMEOUT=120
AGENT_MAX_ROUNDS=20
LOG_LEVEL=INFO
```

### JSON 配置文件

也可以使用 `config.example.json` 作为模板创建配置文件。

## 报告模板

可以提供 Markdown 模板来控制报告结构。模板中的占位符会被 AI 用实际分析数据填充。

参考 `templates/` 目录下的示例模板。

## 扩展工具

实现 `AnalysisTool` 抽象类并注册即可：

```python
from src.tools.base import AnalysisTool, register_tool

class MyCustomTool(AnalysisTool):
    @property
    def name(self) -> str:
        return "my_custom_tool"

    @property
    def description(self) -> str:
        return "工具描述（AI 会看到这段文字来决定是否使用）"

    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "column": {"type": "string", "description": "列名"}
            },
            "required": ["column"]
        }

    def execute(self, data, **kwargs) -> dict:
        # 实现分析逻辑，返回聚合结果
        return {"result": "..."}

    def is_applicable(self, data_profile) -> bool:
        return True

register_tool(MyCustomTool())
```

注册后，AI 会自动在规划和执行阶段发现并使用新工具。

## 依赖

- Python 3.10+
- pandas, numpy, matplotlib, scipy, scikit-learn
- openai（兼容任何 OpenAI API 格式的 LLM 服务）
- python-dotenv