Contributing to IBBI¶

Thank you for considering a contribution to IBBI! This page explains how to get help, how to set up a development environment and what a pull request should contain.

Seeking support¶

If you have a question about how to use ibbi, are unsure about a feature or have found a bug, open an issue on the GitHub issue tracker. Please include the ibbi version (ibbi.__version__), your Python, PyTorch and Ultralytics versions, and a minimal example that reproduces the problem.

Ways to contribute¶

Reporting bugs: open an issue describing the problem, the steps to reproduce it and what you expected.
Suggesting enhancements: open an issue to discuss the idea before writing code.
Improving the documentation: fixes and new examples for the docs or the notebooks are always welcome.
Adding models: see Adding a model below; please open an issue first.
Submitting pull requests: for bug fixes and agreed features.

Development environment¶

Clone the repository

git clone https://github.com/ChristopherMarais/IBBI.git
cd IBBI

Create an environment (conda shown; any Python ≥ 3.11 environment works)
```
conda env create -f environment.yml
conda activate IBBI
```

Install PyTorch for your hardware (pytorch.org), then the package with its development tools:

pip install torch torchvision                      # or the command pytorch.org gives for your system
poetry config virtualenvs.create false --local     # install into the active environment
poetry install --with dev

Without Poetry, pip install -e . pytest ruff is enough to run the tests.

Set up the pre-commit hooks (ruff lint and format, pyright and general checks on every commit):
```
pre-commit install
```

Tests¶

The test suite has two levels:

pytest -q tests                 # fast offline tests: synthetic benchmark, tiny models, no downloads (CPU, ~1 min)
pytest -q tests --run-slow      # also download every model from the Hub and run it (GPU recommended)

The fast tests run on GitHub Actions for Python 3.11 and 3.12 on every pull request, after ruff check src tests benchmarks. Please add tests for new behaviour; fixtures for a synthetic benchmark, a tiny classifier and an untrained YOLO model are in tests/conftest.py.

src/ibbi/evaluate/_reference_evaluator.py is the benchmark's reference evaluator, vendored unchanged: do not edit or reformat it (it is excluded from ruff).

Documentation¶

The documentation site is built with MkDocs Material from docs/ and mkdocs.yml; the API reference is generated from the docstrings (Google style).

mkdocs serve                    # live preview at http://127.0.0.1:8000
mkdocs build --strict           # check for broken links and docstring problems

The site at gcmarais.com/IBBI is deployed to the gh-pages branch by the Deploy documentation GitHub Action (.github/workflows/docs.yml) each time a release is published; it can also be run by hand from the Actions tab.

The benchmark tables in docs/benchmark.md and the summary in README.md are generated by benchmarks/make_tables.py from benchmarks/run_benchmark.py outputs; edit the scripts, not the tables. To rebuild only the README summary from the result files kept in benchmarks/results/, run python benchmarks/make_tables.py --readme-only.

Adding a model¶

IBBI is an inference package: training code lives elsewhere. A new model needs:

weights in a Hugging Face repository with a model card (training data, selection on validation data, benchmark results, licence);
a wrapper in src/ibbi/models/ implementing predict, predict_proba, extract_features and get_classes, and a factory function registered with register_model (see models/detectors.py);
a row in src/ibbi/data/ibbi_model_summary.csv and an entry in docs/models.md;
a benchmark run with benchmarks/run_benchmark.py (nothing tuned on the test splits);
tests (an offline test with a fake or tiny model, and a slow test that loads the real weights).

Pull request process¶

Create a branch for your change (e.g. git checkout -b fix/zero-shot-tiling).
Make your changes with clear commit messages.
Make sure pytest -q tests passes and the pre-commit hooks run without errors.
Push the branch to your fork and open a pull request against main.
Describe what changed and why, and reference the issue it addresses (e.g. "Fixes #123").

Thank you again for your interest in contributing!