OpenDsStar

DS-STAR（Data Science - Structured Thought and Action，即“数据科学 - 结构化思考与行动”）是一个开源的、基于 Python 的智能体（agentic）框架，旨在完全自动化复杂的数据科学任务。该框架基于谷歌研究（Google Research）的论文 [[DS-STAR]]: A State-of-the-Art Versatile Data Science Agent，它协调了一个由专业 AI 智能体组成的协作网络，用以分析数据、生成代码并迭代优化解决方案，从而回答用户的查询。

DS-Star GitHub 项目概述

• 智能体工作流：实现了一个由专业 AI 智能体（分析器 Analyzer、规划器 Planner、编码器 Coder、验证器 Verifier、路由程序 Router、调试器 Debugger 和终结器 Finalyzer）协同工作的流水线，以解决复杂的数据科学任务。
• 完全可复现性：执行的每个阶段都保存在本地——包括提示词、生成的 Python 代码、执行结果和元数据——从而实现完全的可审计性。
• 交互式与可恢复性：执行运行可以暂停和恢复。交互模式允许在进入下一阶段之前进行人机协同的逐步评估。
• 代码编辑与调试：允许用户在运行期间手动编辑生成的 Python 代码，并配有自动调试智能体以动态解决代码执行错误。
• 配置驱动：项目配置、模型参数和全局运行配置可通过集中的 config.yaml 文件轻松管理。

DS-STAR 流水线主要分三个阶段执行：

1. 分析：Analyzer（分析器）智能体检查初始数据集文件（例如 CSV、Excel）并生成描述性摘要。
2. 迭代规划与执行：
   • Planner（规划器）创建初始的逐步计划以回答用户的提示。
   • Coder（编码器）生成 Python 代码以执行该计划的当前步骤。
   • 系统运行生成的代码并捕获输出。
   • 如果代码运行失败，自动 Debugger（调试器）智能体尝试修复逻辑和语法错误。
   • Verifier（验证器）检查执行结果是否充分回答了目标查询。
   • Router（路由程序）决定下一步：要么结束工作流，要么循环返回以添加优化步骤。该循环将持续运行，直到计划完成或达到最大优化轮数限制。
3. 终结：Finalyzer（终结器）接收最终的代码执行结果，并将其打包成整洁、指定的输出结构（如 JSON）。

运行期间生成的所有构件都会使用唯一的 run_id 结构化地保存在 runs/ 目录下。

/
├─── dsstar.py               # Main script containing the agent logic and CLI
├─── config.yaml             # Main configuration file
├─── prompt.yaml             # Prompts for the different AI agents
├─── pyproject.toml          # Project metadata and dependencies (uv format)
├─── uv.lock                 # Locked dependency versions for reproducibility
├─── .python-version         # Python version specification for uv
├─── data/                   # Directory for your data files
└─── runs/                   # Directory where all experiment runs and artifacts are stored

• Python 3.11+
• 谷歌 Gemini 模型（或其他受支持的提供商）的 API 密钥
• uv 包管理器（推荐用于快速解析依赖关系）

要在本地使用 uv 设置项目：

# Clone the repository
git clone https://github.com/JulesLscx/DS-Star.git
cd DS-Star

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv
uv sync

1. 设置您的 API 密钥： 将您的 Gemini API 密钥设置为环境变量：

   export GEMINI_API_KEY='your-api-key'
   

   或者，您也可以直接将其添加到 config.yaml 文件中。

2. 自定义 config.yaml： 在项目根目录下创建一个 config.yaml 文件以自定义模型参数：

   # config.yaml
   model_name: 'gemini-1.5-flash'
   max_refinement_rounds: 5
   interactive: false
   # api_key: 'your-api-key' # Alternatively, place it here
   
   # Optional: Configure specific models for different agents
   agent_models:
     PLANNER: 'gpt-4'
     CODER: 'gemini-1.5-pro'
     VERIFIER: 'gemini-1.5-flash'
   

将您的目标数据文件（例如 .xlsx、.csv）放入 /data 目录中。

• 启动新运行：通过 CLI 提供目标文件和查询。

  uv run python dsstar.py --data-files file1.xlsx file2.xlsx --query "What is the total sales for each department?"
  

• 恢复运行：如果智能体流水线中断，可以使用其唯一的 run_id 恢复它。

  uv run python dsstar.py --resume <run_id>
  

• 运行中编辑代码：您可以手动修改最后生成的一块代码并重新运行。这对于自定义调整或手动调试非常有用。

  uv run python dsstar.py --edit-last --resume <run_id>
  

  注意：此命令会在系统的默认文本编辑器（如 nano、vim）中打开代码文件。保存并关闭编辑器将触发脚本运行更新后的代码。
• 交互模式：在执行前逐步并手动批准每个阶段：

  uv run python dsstar.py --interactive --data-files file1.csv --query "Analyze the year-over-year growth rate"
  

以下设置可通过 config.yaml 进行配置，也可以直接使用 CLI 参数进行覆盖：

DS-STAR 支持多种 AI 模型后端。每个提供商都需要相应的环境变量：

• 提供商标识符：默认提供商（不需要前缀）
• 环境变量：export GEMINI_API_KEY='your-gemini-api-key'
• 模型示例：gemini-2.5-pro、gemini-2.0-flash、gemini-1.5-pro

• 提供商标识符：以 gpt 或 o1 为前缀的模型
• 环境变量：export OPENAI_API_KEY='your-openai-api-key'
• 模型示例：gpt-4、gpt-4-turbo、o1

• 提供商标识符：以 ollama/ 为前缀的模型
• 环境变量：

  export OLLAMA_API_KEY='your-ollama-api-key'  # Optional
  export OLLAMA_HOST='http://localhost:11434'  # Optional, defaults to localhost
  

• 模型示例：ollama/llama3、ollama/qwen3-coder

本项目使用快速 Python 打包工具 uv 进行依赖关系解析。

• 性能：通过 uv 解析的安装速度比标准 pip 快 10 到 100 倍。
• 确定性构建：锁文件（Lockfile）保障了环境的稳定性。
• 无缝执行：无需激活虚拟环境；命令使用 uv run 原生执行。

• 安装依赖关系：uv sync
• 添加依赖关系：uv add <package-name>
• 删除依赖关系：uv remove <package-name>
• 更新包：uv sync --upgrade
• 运行脚本：uv run python <script.py>
• 显示当前环境的包：uv pip list

欢迎大家做出贡献！如果您发现任何 Bug 或有功能请求，请随时直接在 JulesLscx/DS-Star GitHub 仓库上提交 Pull Request 或创建 Issue。

• 多智能体协调：实现专业化的角色（规划、编码、调试和验证）协同工作，以提供高度可靠的数据科学执行。
• 人机协同（Developer-in-the-Loop）：提供灵活的手动代码干预、交互式提示词验证和结构化错误修正。
• 可审计性与日志记录：跟踪执行历史记录，并将物理流水线构件保留在本地运行日志中。
• 多提供商灵活性：与 Google Gemini、OpenAI 和本地 Ollama 模型无缝集成。