sim/docs/content/docs/execution/loops.mdx

---
title: Loops
description: Creating iterative processes with loops in Sim Studio
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Steps, Step } from 'fumadocs-ui/components/steps'
import { Tabs, Tab } from 'fumadocs-ui/components/tabs'

Loops are a powerful feature in Sim Studio that allow you to create iterative processes, implement feedback mechanisms, and build more sophisticated workflows.

<div>
  <video 
    autoPlay 
    loop 
    muted 
    playsInline
    className="w-full"
    src="/loops.mp4"
  >
  </video>
</div>

## What Are Loops?

Loops in Sim Studio allow a group of blocks to execute repeatedly, with each iteration building on the results of the previous one. This enables:

- **Iterative Refinement**: Progressively improve outputs through multiple passes
- **Batch Processing**: Process collections of items one at a time
- **Feedback Mechanisms**: Create systems that learn from their own outputs
- **Conditional Processing**: Continue execution until specific criteria are met

<Callout type="info">
  Loops are particularly powerful for AI workflows, allowing you to implement techniques like chain-of-thought reasoning, recursive refinement, and multi-step problem solving.
</Callout>

## Creating Loops

To create a loop in your workflow:

<Steps>
  <Step>
    <strong>Select Blocks</strong>: Choose the blocks you want to include in the loop
  </Step>
  <Step>
    <strong>Create Loop</strong>: Use the "Create Loop" option in the editor
  </Step>
  <Step>
    <strong>Configure Loop Settings</strong>: Set iteration limits and conditions
  </Step>
  <Step>
    <strong>Create Feedback Connections</strong>: Connect outputs from later blocks back to earlier blocks
  </Step>
</Steps>

## Loop Configuration

When configuring a loop, you can set several important parameters:

### Iteration Limits

- **Maximum Iterations**: The maximum number of times the loop can execute (default: 5)
- **Minimum Iterations**: The minimum number of times the loop must execute before checking conditions

<Callout type="warning">
  Always set a reasonable maximum iteration limit to prevent infinite loops. The default limit of 5 iterations is a good starting point for most workflows.
</Callout>

### Loop Conditions

Loops can continue based on different types of conditions:

<Tabs items={['Conditional Block', 'Function Block', 'Fixed Iterations']}>
  <Tab>
    Use a Condition block to determine whether the loop should continue:
    
    ```javascript
    // Example condition in a Condition block
    function shouldContinueLoop() {
      // Get the current score from an evaluator block
      const score = input.evaluatorBlock.score;
      
      // Continue looping if score is below threshold
      return score < 0.8;
    }
    ```
    
    The loop will continue executing as long as the condition returns true and the maximum iteration limit hasn't been reached.
  </Tab>
  
  <Tab>
    Use a Function block to implement complex loop conditions:
    
    ```javascript
    // Example condition in a Function block
    function processAndCheckContinuation() {
      // Process data from previous blocks
      const currentResult = input.agentBlock.content;
      const previousResults = input.memoryBlock.results || [];
      
      // Store results for comparison
      const allResults = [...previousResults, currentResult];
      
      // Check if we've converged (results not changing significantly)
      const shouldContinue = previousResults.length === 0 || 
        currentResult !== previousResults[previousResults.length - 1];
      
      return {
        results: allResults,
        shouldContinue: shouldContinue
      };
    }
    ```
    
    Connect this Function block's output to a Condition block to control the loop.
  </Tab>
  
  <Tab>
    Execute the loop for a fixed number of iterations:
    
    ```
    // Set in loop configuration
    Minimum Iterations: 3
    Maximum Iterations: 3
    ```
    
    This will run the loop exactly 3 times, regardless of any conditions.
  </Tab>
</Tabs>

## Loop Execution

When a workflow with loops executes, the loop manager handles the iteration process:

1. **First Pass**: All blocks in the loop execute normally
2. **Iteration Check**: The system checks if another iteration should occur
3. **State Reset**: If continuing, block states within the loop are reset
4. **Next Iteration**: The loop blocks execute again with updated inputs
5. **Termination**: The loop stops when either:
   - The maximum iteration count is reached
   - A loop condition evaluates to false (after minimum iterations)

## Loop Use Cases

Loops enable powerful workflow patterns:

### Iterative Refinement

<div className="p-4 border rounded-md mb-4">
  <h4 className="font-medium">Example: Content Refinement</h4>
  <div className="text-sm text-gray-600 dark:text-gray-400 mb-2">
    Create a loop where an Agent block generates content, an Evaluator block assesses it, and a Function block decides whether to continue refining.
  </div>
  <ol className="text-sm list-decimal pl-5">
    <li>Agent generates initial content</li>
    <li>Evaluator scores the content</li>
    <li>Function analyzes score and provides feedback</li>
    <li>Loop back to Agent with feedback for improvement</li>
    <li>Continue until quality threshold is reached</li>
  </ol>
</div>

### Batch Processing

<div className="p-4 border rounded-md mb-4">
  <h4 className="font-medium">Example: Data Processing Pipeline</h4>
  <div className="text-sm text-gray-600 dark:text-gray-400 mb-2">
    Process a collection of items one at a time through a series of blocks.
  </div>
  <ol className="text-sm list-decimal pl-5">
    <li>Function block extracts the next item from a collection</li>
    <li>Processing blocks operate on the single item</li>
    <li>Results are accumulated in a Memory block</li>
    <li>Loop continues until all items are processed</li>
  </ol>
</div>

### Recursive Problem Solving

<div className="p-4 border rounded-md mb-4">
  <h4 className="font-medium">Example: Multi-step Reasoning</h4>
  <div className="text-sm text-gray-600 dark:text-gray-400 mb-2">
    Implement a recursive approach to complex problem solving.
  </div>
  <ol className="text-sm list-decimal pl-5">
    <li>Agent analyzes the current problem state</li>
    <li>Function block implements a step in the solution</li>
    <li>Condition block checks if the problem is solved</li>
    <li>Loop continues until solution is found or maximum steps reached</li>
  </ol>
</div>

## Best Practices for Loops

To use loops effectively in your workflows:

- **Set Appropriate Limits**: Always configure reasonable iteration limits
- **Use Memory Blocks**: Store state between iterations with Memory blocks
- **Include Exit Conditions**: Define clear conditions for when loops should terminate
- **Monitor Performance**: Watch for performance impacts with many iterations
- **Test Thoroughly**: Verify that loops terminate as expected in all scenarios

<Callout type="warning">
  Loops with many blocks or complex operations can impact performance. Consider optimizing individual blocks if your loops need many iterations.
</Callout>

## Loop Debugging

When debugging loops in your workflows:

- **Check Iteration Counts**: Verify the loop is executing the expected number of times
- **Inspect Block Inputs/Outputs**: Look at how data changes between iterations
- **Review Loop Conditions**: Ensure conditions are evaluating as expected
- **Use Console Logging**: Add console.log statements in Function blocks to track loop progress
- **Monitor Memory Usage**: Watch for growing data structures that might cause performance issues

By mastering loops, you can create much more sophisticated and powerful workflows in Sim Studio.