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

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

创建 .env 文件：

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

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

3. 运行分析

# 最简用法 — 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 文件或系统环境变量配置：

# 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 抽象类并注册即可：

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

README.md Unescape Escape

AI-Driven Data Analysis Framework

核心理念

工作流程