🏁 Kaggle sandbox

A small Python 3.10+ template for Kaggle competitions. It keeps a real installable placeholder helper package in src/challenge_xyz/ so shared functions can be used from scripts, notebooks, and Kaggle package resources. Forks should rename challenge_xyz to the competition package name once the project stops being a template. The package is intentionally small: put shared functions there, then import them from multiple Kaggle notebooks.

⚡ Quickstart

Create an environment and install the template:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade uv
uv sync --group dev --extra kaggle

On Kaggle, attach this repository or a built wheel as a resource, then install the helper package from that attached path:

pip install /kaggle/input/<resource-name>

Then import shared helpers from notebook cells:

from challenge_xyz import assert_same_csv_shape, read_csv_shape

For local smoke checks, install the package editable and run tests:

uv sync --group dev
uv run --group dev pytest -q

🗂️ Project Layout

.
├── src/challenge_xyz/  # reusable helper package shared by scripts and notebooks
├── notebooks/          # percent-format notebook scripts with # %% cell markers
├── resources/          # lightweight notes, links, and metadata
├── tests/              # doctests and regression tests for shared helpers
├── data/               # optional local competition files, ignored by git
└── outputs/            # optional local generated files, ignored by git

⚙️ Development Checks

uv run --group dev ruff check .
uv run --group dev pytest -q
uv build
uv run --group dev twine check dist/*

For a full local pre-commit pass:

uv run --group dev pre-commit run --all-files

📋 Template Checklist

When starting a new competition, update or add:

• COMPETITION slug in docs, scripts, and CI examples if needed.
• Data input paths used by Kaggle notebooks.
• Validation split and metric notes.
• Shared helpers that are reused by more than one notebook.
• Output tracking notes: date, code version, notebook version, public/private score.
• Seeds at every entry point that uses randomness.
• Tests for shared helpers: empty inputs, missing files, malformed CSVs, and shape or dtype checks for tensor code.

🌟 Showcases

Some derived projects:

• Multiple image classification
  • Herbarium 2022
  • Plant Pathology 2021 - FGVC8
  • iMet Collection 2021 - FGVC8
  • Cassava Leaf Disease Classification
• Multiple image segmentation
  • UW-Madison GI Tract Image Segmentation
  • Sartorius Cell Instance Segmentation
• COVID detection
• Brain Tumor 3D

Selected Kaggle notebooks:

• AMIA X-Ray: Inference RF-DETR detections
• AMIA X-Ray: EDA baseline RF-DETR detect
• Pig Posture: EDA + baseline RF-DETR detect
• ROGII drill: geosteer + LightGBM/CatBoost/Ridge
• Surface: train+inference 3D segmentation and GPU augment
• Surface: nnUNet training + inference with 2xT4
• Surface: EDA interactive image/mask 3D view
• CSIRO Img2Bio: EDA + XGBoost + DINOv3 features
• Cancer Subtype: Lightning Torch inference tiles
• Credit Risk: EDA and XGBoost depth=0+ GPU
• IceCube: Neutrino fitting 3D points cloud
• BirdCLEF: Lightning Flash inference

Selected writing:

• Tackling the Kaggle COVID Detection Challenge with Lightning Flash and IceVision
• Easy Kaggle Offline Submission With Chaining Kernel Notebooks
• Simple 3D MRI classification ranked bronze on Kaggle
• Kaggle hacking: Validate a simple hypothesis against a hidden dataset
• How to organize a medical imaging challenge: Lessons from ANHIR
• The Open-Source Shepherd: Why Your Best Work Is Building a Project That Doesn't Need You
• What Is Your Python Package's Public API, Really?

🔗 References

• Kaggle CLI
• KaggleHub
• Python Packaging User Guide
• Jirka Borovec on Kaggle
• Jirka Borovec public Kaggle notebooks
• Jirka Borovec on Medium