Paperbanana

🚀 PaperBanana

AI科学者のための自動学術図表作成ツールです。テキスト記述から出版品質の学術図表や統計プロットを生成します。OpenAI、Azure OpenAI / Foundry、Google Geminiなどのプロバイダをサポートします。

🚀 クイックスタート

前提条件

• Python 3.10以上
• OpenAI APIキー（platform.openai.com）またはAzure OpenAI / Foundryエンドポイント
• またはGoogle Gemini APIキー（無料、Google AI Studio）

ステップ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
# .envを編集し、APIキーを追加します。
#   OPENAI_API_KEY=your-key-here
#   GOOGLE_API_KEY=your-key-here
#
# Azure OpenAI / Foundryの場合:
#   OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1
#
# オプションのGeminiオーバーライド:
#   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_<timestamp>/final_output.pngに保存され、すべての中間反復とメタデータも保存されます。

✨ 主な機能

• 反復的なリファインを行う2段階のマルチエージェントパイプライン
• 複数のVLMと画像生成プロバイダ（OpenAI、Azure、Gemini）をサポート
• 生成品質を向上させるための入力最適化レイヤー
• 自動リファインモードとユーザーフィードバックによる実行の継続
• CLI、Python API、およびIDE統合用のMCPサーバー
• マニフェストファイル（YAML/JSON）からのバッチ生成で、一度に複数の図表を生成
• /generate-diagram、/generate-plot、/evaluate-diagramのClaude Codeスキル

🔧 技術詳細

動作原理

PaperBananaは、最大7つの専用エージェントを持つマルチエージェントパイプラインを実装しています。

フェーズ0 -- 入力最適化（オプション、--optimize）: 0. 入力オプティマイザーは2つの並列VLM呼び出しを実行します。

• コンテキストエンリッチャーは、生の手法テキストを図表に適した形式（コンポーネント、フロー、グルーピング、入出力）に構造化します。
• キャプションシャープナーは、曖昧なキャプションを正確な視覚仕様に変換します。

フェーズ1 -- 線形計画:

1. リトリーバーは、エージェント/推論、ビジョン/知覚、生成/学習、科学/アプリケーションのドメインにまたがる13の手法図表のセットから、最も関連性の高い参照例を選択します。
2. プランナーは、取得した例からのコンテキスト内学習を通じて、ターゲット図表の詳細なテキスト記述を生成します。
3. スタイリストは、NeurIPSスタイルのガイドライン（カラーパレット、レイアウト、タイポグラフィ）を使用して、記述を視覚的な美しさのために洗練します。

フェーズ2 -- 反復的なリファイン: 4. ビジュアライザーは、記述を画像にレンダリングします。 5. クリティックは、生成された画像をソースコンテキストと比較し、問題を解決するための修正された記述を提供します。 6. ステップ4-5は、固定回数（デフォルト3回）またはクリティックが満足するまで（--auto）繰り返されます。

プロバイダ

PaperBananaは、複数のVLMと画像生成プロバイダをサポートしています。

Azure OpenAI / Foundryエンドポイントは自動検出されます。OPENAI_BASE_URLをエンドポイントに設定してください。Gemini互換のゲートウェイもサポートされており、必要に応じてGOOGLE_BASE_URLを設定してください。

📚 詳細ドキュメント

CLIリファレンス

paperbanana generate -- 手法図表の生成

# 基本的な生成
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

# 入力最適化と自動リファインを使用する場合
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# 最新の実行をユーザーフィードバックで続行する場合
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

# 特定の実行を続行する場合
paperbanana generate --continue-run run_20260218_125448_e7b876 \
  --iterations 3

paperbanana plot -- 統計プロットの生成

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

paperbanana batch -- バッチ生成

単一のマニフェストファイル（YAMLまたはJSON）から複数の手法図表を生成します。各項目は完全なパイプラインを実行し、出力はoutputs/batch_<id>/run_<id>/に書き込まれ、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

マニフェスト内のパスは、マニフェストファイルのディレクトリを基準に解決されます。

既存のバッチ実行から人間が読めるレポートを生成する（MarkdownまたはHTML）:

paperbanana batch-report --batch-dir outputs/batch_20250109_123456_abc --format markdown
# またはバッチIDで（デフォルト出力ディレクトリ内）
paperbanana batch-report --batch-id batch_20250109_123456_abc --format html --output report.html

paperbanana evaluate -- 品質評価

生成された図表を人間の参照図表と比較し、VLM-as-a-Judgeを使用して評価します。

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

4つの次元でスコア付けされます（論文に従って階層的に集約）:

• 一次: 忠実性、読みやすさ
• 二次: 簡潔性、美観

paperbanana setup -- 初回設定

paperbanana setup

公式Gemini APIを使用するかどうかを最初に尋ねる対話型ウィザードです。公式APIを選択した場合、デフォルトのAI Studioキーフローに従います。そうでない場合、カスタムのGemini互換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,   # 入力最適化を有効にする
    auto_refine=True,       # クリティックが満足するまでループ
)

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}")

前回の実行を続行するには:

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には、Claude Code、Cursor、またはMCP互換クライアントで使用するためのMCPサーバーが含まれています。ローカルクローンなしでuvxを介して使用するには、以下の設定を追加します。

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

3つのMCPツールが公開されています: generate_diagram、generate_plot、evaluate_diagram。

リポジトリには3つのClaude Codeスキルも同梱されています:

• /generate-diagram <file> [caption] - テキストファイルから手法図表を生成
• /generate-plot <data-file> [intent] - CSV/JSONデータから統計プロットを生成
• /evaluate-diagram <generated> <reference> - 生成された図表を人間の参照図表と比較して評価

完全なセットアップの詳細については、を参照してください。

設定

デフォルトの設定はconfigs/config.yamlにあります。CLIフラグまたはカスタムYAMLで上書きできます。

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

主要な設定:

vlm:
  provider: openai           # openai、gemini、またはopenrouter
  model: gpt-5.2

image:
  provider: openai_imagen    # openai_imagen、google_imagen、またはopenrouter_imagen
  model: gpt-image-1.5

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # クリティックが満足するまでループ
  # max_iterations: 30       # auto_refineモードの安全上限
  # optimize_inputs: true    # 生成を改善するために入力を前処理
  output_resolution: "2k"

reference:
  path: data/reference_sets

output:
  dir: outputs
  save_iterations: true
  save_metadata: true

環境変数（.env）:

# OpenAI（デフォルト）
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1    # またはAzureエンドポイント
OPENAI_VLM_MODEL=gpt-5.2                      # モデルを上書き
OPENAI_IMAGE_MODEL=gpt-image-1.5              # モデルを上書き

# Google Gemini（代替、無料）
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # オプションのカスタムGemini互換エンドポイント
GOOGLE_VLM_MODEL=gemini-2.0-flash          # Gemini VLMモデルを上書き
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview  # Gemini画像モデルを上書き

プロジェクト構造

paperbanana/
├── paperbanana/
│   ├── core/          # パイプラインのオーケストレーション、型、設定、再開、ユーティリティ
│   ├── agents/        # オプティマイザー、リトリーバー、プランナー、スタイリスト、ビジュアライザー、クリティック
│   ├── providers/     # VLMと画像生成プロバイダの実装
│   │   ├── vlm/       # OpenAI、Gemini、OpenRouterのVLMプロバイダ
│   │   └── image_gen/ # OpenAI、Gemini、OpenRouterの画像生成プロバイダ
│   ├── reference/     # 参照セットの管理（13の精選された例）
│   ├── guidelines/    # スタイルガイドラインのローダー
│   └── evaluation/    # VLM-as-Judge評価システム
├── configs/           # YAML設定ファイル
├── prompts/           # すべてのエージェントと評価用のプロンプトテンプレート
│   ├── diagram/       # context_enricher、caption_sharpener、retriever、planner、stylist、visualizer、critic
│   ├── plot/          # プロット固有のプロンプトバリアント
│   └── evaluation/    # 忠実性、簡潔性、読みやすさ、美観
├── data/
│   ├── reference_sets/  # 13の検証済み手法図表
│   └── guidelines/      # NeurIPSスタイルの美観ガイドライン
├── examples/          # 動作例のスクリプトとサンプル入力
├── scripts/           # データのキュレーションとビルドスクリプト
├── tests/             # テストスイート
├── mcp_server/        # IDE統合用のMCPサーバー
└── .claude/skills/    # Claude Codeスキル（generate-diagram、generate-plot、evaluate-diagram）

開発

# 開発用依存関係を含めてインストール
pip install -e ".[dev,openai,google]"

# テストを実行
pytest tests/ -v

# リント
ruff check paperbanana/ mcp_server/ tests/ scripts/

# フォーマット
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

免責事項

このプロジェクトは、公開されている論文に基づく独立したオープンソースの再実装です。元の著者、Google Research、または北京大学とは一切関係がありません。実装は論文に記載された元のシステムと異なる場合があります。自己責任で使用してください。

📄 ライセンス

MIT