Plotting Agent

Plotting Agent (Step 2)

Faithful implementation of the Plotting Agent from PaperOrchestra (Song et al., 2026, arXiv:2604.05018, §4 Step 2 and App. F.1 p.45).

Cost: ~20–30 LLM calls. The paper uses PaperBanana (Zhu et al., 2026) as the default backbone with a closed-loop VLM-critique refinement. This skill expresses that loop in host-agent terms: you (the host agent) generate matplotlib code with your own LLM, render via your Bash/Python tool, optionally critique the rendered PNG with your vision model, redraw, and finally caption.

Inputs

• workspace/outline.json — specifically the plotting_plan array
• workspace/inputs/idea.md and workspace/inputs/experimental_log.md —

the source data

• workspace/inputs/figures/ — optional pre-existing figures (PlotOn mode)

Outputs

• workspace/figures/<figure_id>.png — one PNG per plotting_plan entry

(300 DPI, sized to the requested aspect ratio)

• workspace/figures/captions.json — {figure_id: caption_text} map

Workflow

Per figure (executed independently per figure_id)

1. Read the figure spec from 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 retrieval (visual planning): pick the matching pattern from references/chart-patterns.md (for plot_type=="plot") or references/diagram-patterns.md (for plot_type=="diagram").

3. Extract data: parse idea.md and/or experimental_log.md (data_source field tells you which) to obtain the numeric values or conceptual entities the figure needs. For experimental_log.md, the ## 2. Raw Numeric Data section contains markdown tables.

4. Render:

If `PAPERBANANA_PATH` is set — use the PaperBanana backbone (Zhu et al., 2026). It runs a Retriever → Planner → Stylist → Visualizer → Critic loop and is especially good for plot_type == "diagram". See references/paperbanana-cookbook.md for setup (needs a Gemini API key).

   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

Otherwise — write a matplotlib script and run it via your Bash tool, or use the bundled helper:

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

The script must apply the academic style from chart-patterns.md, use the correct pixel size from aspect-ratios.md, save at 300 DPI, and call plt.close() after savefig.

5. VLM critique loop (optional, only if your host has vision):

• Reload the rendered PNG as a multimodal input to your LLM.
• Critique it against the figure's objective from the outline. Look for:

visual artifacts, mislabeled axes, illegible text, color clashes, misleading scaling, missing legend, overlapping labels.

• If problems are found, regenerate the matplotlib script with corrections

and re-render. Cap at 3 critique iterations per figure.

• This is the closed-loop refinement step the paper inherits from

PaperBanana. See references/plotting-pipeline.md for the full loop description.

• If your host has no vision input, skip this step entirely. The

figure will still render correctly, just without iterative refinement.

6. Generate the caption using the verbatim Caption Generation prompt at references/caption-prompt.md. Inputs to the caption prompt:

• task_name — the section the figure belongs to (e.g., "Methodology",

"Experiments")

• raw_content — the surrounding section text (or content_bullets from

the section_plan if the section isn't drafted yet)

• description — the objective field from the figure spec
• figure_desc — a 1-sentence description of what the rendered figure

actually shows (from your VLM critique pass, or from the script's plan if no vision)

Write the caption to workspace/figures/captions.json keyed by figure_id. Captions must NOT contain `Figure N:` or `Caption N:` prefixes — the LaTeX template handles numbering. Plain text only, no markdown.

Conceptual diagrams

For plot_type == "diagram", prefer PaperBanana when available — its Retriever grounds the Planner in real published paper diagrams. If PAPERBANANA_PATH is unset, follow references/diagram-patterns.md. Patterns include block diagrams, system overviews, flowcharts, and algorithm-as-graph. The bundled helper:

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

handles the simple cases (boxes-and-arrows). For complex Fig-1-style overview diagrams, write matplotlib patches code yourself.

Hard rules

• 300 DPI for every figure. Lower DPI gets rejected at the LaTeX compile

step on conference templates.

• Aspect ratio is exact. The figure spec's aspect_ratio is one of 12

enumerated strings. Use the pixel targets in references/aspect-ratios.md.

• Hide top and right spines for plots. (Diagrams: no spines at all.)
• Muted academic colors only. The palette is in chart-patterns.md.

Never use matplotlib defaults (too saturated for print).

• No 3D, no pie charts, no decorative visuals. The paper's evaluators

penalize these.

• Every figure MUST have a caption in captions.json. The Section

Writing Agent will fail-stop if a caption is missing for any figure referenced from the outline.

• No `Figure N:` prefix in captions — LaTeX adds it.
• Never describe data you didn't plot. The Plotting Agent must not

hallucinate axes, baselines, or trends. Source-of-truth is experimental_log.md or idea.md.

Pre-existing figures (PlotOn mode)

If workspace/inputs/figures/ is non-empty, check whether any pre-existing file matches a figure_id in the outline (by filename prefix). If so, copy it into workspace/figures/ as-is and still generate a caption using the caption prompt. Only generate from scratch the figure_ids that have no pre-existing counterpart.

Resources

• references/caption-prompt.md — verbatim Caption Generation prompt from App. F.1
• references/plotting-pipeline.md — the full few-shot → render → critique → caption loop
• references/chart-patterns.md — matplotlib style + chart type recipes
• references/diagram-patterns.md — conceptual diagram recipes
• references/aspect-ratios.md — pixel targets for each of the 12 allowed ratios at 300 DPI
• references/paperbanana-cookbook.md — NEW PaperBanana setup, usage, cost notes, attribution
• scripts/render_matplotlib.py — render a JSON plot spec → PNG (matplotlib fallback)
• scripts/render_diagram.py — render a JSON diagram spec → PNG (matplotlib fallback)
• scripts/paperbanana_render.py — NEW PaperBanana backbone wrapper (reads PAPERBANANA_PATH from env)

Aspect Ratios

The Outline Agent's prompt enumerates exactly 12 allowed aspect ratios (App. F.1, page 41). Each one maps to a specific figure size in inches at 300 DPI. The plotting agent MUST use these — anything else fails the outline schema validator.

Width budget

The widths are chosen to slot into the most common LaTeX layouts:

• 2-column conference template (CVPR, ICCV, NeurIPS):

single-column = 3.3in, double-column = 7.0in. Use widths ≤ 3.5in for \begin{figure} and ≤ 7.0in for \begin{figure*}.

• 1-column template (ICLR, plain article): page text width is ~6.5in.

The fig_size_for(ratio) helper in chart-patterns.md returns the matching (width, height) tuple. The bundled render_matplotlib.py script uses the same table.

DPI

Always 300. Conference templates reject ≤150 DPI raster figures.

Strict mapping in JSON spec

The render_matplotlib.py and render_diagram.py helpers accept a JSON spec with "aspect_ratio" set to one of the 12 strings above. They look up the size, set figsize, set dpi=300, and call tight_layout() + bbox_inches='tight' automatically.

Plotting Agent — Caption Generation prompt

Source: arXiv:2604.05018, Appendix F.1, page 45 (verbatim).

The paper uses PaperBanana (Zhu et al., 2026) for the entire visual generation pipeline; it then appends a single caption regeneration step at the end using the prompt below. We reproduce only this final caption step verbatim because it is the part the paper authors actually wrote (PaperBanana's internal prompts are external and not reproduced here).

---

Input Data
  - Task Type:               {task_name}
  - Contextual Section:      {raw_content}
  - Overall Figure Intent:   {description}
  - Detailed Figure Description: {figure_desc}

Please provide the final caption for this figure based on the system
instructions.

Requirements

  - The caption should be concise and informative, and can be directly used
    as a caption for academic papers.
  - The caption MUST NOT contain a "Figure X:" or "Caption X:" prefix, as
    the latex template will add it automatically.
  - The caption MUST NOT contain any markdown formatting (like bold,
    italics, etc), it should be plain text.

Respond with the plain text caption only.

---

Field substitution guide

Output

Plain text. One caption. No prefix, no markdown, no quotes around it. Save the result into workspace/figures/captions.json keyed by figure_id:

{
  "fig_main_results": "Comparison of three temporal-attention variants on the Ref-AVS Seen split. Bars show Jaccard index; error bars are 95% confidence intervals over five seeds.",
  "fig_framework_overview": "Overview of the proposed pipeline. Raw video frames flow into the frozen SAM encoder; aligned audio cues are projected through the temporal modality fusion layer before being injected into the mask decoder."
}

Chart Patterns

Matplotlib recipes for academic-paper figures. Adapted from ~/.all-skills/academic-paper/references/chart-patterns.md and tuned for the PaperOrchestra plotting agent's aspect-ratio constraints.

Global style config

Apply this at the top of every plotting script.

import matplotlib
matplotlib.use('Agg')             # headless
import matplotlib.pyplot as plt
import numpy as np

plt.rcParams.update({
    'font.family':       'serif',
    'font.serif':        ['Times New Roman', 'DejaVu Serif'],
    'font.size':         8,
    'axes.titlesize':    9,
    'axes.titleweight':  'bold',
    'axes.labelsize':    8,
    'axes.linewidth':    0.6,
    'legend.fontsize':   7,
    'legend.framealpha': 0.95,
    'legend.edgecolor':  '#cccccc',
    'xtick.labelsize':   7,
    'ytick.labelsize':   7,
    'figure.dpi':        300,
    'savefig.dpi':       300,
    'savefig.bbox':      'tight',
    'savefig.pad_inches': 0.08,
    'grid.alpha':        0.15,
    'grid.linewidth':    0.5,
    'lines.linewidth':   1.3,
})

# Muted academic palette (print-safe)
BLUE   = '#2060cc'
RED    = '#cc3030'
GREEN  = '#208040'
ORANGE = '#cc7020'
PURPLE = '#8040cc'
GOLD   = '#b08020'
GRAY   = '#666666'
PALETTE = [BLUE, RED, GREEN, ORANGE, PURPLE, GOLD, GRAY]

Per-pattern recipes

Line chart (training curves, scaling laws)

fig, ax = plt.subplots(figsize=fig_size_for("16:9"))
for i, (name, ys) in enumerate(series.items()):
    ax.plot(xs, ys, color=PALETTE[i], label=name)
ax.set_xlabel('Training step')
ax.set_ylabel('Validation loss')
ax.legend(loc='upper right', frameon=True)
ax.grid(True)
ax.spines['top'].set_visible(False)
ax.spines['right'].set_visible(False)
fig.tight_layout()
fig.savefig(out_path)
plt.close()

For noisy time-series, smooth with a rolling mean before plotting:

def rolling(y, w=7):
    return np.convolve(y, np.ones(w)/w, mode='valid')

Grouped bar chart (method comparison across metrics)

methods = ['Baseline', 'Ours-S', 'Ours-L']
metrics = ['Acc', 'F1', 'AUC']
data = np.array([[78, 79, 0.83],
                 [82, 84, 0.87],
                 [85, 87, 0.91]])  # rows=methods, cols=metrics

fig, ax = plt.subplots(figsize=fig_size_for("5:4"))
x = np.arange(len(metrics))
w = 0.25
for i, m in enumerate(methods):
    ax.bar(x + (i-1)*w, data[i], w, color=PALETTE[i], label=m,
           edgecolor='white', linewidth=0.4)
ax.set_xticks(x)
ax.set_xticklabels(metrics)
ax.set_ylabel('Score')
ax.legend(loc='upper left')
ax.spines['top'].set_visible(False)
ax.spines['right'].set_visible(False)
ax.grid(axis='y', alpha=0.2)
fig.tight_layout()
fig.savefig(out_path)
plt.close()

Radar chart (multi-axis SOTA comparison — paper's Fig 2 pattern)

labels = ['Originality', 'Quality', 'Clarity', 'Significance', 'Soundness']
ours    = [3.0, 3.4, 3.6, 3.0, 3.4]
baseline = [2.5, 2.7, 3.0, 2.3, 2.8]

angles = np.linspace(0, 2*np.pi, len(labels), endpoint=False).tolist()
angles += angles[:1]
ours    = ours + ours[:1]
baseline = baseline + baseline[:1]

fig, ax = plt.subplots(figsize=fig_size_for("1:1"), subplot_kw=dict(polar=True))
ax.plot(angles, ours, color=BLUE, linewidth=1.5, label='Ours')
ax.fill(angles, ours, color=BLUE, alpha=0.15)
ax.plot(angles, baseline, color=RED, linewidth=1.5, label='Baseline')
ax.fill(angles, baseline, color=RED, alpha=0.10)
ax.set_xticks(angles[:-1])
ax.set_xticklabels(labels, fontsize=7)
ax.set_yticks([1, 2, 3, 4])
ax.set_ylim(0, 4)
ax.legend(loc='upper right', bbox_to_anchor=(1.2, 1.05))
fig.tight_layout()
fig.savefig(out_path)
plt.close()

Stacked bar / win-rate plot (paper's Fig 2/3 SxS pattern)

methods = ['Single Agent', 'AI-Sci-v2', 'PaperOrchestra']
wins = [33, 22, 65]
ties = [22, 18, 25]
losses = [45, 60, 10]

fig, ax = plt.subplots(figsize=fig_size_for("4:3"))
x = np.arange(len(methods))
ax.bar(x, losses, color=RED, label='Baseline win', edgecolor='white', linewidth=0.4)
ax.bar(x, ties, bottom=losses, color=GRAY, label='Tie', edgecolor='white', linewidth=0.4)
ax.bar(x, wins, bottom=np.array(losses)+np.array(ties),
       color=BLUE, label='Our win', edgecolor='white', linewidth=0.4)
ax.set_xticks(x)
ax.set_xticklabels(methods)
ax.set_ylabel('Percentage (%)')
ax.set_ylim(0, 100)
ax.legend(loc='upper center', bbox_to_anchor=(0.5, -0.15), ncol=3)
ax.spines['top'].set_visible(False)
ax.spines['right'].set_visible(False)
fig.tight_layout()
fig.savefig(out_path)
plt.close()

Heatmap (ablation grid)

import matplotlib.colors as mcolors
data = np.random.rand(5, 6) * 0.4 + 0.5  # placeholder
xticks = ['M1', 'M2', 'M3', 'M4', 'M5', 'M6']
yticks = ['A=0.1', 'A=0.2', 'A=0.5', 'A=1.0', 'A=2.0']

fig, ax = plt.subplots(figsize=fig_size_for("4:3"))
im = ax.imshow(data, cmap='Blues', vmin=0.4, vmax=1.0, aspect='auto')
ax.set_xticks(range(len(xticks)))
ax.set_xticklabels(xticks)
ax.set_yticks(range(len(yticks)))
ax.set_yticklabels(yticks)
for i in range(data.shape[0]):
    for j in range(data.shape[1]):
        ax.text(j, i, f'{data[i,j]:.2f}', ha='center', va='center',
                color='white' if data[i,j] > 0.7 else 'black', fontsize=6)
fig.colorbar(im, ax=ax, fraction=0.04, pad=0.02)
fig.tight_layout()
fig.savefig(out_path)
plt.close()

Multi-panel (side-by-side ablation/case study)

fig, axes = plt.subplots(1, 3, figsize=fig_size_for("21:9"))
for ax, (label, data) in zip(axes, panels.items()):
    ax.plot(data['x'], data['y'], color=BLUE)
    ax.set_title(label, fontsize=8, fontweight='bold')
    ax.spines['top'].set_visible(False)
    ax.spines['right'].set_visible(False)
fig.tight_layout()
fig.savefig(out_path)
plt.close()

Aspect ratio helper

def fig_size_for(ratio: str) -> tuple[float, float]:
    """Return (width_inches, height_inches) at a fixed width target.
    Width target: 5.5in for single-column, 7.0in for full-page wide."""
    w_to_h = {
        "1:1":  (3.4, 3.4),
        "1:4":  (1.8, 7.2),
        "2:3":  (3.4, 5.1),
        "3:2":  (5.1, 3.4),
        "3:4":  (3.0, 4.0),
        "4:1":  (7.0, 1.75),
        "4:3":  (4.0, 3.0),
        "4:5":  (3.2, 4.0),
        "5:4":  (4.5, 3.6),
        "9:16": (2.8, 4.97),
        "16:9": (5.5, 3.09),
        "21:9": (7.0, 3.0),
    }
    return w_to_h[ratio]

Anti-patterns

• Never use 3D charts, pie charts, or decorative visuals.
• Never use default matplotlib colors (too saturated for print).
• Never skip axis labels or units.
• Never place legend outside the axes area without bbox_to_anchor (causes overflow).
• Always plt.close() after savefig() to prevent memory leaks across many figures.
• Never put a Figure N: text into the chart itself — captions handle that.

Conceptual Diagram Patterns

For plot_type == "diagram" figures: framework overviews, system pipelines, algorithmic flows, architectural block diagrams.

The paper's Fig. 1 (PaperOrchestra overview) is a canonical example: boxes representing agents, arrows showing data flow, grouped sub-systems with labeled inputs and outputs.

Tools

• matplotlib patches — best for hand-controlled layouts (boxes-and-arrows

with exact positioning, labels, and group rectangles). No external deps.

• graphviz — best for DAGs where layout doesn't matter; requires the

graphviz Python binding and the dot system binary. Use only if the diagram is purely topological.

This skill defaults to matplotlib because it ships in requirements.txt and needs no system binary.

Block diagram pattern (boxes + arrows)

import matplotlib.pyplot as plt
from matplotlib.patches import FancyBboxPatch, FancyArrowPatch
from matplotlib.lines import Line2D

# 16:9 frame
fig, ax = plt.subplots(figsize=(7.0, 3.94))
ax.set_xlim(0, 10); ax.set_ylim(0, 6)
ax.axis('off')

PALETTE = {
    'input':   '#cfe2f3',
    'agent':   '#9fc5e8',
    'output':  '#b6d7a8',
    'control': '#ead1dc',
    'border':  '#2060cc',
}

def box(x, y, w, h, text, color):
    bb = FancyBboxPatch((x, y), w, h, boxstyle="round,pad=0.06,rounding_size=0.15",
                        ec=PALETTE['border'], fc=color, lw=0.8)
    ax.add_patch(bb)
    ax.text(x + w/2, y + h/2, text, ha='center', va='center',
            fontsize=8, fontweight='bold')

def arrow(x1, y1, x2, y2):
    a = FancyArrowPatch((x1, y1), (x2, y2),
                        arrowstyle='->', mutation_scale=10,
                        color=PALETTE['border'], lw=0.9)
    ax.add_patch(a)

# Inputs (left column)
box(0.2, 4.8, 1.6, 0.7, "Idea (I)",            PALETTE['input'])
box(0.2, 3.6, 1.6, 0.7, "Exp Log (E)",         PALETTE['input'])
box(0.2, 2.4, 1.6, 0.7, "Template (T)",        PALETTE['input'])
box(0.2, 1.2, 1.6, 0.7, "Guidelines (G)",      PALETTE['input'])

# Agents (middle)
box(2.6, 3.6, 1.8, 1.0, "Outline\nAgent",      PALETTE['agent'])
box(5.0, 4.8, 1.8, 0.9, "Plotting\nAgent",     PALETTE['agent'])
box(5.0, 3.0, 1.8, 0.9, "Lit Review\nAgent",   PALETTE['agent'])
box(5.0, 1.2, 1.8, 0.9, "Section\nWriter",     PALETTE['agent'])
box(7.5, 2.4, 2.0, 1.6, "Refinement\nAgent",   PALETTE['control'])

# Output
box(7.5, 0.4, 2.0, 0.9, "paper.tex\n+ paper.pdf", PALETTE['output'])

# Arrows
for y_in in (5.15, 3.95, 2.75, 1.55):
    arrow(1.8, y_in, 2.6, 4.1)
arrow(4.4, 4.1, 5.0, 5.25)
arrow(4.4, 4.1, 5.0, 3.45)
arrow(4.4, 4.1, 5.0, 1.65)
for y in (5.25, 3.45, 1.65):
    arrow(6.8, y, 7.5, 3.2)
arrow(8.5, 2.4, 8.5, 1.3)

fig.savefig(out_path, dpi=300, bbox_inches='tight', pad_inches=0.05)
plt.close()

Pipeline / flowchart pattern (linear with branches)

Same primitives, just arranged left-to-right with arrow(x1, y1, x2, y2) between successive boxes. For parallel branches (Steps 2 ∥ 3 in PaperOrchestra), draw two parallel rows with a fork-and-join.

Algorithm-as-graph pattern

For diagrams that are just a topological graph (no labels of importance, just nodes-and-edges), use graphviz:

import graphviz
g = graphviz.Digraph(format='png')
g.attr(dpi='300', rankdir='LR', fontname='Times-Roman', fontsize='8')
g.attr('node', shape='box', style='rounded,filled',
       fillcolor='#cfe2f3', color='#2060cc', fontname='Times-Roman', fontsize='8')
g.attr('edge', color='#2060cc', fontname='Times-Roman', fontsize='7')
g.edge('Input', 'Encoder')
g.edge('Encoder', 'Decoder')
g.edge('Decoder', 'Output')
g.render(out_path.replace('.png', ''), cleanup=True)

Anti-patterns

• Never use clip-art icons or emoji.
• Never use color as the only signal (always pair with shape or label).
• Never let arrows cross labels — re-route around.
• Never use a bitmap background.
• Always axis('off') for diagrams; no spines, no ticks, no grid.

PaperBanana Cookbook

Optional backbone for the plotting-agent's render step.

PaperBanana (Zhu et al., 2026 — <https://github.com/dwzhu-pku/PaperBanana>) is the default figure-generation backbone described in the PaperOrchestra paper (arXiv:2604.05018, §4 Step 2). It runs a Retriever → Planner → Stylist → Visualizer → Critic multi-agent loop, producing publication-quality diagrams and plots that are grounded in a curated reference collection.

The plotting-agent works fine without PaperBanana — it falls back to the bundled matplotlib renderer (render_matplotlib.py / render_diagram.py). PaperBanana is best for:

---

1. One-time setup

# Clone PaperBanana
git clone https://github.com/dwzhu-pku/PaperBanana /path/to/PaperBanana

# Install dependencies (Python 3.12 required)
cd /path/to/PaperBanana
uv pip install -r requirements.txt      # or: pip install -r requirements.txt

# Configure API key — fill at least one, you do not need both
cp configs/model_config.template.yaml configs/model_config.yaml

Open configs/model_config.yaml and paste your key:

If both are set, OpenRouter is preferred. For OpenRouter, set the model names to "openrouter/<model>" (e.g. "openrouter/google/gemini-pro-1.5").

# Point paper-orchestra at your clone
export PAPERBANANA_PATH="/path/to/PaperBanana"

Optional model overrides (take precedence over model_config.yaml):

export PAPERBANANA_MAIN_MODEL="gemini-3.1-pro-preview"
export PAPERBANANA_IMAGE_MODEL="gemini-3.1-flash-image-preview"

Verify the setup before running the pipeline:

python skills/plotting-agent/scripts/paperbanana_render.py --check-backend
# Expected output:
#   PaperBanana found at: /path/to/PaperBanana
#   Backend is ready.

---

2. Rendering a single figure

# Diagram (e.g. Figure 1 overview)
python skills/plotting-agent/scripts/paperbanana_render.py \
    --figure-id   fig_overview \
    --caption     "Figure 1: Overview of our proposed PaperOrchestra framework." \
    --content-file workspace/inputs/idea.md \
    --task        diagram \
    --aspect-ratio 16:9 \
    --out         workspace/figures/fig_overview.png

# Plot (e.g. main results bar chart)
python skills/plotting-agent/scripts/paperbanana_render.py \
    --figure-id   fig_main_results \
    --caption     "Figure 3: Comparison of our method against baselines." \
    --content-file workspace/inputs/experimental_log.md \
    --task        plot \
    --aspect-ratio 5:4 \
    --max-critic-rounds 2 \
    --out         workspace/figures/fig_main_results.png

Exit codes:

• 0 — success, image saved at --out
• 1 — PaperBanana pipeline error (see stderr)
• 2 — PAPERBANANA_PATH not set or invalid → fall back to matplotlib

---

3. Input format (PaperBanana)

The wrapper converts the plotting-agent's figure spec to PaperBanana's input dict:

---

4. Output format (PaperBanana)

PaperBanana stores all intermediate and final images as base64-encoded JPEG strings in the result dictionary. The wrapper selects the best image using this priority:

1. Latest critic round: target_{task}_critic_descN_base64_jpg (N = 0…3) 2. eval_image_field pointer 3. Stylist output: target_{task}_stylist_desc0_base64_jpg 4. Planner output: target_{task}_desc0_base64_jpg 5. Vanilla baseline: vanilla_{task}_base64_jpg

The selected image is decoded and saved as a 300-DPI PNG to --out.

---

5. Pipeline modes

PaperBanana's exp_mode controls which agents run. The wrapper uses demo_full (full pipeline, no benchmark evaluation):

To override, set --exp-mode (future flag — hardcoded to demo_full today).

---

6. Cost and rate limits

• PaperBanana makes multiple LLM calls per figure (~5–10 in demo_full mode).
• API cost depends on the model chosen; Gemini Flash is cheapest for image gen.
• No S2 / Exa calls — PaperBanana uses its own reference collection for retrieval.
• Runs one figure at a time when invoked via paperbanana_render.py; parallel

batch processing is available via PaperBanana's native main.py if you have many figures.

---

7. Security notes

• PAPERBANANA_PATH, PAPERBANANA_MAIN_MODEL, and PAPERBANANA_IMAGE_MODEL

are read from the environment only. This repo never commits these values.

• API keys for PaperBanana live in {PAPERBANANA_PATH}/configs/model_config.yaml,

which is .gitignore'd in the PaperBanana repo. Never commit that file.

---

8. Attribution

If you use PaperBanana as the plotting backbone, cite:

@article{zhu2026paperbanana,
  title={PaperBanana: A Reference-Driven Multi-Agent Framework for
         Automated Academic Illustration Generation},
  author={Zhu, Dawei and others},
  year={2026},
  url={https://github.com/dwzhu-pku/PaperBanana}
}

Plotting Pipeline (per-figure loop)

Source: arXiv:2604.05018, §4 Step 2 ("Plotting Agent"), App. B (cost: ~20-30 LLM calls including few-shot retrieval, visual planning, image generation, VLM-guided critique-and-redraw cycles, and context-aware captioning).

The paper outsources visual generation to PaperBanana (Zhu et al., 2026) internally. We can't redistribute PaperBanana, so this skill expresses the loop structure in terms a host coding agent can execute with its own LLM and matplotlib.

The 5-stage per-figure loop

                ┌─────────────────────────────────────┐
                │  outline.json  →  figure spec        │
                │  { figure_id, plot_type, objective,  │
                │    aspect_ratio, data_source }       │
                └─────────────────┬───────────────────┘
                                  │
                                  ▼
       ┌──────────────────────────────────────────────────┐
       │  STAGE 1 — Few-shot retrieval                     │
       │  Pick the matching pattern from chart-patterns.md │
       │  (plot) or diagram-patterns.md (diagram). Identify│
       │  variables you'll need from the data sources.     │
       └─────────────────┬────────────────────────────────┘
                         │
                         ▼
       ┌──────────────────────────────────────────────────┐
       │  STAGE 2 — Visual planning                        │
       │  Sketch (in your head / in JSON) the chart layout:│
       │  axes, series, colors, legend placement, title.   │
       │  Resolve aspect_ratio → pixel dimensions          │
       │  via aspect-ratios.md.                            │
       └─────────────────┬────────────────────────────────┘
                         │
                         ▼
       ┌──────────────────────────────────────────────────┐
       │  STAGE 3 — Image generation                       │
       │  Write matplotlib code. Apply the global style    │
       │  from chart-patterns.md. Save to                  │
       │  workspace/figures/<figure_id>.png at 300 DPI.    │
       │  Run via your Bash tool, OR call                  │
       │  scripts/render_matplotlib.py with a spec JSON.   │
       └─────────────────┬────────────────────────────────┘
                         │
                         ▼
       ┌──────────────────────────────────────────────────┐
       │  STAGE 4 — VLM critique loop  (skip if no vision) │
       │  for iter in 1..3:                                │
       │      load PNG as multimodal input to your LLM     │
       │      critique against `objective` field           │
       │      if no issues: break                          │
       │      else: regenerate matplotlib code, re-render  │
       └─────────────────┬────────────────────────────────┘
                         │
                         ▼
       ┌──────────────────────────────────────────────────┐
       │  STAGE 5 — Caption                                │
       │  Use the verbatim caption-prompt.md.              │
       │  Save into figures/captions.json.                 │
       └──────────────────────────────────────────────────┘

What to look for in the VLM critique

When you (the host agent) inspect a rendered figure with vision, score it against this checklist (derived from the paper's plotting failure modes and the academic-paper skill's review-guide.md):

If any of these fire, regenerate the matplotlib script with the fix and re-render. Cap at 3 iterations.

Wall-time budget

The paper allocates ~20-30 LLM calls per Plotting Agent invocation. With ~5-10 figures per typical paper, that's ~3 calls per figure: roughly 1 (planning) + 1 (initial generation) + 1 (critique pass) + 0-1 (redraw) + 1 (caption). Stay within this budget by using deterministic helpers for the mechanical parts (render_matplotlib.py does pixel sizing, style, save) and reserving LLM calls for actual visual judgment.