github/sim
1
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-01-09 15:07:55 -05:00
Code Issues Packages Projects Releases Wiki Activity

improvement(subflow-docs): docs for loops and parallels added under blocks section (#686)

Browse Source 
* docs: update loop and parallel block documentation

* improvement(subflows-docs): add docs for subflows
This commit is contained in:
Vikhyath Mondreti
2025-07-14 18:59:49 -07:00
committed by GitHub
parent a030329fd5
commit 1213a64ecd
11 changed files with 405 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
apps/docs/content/docs/blocks/agent.mdx
View File

@@ -81,22 +81,16 @@ Control the creativity and randomness of responses:
<Tabs items={['Low (0-0.3)', 'Medium (0.3-0.7)', 'High (0.7-2.0)']}>
<Tab>
<p>
More deterministic, focused responses. Best for factual tasks, customer support, and
situations where accuracy is critical.
</p>
More deterministic, focused responses. Best for factual tasks, customer support, and
situations where accuracy is critical.
</Tab>
<Tab>
<p>
Balanced creativity and focus. Suitable for general purpose applications that require both
accuracy and some creativity.
</p>
Balanced creativity and focus. Suitable for general purpose applications that require both
accuracy and some creativity.
</Tab>
<Tab>
<p>
More creative, varied responses. Ideal for creative writing, brainstorming, and generating
diverse ideas.
</p>
More creative, varied responses. Ideal for creative writing, brainstorming, and generating
diverse ideas.
</Tab>
</Tabs>

175
apps/docs/content/docs/blocks/loop.mdx Normal file
View File

@@ -0,0 +1,175 @@
---
title: Loop
description: Create iterative workflows with loops that execute blocks repeatedly
---
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { ThemeImage } from '@/components/ui/theme-image'
The Loop block is a container block in Sim Studio that allows you to execute a group of blocks repeatedly. Loops enable iterative processing in your workflows.
<ThemeImage
lightSrc="/static/light/loop-light.png"
darkSrc="/static/dark/loop-dark.png"
alt="Loop Block"
width={300}
height={175}
/>
<Callout type="info">
Loop blocks are container nodes that can hold other blocks inside them. The blocks inside a loop will execute multiple times based on your configuration.
</Callout>
## Overview
The Loop block enables you to:
<Steps>
<Step>
<strong>Iterate over collections</strong>: Process arrays or objects one item at a time
</Step>
<Step>
<strong>Repeat operations</strong>: Execute blocks a fixed number of times
</Step>
</Steps>
## Configuration Options
### Loop Type
Choose between two types of loops:
<Tabs items={['For Loop', 'ForEach Loop']}>
<Tab>
A numeric loop that executes a fixed number of times. Use this when you need to repeat an operation a specific number of times.
```
Example: Run 5 times
- Iteration 1
- Iteration 2
- Iteration 3
- Iteration 4
- Iteration 5
```
</Tab>
<Tab>
A collection-based loop that iterates over each item in an array or object. Use this when you need to process a collection of items.
```
Example: Process ["apple", "banana", "orange"]
- Iteration 1: Process "apple"
- Iteration 2: Process "banana"
- Iteration 3: Process "orange"
```
</Tab>
</Tabs>
## How to Use Loops
### Creating a Loop
1. Drag a Loop block from the toolbar onto your canvas
2. Configure the loop type and parameters
3. Drag other blocks inside the loop container
4. Connect the blocks as needed
### Accessing Results
After a loop completes, you can access aggregated results:
- **`<loop.results>`**: Array of results from all loop iterations
## Example Use Cases
### Processing API Results
<div className="mb-4 rounded-md border p-4">
<h4 className="font-medium">Scenario: Process multiple customer records</h4>
<ol className="list-decimal pl-5 text-sm">
<li>API block fetches customer list</li>
<li>ForEach loop iterates over each customer</li>
<li>Inside loop: Agent analyzes customer data</li>
<li>Inside loop: Function stores analysis results</li>
</ol>
</div>
### Iterative Content Generation
<div className="mb-4 rounded-md border p-4">
<h4 className="font-medium">Scenario: Generate multiple variations</h4>
<ol className="list-decimal pl-5 text-sm">
<li>Set For loop to 5 iterations</li>
<li>Inside loop: Agent generates content variation</li>
<li>Inside loop: Evaluator scores the content</li>
<li>After loop: Function selects best variation</li>
</ol>
</div>
## Advanced Features
### Limitations
<Callout type="warning">
Container blocks (Loops and Parallels) cannot be nested inside each other. This means:
- You cannot place a Loop block inside another Loop block
- You cannot place a Parallel block inside a Loop block
- You cannot place any container block inside another container block
If you need multi-dimensional iteration, consider restructuring your workflow to use sequential loops or process data in stages.
</Callout>
<Callout type="info">
Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead.
</Callout>
## Inputs and Outputs
<Tabs items={['Configuration', 'Variables', 'Results']}>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>Loop Type</strong>: Choose between 'for' or 'forEach'
</li>
<li>
<strong>Iterations</strong>: Number of times to execute (for loops)
</li>
<li>
<strong>Collection</strong>: Array or object to iterate over (forEach loops)
</li>
</ul>
</Tab>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>loop.currentItem</strong>: Current item being processed
</li>
<li>
<strong>loop.index</strong>: Current iteration number (0-based)
</li>
<li>
<strong>loop.items</strong>: Full collection (forEach loops)
</li>
</ul>
</Tab>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>loop.results</strong>: Array of all iteration results
</li>
<li>
<strong>Structure</strong>: Results maintain iteration order
</li>
<li>
<strong>Access</strong>: Available in blocks after the loop
</li>
</ul>
</Tab>
</Tabs>
## Best Practices
- **Set reasonable limits**: Keep iteration counts reasonable to avoid long execution times
- **Use ForEach for collections**: When processing arrays or objects, use ForEach instead of For loops
- **Handle errors gracefully**: Consider adding error handling inside loops for robust workflows

13
apps/docs/content/docs/blocks/meta.json
View File

@@ -1,4 +1,15 @@
{
"title": "Blocks",
"pages": ["agent", "api", "condition", "function", "evaluator", "router", "response", "workflow"]
"pages": [
"agent",
"api",
"condition",
"function",
"evaluator",
"router",
"response",
"workflow",
"loop",
"parallel"
]
}

210
apps/docs/content/docs/blocks/parallel.mdx Normal file
View File

@@ -0,0 +1,210 @@
---
title: Parallel
description: Execute multiple blocks concurrently for faster workflow processing
---
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { ThemeImage } from '@/components/ui/theme-image'
The Parallel block is a container block in Sim Studio that allows you to execute multiple instances of blocks concurrently.
<ThemeImage
lightSrc="/static/light/parallel-light.png"
darkSrc="/static/dark/parallel-dark.png"
alt="Parallel Block"
width={300}
height={175}
/>
<Callout type="info">
Parallel blocks are container nodes that execute their contents multiple times simultaneously, unlike loops which execute sequentially.
</Callout>
## Overview
The Parallel block enables you to:
<Steps>
<Step>
<strong>Distribute work</strong>: Process multiple items concurrently
</Step>
<Step>
<strong>Speed up execution</strong>: Run independent operations simultaneously
</Step>
<Step>
<strong>Handle bulk operations</strong>: Process large datasets efficiently
</Step>
<Step>
<strong>Aggregate results</strong>: Collect outputs from all parallel executions
</Step>
</Steps>
## Configuration Options
### Parallel Type
Choose between two types of parallel execution:
<Tabs items={['Count-based', 'Collection-based']}>
<Tab>
Execute a fixed number of parallel instances. Use this when you need to run the same operation multiple times concurrently.
```
Example: Run 5 parallel instances
- Instance 1 ┐
- Instance 2 ├─ All execute simultaneously
- Instance 3 │
- Instance 4 │
- Instance 5 ┘
```
</Tab>
<Tab>
Distribute a collection across parallel instances. Each instance processes one item from the collection simultaneously.
```
Example: Process ["task1", "task2", "task3"] in parallel
- Instance 1: Process "task1" ┐
- Instance 2: Process "task2" ├─ All execute simultaneously
- Instance 3: Process "task3" ┘
```
</Tab>
</Tabs>
## How to Use Parallel Blocks
### Creating a Parallel Block
1. Drag a Parallel block from the toolbar onto your canvas
2. Configure the parallel type and parameters
3. Drag a single block inside the parallel container
4. Connect the block as needed
### Accessing Results
After a parallel block completes, you can access aggregated results:
- **`<parallel.results>`**: Array of results from all parallel instances
## Example Use Cases
### Batch API Processing
<div className="mb-4 rounded-md border p-4">
<h4 className="font-medium">Scenario: Process multiple API calls simultaneously</h4>
<ol className="list-decimal pl-5 text-sm">
<li>Parallel block with collection of API endpoints</li>
<li>Inside parallel: API block calls each endpoint</li>
<li>After parallel: Process all responses together</li>
</ol>
</div>
### Multi-Model AI Processing
<div className="mb-4 rounded-md border p-4">
<h4 className="font-medium">Scenario: Get responses from multiple AI models</h4>
<ol className="list-decimal pl-5 text-sm">
<li>Count-based parallel set to 3 instances</li>
<li>Inside parallel: Agent configured with different model per instance</li>
<li>After parallel: Compare and select best response</li>
</ol>
</div>
## Advanced Features
### Result Aggregation
Results from all parallel instances are automatically collected:
```javascript
// In a Function block after the parallel
const allResults = input.parallel.results;
// Returns: [result1, result2, result3, ...]
```
### Instance Isolation
Each parallel instance runs independently:
- Separate variable scopes
- No shared state between instances
- Failures in one instance don't affect others
### Limitations
<Callout type="warning">
Container blocks (Loops and Parallels) cannot be nested inside each other. This means:
- You cannot place a Loop block inside a Parallel block
- You cannot place another Parallel block inside a Parallel block
- You cannot place any container block inside another container block
</Callout>
<Callout type="warning">
Parallel blocks can only contain a single block. You cannot have multiple blocks connected to each other inside a parallel - only the first block would execute in that case.
</Callout>
<Callout type="info">
While parallel execution is faster, be mindful of:
- API rate limits when making concurrent requests
- Memory usage with large datasets
- Maximum of 20 concurrent instances to prevent resource exhaustion
</Callout>
## Parallel vs Loop
Understanding when to use each:
| Feature | Parallel | Loop |
|---------|----------|------|
| Execution | Concurrent | Sequential |
| Speed | Faster for independent operations | Slower but ordered |
| Order | No guaranteed order | Maintains order |
| Use case | Independent operations | Dependent operations |
| Resource usage | Higher | Lower |
## Inputs and Outputs
<Tabs items={['Configuration', 'Variables', 'Results']}>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>Parallel Type</strong>: Choose between 'count' or 'collection'
</li>
<li>
<strong>Count</strong>: Number of instances to run (count-based)
</li>
<li>
<strong>Collection</strong>: Array or object to distribute (collection-based)
</li>
</ul>
</Tab>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>parallel.currentItem</strong>: Item for this instance
</li>
<li>
<strong>parallel.index</strong>: Instance number (0-based)
</li>
<li>
<strong>parallel.items</strong>: Full collection (collection-based)
</li>
</ul>
</Tab>
<Tab>
<ul className="list-disc space-y-2 pl-6">
<li>
<strong>parallel.results</strong>: Array of all instance results
</li>
<li>
<strong>Access</strong>: Available in blocks after the parallel
</li>
</ul>
</Tab>
</Tabs>
## Best Practices
- **Independent operations only**: Ensure operations don't depend on each other
- **Handle rate limits**: Add delays or throttling for API-heavy workflows
- **Error handling**: Each instance should handle its own errors gracefully

7
apps/docs/content/docs/execution/index.mdx
View File

@@ -26,13 +26,8 @@ import {
Sim Studio provides a powerful execution engine that brings your workflows to life. Understanding how execution works will help you design more effective workflows and troubleshoot any issues that arise.
<div>
<video autoPlay loop muted playsInline className="w-full" src="/loops.mp4"></video>
</div>
<Callout type="info">
The execution engine handles everything from block execution order to data flow, error handling,
and loop management. It ensures your workflows run efficiently and predictably.
The execution engine handles everything from block execution order to data flow and error handling. It ensures your workflows run efficiently and predictably.
</Callout>
## Execution Documentation

214
apps/docs/content/docs/execution/loops.mdx
View File

@@ -1,214 +0,0 @@
---
title: Loops
description: Creating iterative processes with loops in Sim Studio
---
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } 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="mb-4 rounded-md border p-4">
<h4 className="font-medium">Example: Content Refinement</h4>
<div className="mb-2 text-sm text-gray-600 dark:text-gray-400">
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="list-decimal pl-5 text-sm">
<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="mb-4 rounded-md border p-4">
<h4 className="font-medium">Example: Data Processing Pipeline</h4>
<div className="mb-2 text-sm text-gray-600 dark:text-gray-400">
Process a collection of items one at a time through a series of blocks.
</div>
<ol className="list-decimal pl-5 text-sm">
<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="mb-4 rounded-md border p-4">
<h4 className="font-medium">Example: Multi-step Reasoning</h4>
<div className="mb-2 text-sm text-gray-600 dark:text-gray-400">
Implement a recursive approach to complex problem solving.
</div>
<ol className="list-decimal pl-5 text-sm">
<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.

2
apps/docs/content/docs/execution/meta.json
View File

@@ -1,4 +1,4 @@
{
"title": "Execution",
"pages": ["basics", "loops", "advanced"]
"pages": ["basics", "advanced"]
}

BIN
apps/docs/public/static/dark/loop-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

BIN
apps/docs/public/static/dark/parallel-dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 102 KiB

BIN
apps/docs/public/static/light/loop-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 114 KiB

BIN
apps/docs/public/static/light/parallel-light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB