paperbanana copilot-instructions.md

Copilot Instructions for PaperBanana

Build & Test

# Install for development
pip install -e ".[dev,openai,google]"

# Run full test suite
pytest tests/ -v

# Run a single test file
pytest tests/test_pipeline/test_types.py -v

# Run a single test by name
pytest tests/ -k "test_critique_result_needs_revision" -v

# Lint
ruff check paperbanana/ mcp_server/ tests/ scripts/

# Format
ruff format paperbanana/ mcp_server/ tests/ scripts/

CI runs lint, tests (Python 3.10–3.12 on Linux/macOS/Windows), and package build. Tests must pass without a GOOGLE_API_KEY—all tests mock external providers.

Architecture

PaperBanana is an agentic framework that generates publication-quality academic diagrams from text. It implements a two-phase multi-agent pipeline:

Phase 1 — Linear Planning: Retriever → Planner → Stylist
Phase 2 — Iterative Refinement: Visualizer ↔ Critic (up to N rounds)

Key architectural layers:

• paperbanana/core/ — Pipeline orchestrator (pipeline.py), Pydantic data types (types.py), config via pydantic-settings (config.py). Settings loads from env vars, .env file, or YAML config.
• paperbanana/agents/ — Seven agents (Optimizer, Retriever, Planner, Stylist, Visualizer, Critic, plus InputOptimizer with parallel sub-tasks), all inheriting from BaseAgent. Each agent wraps a VLM provider and a prompt template loaded from prompts/.
• paperbanana/providers/ — Abstract VLMProvider and ImageGenProvider base classes in base.py. Concrete implementations in vlm/ (OpenAI, Gemini, OpenRouter) and image_gen/ (OpenAI, Google Imagen, OpenRouter). ProviderRegistry is the factory that creates providers from Settings.
• prompts/ — Text prompt templates organized by type (diagram/, plot/, evaluation/). Templates use {placeholder} formatting, loaded by BaseAgent.load_prompt().
• paperbanana/evaluation/ — VLM-as-Judge system. Scores on 4 dimensions (Faithfulness, Readability, Conciseness, Aesthetics) with hierarchical aggregation.
• mcp_server/ — FastMCP server exposing tools including generate_diagram, continue_run, generate_plot, evaluate_diagram, and evaluate_plot.
• data/reference_sets/ — 13 curated methodology diagram examples used for in-context learning by the Retriever agent.