paperbanana

paperbanana — ルーティング優先の学術イラスト生成

キーワード：paperbanana · methodology diagram · statistical plot · figure evaluation · plan-then-refine

これは、PaperBanana 論文（arXiv:2601.23265）の非公式コミュニティ実装です。 各プロバイダーの規約、API の予算、各会議の図版の利用・再利用ポリシーを遵守してください。

PaperBanana は、2段階のマルチエージェント型、計画してから改善するパイプラインで、テキストや論文を出版品質の図に変換します。常に生成ループをフルで実行するのではなく、実用可能な最小モードを選ぶと、特に効果を発揮します。

• 画像生成クレジットを使う前に、plot でデータ駆動型のグラフを描画します（matplotlib コードを使用し、画像生成用キーは不要です）
• 最初から再生成する前に、polish または evaluate で既存の図を修正します
• バッチ／スイープ／オーケストレーションに進む前に、generate で図を1つ生成します
• 反復回数、候補数、--optimize の利用は、デフォルトではなく根拠に基づいて増やします
• 生成図が適切な手段ではない場合は、ベクターエディター、TikZ、または人間のデザイナーに切り替えます

このスキルを使う場面

• ユーザーが .txt、.md、または .pdf から方法論／アーキテクチャ図を求めており、最も軽量な生成経路を選ぶ必要がある場合
• ユーザーが表形式の結果（CSV/JSON）を持っており、グラフを求めている場合 — 画像生成プロバイダーが不要なため、図より低コストです
• ユーザーがすでに図を持っており、作り直すのではなく、評価（evaluate）または改善（polish）を求めている場合
• ユーザーが多数の図を必要としている場合（マニフェストによるバッチ処理、パラメータースイープ、論文全体の図一式）
• ユーザーが MCP サーバーまたは Claude Code スキル経由で、PaperBanana をエージェント／IDE から利用したい場合
• ユーザーがすべての図を手描きにしようとしたり、特定のプロバイダーにハードコードしようとしたり、反復回数や候補数を最大にしようとしたりしており、適切な別の手段が必要な場合

手順

ステップ1：モードを選ぶ前に、必要事項をまとめる

必要最小限の情報を集めます。

• 成果物の種類：方法論図、統計グラフ、修正／評価対象の既存図、複数の図、または論文全体の図一式
• ソース：生の手法テキスト、論文（.pdf／.md）、データファイル（CSV/JSON）、または既存の画像
• 予算／キー：利用可能なプロバイダーキー（VLM のみか、画像生成も利用可能か）と、USD の上限
• 品質要件：簡易ドラフト、評価者が満足するまでの自動改善、または複数候補の並列生成

次の段階的な選択肢を使ってください（上から順に軽量です）。

1. データからグラフを作成しますか？ plot／plot-batch を使います（VLM が matplotlib を生成し、画像生成用キーは不要です）
2. テキスト／PDF から図を1つ作成しますか？ generate を使います
3. すでに図がありますか？ 新たに実行するのではなく、evaluate（評価）または polish（ガイド付き編集）を使います
4. マニフェストから多数の図／グラフを作成しますか？ batch／plot-batch を使い、sweep でパラメーターをスイープします
5. 論文全体の図一式が必要ですか？ orchestrate を使います
6. 生成図が適切な手段ではありませんか（厳密なベクターアート、単純なグラフ、ブランド指定のデザインなど）？ 別の手段に切り替えます

必要事項の詳細な例と別の手段については、references/intake-and-route-outs.md を参照してください。

ステップ2：必要なプロファイルだけをインストールする

ユーザーがシステムへのインストールを明示的に希望しない限り、仮想環境を使ってください。

bash bash scripts/install.sh --profile plot # VLM のみ：統計グラフ bash scripts/install.sh --profile diagram # 図用の画像生成プロバイダー bash scripts/install.sh --profile pdf # + PDF 入力用の PyMuPDF bash scripts/install.sh --profile studio # + Gradio ローカルウェブ UI bash scripts/install.sh --profile mcp # MCP サーバー機能 bash scripts/install.sh --profile all # すべての機能が本当に必要な場合のみ

次に、プロバイダーキーを1つだけ設定します（OPENAI_API_KEY、GOOGLE_API_KEY、ATLASCLOUD_API_KEY、…）。 プロバイダーの選択と設定については、references/providers-and-config.md を参照してください。

Step 3: 設定を調整する前にパイプラインを理解する

図の生成は常に、計画してから調整する同じループで行われるため、フラグを推測するのではなく、各段階を調整してください。

• Phase 0 — 入力の最適化（任意の --optimize）：Context Enricher が生の手法テキストを構造化し、Caption Sharpener がキャプションを簡潔にします。2 つの VLM 呼び出しを並列で実行します。
• Phase 1 — 線形計画：Retriever が参照例を選択 → Planner がインコンテキスト学習によって目標の説明を作成 → Stylist が会場の美的スタイルを適用します。
• Phase 2 — 反復的な調整：Visualizer が画像をレンダリング → Critic が説明を修正します。--iterations（デフォルトは 3）で指定した回数だけ、または --auto で満足するまで繰り返します。

エージェントごとの詳細は、references/pipeline-and-agents.md をご覧ください。

Step 4: 要件に合う最も軽量なモードを実行する

bash

最も低コスト：データから統計プロットを作成（画像生成用のキーは不要）

bash scripts/run.sh plot --data results.csv --intent "Bar chart of accuracy across benchmarks"

テキストから単一の手法図を作成

bash scripts/run.sh generate --input method.txt --caption "Overview of our framework"

通常の実行で期待した結果が得られない場合に限り、最適化と自動調整を追加

bash scripts/run.sh generate --input method.txt --caption "Overview" --optimize --auto

フラグを含むすべてのコマンド（generate、plot、batch、plot-batch、sweep、orchestrate、 composite、evaluate、polish、venues、studio、setup、data）については、 references/modes-and-cli.md をご覧ください。

Step 5: 再生成する前に修正する

図がすでにある場合は、パイプライン全体を再実行しないでください。

bash

既存の図を人間が作成した参照図と照合して評価（VLM-as-Judge）

bash scripts/run.sh evaluate --generated out.png --reference human.png
--context method.txt --caption "Overview of our framework"

会場のスタイルガイドに沿って編集（画像編集対応プロバイダー）

bash scripts/run.sh polish --input figure.png --venue icml --iterations 2

評価の項目（忠実度、読みやすさ、簡潔さ、美しさ）と会場別スタイルパックについては、 references/evaluation-and-venues.md をご覧ください。

Step 6: 規模が本当の問題である場合に限り、batch、sweep、または orchestrate に進む

• batch / plot-batch — 1 つのマニフェストから多数の項目を処理します。任意の composite でパネルをつなぎ合わせ、ラベル付きの図を 1 つ作成できます。
• sweep — パラメーターのグリッドごとに同じ図を作成し、品質の代理スコアで順位付けします。
• orchestrate — 論文全体を解析し、複数の手法図とデータプロットを計画して、figure_package.json と figures.tex のバンドルを出力します。

図が 1～2 点であれば、単発の generate / plot のほうが簡単で低コストです。

Step 7: スクリプトの実行が目的ではない場合に限り、エージェントから使えるようにする

エージェントや IDE から利用できるようにするのが目的であり、個別の実行が目的ではない場合は、MCP サーバー（11 個のツール：generate_diagram、generate_plot、continue_run、evaluate_diagram、 orchestrate_figures、batch_diagrams、batch_plots、download_references、…）または同梱の Claude Code スキル（/generate-diagram、/generate-plot、/evaluate-diagram）を使用してください。

bash bash scripts/run-mcp.sh # uvx --from paperbanana[mcp] 経由の stdio MCP サーバー

例

例 1：ユーザーが CSV を持っていて、グラフを作成したい

plot（または plot-batch）を使用します。VLM から matplotlib をレンダリングし、画像生成用のキーも必要ないため、最も低コストな方法です。

例 2：ユーザーが手法についての段落を 1 つ持っていて、図を作成したい

わかりやすい --caption を指定して generate を使用します。最初の生成で期待した結果が得られない場合に限り、--optimize / --auto を追加します。

例 3：ユーザーがすでに図を持っていて、「ほぼ問題ない」状態

新たに generate を実行するのではなく、polish（ガイド付き編集）または evaluate（評価）を使用します。

例 4：ユーザーが論文内のすべての図を再生成したい

論文のソースに対して orchestrate を使用します。クレジットを消費する前に、--dry-run を指定して orchestration_plan.json を確認してください。

例 5：ユーザーがエージェントに必要に応じて図を作成させたい

その場限りのスクリプトを手書きするのではなく、MCP サーバーまたは Claude Code スキルを利用できるようにします。

例 6：図が単純な2本の棒グラフ、または正確なベクターアートの場合

matplotlib、TikZ、またはベクターエディターに切り替えてください。マルチエージェントによる生成実行は過剰であるか、適切なツールではありません。

ベストプラクティス

1. 最小のモード（plot < generate < batch/sweep/orchestrate）から始め、根拠がある場合にのみ段階的に引き上げます。
2. データには plot を優先してください。画像生成プロバイダーを完全にスキップでき、コストも抑えられます。
3. 全面再生成に費用をかける前に、polish/evaluate で既存の図を修正します。
4. --optimize、--auto、--iterations、--num-candidates はコスト調整用のパラメーターとして扱い、通常の実行で期待に届かない場合にのみ値を上げます。
5. 品質基準を満たす最も安価なプロバイダーを選びます（Gemini/Atlas VLM は低コストです）。パイプラインはプロバイダーに依存しません。
6. 実行ごとに見た目を手動で調整するのではなく、会議用のスタイルパック（neurips、icml、acl、ieee、またはカスタムパック）を使用します。
7. 図が出版可能な品質だと判断する前に、VLM-as-Judge の evaluate コマンドで評価します。
8. 生成図が適切でない場合は、matplotlib/TikZ/ベクターエディターや人間のデザイナーに正直に切り替えます。

参考資料

• references/intake-and-route-outs.md
• references/pipeline-and-agents.md
• references/modes-and-cli.md
• references/providers-and-config.md
• references/evaluation-and-venues.md
• scripts/install.sh
• scripts/run.sh
• scripts/run-mcp.sh
• PaperBanana GitHub リポジトリ
• PaperBanana の論文（arXiv:2601.23265）