What this recipe does
Replaces "ask GPT to write a docstring" with a model that has read your codebase. The verifier checks that the output starts with a one-line summary, includes the parameters and return values present in the function signature, and matches your repo's prevailing style.
The shape: function source in, docstring text out. The output is just the docstring (no surrounding code), so you can pipe it straight into a code editor's "insert docstring" command.
The spec
{
"output_kind": "text",
"verifier": {
"required_first_line_pattern": "^[A-Z].*[.!?]$",
"must_mention_params": true,
"must_mention_return": true,
"style": "google",
"max_lines": 24
}
}
The style field is one of google, numpy, sphinx, jsdoc, or tsdoc. The verifier reads it once at compile time and inserts the appropriate keyword set (Args:, Parameters, :param:, @param, etc.) into the K-score check.
Gold pairs (3 of 100 shown)
def chunk(seq, size):
return [seq[i:i+size] for i in range(0, len(seq), size)]
"""Split a sequence into fixed-size chunks.
Args:
seq: The sequence to partition. Anything that supports slicing.
size: Chunk size. Must be positive; behavior at zero is undefined.
Returns:
A list of slices. The last chunk may be shorter than ``size`` if
the input length is not a multiple of ``size``.
"""
export function debounce<T extends (...args: any[]) => void>(
fn: T, ms: number
): T {
let h: NodeJS.Timeout | undefined;
return ((...a) => {
if (h) clearTimeout(h);
h = setTimeout(() => fn(...a), ms);
}) as T;
}
/**
* Wraps a function so it only fires once `ms` milliseconds have
* passed since the last invocation.
*
* @param fn - The function to debounce.
* @param ms - Quiet period in milliseconds.
* @returns A drop-in replacement that delays calls.
*/
func MustParse(s string) *url.URL {
u, err := url.Parse(s)
if err != nil { panic(err) }
return u
}
// MustParse parses s as a URL and returns the result.
// It panics if the input is not a valid URL.
// Intended for compile-time constants and tests; use url.Parse for
// runtime input where you need to handle the error.
Compile
# pairs.jsonl: 100 (function source, docstring) pairs from your repo kolm compile "write a docstring in google style" \ --base qwen2.5-coder-3b \ --pairs pairs.jsonl \ --verifier style=google \ --k-floor 0.80 \ --output docstring.kolm ok wrote docstring.kolm k_score=0.84 signature=hmac-sha256
K-score gate
The verifier penalizes outputs that omit required sections (Args:, Returns:) or use the wrong style markers. False-positive rate on style mismatch was 8%; recompiling with a tighter style verifier brought it under 5%.
Run-time profile
Deploy
# VS Code task that fills in the docstring on selection: { "label": "kolm: docstring", "command": "kolm run docstring.kolm --input ${selectedText}", "presentation": { "reveal": "never" }, "problemMatcher": [] }