# 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)
```

![Pipeline Data Flow Diagram](./docs/diagrams/pipeline_flow.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](https://aistudio.google.com/apikey))
- SSH or HTTPS access to the repo

## Quick Start

### Automatic (recommended)

```bash
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

```bash
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:

```json
{
  "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

```bash
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.

![Resume path data flow diagram](./docs/diagrams/pipeline_resume_path.png)

### 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

```bash
# 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

![Pipeline I/O](./docs/diagrams/pipeline_agent_io.png)

## Conncurrent Optimization

![Concurrent Optimization Path](./docs/diagrams/pipeline_optimizer_concurrent.png)

## Run state persistence

![State persistence diagram](docs/diagrams/pipeline_run_state.png)