kaggle

Generate Kaggle competition notebook script, Jupytext # %% format.

Two goals, equal weight — neither traded for other:

• Win — leaderboard-competitive: leakage-safe CV, metric-aligned loss/model choice, tuning/ensembling when it moves the score, not style theater
• Teach — read top to bottom like a university/seminar lecture on solving this competition: reader new to it follows the full reasoning chain, every decision motivated, nothing left as unexplained code

Follows user's ML research style distilled from past notebooks:

• PTL always for DNN training (PyTorch Lightning + torchmetrics) — even simple baselines
• Tool agnostic — best-fit library for problem; PTL when training loop needed
• Stages with lenses — each major stage: quick sanity check cell (show one batch, print shapes, verify submission format)
• Small, single-purpose cells — one action per cell (load, one transform, one plot, one check); never bundle setup + run + verify to save cell count
• Every cell earns its place — one-line why (comment or markdown sentence) before/in each cell: the specific reason this step happens now — never a restatement of what the code does
• Section markdown is extensive and structured — full explanation of what/why/how-it-advances-the-goal per section, formatted as tables/lists/blockquotes over dense prose paragraphs; markdown before a plot sets up the question, markdown after states the finding and its implication — plot and prose flow as one beat, never an orphaned chart
• # ! bash over subprocess — package installs, nvidia-smi, ls -lh, # ! head submission.csv
• EDA is visual — distribution plots, sample grids, dimension scatters before any model
• Inference included — model save pattern + separate load-and-infer cells
• CSVLogger + seaborn — metrics plotted from metrics.csv after every training run

NOT for writing Python packages, modules, production code — notebook scripts only. NOT research literature survey — use /research:topic for SOTA literature search.

• $ARGUMENTS: one of:
  • <competition-name> — short slug for output filename; generates blank template
  • <competition-name> <url> — fetches competition overview from URL before generating
  • <competition-name> "<description>" — inline description of problem and data
  • --type <type> — hint: classification, regression, segmentation, detection, tabular (auto-detected when omitted)
  • --eda-only — generate only EDA sections (no model/training/submission); always online (no offline setup)
  • --inference-only — generate inference notebook from checkpoint (no EDA, no training); always offline (frozen packages pattern); loads checkpoint from PATH_CHECKPOINT constant; output suffix -inference.py
  • --offline-setup — include offline package setup (frozen_packages pattern) in setup cell; auto-applied when --inference-only; ignored when --eda-only (EDA always online)
  • --resume <path> — read existing .py script, extend/improve it

Output: .experiments/kaggle/<competition-name>.py

OUTPUT_DIR:       .experiments/kaggle/
DATA_DIR:         .experiments/kaggle/data/<competition>/  # kaggle CLI downloads land here, gitignored
CELL_MARK:        "# %%"
MD_CELL_MARK:     "# %% [markdown]"
COMPETITORS_DIR:  resources/competitors/  # optional user-project path, not shipped in plugin — Step 1 reads if present
# NOTE: doc-only — not shell vars across Bash() calls (state doesn't persist); keep synced with literal use sites (Steps 1,3,4)

• Key boundary: end of Step 3 — notebook script generated by foundry:sw-engineer, written to OUTFILE.
• Preserve: OUTFILE path (derived from TMPDIR keys), COMPETITION_NAME (TMPDIR key), mode flags (EDA_ONLY, INFERENCE_ONLY, OFFLINE_SETUP).
• Clear at Step 1 start (stale prior run) and after Step 4 package-distillation gate resolves.