Complete AI Data Analysis Agent implementation with 95.7% test coverage

This commit is contained in:
2026-03-07 00:04:29 +08:00
parent 621e546b43
commit 7071b1f730
245 changed files with 22612 additions and 2211 deletions

195
examples/README.md Normal file
View File

@@ -0,0 +1,195 @@
# 示例脚本说明
本目录包含三种分析模式的示例脚本,展示了如何使用真正的 AI 数据分析 Agent。
## 示例列表
### 1. 完全自主分析 (autonomous_analysis.py)
**场景**:让 AI 完全自主地分析数据,无需任何人工指导。
**特点**
- 无需指定分析需求
- 无需提供分析模板
- AI 自动识别数据类型
- AI 自主决定分析维度
- AI 动态生成分析计划
**使用方法**
```bash
# 方法1直接运行脚本
python examples/autonomous_analysis.py
# 方法2使用命令行
python -m src.main --data test_data/ticket_sample.csv --output output/autonomous
```
**适用场景**
- 快速了解新数据集
- 探索性数据分析
- 不确定分析方向时
### 2. 指定需求分析 (requirement_based_analysis.py)
**场景**:指定分析需求,让 AI 进行针对性分析。
**特点**
- 支持自然语言需求描述
- AI 理解抽象概念(如"健康度"
- AI 将需求转化为具体指标
- 生成针对性的分析报告
**使用方法**
```bash
# 方法1直接运行脚本
python examples/requirement_based_analysis.py
# 方法2使用命令行
python -m src.main \
--data test_data/ticket_sample.csv \
--requirement "分析工单健康度" \
--output output/requirement
```
**示例需求**
- "我想了解工单的健康度"
- "分析销售趋势和区域表现"
- "识别流失风险用户"
- "找出系统性能瓶颈"
**适用场景**
- 有明确分析目标
- 需要针对性洞察
- 业务问题导向的分析
### 3. 基于模板分析 (template_based_analysis.py)
**场景**:使用分析模板作为参考框架,保持报告结构一致性。
**特点**
- 使用预定义的报告模板
- AI 理解模板结构和要求
- 数据不满足时灵活调整
- 说明跳过的分析及原因
**使用方法**
```bash
# 方法1直接运行脚本
python examples/template_based_analysis.py
# 方法2使用命令行
python -m src.main \
--data test_data/ticket_sample.csv \
--template templates/ticket_analysis.md \
--output output/template
```
**可用模板**
- `templates/ticket_analysis.md` - 工单分析模板
- `templates/problem_analysis.md` - 问题分析模板
- `templates/data_analysis.md` - 通用数据分析模板
**适用场景**
- 需要标准化报告格式
- 定期生成相同结构的报告
- 团队协作需要统一格式
## 组合使用
你也可以同时使用模板和需求:
```bash
python -m src.main \
--data test_data/ticket_sample.csv \
--template templates/ticket_analysis.md \
--requirement "重点关注车门模块的远程控制问题" \
--output output/combined
```
这样可以:
- 使用模板提供报告结构
- 使用需求指定分析重点
- AI 在模板框架下进行深入分析
## 测试数据
示例脚本使用 `test_data/` 目录下的测试数据:
- `ticket_sample.csv` - 工单数据20条记录
- `sales_sample.csv` - 销售数据25条记录
- `user_sample.csv` - 用户数据20条记录
- `anomaly_sample.csv` - 包含异常的数据25条记录
## 输出结果
分析结果会保存在指定的输出目录中:
```
output/
├── autonomous/ # 自主分析结果
│ ├── report.md # 分析报告
│ └── charts/ # 生成的图表
├── requirement/ # 需求分析结果
│ ├── report.md
│ └── charts/
└── template/ # 模板分析结果
├── report.md
└── charts/
```
## 运行所有示例
如果你想运行所有示例,可以使用以下命令:
```bash
# 完全自主分析
python examples/autonomous_analysis.py
# 指定需求分析
python examples/requirement_based_analysis.py
# 基于模板分析
python examples/template_based_analysis.py
```
## 自定义示例
你可以修改示例脚本中的参数来测试不同的场景:
```python
# 修改数据文件
data_file = "your_data.csv"
# 修改需求
user_requirement = "你的分析需求"
# 修改模板
template_file = "your_template.md"
# 修改输出目录
output_dir = "your_output_dir"
```
## 注意事项
1. **环境配置**:确保已配置 `.env` 文件中的 LLM API 密钥
2. **数据格式**:数据文件应为 CSV 格式,支持 UTF-8 和 GBK 编码
3. **输出目录**:输出目录会自动创建,无需手动创建
4. **日志查看**:运行时会显示详细的分析过程日志
## 故障排除
如果遇到问题,请检查:
1. Python 版本是否为 3.8+
2. 是否安装了所有依赖:`pip install -r requirements.txt`
3. 是否配置了 `.env` 文件
4. 数据文件路径是否正确
5. 是否有足够的磁盘空间保存输出
## 更多信息
- 查看主 README`README_MAIN.md`
- 查看配置指南:`docs/configuration_guide.md`
- 查看需求文档:`.kiro/specs/true-ai-agent/requirements.md`
- 查看设计文档:`.kiro/specs/true-ai-agent/design.md`

View File

@@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""
完全自主分析示例
这个示例展示了如何让 AI 完全自主地分析数据,无需指定任何需求或模板。
AI 会自动识别数据类型、推断分析目标、生成分析计划并执行分析。
使用方法:
python examples/autonomous_analysis.py
或者使用命令行:
python -m src.main --data test_data/ticket_sample.csv --output output/autonomous
"""
import sys
import os
# 添加项目根目录到路径
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from src.main import run_analysis
from src.logging_config import setup_logging
import logging
def main():
"""运行完全自主分析"""
# 设置日志
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("完全自主分析示例")
logger.info("=" * 80)
# 配置参数
data_file = "test_data/ticket_sample.csv"
output_dir = "output/autonomous"
logger.info(f"数据文件: {data_file}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("分析模式: 完全自主")
logger.info("AI 将自动:")
logger.info(" 1. 识别数据类型(工单、销售、用户等)")
logger.info(" 2. 推断数据的业务含义")
logger.info(" 3. 自主决定分析维度和方法")
logger.info(" 4. 生成动态分析计划")
logger.info(" 5. 执行分析并生成报告")
logger.info("")
try:
# 运行分析(不指定需求和模板)
report_path = run_analysis(
data_file=data_file,
user_requirement=None, # 无需求,完全自主
template_file=None, # 无模板
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
# 显示报告预览
if os.path.exists(report_path):
with open(report_path, 'r', encoding='utf-8') as f:
content = f.read()
preview = content[:500] + "..." if len(content) > 500 else content
logger.info("")
logger.info("报告预览:")
logger.info("-" * 80)
logger.info(preview)
logger.info("-" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
sys.exit(1)
if __name__ == "__main__":
main()

View File

@@ -0,0 +1,162 @@
#!/usr/bin/env python3
"""
指定需求分析示例
这个示例展示了如何指定分析需求,让 AI 根据需求进行针对性分析。
AI 会理解抽象的需求概念(如"健康度"),并将其转化为具体的分析指标。
使用方法:
python examples/requirement_based_analysis.py
或者使用命令行:
python -m src.main --data test_data/ticket_sample.csv --requirement "分析工单健康度" --output output/requirement
"""
import sys
import os
# 添加项目根目录到路径
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from src.main import run_analysis
from src.logging_config import setup_logging
import logging
def main():
"""运行指定需求分析"""
# 设置日志
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("指定需求分析示例")
logger.info("=" * 80)
# 配置参数
data_file = "test_data/ticket_sample.csv"
user_requirement = "我想了解工单的健康度,包括关闭率、处理效率、积压情况和响应及时性"
output_dir = "output/requirement"
logger.info(f"数据文件: {data_file}")
logger.info(f"用户需求: {user_requirement}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("分析模式: 指定需求")
logger.info("AI 将:")
logger.info(" 1. 理解用户的抽象需求(健康度)")
logger.info(" 2. 将需求转化为具体指标")
logger.info(" - 关闭率")
logger.info(" - 处理效率(平均处理时长)")
logger.info(" - 积压情况(待处理工单占比)")
logger.info(" - 响应及时性")
logger.info(" 3. 生成针对性的分析计划")
logger.info(" 4. 执行分析并生成报告")
logger.info("")
try:
# 运行分析(指定需求)
report_path = run_analysis(
data_file=data_file,
user_requirement=user_requirement,
template_file=None,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
# 显示报告预览
if os.path.exists(report_path):
with open(report_path, 'r', encoding='utf-8') as f:
content = f.read()
preview = content[:500] + "..." if len(content) > 500 else content
logger.info("")
logger.info("报告预览:")
logger.info("-" * 80)
logger.info(preview)
logger.info("-" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
sys.exit(1)
def example_sales_analysis():
"""销售数据分析示例"""
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("销售数据分析示例")
logger.info("=" * 80)
data_file = "test_data/sales_sample.csv"
user_requirement = "分析销售趋势和区域表现,识别高价值客户和畅销产品"
output_dir = "output/sales_analysis"
logger.info(f"数据文件: {data_file}")
logger.info(f"用户需求: {user_requirement}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
try:
report_path = run_analysis(
data_file=data_file,
user_requirement=user_requirement,
template_file=None,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
def example_user_analysis():
"""用户数据分析示例"""
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("用户数据分析示例")
logger.info("=" * 80)
data_file = "test_data/user_sample.csv"
user_requirement = "分析用户活跃度和订阅情况,识别流失风险用户"
output_dir = "output/user_analysis"
logger.info(f"数据文件: {data_file}")
logger.info(f"用户需求: {user_requirement}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
try:
report_path = run_analysis(
data_file=data_file,
user_requirement=user_requirement,
template_file=None,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
if __name__ == "__main__":
# 运行主示例
main()
# 取消注释以运行其他示例
# example_sales_analysis()
# example_user_analysis()

View File

@@ -0,0 +1,212 @@
#!/usr/bin/env python3
"""
基于模板分析示例
这个示例展示了如何使用分析模板作为参考框架。
AI 会理解模板的结构和要求,并根据数据特征灵活调整分析内容。
使用方法:
python examples/template_based_analysis.py
或者使用命令行:
python -m src.main --data test_data/ticket_sample.csv --template templates/ticket_analysis.md --output output/template
"""
import sys
import os
# 添加项目根目录到路径
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from src.main import run_analysis
from src.logging_config import setup_logging
import logging
def main():
"""运行基于模板的分析"""
# 设置日志
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("基于模板分析示例")
logger.info("=" * 80)
# 配置参数
data_file = "test_data/ticket_sample.csv"
template_file = "templates/ticket_analysis.md"
output_dir = "output/template"
logger.info(f"数据文件: {data_file}")
logger.info(f"分析模板: {template_file}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("分析模式: 基于模板")
logger.info("AI 将:")
logger.info(" 1. 解析模板结构和要求")
logger.info(" 2. 检查数据是否满足模板要求")
logger.info(" 3. 根据数据特征灵活调整分析内容")
logger.info(" 4. 按模板结构组织报告")
logger.info(" 5. 说明哪些分析被跳过及原因")
logger.info("")
logger.info("注意如果数据缺少某些字段AI 会智能跳过相关分析")
logger.info("")
try:
# 运行分析(使用模板)
report_path = run_analysis(
data_file=data_file,
user_requirement=None,
template_file=template_file,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
# 显示报告预览
if os.path.exists(report_path):
with open(report_path, 'r', encoding='utf-8') as f:
content = f.read()
preview = content[:500] + "..." if len(content) > 500 else content
logger.info("")
logger.info("报告预览:")
logger.info("-" * 80)
logger.info(preview)
logger.info("-" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
sys.exit(1)
def example_problem_analysis():
"""问题分析模板示例"""
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("问题分析模板示例")
logger.info("=" * 80)
data_file = "test_data/anomaly_sample.csv"
template_file = "templates/problem_analysis.md"
output_dir = "output/problem_analysis"
logger.info(f"数据文件: {data_file}")
logger.info(f"分析模板: {template_file}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("这个示例使用包含异常的数据集AI 将:")
logger.info(" 1. 识别数据中的异常模式")
logger.info(" 2. 分析异常的分布和影响")
logger.info(" 3. 推断可能的根本原因")
logger.info(" 4. 提供解决方案建议")
logger.info("")
try:
report_path = run_analysis(
data_file=data_file,
user_requirement=None,
template_file=template_file,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
def example_data_analysis():
"""通用数据分析模板示例"""
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("通用数据分析模板示例")
logger.info("=" * 80)
data_file = "test_data/sales_sample.csv"
template_file = "templates/data_analysis.md"
output_dir = "output/data_analysis"
logger.info(f"数据文件: {data_file}")
logger.info(f"分析模板: {template_file}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("这个示例使用通用数据分析模板,适用于各种数据类型")
logger.info("")
try:
report_path = run_analysis(
data_file=data_file,
user_requirement=None,
template_file=template_file,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
def example_combined_analysis():
"""组合模式:模板 + 需求"""
setup_logging()
logger = logging.getLogger(__name__)
logger.info("=" * 80)
logger.info("组合模式示例:模板 + 需求")
logger.info("=" * 80)
data_file = "test_data/ticket_sample.csv"
template_file = "templates/ticket_analysis.md"
user_requirement = "重点关注车门模块的远程控制问题,进行深入的根因分析"
output_dir = "output/combined_analysis"
logger.info(f"数据文件: {data_file}")
logger.info(f"分析模板: {template_file}")
logger.info(f"用户需求: {user_requirement}")
logger.info(f"输出目录: {output_dir}")
logger.info("")
logger.info("这个示例同时使用模板和需求:")
logger.info(" - 模板提供报告结构框架")
logger.info(" - 需求指定分析重点和深度")
logger.info(" - AI 会在模板框架下进行针对性深入分析")
logger.info("")
try:
report_path = run_analysis(
data_file=data_file,
user_requirement=user_requirement,
template_file=template_file,
output_dir=output_dir
)
logger.info("")
logger.info("=" * 80)
logger.info("分析完成!")
logger.info(f"报告已生成: {report_path}")
logger.info("=" * 80)
except Exception as e:
logger.error(f"分析失败: {e}", exc_info=True)
if __name__ == "__main__":
# 运行主示例
main()
# 取消注释以运行其他示例
# example_problem_analysis()
# example_data_analysis()
# example_combined_analysis()