Paper Banana — Proposal Image Generator

A multiagent AI pipeline for generating process diagrams and CONOPS visuals for government and defense proposals. Based on the Paper Banana framework (arXiv 2601.23265), adapted for proposal-domain aesthetics and distributed as an MCP server.

Architecture

User Input (proposal text + caption/intent)
        |
        v
[1] Classifier Agent      Determines: process diagram vs. CONOPS image
        |
        v
[2] Retriever Agent       Selects N most relevant examples from library
        |                 (library starts empty; grows via add_example)
        v
[3] Planner Agent         Synthesizes detailed visual description (few-shot)
        |
        v
[4] Stylist Agent         Applies proposal-specific aesthetic guidelines
        |
        v
[5] Visualizer Agent      Calls gemini-3-pro-image-preview -> generates PNG
        |  ^
        |  | (refined description, up to T=3 rounds)
        v  |
[6] Critic Agent          Evaluates image, produces refined description
        |
        v
    Final Image (PNG)

Models

Agent	Model	Role
Extractor	gemini-3.6-flash	Pulls the relevant section from a full document
Optimizer	gemini-3.6-flash	Enriches context + sharpens caption (2 concurrent calls)
Classifier	gemini-3.6-flash	Fast classification, no deep reasoning needed
Retriever	gemini-3.6-flash	Relevance scoring across examples
Planner	gemini-3.1-pro-preview	Best reasoning for synthesizing visual descriptions
Stylist	gemini-3.1-pro-preview	Creative + domain-aware aesthetic refinement
Visualizer	gemini-3-pro-image	Image generation
Critic	gemini-3.6-flash	Different model family from Planner/Stylist (anti-bias)

Prerequisites

• A Gemini API key with access to the models listed above (get one at aistudio.google.com/apikey)
• SSH or HTTPS access to the repo

Quick Start

Automatic (recommended)

git clone git@github.com:lexicalninja/paper-banana.git
cd paper-banana
./install.sh

The install script will:

1. Install uv if needed
2. Prompt for your GOOGLE_API_KEY
3. Detect Claude Code and/or VS Code and configure them
4. Optionally seed the example library

On Windows, use install.ps1 instead.

Manual — Claude Code

claude mcp add paper-banana -e GOOGLE_API_KEY=your-key -- \
  uvx --from "git+ssh://git@github.com/lexicalninja/paper-banana.git" paper-banana

Manual — VS Code

You can install at the user level (available in every workspace) or the workspace level (scoped to one project).

User-level — edit ~/Library/Application Support/Code/User/mcp.json (macOS) or ~/.config/Code/User/mcp.json (Linux) or %APPDATA%\Code\User\mcp.json (Windows). Add paper-banana inside the top-level servers object:

{
  "servers": {
    "paper-banana": {
      "command": "uvx",
      "args": ["--from", "git+ssh://git@github.com/lexicalninja/paper-banana.git", "paper-banana"],
      "env": { "GOOGLE_API_KEY": "your-key" }
    }
  }
}

Workspace-level — add the same block to .vscode/mcp.json in your project root. This is safe to commit so teammates get the server automatically.

Local Development

pip install -e .
export GOOGLE_API_KEY=your-key
paper-banana

After setup, the generate_proposal_image and add_example tools will appear in your MCP client.

MCP Tools

generate_proposal_image

Generate a proposal diagram image.

Parameter	Type	Default	Description
caption	string	required	Communicative intent for the diagram
source_context	string	""	Raw proposal text to diagram
source_file	string	""	Path to a document file; section specifies which section to extract
section	string	""	Section heading to extract from source_file
image_type	string	"auto"	"process", "conops", or "auto" (classifier decides)
iterations	integer	3	Max visualizer/critic refinement cycles (1–5)
output_path	string	"output.png"	Where to save the generated PNG
save_artifacts	boolean	true	Save per-iteration PNGs + critique JSON to {stem}_artifacts/
export_schema	boolean	true	Append structured diagram YAML/JSON to critique file
brand	string	"mlst"	Visual identity profile: "mlst" (purple/blue) or "default" (navy/gov)
aspect_ratio	string	""	Pin output dimensions: "16:9", "4:3", "1:1", "3:4", or "" (Planner decides)
resume_from	string	""	Path to a {stem}_run/ directory from a prior run to resume from
user_feedback	string	""	Freeform feedback about the prior output; overrides original intent in the critic

Returns the absolute path to the saved PNG.

Resuming a run

Each run saves state to {output_stem}_run/run_input.json. Pass that directory to resume_from to skip the full pipeline and iterate from where you left off:

generate_proposal_image(
  caption="",
  resume_from="output/my_diagram_run",
  user_feedback="Add a decision diamond after step 2 with yes/no branches",
  iterations=2
)

Use user_feedback to steer the next generation. The pipeline critiques the existing image first, bakes the feedback into a revised description, then generates.

add_example

Add a reference image to the example library. The library starts empty; add examples over time to improve retrieval quality.

Parameter	Type	Description
description	string	Written description of what the image shows
image_path	string	Path to the image file
caption	string	Caption associated with the image
image_type	string	"process" or "conops"

Returns the unique ID assigned to the new example.

Cold Start

The library starts empty (examples/metadata.json contains []). On an empty library, the pipeline proceeds zero-shot (a warning is logged). Use add_example to build up a reference library over time. Retrieval quality improves noticeably after ~5 examples per diagram type.

Design Aesthetic

Two brand profiles ship with the server, selected via the brand parameter.

mlst (default) — MLST purple

Token	Hex	Usage
Brand purple	#73628A	Primary boxes, borders, headers, flow arrows
Muted purple	#9C8DAF	Secondary elements, highlights
Pale purple	#EAE8EE	Interior fill of content boxes
Blue	#3FA7D6	Data flows, supporting links
Coral	#FE5F55	Critical path, key decisions
Amber	#FAC05E	Alternate emphasis
Green	#59CD90	Confirmation states, approved paths
Off-white	#FAFAFA	Page background
Light gray	#EDEDED	Swimlanes, grouping zones
Near-black	#313131	Body text

default — government/defense

Token	Hex	Usage
Navy blue	#1B3A6B	Primary boxes, header bars, key actors
White	#FFFFFF	Text on dark backgrounds, box interiors
Gray	#6B7280	Connectors, borders, annotations
Light gray	#F3F4F6	Swimlane backgrounds, grouping zones
Deep orange	#C2410C	Decisions, critical path, highlights
Teal	#0D9488	Data flows, supporting systems, feedback paths

Running Directly

# Start the MCP server (used by VS Code / Claude Code)
python -m paper_banana.server

# Or via the installed entry point
paper-banana

Pipeline I/O

Conncurrent Optimization

Run state persistence