PaperBanana MCP

PaperBanana

Automated Academic Illustration for AI Scientists

______________________________________________________________________

免责声明：这是一个 非官方、社区驱动的开源实现 的论文 *PaperBanana：为人工智能科学家自动化学术插图* 朱大伟，孟睿，宋雅玲， 魏希宇、李素坚、汤玛斯、尹锦松(arXiv:2601.23265). 这个项目是 不隶属于或认可 原始作者或谷歌研究。 该实现基于公开的论文，可能与原始系统不同。

一个代理框架，用于从文本描述中生成出版质量的学术图表和统计图。支持OpenAI（GPT-5.2+GPT-Image-1.5）、Azure OpenAI/Foundry和Google Gemini提供商。

• 迭代精化的两阶段多智能体管道
• 多个VLM和映像生成提供商（OpenAI、Azure、Gemini）
• 输入优化层，提高发电质量
• 根据用户反馈自动优化模式并继续运行
• 用于IDE集成的CLI、Python API和MCP服务器
• 批量生成 从清单文件（YAML/JSON）中获取一次运行中的多个图表
• 批量绘图 — paperbanana plot-batch 从一个清单运行多个统计图（每个项目CSV/JSON）
• PDF输入 用于方法论上下文（可选 paperbanana[pdf] /PyMuPDF），每页选择
• PaperBanana工作室 --本地Gradio web UI(paperbanana studio)用于图表、绘图、评估、批处理和运行浏览器
• Claude代码技能 /generate-diagram, /generate-plot，以及 /evaluate-diagram

______________________________________________________________________

快速开始

先决条件

• Python 3.10+
• 一个OpenAI API密钥(platform.openai.com)或Azure OpenAI/Foundry端点
• 或者Google Gemini API密钥（免费， Google AI 工作室)

步骤1：安装

pip install paperbanana

或者从源代码安装以进行开发：

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"

第2步：获取API密钥

cp .env.example .env
# Edit .env and add your API key:
#   OPENAI_API_KEY=your-key-here
#   GOOGLE_API_KEY=your-key-here
#
# For Azure OpenAI / Foundry:
#   OPENAI_BASE_URL=https://.openai.azure.com/openai/v1
#
# Optional Gemini overrides:
#   GOOGLE_BASE_URL=https://your-gemini-proxy.example.com
#   GOOGLE_VLM_MODEL=gemini-2.0-flash
#   GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview

或者使用Gemini的设置向导：

paperbanana setup

步骤3：生成图表

paperbanana generate \
  --input examples/sample_inputs/transformer_method.txt \
  --caption "Overview of our encoder-decoder architecture with sparse routing"

通过输入优化和自动精炼：

paperbanana generate \
  --input my_method.txt \
  --caption "Overview of our encoder-decoder framework" \
  --optimize --auto

输出保存到 outputs/run_/final_output.png 以及所有中间迭代和元数据。

PaperBanana工作室（本地网络用户界面）

安装可选的Gradio依赖项，然后启动应用程序：

pip install 'paperbanana[studio]'
paperbanana studio

打开终端中显示的URL（默认 http://127.0.0.1:7860/).Studio公开了与CLI相同的工作流程：方法图、统计图、比较评估、继续之前的运行、批处理清单（方法或 情节 通过batch选项卡进行批处理），以及一个简单的浏览器 run_* / batch_* 输出文件夹。使用 --host, --port, --config，以及 --output-dir 根据需要。

______________________________________________________________________

运作原理

PaperBanana实现了一个多代理管道，最多有7个专门的代理：

阶段0——输入优化（可选， --optimize):

1. 输入优化器 运行两个并行VLM调用：

- 上下文丰富器 将原始方法文本结构化为图表格式（组件、流、分组、I/O） - 标题锐化器 将模糊的标题转化为精确的视觉规格

第一阶段——线性规划：

1. 检索器 从一组精心策划的13个方法论图中选择最相关的参考示例，涵盖代理/推理、视觉/感知、生成/学习和科学/应用领域
2. 规划师 通过从检索到的示例中进行上下文学习，生成目标图的详细文本描述
3. 造型师 使用NeurIPS风格指南（调色板、布局、排版）细化视觉美学的描述

第2阶段——迭代优化：

1. 可视化工具 将描述渲染为图像
2. 批评家 根据源上下文评估生成的图像，并提供修改后的描述来解决任何问题
3. 重复步骤4-5，迭代次数固定（默认为3次），或直到评论家满意为止(--auto)

提供商

PaperBanana支持多个VLM和图像生成提供商：

自动检测Azure OpenAI/Foundry终结点--设置 OPENAI_BASE_URL 到你的终点。 还支持Gemini兼容网关——set GOOGLE_BASE_URL 必要时。

______________________________________________________________________

CLI 参考

paperbanana generate --方法图

# Basic generation
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

# With input optimization and auto-refine
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# Continue the latest run with user feedback
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

# Continue a specific run
paperbanana generate --continue-run run_20260218_125448_e7b876 \
  --iterations 3

# PDF as input (install PyMuPDF: pip install 'paperbanana[pdf]')
paperbanana generate \
  --input paper.pdf \
  --caption "Overview of our method" \
  --pdf-pages "3-8"

paperbanana plot --统计图

paperbanana plot \
  --data results.csv \
  --intent "Bar chart comparing model accuracy across benchmarks"

paperbanana batch --批量生成

从单个清单文件（YAML或JSON）生成多个方法图。每个项目都运行整个管道；输出内容写在 outputs/batch_/run_/ 和一个 batch_report.json 总结所有运行。

paperbanana batch --manifest examples/batch_manifest.yaml --optimize

清单格式（YAML或JSON，带 items 列表）：

items:
  - input: path/to/method1.txt
    caption: "Overview of our encoder-decoder"
    id: fig1
  - input: method2.txt
    caption: "Training pipeline"
    id: fig2
  - input: paper.pdf
    caption: "System overview"
    id: fig3
    pdf_pages: "4-9" # optional; PDF inputs only

清单中的路径是相对于清单文件的目录解析的。

综合数字： 添加可选 composite 在批处理完成后，将所有生成的面板自动缝合成一个带标签的图形：

composite:
  layout: "1x3"          # rows x cols, or "auto"
  labels: auto            # (a), (b), (c)... or explicit list, or null
  spacing: 20             # pixels between panels
  label_position: bottom  # top or bottom
  output: "composite.png"

items:
  - input: method_encoder.txt
    caption: "Encoder architecture"
    id: panel_a
  # ...

合成图像与各个面板一起保存在批处理输出目录中。看 examples/composite_batch_manifest.yaml 举一个完整的例子。

生成人类可读的报告 从现有的批处理运行（Markdown或HTML）中：

paperbanana batch-report --batch-dir outputs/batch_20250109_123456_abc --format markdown
# or by batch ID (under default output dir)
paperbanana batch-report --batch-id batch_20250109_123456_abc --format html --output report.html

图表批处理报告包括 batch_kind: methodology；绘制批次使用 batch_kind: statistical_plot.人类可读的报告(paperbanana batch-report)显示批次类型（如果存在）。

扫描报告 由...制作 paperbanana sweep 可以以相同的方式呈现：

paperbanana sweep-report --sweep-dir outputs/sweep_20250109_123456_abc --format html
# or by sweep ID
paperbanana sweep-report --sweep-id sweep_20250109_123456_abc --format markdown

渲染的扫描报告包括摘要、前5名表格、完整变体表格（包括每个变体提供者/模型、迭代、评论家建议计数、代理评分和输出路径）以及 quality_proxy_score 注意。模拟运行报告呈现了一个简化的“计划变体”部分。

paperbanana plot-batch --批量统计图

从清单（YAML或JSON）生成多个图。每个项目指定一个 数据 文件（CSV或JSON）和 意图 字符串，镜像 paperbanana plot.输出实时 outputs/batch_/run_/ 同样的 batch_report.json 和 paperbanana batch-report 工作流作为图表批处理。

paperbanana plot-batch --manifest examples/plot_batch_manifest.yaml --optimize

清单格式(items 列表）：

items:
  - data: path/to/results.csv
    intent: "Bar chart comparing accuracy across models"
    id: fig_acc
  - data: other.json
    intent: "Scatter plot with trend line"
    aspect_ratio: "16:9"   # optional per item; CLI --aspect-ratio is the default when omitted

路径是相对于清单文件的目录解析的。

paperbanana orchestrate --全纸人像包

从完整的论文来源生成一个以出版物为重点的图表包，其中包含可选的数据驱动图。命令：

• 解析论文(.txt, .md，或 .pdf)
• 从剖面结构规划多种方法图
• 可选地发现CSV/JSON文件以计划统计图
• 运行所有计划项目的生成
• 写入包含以下内容的包文件夹 figure_package.json, figures/, figures.tex，以及 captions.md

paperbanana orchestrate \
  --paper paper.pdf \
  --data-dir ./results \
  --max-method-figures 4 \
  --max-plot-figures 3 \
  --optimize

使用 --dry-run 仅计划和检查 orchestration_plan.json 没有API调用。 使用 --resume-orchestrate 从检查点状态继续中断的编排。

paperbanana composite --组合多面板图形

将多个图像拼接成一个带有标签的图形 (a), (b), (c) 子面板标签：

paperbanana composite \
  panel_a.png panel_b.png panel_c.png \
  --layout 1x3 \
  --output figure2.png

此命令适用于任何现有的映像-不需要API调用。当批处理清单包含以下内容时，它也会自动触发 composite 部分（参见 paperbanana batch 上文）。

paperbanana evaluate --质量评估

使用VLM-as-a-Jegister对生成的图表与人类参考进行比较评估：

paperbanana evaluate \
  --generated diagram.png \
  --reference human_diagram.png \
  --context method.txt \
  --caption "Overview of our framework"

4个维度的得分（根据论文进行分层汇总）：

• 主要的，重要的：忠实、易读
• 次要的：简洁、美学

paperbanana studio --本地web UI

需要 pip install 'paperbanana[studio]' （等级）。

paperbanana studio
paperbanana studio --port 8080 --output-dir ./my_outputs

paperbanana setup --首次配置

paperbanana setup

首先询问是否使用Gemini官方API的交互式向导。 如果选择官方API，则遵循默认的AI Studio密钥流；如果不是，它要求一个自定义的Gemini-compatible URL和API密钥。

______________________________________________________________________

Python API

import asyncio
from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings

settings = Settings(
    vlm_provider="openai",
    vlm_model="gpt-5.2",
    image_provider="openai_imagen",
    image_model="gpt-image-1.5",
    optimize_inputs=True,   # Enable input optimization
    auto_refine=True,       # Loop until critic is satisfied
)

pipeline = PaperBananaPipeline(settings=settings)

result = asyncio.run(pipeline.generate(
    GenerationInput(
        source_context="Our framework consists of...",
        communicative_intent="Overview of the proposed method.",
        diagram_type=DiagramType.METHODOLOGY,
    )
))

print(f"Output: {result.image_path}")

进度回调： generate() 和 continue_run() 接受可选 progress_callback 争论。管道通过以下方式调用它 PipelineProgressEvent 每个步骤（优化器、检索器、计划器、样式器、可视化器、评论家）中的对象（阶段、消息、秒、迭代、额外），因此您可以在UI中显示进度或记录时间，而无需补丁代理。

要继续上一次运行，请执行以下操作：

from paperbanana.core.resume import load_resume_state

state = load_resume_state("outputs", "run_20260218_125448_e7b876")
result = asyncio.run(pipeline.continue_run(
    resume_state=state,
    additional_iterations=3,
    user_feedback="Make the encoder block more prominent",
))

看 examples/generate_diagram.py 和 examples/generate_plot.py 查看完整的工作示例。

______________________________________________________________________

MCP服务器

PaperBanana包含一个MCP服务器，可与Claude Code、Cursor或任何兼容MCP的客户端一起使用。添加以下配置以通过使用它 uvx 没有本地克隆：

{
  "mcpServers": {
    "paperbanana": {
      "command": "uvx",
      "args": ["--from", "paperbanana[mcp]", "paperbanana-mcp"],
      "env": { "GOOGLE_API_KEY": "your-google-api-key" }
    }
  }
}

暴露了四个MCP工具： generate_diagram, generate_plot, evaluate_diagram，以及 evaluate_plot.

回购还附带了3种克劳德代码技能：

• /generate-diagram [caption] -从文本文件生成方法图
• /generate-plot [intent] -从CSV/JSON数据生成统计图
• /evaluate-diagram -根据人类参考来评估图表

看 mcp_server/README.md 了解完整的设置细节（Claude Code、Cursor、本地开发）。

______________________________________________________________________

配置

默认设置为 configs/config.yaml.通过CLI标志或自定义YAML进行覆盖：

paperbanana generate \
  --input method.txt \
  --caption "Overview" \
  --config my_config.yaml

关键设置：

vlm:
  provider: openai           # openai, gemini, or openrouter
  model: gpt-5.2

image:
  provider: openai_imagen    # openai_imagen, google_imagen, or openrouter_imagen
  model: gpt-image-1.5

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # Loop until critic is satisfied
  # max_iterations: 30       # Safety cap for auto_refine mode
  # optimize_inputs: true    # Preprocess inputs for better generation
  output_resolution: "2k"

reference:
  path: data/reference_sets

output:
  dir: outputs
  save_iterations: true
  save_metadata: true

环境变量(.env):

# OpenAI (default)
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1    # or Azure endpoint
OPENAI_VLM_MODEL=gpt-5.2                      # override model
OPENAI_IMAGE_MODEL=gpt-image-1.5              # override model

# Google Gemini (alternative, free)
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # optional custom Gemini-compatible endpoint
GOOGLE_VLM_MODEL=gemini-2.0-flash          # override Gemini VLM model
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview  # override Gemini image model

______________________________________________________________________

项目结构

paperbanana/
├── paperbanana/
│   ├── core/          # Pipeline orchestration, types, config, resume, utilities
│   ├── agents/        # Optimizer, Retriever, Planner, Stylist, Visualizer, Critic
│   ├── providers/     # VLM and image gen provider implementations
│   │   ├── vlm/       # OpenAI, Gemini, OpenRouter VLM providers
│   │   └── image_gen/ # OpenAI, Gemini, OpenRouter image gen providers
│   ├── reference/     # Reference set management (13 curated examples)
│   ├── guidelines/    # Style guidelines loader
│   └── evaluation/    # VLM-as-Judge evaluation system
├── configs/           # YAML configuration files
├── prompts/           # Prompt templates for all agents + evaluation
│   ├── diagram/       # context_enricher, caption_sharpener, retriever, planner, stylist, visualizer, critic
│   ├── plot/          # plot-specific prompt variants
│   └── evaluation/    # faithfulness, conciseness, readability, aesthetics
├── data/
│   ├── reference_sets/  # 13 verified methodology diagrams
│   └── guidelines/      # NeurIPS-style aesthetic guidelines
├── examples/          # Working example scripts + sample inputs
├── scripts/           # Data curation and build scripts
├── tests/             # Test suite
├── mcp_server/        # MCP server for IDE integration
└── .claude/skills/    # Claude Code skills (generate-diagram, generate-plot, evaluate-diagram)

发展

# Install with dev dependencies
pip install -e ".[dev,openai,google]"

# Run tests
pytest tests/ -v

# Lint
ruff check paperbanana/ mcp_server/ tests/ scripts/

# Format
ruff format paperbanana/ mcp_server/ tests/ scripts/

引用

这是一个 非官方的 实施。如果您使用此作品，请引用 原始论文:

@article{zhu2026paperbanana,
  title={PaperBanana: Automating Academic Illustration for AI Scientists},
  author={Zhu, Dawei and Meng, Rui and Song, Yale and Wei, Xiyu
          and Li, Sujian and Pfister, Tomas and Yoon, Jinsung},
  journal={arXiv preprint arXiv:2601.23265},
  year={2026}
}

原始论文: https://arxiv.org/abs/2601.23265

免责声明

该项目是基于公开论文的独立开源重新实现。 它与原作者、谷歌研究或 北京大学无论如何。该实现可能与本文中描述的原始系统不同。 请自行决定使用。

许可证

麻省理工学院