humanize

KernelPilot is for serious CUDA kernel tuning runs where the important facts are easy to lose: which upstream PR inspired a candidate, which shape regressed, what Nsight Compute actually said, which evidence changed the next edit, and whether the candidate belongs in a framework repo or a clean experiment.

The project packages three cooperating skills:

Skill	Role
humanize-kernel-agent-loop	Turns kernel definition K, reference R, and workload distribution W into task-acceptance pairs, a standalone optimization repo, autonomous research/iteration/autotuning, correctness tests, benchmarks, ledgers, dispatcher, tuning decisions, and review-gated iteration.
kernel-knowledge	A local PR-diff-first CUDA kernel evidence corpus. It routes by architecture, repo, topic, technique, profile symptom, operator, and DSL, then opens PR diffs, source snapshots, wiki pages, docs, and blogs as needed.
ncu-report	Converts Nsight Compute reports into a reproducible profile digest: metrics, source counters, PM sampling, PTX/SASS hotspots, bottleneck diagnosis, and exactly one next kernel edit.

Together they make an optimization loop that can work from a simple request:

[$humanize-kernel-agent-loop] Optimize SGLang's GEMM path for M=64, N=2048, K=2048, fp16, bias=true, and beat the current SGLang baseline by at least 10%.

The loop decides how to plan, when to query knowledge, what to profile, how to record lineage, how to scan the workload distribution, and when to ask the Humanize review gate whether another round is needed. The human should specify the target when it is ambiguous; the loop owns the rest.

Why Use It

• PR-diff-grounded prior art. The knowledge base is organized around real merged kernel PRs, with review diffs and source snapshots materialized under knowledge/evidence/pull-bundles/.
• Standalone by default. Candidate kernels do not pollute SGLang, vLLM, PyTorch, or other large framework repos. The loop creates an isolated repo with bindings, tests, benchmarks, ledgers, lineage, and profile artifacts. The standalone repo is where implementation artifacts, provenance, and measurements live.
• Evidence-driven profiling. The loop decides when ncu-report is worth running, then uses it to move from vague labels like "memory-bound" toward measured bottlenecks and one concrete next edit.
• Knowledge-backed edits. The agent can read PRs, wiki pages, official docs, blog/code notes, and profiler examples when they help explain a benchmark result, profile symptom, regression, plateau, or next edit.
• Review-gated iteration. Humanize RLCR keeps the loop from declaring victory too early; default loop budget is 84 iterations unless configured otherwise.
• Shape-aware tuning. The loop treats benchmark cases as a workload distribution, builds a performance map, and emits dispatcher/tuning decisions when different regimes need different kernels or configurations.

Kernel Agent Loop

flowchart LR
    K[Kernel definition K] --> P[Plan P = task and AC pairs]
    R[Correctness reference R] --> P
    W[Workload distribution W] --> P
    P --> S[Clean standalone repo]

    subgraph R0[Stage 1: Research]
        KW[kernel-knowledge / KernelWiki]
        B[Baseline and repo inspection]
        RD[Research digest and recipes]
        KW --> RD
        B --> RD
    end

    subgraph I0[Stage 2: Iterate]
        T[Writer executes task t_i]
        E[Inspect, edit, compile, test, benchmark, profile]
        V{Reviewer checks evidence vs ac_i}
        T --> E --> V
        V -->|blocked feedback| T
    end

    subgraph A0[Stage 3: Autotune]
        PM[Performance map over W]
        D[Shape-aware dispatcher]
        TD[Tuning decisions]
        PM --> D --> TD
    end