paperbanana
Gere diagramas de metodologia para o seu artigo de pesquisa
Documentação
|
PaperBananaIlustração Acadêmica Automatizada para Cientistas de IA
|
Aviso: Esta é uma implementação de código aberto não oficial, conduzida pela comunidade do artigo "PaperBanana: Automating Academic Illustration for AI Scientists" de Dawei Zhu, Rui Meng, Yale Song, Xiyu Wei, Sujian Li, Tomas Pfister e Jinsung Yoon (arXiv:2601.23265). Este projeto não é afiliado ou endossado pelos autores originais ou pela Google Research. A implementação é baseada no artigo publicamente disponível e pode diferir do sistema original.
Um framework agêntico para gerar diagramas acadêmicos de qualidade de publicação e gráficos estatísticos a partir de descrições de texto. Suporta OpenAI (GPT-5.2 + GPT-Image-1.5), Azure OpenAI / Foundry, Google Gemini e provedores Atlas Cloud.
- Pipeline multiagente em duas fases com refinamento iterativo
- Múltiplos provedores de VLM e geração de imagens (OpenAI, Azure, Gemini, Atlas Cloud)
- Camada de otimização de entrada para melhor qualidade de geração
- Modo de refinamento automático e continuação de execução com feedback do usuário
- CLI, API Python e servidor MCP para integração com IDE
- Geração em lote a partir de um arquivo de manifesto (YAML/JSON) para múltiplos diagramas em uma única execução
- Gráficos em lote —
paperbanana plot-batchexecuta muitos gráficos estatísticos a partir de um manifesto (CSV/JSON por item) - Entradas em PDF para contexto de metodologia (opcional
paperbanana[pdf]/ PyMuPDF), com seleção por página - PaperBanana Studio — interface web local em Gradio (
paperbanana studio) para diagramas, gráficos, avaliação, lote e navegador de execuções - Habilidades Claude Code para
/generate-diagram,/generate-plote/evaluate-diagram
Aprendendo conceitos de LLM? Também publicamos 211 cartões visuais gratuitos sobre atenção, RAG, agentes e inferência. Leia-os online.
Atlas Cloud
Atlas Cloud é uma plataforma de inferência de IA multimodal que dá aos desenvolvedores uma única API de IA para acessar APIs de geração de vídeo, geração de imagens e LLM. Em vez de gerenciar múltiplas integrações de fornecedores, você conecta uma vez e obtém acesso unificado a mais de 300 modelos selecionados em todas as modalidades.
Confira a nova promoção do plano de codificação da Atlas Cloud para acesso mais econômico à API: https://www.atlascloud.ai/console/coding-plan
Início Rápido
Experimente no seu navegador: o notebook de início rápido do Colab percorre instalação → chave de API → geração de diagrama de ponta a ponta, sem necessidade de configuração local.
Pré-requisitos
- Python 3.10+
- Uma chave de API OpenAI (platform.openai.com) ou endpoint Azure OpenAI / Foundry
- Ou uma chave de API Google Gemini (gratuita, Google AI Studio)
Passo 1: Instalar
pip install paperbanana
Ou instale a partir do código-fonte para desenvolvimento:
git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"
Docker
Construa a imagem a partir de um clone do repositório e passe sua chave de API em tempo de execução:
docker build -t paperbanana .
docker run --rm -e GOOGLE_API_KEY paperbanana generate --help
Para gerar um diagrama, monte sua entrada e uma pasta de saídas em /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"
Passo 2: Obtenha Sua Chave de API
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
Ou use o assistente de configuração para Gemini:
paperbanana setup
Passo 3: Gere um Diagrama
paperbanana generate \
--input examples/sample_inputs/transformer_method.txt \
--caption "Overview of our encoder-decoder architecture with sparse routing"
Com otimização de entrada e refinamento automático:
paperbanana generate \
--input my_method.txt \
--caption "Overview of our encoder-decoder framework" \
--optimize --auto
A saída é salva em outputs/run_<timestamp>/final_output.png junto com todas as iterações intermediárias e metadados.
PaperBanana Studio (interface web local)
Instale a dependência opcional do Gradio e inicie o aplicativo:
pip install 'paperbanana[studio]'
paperbanana studio
Abra a URL mostrada no terminal (padrão http://127.0.0.1:7860/). O Studio expõe os mesmos fluxos de trabalho da CLI: diagramas de metodologia, gráficos estatísticos, avaliação comparativa, continuação de uma execução anterior, manifestos em lote (metodologia ou lote de gráficos via aba Lote) e um navegador simples para pastas de saída run_* / batch_*. Use --host, --port, --config e --output-dir conforme necessário.
Como Funciona
O PaperBanana implementa um pipeline multiagente com até 7 agentes especializados:
Fase 0 -- Otimização de Entrada (opcional, --optimize):
- Otimizador de Entrada executa duas chamadas VLM em paralelo:
- Enriquecedor de Contexto estrutura o texto bruto da metodologia em formato pronto para diagrama (componentes, fluxos, agrupamentos, E/S)
- Afiador de Legenda transforma legendas vagas em especificações visuais precisas
Fase 1 -- Planejamento Linear:
- Recuperador seleciona os exemplos de referência mais relevantes de um conjunto curado de 13 diagramas de metodologia abrangendo domínios de agente/raciocínio, visão/percepção, generativo/aprendizado e ciência/aplicações
- Planejador gera uma descrição textual detalhada do diagrama alvo via aprendizado em contexto a partir dos exemplos recuperados
- Estilista refina a descrição para estética visual usando diretrizes de estilo NeurIPS (paleta de cores, layout, tipografia)
Fase 2 -- Refinamento Iterativo:
- Visualizador renderiza a descrição em uma imagem
- Crítico avalia a imagem gerada em relação ao contexto de origem e fornece uma descrição revisada abordando quaisquer problemas
- Os passos 4-5 se repetem por um número fixo de iterações (padrão 3), ou até que o crítico esteja satisfeito (
--auto)
Provedores
O PaperBanana suporta múltiplos provedores de VLM e geração de imagens:
| Componente | Provedor | Modelo | Notas |
|---|---|---|---|
| VLM (planejamento, crítica) | OpenAI | gpt-5.2 | Padrão |
| Geração de Imagens | OpenAI | gpt-image-1.5 | Padrão |
| VLM | Atlas Cloud | deepseek-ai/DeepSeek-V3-0324 | Endpoint de chat compatível com OpenAI |
| Geração de Imagens | Atlas Cloud | openai/gpt-image-2/text-to-image | API de previsão assíncrona |
| VLM | Google Gemini | gemini-2.5-flash | Baixo custo |
| Geração de Imagens | Google Gemini | gemini-3-pro-image-preview | $0,134/imagem (1K) |
| VLM / Imagem | OpenRouter | Qualquer modelo suportado | Roteamento flexível |
Endpoints Azure OpenAI / Foundry são detectados automaticamente — defina OPENAI_BASE_URL para seu endpoint.
Gateways compatíveis com Gemini também são suportados — defina GOOGLE_BASE_URL quando necessário.
A Atlas Cloud usa ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1 para chat e ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1 para geração de imagens.
Site oficial da Atlas Cloud: https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=paperbanana
Modelos LLM Atlas recomendados para ATLASCLOUD_VLM_MODEL:
deepseek-ai/DeepSeek-V3-0324(padrão)openai/gpt-4oopenai/gpt-4.1google/gemini-2.5-flashanthropic/claude-sonnet-4.5-20250929
Estes são modelos estáveis, geralmente disponíveis, verificados contra a API da Atlas Cloud. O pool completo de modelos, sempre atualizado (300+ modelos), está documentado na própria documentação da Atlas Cloud — veja https://www.atlascloud.ai/models — e qualquer id de modelo listado lá pode ser passado via ATLASCLOUD_VLM_MODEL.
Modelos de imagem Atlas recomendados para ATLASCLOUD_IMAGE_MODEL:
openai/gpt-image-2/text-to-imageopenai/gpt-image-2/editbaidu/ERNIE-Image-Turbo/text-to-imageblack-forest-labs/flux-devblack-forest-labs/flux-schnellqwen/qwen-image
Referência da CLI
paperbanana generate -- Diagramas de Metodologia
# 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 | Curto | Descrição |
|---|---|---|
--input | -i | Caminho para arquivo de texto de metodologia ou PDF (obrigatório para novas execuções) |
--caption | -c | Legenda da figura / intenção comunicativa (obrigatório para novas execuções) |
--image | Imagem de referência/esboço (esboço à mão, foto de quadro branco, figura anterior) que guia o Planejador. Repetível para múltiplas imagens | |
--output | -o | Caminho da imagem de saída (padrão: gerado automaticamente em outputs/) |
--iterations | -n | Número de rodadas de refinamento Visualizador-Crítico (padrão: 3) |
--num-candidates | -k | Gera N imagens candidatas em paralelo, 1-8 (padrão: 1). O planejamento executa uma vez; o refinamento se expande por candidato com deslocamentos de semente. As saídas ficam em candidates/cand_<i>/; a raiz da execução final_output é o candidato 1. As estimativas de custo e --budget consideram a expansão |
--auto | Loop até o crítico estar satisfeito (com limite de segurança --max-iterations) | |
--max-iterations | Limite de segurança para o modo --auto (padrão: 30) | |
--optimize | Pré-processa entradas com enriquecimento de contexto paralelo e afiação de legenda | |
--continue | Continua da execução mais recente em outputs/ | |
--continue-run | Continua de um ID de execução específico | |
--feedback | Feedback do usuário para o crítico ao continuar uma execução | |
--pdf-pages | Apenas entrada em PDF: páginas baseadas em 1 (ex.: 1-5, 2,4,6-8; padrão: todas) | |
--vlm-provider | Nome do provedor VLM (padrão: openai) | |
--vlm-model | Nome do modelo VLM (padrão: gpt-5.2) | |
--image-provider | Provedor de geração de imagens (padrão: openai_imagen) | |
--image-model | Modelo de geração de imagens (padrão: gpt-image-1.5) | |
--format | -f | Formato de saída: png, jpeg ou webp (padrão: png) |
--config | Caminho para arquivo de configuração YAML (veja configs/config.yaml) | |
--verbose | -v | Mostra progresso detalhado do agente e tempos |
--progress-json | Emite eventos de progresso JSON para stdout durante a geração |
paperbanana plot -- Gráficos Estatísticos
paperbanana plot \
--data results.csv \
--intent "Bar chart comparing model accuracy across benchmarks"
| Flag | Curto | Descrição |
|---|---|---|
--data | -d | Caminho para arquivo de dados, CSV ou JSON (obrigatório) |
--intent | Intenção comunicativa para o gráfico (obrigatório) | |
--output | -o | Caminho da imagem de saída |
--iterations | -n | Iterações de refinamento (padrão: 3) |
--vlm-provider | Nome do provedor VLM | |
--vlm-model | Nome do modelo VLM |
Os gráficos são renderizados via código matplotlib gerado por VLM — nenhum provedor de geração de imagens ou credenciais são necessários.
paperbanana venues -- Pacotes de Estilo de Local Personalizados
--venue seleciona um pacote de estilo de local: um diretório com methodology_style_guide.md, plot_style_guide.md e um venue.yaml opcional. Pacotes integrados (neurips, icml, acl, ieee) acompanham o PaperBanana; você pode adicionar os seus próprios em ~/.config/paperbanana/venues/ (substitua com --venue-dir ou PAPERBANANA_VENUE_DIR) sem tocar no repositório:
# 1. Scaffold a pack (seeds both guides from the NeurIPS templates)
paperbanana venues init mylab
# 2. Edit the style guides — or generate them from a corpus of example figures:
# paperbanana guidelines synthesize --reference-set ./examples \
# --output ~/.config/paperbanana/venues/mylab/methodology_style_guide.md
# 3. Use it anywhere --venue is accepted
paperbanana generate --input method.txt --caption "Overview" --venue mylab
# See everything that's available (built-in + user, with source)
paperbanana venues list
venue.yaml (todos os campos opcionais):
display_name: "My Lab Style" # shown by `paperbanana venues list`
aspect_ratio: "16:9" # default --aspect-ratio for this venue's runs
fonts: # preferred fonts, appended to the style guides
- "Helvetica"
Em caso de conflito de nomes, os pacotes integrados vencem — pacotes de usuário não podem sobrepor locais integrados. Nomes de locais desconhecidos falham rapidamente com a lista de pacotes disponíveis de ambas as fontes.
paperbanana batch -- Geração em Lote
Gere múltiplos diagramas de metodologia a partir de um único arquivo de manifesto (YAML ou JSON). Cada item executa o pipeline completo; as saídas são gravadas em outputs/batch_<id>/run_<id>/ e um batch_report.json resume todas as execuções.
paperbanana batch --manifest examples/batch_manifest.yaml --optimize
Formato do manifesto (YAML ou JSON com uma lista items):
items:
- input: path/to/method1.txt
caption: "Overview of our encoder-decoder"
id: fig1
- input: method2.txt
caption: "Training pipeline"
id: fig2
- input: paper.pdf
caption: "System overview"
id: fig3
pdf_pages: "4-9" # optional; PDF inputs only
Os caminhos no manifesto são resolvidos em relação ao diretório do arquivo de manifesto.
Figuras compostas: Adicione uma seção opcional composite para combinar automaticamente todos os painéis gerados em uma única figura rotulada após a conclusão do lote:
composite:
layout: "1x3" # rows x cols, or "auto"
labels: auto # (a), (b), (c)... or explicit list, or null
spacing: 20 # pixels between panels
label_position: bottom # top or bottom
output: "composite.png"
items:
- input: method_encoder.txt
caption: "Encoder architecture"
id: panel_a
# ...
A imagem composta é salva junto aos painéis individuais no diretório de saída do lote. Consulte examples/composite_batch_manifest.yaml para um exemplo completo.
Gere um relatório legível por humanos a partir de uma execução de lote existente (Markdown ou HTML):
paperbanana batch-report --batch-dir outputs/batch_20250109_123456_abc --format markdown
# or by batch ID (under default output dir)
paperbanana batch-report --batch-id batch_20250109_123456_abc --format html --output report.html
Relatórios de lote de diagramas incluem batch_kind: methodology; lotes de gráficos usam batch_kind: statistical_plot. Relatórios legíveis por humanos (paperbanana batch-report) mostram o tipo de lote quando presente.
Manifestos de varredura permitem armazenar o plano completo de varredura como YAML/JSON em vez de oito flags de CLI separadas por vírgula. Mutuamente exclusivos com as flags de eixo; consulte examples/sweep_manifest.yaml.
paperbanana sweep --manifest examples/sweep_manifest.yaml
Relatórios de varredura produzidos por paperbanana sweep podem ser renderizados da mesma forma:
paperbanana sweep-report --sweep-dir outputs/sweep_20250109_123456_abc --format html
# or by sweep ID
paperbanana sweep-report --sweep-id sweep_20250109_123456_abc --format markdown
Relatórios de varredura renderizados incluem um resumo, uma tabela classificada top-5, a tabela completa de variantes (com provedor/modelo por variante, iterações, contagem de sugestões do crítico, pontuação proxy e caminho de saída) e a nota quality_proxy_score. Relatórios de execução simulada renderizam uma seção simplificada "Variantes Planejadas".
| Flag | Curto | Descrição |
|---|---|---|
--manifest | -m | Caminho para o arquivo de manifesto (obrigatório) |
--output-dir | -o | Diretório pai para a execução do lote (padrão: outputs) |
--config | Caminho para o YAML de configuração | |
--iterations | -n | Iterações de refinamento por item |
--optimize | Pré-processar entradas para cada item | |
--auto | Repetir até o crítico ficar satisfeito por item | |
--format | -f | Formato de imagem de saída (png, jpeg, webp) |
--auto-download-data | Baixar automaticamente o conjunto de referência PaperBananaBench (~254 MB) se não estiver em cache |
paperbanana plot-batch -- Gráficos Estatísticos em Lote
Gere múltiplos gráficos a partir de um manifesto (YAML ou JSON). Cada item especifica um arquivo de dados (CSV ou JSON) e uma string de intenção, espelhando paperbanana plot. As saídas ficam em outputs/batch_<id>/run_<id>/ com o mesmo fluxo de trabalho batch_report.json e paperbanana batch-report dos lotes de diagramas.
paperbanana plot-batch --manifest examples/plot_batch_manifest.yaml --optimize
Formato do manifesto (lista items):
items:
- data: path/to/results.csv
intent: "Bar chart comparing accuracy across models"
id: fig_acc
- data: other.json
intent: "Scatter plot with trend line"
aspect_ratio: "16:9" # optional per item; CLI --aspect-ratio is the default when omitted
Os caminhos são resolvidos em relação ao diretório do arquivo de manifesto.
| Flag | Curto | Descrição |
|---|---|---|
--manifest | -m | Caminho para o manifesto (obrigatório) |
--output-dir | -o | Diretório pai para batch_* (padrão: outputs) |
--config | Caminho para o YAML de configuração | |
--vlm-provider | Provedor VLM (padrão: gemini) | |
--vlm-model | Substituição do modelo VLM | |
--image-provider | Provedor de geração de imagem | |
--image-model | Modelo de geração de imagem | |
--iterations | -n | Iterações de refinamento por item |
--auto | Repetir até o crítico ficar satisfeito por item | |
--max-iterations | Limite de segurança para --auto | |
--optimize | Otimização de entrada por item | |
--format | -f | png, jpeg ou webp |
--save-prompts / --no-save-prompts | Persistir prompts (padrão: ativado, igual a plot) | |
--venue | Pacote de estilo de evento: integrado (neurips, icml, acl, ieee), um pacote de usuário ou custom | |
--aspect-ratio | -ar | Proporção de aspecto padrão quando não definida no manifesto |
--verbose | -v | Registro detalhado |
paperbanana orchestrate -- Pacote de Figuras de Artigo Completo
Gere um pacote de figuras focado em publicação a partir de uma fonte de artigo completo, com gráficos opcionais orientados a dados. O comando:
- analisa o artigo (
.txt,.mdou.pdf) - planeja múltiplas figuras de metodologia a partir da estrutura de seções
- opcionalmente descobre arquivos CSV/JSON para planejar gráficos estatísticos
- executa a geração de todos os itens planejados
- escreve uma pasta de pacote contendo
figure_package.json,figures/,figures.texecaptions.md
paperbanana orchestrate \
--paper paper.pdf \
--data-dir ./results \
--max-method-figures 4 \
--max-plot-figures 3 \
--optimize
Use --dry-run para apenas planejar e inspecionar orchestration_plan.json sem chamadas de API.
Use --resume-orchestrate <id-or-path> para continuar uma orquestração interrompida a partir do estado de checkpoint.
| Flag | Descrição |
|---|---|
--paper / -p | Caminho da fonte do artigo (.txt, .md ou .pdf) |
--resume-orchestrate | Retomar uma orquestração existente por ID ou diretório |
--retry-failed | Ao retomar, incluir tarefas que falharam anteriormente |
--max-retries | Tentativas extras por tarefa após a primeira falha |
--data-dir | Diretório opcional contendo arquivos CSV/JSON para planejamento de gráficos |
--output-dir / -o | Diretório de saída pai (cria orchestrate_*) |
--max-method-figures | Máximo de figuras de metodologia para planejar/gerar |
--max-plot-figures | Máximo de figuras de gráficos para planejar/gerar |
--pdf-pages | Seleção de páginas somente PDF (ex.: 1-5, 2,4,6-8) |
--optimize | Habilitar otimização de entrada para itens gerados |
--iterations / -n | Iterações de refinamento por item gerado |
--auto + --max-iterations | Modo de refinamento automático orientado por crítico com limite de segurança |
--concurrency | Trabalhadores paralelos de geração de figuras |
--format / -f | Formato de saída (png, jpeg, webp) |
--dry-run | Apenas planejar pacote; sem chamadas de geração |
paperbanana composite -- Compor Figuras Multi-Painel
Combine múltiplas imagens em uma única figura rotulada com rótulos de sub-painel (a), (b), (c):
paperbanana composite \
panel_a.png panel_b.png panel_c.png \
--layout 1x3 \
--output figure2.png
| Flag | Curto | Descrição |
|---|---|---|
IMAGES | Posicional: caminhos para as imagens a compor | |
--layout | -l | Layout de grade: RxC (ex.: 1x3, 2x2) ou auto (padrão: automático) |
--labels | Rótulos separados por vírgula, ou none para desativar (padrão: automático (a),(b),...) | |
--spacing | -s | Espaçamento em pixels entre painéis (padrão: 20) |
--label-position | top ou bottom (padrão: inferior) | |
--label-font-size | Tamanho da fonte para rótulos (padrão: 32) | |
--output | -o | Caminho de saída (padrão: composite_output.png) |
Este comando funciona em qualquer imagem existente — nenhuma chamada de API necessária. Também é acionado automaticamente quando um manifesto de lote inclui uma seção composite (veja paperbanana batch acima).
paperbanana evaluate -- Avaliação de Qualidade
Avaliação comparativa de um diagrama gerado contra uma referência humana usando VLM-como-Juiz:
paperbanana evaluate \
--generated diagram.png \
--reference human_diagram.png \
--context method.txt \
--caption "Overview of our framework"
| Flag | Curto | Descrição |
|---|---|---|
--generated | -g | Caminho para a imagem gerada (obrigatório) |
--reference | -r | Caminho para a imagem de referência humana (obrigatório) |
--context | Caminho para o arquivo de texto de contexto de origem ou PDF (obrigatório) | |
--caption | -c | Legenda da figura (obrigatório) |
--pdf-pages | Somente contexto PDF: seleção de páginas baseada em 1 (padrão: todas) |
Pontuações em 4 dimensões (agregação hierárquica conforme o artigo):
- Primárias: Fidelidade, Legibilidade
- Secundárias: Concisão, Estética
paperbanana polish -- Refinar uma Figura Existente
Traga sua própria figura: um VLM a audita contra o guia de estilo do evento e propõe até 10 melhorias concretas e acionáveis, então um provedor capaz de edição de imagem as aplica à figura original (edição guiada). As sugestões são impressas no console para que você veja exatamente o que mudou.
paperbanana polish --input figure.png
paperbanana polish --input figure.png --venue icml --iterations 2 --output polished.png
| Flag | Curto | Descrição |
|---|---|---|
--input | -i | Caminho para a imagem da figura existente (obrigatório) |
--output | -o | Caminho de saída (padrão: outputs/polish_<timestamp>/final_output.png) |
--venue | Guia de estilo do evento: neurips (padrão), icml, acl, ieee, custom | |
--iterations | -n | Rodadas de polimento; cada rodada sugere e aplica melhorias no resultado anterior (padrão: 1) |
--aspect-ratio | -ar | Proporção de aspecto alvo (padrão: preservar a proporção da figura de entrada) |
--num-candidates | -k | Aplicar as sugestões de cada rodada N vezes em paralelo (1-8) |
--budget | Limite de orçamento em USD; o polimento para graciosamente quando excedido | |
--seed | Semente aleatória para edições reproduzíveis |
Requer um provedor de imagem que suporte edições de imagem guiadas (modelos de imagem Google Gemini). Se a figura já estiver em conformidade com o guia de estilo, o polimento sai sem fazer alterações.
paperbanana studio -- Interface web local
Requer pip install 'paperbanana[studio]' (Gradio).
paperbanana studio
paperbanana studio --port 8080 --output-dir ./my_outputs
| Flag | Descrição |
|---|---|
--host | Endereço de vinculação (padrão 127.0.0.1) |
--port | Porta (padrão 7860) |
--share | Criar um link público temporário do Gradio (não use com dados sensíveis) |
--config | Caminho para o YAML de configuração |
--output-dir / -o | Diretório de saída padrão para execuções |
--root-path | Subcaminho de URL quando atrás de um proxy reverso |
paperbanana setup -- Configuração Inicial
paperbanana setup
Assistente interativo que primeiro pergunta se deseja usar a API oficial do Gemini. Se você escolher a API oficial, ele segue o fluxo padrão de chave do AI Studio; se não, ele pede uma URL personalizada compatível com Gemini e uma chave de API.
paperbanana data -- Conjunto de Dados de Referência
# Download the PaperBananaBench reference set (~254 MB, one command)
paperbanana data download
# Import plot references too (or both)
paperbanana data download --task plot
paperbanana data download --task both
# Inspect / clear the cache
paperbanana data info
paperbanana data clear
O conjunto de dados é servido a partir de um espelho de release do GitHub hospedado pelo projeto
(bench-data-v1)
e sua soma de verificação SHA256 é verificada antes da extração. Crédito aos
autores do PaperBananaBench —
o espelho acompanha a revisão de 2026-03-22 deles. O conjunto é armazenado em cache em
~/.cache/paperbanana/ (substituível com PAPERBANANA_CACHE_DIR); comandos de
geração também podem buscá-lo no primeiro uso via --auto-download-data.
API Python
import asyncio
from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings
settings = Settings(
vlm_provider="openai",
vlm_model="gpt-5.2",
image_provider="openai_imagen",
image_model="gpt-image-1.5",
optimize_inputs=True, # Enable input optimization
auto_refine=True, # Loop until critic is satisfied
)
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}")
Callbacks de progresso: generate() e continue_run() aceitam um argumento opcional progress_callback. O pipeline o invoca com objetos PipelineProgressEvent (estágio, mensagem, segundos, iteração, extra) em cada etapa (otimizador, recuperador, planejador, estilista, visualizador, crítico), para que você possa mostrar progresso em UIs ou registrar tempos sem corrigir agentes.
Para continuar uma execução anterior:
from paperbanana.core.resume import load_resume_state
state = load_resume_state("outputs", "run_20260218_125448_e7b876")
result = asyncio.run(pipeline.continue_run(
resume_state=state,
additional_iterations=3,
user_feedback="Make the encoder block more prominent",
))
Consulte examples/generate_diagram.py e examples/generate_plot.py para exemplos completos e funcionais.
Servidor MCP
O PaperBanana inclui um servidor MCP para uso com Claude Code, Cursor ou qualquer cliente compatível com MCP. Adicione a seguinte configuração para usá-lo via uvx sem um clone local:
{
"mcpServers": {
"paperbanana": {
"command": "uvx",
"args": ["--from", "paperbanana[mcp]", "paperbanana-mcp"],
"env": { "GOOGLE_API_KEY": "your-google-api-key" }
}
}
}
Onze ferramentas MCP são expostas: generate_diagram, generate_plot, continue_run (retomar um run_* anterior com feedback opcional), continue_diagram, continue_plot, evaluate_diagram, evaluate_plot, orchestrate_figures (pacotes de figuras de artigo completo), batch_diagrams, batch_plots e download_references.
O repositório também inclui 3 habilidades do Claude Code:
/generate-diagram <file> [caption]- gerar um diagrama de metodologia a partir de um arquivo de texto/generate-plot <data-file> [intent]- gerar um gráfico estatístico a partir de dados CSV/JSON/evaluate-diagram <generated> <reference>- avaliar um diagrama contra uma referência humana
Consulte mcp_server/README.md para detalhes completos de configuração (Claude Code, Cursor, desenvolvimento local).
Integração Overleaf (GitHub Action)
Mantenha a figura de metodologia do seu artigo em sincronia com o texto — automaticamente. O PaperBanana inclui uma GitHub Action que se integra à sincronização GitHub integrada do Overleaf: envie suas alterações .tex, a action extrai a seção de metodologia, gera a figura e envia de volta a imagem mais um trecho LaTeX pronto para \input. Puxe no Overleaf e ele estará na sua árvore de arquivos.
- uses: actions/checkout@v4
- uses: llmsresearch/paperbanana/integrations/github-action@main
with:
tex-file: sections/method.tex
caption: "Overview of our proposed framework"
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
Consulte integrations/github-action/README.md para ver o fluxo de trabalho completo, todas as entradas e opções de controle de custos.
Configuração
As configurações padrão estão em configs/config.yaml. Substitua-as por meio de flags de CLI ou de um YAML personalizado:
paperbanana generate \
--input method.txt \
--caption "Overview" \
--config my_config.yaml
Configurações principais:
vlm:
provider: openai # openai, atlas, gemini, or openrouter
model: gpt-5.2
image:
provider: openai_imagen # openai_imagen, atlas_imagen, google_imagen, or openrouter_imagen
model: gpt-image-1.5
pipeline:
num_retrieval_examples: 10
refinement_iterations: 3
# auto_refine: true # Loop until critic is satisfied
# max_iterations: 30 # Safety cap for auto_refine mode
# optimize_inputs: true # Preprocess inputs for better generation
output_resolution: "2k"
reference:
path: data/reference_sets
output:
dir: outputs
save_iterations: true
save_metadata: true
Variáveis de ambiente (.env):
# OpenAI (default)
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1 # or Azure endpoint
OPENAI_VLM_MODEL=gpt-5.2 # override model
OPENAI_IMAGE_MODEL=gpt-image-1.5 # override model
# Atlas Cloud
ATLASCLOUD_API_KEY=your-key
ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
ATLASCLOUD_VLM_MODEL=deepseek-ai/DeepSeek-V3-0324
ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1
ATLASCLOUD_IMAGE_MODEL=openai/gpt-image-2/text-to-image
# Google Gemini (alternative, free)
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL= # optional custom Gemini-compatible endpoint
GOOGLE_VLM_MODEL=gemini-2.5-flash # override Gemini VLM model
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview # override Gemini image model
Estrutura do Projeto
paperbanana/
├── paperbanana/
│ ├── core/ # Pipeline orchestration, types, config, resume, utilities
│ ├── agents/ # Optimizer, Retriever, Planner, Stylist, Visualizer, Critic
│ ├── providers/ # VLM and image gen provider implementations
│ │ ├── vlm/ # OpenAI, Atlas Cloud, Gemini, OpenRouter VLM providers
│ │ └── image_gen/ # OpenAI, Atlas Cloud, Gemini, OpenRouter image gen providers
│ ├── reference/ # Reference set management (13 curated examples)
│ ├── guidelines/ # Style guidelines loader
│ └── evaluation/ # VLM-as-Judge evaluation system
├── configs/ # YAML configuration files
├── prompts/ # Prompt templates for all agents + evaluation
│ ├── diagram/ # context_enricher, caption_sharpener, retriever, planner, stylist, visualizer, critic
│ ├── plot/ # plot-specific prompt variants
│ └── evaluation/ # faithfulness, conciseness, readability, aesthetics
├── data/
│ ├── reference_sets/ # 13 verified methodology diagrams
│ └── guidelines/ # NeurIPS-style aesthetic guidelines
├── examples/ # Working example scripts + sample inputs
├── scripts/ # Data curation and build scripts
├── tests/ # Test suite
├── mcp_server/ # MCP server for IDE integration
└── .claude/skills/ # Claude Code skills (generate-diagram, generate-plot, evaluate-diagram)
Desenvolvimento
# Install with dev dependencies
pip install -e ".[dev,openai,google]"
# Run tests
pytest tests/ -v
# Lint
ruff check paperbanana/ mcp_server/ tests/ scripts/
# Format
ruff format paperbanana/ mcp_server/ tests/ scripts/
Citação
Esta é uma implementação não oficial. Se você usar este trabalho, cite o artigo original:
@article{zhu2026paperbanana,
title={PaperBanana: Automating Academic Illustration for AI Scientists},
author={Zhu, Dawei and Meng, Rui and Song, Yale and Wei, Xiyu
and Li, Sujian and Pfister, Tomas and Yoon, Jinsung},
journal={arXiv preprint arXiv:2601.23265},
year={2026}
}
Artigo original: https://arxiv.org/abs/2601.23265
Aviso Legal
Este projeto é uma reimplementação independente de código aberto baseada no artigo disponível publicamente. Não é afiliado, endossado ou conectado aos autores originais, ao Google Research ou à Universidade de Pequim de forma alguma. A implementação pode diferir do sistema original descrito no artigo. Use por sua conta e risco.
Licença
MIT