Stage
The single unified scope for the training DSL.
Provides all operations: nested stages, agent runs, prompt executions, action logging, and dataset iteration.
Stages can be nested to arbitrary depth via runStage. Leaf operations (runAgent, executePrompt) create leaf records.
When to use stages: stages are primarily for exception handling, metric aggregation, and structured logging. If a piece of code doesn't need any of these, it doesn't need to be wrapped in a stage. A good "smell" that you're using something wrong is if your stage only has a single substage inside: while technically okay, you will have unnecessary metrics aggregation in the records tree, polluting it.
Inheritors
Properties
The full training dataset, used as the default for iterateDataset.
The agent being trained, available as the default target of runAgent.
Functions
Executes an LLM prompt with consumption tracking. Creates a PromptExecutionRecord as a leaf record, recording elapsed time and consumption. On success, returns the raw LLM response messages.
.getOrThrow() shortcut over executePrompt; throws on a recorded execution failure.
Executes a structured LLM prompt with consumption tracking. Creates a PromptExecutionRecord and returns the deserialized structure.
.getOrThrow() shortcut over executePromptStructured; throws on a recorded execution failure.
Helper function that creates a consumption-capturing executor, runs execute with it, records the result as a PromptExecutionRecord, and recomputes metrics. Notice that this function only produces one record, so you should only make a single LLM call inside the execute block.
Iterates over the dataset, processing each item as a substage. Uses dataset-specific metrics (solved rate, item counts, agent run stats).
Builds an action log via the ActionLogBuilder DSL and stores it on the current stage record.
Convenience wrapper that maps a collection, enclosing it in a dedicated stage. Pros: automatically sets substagesTotal to enable ETC calculation.
Attaches a custom metric to the records tree of this stage. This method has two uses:
Runs the agent on the given item.
.getOrThrow() shortcut over StageScope.runAgent; throws on a recorded run failure.
Re-samples the agent: runs it up to maxAttempts times, returning the first attempt whose outcome satisfies until (default RunUntil.SOLVED). The intended use is intentional re-sampling — e.g. bootstrap demonstration generation — not transient-failure recovery.
Runs the agent up to maxAttempts times, creating a fresh agent per attempt via agentProvider.
Convenience wrapper that iterates a collection, enclosing it in a dedicated stage. Pros: automatically sets substagesTotal to enable ETC calculation.
Runs a named substage. Creates a StageRecord as a substage of the current stage.
.getOrThrow() shortcut over StageScope.runStage. See its KDoc for the metrics preset conventions; the default and parameter semantics are identical.
Serializes data with defaultExperimentsJson and stores it as this stage's additional data via StageScope.setAdditionalDataJson. Overwrites any previously set value.
Sets some additional data in this stage's record. Overwrites if additional data was already added.