roast-ai 0.4.10 → 0.5.1

data/dsl/tutorial/06_reusable_scopes/basic_scope.rb

@@ -0,0 +1,63 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates basic named execute scopes and the call cog.
+# It shows how to define reusable logic and invoke it multiple times.
+
+config {}
+
+# Define a reusable scope that displays a separator
+execute(:print_separator) do
+  ruby { puts "=" * 70 }
+end
+
+# Define a scope that generates a random word
+execute(:random_word) do
+  cmd(:word) { "shuf /usr/share/dict/words -n 1" }
+
+  outputs! { cmd!(:word).text }
+end
+
+# Main workflow
+execute do
+  call(run: :print_separator)
+
+  ruby { puts "REUSABLE SCOPES EXAMPLE" }
+
+  call(run: :print_separator)
+
+  # Call the random_word scope three times
+  ruby { puts "\nGenerating three random words:" }
+
+  call(:word1, run: :random_word)
+  call(:word2, run: :random_word)
+  call(:word3, run: :random_word)
+
+  # Extract and display the results
+  ruby do
+    word1 = from(call!(:word1))
+    word2 = from(call!(:word2))
+    word3 = from(call!(:word3))
+
+    puts "  1. #{word1}"
+    puts "  2. #{word2}"
+    puts "  3. #{word3}"
+  end
+
+  call(run: :print_separator)
+
+  ruby do
+    puts <<~NOTE
+      KEY POINTS:
+      - Named scopes don't run automatically - they must be called
+      - The same scope can be called multiple times
+      - Each call is independent with its own execution context
+      - Use outputs! to return values from a scope
+      - Use from() to extract the returned value
+    NOTE
+  end
+
+  call(run: :print_separator)
+end

data/dsl/tutorial/06_reusable_scopes/parameterized_scope.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates parameterized scopes.
+# It shows how to pass values to scopes and use them within the scope's cogs.
+
+config do
+  chat do
+    model "gpt-4o-mini"
+  end
+end
+
+# Define a scope that analyzes text
+execute(:analyze_text) do
+  chat(:analysis) do |_, text|
+    # The text parameter comes from the call cog's input block
+    <<~PROMPT
+      Analyze this text and provide:
+      1. Word count (approximate)
+      2. Main topic
+      3. Sentiment (positive/negative/neutral)
+
+      Text: #{text}
+
+      Return your analysis as a brief summary.
+    PROMPT
+  end
+
+  outputs! { chat!(:analysis).response }
+end
+
+# Main workflow
+execute do
+  ruby { puts "=" * 70 }
+  ruby { puts "PARAMETERIZED SCOPES EXAMPLE" }
+  ruby { puts "=" * 70 }
+
+  # Analyze different texts using the same scope
+  call(:analysis1, run: :analyze_text) do
+    "The quick brown fox jumps over the lazy dog."
+  end
+
+  call(:analysis2, run: :analyze_text) do
+    "Artificial intelligence is transforming how we build software."
+  end
+
+  call(:analysis3, run: :analyze_text) do
+    "I'm disappointed with the results of this experiment."
+  end
+
+  # Display all results
+  ruby do
+    puts "\nANALYSIS 1:"
+    puts from(call!(:analysis1))
+
+    puts "\nANALYSIS 2:"
+    puts from(call!(:analysis2))
+
+    puts "\nANALYSIS 3:"
+    puts from(call!(:analysis3))
+  end
+
+  ruby { puts "\n" + "=" * 70 }
+
+  ruby do
+    puts <<~NOTE
+      KEY POINTS:
+      - Pass values to scopes using call's input block
+      - Access the value as the second parameter in cog blocks
+      - The same scope can process different inputs
+      - This makes scopes reusable and composable
+    NOTE
+  end
+
+  ruby { puts "=" * 70 }
+end

data/dsl/tutorial/07_processing_collections/README.md

@@ -0,0 +1,152 @@
+# Chapter 7: Processing Collections
+
+Learn how to process arrays and other collections with the `map` cog, which applies a named execute scope to each item
+in a collection.
+
+## The `map` Cog
+
+The `map` cog executes a named execute scope (defined with `execute(:name)`) for each item in a collection:
+
+```ruby
+execute(:process_item) do
+  chat(:analyze) do |_, item|
+    "Analyze this item: #{item}"
+  end
+end
+
+execute do
+  map(run: :process_item) { ["item1", "item2", "item3"] }
+end
+```
+
+The scope receives each item as its value parameter, just like with the `call` cog.
+
+## Collecting Results
+
+Use `collect` to gather outputs from all iterations into an array:
+
+```ruby
+# Get all final outputs
+results = collect(map!(:process_items))
+
+# Transform outputs with a block, with access to the original item and its index in the source collection
+results = collect(map!(:process_items)) do |output, item, index|
+  { original_item: item, result_text: output.text, index: }
+end
+
+# Access other cog outputs from within each iteration
+sessions = collect(map!(:process_items)) do
+  chat!(:analyze).session
+end
+```
+
+## Reducing Results
+
+Use `reduce` to combine outputs into a single value:
+
+```ruby
+# Sum all outputs
+# The second argument to `reduce` is the initial value for the accumulator. It is required.
+total = reduce(map!(:calculate_scores), 0) do |sum, output|
+  # the block given to `reduce` should return the new value of the accumulator at each step
+  sum + output
+end
+
+# Build a hash
+results = reduce(map!(:process_items), {}) do |hash, output, item, index|
+  # returning nil will skip this item; it will not reset the accumulator to nil
+  hash.merge(item => output) unless output.text.include?("failure")
+end
+```
+
+## Parallel Execution
+
+By default, `map` runs iterations serially. Configure parallel execution for the `map` cog in the `config` block.
+Roast uses fibers for efficient asynchronous operation.
+
+```ruby
+config do
+  map do
+    parallel(3) # Run up to 3 iterations concurrently for all `map` cogs
+  end
+
+  map(:unlimited) do
+    parallel! # Run all iterations in parallel for a specific `map` cog
+  end
+end
+```
+
+Results from `collect` and `reduce` are always returned in the original order, regardless of completion order.
+
+## Accessing Specific Iterations
+
+Access the output from a specific iteration using `.iteration(index)`.
+This is convenient shorthand to avoid having to `collect` all the outputs when you only want one
+in a particular situation.
+
+```ruby
+# Get output from third iteration (index 2)
+result = from(map!(:process_items).iteration(2))
+
+# Access first and last iterations
+first_result = from(map!(:process_items).first)
+last_result = from(map!(:process_items).last)
+
+# Use with a block to access specific cogs
+result = from(map!(:process_items).iteration(2)) do
+  chat!(:analyze).response
+end
+```
+
+## Working with Indices
+
+Scopes called by `map` receive the iteration index as a third parameter:
+
+```ruby
+execute(:process_with_index) do
+  chat(:numbered) do |_, item, index|
+    "Process item #{index}: #{item}"
+  end
+end
+
+execute do
+  # Default: indices start at 0
+  map(run: :process_with_index) { ["a", "b", "c"] }
+
+  # Custom starting index
+  map(run: :process_with_index) do |my|
+    my.items = ["a", "b", "c"]
+    my.initial_index = 1 # Start counting from 1
+  end
+end
+```
+
+Technically, because you can call a scope with `call` just as well as `map`, the third `index` argument
+will always be present. When you invoke a scope with `call`, the index will be 0 by default. You can also override
+the index value for an individual call invocation, to simulate processing one item from the middle of a collection.
+
+```ruby
+call(run: :some_scope) do |my|
+  my.value = "some data"
+  my.index = 3
+end
+```
+
+## Running the Workflows
+
+Try these examples to see `map` in action:
+
+```bash
+# Basic map with collect, reduce, and accessing specific iterations
+bin/roast execute --executor=dsl dsl/tutorial/07_processing_collections/basic_map.rb
+
+# Parallel execution
+bin/roast execute --executor=dsl dsl/tutorial/07_processing_collections/parallel_map.rb
+```
+
+## What's Next?
+
+In the next chapter, you'll learn about iterative workflows with the `repeat` cog: an easy way to execute a set of
+steps repeatedly until a condition is met.
+
+But first, experiment with `map` to process collections and try different parallel execution strategies!

data/dsl/tutorial/07_processing_collections/basic_map.rb

@@ -0,0 +1,70 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  chat do
+    model "gpt-4o-mini"
+    provider :openai
+    no_display!
+  end
+end
+
+execute(:analyze_city) do
+  chat(:extract_info) do |_, city|
+    <<~PROMPT
+      For the city #{city}, provide a one-sentence fact about its population or geography.
+      Keep it brief and factual.
+    PROMPT
+  end
+end
+
+execute do
+  cities = ["Tokyo", "Paris", "Cairo", "Sydney"]
+
+  # Apply the :analyze_city scope to each city
+  map(:city_analysis, run: :analyze_city) { cities }
+
+  # Collect all the responses
+  ruby do
+    puts "\n=== City Facts ==="
+    facts = collect(map!(:city_analysis)) do
+      chat!(:extract_info).response.strip
+    end
+
+    cities.each_with_index do |city, i|
+      puts "#{city}: #{facts[i]}"
+    end
+  end
+
+  # Use reduce to combine results
+  ruby do
+    summary = reduce(map!(:city_analysis), "Summary of cities:") do |acc, _, city, index|
+      "#{acc}\n- #{city} (position #{index})"
+    end
+    puts "\n#{summary}"
+  end
+
+  # Access a specific iteration
+  ruby do
+    puts "\n=== Accessing Specific Iterations ==="
+
+    # Get the second city's analysis (Paris, index 1)
+    paris_fact = from(map!(:city_analysis).iteration(1)) do
+      chat!(:extract_info).response.strip
+    end
+    puts "Paris (index 1): #{paris_fact}"
+
+    # Access first and last
+    first_city = from(map!(:city_analysis).first) do
+      chat!(:extract_info).response.strip
+    end
+    last_city = from(map!(:city_analysis).last) do
+      chat!(:extract_info).response.strip
+    end
+
+    puts "First: #{first_city}"
+    puts "Last: #{last_city}"
+  end
+end

data/dsl/tutorial/07_processing_collections/parallel_map.rb

@@ -0,0 +1,74 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  chat do
+    model "gpt-4o-mini"
+    provider :openai
+    no_display!
+  end
+
+  map(:serial) do
+    no_parallel! # Explicitly serial (this is the default)
+  end
+
+  map(:limited_parallel) do
+    parallel(2) # Process up to 2 items concurrently
+  end
+
+  map(:unlimited_parallel) do
+    parallel! # Process all items concurrently
+  end
+end
+
+execute(:generate_fact) do
+  chat(:fact) do |_, topic, index|
+    <<~PROMPT
+      Generate a brief, interesting fact (one sentence) about: #{topic}
+      Label it as "Fact #{index}:"
+    PROMPT
+  end
+end
+
+execute do
+  topics = ["Ruby", "Python", "JavaScript", "Go", "Rust"]
+
+  # Serial execution (one at a time)
+  map(:serial, run: :generate_fact) do |my|
+    my.items = topics
+    my.initial_index = 1
+  end
+
+  ruby do
+    puts "\n=== Serial Execution ==="
+    facts = collect(map!(:serial)) { chat!(:fact).response.strip }
+    facts.each { |fact| puts fact }
+  end
+
+  # Limited parallelism (up to 2 concurrent)
+  map(:limited_parallel, run: :generate_fact) do |my|
+    my.items = topics
+    my.initial_index = 1
+  end
+
+  ruby do
+    puts "\n=== Limited Parallel Execution (max 2 concurrent) ==="
+    facts = collect(map!(:limited_parallel)) { chat!(:fact).response.strip }
+    facts.each { |fact| puts fact }
+  end
+
+  # Unlimited parallelism (all at once)
+  map(:unlimited_parallel, run: :generate_fact) do |my|
+    my.items = topics
+    my.initial_index = 1
+  end
+
+  ruby do
+    puts "\n=== Unlimited Parallel Execution ==="
+    facts = collect(map!(:unlimited_parallel)) { chat!(:fact).response.strip }
+    facts.each { |fact| puts fact }
+    puts "\nNote: Results are always returned in original order, regardless of completion order."
+  end
+end

data/dsl/tutorial/08_iterative_workflows/README.md

@@ -0,0 +1,231 @@
+# Chapter 8: Iterative Workflows
+
+Learn how to create iterative workflows with the `repeat` cog, which executes a named scope repeatedly until a condition
+is met. Unlike `map` which processes a collection holding a fix number of items, `repeat` continues indefinitely until
+it hits a specified maximum number of iterations or you explicitly stop it with `break!`.
+
+## The `repeat` Cog
+
+The `repeat` cog executes a named execute scope repeatedly, where the output of each iteration becomes the input to the
+next:
+
+```ruby
+execute(:process) do
+  ruby(:step_increment) do |_, value, index|
+    new_value = value + index
+    puts "Current value: #{new_value}"
+    new_value
+  end
+
+  ruby { break! if ruby!(:step_increment).value >= 12 }
+
+  outputs { ruby!(:step_increment).value }
+end
+
+execute do
+  repeat(:loop, run: :process) { 0 } # Start with initial value 0
+
+  ruby do
+    puts "Final value: #{repeat!(:loop).value}"
+  end
+end
+```
+
+Each iteration receives two parameters:
+
+1. The **value** from the previous iteration (or the initial value for the first iteration)
+2. The **index** starting at 0 (or a custom `initial_index`)
+
+Key differences from `map`:
+
+- `repeat` continues until you call `break!` (or hit the specified maximum number of iterations)
+- Each iteration's output becomes the next iteration's input (iterative transformation)
+- `map` processes independent items; `repeat` builds up a result iteratively
+
+## Maximum Iteration Limit
+
+You can specify the optional `max_iterations` attribute on the input value of the `repeat` cog to set a limit
+on the number of loop iterations that can run. By default, the value of this attribute is `nil`, and the loop
+will be allowed to run forever, until explicitly terminated from within.
+
+## Breaking Out of Loops
+
+Use `break!` to terminate the loop. Once `break!` is called, no more iterations will run.
+Also, the cog in which you call `break!` will not run, and no subsequent cogs in that iteration will run either.
+It is often cleanest to call `break!` in a `ruby` cog at the end of the scope, that only performs a check for the
+termination condition(s), but you can call it anywhere that makes sense.
+
+NOTE: the `outputs` block will __always__ run, even if you call `break!` earlier in the scope.
+
+```ruby
+execute(:find_threshold) do
+  chat(:analyze) do |_, number|
+    "Is #{number} greater than 50? Answer yes or no."
+  end
+
+  ruby do
+    response = chat!(:analyze).response
+    break! if response.downcase.include?("yes")
+  end
+
+  outputs { |_, number| number + 10 }
+end
+
+execute do
+  repeat(:search, run: :find_threshold) { 0 }
+
+  ruby do
+    puts "Stopped at: #{repeat!(:search).value}"
+  end
+end
+```
+
+## Skipping to the Next Iteration
+
+Use `next!` to skip the rest of the current iteration and immediately start the next one:
+
+```ruby
+execute(:process_numbers) do
+  ruby(:check) do |_, _, index|
+    # Skip processing for multiples of 3
+    if index % 3 == 0
+      puts "  Skipping every third 3 iteration"
+      next!
+    end
+    puts "Processing #{index}"
+  end
+
+  ruby(:double) do |_, value|
+    result = value * 2
+    puts "  Doubled to #{result}"
+    result
+  end
+
+  ruby { |_, _, index| break! if index >= 10 }
+
+  outputs { ruby!(:double).value }
+end
+
+execute do
+  repeat(run: :process_numbers) { 1 }
+end
+```
+
+When `next!` is called, the remaining cogs in that iteration are skipped, but the `outputs` block will still run, to
+generate the input value for the next iteration.
+
+## Accessing Iteration Results
+
+Access specific iterations or the final result:
+
+```ruby
+execute do
+  repeat(:loop, run: :process) { 0 }
+
+  ruby do
+    # Get value directly from the final iteration's output block
+    final = repeat!(:loop).value
+    puts "Final result: #{final}"
+
+    # Access specific iterations
+    first = from(repeat!(:loop).first)
+    last = from(repeat!(:loop).last)
+    third = from(repeat!(:loop).iteration(2))
+
+    puts "First iteration: #{first}"
+    puts "Last iteration: #{last}"
+    puts "Third iteration: #{third}"
+
+    # Access specific cogs in specific iterations
+    answer = from(repeat!(:loop).iteration(-2)) { chat!(:question).text }
+    puts "Second-to-last answer: #{answer}"
+  end
+end
+```
+
+## Processing All Iterations
+
+Use `.results` with `collect` or `reduce` to process all iteration outputs:
+
+```ruby
+execute do
+  repeat(:loop, run: :calculate) { 1 }
+
+  ruby do
+    # Collect all intermediate values
+    all_values = collect(repeat!(:loop).results) do
+      ruby!(:calculate).value
+    end
+    puts "All values: #{all_values.inspect}"
+
+    # Sum all iterations
+    total = reduce(repeat!(:loop).results, 0) do |sum|
+      sum + ruby!(:calculate).value
+    end
+    puts "Sum of all iterations: #{total}"
+  end
+end
+```
+
+## The `outputs` Block
+
+The `outputs` block determines what value gets passed to the next iteration. It always runs, even on an iteration where
+`break!` or `next!` is called:
+
+```ruby
+execute(:accumulate) do
+  ruby(:add) do |_, sum, index|
+    sum + index
+  end
+
+  ruby { |_, _, index| break! if index >= 5 }
+
+  # This runs even on the final iteration (when break! is called)
+  outputs { ruby!(:add).value }
+end
+
+execute do
+  repeat(run: :accumulate) { 0 }
+
+  ruby do
+    # The final value includes the computation from the iteration where break! was called
+    puts "Final sum: #{repeat!(:accumulate).value}"
+  end
+end
+```
+
+## Custom Starting Index
+
+Customize where iteration indices start:
+
+```ruby
+execute do
+  repeat(run: :process) do |my|
+    my.value = 100
+    my.index = 10 # Start counting from 10
+  end
+
+  ruby do
+    puts "Final: #{repeat!.value}"
+  end
+end
+```
+
+## Running the Workflows
+
+Try these examples to see `repeat` in action:
+
+```bash
+# Basic iterative transformation
+bin/roast execute --executor=dsl dsl/tutorial/08_iterative_workflows/basic_repeat.rb
+
+# Using break! to terminate based on conditions
+bin/roast execute --executor=dsl dsl/tutorial/08_iterative_workflows/conditional_break.rb
+```
+
+## What's Next?
+
+In the final chapter, you'll learn about asynchronous cogs: how to run multiple independent tasks concurrently to improve
+workflow performance without waiting for each task to complete before starting the next.
+
+But first, experiment with `repeat` to create iterative transformations and see how values flow from one iteration to the next!