roast-ai 0.4.10 → 0.5.0

data/dsl/tutorial/08_iterative_workflows/basic_repeat.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  chat { no_display! }
+end
+
+execute(:refine_text) do
+  chat(:improve) do |_, text|
+    <<~PROMPT
+      Improve this text by making it more concise and clear.
+      Keep the same meaning but use fewer words.
+
+      Text: #{text}
+
+      Return only the improved text, nothing else.
+    PROMPT
+  end
+
+  ruby do |_, _, index|
+    puts "\n--- Iteration #{index} ---"
+    puts chat!(:improve).response
+    break! if index >= 3
+  end
+
+  outputs { chat!(:improve).text }
+end
+
+execute do
+  initial_text = <<~TEXT
+    It is widely known and commonly accepted by many people that
+    regular physical exercise and activity is generally beneficial
+    and helpful for maintaining good health and overall wellness.
+  TEXT
+
+  puts "=== Original Text ==="
+  puts initial_text
+
+  repeat(:refinement, run: :refine_text) { initial_text }
+
+  ruby do
+    puts "\n=== Final Result ==="
+    puts repeat!(:refinement).value
+
+    puts "\n=== All Iterations ==="
+    all_versions = collect(repeat!(:refinement).results) do
+      chat!(:improve).response
+    end
+
+    all_versions.each_with_index do |version, i|
+      puts "\nIteration #{i}:"
+      puts version
+    end
+  end
+end

data/dsl/tutorial/08_iterative_workflows/conditional_break.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  chat { display! }
+end
+
+execute(:guess_number) do
+  ruby { |_, _, index| puts "\n--- Iteration #{index} ---" }
+
+  chat(:make_initial_guess) do |_, _, index|
+    skip! unless index == 0
+
+    <<~PROMPT
+      I'm thinking of a number between 1 and 100.
+      Take a guess! Respond with just the number.
+    PROMPT
+  end
+
+  chat(:make_guess) do |my, state, index|
+    skip! if index == 0
+
+    guess, session, target = state.values_at(:guess, :session, :target)
+    break! if guess == target
+
+    my.session = session
+    my.prompt = "Too #{guess > target ? "high" : "low"}. Guess again"
+  end
+
+  outputs do |_, target|
+    result = chat(:make_guess) || chat!(:make_initial_guess)
+    { guess: result.integer, session: result.session, target: }
+  end
+end
+
+execute do
+  ruby do
+    fail! "Target number out of range" if target!.to_i < 1 || target!.to_i > 100
+
+    puts "=== Number Guessing Game ==="
+    puts "Target number: #{target!} (hidden from the LLM)\n"
+  end
+
+  repeat(:guessing, run: :guess_number) do |my|
+    my.value = target!.to_i
+    my.max_iterations = 7
+  end
+
+  ruby do
+    iteration_count = collect(repeat!(:guessing).results).length
+
+    puts "\n=== Game Complete ==="
+    puts "Found the number in #{iteration_count} guesses!"
+  end
+end

data/dsl/tutorial/09_async_cogs/README.md

@@ -0,0 +1,197 @@
+# Chapter 9: Asynchronous Cogs
+
+Learn how to run cogs asynchronously in the background while other work continues. This is different from `map` with
+parallel execution, which can run multiple invocations of an execution scope in parallel, each processing a different
+input. Async cogs let you run all sorts of independent tasks concurrently, __within the same execution scope__ without
+waiting for one task to complete before starting another.
+
+## What Are Async Cogs?
+
+By default, cogs run synchronously: each cog must complete before the next one starts. With async cogs, you can kick off
+long-running tasks in the background and continue with other work immediately.
+
+```ruby
+config do
+  agent(:analyze_code) { async! }
+end
+
+execute do
+  # This agent starts running in the background
+  agent(:analyze_code) do
+    "Analyze the Ruby files in src/ for code quality issues. List the top three issues."
+  end
+
+  # This starts immediately without waiting for the agent to finish
+  chat(:draft_email) do
+    "Draft a brief status update email about the current sprint"
+  end
+
+  # This blocks until the agent completes, then uses its output
+  chat(:finish_email) do |my|
+    my.session = chat!(:draft_email).session
+    my.prompt = <<~PROMPT
+      "Update the status email with a summary of the issues we'll tackle next week:
+      #{agent!(:analyze_code).text}"
+    PROMPT
+  end
+end
+```
+
+## Key Differences from Parallel Map
+
+- **Async cogs**: Run different, independent tasks concurrently in the same scope (e.g., analyze code + draft email)
+- **Parallel map**: Apply the same operation to multiple items concurrently (e.g., process 10 files in parallel), each in their own scope
+
+Use async cogs when you have separate tasks that can happen at the same time. Use parallel map when you're processing a
+collection.
+
+## Configuring Async Cogs
+
+Configure cogs to run asynchronously in the `config` block:
+
+```ruby
+config do
+  # Make specific cog async
+  agent(:background_task) { async! }
+
+  # Make all agent cogs async
+  agent { async! }
+
+  # Pattern-based configuration
+  agent(/analyze_/) { async! }
+
+  # Override a more general config to make a cog explicitly synchronous (this is the default)
+  chat(:critical_step) { no_async! }
+end
+```
+
+## How Async Execution Works
+
+When an async cog is invoked:
+
+1. It starts running in the background
+2. The next cog starts immediately (doesn't wait)
+3. If you try access the async cog's output from a later cog, that will block until the async cog completes
+4. The workflow doesn't exit until all async cogs have finished
+5. A named execute scope doesn't complete until all async cogs within it have finished 
+
+```ruby
+config do
+  agent { async! }
+end
+
+execute do
+  agent(:task1) { "Read and summarize README.md" }
+  agent(:task2) { "Count lines of code in src/" }
+  agent(:task3) { "List all TODO comments" }
+
+  # Accessing outputs blocks until each completes
+  ruby do
+    puts "\nTask 1: #{agent!(:task1).response}"
+    puts "\nTask 2: #{agent!(:task2).response}"
+    puts "\nTask 3: #{agent!(:task3).response}"
+  end
+end
+```
+
+## Accessing Async Cog Outputs
+
+All three accessor patterns (the `!`, `?` and normal cog methods) work with async cogs and all will block if needed:
+
+```ruby
+config do
+  agent { async! }
+end
+
+execute do
+  agent(:background) { "Long running task" }
+
+  ruby do
+    # All of these block until the async cog completes:
+
+    # Check if it ran (blocks)
+    if agent?(:background)
+      puts "Completed!"
+    end
+
+    # Get output or nil (blocks)
+    result = agent(:background)
+
+    # Get output or raise error (blocks)
+    result = agent!(:background)
+  end
+end
+```
+
+## Real-World Example: Parallel Code Analysis
+
+Run multiple independent analyses concurrently:
+
+```ruby
+config do
+  agent { async! }
+end
+
+execute do
+  # All three start immediately
+  agent(:security) do
+    "Review files in src/ for security vulnerabilities"
+  end
+
+  agent(:performance) do
+    "Identify performance bottlenecks in src/"
+  end
+
+  agent(:style) do
+    "Check code style and formatting in src/"
+  end
+
+  # Collect results as they complete
+  ruby do
+    puts "\n=== Security Issues ==="
+    puts agent!(:security).response
+
+    puts "\n=== Performance Issues ==="
+    puts agent!(:performance).response
+
+    puts "\n=== Style Issues ==="
+    puts agent!(:style).response
+  end
+end
+```
+
+## When to Use Async Cogs
+
+**Good use cases:**
+
+- Running multiple independent agent tasks that don't depend on each other
+- Starting a long-running background task while doing other work
+- Parallelizing unrelated API calls or file operations
+
+**Not needed when:**
+
+- Cogs already run fast enough sequentially
+- Cogs depend on each other's outputs (they'll block anyway)
+- You're processing a collection (use `map` with `parallel!` instead)
+
+## Important Notes
+
+- Async cogs use Ruby's fiber-based concurrency (efficient and lightweight)
+- The workflow waits for all async cogs to complete before exiting
+- Accessing an async cog's output blocks until that cog finishes
+- All cog types (`agent`, `chat`, `cmd`, `ruby`, and even `call`, `map`, and `repeat`) can be async
+
+## Running the Workflows
+
+Try these examples to see async cogs in action:
+
+```bash
+# Basic async execution
+bin/roast execute --executor=dsl dsl/tutorial/09_async_cogs/basic_async.rb
+
+# Parallel analysis with multiple agents
+bin/roast execute --executor=dsl dsl/tutorial/09_async_cogs/parallel_analysis.rb
+
+# Synchronous barriers controlling execution order
+bin/roast execute --executor=dsl dsl/tutorial/09_async_cogs/sync_barriers.rb
+```

data/dsl/tutorial/09_async_cogs/basic_async.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  agent do
+    async!
+    display!
+  end
+end
+
+execute do
+  # All three agents start immediately and run in the background
+  agent(:readme) do
+    "Read the README.md file and give me a one-sentence summary of what this project does."
+  end
+
+  agent(:gemfile) do
+    "Look at the Gemfile and list the 3 most important dependencies (just their names)."
+  end
+
+  agent(:structure) do
+    "Look at the directory structure and tell me what programming language this project uses."
+  end
+
+  # When we access outputs, we block until that agent completes
+  ruby do
+    puts "=== Project Summary ==="
+    puts agent!(:readme).response
+
+    puts "=== Key Dependencies ==="
+    puts agent!(:gemfile).response
+
+    puts "=== Language ==="
+    puts agent!(:structure).response
+  end
+end

data/dsl/tutorial/README.md

@@ -0,0 +1,222 @@
+![roast-horiz-logo](https://github.com/user-attachments/assets/f9b1ace2-5478-4f4a-ac8e-5945ed75c5b4)
+
+# Roast Tutorial
+
+🔥 _version 1.0 feature preview_ 🔥
+
+Welcome to the Roast tutorial! This guide will teach you how to build AI workflows using the Roast DSL.
+
+## What is Roast?
+
+Roast is a Ruby-based domain-specific language for creating structured AI workflows
+and building complex AI-powered automation. You write workflows in a simple Ruby syntax to orchestrate LLM calls,
+run coding agents, process data, and so much more.
+
+## Prerequisites
+
+- Ruby installed (3.4.2+)
+- Roast gem installed
+- API keys for your AI providers of choice (to use LLM chat)
+- Claude Code CLI installed and configured (to use coding agents)
+
+## How to Use This Tutorial
+
+Each chapter is a self-contained lesson with:
+
+- **README.md** - Lesson content with explanations and code snippets
+- **Workflow files** (`.rb`) - Complete, runnable examples
+- **data/** folder - Sample data files (when needed)
+
+To run any example:
+
+```bash
+bin/roast execute --executor=dsl dsl/tutorial/CHAPTER_NAME/workflow_name.rb
+```
+
+## Tutorial Chapters
+
+### Chapter 1: Your First Workflow
+
+Quickly learn the basics: how to create and run a simple workflow with a single chat cog.
+
+**You'll learn:**
+
+- Basic workflow file structure
+- Using the `chat` cog
+- Running workflows
+- Simple configuration
+
+**Files:**
+
+- `01_your_first_workflow/hello.rb` - Simplest possible workflow
+- `01_your_first_workflow/configured_chat.rb` - Adding configuration
+
+---
+
+### Chapter 2: Chaining Cogs Together
+
+Learn how to build multi-step workflows by chaining cogs together, where the output of one step becomes the input to the
+next.
+
+**You'll learn:**
+
+- How to name cogs and reference their outputs
+- Using the `!` suffix to access previous results
+- The difference between `agent` and `chat` cogs
+- Using the `ruby` cog for custom logic
+- How data flows through a workflow
+- Resuming conversations with session management
+
+**Files:**
+
+- `02_chaining_cogs/simple_chain.rb` - Basic chaining with `chat` cogs
+- `02_chaining_cogs/code_review.rb` - Realistic workflow with `agent`, `chat`, and `ruby`
+- `02_chaining_cogs/session_resumption.rb` - Multi-turn conversations with session resumption
+
+---
+
+### Chapter 3: Targets and Parameters
+
+Learn how to make workflows flexible by accepting targets and custom parameters from the command line.
+
+**You'll learn:**
+
+- Using `target!` for single-target workflows (file, url, etc.)
+- Using `targets` for a workflow that can accept multiple targets in one shot 
+- Passing custom arguments with `args` and `kwargs`
+- Checking for argument presence
+- Combining targets with arguments
+
+**Files:**
+
+- `03_targets_and_params/single_target.rb` - Processing a single URL with `target!`
+- `03_targets_and_params/multiple_targets.rb` - Processing multiple files with arguments
+
+---
+
+### Chapter 4: Configuration Options
+
+Learn how to configure cogs to control their behavior, use different models for different steps, and manage what
+gets displayed during execution.
+
+**You'll learn:**
+
+- Global vs per-step configuration
+- Pattern-based configuration with regex
+- Display options (`show_prompt!`, `no_show_response!`)
+- Using different models for different steps
+
+**Files:**
+
+- `04_configuration_options/simple_config.rb` - Basic configuration and overrides
+- `04_configuration_options/control_display_and_temperature.rb` - Configuring multiple parameters for multiple steps
+
+---
+
+### Chapter 5: Control Flow
+
+Learn how to create dynamic workflows that adapt based on conditions: skipping steps, handling failures, and checking
+whether steps actually ran.
+
+**You'll learn:**
+
+- Conditional execution with `skip!`
+- Early termination with `fail!`
+- Checking if cogs ran with `?` accessor
+- The difference between `!`, `?`, and non-bang accessors
+
+**Files:**
+
+- `05_control_flow/conditional_execution.rb` - Using `skip!` and `?` accessor
+- `05_control_flow/handling_failures.rb` - Command failures with `no_abort_on_failure!`, `no_fail_on_error!`, and
+  explicit `fail!`
+
+---
+
+### Chapter 6: Reusable Scopes
+
+Learn how to create reusable `execute` scopes that can be called multiple times with different inputs, making your
+workflows more modular and maintainable.
+
+**You'll learn:**
+
+- Defining named execute scopes
+- Calling scopes with the `call` cog
+- Passing values to scopes
+- Returning values with `outputs`
+- Extracting outputs with `from()`
+
+**Files:**
+
+- `06_reusable_scopes/basic_scope.rb` - Defining and calling named scopes
+- `06_reusable_scopes/parameterized_scope.rb` - Passing values to scopes
+- `06_reusable_scopes/accessing_scope_outputs.rb` - Using `from()` with a block to access specific cog outputs
+
+---
+
+### Chapter 7: Processing Collections
+
+Learn how to process arrays and collections by applying a named execute scope to each item with the `map` cog.
+
+**You'll learn:**
+
+- Using the `map` cog to process collections
+- Collecting and reducing results with `collect` and `reduce`
+- Parallel execution with `parallel` configuration
+- Accessing specific iteration outputs
+- Working with iteration indices
+
+**Files:**
+
+- `07_processing_collections/basic_map.rb` - Basic map usage with collect, reduce, and accessing specific iterations
+- `07_processing_collections/parallel_map.rb` - Serial, limited parallel, and unlimited parallel execution
+
+---
+
+### Chapter 8: Iterative Workflows
+
+Learn how to create iterative workflows with the `repeat` cog, which executes a scope repeatedly until a condition is
+met, with each iteration's output becoming the next iteration's input.
+
+**You'll learn:**
+
+- Using the `repeat` cog for iterative transformations
+- How output from one iteration becomes input to the next
+- Breaking out of loops with `break!`
+- Skipping to the next iteration with `next!`
+- Accessing specific iterations and the final result with `from`
+- Processing all iterations with `collect` and `reduce`
+- Using the `outputs` block for controlling iteration values
+
+**Files:**
+
+- `08_iterative_workflows/basic_repeat.rb` - Iterative text refinement showing basic repeat patterns
+- `08_iterative_workflows/conditional_break.rb` - Number guessing game with conditional termination
+- `08_iterative_workflows/skip_with_next.rb` - Processing numbers while skipping even values
+
+---
+
+### Chapter 9: Asynchronous Cogs
+
+Learn how to run cogs asynchronously to improve workflow performance when you have independent tasks
+that can run concurrently.
+
+**You'll learn:**
+
+- How async cogs differ from parallel map execution
+- Configuring cogs to run asynchronously with `async!`
+- How async execution works and when cogs block
+- Using synchronous cogs as synchronization barriers
+- Real-world patterns for parallel code analysis
+- When to use async cogs vs other parallelization methods
+
+**Files:**
+
+- `09_async_cogs/basic_async.rb` - Simple async execution with multiple independent agent tasks
+- `09_async_cogs/parallel_analysis.rb` - Parallel code analysis using multiple agents
+- `09_async_cogs/sync_barriers.rb` - Using synchronous cogs to control execution phases
+
+---
+
+Let's get started with
+[Chapter 1](https://github.com/Shopify/roast/blob/edge/dsl/tutorial/01_your_first_workflow/README.md)!

data/dsl/working_directory.rb

@@ -0,0 +1,16 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  cmd { display! }
+  cmd(:alt) { working_directory "/tmp" }
+  cmd(:orig) { use_current_working_directory! }
+end
+
+execute do
+  cmd(:cwd) { "echo Current working directory: `pwd`" }
+  cmd(:alt) { "echo Alternate working directory: `pwd`" }
+  cmd(:orig) { "echo Back to original working directory: `pwd`" }
+end

data/exe/roast

@@ -13,5 +13,5 @@ unshift_path.call("lib")
 require "bundler/setup"
 require "roast"
 
-puts "🔥🔥🔥 Everyone loves a good roast 🔥🔥🔥\n\n"
+$stderr.puts "🔥🔥🔥 Everyone loves a good roast 🔥🔥🔥\n\n"
 Roast::CLI.start(ARGV)