Decision guide
Which method should sort your list, and what will it cost?
Four questions decide it: how many items, whether you need the whole order or the top-k, whether you need the gaps or only the order, and which judge you can run. Below is the decision as prose, then as a calculator. The rules are not opinions — each comes from a measured cell in the program, linked where it applies. Terms are defined in the field guide.
The decision
Never start with pointwise (“rate each 0–100”).
- It is the cheapest per item and the one that fails first: scores collapse into tie blocks, and a top-k cut through a block drops arbitrary members — up to 70% of the reference top-10 in the measured cells. → E12, E14.
n ≤ ~30 and you want the gaps (“how much better”), with a frontier judge?
- Pairwise ratio, default budget 4·n comparisons, both presentation orders, active planner. You get a cardinal scaling with σ per item, order flips reported, and a certified stop. At n = 8 that is 32 comparisons — measured at ≈ $0.11 on the default judge with the README's items; the calculator below gives $0.086 at 600-character items. →
llmsort sort list.txt --by "…"
n from ~30 to a few hundred, and the order is what you need?
- Setwise — windows of 6–8 items in lettered slots, one full order per call, anchored ring so the graph connects in one round. Matches pairwise's own test–retest band at ~⅓ the cost; a 24-item sort cost $0.0054 live. →
--setwise, E6. - Past n = 24 (three times the window size) the engine adds a second round by default. Per-item budget does not transfer across n; graph density does (at n = 150, agreement 0.81–0.91 → 0.55–0.71 with one round, back within 0.02–0.07 of the pairwise ceiling with two, at ~⅙ its cost). →
--rounds 2, E13.
You only need the best k?
- The funnel: setwise screen of the whole pool, then a certified pairwise refine of the top ~3k. Brackets the reproducibility ceiling in every measured cell at 0.3–0.6× the cost of pairwise alone. →
--setwise --top-k K, E14. - Read the stability number it prints. Subjective top-k reproduces itself across seeds at only 0.3–0.7 for every method; if yours is at the low end, the honest move is a bigger k or a sharper criterion, not a different tool.
Your judge is a small or local model (under ~30B parameters)?
- Ask for direction, not magnitude. Seven of nine small judges could not read the ratio ladder (four of them answer one half of the alphabet 99–100% of the time, one answers parity 99% of the time) yet agree with the reference at +0.40 to +0.80 on direction; gemma-4-12b-it on the ordinal instrument is as good as the 31b. In the crate the ordinal path is setwise — a full order per window, lowered to direction evidence — pointed at your model. The pairwise ordinal-letter instrument from the bakeoff (
ordinal_letter_v1) is in the crate as the default read for the local gemma judges on the logprob route, but is not yet a documented--templatevalue. →--setwise --model <slug>, bakeoff.
The list is in the thousands?
- Screen first. Retrieval or a cheap setwise pass bounds the pool to the few hundred that could plausibly matter, then the funnel. This is the frontier of the program, not a finished recipe; the n = 150 lesson (structure over budget) is the guide up the exponents. → agenda.
You are not sure the criterion means anything?
Calculator: comparisons and dollars before you run
An estimate from list size, item length, goal and judge, using the same per-model prices the engine carries and per-call token shapes from live runs. It is a planning number; llmsort sort … --estimate prints the worst-case bound for your file on the pairwise path, without a network call; setwise runs are ⌈n/6⌉ · rounds calls by construction, and the crate refuses --estimate (like budgets, caches, probes and traces) alongside --setwise.
Token shapes: pairwise ≈ 420 prompt tokens + both items, ~60 completion; setwise window of 8 ≈ 300 + eight items, ~40 completion; 1 token ≈ 4 characters. Prices are OpenRouter list prices per million tokens as carried in llmsort's pricing table; provider caching and reasoning tokens move real spend either way, which is why every run prints what it actually cost.
The recommendation as flags
| Situation | Command | Yields |
|---|---|---|
| Short list, frontier judge, want gaps | llmsort sort list.txt --by "…" | cardinal scaling ± σ, active planner, certified stop |
| Medium list, order is enough | llmsort sort list.txt --by "…" --setwise | order, flip-rate gauge, ~⅓ the cost |
| n past ~24 (auto), or to force it | … --setwise --rounds 2 | density the per-item budget cannot buy |
| Best k only | … --setwise --top-k K | funnel: screen, then certified refine; stability number |
| Small or local judge | … --setwise --model <slug> | direction evidence a sub-30B model can actually give |
| Before spending anything (pairwise path) | … --estimate | worst-case comparisons and dollars, no network |
| Is the criterion real? | … --two-sided --also-by "paraphrase" | polarity and paraphrase readouts |
| One pair, audited | llmsort judge @a.md @b.md --by "…" --orbit | the invariant component and every named bias, separately |
Flag names are the crate's at v0.14; llmsort sort --help is canonical if the two disagree.
Logprob evidence depends on the provider exposing answer probabilities, and the caps differ: the gpt-4.1 and gpt-4o families return 20 alternatives; gpt-5.4 / 5.5 / 5.6 return 5 — the 5.4 family with reasoning effort unset or none, 5.5 and 5.6 only with reasoning_effort: "none"; gpt-5, o3 and o4-mini return none. Over-cap requests through OpenRouter answer 200 with logprobs: null, so the engine clamps per route and degrades loudly to sampled mode. Table and probe dates: docs/LOGPROBS.md.
The criterion is half the method
Sorting inherits everything from whether the attribute deserves to be sorted by. Some attributes a model grasps as a stable direction; some dissolve under paraphrase, polarity or pressure. The measured cases are instructive: a single dangling “ASK” line inside items moved one attribute's whole ranking (a lineup framing read the price tag while an isolated-pair framing read the blurb); a rubric truncated mid-sentence quietly changed what was measured. Write the criterion as one complete sentence that names the direction (“more of this is better”), avoid embedding a second criterion, and let the probes tell you whether the judge read what you wrote. The judge's agreement with itself across paraphrases is the number that says the sentence was understood.
What no method fixes
Three ceilings are properties of the task, not of the tool, and an honest instrument reports them instead of exceeding them silently. Item-level distinctions inside the error bars — twins and near-duplicates land in arbitrary order, inside their joint 2σ; the gauge certifies pool-level order only. Top-k reproducibility on subjective attributes — 0.3–0.7 across seeds at default budget, for every method. Magnitude compression — judges return log-ratios at about ⅔ of their true spread (slopes 0.55–0.68 on anchors) even when the order is right, so readings are comparable to each other, not to physical units, unless anchored. Buy them down with more budget, a sharper criterion, or multiple judges; never delete them from the report.