alterlab-denario

Denario

概述

Denario（由 AstroPilot-AI 开发）是一个多 Agent AI 系统，旨在自动化科学研究工作流，从描述数据集到生成可供发表的论文。它使用 AG2 和 LangGraph 实现 Agent，并以 cmbagent 作为研究分析后端，处理假设生成、方法开发、计算分析和论文撰写。

源码：https://github.com/AstroPilot-AI/Denario | 文档：https://denario.readthedocs.io | 论文：arXiv:2510.26887（v1.0，2025 年 11 月）。

何时使用此技能

在以下情形使用此技能：

• 分析数据集，生成新颖的研究假设
• 制定结构化的研究方法
• 执行计算实验并生成可视化内容
• 搜索文献，为研究提供背景信息
• 根据研究结果撰写符合期刊格式的 LaTeX 论文
• 自动化从数据到发表的完整研究流程

不适用情形

情形	改用
没有待分析的数据集，只需撰写带引用的文献综述或事实核查	alterlab-deep-research
为你自己的论文协调研究 → 写作 → 评审 → 修改	alterlab-research-pipeline
起草或修改你自己撰写的论文（IMRaD、双语摘要）	alterlab-paper-writer
在表格数据集上通过 LLM 生成并检验假设（HypoGeniC）	alterlab-hypogenic
咨询风格的市场或行业报告	alterlab-market-research

Denario 的输出从头到尾均由 AI 生成：请将其创意、代码、结果和引用视为草稿，由研究人员核验，并在最终论文中披露 AI 辅助情况。

安装

推荐使用 uv 安装。请为 extra 加上引号，避免 zsh 将 [app] 识别为通配符：

uv init
uv add "denario[app]"

[app] extra 会安装 Streamlit GUI（DenarioApp）；无头或库模式下使用时可省略。有关 Docker 部署或从源码构建，请参阅 references/installation.md。

LLM API 配置

初始化时，Denario 会通过 KeyManager 从环境变量读取服务商密钥（无需配置对象）。相关变量如下：

• OPENAI_API_KEY — 必需（分析/结果模块需要此密钥；OpenAI 模型是 cmbagent 模式的默认模型）。
• GOOGLE_API_KEY — 可选，即 Gemini API 密钥；选择 Gemini 模型时需要此密钥（mode="fast"、check_idea 和 get_paper 的默认模型为 Gemini）。请注意，这是普通的 Gemini 密钥，不是 Vertex AI 服务账号 JSON。
• ANTHROPIC_API_KEY — 可选（Claude）。
• PERPLEXITY_API_KEY — 可选，仅用于引用搜索。

在 shell 中设置这些变量，或在工作目录下的 .env 文件中设置（KeyManager 会自行调用 load_dotenv()）。也支持将 Google Vertex AI 用作后端；相关信息以及 .env/Docker 详情请参阅 references/llm_configuration.md。

模型 ID：显式传入当前可用的模型

denario 1.0.1（当前版本；截至 2026-09，GitHub master 未发生变化）硬编码了已被服务提供商弃用的默认模型，因此请在每次调用时指定模型，而不要依赖这些默认值：

• mode="fast"（get_idea/get_method）默认使用 gemini-2.0-flash，Google 已于 2026-06-01 停用该模型——现在默认调用路径会失败。请显式传入 llm=。
• cmbagent 默认设置（mode="cmbagent" 和 get_results）使用 o3-mini（OpenAI 计划于 2026-10-23 停用），以及 gpt-4o 和 gpt-4.1；请覆盖所有使用 o3-mini 的角色：idea_hater_model、plan_reviewer_model、formatter_model，以及（在 get_results 中的）researcher_model。
• 注册表条目 "gpt-4.5"（gpt-4.5-preview）已于 2025-07-14 停用；请勿选择该模型。

字符串模型名称必须是 denario.models 中的键（例如 "gpt-4.1"、"gpt-5"、"gpt-5-mini"、"gemini-2.5-flash"、"gemini-2.5-pro"）；对于其他服务提供商的模型 ID，请传入 LLM 对象——路由依据子字符串判断（gemini → Google，gpt/o3 → OpenAI，claude → Anthropic）：

from denario import Denario, LLM

den = Denario(project_dir="./my_research")
den.get_idea(mode="fast", llm="gpt-4.1")  # a registry key the provider still serves
den.get_method(mode="fast", llm=LLM(name="gemini-3.6-flash", max_output_tokens=8192, temperature=0.7))

gemini-3.6-flash 是 Google 列出的 gemini-2.0-flash 替代模型；Google 目前仅允许现有用户使用 Gemini 2.5 系列模型，因此新的 Google 账户应使用 LLM 对象路由。长时间运行前，请检查服务提供商的模型列表——模型 ID 会不断变动。各阶段的参数请参阅 references/llm_configuration.md。

核心研究工作流

Denario 遵循结构化的四阶段研究流程：

1. 数据描述

指定可用数据和工具，以定义研究背景：

from denario import Denario

den = Denario(project_dir="./my_research")
den.set_data_description("""
Available datasets: time-series data on X and Y
Tools: pandas, sklearn, matplotlib
Research domain: [specify domain]
""")

2. 创意生成

根据数据描述生成研究假设：

den.get_idea(llm="gpt-4.1")  # pass a live model; the built-in fast-mode default is retired

此操作会基于所描述的数据生成研究问题或假设。get_idea() 和 get_method() 接受 mode 参数：mode="fast"（默认；使用 LangGraph 后端，速度更快但可靠性较低）或 mode="cmbagent"（使用 cmbagent 后端，速度较慢但可靠性较高）。也可以提供自定义创意：

den.set_idea("Custom research hypothesis")

3. 方法论制定

制定研究方法论：

den.get_method(llm="gpt-4.1")

此操作会创建一种用于研究假设的结构化方法。也可以接受包含自定义方法论的 Markdown 文件：

den.set_method("path/to/methodology.md")

4. 结果生成

执行计算实验并生成分析：

den.get_results(researcher_model="gpt-4.1", plan_reviewer_model="gpt-4.1", formatter_model="gpt-4.1")

此操作会运行方法论、执行计算、创建可视化图表并生成研究发现。也可以提供预先计算的结果：

den.set_results("path/to/results.md")

5. 论文生成

创建可供发表的 LaTeX 论文：

from denario import Journal

den.get_paper(journal=Journal.APS)

生成的论文包含符合指定期刊要求的格式、整合的图表以及完整的 LaTeX 源码。

可用期刊

get_paper(journal=...) 默认使用 Journal.NONE（纯 LaTeX，unsrt 参考文献样式）。Journal 枚举（from denario import Journal）支持：

• Journal.NONE — 通用 LaTeX，无期刊预设
• Journal.AAS — 美国天文学会（例如 ApJ）
• Journal.APS — 美国物理学会（Physical Review、PRL、PRA 等）
• Journal.ICML — 国际机器学习会议
• Journal.JHEP — 高能物理学杂志（包括 JCAP）
• Journal.NeurIPS — 神经信息处理系统大会
• Journal.PASJ — 日本天文学会刊物

启动 GUI

运行图形用户界面：

denario run

此操作会启动基于 Web 的界面，用于交互式管理研究工作流。

常见工作流

端到端研究流程

from denario import Denario, Journal

# Initialize project
den = Denario(project_dir="./research_project")

# Define research context
den.set_data_description("""
Dataset: Time-series measurements of [phenomenon]
Available tools: pandas, sklearn, scipy
Research goal: Investigate [research question]
""")

# Generate research idea and methodology (explicit models; see "Model IDs" above)
den.get_idea(llm="gpt-4.1")
den.get_method(llm="gpt-4.1")

# Execute analysis (cmbagent agents); replace the o3-mini defaults before OpenAI retires them
den.get_results(researcher_model="gpt-4.1", plan_reviewer_model="gpt-4.1", formatter_model="gpt-4.1")

# Create publication (default writer LLM is gemini-2.5-flash; pass llm= to change it)
den.get_paper(journal=Journal.APS)

混合工作流（自定义 + 自动化）

# Provide custom research idea
den.set_idea("Investigate the correlation between X and Y using time-series analysis")

# Auto-generate methodology
den.get_method(llm="gpt-4.1")

# Auto-generate results
den.get_results(researcher_model="gpt-4.1", plan_reviewer_model="gpt-4.1", formatter_model="gpt-4.1")

# Generate paper
den.get_paper(journal=Journal.APS)

文献 / 新颖性检查

使用 den.check_idea(mode="semantic_scholar")（或 mode="futurehouse"），在投入方法和结果阶段之前，检查某个创意相对于现有文献是否具有原创性。请参阅 references/examples.md。

详细参考

如需完整文档，请参阅：

• 安装选项：references/installation.md
• 大模型配置：references/llm_configuration.md
• 完整 API 参考：references/research_pipeline.md
• 工作流示例：references/examples.md

故障排除

常见问题及解决方案：

• API 密钥错误：确保正确设置了环境变量（请参阅 references/llm_configuration.md）
• LaTeX 编译：安装 TeX 发行版，或使用预装 LaTeX 的 Docker 镜像
• 软件包冲突：使用虚拟环境或 Docker 进行隔离
• Python 版本：denario 1.0.x 需要 Python 3.12 或 3.13（>=3.12,<3.14）
• KeyError: LLM '...' not available：该字符串不是 denario.models 中的键；请改为传入 LLM(...) 对象
• 提供方报告模型未找到或已弃用错误：正在使用已停用的默认模型；请传入当前可用的模型（见上文“模型 ID”）

属于 AlterLab Academic Skills 套件的一部分。