Top-Level Config

A LADR file is data, not code. It gets published to a directory, indexed by search engines, embedded as JSON-LD on crawlable pages, version-pinned for reproducibility, and loaded by callers who may not trust the author. All of this depends on the schema being closed.

Strict parsing means:

• Unknown top-level keys are rejected. Adding a new field is a grammar change, not a silent extension.
• Required fields are enforced. A ladder with no exit does not parse.
• Type mismatches surface at parse time. A ladder with steps: "hello" does not parse.

This is the opposite of a YAML config file that silently ignores typos. The discipline is what lets ladders be analyzed, validated, priced, and trusted as data.

When the parser rejects a config, it returns a single error message identifying the offending key. When validation rejects a config (after parse succeeds), it returns every error at once in an array, so the author can fix the whole batch before retrying.

# Required
name: <ladder name>
allowedTargets:
  strategy: universal              # or { strategy: constrained, providers: [...], models: [...] }
exit: <step id>
knobs: { ... }                     # may be empty
steps: [ ... ]                     # at least one

# Optional
id: <platform-assigned uuid>
description: <human-readable summary>
slates: [ ... ]                    # persistent memory stores
executionBudget:
  maxSpend: 5.0
  maxHops: 200
  maxLlmCalls: 500
  maxRecursion: 5
trace:
  mode: reasoning                  # reasoning | inline | off
  allSteps: false

The nine accepted top-level keys. Anything else fails parse.

Five top-level fields must be present in every ladder.

name

The ladder's display name. Shown in Studio, Foundry, the public directory page, and API responses. Free-form string.

name: Gated Tree of Thought

allowedTargets

Declares which LLM providers and models the ladder is allowed to run against. Two strategies:

# Universal: any provider the platform supports
allowedTargets: { strategy: universal }

# Constrained: pinned to an allowlist
allowedTargets:
  strategy: constrained
  providers: [openai, anthropic]
  models: [gpt-4o, claude-sonnet-4-20250514]

Validation rules for constrained:

• providers must include at least one entry. * is accepted as a wildcard but cannot combine with explicit providers.
• models must include at least one entry. Same wildcard rule.
• Every entry must be non-empty.

universal is the right choice for published ladders that should run anywhere. constrained is the right choice for ladders that depend on a specific model's behavior (e.g. a ladder that requires a model with strong JSON-mode support).

See Provider Strategy for the full deep dive on routing, fallback, and common patterns.

exit

The id of the step whose output is returned to the caller. Must reference a step that exists in steps:. If the exit step has multiple nodes:, it must be type: sequential (a normal step with parallel nodes has no deterministic "last" node).

exit: answer

knobs

A map of caller-tunable parameters. May be empty (knobs: {}); the field itself is still required. See Language > Knobs for the full reference.

steps

An ordered list of step declarations. Must contain at least one step. Each step must have id and name; everything else is optional. See Language > Steps for the full reference.

Four top-level fields are optional.

id

A platform-assigned UUID. Authors do not set this; the platform generates it when the ladder is first published. Present in API responses and used internally for referencing the ladder across versions.

id: 4f6e8d2a-3b1c-4e5f-8a9b-7c3d2e1f0a9b

description

A human-readable summary shown on the ladder's directory page and in Studio. Free-form string. Not parsed or validated beyond being a string.

description: Tree of Thoughts with verifier gate and synthesis. Best for hard multi-step reasoning tasks.

slates

A list of persistent memory stores. Each slate is composed of folders of plain-text files plus typed metatags. Survives across invocations. See Language > Slates for the full reference.

executionBudget

Per-ladder resource ceilings. All four fields are optional and use platform defaults when omitted. Authors can lower any ceiling (always safe) or raise it up to the platform max. See Runtime > Execution Budget for the full reference.

executionBudget:
  maxSpend: 10.0          # dollars; default 5.0, platform max 50.0
  maxHops: 500            # default 200, platform max 10000
  maxLlmCalls: 1000       # default 500, platform max 5000
  maxRecursion: 10        # default 5, platform max 20

trace

Controls what execution detail is emitted in the OpenAI-compatible response. Two fields:

trace:
  mode: reasoning          # reasoning | inline | off (default: reasoning)
  allSteps: false          # true emits every step; false only leaf steps

See Runtime > Observability for how trace modes affect the response shape.

Every top-level field, its type, whether it's required, and its default.

allowedTargets shape

allowedTargets: { strategy: universal }

allowedTargets:
  strategy: constrained
  providers: [...]    # required when constrained; "*" allowed alone
  models: [...]       # required when constrained; "*" allowed alone

executionBudget shape

All four fields are optional within the object. Omitting the whole object uses platform defaults for all four.

executionBudget:
  maxSpend: <number, dollars>       # default 5.0; platform max 50.0
  maxHops: <integer>                # default 200; platform max 10000
  maxLlmCalls: <integer>            # default 500; platform max 5000
  maxRecursion: <integer>           # default 5; platform max 20

A ladder can lower any ceiling (always safe) or raise it up to the platform max. Declaring a value above the platform max fails validation.

trace shape

trace:
  mode: reasoning      # "reasoning" | "inline" | "off"
  allSteps: false      # boolean; default false

mode controls how the runtime exposes intermediate step outputs in the OpenAI-compatible response. allSteps controls whether every step emits a trace block, or only "leaf" steps (steps that produce user-visible output).

Some validation rules span multiple top-level fields.

exit references steps. The exit step id must exist in the steps array. If the exit step has multiple nodes, it must be type: sequential.

slates referenced by step fields must be declared. A step with a slateRead field pointing at slate "Project Memory" fails validation if no slate titled "Project Memory" is declared at the top level.

slates referenced by slateWrite must be declared. Same rule for writes. The folder and (if specified) file must also exist.

knobs referenced by nodes:, recursion.maxDepth, or knobInfo.from must be declared. Wrong-type references fail: nodes: iterations against a knob of type: recursion is invalid.

steps cannot reference forward steps with loopRef: current. A step can only ingest from a step that has already executed in the current loop. The forward-reference check enforces declaration order for current references.

steps cannot have two steps with recursion: blocks. Only one recursion step per ladder.

steps cannot have nested type: group steps. A group's children must be normal or sequential.

At most one step can have timeline: init. And that step cannot have nodes: and cannot be the exit step.

executionBudget values cannot exceed platform maximums. Setting maxSpend: 100 against a platform max of 50 fails validation.

A ladder using every top-level field:

name: Adaptive Critic
description: Tree of Thoughts with reflexion loop, persistent lessons, and dynamic refinement.
id: 7c3d2e1f-0a9b-4e5f-8a2c-3b1c4d5e6f7a   # normally platform-assigned
allowedTargets:
  strategy: constrained
  providers: [openai, anthropic]
  models: [gpt-4o, gpt-4o-mini, claude-sonnet-4-20250514]
exit: answer
knobs:
  branches:
    name: Branches
    type: nodes
    input: slider
    steps:
      - { title: Few, value: 3 }
      - { title: Many, value: 7, default: true }
  iterations:
    name: Iterations
    type: recursion
    input: numerical
    default: 2
    min: 1
    max: 4
slates:
  - title: Critic Memory
    folders:
      - name: lessons
        tokenLimit: 400
        access: readWrite
        evictionPolicy: FIFO
        files:
          - { name: failures.md, init: blank }
      - name: solution
        tokenLimit: 1000
        access: readWrite
        files:
          - { name: best.md, init: blank }
executionBudget:
  maxSpend: 8.0
  maxHops: 500
  maxLlmCalls: 800
trace:
  mode: reasoning
  allSteps: true
steps:
  - id: generate
    # ...
  - id: verify
    # ...
  - id: answer
    # ...

This ladder:

• Pins to GPT-4o family and Claude Sonnet (no other models allowed).
• Exposes two knobs (caller picks branch count and recursion depth).
• Persists lessons and best solution across calls via two slate folders.
• Raises the spend ceiling to $8 (default is $5).
• Emits trace data for every step (not just leaves).

The strict parser enforces three rules at parse time, before any validation runs.

Rejects unknown top-level keys. Typos like descripton: or hypothetical fields like version: fail immediately:

parseConfig: unknown top-level key "descripton" (PipelineConfig is strict)

Rejects missing required fields. All five required fields (name, exit, allowedTargets, knobs, steps) must be present:

parseConfig: missing required top-level field "exit"

Rejects malformed values. A non-object steps value, a non-string name, or a structurally broken allowedTargets all fail at parse time.

Parse errors return immediately with a single message. They do not aggregate (the parser cannot continue past a malformed value). Validation errors, by contrast, aggregate; see Runtime > Validation for the full validation pipeline.

Can I add custom metadata fields? No. The strict parser rejects unknown keys. If you need to attach metadata, use description (free-form string) or embed it in the slate system (write to a slate on first call, read on subsequent calls).

What happens if I omit knobs? Parse fails. The field is required even when empty. Use knobs: {} for ladders with no caller-tunable parameters.

Can I version a ladder via a top-level field? Versioning is handled at the addressing layer (@author/name@v3), not in the config itself. The same YAML can be published under multiple versions.

Can a ladder have zero steps? No. steps must contain at least one entry.

Are comments allowed in the YAML? Yes. Standard YAML # comment syntax works. Comments are stripped during JSON conversion before parsing.

Can I use JSON instead of YAML? Yes. The parser accepts either format. YAML is the canonical authoring format; JSON is what gets stored and transmitted. Authoring tools that emit JSON work identically.

What's the difference between id and name? id is a platform-assigned UUID used internally for cross-version references. name is a human-readable display string set by the author. Two versions of the same ladder share id but may differ in name.