Paperbanana

PaperBanana AI 科学者向けの学術イラスト自動生成

---

免責事項：これは、論文 「PaperBanana: Automating Academic Illustration for AI Scientists」（Dawei Zhu、Rui Meng、Yale Song、 Xiyu Wei、Sujian Li、Tomas Pfister、Jinsung Yoon 著。 arXiv:2601.23265）の 非公式の、コミュニティ主導によるオープンソース実装です。 このプロジェクトは、原著者や Google Research と提携しておらず、承認も受けていません。 この実装は公開されている論文に基づいており、元のシステムとは異なる場合があります。

テキストによる説明から、出版品質の学術図や統計プロットを生成するためのエージェント型フレームワークです。OpenAI（GPT-5.2 + GPT-Image-1.5）、Azure OpenAI / Foundry、Google Gemini、Atlas Cloud の各プロバイダーに対応しています。

• 反復的な改良を行う、2 フェーズのマルチエージェントパイプライン
• 複数の VLM および画像生成プロバイダー（OpenAI、Azure、Gemini、Atlas Cloud）
• 生成品質を高める入力最適化レイヤー
• 自動改良モードと、ユーザーフィードバックを受けた実行の継続
• CLI、Python API、IDE 連携用の MCP サーバー
• バッチ生成：マニフェストファイル（YAML/JSON）から、1 回の実行で複数の図を生成
• バッチプロット — paperbanana plot-batch を実行すると、1 つのマニフェストから複数の統計プロットを生成します（各項目に CSV/JSON を指定）
• 方法論のコンテキストに使用する PDF 入力（paperbanana[pdf] / PyMuPDF は任意）。ページごとの選択にも対応
• PaperBanana Studio — ローカルの Gradio ウェブ UI（paperbanana studio）。図、プロット、評価、バッチ処理、実行履歴のブラウザー機能を利用できます
• /generate-diagram、/generate-plot、/evaluate-diagram 用の Claude Code スキル

LLM の概念を学習中ですか？ attention、RAG、エージェント、推論を扱った無料のビジュアルカード 211 枚も公開しています。 オンラインでご覧ください。

Atlas Cloud

Atlas Cloud は、動画生成、画像生成、LLM API にアクセスできる単一の AI API を開発者に提供する、フルモーダル AI 推論プラットフォームです。複数のベンダーとの連携を管理する代わりに、一度接続するだけで、あらゆるモダリティに対応した 300 以上の厳選モデルをまとめて利用できます。

Atlas Cloud の新しいコーディングプランのプロモーションをご確認ください。より手頃な価格で API をご利用いただけます： https://www.atlascloud.ai/console/coding-plan

---

クイックスタート

ブラウザーでお試しください：
Colab クイックスタートノートブックでは、 インストールから API キーの設定、図の生成までを一通り説明します。ローカル環境のセットアップは不要です。

前提条件

• 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]"

Docker

リポジトリをクローンしたディレクトリからイメージをビルドし、実行時に API キーを渡します：

docker build -t paperbanana .
docker run --rm -e GOOGLE_API_KEY paperbanana generate --help

図を生成するには、入力ファイルと出力フォルダーを /work にマウントします：

docker run --rm -e GOOGLE_API_KEY \
  -v "$(pwd)/method.txt:/work/method.txt:ro" \
  -v "$(pwd)/outputs:/work/outputs" \
  paperbanana generate --input method.txt --caption "Overview of our framework"

ステップ 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://<resource>.openai.azure.com/openai/v1
#
# Optional Gemini overrides:
#   GOOGLE_BASE_URL=https://your-gemini-proxy.example.com
#   GOOGLE_VLM_MODEL=gemini-2.5-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 に保存され、中間の反復結果とメタデータもすべて保存されます。

PaperBanana Studio（ローカルウェブ UI）

任意の 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）：

0. 入力オプティマイザーは、2 つの VLM 呼び出しを並行して実行します。
   • コンテキストエンリッチャーは、生の方法論テキストを図に適した形式（コンポーネント、フロー、グループ分け、入出力）に構成します
   • キャプションシャープナーは、曖昧なキャプションを明確な視覚仕様に変換します

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

1. リトリーバーは、エージェント／推論、ビジョン／知覚、生成／学習、科学／応用の各分野にわたる、厳選された 13 個の方法論図のセットから、最も関連性の高い参照例を選択します
2. プランナーは、取得した例を用いたインコンテキスト学習によって、対象の図の詳細なテキスト説明を生成します
3. スタイリストは、NeurIPS スタイルのガイドライン（カラーパレット、レイアウト、タイポグラフィ）を用いて、視覚的な美しさを高めるよう説明を調整します

フェーズ 2 -- 反復的な改善：

4. ビジュアライザーは、説明を画像にレンダリングします
5. クリティックは、生成された画像をソースコンテキストと照らし合わせて評価し、問題点に対処する改訂版の説明を提示します
6. ステップ 4～5 は、反復回数が固定されている場合（デフォルトは 3 回）、またはクリティックが満足するまで（--auto）繰り返されます

プロバイダー

PaperBanana は、複数の VLM プロバイダーと画像生成プロバイダーに対応しています。

コンポーネント	プロバイダー	モデル	備考
VLM（計画、評価）	OpenAI	gpt-5.2	デフォルト
画像生成	OpenAI	gpt-image-1.5	デフォルト
VLM	Atlas Cloud	deepseek-ai/DeepSeek-V3-0324	OpenAI 互換のチャットエンドポイント
画像生成	Atlas Cloud	openai/gpt-image-2/text-to-image	非同期予測 API
VLM	Google Gemini	gemini-2.5-flash	低コスト
画像生成	Google Gemini	gemini-3-pro-image-preview	1K 画像あたり $0.134
VLM／画像	OpenRouter	対応する任意のモデル	柔軟なルーティング

Azure OpenAI／Foundry のエンドポイントは自動検出されます。エンドポイントに OPENAI_BASE_URL を設定してください。 Gemini 互換のゲートウェイにも対応しています。必要に応じて GOOGLE_BASE_URL を設定してください。 Atlas Cloud では、チャットに ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1、画像生成に ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1 を使用します。

Atlas Cloud 公式サイト： https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=paperbanana

ATLASCLOUD_VLM_MODEL に推奨される Atlas LLM モデル：

• deepseek-ai/DeepSeek-V3-0324（デフォルト）
• openai/gpt-4o
• openai/gpt-4.1
• google/gemini-2.5-flash
• anthropic/claude-sonnet-4.5-20250929

これらは、Atlas Cloud API で検証済みの、安定して広く利用可能なモデルです。常に最新の全モデル一覧（300 以上）は Atlas Cloud の公式ドキュメントに記載されています。https://www.atlascloud.ai/models を参照してください。そこに記載されている任意のモデル ID を ATLASCLOUD_VLM_MODEL に指定できます。

ATLASCLOUD_IMAGE_MODEL に推奨される Atlas 画像モデル：

• openai/gpt-image-2/text-to-image
• openai/gpt-image-2/edit
• baidu/ERNIE-Image-Turbo/text-to-image
• black-forest-labs/flux-dev
• black-forest-labs/flux-schnell
• qwen/qwen-image

---

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"

# Guide generation with a reference/sketch image (repeatable)
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --image sketch.png --image prior_figure.png

フラグ	短縮形	説明
--input	-i	方法論のテキストファイルまたは PDF のパス（新規実行では必須）
--caption	-c	図のキャプション／伝達意図（新規実行では必須）
--image		プランナーの指針となる参照画像／スケッチ（手描きのスケッチ、ホワイトボードの写真、以前の図）。複数の画像を指定する場合は繰り返し指定できます
--output	-o	出力画像のパス（デフォルト：outputs/ 内に自動生成）
--iterations	-n	ビジュアライザーと批評者による改良ラウンド数（デフォルト：3）
--num-candidates	-k	候補画像を並列で N 個生成します。1～8（デフォルト：1）。プランニングは一度だけ実行され、候補ごとにシードをずらして改良を並行実行します。出力先は candidates/cand_<i>/ です。実行ルートの final_output は候補 1 です。コスト見積もりと --budget には並列生成数が反映されます
--auto		批評者が満足するまで繰り返します（安全上限として --max-iterations を指定）
--max-iterations		--auto モードの安全上限（デフォルト：30）
--optimize		並列コンテキスト拡充とキャプションの明確化により、入力を前処理します
--continue		outputs/ 内の最新の実行から続行します
--continue-run		特定の実行 ID から続行します
--feedback		実行を続行する際に批評者へ渡すユーザーフィードバック
--pdf-pages		PDF 入力のみ：ページ番号を 1 始まりで指定します（例：1-5、2,4,6-8。デフォルト：すべて）
--vlm-provider		VLM プロバイダー名（デフォルト：openai）
--vlm-model		VLM モデル名（デフォルト：gpt-5.2）
--image-provider		画像生成プロバイダー（デフォルト：openai_imagen）
--image-model		画像生成モデル（デフォルト：gpt-image-1.5）
--format	-f	出力形式：png、jpeg、webp（デフォルト：png）
--config		YAML 設定ファイルのパス（configs/config.yaml を参照）
--verbose	-v	エージェントの詳細な進行状況と所要時間を表示します
--progress-json		生成中の進行状況イベントを JSON 形式で標準出力に出力します

paperbanana plot -- 統計プロット

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

フラグ	短縮形	説明
--data	-d	データファイル（CSV または JSON）のパス（必須）
--intent		プロットの伝達意図（必須）
--output	-o	出力画像のパス
--iterations	-n	改良の反復回数（デフォルト：3）
--vlm-provider		VLM プロバイダー名
--vlm-model		VLM モデル名

プロットは VLM が生成した matplotlib コードで描画されるため、画像生成プロバイダーや認証情報は不要です。

paperbanana venues -- カスタム会場スタイルパック

--venue では、methodology_style_guide.md、plot_style_guide.md、および任意の venue.yaml を含むディレクトリである会場スタイルパックを選択します。組み込みパック（neurips、icml、acl、ieee）は PaperBanana に同梱されています。リポジトリに手を加えず、独自のパックを ~/.config/paperbanana/venues/ に追加できます（--venue-dir または PAPERBANANA_VENUE_DIR で変更できます）。

# 1. Scaffold a pack (seeds both guides from the NeurIPS templates)
paperbanana venues init mylab

# 2. Edit the style guides — or generate them from a corpus of example figures:
#    paperbanana guidelines synthesize --reference-set ./examples \
#      --output ~/.config/paperbanana/venues/mylab/methodology_style_guide.md

# 3. Use it anywhere --venue is accepted
paperbanana generate --input method.txt --caption "Overview" --venue mylab

# See everything that's available (built-in + user, with source)
paperbanana venues list

venue.yaml（すべてのフィールドは任意です）：

display_name: "My Lab Style"  # shown by `paperbanana venues list`
aspect_ratio: "16:9"          # default --aspect-ratio for this venue's runs
fonts:                        # preferred fonts, appended to the style guides
  - "Helvetica"

名前が重複する場合は組み込みパックが優先され、ユーザーパックで組み込みの会場を上書きすることはできません。不明な会場名が指定されると、両方の場所から利用可能なパックの一覧を表示して、即座にエラーになります。

paperbanana batch -- 一括生成

単一のマニフェストファイル（YAML または JSON）から複数の方法論図を生成します。各項目でパイプライン全体が実行され、出力は outputs/batch_<id>/run_<id>/ に保存されます。すべての実行の概要は batch_report.json にまとめられます。

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

マニフェスト形式（items リストを含む YAML または JSON）：

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）では、バッチの種類が存在する場合に表示されます。

スイープマニフェストを使うと、8 個のカンマ区切り CLI フラグの代わりに、スイープ計画全体を YAML／JSON として保存できます。軸フラグとは併用できません。examples/sweep_manifest.yaml を参照してください。

paperbanana sweep --manifest examples/sweep_manifest.yaml

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 の注記が含まれます。ドライランのレポートでは、簡略化された「計画済みバリアント」セクションがレンダリングされます。

フラグ	短縮形	説明
--manifest	-m	マニフェストファイルのパス（必須）
--output-dir	-o	バッチ実行の親ディレクトリ（デフォルト：outputs）
--config		設定 YAML のパス
--iterations	-n	項目ごとの改善反復回数
--optimize		各項目の入力を前処理します
--auto		項目ごとに、批評家が満足するまで繰り返します
--format	-f	出力画像形式（png、jpeg、webp）
--auto-download-data		キャッシュされていない場合、PaperBananaBench の参照セット（約 254 MB）を自動ダウンロードします

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

マニフェスト（YAML または JSON）から複数のプロットを生成します。各項目ではデータファイル（CSV または JSON）と意図を表す文字列を指定し、paperbanana plot と同様に処理します。出力は outputs/batch_<id>/run_<id>/ に保存され、図のバッチと同じ 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

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

フラグ	短縮形	説明
--manifest	-m	マニフェストのパス（必須）
--output-dir	-o	batch_* の親ディレクトリ（デフォルト：outputs）
--config		設定 YAML のパス
--vlm-provider		VLM プロバイダー（デフォルト：gemini）
--vlm-model		VLM モデルの上書き設定
--image-provider		画像生成プロバイダー
--image-model		画像生成モデル
--iterations	-n	項目ごとの改善反復回数
--auto		項目ごとに、批評家が満足するまで繰り返します
--max-iterations		--auto の安全上限
--optimize		項目ごとの入力最適化
--format	-f	png、jpeg、または webp
--save-prompts / --no-save-prompts		プロンプトを保存します（デフォルト：有効。plot と同じ）
--venue		会議スタイルパック：組み込み（neurips、icml、acl、ieee）、ユーザーパック、または custom
--aspect-ratio	-ar	マニフェストで指定されていない場合のデフォルトのアスペクト比
--verbose	-v	詳細ログを出力します

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 を使用すると、API 呼び出しを行わずに計画のみを実行し、orchestration_plan.json を確認できます。 --resume-orchestrate <id-or-path> を使用すると、チェックポイントの状態から中断したオーケストレーションを再開できます。

フラグ	説明
--paper / -p	論文ソースのパス（.txt、.md、または .pdf）
--resume-orchestrate	ID またはディレクトリを指定して既存のオーケストレーションを再開します
--retry-failed	再開時に、以前に失敗したタスクを含めます
--max-retries	最初の失敗後に各タスクで行う追加の再試行回数
--data-dir	プロットの計画に使用する CSV/JSON ファイルを含む任意のディレクトリ
--output-dir / -o	出力先の親ディレクトリ（orchestrate_* を作成します）
--max-method-figures	計画・生成する手法図の最大数
--max-plot-figures	計画・生成するプロット図の最大数
--pdf-pages	PDF 専用のページ指定（例：1-5、2,4,6-8）
--optimize	生成項目の入力最適化を有効にします
--iterations / -n	生成項目ごとの反復改良回数
--auto + --max-iterations	安全上限付きの評価器駆動型自動改良モード
--concurrency	図の並列生成ワーカー数
--format / -f	出力形式（png、jpeg、webp）
--dry-run	パッケージの計画のみを実行します。生成の呼び出しは行いません

paperbanana composite -- 複数パネル図の作成

複数の画像をつなぎ合わせ、(a)、(b)、(c) のサブパネルラベルを付けた1つの図を作成します。

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

フラグ	短縮形	説明
IMAGES		位置引数：合成する画像のパス
--layout	-l	グリッドレイアウト：RxC（例：1x3、2x2）または auto（デフォルト：auto）
--labels		カンマ区切りのラベル。ラベルを無効にする場合は none（デフォルト：自動で (a),(b),...）
--spacing	-s	パネル間のピクセル間隔（デフォルト：20）
--label-position		top または bottom（デフォルト：bottom）
--label-font-size		ラベルのフォントサイズ（デフォルト：32）
--output	-o	出力パス（デフォルト：composite_output.png）

このコマンドは既存の画像であればどれでも処理でき、API 呼び出しは不要です。また、バッチマニフェストに composite セクションが含まれている場合（上記の paperbanana batch を参照）、自動的に実行されます。

paperbanana evaluate -- 品質評価

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

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

フラグ	短縮形	説明
--generated	-g	生成画像のパス（必須）
--reference	-r	人間が作成した参照画像のパス（必須）
--context		ソースコンテキストのテキストファイルまたは PDF のパス（必須）
--caption	-c	図のキャプション（必須）
--pdf-pages		PDF コンテキストのみ：1始まりのページ指定（デフォルト：すべて）

論文に基づく階層集約により、4つの評価軸を採点します。

• 主要：忠実性、読みやすさ
• 副次：簡潔さ、美しさ

paperbanana polish -- 既存の図をブラッシュアップ

お手持ちの図を使用できます。VLM が会場のスタイルガイドに照らして図を確認し、具体的ですぐに実行できる改善案を最大 10 件提案します。その後、画像編集に対応したプロバイダーが、元の図に対してそれらを適用します（ガイド付き編集）。何が変更されたかを正確に確認できるよう、提案はコンソールに表示されます。

paperbanana polish --input figure.png
paperbanana polish --input figure.png --venue icml --iterations 2 --output polished.png

フラグ	短縮形	説明
--input	-i	既存の図の画像へのパス（必須）
--output	-o	出力先のパス（デフォルト：outputs/polish_<timestamp>/final_output.png）
--venue		会場のスタイルガイド：neurips（デフォルト）、icml、acl、ieee、custom
--iterations	-n	ブラッシュアップのラウンド数。各ラウンドでは、前の結果に対する改善案の提案と適用を行います（デフォルト：1）
--aspect-ratio	-ar	目標のアスペクト比（デフォルト：入力図の比率を維持）
--num-candidates	-k	各ラウンドの提案を並行して N 回適用します（1～8）
--budget		予算の上限（USD）。超過すると、ブラッシュアップを安全に停止します
--seed		編集を再現可能にするための乱数シード

ガイド付き画像編集に対応した画像プロバイダー（Google Gemini 画像モデル）が必要です。図がすでにスタイルガイドに準拠している場合、変更を加えずに polish を終了します。

paperbanana studio -- ローカル Web UI

pip install 'paperbanana[studio]'（Gradio）が必要です。

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

フラグ	説明
--host	バインドするアドレス（デフォルト：127.0.0.1）
--port	ポート（デフォルト：7860）
--share	一時的な公開 Gradio リンクを作成します（機密データには使用しないでください）
--config	YAML 設定ファイルへのパス
--output-dir / -o	実行時のデフォルト出力ディレクトリ
--root-path	リバースプロキシの背後で使用する場合の URL サブパス

paperbanana setup -- 初回設定

paperbanana setup

対話形式のウィザードでは、最初に公式 Gemini API を使用するかどうかを尋ねます。 公式 API を選択した場合は、デフォルトの AI Studio キー取得手順に従います。選択しない場合は、カスタムの Gemini 互換 URL と API キーを尋ねます。

paperbanana data -- 参照データセット

# Download the PaperBananaBench reference set (~254 MB, one command)
paperbanana data download

# Import plot references too (or both)
paperbanana data download --task plot
paperbanana data download --task both

# Inspect / clear the cache
paperbanana data info
paperbanana data clear

データセットは、プロジェクトがホストする GitHub リリースミラー （bench-data-v1） から提供され、展開前に SHA256 チェックサムが検証されます。PaperBananaBench の作成者に謝意を表します。ミラーには、2026-03-22 の改訂版が反映されています。データセットは ~/.cache/paperbanana/ にキャッシュされます（PAPERBANANA_CACHE_DIR で変更可能）。生成コマンドでは、初回使用時に --auto-download-data を指定して取得することもできます。

---

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 引数を受け取ります。パイプラインは各ステップ（optimizer、retriever、planner、stylist、visualizer、critic）で PipelineProgressEvent オブジェクト（stage、message、seconds、iteration、extra）を渡してコールバックを呼び出すため、エージェントに手を加えることなく、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 には、Claude Code、Cursor、または MCP 互換クライアントで使用できる MCP サーバーが含まれています。ローカルにクローンせず uvx 経由で使用するには、次の設定を追加してください。

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

11 個の MCP ツールが公開されています。generate_diagram、generate_plot、continue_run（フィードバックを任意で指定して以前の run_* を再開）、continue_diagram、continue_plot、evaluate_diagram、evaluate_plot、orchestrate_figures（論文全体の図パッケージ）、batch_diagrams、batch_plots、download_references です。

リポジトリには 3 つの Claude Code スキルも含まれています。

• /generate-diagram <file> [caption] - テキストファイルから方法論図を生成します
• /generate-plot <data-file> [intent] - CSV/JSON データから統計プロットを生成します
• /evaluate-diagram <generated> <reference> - 人間が作成した参照図に照らして図を評価します

詳しいセットアップ方法（Claude Code、Cursor、ローカル開発）については、mcp_server/README.md をご覧ください。

---

Overleaf 連携（GitHub Action）

論文の方法論図をテキストと自動的に同期します。PaperBanana には、Overleaf の組み込み GitHub 同期と連携する GitHub Action が含まれています。.tex の変更をプッシュすると、Action が方法論のセクションを抽出して図を生成し、画像とすぐに \input できる LaTeX スニペットをコミットします。Overleaf に取り込めば、ファイルツリーに表示されます。

- uses: actions/checkout@v4
- uses: llmsresearch/paperbanana/integrations/github-action@main
  with:
    tex-file: sections/method.tex
    caption: "Overview of our proposed framework"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

ワークフロー全体、すべての入力、コスト管理オプションについては、integrations/github-action/README.md をご覧ください。

---

設定

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

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

主な設定：

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

image:
  provider: openai_imagen    # openai_imagen, atlas_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

# Atlas Cloud
ATLASCLOUD_API_KEY=your-key
ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
ATLASCLOUD_VLM_MODEL=deepseek-ai/DeepSeek-V3-0324
ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1
ATLASCLOUD_IMAGE_MODEL=openai/gpt-image-2/text-to-image

# Google Gemini (alternative, free)
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # optional custom Gemini-compatible endpoint
GOOGLE_VLM_MODEL=gemini-2.5-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, Atlas Cloud, Gemini, OpenRouter VLM providers
│   │   └── image_gen/ # OpenAI, Atlas Cloud, 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

免責事項

このプロジェクトは、公開されている論文に基づく独立したオープンソースの再実装です。 原著者、Google Research、または Peking University との提携、承認、関係は一切ありません。 この実装は、論文に記載された元のシステムと異なる場合があります。 ご自身の判断でご利用ください。

ライセンス

MIT