diff --git a/apps/docs/content/docs/blocks/agent.mdx b/apps/docs/content/docs/blocks/agent.mdx index 1f9747a0d2..320396967e 100644 --- a/apps/docs/content/docs/blocks/agent.mdx +++ b/apps/docs/content/docs/blocks/agent.mdx @@ -81,22 +81,16 @@ Control the creativity and randomness of responses: -

- More deterministic, focused responses. Best for factual tasks, customer support, and - situations where accuracy is critical. -

+ More deterministic, focused responses. Best for factual tasks, customer support, and + situations where accuracy is critical. -

- Balanced creativity and focus. Suitable for general purpose applications that require both - accuracy and some creativity. -

+ Balanced creativity and focus. Suitable for general purpose applications that require both + accuracy and some creativity. -

- More creative, varied responses. Ideal for creative writing, brainstorming, and generating - diverse ideas. -

+ More creative, varied responses. Ideal for creative writing, brainstorming, and generating + diverse ideas. diff --git a/apps/docs/content/docs/blocks/loop.mdx b/apps/docs/content/docs/blocks/loop.mdx new file mode 100644 index 0000000000..0ef768c99d --- /dev/null +++ b/apps/docs/content/docs/blocks/loop.mdx @@ -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. + + + + + 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. + + +## Overview + +The Loop block enables you to: + + + + Iterate over collections: Process arrays or objects one item at a time + + + Repeat operations: Execute blocks a fixed number of times + + + +## Configuration Options + +### Loop Type + +Choose between two types of loops: + + + + 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 + ``` + + + 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" + ``` + + + +## 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: + +- **``**: Array of results from all loop iterations + +## Example Use Cases + +### Processing API Results + +
+

Scenario: Process multiple customer records

+
    +
  1. API block fetches customer list
    2. +
  2. ForEach loop iterates over each customer
    3. +
  3. Inside loop: Agent analyzes customer data
    4. +
  4. Inside loop: Function stores analysis results
    5. +
+
+ +### Iterative Content Generation + +
+

Scenario: Generate multiple variations

+
    +
  1. Set For loop to 5 iterations
    2. +
  2. Inside loop: Agent generates content variation
    3. +
  3. Inside loop: Evaluator scores the content
    4. +
  4. After loop: Function selects best variation
    5. +
+
+ +## Advanced Features + +### Limitations + + + 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. + + + + Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead. + + +## Inputs and Outputs + + + +
    +
  • + Loop Type: Choose between 'for' or 'forEach' +
    • +
  • + Iterations: Number of times to execute (for loops) +
    • +
  • + Collection: Array or object to iterate over (forEach loops) +
    • +
+ + +
    +
  • + loop.currentItem: Current item being processed +
    • +
  • + loop.index: Current iteration number (0-based) +
    • +
  • + loop.items: Full collection (forEach loops) +
    • +
+ + +
    +
  • + loop.results: Array of all iteration results +
    • +
  • + Structure: Results maintain iteration order +
    • +
  • + Access: Available in blocks after the loop +
    • +
+ + + +## 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 \ No newline at end of file diff --git a/apps/docs/content/docs/blocks/meta.json b/apps/docs/content/docs/blocks/meta.json index 98a69a80e8..374ed282c1 100644 --- a/apps/docs/content/docs/blocks/meta.json +++ b/apps/docs/content/docs/blocks/meta.json @@ -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" + ] } diff --git a/apps/docs/content/docs/blocks/parallel.mdx b/apps/docs/content/docs/blocks/parallel.mdx new file mode 100644 index 0000000000..66014b8c29 --- /dev/null +++ b/apps/docs/content/docs/blocks/parallel.mdx @@ -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. + + + + + Parallel blocks are container nodes that execute their contents multiple times simultaneously, unlike loops which execute sequentially. + + +## Overview + +The Parallel block enables you to: + + + + Distribute work: Process multiple items concurrently + + + Speed up execution: Run independent operations simultaneously + + + Handle bulk operations: Process large datasets efficiently + + + Aggregate results: Collect outputs from all parallel executions + + + +## Configuration Options + +### Parallel Type + +Choose between two types of parallel execution: + + + + 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 ┘ + ``` + + + 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" ┘ + ``` + + + +## 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: + +- **``**: Array of results from all parallel instances + +## Example Use Cases + +### Batch API Processing + +
+

Scenario: Process multiple API calls simultaneously

+
    +
  1. Parallel block with collection of API endpoints
    2. +
  2. Inside parallel: API block calls each endpoint
    3. +
  3. After parallel: Process all responses together
    4. +
+
+ +### Multi-Model AI Processing + +
+

Scenario: Get responses from multiple AI models

+
    +
  1. Count-based parallel set to 3 instances
    2. +
  2. Inside parallel: Agent configured with different model per instance
    3. +
  3. After parallel: Compare and select best response
    4. +
+
+ +## 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 + + + 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 + + + + 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. + + + + 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 + + +## 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 + + + +
    +
  • + Parallel Type: Choose between 'count' or 'collection' +
    • +
  • + Count: Number of instances to run (count-based) +
    • +
  • + Collection: Array or object to distribute (collection-based) +
    • +
+ + +
    +
  • + parallel.currentItem: Item for this instance +
    • +
  • + parallel.index: Instance number (0-based) +
    • +
  • + parallel.items: Full collection (collection-based) +
    • +
+ + +
    +
  • + parallel.results: Array of all instance results +
    • +
  • + Access: Available in blocks after the parallel +
    • +
+ + + +## 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 \ No newline at end of file diff --git a/apps/docs/content/docs/execution/index.mdx b/apps/docs/content/docs/execution/index.mdx index ce7f14e87c..49de3bdbdc 100644 --- a/apps/docs/content/docs/execution/index.mdx +++ b/apps/docs/content/docs/execution/index.mdx @@ -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. -
- -
- - 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. ## Execution Documentation diff --git a/apps/docs/content/docs/execution/loops.mdx b/apps/docs/content/docs/execution/loops.mdx deleted file mode 100644 index 328cec4424..0000000000 --- a/apps/docs/content/docs/execution/loops.mdx +++ /dev/null @@ -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. - -
- -
- -## 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 - - - Loops are particularly powerful for AI workflows, allowing you to implement techniques like - chain-of-thought reasoning, recursive refinement, and multi-step problem solving. - - -## Creating Loops - -To create a loop in your workflow: - - - - Select Blocks: Choose the blocks you want to include in the loop - - - Create Loop: Use the "Create Loop" option in the editor - - - Configure Loop Settings: Set iteration limits and conditions - - - Create Feedback Connections: Connect outputs from later blocks back to earlier - blocks - - - -## 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 - - - 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. - - -### Loop Conditions - -Loops can continue based on different types of conditions: - - - - 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. - - - - 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. - - - - 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. - - - -## 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 - -
-

Example: Content Refinement

-
- Create a loop where an Agent block generates content, an Evaluator block assesses it, and a - Function block decides whether to continue refining. -
-
    -
  1. Agent generates initial content
    2. -
  2. Evaluator scores the content
    3. -
  3. Function analyzes score and provides feedback
    4. -
  4. Loop back to Agent with feedback for improvement
    5. -
  5. Continue until quality threshold is reached
    6. -
-
- -### Batch Processing - -
-

Example: Data Processing Pipeline

-
- Process a collection of items one at a time through a series of blocks. -
-
    -
  1. Function block extracts the next item from a collection
    2. -
  2. Processing blocks operate on the single item
    3. -
  3. Results are accumulated in a Memory block
    4. -
  4. Loop continues until all items are processed
    5. -
-
- -### Recursive Problem Solving - -
-

Example: Multi-step Reasoning

-
- Implement a recursive approach to complex problem solving. -
-
    -
  1. Agent analyzes the current problem state
    2. -
  2. Function block implements a step in the solution
    3. -
  3. Condition block checks if the problem is solved
    4. -
  4. Loop continues until solution is found or maximum steps reached
    5. -
-
- -## 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 - - - Loops with many blocks or complex operations can impact performance. Consider optimizing - individual blocks if your loops need many iterations. - - -## 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. diff --git a/apps/docs/content/docs/execution/meta.json b/apps/docs/content/docs/execution/meta.json index b7738fded5..f6bc4b0fd8 100644 --- a/apps/docs/content/docs/execution/meta.json +++ b/apps/docs/content/docs/execution/meta.json @@ -1,4 +1,4 @@ { "title": "Execution", - "pages": ["basics", "loops", "advanced"] + "pages": ["basics", "advanced"] } diff --git a/apps/docs/public/static/dark/loop-dark.png b/apps/docs/public/static/dark/loop-dark.png new file mode 100644 index 0000000000..82c53046ff Binary files /dev/null and b/apps/docs/public/static/dark/loop-dark.png differ diff --git a/apps/docs/public/static/dark/parallel-dark.png b/apps/docs/public/static/dark/parallel-dark.png new file mode 100644 index 0000000000..e72a8c88ae Binary files /dev/null and b/apps/docs/public/static/dark/parallel-dark.png differ diff --git a/apps/docs/public/static/light/loop-light.png b/apps/docs/public/static/light/loop-light.png new file mode 100644 index 0000000000..24d8b99f8e Binary files /dev/null and b/apps/docs/public/static/light/loop-light.png differ diff --git a/apps/docs/public/static/light/parallel-light.png b/apps/docs/public/static/light/parallel-light.png new file mode 100644 index 0000000000..05efcce7a3 Binary files /dev/null and b/apps/docs/public/static/light/parallel-light.png differ