simulation

Types

AssertFn

Optional assertion function. Use no_assert for no assertion.

pub type AssertFn {
  NoAssert
  Assert(fn(SimulationState) -> Result(Nil, AssertionError))
}

Constructors

```
NoAssert
```

Assert(fn(SimulationState) -> Result(Nil, AssertionError))

AssertionError

</>

Error from a failed assertion.

pub type AssertionError {
  AssertionError(step: Int, expected: String, got: String)
}

Constructors

AssertionError(step: Int, expected: String, got: String)

ScriptedToolExecution

</>

Describes a tool call and its expected result.

pub type ScriptedToolExecution {
  ScriptedToolExecution(
    call: provider.ScriptedToolCall,
    result: ToolExecutionResult,
  )
}

Constructors

ScriptedToolExecution(
  call: provider.ScriptedToolCall,
  result: ToolExecutionResult,
)

Simulation

opaque </>

A complete simulation scenario (opaque, built with builder pattern).

pub opaque type Simulation

SimulationResult

</>

Result of running a simulation.

pub type SimulationResult {
  SimulationPassed(name: String, final_state: SimulationState)
  SimulationFailed(
    name: String,
    step: Int,
    error: AssertionError,
  )
  SimulationExceededMaxSteps(
    name: String,
    max_steps: Int,
    state: SimulationState,
  )
}

Constructors

SimulationPassed(name: String, final_state: SimulationState)

SimulationFailed(name: String, step: Int, error: AssertionError)

SimulationExceededMaxSteps(
  name: String,
  max_steps: Int,
  state: SimulationState,
)

SimulationState

</>

State accumulated during simulation.

pub type SimulationState {
  SimulationState(
    messages: List(message.Message),
    step_count: Int,
    total_usage: stream.Usage,
    tool_calls_made: List(message.ToolResult),
    errors_encountered: List(error.GleanError),
  )
}

Constructors

SimulationState(
  messages: List(message.Message),
  step_count: Int,
  total_usage: stream.Usage,
  tool_calls_made: List(message.ToolResult),
  errors_encountered: List(error.GleanError),
)

SimulationStep

</>

A step in a simulated agent workflow.

pub type SimulationStep {
  ExpectText(text: String, then_assert: AssertFn)
  ExpectToolCalls(
    executions: List(ScriptedToolExecution),
    then_assert: AssertFn,
  )
  ExpectError(error: error.GleanError, then_assert: AssertFn)
}

Constructors

```
ExpectText(text: String, then_assert: AssertFn)
```
Provider returns text (agent loop should terminate)

ExpectToolCalls(
  executions: List(ScriptedToolExecution),
  then_assert: AssertFn,
)

Provider returns tool calls, tools execute, results fed back

ExpectError(error: error.GleanError, then_assert: AssertFn)

Provider returns an error

ToolExecutionResult

</>

What happens when a tool is executed.

pub type ToolExecutionResult {
  ToolSuccess(content: String)
  ToolFailure(error: String)
}

Constructors

```
ToolSuccess(content: String)
```
```
ToolFailure(error: String)
```

Values

assert_finally

</>

pub fn assert_finally(
  sim: Simulation,
  assertion: fn(SimulationState) -> Result(Nil, AssertionError),
) -> Simulation

Add a final assertion that runs after all steps complete.

assert_passed

</>

pub fn assert_passed(result: SimulationResult) -> SimulationState

Assert that a simulation passed. Panics with descriptive message if not.

new

</>

pub fn new(name: String, prompt: String) -> Simulation

Create a new simulation.

run

</>

pub fn run(sim: Simulation) -> SimulationResult

Run the simulation. Pure function — all responses come from the script.

then_call_tools

</>

pub fn then_call_tools(
  sim: Simulation,
  executions: List(ScriptedToolExecution),
) -> Simulation

Add a step where the provider calls tools.

then_call_tools_and_assert

</>

pub fn then_call_tools_and_assert(
  sim: Simulation,
  executions: List(ScriptedToolExecution),
  assertion: fn(SimulationState) -> Result(Nil, AssertionError),
) -> Simulation

Add a tool call step with assertion.

then_provider_error

</>

pub fn then_provider_error(
  sim: Simulation,
  error: error.GleanError,
) -> Simulation

Add a step where the provider returns an error.

then_respond_text

</>

pub fn then_respond_text(
  sim: Simulation,
  text: String,
) -> Simulation

Add a step where the provider returns text.

then_respond_text_and_assert

</>

pub fn then_respond_text_and_assert(
  sim: Simulation,
  text: String,
  assertion: fn(SimulationState) -> Result(Nil, AssertionError),
) -> Simulation

Add a text step with assertion.

with_max_steps

</>

pub fn with_max_steps(sim: Simulation, max: Int) -> Simulation

Set max steps before the simulation is considered stuck.

with_system_prompt

</>

pub fn with_system_prompt(
  sim: Simulation,
  prompt: String,
) -> Simulation

Set the system prompt.