Understanding framesPerRun, ideasPerFrame, and topK in the ADHD Engine

framesPerRun controls how many distinct cognitive viewpoints the ADHD engine instantiates, ideasPerFrame determines how many raw ideas each viewpoint generates during divergence, and topK selects how many of the best-scoring ideas proceed to the deepening phase.

The ADHD (Adaptive Divergence-Heavy Design) engine orchestrates a multi-stage reasoning pipeline that first explores solutions in parallel across multiple frames, then converges on the most promising candidates for detailed elaboration. The three parameters—framesPerRun, ideasPerFrame, and topK—defined in src/types.ts govern the width of exploration and depth of focus, directly impacting both the diversity of generated ideas and the volume of LLM calls required.

The Multi-Stage Reasoning Architecture

ADHD implements a diverge-then-converge pattern across five distinct phases. In the Diverge phase, the engine selects cognitive frames and generates raw ideas. During Score + Cluster, all candidates are evaluated and grouped. The Shortlist phase filters candidates based on ranking, and the Deepen phase elaborates the winners.

According to the source code in src/engine.ts, the engine instantiates framesPerRun distinct branches, each calling divergeBranch with the ideasPerFrame parameter. After clustering and scoring in scoreIdeas and clusterIdeas, the top-ranked ideas are sliced according to topK for the final deepening pass via deepenIdea.

framesPerRun: Cognitive Breadth Across Viewpoints

framesPerRun defines the number of cognitive frames—distinct system-prompt vantage points—instantiated for a single run. Each frame operates as an independent branch with its own perspective on the problem.

• Default value: 5
• Defined in: src/types.ts (lines 52-55)
• Used in: src/engine.ts (lines 49-50) within the run function

Increasing this parameter expands the diversity of approaches by adding more parallel viewpoints, though each additional frame incurs separate LLM inference costs during the divergence phase.

ideasPerFrame: Intra-Frame Generation Volume

ideasPerFrame controls how many raw ideas are generated inside each individual frame during the divergence phase. While framesPerRun spreads thinking across different angles, this parameter deepens the search within each specific angle.

• Default value: 6
• Defined in: src/types.ts (lines 52-55)
• Passed to: divergeBranch in src/engine.ts (lines 57-58)

A larger number yields a richer set of candidates within each frame but linearly increases LLM call costs during the initial generation stage.

topK: Convergence and Deepening Depth

topK determines how many of the highest-scoring ideas advance to the deepening pass (the "focus" stage), where the engine produces detailed sketches and child ideas. This parameter controls the depth of elaboration rather than the breadth of exploration.

• Default value: 3
• Defined in: src/types.ts (lines 54-55)
• Used in: src/engine.ts for slicing the ranked list (lines 97-100) and building the shortlist (lines 84-86)

The engine calculates the shortlist size using the formula Math.max(2, Math.min(4, topK + 1)), ensuring at least two candidates are considered but capping the selection to manage computational overhead.

Configuring Parameters via CLI

You can override defaults directly from the command line. The CLI parser in src/cli.ts maps flags to the RunOptions interface.

# Generate 7 frames, 10 ideas per frame, and deepen the top 4 ideas

adhd "design a low-latency cache" --frames 7 --ideas 10 --top 4

The flags --frames, --ideas, and --top correspond exactly to framesPerRun, ideasPerFrame, and topK respectively.

Programmatic Usage in TypeScript

For embedded workflows, import the run function from src/engine and pass a configuration object conforming to the RunOptions interface.

import { run } from "adhd/src/engine";

await run({
  problem: "Make a server-less image thumbnail service",
  framesPerRun: 6,   // Number of cognitive frames
  ideasPerFrame: 8,  // Ideas generated per frame
  topK: 2,           // Deep-enrich the best 2 ideas
});

You can inspect the results to verify the pipeline behavior:

const result = await run({...});
console.log("Branches (frames × ideas):", result.branches.length, "×", result.branches[0].ideas.length);
console.log("Deepened ideas:", result.deepened.length); // Will be ≤ topK

Source Code Reference

The implementation spans three critical files:

• src/types.ts: Contains the TypeScript interface definitions for RunOptions, declaring all three parameters with their default values and type signatures.
• src/engine.ts: Implements the core execution logic, including frame selection (selectFrames), branch divergence (divergeBranch), scoring, clustering, and the deepening logic that consumes topK.
• src/cli.ts: Handles argument parsing and validation, mapping command-line flags to the structured options passed to the engine.

Summary

• framesPerRun controls breadth across different cognitive viewpoints; default is 5, defined in src/types.ts and used in engine.run.
• ideasPerFrame controls breadth within each viewpoint during the divergence phase; default is 6, passed to divergeBranch.
• topK controls depth by determining how many scored ideas receive detailed elaboration; default is 3, used to slice the final candidate list.
• Raising any parameter increases LLM utilization: framesPerRun and ideasPerFrame affect initial generation costs, while topK affects the deepening phase computation.

Frequently Asked Questions

How do framesPerRun and ideasPerFrame interact for total idea volume?

The total number of raw ideas generated during the divergence phase equals framesPerRun multiplied by ideasPerFrame. With defaults of 5 and 6 respectively, the engine produces 30 initial ideas before clustering and scoring occur. Adjusting these parameters allows you to trade exploration breadth against token consumption and latency.

What determines the shortlist size if topK is set to 3?

According to the implementation in src/engine.ts, the shortlist size is calculated as Math.max(2, Math.min(4, topK + 1)). When topK is 3, this formula evaluates to 4, meaning the engine considers up to four ideas for intermediate processing before selecting the final three for deepening.

Can reducing topK improve performance?

Yes. Lowering topK reduces the number of ideas processed through the deepenIdea function, decreasing both LLM call volume and overall execution time. However, setting it too low may cause the engine to miss valuable candidates that score poorly initially but offer high potential upon elaboration.

Where are these parameters validated in the codebase?

Type definitions in src/types.ts enforce the structure of RunOptions, while src/cli.ts validates command-line inputs before instantiation. The run function in src/engine.ts receives these values directly and passes them to downstream functions like selectFrames and divergeBranch without additional runtime bounds checking, relying on TypeScript compilation for type safety.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}