Development Guide

November 25, 2025 · View on GitHub

Thank you for your interest in contributing to bagel!

To contribute, please follow these general steps:

  1. Fork the repository and clone your fork locally.
  2. Create a feature branch for your changes.
  3. Use uv for dependency and environment management (see below).
  4. Follow the coding style and linting rules (enforced via pre-commit).
  5. Submit a pull request (PR) to the main repository for review.

We welcome contributions of all kinds — new features, bug fixes, documentation improvements, and test coverage.

For more detailed guidelines consult these Notion Docs.

Installation

First, you need to install the development dependencies:

uv sync --extra dev

If you are working on the optimization logic, using Modal should be sufficient; however, if you also need to debug individual Oracles locally, we suggest using a GPU and installing the local dependencies:

uv sync --extra local
# or install all extras
uv sync --all-extras

Documentation [Work In Progress]

Generate documentation:

uv run pydoclint src/bagel/* --style=sphinx

Testing

To run the tests, you must specify how to handle Oracles, i.e. whether to run remotely or not.

# Run tests while skipping Oracle execution
uv run pytest --oracles skip

# Alternative options:
# --oracles modal   # Use remote execution via Modal
# --oracles local   # Use local GPU-based execution

When using --oracles local, the MODEL_DIR environment variable must be set. You can either:

  • Set it in a .env file (copy .env.example to .env and update the path), or
  • Set it as an environment variable. If not set, it will default to an XDG-compliant location (~/.cache/bagel/models or $XDG_CACHE_HOME/bagel/models).

Commit Checking

On commit, MyPy, Ruff, and PyTest checks are all run to ensure code quality.

If any of these tests fail, this will be displayed on the corresponding GitHub pull request.

To automatically run code quality checks before each commit (recommended for contributors):

uv run pre-commit install

To disable the hooks:

uv run pre-commit uninstall

You can also run all checks manually at any time:

uv run pre-commit run --all-files