StepExecutor is the processing system used by API Endpoint Response Handling, Workflows, and Custom Commands

• Streamlines many complicated functions via simple "Step" configurations:
  • Processes each defined "Step" sequentially.
  • The result of the previous step will be input for the next step
  • Can execute a "for-each" loop of steps from a list of data
  • Can even run a step "groups" in parallel
• Uses a sophisticated context management system
  • Step results / extracted values can be stored via save_as
  • Context values, Bot Variables, even Websocket variables can be used anywhere in the system which will automatically resolve to their actual values

Any Step can include Meta parameters, set as top level items in each step dictionary (not nested in each "step config")

Meta Parameters are applied in the following order: on_error -> save_as -> returns -> log

Saves the result into a Context dictionary using the given key name

Saved values can then be injected anywhere using {this_syntax}.

The script can also convert a string value like this into actual python value: "{some_key: {saved_value}}" - this will be turned into an actual dictionary object with the resolved value from context {'some_key': \<the value previously saved to context as 'saved_value'\>}

Can override what is typically returned by a Step.

• "data" (default) the Step result
• "input" the original input to the Step
• "context" the entire stored context dictionary
• "a key name" If the step result is a dict, you can return a top-level key value from it. For deeper values just use extract_key

Provides additional logging for a step. Useful for debugging

Allows gracefully handling exceptions without aborting StepExecutor

• "raise" (default) raises Exception (aborts StepExecutor)
• "skip" returns the input value to the next step.
• "default" A specific value to return for the next step.

Evaluates a condition, typically by comparing two values, and executes the steps if evalues to True.

Refer to the List of valid operators (accordion menu below), and the correct usage of these parameters should make sense.

Returns: If True, returns the final step result from the "steps". If False, returns the current "result" (last step result).

Like the if step, but also supports elif and else logic.

This step is formatted as a list of dictionaries; configs for if / elif (optional) / else. It's formatted as a list so that multiple elif can be chained.

• if and elif are formatted same as the if step above.

• else is expected to simply be a list of steps, optionally nested in a "steps" key.

Refer to the List of valid operators (accordion menu in "if" step, above).

- if_group:
  - if:
      value1: status
      operator: ==
      value2: active
      steps:
        - send_content: "**Status**: Active"
  - elif:
      value1: status
      operator: ==
      value2: pending
      steps:
        - send_content: "**Status**: Pending"
  - elif:
      value1: status
      operator: ==
      value2: cancelled
      steps:
        - send_content: "**Status**: Cancelled"
  - else:
      - send_content: "**Status**: Unknown"

Returns: Returns the final step result from whichever condition block is executed.

Executes multiple step sequences in parallel, each defined as a list of steps.

Each item in the config is a list of steps (a sub-workflow), which is executed in parallel with others.

Any changes to "context" in each branch will not be reflected instantly, but will be captured/merged into the original context to be available in subsequent steps.

Config: sub-lists of Steps sequences (any Steps)

Returns: A list of results from each parallel sub-sequence

Runs a sub-StepExecutor for each item in a list or each key-value pair in a dict.

Any changes to "context" in this iteration will be captured and available in subsequent steps.

    response_handling:
      # Capture 'images' list as context variable "image_list"
      - extract_key: images
        save_as: image_list
      # Execute a 'for loop' of steps on each value in 'image_list'
      - for_each:
          in: image_list
          as: image
          steps:
            - decode_base64: true          
            - save:
                file_format: png
                file_path: "images"
                file_name: "img_{image_index}"

Returns: a list of all the last step results from each loop

Runs a predefined workflow (a sub-StepExecutor), returning the last step result of that workflow.

Returns last step result from the workflow

Releases the executing "Task" from the internal task manager's queue - freeing up a slot for another Task.

This is useful when there are only low-compute, time-consuming steps remaining (uploading files, etc).

Example usage:

- offload: true

Prompts the user for input via Discord message interaction.

Returns

• if type is "text": string

• if type is "select": the selected value.

• if type is "file": dictionary with keys:

  • file_dict (ready to attach to a file payload)

  • bytes (ready for additional processing ex. "save" step)

  • file_format the file type string (ex: "png")

  • filename the filename without extension (string)

  • Tip: use extract_values to capture the bytes and file_format, to use in a save step)

  • Tip: Passing the bytes into a save step can be useful for further processing (getting a file path to send to an API, etc).

{
    "file_dict": {                     # "file_dict" is a value ready to for a "files" payload, to upload to an API
        "image": {                     # 'image' is example value - will be dynamic (string)
            "file": file_obj,          # io.BytesIO object
            "filename": filename,      # filename without extension (string)
            "content_type": mime_type} # mime type ex: 'image/png' (string)
        },
    "bytes": <bytes>,        # raw bytes
    "file_format": "png"     # file format
    "filename": "my_image"   # filename without extension (string)
}

Sends text or files to Discord interaction channel.

Valid value types: string or list of strings

File paths are automatically identified and handled appropriately, and can be absolute (full path) or relative (must be relative to '/output/' or '/user/')

Example usage:

- send_content: '{result}' (the value would be resolved from the last step)

- send_content: Hello world!

- send_content: ['/images/image1.png', '/images/image2.png']

Loads a .json or .yaml or .yml file as a dictionary.

Can be an absolute path or relative to root bot dir (expected to be relative to /user/ subdir).

The file must be in an "allowed path" as configured in config.yaml.

Example usage:

- load_data_file: payloads/comfy_wan-txt2vid.json

Returns dictionary

Saves input data to a file

Returns dictionary

{"file_path": <(string) full file path including extension>,
"file_format": <(string) file format without leading period>,
"file_name": <(string) filename without extension>,
"file_data": <the original or decoded data as applicable}

Does nothing. Can be useful when you simply want to use a meta parameter

Retrieves a nested value from a data structure (dicts and lists) based on a specified path. The path is expressed as a dot/bracket notation string (e.g., "a.b[0].c"), and can optionally return a default value if the path is invalid or inaccessible.

Returns: Any - The extracted value, or the default value

data = {
    "user": {
        "name": ["Alice", "Bob"],
        "profile": {
            "age": 30
        }
    }
}

path: "user.address"
default: "Unknown"

Applies extract_key to build a new dictionary using user-defined key names for the extracted values.

The dictionary can be stored to Context. Each item can then be resolved in future steps using dot/bracket notation.

Example Usage:

- extract_values:
    image: data.image
    description: data.description
  save_as: image_data
  log: true

printed in cmd log: 'image_data': {'image': <the image data>, 'description': <the image description>}

The value for 'image' (Saved to context in the 'image_data' dict) can then be resolved into another field like this:

image: "{image_data.image}"

Sets arbitrary key values into the Context dict. This is intended to set values you don't "extract" from another object, etc.

You can set any number of key values in the same step.

Example usage:

- set_context:
    lora_weight: 1.0
    another_key: "Another value!"

context will now include:

self.context = {
  'lora_weight': 1.0,
  'another_key': "Another value!"
}

Returns: The last step result

Sets a value within a data structure (dicts/lists) based on a specified path. The path is expressed using the same dot/bracket notation string as extract_key (e.g., "a.b[0].c").

Returns: The updated data structure (dict or list)

Helpful for passing a specific variable from saved Context as input to the next step.

Creates a string or python object depending on usage. Accepts {placeholder syntax} to resolve values into the string (it will "stringify" many python values). It will subsequently try to resolve the string into an object if it is loosely formatted like a python object (dict / list / etc). Does not work with non-JSON serializable objects (bytes, etc) - objects which cannot be converted to strings

Example 1:

self.context = {..., 'my_saved_name': "Robby", ...}

- format: "{name: {my_saved_name}, location: 'Baltimore'}"

Result is python dictionary {'name': "Robby", 'location': "Baltimore"}

Example 2:

format: "[{my_saved_name}, {another_saved_value}]"

Result is a python list

Example 3:

format: "{my_saved_name} is a great friend"

Result is the string "Robby is a great friend"

Returns: The result of this step.

Make a dict, typically from stored variables.

Unlike the format step, you can work with non-JSON serializable objects (bytes, etc).

Example usage:

- dict:
    bytes: "{my_saved_image_bytes}"
    filename: "{my_saved_filename}"

Returns: The dictionary, with resolved placeholders.

Make a list. Unlike the format step, you can collect non-JSON serializable objects (bytes, etc).

Example usage:

- list:
  - "{my_saved_base64_string}"
  - "{another_base64_string}"

Returns: The list, with resolved placeholders.

Converts the input data to a specified target type. For "bool": "true", 1, and "yes" will return True otherwise False

Valid types: "int", "float", "str", "bool"

Example usage:

- type: "int" - Would convert the input value to an integer

Like type except it can convert multiple dictionary value types at once.

- cast:
    age: "int"
    height: "float"
    name: "str"
    active: "bool"

{
   "age": 30,           # converted to int
   "height": 5.8,       # converted to float
   "name": "123",       # converted to str
   "active": True       # converted to bool ("yes" → True)
 }

Transforms each element of a list into a dict. The key name can be arbitrary, or set by a dynamic context value:

- map:
    as: "dict"
    key: "fruit"

Extracts text from an input string using a regular expression pattern. It returns the first captured group if one exists, or the entire match if not.

Behavior: Uses re.search, which returns the first match anywhere in the string. Safely handles missing matches and avoids exceptions.

Returns: The first capturing group (group(1)) if the pattern contains any capturing groups. Otherwise, the full matched string (group(0)). If no match is found, logs a warning and returns the original data.

(Except for get_payload): For these Steps, any Endpoint Parameters can be included in addition to the inputs defined here, which will override the configured Endpoint behaviors for the Step interaction.

IMPORTANT For non-websocket API calls: Unless config input_data: null, the bot will send the current "result" / defined input.

Gets the base_payload from an API Endpoint.

Returns: The Endpoint's base_payload.

Performs an API call, and returns the result.

Returns: Result is dependent on the Endpoint configuration / extra API Endpoint parameters included.

Like call_api except that it repeatedly calls the API, collecting each result to a list which is returned after polling is stopped.

Uses same parameters as call_api with a few additions

Returns: A list of the results from the API calls, dependent on the Endpoint configuration / extra API Endpoint parameters included.

Polls an endpoint while sending a progress Embed to discord.

Like poll_api except specialized for purpose of tracking progress from a previous or concurrent call_api step.

If max_key is specified, progress is interpreted as a step count and normalized as (progress / max). Otherwise, progress is assumed to be a float between 0.0 and 1.0.

Uses same parameters as call_api and poll_api with a few additions

- call_api:
    api_name: ComfyUI
    endpoint_name: Prompt
    payload_type: json
    input_data:
      prompt: "{prompt}"
  save_as: prompt_id
- track_progress:
    client_name: ComfyUI
    progress_key: data.value # Required. dot notation gets the value nested in "data"
    max_key: data.max        # Optional. If applicable, should return the maximum value of "progress".
    eta_key: null            # Optional. If applicable, discord embed will include the ETA value.
    message: Generating a video # message for the discord embed
    completion_condition:       # Optional: All key/values must be matched to stop fetching progress
      type: executed
      data: {prompt_id: "{prompt_id}"}
    # websocket exclusive values
    use_ws: True
    type_filter: [progress, executed]   # ignores other message types
    data_filter: {prompt_id: "{prompt_id}"} # must '.get()' these key/values

Handles multipart form payloads for uploading to a specified endpoint.

The input_data param can be any of the following:

• full filepath string, or a list of full filepath strings
• bytes (must include a file_name value)
• dict containing file_path, or bytes (as bytes or file_data) and file_name
• list of dicts (see above)

Accepts same parameters as call_api with a few additions

Returns: The response body (one file upload) or a list of response bodies (multiple files uploaded)

Applicable for TGWUI-Integrated installations of this bot

Loads an LLM Model by name. Will raise ValueError if the name is invalid!

Does not accept other model loading arguments. Recommended to pre-configure your model settings as described here

Name 'None' will temporarily unload the current model ('None' string - not actual Nonetype null).

For persistent model unloading, use /llmmodel command.

Example to load a model:

- load_llmmodel: "gemma-3-4b-it-Q4_K_S.gguf"

Example to temporarily unload current model:

- load_llmmodel: "None"

Reduces tediousness and complexity for expected interactions.

Executes the standardized internal workflow for the average "txt2img / img2img" API request. This step may work for other similar endpoints / user cases - if not, use call_api, track_progress, etc.

API client > tracks progress > (optional) save output > returns dictionaries of file data.

To send results to Discord:

• This step can be the last step in a "run_workflow" Tag (the results will be sent at the end of the Task).
• Or, follow it up with a send_content step.

Returns: list of file dictionaries which can be passed directly to save_file, or send_content, or returned to caller and bot will send to channel automatically.

Posts prompt to a ComfyUI API client > tracks progress > saves outputs > returns output filepath(s).

To send results to Discord:

• This step can be the last step in a "run_workflow" Tag (the results will be sent at the end of the Task).
• Or, follow it up with a send_content step.

Returns: list of file paths (by default). This is all the bot needs to send content to discord. Can optionally return list of complete file dictionaries (returns: None), or lists of other data based on the "returns" param.

Use this to unload models and/or "free memory".

Returns: last step result

Deletes specified nodes from a ComfyUI payload and reroutes/cleans up the references.

Returns: the updated payload

Decodes a Base64-encoded string into raw bytes. For convenience, checks for a data URI (e.g., "data:image/png;base64,...") and splits it, using only the part after the comma for decoding.

Returns: bytes