plotting-agent

プロッティングエージェント（ステップ 2）

PaperOrchestra のプロッティングエージェントを忠実に実装したものです （Song et al., 2026, arXiv:2604.05018, §4 Step 2 and App. F.1 p.45）。

コスト：約20〜30回の LLM 呼び出し。 論文では、閉ループの VLM による批評と改善を備えたデフォルトのバックボーンとして PaperBanana（Zhu et al., 2026）を使用しています。このスキルでは、そのループをホストエージェントの観点から表現しています。つまり、あなた（ホストエージェント）が自身の LLM で matplotlib のコードを生成し、Bash/Python ツールでレンダリングし、任意でビジョンモデルを使ってレンダリング済みの PNG を批評して描き直し、最後にキャプションを付けます。

入力

• workspace/outline.json — 特に plotting_plan 配列
• workspace/inputs/idea.md と workspace/inputs/experimental_log.md — 元データ
• workspace/inputs/figures/ — 既存の図（任意、PlotOn モード）

出力

• workspace/figures/<figure_id>.png — plotting_plan の各項目につき PNG を1つ （300 DPI、指定されたアスペクト比に合わせたサイズ）
• workspace/figures/captions.json — {figure_id: caption_text} マップ

ワークフロー

図ごと（figure_id ごとに個別に実行）

1. outline.json から図の仕様を読み取ります：

   {
     "figure_id": "fig_main_results",
     "title": "Main Results on Dataset X",
     "plot_type": "plot",
     "data_source": "experimental_log.md",
     "objective": "Visual summary (Grouped Bar Chart) demonstrating ...",
     "aspect_ratio": "5:4"
   }
   

2. Few-shot 検索（ビジュアルプランニング）：plot_type=="plot" の場合は references/chart-patterns.md から、plot_type=="diagram" の場合は references/diagram-patterns.md から対応するパターンを選びます。

3. データの抽出：idea.md および／または experimental_log.md を解析して （どちらを使うかは data_source フィールドで指定）、図に必要な数値または概念的な要素を取得します。experimental_log.md では、 ## 2. Raw Numeric Data セクションに Markdown の表が含まれています。

4. レンダリング：

   PAPERBANANA_PATH が設定されている場合 — PaperBanana バックボーンを使用します （Zhu et al., 2026）。Retriever → Planner → Stylist → Visualizer → Critic のループを実行し、特に plot_type == "diagram" に適しています。 セットアップについては references/paperbanana-cookbook.md を参照してください（Gemini API キーが必要です）。

   python skills/plotting-agent/scripts/paperbanana_render.py \
       --figure-id <figure_id> \
       --caption   "<objective from figure spec>" \
       --content-file workspace/inputs/idea.md \
       --task      <diagram|plot> \
       --aspect-ratio <aspect_ratio> \
       --out       workspace/figures/<figure_id>.png
   

   それ以外の場合 — matplotlib スクリプトを作成して Bash ツール経由で実行するか、 同梱のヘルパーを使用します：

   python skills/plotting-agent/scripts/render_matplotlib.py \
       --spec spec.json \
       --out workspace/figures/<figure_id>.png
   

   スクリプトでは、chart-patterns.md のアカデミックスタイルを適用し、 aspect-ratios.md の正しいピクセルサイズを使用して、300 DPI で保存し、 savefig の後に plt.close() を呼び出す必要があります。

5. VLM 批評ループ（任意、ホストがビジョン機能を備えている場合のみ）：

   • レンダリング済みの PNG をマルチモーダル入力として LLM に再読み込みします。
   • 図の objective と照らし合わせて批評します。視覚的なアーティファクト、軸のラベル間違い、 読みにくいテキスト、色の不調和、誤解を招くスケーリング、凡例の欠落、ラベルの重なりを確認します。
   • 問題が見つかった場合は、修正を加えて matplotlib スクリプトを再生成し、 再レンダリングします。図ごとの批評反復は最大3回です。
   • これは、論文が PaperBanana から受け継いだ閉ループの改善ステップです。ループの詳細な 説明については references/plotting-pipeline.md を参照してください。
   • ホストにビジョン入力機能がない場合、このステップは完全に省略してください。 図は 反復的な改善なしでも正しくレンダリングされます。

6. references/caption-prompt.md にあるキャプション生成プロンプトを一字一句そのまま使用して、 キャプションを生成します。キャプションプロンプトへの入力：

   • task_name — 図が属するセクション（例：「Methodology」、 「Experiments」）
   • raw_content — 周辺のセクションの本文（または、セクションがまだ 作成されていない場合は section_plan の content_bullets）
   • description — 図の仕様にある objective フィールド
   • figure_desc — レンダリングされた図が実際に何を示しているかの1文の説明 （VLM 批評パスから取得するか、ビジョン機能がない場合はスクリプトの計画から取得）

   キャプションは figure_id をキーとして workspace/figures/captions.json に 書き込みます。キャプションに Figure N: や Caption N: の 接頭辞を含めてはいけません — LaTeX テンプレートが番号を処理します。プレーンテキストのみとし、 Markdown は使用しません。

概念図

plot_type == "diagram" の場合、利用可能であれば PaperBanana を優先してください。Retriever が、実際に公開された論文の図に基づいて Planner を支援します。PAPERBANANA_PATH が設定されていない場合は、references/diagram-patterns.md に従ってください。パターンには、ブロック図、システム概要図、フローチャート、アルゴリズムのグラフ化が含まれます。同梱のヘルパーは次のとおりです。

python skills/plotting-agent/scripts/render_diagram.py \
    --spec diagram_spec.json \
    --out workspace/figures/<figure_id>.png

簡単なケース（ボックスと矢印）に対応します。複雑な Fig-1 形式の概要図は、matplotlib のパッチコードを自分で記述してください。

厳守事項

• すべての図を 300 DPI にしてください。 DPI が低いと、会議テンプレートでの LaTeX コンパイル時に却下されます。
• アスペクト比は正確に合わせてください。 図の仕様にある aspect_ratio は、列挙された 12 個の文字列のいずれかです。references/aspect-ratios.md のピクセル目標値を使用してください。
• プロットでは上と右のスパインを非表示にしてください。（図ではスパインをすべて非表示にしてください。）
• 落ち着いた学術向けの色のみを使用してください。 パレットは chart-patterns.md にあります。matplotlib のデフォルトは使用しないでください（印刷には彩度が高すぎます）。
• 3D、円グラフ、装飾的なビジュアルは禁止です。 論文の評価者はこれらを減点します。
• すべての図に captions.json 内のキャプションが必須です。 アウトラインから参照される図にキャプションがない場合、Section Writing Agent は処理を停止します。
• キャプションに Figure N: という接頭辞を付けないでください。 LaTeX が追加します。
• プロットしていないデータについて記述しないでください。 Plotting Agent は、軸、ベースライン、傾向を捏造してはなりません。情報源は experimental_log.md または idea.md です。

検証ゲート（Step 3/4 に渡す前に実行）

上記の厳守事項はあらゆる場所に記載されていますが、どこでも強制されていません。このゲートにより、機械的に確認できる項目を検査できます。

python skills/plotting-agent/scripts/figure_lint.py \
    --figures workspace/figures \
    --captions workspace/figures/captions.json

ERROR：キャプションのないレンダリング済みの図、ファイルのないキャプション、空のキャプション、印刷には小さすぎるラスター画像。WARN：単一カラム幅で解像度が約 300 DPI 未満、アスペクト比が 4:1 を超える、番号を自ら付けたキャプション（Figure 3: ...）、8 語未満のキャプション、アーキテクチャ／パイプライン／概要図が含まれない図のセット。

PNG のジオメトリは IHDR チャンクと pHYs チャンクから直接読み取ります。画像ライブラリは使用しません。これは、リポジトリの「決定論的ヘルパーのみ」というルールに沿ったものです。

Step 4 で paper.tex を生成した後、--paper を付けて再実行し、ドラフトが Step 2 でレンダリングしたすべての図を使用しており、存在しないファイルを参照していないことを確認してください。

python skills/plotting-agent/scripts/figure_lint.py \
    --figures workspace/figures \
    --paper   workspace/drafts/paper.tex

続行する前に ERROR を修正してください。キャプションの欠落だけは、気付かれないまま後続に影響する失敗です。Step 4 では、図に任意のキャプションを付けて挿入してしまい、Step 5 では、そのキャプションが根拠に基づいていなかったことを知る手段がありません。

既存の図（PlotOn モード）

workspace/inputs/figures/ が空でない場合、既存のファイルのうち、アウトライン内の figure_id と一致するものがあるか（ファイル名のプレフィックスで）確認してください。一致するものがあれば、そのファイルをそのまま workspace/figures/ にコピーし、キャプションプロンプトを使用してキャプションも生成してください。既存の図がない figure_id のみを新規に生成してください。

リソース

• references/caption-prompt.md — App. F.1 のキャプション生成プロンプト（原文）
• references/plotting-pipeline.md — few-shot → レンダリング → 批評 → キャプション作成までの全工程
• references/chart-patterns.md — matplotlib のスタイルとグラフ種別のレシピ
• references/diagram-patterns.md — 概念図のレシピ
• references/aspect-ratios.md — 300 DPI で使用可能な 12 種類の比率それぞれのピクセル目標値
• references/paperbanana-cookbook.md — 新規 PaperBanana のセットアップ、使用方法、コストに関する注記、帰属表示
• scripts/render_matplotlib.py — JSON のプロット仕様を PNG にレンダリング（matplotlib フォールバック）
• scripts/render_diagram.py — JSON の図の仕様を PNG にレンダリング（matplotlib フォールバック）
• scripts/paperbanana_render.py — 新規 PaperBanana バックボーンのラッパー（環境変数から PAPERBANANA_PATH を読み込み）
• scripts/figure_lint.py — 新規 解像度／アスペクト比／キャプション網羅性のゲート。--paper は \includegraphics を照合します。