What is Best of N in a Wavemaker workflow?

A combinator that executes up to six parallel candidate branches, evaluates scoreBy on each result (often review.score), and keeps the winner. Scheduler instance keys use pick~N notation.

How is Best of N different from Retry Until?

Retry Until is serial — attempt 2 runs because attempt 1 failed a condition. Best of N is parallel exploration — you pay for N candidates upfront within the envelope, then select.

Why does candidate 2 need a different memo key than candidate 1?

Without instanceSalt ~2, identical params would memo-hit candidate 1's artifact — breaking selection when you intended distinct generations. Salt applies from candidate ≥2.

Does chat use Best of N too?

Chat uses imageVariantCount and permissive best-of-N policies on the production driver. Workflows make the same idea explicit on the canvas with compile-time envelope math.

← All posts

August 22, 2026 6 min read The Wavemaker Team

Best of N Generation Explained: Parallel Candidates, scoreBy, and Memo Salt

The bestOfN combinator runs up to six candidates, picks the highest scoreBy expression, and memo-salts candidate index ≥2 so quality selection cannot reuse the same rejected pixels.

workflows
quality
platform
product

Illustration for: Best of N Generation Explained: Parallel Candidates, scoreBy, and Memo Salt — Conceptual illustration — product screenshots appear in the guide below where they help you click through.

Best of N is the workflow answer to “generate several options and keep the best one” — not as a hidden loop in generate_image, but as a bestOfN combinator with a declared scoreBy and a hard cap of six candidates. It sits beside retryUntil in the control-flow palette on the AI workflow builder, often inside a Map over storyboard scenes (visual tour).

When Best of N beats Retry Until

Pattern	Shape	Best for
retryUntil	Serial attempts until condition	Fixable defects — adherence, anatomy
bestOfN	Parallel candidates + max score	High variance — composition, lighting luck

Retry assumes the model can correct on a second pass with similar inputs. Best of N assumes the model rolls dice — you want the best roll, not a lecture to the same roll.

Both are quality contracts (quality contracts post).

scoreBy and review_image

Typical wiring:

Each candidate branch runs generate_image → review_image.
scoreBy references review facts — e.g. review.score or a weighted expression the parser allows.
Scheduler completes all candidates in the wave budget, compares scores, promotes the winner’s artifact to the combinator output port.

Conditions use the same micro-grammar as retryUntil — parsed, not eval’d. Keep expressions short (MAX_EXPRESSION_LENGTH).

Cost envelope honesty

Compile multiplies block costs by N (and map fan-out separately). Quotes and holds reflect that multiplication — no surprise six-pack bill after run. Hard stop at ENVELOPE_HARD_STOP_FACTOR (1.25×) still applies.

For slug runs on /w/{slug}, foreign runners see itemized estimates including fan-out; premium line items separate (publish post).

Memo keys and pick~2

Instance keys encode candidate index: pick~2/gen means Best of N candidate 2, node gen. Memo instanceSalt "~2" from candidate ≥ 2 prevents distinct candidates from collapsing to one cached PNG.

Candidate 1 may still memo-hit prior plain runs with identical inputs — intentional dedupe when you re-run the whole workflow unchanged (memoized workflow runs).

Nested in Map: the Music Video pattern

Template graphs fan Map over board.scenes; inside each iteration:

enrich_prompt → bestOfN(generate_image, review_image) → animate winner.

That is how you scale best-of without copy-pasting nodes — one combinator, N scenes, envelope assumes documented map fan-out cap.

Visual builder canvas — typed blocks, wires, and quality contracts.

Permissive chat parity (scope note)

The permissive video pipeline enables permissiveBestOfN following imageVariantCount on the chat path — related economics, different authoring surface. Workflows expose bestOfN to integrators via wf_<slug> MCP and OpenAPI inputs — behavior is spec-defined, not session-flag-defined.

Design tips

Cap N at what review can afford — six vision reviews × M map scenes adds up.
Pair with style-locked specs so candidates differ in composition, not accidental medium drift (style-locked workflows).
Use approvalGate after Best of N when a human must choose among high scores (approval gates).
Log instance keys when debugging “why did pick~3 win?” in run node list.

Where to go next

Production kernel § IR combinators
Quality contracts for AI pipelines
Build: /workflows/new · /ai-workflow-builder

Eval grids vs workflow bestOfN

Training Studio blind evals cap variant grids (MAX_EVAL_VARIANTS = 8) — related selection metaphor, different product surface. Workflow bestOfN combinator caps at six candidates per combinator instance — do not confuse eval MCP tools with published slug graphs.

scoreBy expressions beyond review.score

When all candidates share the same reviewer, review.score suffices. Some graphs wire auxiliary json artifacts with custom facts — only use expression paths the compiler resolves; invalid paths fail compile. Keep scoreBy monotonic with quality — inventing numeric hacks defeats review trust.

Combining with retryUntil

Serial retry inside each Best-of-N candidate is valid but explodes envelopes — usually pick one pattern per stage. Common pattern: Best of N for seeds, retryUntil on review_video for clips — different artifact types, different variance profiles (quality contracts).

Parallelism inside the wave

Best-of-N candidates execute within wave concurrency bounds — not unbounded fan-out. Extremely heavy map × bestOfN graphs may queue inside the wave executor — watch envelope and plan-tier concurrency entitlements.

Permissive score gates (chat cross-reference)

Chat permissive pipeline may score unscored primaries before Best-of-N clip render — workflow graph expresses equivalent policy explicitly with review blocks wired before selection. Do not assume workflow slug runs inherit chat session flags — only spec combinators apply.

Publishing graphs with bestOfN

Premium publishers hiding graph should document candidate count N in marketing copy — runners pay envelope reflecting N. Open remixers inherit your N — large N on Open templates affects community run cost; consider lowering N for educational Open releases.

Field notes

When teaching Best of N to new authors, start from the Music Video template Map group: duplicate the combinator subgraph mentally — each scene pays up to N image generations plus N reviews. Export that mental model to sales: ‘we shoot N stills per scene and pick the best score.’ Integrators should encode N in their own SKU docs because envelope quotes rise linearly with N. If runners complain about cost, lower N or move to retryUntil for cheap serial correction instead of parallel exploration.

Platform links worth bookmarking

The AI workflow builder landing orients new authors; /workflows/new is the authenticated entry. Published runners live at /w/{slug} with JSON Schema exposed on GET /api/v1/w/{slug}. Hub discovery is /hub. Kernel contracts are unauthenticated at GET /api/v1/openapi.json and GET /api/v1/workflow-spec-schema. Docs cluster: workflows overview, building workflows, running workflows, publishing and earning. Comfy transpile honesty: /comfyui and import ComfyUI workflows. API integrators: workflows as API endpoints and agent-driven MCP builder. Next step for this topic: open /workflows/new and apply the pattern from best of n generation explained, then publish to /hub when the run is stable.

Glossary (quick)

WorkflowSpec — canonical IR JSON. Compile gate — validate before run/publish. Open royalty — 10% to creator on foreign settled platform credits. Premium — creator-priced runs with 80/20 success split. Memoization — content-addressed skip for unchanged blocks. approvalGate — human pause with webhook. bestOfN — parallel candidates, scoreBy winner. Lineage — fork/remix parent attribution. Slug run — execute published workflow by Hub slug without chat orchestrator.

Historical note (chat vs workflow)

Before workflow combinators, teams duplicated Best-of-N behavior with manual regenerate buttons and spreadsheet tracking. Workflow bestOfN makes candidate index, score comparison, and winner promotion auditable in kernel_run_nodes. When migrating a chat playbook, count how many variants you actually reviewed per scene — that number becomes N, not a guess. If N was never consistent in chat, start with N=2 on workflow slug before jumping to N=6 — envelope and review time scale linearly.

Takeaways

bestOfN is a first-class combinator (≤6 candidates), not a hidden image toggle.
scoreBy usually reads review.score from wired review_image outputs.
instanceSalt on candidate ≥2 prevents memo collapse between parallel candidates.
Envelope quotes scale with N and Map fan-out — quote before batch campaigns.
Slug runs and MCP wf_<slug> inherit the same combinator semantics as editor runs.
Start from the Music Video template Map group when learning visually.
Pair with style-locked workflows so candidates differ in composition, not medium drift.
For serial correction, prefer retryUntil instead of high N.
/ai-workflow-builder Control Flow palette adds Best of N without JSON editing.

Frequently asked questions

What is Best of N in a Wavemaker workflow?: A combinator that executes up to six parallel candidate branches, evaluates scoreBy on each result (often review.score), and keeps the winner. Scheduler instance keys use pick~N notation.
How is Best of N different from Retry Until?: Retry Until is serial — attempt 2 runs because attempt 1 failed a condition. Best of N is parallel exploration — you pay for N candidates upfront within the envelope, then select.
Why does candidate 2 need a different memo key than candidate 1?: Without instanceSalt ~2, identical params would memo-hit candidate 1's artifact — breaking selection when you intended distinct generations. Salt applies from candidate ≥2.
Does chat use Best of N too?: Chat uses imageVariantCount and permissive best-of-N policies on the production driver. Workflows make the same idea explicit on the canvas with compile-time envelope math.