# Understanding framesPerRun, ideasPerFrame, and topK in the ADHD Engine

> Understand framesPerRun, ideasPerFrame, and topK in the ADHD Engine. Learn how these parameters control idea generation and selection for advanced cognitive processes.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: deep-dive
- Published: 2026-08-19

---

**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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) (lines 52-55)
- **Used in**: [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) (lines 52-55)
- **Passed to**: `divergeBranch` in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) (lines 54-55)
- **Used in**: [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) maps flags to the `RunOptions` interface.

```bash

# 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.

```typescript
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:

```typescript
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`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)**: Contains the TypeScript interface definitions for `RunOptions`, declaring all three parameters with their default values and type signatures.
- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) enforce the structure of `RunOptions`, while [`src/cli.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/cli.ts) validates command-line inputs before instantiation. The `run` function in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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.