paperbanana

<!-- mcp-name: io.github.llmsresearch/paperbanana --> <table align="center" width="100%" style="border: none; border-collapse: collapse;"> <tr> <td width="220" align="left" valign="middle" style="border: none;"> <img src="https://dwzhu-pku.github.io/PaperBanana/static/images/logo.jpg" alt="PaperBanana Logo" width="180"/> </td> <td align="left" valign="middle" style="border: none;"> <h1>PaperBanana</h1> <p><strong>Automated Academic Illustration for AI Scientists</strong></p> <p> <a href="https://github.com/llmsresearch/paperbanana/actions/workflows/ci.yml"><img src="https://github.com/llmsresearch/paperbanana/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="https://pypi.org/project/paperbanana/"><img src="https://img.shields.io/pypi/dm/paperbanana?label=PyPI%20downloads&logo=pypi&logoColor=white" alt="PyPI Downloads"/></a> <a href="https://huggingface.co/spaces/llmsresearch/paperbanana"><img src="https://img.shields.io/badge/Demo-HuggingFace-yellow?logo=huggingface&logoColor=white" alt="Demo"/></a> <a href="https://colab.research.google.com/github/llmsresearch/paperbanana/blob/main/notebooks/PaperBanana_Colab_Quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"/></a> <br/> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a> <a href="https://arxiv.org/abs/2601.23265"><img src="https://img.shields.io/badge/arXiv-2601.23265-b31b1b?logo=arxiv&logoColor=white" alt="arXiv"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?logo=opensourceinitiative&logoColor=white" alt="License: MIT"/></a> <br/> <a href="https://pydantic.dev"><img src="https://img.shields.io/badge/Pydantic-v2-e92063?logo=pydantic&logoColor=white" alt="Pydantic v2"/></a> <a href="https://typer.tiangolo.com"><img src="https://img.shields.io/badge/CLI-Typer-009688?logo=gnubash&logoColor=white" alt="Typer"/></a> <a href="https://ai.google.dev/"><img src="https://img.shields.io/badge/Gemini-Free%20Tier-4285F4?logo=google&logoColor=white" alt="Gemini Free Tier"/></a> </p> </td> </tr> </table>

---

Disclaimer: This is an unofficial, community-driven open-source implementation of the paper "PaperBanana: Automating Academic Illustration for AI Scientists" by Dawei Zhu, Rui Meng, Yale Song, Xiyu Wei, Sujian Li, Tomas Pfister, and Jinsung Yoon (arXiv:2601.23265). This project is not affiliated with or endorsed by the original authors or Google Research. The implementation is based on the publicly available paper and may differ from the original system.

An agentic framework for generating publication-quality academic diagrams and statistical plots from text descriptions. Supports OpenAI (GPT-5.2 + GPT-Image-1.5), Azure OpenAI / Foundry, Google Gemini, and Atlas Cloud providers.

• Two-phase multi-agent pipeline with iterative refinement
• Multiple VLM and image generation providers (OpenAI, Azure, Gemini, Atlas Cloud)
• Input optimization layer for better generation quality
• Auto-refine mode and run continuation with user feedback
• CLI, Python API, and MCP server for IDE integration
• Batch generation from a manifest file (YAML/JSON) for multiple diagrams in one run
• Batch plots — paperbanana plot-batch runs many statistical plots from one manifest (CSV/JSON per item)
• PDF inputs for methodology context (optional paperbanana[pdf] / PyMuPDF), with per-page selection
• PaperBanana Studio — local Gradio web UI (paperbanana studio) for diagrams, plots, evaluation, batch, and run browser
• Claude Code skills for /generate-diagram, /generate-plot, and /evaluate-diagram

<p align="center"> <img src="assets/img/hero_image.png" alt="PaperBanana takes paper as input and provide diagram as output" style="max-width: 960px; width: 100%; height: auto;"/> </p>

Atlas Cloud

<p align="center"> <img src="assets/sponsors/atlas_cloud_logo.png" alt="Atlas Cloud Logo" width="180"/> </p>

Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities.

Check out Atlas Cloud's new coding plan promotion for more budget-friendly API access: https://www.atlascloud.ai/console/coding-plan

---

Quick Start

Try it in your browser: the Colab quickstart notebook walks through install → API key → diagram generation end-to-end, no local setup required.

Prerequisites

• Python 3.10+
• An OpenAI API key (platform.openai.com) or Azure OpenAI / Foundry endpoint
• Or a Google Gemini API key (free, Google AI Studio)

Step 1: Install

pip install paperbanana

Or install from source for development:

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"

Docker

Build the image from a clone of the repo and pass your API key at runtime:

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

To generate a diagram, mount your input and an outputs folder into /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"

Step 2: Get Your API Key

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

Or use the setup wizard for Gemini:

paperbanana setup

Step 3: Generate a Diagram

paperbanana generate \
  --input examples/sample_inputs/transformer_method.txt \
  --caption "Overview of our encoder-decoder architecture with sparse routing"

With input optimization and auto-refine:

paperbanana generate \
  --input my_method.txt \
  --caption "Overview of our encoder-decoder framework" \
  --optimize --auto

Output is saved to outputs/run_<timestamp>/final_output.png along with all intermediate iterations and metadata.

PaperBanana Studio (local web UI)

Install the optional Gradio dependency, then start the app:

pip install 'paperbanana[studio]'
paperbanana studio

Open the URL shown in the terminal (default http://127.0.0.1:7860/). The Studio exposes the same workflows as the CLI: methodology diagrams, statistical plots, comparative evaluation, continuing a prior run, batch manifests (methodology or plot batch via the Batch tab), and a simple browser for run_* / batch_* output folders. Use --host, --port, --config, and --output-dir as needed.

---

How It Works

PaperBanana implements a multi-agent pipeline with up to 7 specialized agents:

Phase 0 -- Input Optimization (optional, --optimize):

0. Input Optimizer runs two parallel VLM calls:
   • Context Enricher structures raw methodology text into diagram-ready format (components, flows, groupings, I/O)
   • Caption Sharpener transforms vague captions into precise visual specifications

Phase 1 -- Linear Planning:

1. Retriever selects the most relevant reference examples from a curated set of 13 methodology diagrams spanning agent/reasoning, vision/perception, generative/learning, and science/applications domains
2. Planner generates a detailed textual description of the target diagram via in-context learning from the retrieved examples
3. Stylist refines the description for visual aesthetics using NeurIPS-style guidelines (color palette, layout, typography)

Phase 2 -- Iterative Refinement:

4. Visualizer renders the description into an image
5. Critic evaluates the generated image against the source context and provides a revised description addressing any issues
6. Steps 4-5 repeat for a fixed number of iterations (default 3), or until the critic is satisfied (--auto)

Providers

PaperBanana supports multiple VLM and image generation providers:

| Component | Provider | Model | Notes | |-----------|----------|-------|-------| | VLM (planning, critique) | OpenAI | gpt-5.2 | Default | | Image Generation | OpenAI | gpt-image-1.5 | Default | | VLM | Atlas Cloud | deepseek-ai/DeepSeek-V3-0324 | OpenAI-compatible chat endpoint | | Image Generation | Atlas Cloud | openai/gpt-image-2/text-to-image | Async prediction API | | VLM | Google Gemini | gemini-2.5-flash | Low cost | | Image Generation | Google Gemini | gemini-3-pro-image-preview | $0.134/image (1K) | | VLM / Image | OpenRouter | Any supported model | Flexible routing |

Azure OpenAI / Foundry endpoints are auto-detected — set OPENAI_BASE_URL to your endpoint. Gemini-compatible gateways are also supported — set GOOGLE_BASE_URL when needed. Atlas Cloud uses ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1 for chat and ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1 for image generation.

Atlas Cloud official site: https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=paperbanana

Recommended Atlas LLM models for ATLASCLOUD_VLM_MODEL:

• deepseek-ai/DeepSeek-V3-0324 (default)
• openai/gpt-4o
• openai/gpt-4.1
• google/gemini-2.5-flash
• anthropic/claude-sonnet-4.5-20250929

These are stable, generally available models verified against the Atlas Cloud API. The full, always-current model pool (300+ models) is documented on Atlas Cloud's own docs — see https://www.atlascloud.ai/models — and any model id listed there can be passed via ATLASCLOUD_VLM_MODEL.

Recommended Atlas image models for ATLASCLOUD_IMAGE_MODEL:

• 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 Reference

paperbanana generate -- Methodology Diagrams

# 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

| Flag | Short | Description | |------|-------|-------------| | --input | -i | Path to methodology text file or