Skip to content

Contributing

Jump to bottom
dippatel1994 edited this page Feb 13, 2026 · 3 revisions

Contributing to PaperBanana

The most impactful contribution right now is improving the reference dataset. Output quality scales directly with reference quality, so even a single well-chosen example helps. However, we are open to improving distributions or adding new features. Support is always welcome.

Try it and report what works / breaks

Install from PyPI (pip install paperbanana), generate a few diagrams, and let us know what you find. Even without writing code, reports about output quality on different paper types help us prioritize improvements.

Contributing Reference Examples

PaperBanana uses a curated set of methodology diagrams for in-context learning. We need more diverse, high-quality samples across different diagram styles and research domains.

What makes a good reference example

  • The diagram clearly illustrates system architecture, pipeline flow, or framework structure
  • Landscape layout with aspect ratio roughly between 1.5 and 2.5 (width / height)
  • The methodology section in the paper is self-contained enough to describe the approach
  • The diagram is not a results plot, ablation table, t-SNE visualization, or data sample

Option 1: Submit a paper recommendation (easiest)

Open a Discussion post or an Issue with:

  • arXiv link (or other public paper URL)
  • Figure number of the methodology diagram
  • (Optional) Which category it falls under: Agent & Reasoning, Vision & Perception, Generative & Learning, or Science & Applications

We'll handle extraction and curation from there.

Option 2: Submit a parsed reference tuple (more involved)

Add a complete reference example via pull request. Each example is a directory under data/reference_sets/ containing three files:

data/reference_sets/your_example_name/
├── methodology.txt    # Extracted methodology section text
├── diagram.png        # Methodology diagram image
└── metadata.json      # Caption and metadata

metadata.json format:

{
  "paper_title": "Full paper title",
  "arxiv_id": "2601.23265",
  "figure_number": 2,
  "caption": "Original figure caption from the paper",
  "category": "agent_reasoning",
  "source_url": "https://arxiv.org/abs/2601.23265",
  "aspect_ratio": 1.85
}

Valid categories: agent_reasoning, vision_perception, generative_learning, science_applications

Before submitting, verify:

  • The methodology text matches what the diagram actually depicts
  • The diagram image is clean (no scan artifacts, readable at 800px width)
  • The aspect ratio is between 1.5 and 2.5
  • The paper is publicly available

Categories we're short on

  • Science & Applications: domain-specific architectures outside core ML
  • Vision & Perception: detection, segmentation, multimodal pipelines

Contributing Code

Development Setup

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,google]"

Pre-commit Hooks (Recommended)

We use pre-commit hooks to automatically format code before each commit. This prevents CI failures from formatting issues.

Install pre-commit:

pip install pre-commit
pre-commit install

What it does:

  • Runs ruff check --fix to auto-fix linting issues
  • Runs ruff format to format code

Manual run (check all files):

pre-commit run --all-files

If you skip pre-commit setup, CI will still check formatting and may reject PRs with unformatted code.

Running Tests

pytest tests/ -v

With coverage:

pytest tests/ -v --cov=paperbanana --cov-report=html
open htmlcov/index.html  # View coverage report

Code Style

We use ruff for linting and formatting:

ruff check paperbanana/ mcp_server/ tests/
ruff format paperbanana/ mcp_server/ tests/

Configuration is in pyproject.toml:

  • Line length: 100
  • Target Python: 3.10+

Pull Request Process

  1. Fork the repo and create a branch from main
  2. Install pre-commit hooks: pre-commit install
  3. Make your changes with clear, descriptive commit messages
  4. Add or update tests if applicable
  5. Ensure pytest and ruff check pass
  6. Open a PR with a brief description of what changed and why

CI Pipeline

Every PR runs:

  • Lint: ruff check and ruff format --check
  • Test: pytest on Ubuntu, Windows, macOS × Python 3.10, 3.11, 3.12
  • Build: Verifies package builds and installs correctly

All checks must pass before merging.

Areas Where Code Contributions Are Welcome

  • Provider support: Adding backends beyond Gemini (OpenAI, Anthropic, local models via Ollama)
  • Reference set tooling: Improving the automated extraction pipeline in scripts/
  • Evaluation: Expanding the VLM-as-Judge evaluation with additional metrics or human correlation studies
  • MCP server: Additional tools, better error handling, support for more IDE clients
  • Documentation: Usage examples, tutorials, edge case documentation
  • Architecture improvements: See Research Directions for ideas

Reporting Issues

When opening an issue, include:

  • What you were trying to do
  • The input you used (methodology text and caption)
  • The output you got (attach the generated image if possible)
  • Python version and OS
  • Any error messages or tracebacks

For diagram quality issues specifically, attaching both the generated output and the expected result (or a reference from the paper) helps us diagnose whether the issue is in retrieval, planning, or rendering.

Questions

Use GitHub Discussions for questions, ideas, and general conversation. Issues are for bugs and concrete feature requests.

Clone this wiki locally