Iteration Step

Run one step many times over with the iteration step

The iteration step (iterator) allows you to repeat the same step(s) repeatedly. It's functionally equivalent to a for-loop in code. It's great for looping over the same LLM prompt multiple times, but has other applications.

1. First, create a valid input Array

// Example 1 - Array of numbers: 
return([1,2,3,4,5]);
  • The iterator will only accept an array as the proper input type

    • An array is a data structure that starts and ends with brackets such as [ ] and contains a comma-separated list of values
  • Here are some example of valid arrays :

  • # Basic Array
    ["San Francisco", "New York City", "Miami"]
    
    # Multi-attribute Array
    [
      {
        "link": "https://openai.com/",
        "title": "OpenAI",
        "source": "OpenAI"
      },
      {
        "link": "https://www.youtube.com/@OpenAI",
        "title": "OpenAI",
        "source": "YouTube"
      },
      {
        "link": "https://en.wikipedia.org/wiki/OpenAI",
        "title": "OpenAI",
        "source": "Wikipedia"
      }
    ]
    
  • The workflow Step immediately before an iterator step must output an Array otherwise the Iterator will fail. :thumbsdown:

  • You can generate an array through an LLM step, code step, or API step. :

  • Some code samples for testing :

    // Example 2 - Array of strings: 
    return(["San Francisco", "New York City", "Miami"]);
    
    
    // Example 3 - Array of JSON objects: 
    return(
      [
        {
          "link": "https://openai.com/",
          "title": "OpenAI",
          "source": "OpenAI"
        },
        {
          "link": "https://www.youtube.com/@OpenAI",
          "title": "OpenAI",
          "source": "YouTube"
        },
        {
          "link": "https://en.wikipedia.org/wiki/OpenAI",
          "title": "OpenAI",
          "source": "Wikipedia"
        }
      ]
      );
    
    

    Tip : If AirOps detects a valid Array it will display List next to the Out Type. Useful for testing.
    [block:image]
    {
    "images": [
    {
    "image": [
    "https://files.readme.io/77b52b7-image.png",
    null,
    ""
    ],
    "align": "center",
    "sizing": "400px",
    "border": true
    }
    ]
    }
    [/block]

2. Configure the Iterator

  • The iterator will repeat a step (or many steps) as many times as the size of your input array
  • For any step(s) you add to the iterator, you can reference two variables from your input array:
    • The "element": the value of the current iteration
    • The "element index": the numerical index of the current iteration
      • The iterator starts at 0 for the first element and increments until [the size of your input array - 1]

Let's use the examples above to demonstrate how the iterator will loop over each element. Each of the rows from the following table is one loop or repetition:

Element IndexExample 1 ElementExample 2 ElementExample 3 Element
01San Francisco{
"link": "https://openai.com/",
"title": "OpenAI",
"source": "OpenAI"
}
12New York City{
"link": "https://www.youtube.com/@OpenAI",
"title": "OpenAI",
"source": "YouTube"
}
23Miami{
"link": "https://en.wikipedia.org/wiki/OpenAI",
"title": "OpenAI",
"source": "Wikipedia"
}

How to Reference the Element and Element Index

To access the element or element index, use the the following liquid syntax where x is the step number of the iterator:

  • Element: {{step_x.element}}
  • Element Index: {{step_x.element_index}}

Let's demonstrate this in a prompt using "Example 2" above:

// LLM Step
System: 
You are a travel guide expert. 
Your task is to generate a guide for a 5-day trip to the city provided by the user.

User: 
Please give me a 5-day travel guide for my trip to {{step_x.element}}.

3. Configure the Iteration Step Output

Just as we provided the iteration step an array, the step will also output an array.

To visualize what this looks like, the output from "Example 2" above would be an array of three strings (albeit long strings) which might look like this:

[ "Travel Guide for San Francisco...", "Travel Guide for New York City...", "Travel Guide for Miami..."]

If you just want the extract text from the output array (removing the brackets and commas), you could use a text step that loops over the output of the iterator and outputs only the text. For example:

// Text Step where step_x is the iterator step
{% for chunk in step_x.output %}
{{chunk}}
{% endfor %}