yassineAlouini/kaggle-tools
yassineAlouini/kaggle-tools has 32 GitHub stars and 13 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 00:38 UTC. Last push 2026-11-08.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Some tools that I often find myself using in Kaggle challenges.
Machine LearningREADME.md
Originalkaggle-tools
Agent skills and a small Python library for Kaggle competitions, built from what went wrong in real ones.
Each piece exists because something failed: a silent "Submission Scoring Error", a notebook that timed out on the hidden test, a P100 that current PyTorch can no longer run, a re-run without internet, an out-of-fold gain that never reached the leaderboard. The lessons come from AIMO3, BirdCLEF 2026, RSNA Knee 2026, ROGII Wellbore Geology, NVIDIA Nemotron, Biohub cell tracking and ARC-AGI-2.
The repository has two independent parts:
- Agent skills: a Claude Code plugin of 9 skills that guide an agent through CV design, code-competition submissions, LLM inference and fine-tuning on Kaggle GPUs, leaderboard analysis, and domain-specific pipelines. Recommendations are tied to the competition results that motivated them.
- Python package:
kaggle_tools, small utilities for notebooks that must survive Kaggle's offline, time-limited re-runs, plus thektCLI that lints a kernel before you push it and plots leaderboard and progress reports.
Agent skills
| skill | use it for |
|---|---|
kaggle-competition-playbook |
reading the metric code, CV design, CV→LB transfer, experiment selection, ensembling, submission quota |
kaggle-code-competitions |
offline re-runs, data paths, wheels, accelerators, time limits, push workflow, pre-submit checklist |
kaggle-leaderboard-analysis |
public/private rank shifts and yearly competition progress reports |
kaggle-audio-bioacoustics |
BirdCLEF-style soundscapes: Perch embeddings + probes + temporal model + rank blend |
kaggle-llm-reasoning |
AIMO-style math: model choice, vLLM, tool-integrated reasoning, voting, time budget |
kaggle-llm-serving |
vLLM throughput on 4x L4: TP vs one replica per GPU, fitting a 27B on 24 GB, KV/state capacity, MTP depth, quality gate |
kaggle-llm-finetuning |
LoRA/SFT on Kaggle: TRL/PEFT, packing, verified chain-of-thought data, adapter packaging |
kaggle-medical-imaging |
MRI/CT classification: weak report labels, anatomical inputs, teacher lineage, site-aware validation |
kaggle-tabular |
GBDT + TabICL stacks, spatial CV, feature ablations, local training → Kaggle inference |
Install
In Claude Code (inside a session, or the equivalent claude plugin ... shell commands):
/plugin marketplace add yassineAlouini/kaggle-tools
/plugin install kaggle-tools@kaggle-tools
/plugin marketplace update kaggle-tools # later, to pull new skills
Skills load on demand when a task matches their description. The plugin contains only
SKILL.md files and Markdown references: no hooks, MCP servers or commands, and nothing
runs on install (see SECURITY.md).
Supported clients. Claude Code through the plugin above (tested with
claude plugin install). Each skills/<name>/ folder is also a standalone
Agent Skill that any client reading SKILL.md folders can use:
Claude Code without the plugin: copy a skill folder into
~/.claude/skills/.Codex: copy or link a skill folder into
~/.codex/skills/, then invoke it as$<skill-name>. The optionalagents/openai.yamladds Codex UI metadata. From a checkout:mkdir -p ~/.codex/skills ln -s "$PWD/skills/kaggle-leaderboard-analysis" ~/.codex/skills/kaggle-leaderboard-analysis
Keep each folder's references/ directory when copying.
Case studies
The RSNA Knee 2026 case study and its first-place extension extract evidence from the 1st-, 5th- and 22nd-place writeups, with ablation limits and source links. The medical-imaging skill applies the transferable decisions; the playbook and code-competition skills carry the validation, blending and shared-inference lessons.
Python package
uv add git+https://github.com/yassineAlouini/kaggle-tools # or: pip install git+...
uv add "kaggle-tools[tracking,tune,gbdt] @ git+https://github.com/yassineAlouini/kaggle-tools"
Python 3.11+. Core dependencies are only numpy, pandas and scikit-learn; heavier
integrations are optional extras, imported only by the functions that need them:
| extra | adds | for |
|---|---|---|
tracking |
Trackio | local-first, wandb-compatible experiment tracking |
tune |
Optuna | hyper-parameter search |
gbdt |
LightGBM, XGBoost, CatBoost | tabular stacks |
plots |
Matplotlib, Plotly | local PNG/SVG/HTML and paginated PDF reports |
kaggle |
Kaggle API and SDK | read-only live leaderboard/account history fetching |
Modules
| module | highlights |
|---|---|
env |
competition_dir / dataset_dir resolve every /kaggle/input mount layout; is_competition_rerun; install_offline_wheels (fails loudly instead of silently degrading) |
submission |
ProgressiveSubmission keeps a valid file on disk after every stage (atomic writes; a stage's output only replaces the file if the stage finishes, failing stages are logged and skipped); vectorised build_submission; validate_submission |
ensemble |
rank_blend (per-column percentile ranks, for AUC-like metrics); hill_climb (Caruana greedy weights) |
cv |
spatial_group_folds (K-means on entity coordinates); rare_safe_folds (stratified-group, rare classes pinned to train, multi-label aware) |
metrics |
macro_auc (skips empty columns, like BirdCLEF), rmse, best_threshold |
budget |
TimeBudget for wall-clock-limited notebooks; @timed |
kernel |
pre-push lint for kernel-metadata.json + notebook source (incl. recursive /kaggle/input scans); push / status / wait / output wrappers; parse_pushed_version + submit (code competitions: -k/-v); download_resumable for multi-GB outputs (HTTP 206 size probe, bounded resume, sha256) |
runtime |
in-kernel guards: watchdog (native faulthandler timeout, cancelled on exit); guarded_initializer + raise_if_init_failed (Pool init errors reach the parent instead of hanging); shard_ids (one seeded manifest); rehearsal_root (train rows posing as test) |
llm |
extract_integer_answer, majority_vote, inverse-entropy weighted_vote, early-stopping ConsensusVoter |
audio |
BirdCLEF row_id parsing, window ids, frame_windows |
features |
date_features (tz-aware, cyclical), oof_target_encode |
tracking |
Ledger: JSONL submission ledger keyed by Kaggle kernel version, with LB deltas; trackio_run |
leaderboard |
complete public/private fetching, ID matching, account history, top percentages |
leaderboard_plots |
public/private scatter + zoom; per-year competition bars, readable multipage PDF and standalone HTML |
Example: an inference notebook that always submits
A valid submission is on disk from the first line, and each stage only replaces it if the stage finishes. If the second model crashes, or the time budget says it would not finish, the notebook still submits the first. (A notebook that hits Kaggle's hard time limit is not scored at all, which is why the budget check skips stages up front.)
import pandas as pd
from kaggle_tools.env import competition_dir, working_dir
from kaggle_tools.submission import ProgressiveSubmission
from kaggle_tools.ensemble import rank_blend
from kaggle_tools.budget import TimeBudget
budget = TimeBudget(total_seconds=90 * 60, margin_seconds=10 * 60)
data = competition_dir("birdclef-2026")
sub = ProgressiveSubmission(
pd.read_csv(data / "sample_submission.csv"), working_dir() / "submission.csv"
) # prior written now
with sub.stage("backbone"):
p_backbone = run_backbone(data)
sub.write(p_backbone)
if sub.ok("backbone") and budget.has(20 * 60):
with sub.stage("ensemble"):
sub.write(rank_blend([p_backbone, run_second_arm(data)], [0.5, 0.5]))
CLI
kt init-kernel notebooks/my-kernel --id me/my-kernel --competition birdclef-2026 # T4, internet off
kt check notebooks/*/ # lint before `kaggle kernels push`
kt validate submission.csv sample_submission.csv
kt ledger submissions.jsonl # every submission, with delta vs best-so-far
kt check reports three levels:
- error (exit 1): internet enabled on a competition kernel, a missing
code_file, malformedidor source slugs. - warning (exit 1 only with
--strict): a GPU kernel without a pinned T4 (the default P100 is unsupported by current PyTorch), a hard-coded/kaggle/input/<comp>/path instead ofenv.competition_dir, nosubmission.csv/.parquet/.zipwrite (inference-server notebooks are exempt), recursive scans of/kaggle/input, bareasserts and onlinepip installs. - info:
kernel_sourcesin use. Fine for wheels and weights, wrong for predictions that must be recomputed on the hidden test.
Leaderboard reports
Install the optional dependencies with uv sync --extra plots --extra kaggle, then:
uv run kt leaderboard-plot --competition COMPETITION_SLUG --output reports/leaderboard
uv run kt competition-progress --include-unranked --output reports/history
# Saved CSVs need only the plots extra:
uv run kt leaderboard-plot --public-csv public.csv --private-csv private.csv --output reports/leaderboard
uv run kt competition-progress --input history.csv --output reports/history
History uses top percentage = 100 * rank / teams (lower is better). Each
competition keeps its own bar in a yearly subplot, with the mean top percentage
of ended results in the heading. The PDF packs readable subplots across pages;
HTML embeds Plotly for offline hover/zoom. CSV/JSON preserve data and provenance.
The history PNG/SVG shows the yearly overview with competition counts and mean
top percentages; PDF/HTML also include each competition’s bar.
Use --include-unranked to display entries with no rank as empty, labeled rows.
Live history always uses the authenticated account, not a supplied display name.
The leaderboard command preserves board positions and matches by team ID; it
refuses an unverifiable public-board fallback. --highlight-team takes a team ID.
See the skill input reference
for CSV schemas, snapshot dates, and API limitations. Generated reports stay local.
Development
uv sync --extra plots --extra kaggle # .venv with dev tools + report test deps
uv run pytest
uv run ruff format . && uv run ruff check .
uv run ty check src
claude plugin validate . # after editing .claude-plugin/ or skills/
uvx pre-commit install
New utilities and skills follow the same rule as the rest of the repo: tie each one to the competition failure it prevents, and back every "works" or "doesn't work" claim with evidence (competition, version, leaderboard delta). See CLAUDE.md for the conventions.
License
MIT © 2018–2026 Yassine Alouini