paper-banana

PaperBanana — Academic Illustration Generator

Automatically generates publication-ready academic illustrations from paper text. Five agents (Retriever, Planner, Stylist, Visualizer, Critic) collaborate to generate and iteratively refine methodology diagrams, statistical charts, system architectures, etc.

Prerequisites

• paperbanana[mcp] package: pip install paperbanana[mcp]
• Environment variable GOOGLE_API_KEY setup (issued by Google AI Studio)
• When registering the MCP server: claude mcp add paperbanana -e GOOGLE_API_KEY=<key> -- uvx --from "paperbanana[mcp]" paperbanana-mcp

Core Commands

Generate Methodology Diagram

Enter methodology text from a paper to generate a publication-quality diagram.

paperbanana generate \
  --input <텍스트_파일.txt> \
  --caption "<Figure 캡션>" \
  --optimize --auto

Main options:

• --input / -i: methodology text file (.txt) or paper PDF (.pdf)
• --caption / -c: communicative intent (the key message the figure should convey)
• --optimize: improve quality through input preprocessing
• --auto: automatically iterate until the Critic is satisfied
• --iterations N / -n: number of manual iterations (default 3)
• --format [png|jpeg|webp]: output format

When inputting PDF:

paperbanana generate \
  --input paper.pdf \
  --caption "Overview of our framework" \
  --pdf-pages "3-8" \
  --optimize --auto

Generate Statistical Plot

Generates statistical charts from CSV data as Matplotlib code (ensuring mathematical accuracy).

paperbanana plot \
  --data <결과.csv> \
  --intent "<원하는 차트 설명>"

Quality Evaluation

Compares and evaluates the generated diagram against a reference image. Four criteria: Faithfulness, Readability, Conciseness, Aesthetics.

paperbanana evaluate \
  --generated <생성된_이미지.png> \
  --reference <참조_이미지.png> \
  --context <원본_텍스트.txt> \
  --caption "<캡션>"

Revise Previous Result

Continues revising from the previous result by incorporating user feedback.

paperbanana generate --continue --feedback "화살표를 더 굵게 해줘"
paperbanana generate --continue-run <run_ID> --iterations 3

Batch Generation

Generates multiple figures within a paper at once.

paperbanana batch --manifest manifest.yaml --optimize

manifest format:

items:
  - input: method1.txt
    caption: "Encoder-decoder overview"
    id: fig1
  - input: method2.txt
    caption: "Training pipeline"
    id: fig2

Python API

When calling directly at the code level:

import asyncio
from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings

settings = Settings(
    vlm_provider="google",
    vlm_model="gemini-2.5-pro",
    image_provider="google",
    image_model="gemini-2.5-flash",
    optimize_inputs=True,
    auto_refine=True,
)

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}")

Workflow

1. When the user provides paper text or a PDF, identify the parts to turn into figures
2. Write an appropriate caption (communicative intent) together with it — this becomes the core message of the figure
3. paperbanana generateGenerate with and show the resulting image to the user
4. If there is user feedback, revise with --continue --feedbackand revise
5. Save the final output in the workspace folder

Output Structure

outputs/run_<timestamp>_<hash>/
├── final_output.png      # 최종 이미지
├── metadata.json         # 생성 메타데이터
├── iterations/           # 반복 과정
│   ├── iteration_0.png
│   └── iteration_1.png
└── intermediate_states/  # 중간 상태

Usage Limits Reference (Gemini API Tier 2)

About 10 per figure20 API calls are consumed. With a Tier 2 limit of 500 requests per day, about 25 per day50 figures can be generated. On a rate limit error, retry after a moment or switch to the Flash-Lite model.