Knobs

Every knob has a semantic type that tells the platform what the knob controls. Four types are available:

loops — controls how many times the entire steps sequence repeats. At most one loops knob per stilt. When a stilt loops, each iteration can read outputs from previous iterations via loopRef: previous or loopRef: accumulate.

recursion — controls the maximum recursion depth for a step that has recursion enabled. At most one recursion knob per stilt. The step's recursion.maxDepth references the knob via "{{knobs.iterations}}".

nodes — controls fanout, meaning how many parallel LLM calls a step makes. Multiple nodes knobs are allowed — one for branch exploration breadth, another for evaluation panel size, etc. A step references its node knob via nodes: "{{knobs.coverage}}".

generic — any other runtime value that doesn't map to loops, recursion, or nodes. Things like tone (concise vs detailed), audience (beginner vs expert), or strictness (low/medium/high). These are consumed inside fields using knobInfo.

Each knob has two identifiers that serve different purposes.

YAML key — the key under knobs: is the machine identifier. It's used in code references: {{knobs.coverage}} in step configs, knobInfo.from: coverage in fields, and "knobs": { "coverage": 6 } in API requests.

name — the display label shown in the Studio UI. It appears on sliders, dropdowns, and input labels.

They can differ:

knobs:
  coverage:
    name: Exploration Breadth
    type: nodes
    input: slider
    steps:
      - title: Compact
        value: 3
        default: true
      - title: Balanced
        value: 6

Here coverage is the key (used in code references) and Exploration Breadth is the label shown in Studio.

In API requests, use the YAML key:

{
  "knobs": { "coverage": 6 }
}

In Studio, the user sees Exploration Breadth as the label on the slider, but the engine receives coverage: 6 internally.

Every knob has an input mode that controls how the UI presents it. The two modes are independent of the semantic type — any knob type can use either input mode.

slider — presents 3 to 5 named positions, each with a numeric value. Exactly one position must be default: true. The user picks a label, and the corresponding value is what the stilt sees.

coverage:
  name: Coverage
  type: nodes
  input: slider
  steps:
    - title: Compact
      value: 3
      default: true
    - title: Balanced
      value: 6
    - title: Wide
      value: 12

numerical — presents a number input with a defined range. Requires min, max, and default where min <= default <= max.

iterations:
  name: Iterations
  type: recursion
  input: numerical
  default: 1
  min: 1
  max: 4

Knob values are referenced using the {{knobs.knobName}} syntax. This works in two places:

In a step's nodes count — the knob value determines how many parallel LLM calls the step makes:

nodes: "{{knobs.coverage}}"

In a step's recursion.maxDepth — the knob value determines how deep the recursion goes:

recursion:
  maxDepth: "{{knobs.iterations}}"

Beyond these two locations, knobs are consumed inside fields using the knobInfo field type — covered in the Fields section.

Two special field types inject runtime values into a step's prompt — knobInfo and nodeInfo. They're defined alongside other fields on a step, but work differently because they don't read from user input or other steps' outputs.

knobInfo injects a knob's current value. Set from to the knob's key name. When the step runs, the knob's resolved numeric value is rendered into the prompt:

fields:
  - name: Branch Count
    type: knobInfo
    from: coverage

If the coverage knob is set to 6, this renders as Branch Count: 6 in the prompt.

nodeInfo injects the current node number (1-based). No from is needed — it automatically resolves to which parallel branch is currently executing:

fields:
  - name: Node Number
    type: nodeInfo

If the step has 5 nodes running in parallel, node 3 gets Node Number: 3 in its prompt.

Having more than one loops knob or more than one recursion knob — only one of each is allowed. A slider with fewer than 3 steps or more than 5 steps. A slider where zero steps have default: true or where multiple steps claim the default. A numerical knob where default falls outside the min/max range. Referencing a knob name in {{knobs.X}} or knobInfo.from that doesn't exist in the knobs section.