新一代因果分析智能体
只需上传你的数据集，Causal-Agent 就能以对话的方式，自动帮你选用因果分析算法，并在生成可交互的对话面板和专业的分析报告。
Important
项目开发中
目前 CausalAgent 正在进行核心架构升级,我们正在努力完善功能，请点击右上角 Star ⭐ 关注后续更新！
新一代因果分析智能体: CausalAgent 是一个集成了AGENT的因果分析工具，它能够自动识别因果关系，生成专业的分析报告，并提供可交互的因果图谱。
缩减因果分析门槛：什么是因果？为什么需要因果分析？简单来说，因果分析就是对真实世界数据进行逻辑分析。
| 特性 | 说明 |
|---|---|
| Agent 驱动 | 基于 LangGraph 的多智能体协作，自动路由任务，无需人工干预算法细节。 |
| 动态图谱 | 摒弃静态图片，生成可交互的 Network 图谱，支持节点拖拽、点击追问。 |
| MCP 架构 | 采用 Model Context Protocol，将核心逻辑与工具解耦，极易扩展新算法。 |
| RAG 增强 | 内置因果推断领域的专业知识库，确保生成的分析报告学术性与严谨性并存。 |
| 类别 | 技术组件 |
|---|---|
| Core AI |    |
| Backend |    |
| Frontend |    |
| Tools |   |
CausalAgent 的整体因果分析流程可以抽象为：用户上传数据 → 预处理与数据体检 → 因果结构学习 → 后处理与质量提升 → 报告与可视化输出。下面按模块进行说明。
graph TD;
subgraph "User Interaction"
Human((User)) <--> UI[Web/Desktop UI]
end
subgraph "Agent Core (LangGraph)"
UI --> Router{Router Agent}
Router -->|Need Info| Pre[数据预处理 Agent]
Router -->|Analysis| Causal[因果分析 Agent]
Router -->|Report| Writer[报告生成 Agent]
Router -->|Q&A| Chat[普通对话]
Causal <--> MCP[MCP Tool Server]
Writer <--> RAG((RAG Knowledge Base))
end
subgraph "Tools & Data"
MCP --> PC[PC Algorithm]
MCP --> FCI[FCI Algorithm]
Pre --> Data[(MySQL/Files)]
end
- Router Agent：根据用户意图在「预处理 / 因果分析 / 知识库问答 / 报告生成」等节点之间自动路由，无需用户关心底层算法。
- Causal Agent：负责与 MCP 因果算法工具交互（如 PC、FCI 等），完成因果结构学习与干预效应估计的核心推理。
- Writer Agent：结合因果结果与 RAG 知识库，自动撰写结构化专业报告（背景、方法、结果、结论与局限性）。
- Chat Agent：面向一般问答与解释型对话，为非专业用户提供自然语言解释与操作指引。
进行基本的数据建模，对数据进行可视化分析，并为后续因果分析做「体检与筛选」
- 数据概览：统计数据集的行数、列数和所有字段名，生成统一的表结构摘要，帮助快速理解数据规模与字段含义。
- 列级体检与类型推断：逐列分析缺失率、唯一值、是否常数列，自动识别连续变量、分类变量、时间变量、疑似 ID 等，并给出每一列在因果分析中的适用性评级（如 excellent / good / warning）。
- 质量诊断与因果友好度评估：汇总整体缺失率，标记高缺失列和常数列，识别高基数分类、疑似 ID 等问题字段，并按适用性分组出「优先用于因果分析」的候选变量列表。
- 可视化摘要：通过直方图、箱线图、相关性热力图等可视化方式，辅助发现明显异常值和潜在共线性问题。
基于 MCP（Model Context Protocol）快速迭代因果算法
- 可插拔算法框架：通过 MCP 将因果发现与估计算法以「工具」形式解耦，便于在不改动 Agent 主逻辑的前提下扩展/更换算法库。
- 当前支持：
- PC 算法（基于条件独立检验的因果结构学习）。
- 规划中：
- FCI 等含潜在混杂的结构学习算法；
- 因果效应估计（ATE/CATE）与反事实分析等模块。
通过嵌入论文与书籍构建因果推断领域知识库，为报告和问答提供专业支撑
- 嵌入模型：目前采用
bge-small-zh-v1.5作为中文向量化模型，兼顾性能与效果。 - 知识来源：使用大量因果推断相关书籍与论文的 PDF / TXT 文档构建，涵盖经典因果图论、干预推断、工具变量、面板因果等主题。
- 典型能力：
- 在生成报告时，自动检索相关理论和方法描述，为结论补充严谨的文献背景；
- 支持面向初学者的「概念解释」，例如“什么是混杂变量”“为什么需要随机试验”等。
对因果图进行后处理，包括环路检测、边合理性评估等，提高因果结构的可解释性与可靠性
- 环路检测与修正：检查学习得到的因果图中是否存在违背 DAG（有向无环图）假设的环路；若发现异常，则调用 LLM 辅助判断合理的断边方案，给出修正建议。
- 边评估与置信度分析：对每一条因果边进行强度或置信度评估，结合数据统计特征和领域常识，对明显不合理的边进行标记与修正建议。
- 结构约束与业务先验融合：在后处理阶段支持引入业务先验（如「变量 A 不可能被 B 因果影响」），从而得到更符合领域知识的因果图。
根据后处理结果生成面向业务方与研究者的专业报告，并配套交互式可视化
- 自动生成结构化报告：围绕「分析背景 → 数据概况 → 方法说明 → 因果发现 → 结论与建议 → 局限性」等章节自动撰写自然语言报告。
- 交互式因果图谱：基于 vis-network 等前端组件生成可交互的因果图，支持节点拖拽、缩放、查看变量说明、点击追问等操作。
当前项目已经提供了完整的 Dockerfile，支持通过 Docker 运行后端服务，但暂未在公网镜像仓库发布官方镜像。
如果你已安装 Docker，可以在本地根据下面的步骤自行构建并运行镜像。
- 安装docker并且gitclone项目
git clone https://github.com/Heyflyingpig/CausalAgent- 创建.env文件,并在文件中键入以下值
# Flask 应用密钥（用于会话加密等）
SECRET_KEY=
# API 基础URL（OpenAI官方或第三方兼容接口）
BASE_URL=
MODEL=
# OpenAI API 密钥或兼容 API 的密钥
API_KEY=
# Docker环境：使用服务名 'mysql'
# 本地开发：使用 'localhost' 或 '127.0.0.1'
MYSQL_HOST=mysql
# 数据库用户名
MYSQL_USER=
MYSQL_ROOT_PASSWORD=
# 数据库密码
MYSQL_PASSWORD=
# 数据库名称
MYSQL_DATABASE=
# LangSmith API 密钥(不强制)
LANGCHAIN_API_KEY=
# LangSmith 项目名称（不强制）
LANGCHAIN_PROJECT=
- 在项目根目录运行docker-compose
docker-compose up -dImportant
知识库仍然在构建，所以知识库查询功能暂不可用
项目采用前后端分离的设计，需要同时运行后端服务和前端应用。
首先推荐创建一个环境，具体创建方式请自行查阅
-
打开命令行工具。
-
导航到您想要存放项目的目录。 （例如，如果您想放在 D 盘的 Projects 文件夹下，可以输入 cd /d D:\Projects）
-
克隆仓库: 输入以下命令并按回车：
git clone https://github.com/Heyflyingpig/CausalAgent 这将在当前目录下创建一个名为 CausalAgent 的文件夹，并下载所有项目文件。
备选方案：您也可以在 GitHub 页面上点击 "Code" -> "Download ZIP" 下载项目的压缩包，然后手动解压。
-
Python 环境: 确保你已安装 Python 3.11+。
-
MySQL 数据库: 你需要一个正在运行的 MySQL 8.0+ 实例。请预先创建一个数据库（例如，名为
causal_chat_db）并准备好其访问凭据（主机、用户名、密码）。 -
安装 Python 依赖: 克隆项目后，在项目根目录运行以下命令：
pip install -r requirements.txt
-
项目配置
在首次运行前，你必须在项目根目录下创建一个 .env 文件，用于存放所有敏感配置信息。
-
创建
.env文件。 -
将以下模板内容复制到文件中，并填入你自己的真实信息。
# Flask 应用密钥（用于会话加密等） SECRET_KEY= # API 基础URL（OpenAI官方或第三方兼容接口） BASE_URL= MODEL= # OpenAI API 密钥或兼容 API 的密钥 API_KEY= # Docker环境：使用服务名 'mysql' # 本地开发：使用 'localhost' 或 '127.0.0.1' MYSQL_HOST=mysql # 数据库用户名 MYSQL_USER= MYSQL_ROOT_PASSWORD= # 数据库密码 MYSQL_PASSWORD= # 数据库名称 MYSQL_DATABASE= # LangSmith API 密钥(不强制) LANGCHAIN_API_KEY= # LangSmith 项目名称（不强制） LANGCHAIN_PROJECT=
- 启动数据库 需要预先安装mysql数据库 在项目根目录下打开一个终端，运行以下命令：
python database_init.py
alembic upgrade headDatabase/database_init.py 负责创建数据库和基础表结构；Alembic 迁移脚本负责在此基础上做结构升级。
- 全新安装时先运行 Database/database_init.py，再执行 alembic upgrade head；
- 已有历史数据的环境只需要执行 alembic upgrade head 即可。
- 启动后端服务
在项目根目录下打开一个终端，运行以下命令：
python CausalAgent.py首次运行时，程序会自动连接到你在 secrets.json 中配置的数据库，并创建所需的表结构。你会看到 Flask 开发服务器启动的日志，它正在 http://127.0.0.1:5001 上监听。请保持此终端窗口持续运行。
- 启动前端应用
再打开一个 新的终端窗口，同样在项目根目录下，运行以下命令：
python Run_causal.py稍等片刻，一个标题为 "CausalAgent" 的桌面应用窗口将会出现，并加载应用的登录界面。现在，你可以注册并开始使用了。
- rag和知识库部分
Important
知识库仍然在构建，所以知识库查询功能暂不可用
欢迎提交 Issue 和 Pull Request！
-
Fork 本项目
-
新建 Feat_xxx 分支
-
提交代码
-
新建 Pull Request
@inproceedings{Zhu_IUI2026_CausalAgent,
author = {Zhu, JiaWei and Chen, Wei and Cai, Ruichu},
title = {CausalAgent: A Conversational Multi-Agent System for End-to-End Causal Inference},
booktitle = {Proceedings of the 2026 ACM Conference on Intelligent User Interfaces (IUI '26)},
year = {2026},
month = {March},
publisher = {ACM},
location = {Paphos, Cyprus},
doi = {10.1145/3742414.3794777},
}.
├── CausalAgent.py # Flask 入口
├── Run_causal.py # 桌面端启动入口（pywebview）
├── requirements.txt # 完整依赖
├── requirements-base.txt # 基础依赖（docker/生产使用）
├── Dockerfile
├── docker-compose.yml
├── docker-compose.prod.yml
├── README.md # 项目说明
├── database_init.log # 数据库初始化日志
├── app/ # Flask 应用主目录（Blueprint 结构）
│ ├── __init__.py # 创建 Flask app，注册蓝图
│ ├── db.py # 数据库会话与连接封装
│ ├── main/ # 通用页面相关路由
│ ├── auth/ # 登录、注册等认证相关路由
│ ├── chat/ # 聊天 & 会话相关路由与服务
│ ├── files/ # 文件上传/管理相关路由
│ └── static/ # 前端静态资源
│ ├── chat.html # 主聊天界面
│ ├── css/
│ ├── js/
│ └── generated_graphs/ # 因果图等生成图像
├── Agent/ # 因果分析与智能体核心逻辑
│ ├── causal/ # 底层因果发现算法
│ ├── causal_agent/ # langgraph/agent 状态、节点定义
│ ├── Processing/ # 数据预处理、折叠验证、可视化
│ ├── Postprocessing/ # 后处理
│ ├── Report/ # 报告生成逻辑
│ ├── knowledge_base/ # RAG 知识库
│ │ ├── build_knowledge.py
│ │ ├── db/ # 向量知识库存储
│ │ └── models/ # 嵌入模型
│ └── tool_node/ # MCP 工具节点封装（task、rag 调用等）
├── Database/ # 数据库初始化与迁移逻辑
│ ├── database_init.py # 数据库初始化脚本
│ ├── agent_connect.py # Langgraph checkpoint 相关数据库支持
│ └── migrations/ # Alembic 迁移脚本
├── config/ # 全局配置
│ └── settings.py
├── setting/ # 用户可见文档
│ ├── manual.md # 用户手册
│ └── Userprivacy.md # 用户隐私协议
├── openspec/ # 项目规范与变更说明（内部开发用）