Identify the GPU(s) in this machine via nvidia-smi: name, driver, memory, power limit, compute capability, max SM clock. Also returns the matching roofline table entry if known.

Roofline for a GPU (default: the first GPU in this machine). Pass the kernel's flops and bytes moved (bench()/verify() return them as roofline_inputs) to get the bound, the attainable TFLOPS and attainable_ms from the spec sheet. Pass measured_mem_gbs (the bandwidth a streaming copy reaches on this card under the repo's timer, see docs/platform-matrix.md; 1501 on the reference RTX 5090) to also get attainable_ms_measured, the floor a kernel can realistically get within 10% of. dtype: bf16 | fp16 | fp8 | fp32.

Run a Python script n times in the user's interpreter and aggregate its timing. Contract: the script prints one JSON line to stdout containing at least {"ms": } and optionally {"ok": } for a correctness check. Returns mean/std/min over the n timed runs plus every raw sample, so a LEADERBOARD row can cite n and seed.

Run a Python script under torch.profiler in the user's interpreter. Returns kernels (real GPU kernels by device time, pct over total kernel time) and ops (aten ops with input shapes, inclusive time). Works without Nsight installed; use this first.

Run a command under Nsight Systems (tool='nsys') or Nsight Compute (tool='ncu') and return the path of the report plus a parsed kernel summary. nsys gives the per-kernel time breakdown; ncu gives per-kernel metrics (achieved occupancy, DRAM throughput, SM throughput) and is much slower, so use ncu_kernel_regex to target one kernel.

Read a saved profile CSV (from profile()) and return the n heaviest kernels. tool='nsys': cuda_gpu_kern_sum CSV -> share of GPU time, calls, avg/med/min/max/std ns. tool='ncu': details CSV -> per-launch duration, achieved occupancy, DRAM / SM throughput %, registers per thread, and a memory/compute/latency hint.

Disassemble a kernel. target is a .cubin/.ptx/.so/.exe path, or 'triton-cache' to search ~/.triton/cache (and TRITON_CACHE_DIR) for the most recent kernel whose name contains kernel. level: 'sass' (via cuobjdump -sass) or 'ptx' (cuobjdump -ptx / the .ptx file). A real kernel is 500-3000 SASS lines; max_lines<=0 returns all of them.

Decide whether a candidate script beats the baseline script. Both follow the bench contract (print one JSON line with "ms" and "ok"). Runs them interleaved (baseline, candidate, baseline, candidate, ...) warmup+n times each, back to back on the same card, discards the warmup pairs, and returns mean/std/min for both plus a verdict: 'faster' or 'slower' when |mean_b - mean_c| > 2*sqrt(std_b^2/n + std_c^2/n), 'inconclusive' otherwise, 'incorrect' if the candidate printed ok=false in any run (then no speedup is reported), 'invalid' if the two scripts disagree on shape/dtype/iters/seed or the baseline fails its own check. Also records gpu, driver, power limit, timestamp and the exact commands. Pass the result to record().

Write a verify() result to results//.json, then regenerate LEADERBOARD.md from every log under results/ (so the table is always reproducible from the raw files). The Speedup cell is filled only when the verdict is 'faster'; otherwise it says 'no gain', 'incorrect' or 'invalid'. Call it after every verify(), win or lose; never edit LEADERBOARD.md by hand. note is the one-line "what changed"; who says honestly who produced the candidate, e.g. 'agent: running kernel-speedrun unattended' or 'hand-written by during tool bring-up'.

Scaffold a target from the user's own PyTorch function so the loop can run on it: writes <out_dir>/_baseline.py (the function as the baseline plus the Target definition: inputs, seed, fp32 reference, dtype-default tolerances, rotation, timer), <out_dir>/_candidate.py (the file to edit; starts as the baseline) and the vendored hotkernel_contract.py (protocol 3) they import, so they run in HOTKERNEL_PYTHON without hotkernel installed there. from: 'torch.nn.functional:gelu' or './mykernels.py:fused'; shape: the primary input x, e.g. '4096x8192'; extra: more inputs in call order like ['w:8192', 'b:8192'] (random tensors of the same dtype); rotate: inputs that stream through memory (default ['x']); flops: nominal flops per call for roofline(); reference: a different 'module:function' to run in fp32 as the reference when the baseline cannot run in fp32 (a backend-forced SDPA call, a bf16-only library kernel). For inputs randn cannot draw (a quantized weight): derive: a 'module:function' from the dict of raw random tensors to the dict of tensors the call takes, in call order; inputs: the names it returns, e.g. ['x', 'w_q', 'scales'] or 'x,w_q,scales', which become the candidate's signature; reference is then required and gets the derived inputs as they are (it must do its own fp32 math); min_bytes: the bytes one call must read (one weight layout), which sizes the rotation K. Same as the CLI hotkernel new. Then bench() the baseline and verify() the blank candidate (expect 'inconclusive') before changing anything.