STEP

Our planning system is called STEP, which stands for (Software Transformation Execution Plan), and it represents the layer in between the AI agent planning phase and the AI agent execution phase. This is important because it enables the humans (that's you!) to review and edit plans before they are executed.

YAML Plan Structure

STEPs are defined in YAML. STEP YAML has the following shape:

steps:
  - tools:
      - name: <some-tool-name>
        arguments:
          arg1: <some-arg-value>
          arg2: <some-arg-value>

System Tools

System tools are designed to manage the execution flow within plans, such as conditional execution and iteration, without returning values. These tools are organized within the system_tools directory and their detailed documentation can be found in the system_tools README.

Variables

Variables in STEP are used to store and manipulate data returned by tools. Here's how they work:

• Data Types: Variables can hold different types of data including arrays, strings, numbers, and booleans.

• Declaration: Variables are denoted by double curly braces {{ variable_name }}.

• String Interpolation: When a variable is embedded within a string, it converts the variable's value to a string. For example, if list_var is an array [1,2,3], then "{{ list_var }}-suffix" becomes "[1,2,3]-suffix".

• Direct Usage: If a variable is used directly without additional text, it retains its original data type. Using the previous example, "{{ list_var }}" would output [1,2,3].

• Usage in Tools: Variables can be utilized as arguments in both regular and system tools, allowing dynamic data flow between tools.

• Scope: Variables have local scope. They are accessible within the block they are defined and any nested blocks. Redefining a variable in a nested block does not affect its value in the outer block.

  steps:
    - tools:
        - name: some_tool
          arguments:
            arg1: '{{ variable1 }}'
          returns: variable2
        - name: some_other_tool
          arguments:
            arg2: '{{ variable2 }}'
          returns: variable3

Global Constants

Global constants are defined using the constants key at the root level of the plan. While it is technically possible to overwrite constants within a local scope, this practice is generally discouraged. Additionally, you can nest constants within other constants, provided that the nested constants are declared before their parent constant.

constants:
  constant1: prefix
  constant2: '{{ constant1 }}-suffix'

steps:
  - tools:
      - name: some_tool
        arguments:
          arg1: '{{ constant2 }}'

Example Yaml Plan

constants:
  limit: 5

steps:
  - tools:
      # Use regex to find all files in the current directory (up to a limit of 5)
      - name: find_files_by_name_with_regex
        arguments:
          path_to_directory: '.'
          find_file_name_pattern: '.*'
          limit: '{{ limit }}'
        returns: files

      # For each file, get the file content
      - name: for_each
        items: '{{ files }}'
        each_item:
          item_name: file
          tools:
            - name: get_content_from_file
              arguments:
                path_to_file: '{{ file }}'
              returns: file_content

            # If the file content exists, show it in the agent trace.
            - name: if_else
              condition: '{{ file_content }}'
              if:
                tools:
                  - name: echo_one
                    arguments:
                      echo_arg: |
                        The file content exists! Here it is:
                        ```
                        {{ file_content }}
                        ```

              # If the file content does not exist, log that it does not exist in the agent trace.
              else:
                tools:
                  - name: echo_one
                    arguments:
                      echo_arg: |
                        The file content does not exist!