roast-ai 0.4.9 → 0.5.0

data/dsl/tutorial/04_configuration_options/simple_config.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates basic configuration of models and providers.
+# It shows how to set global defaults and override them for specific steps.
+
+config do
+  # Set default configuration for all chat cogs
+  chat do
+    model "gpt-4o-mini"
+    provider :openai
+    show_prompt! # Show prompts for all chat cogs
+  end
+
+  # Override for a specific cog - use more capable model
+  chat(:analyze_trends) do
+    model "gpt-5"
+  end
+
+  # Override for a specific cog - hide response
+  chat(:format_report) do
+    no_show_response!
+  end
+end
+
+execute do
+  # This cog uses the global config (gpt-4o-mini)
+  chat(:extract_info) do
+    <<~PROMPT
+      Extract the key information from this text and format it as a bullet list:
+
+      "Our Q4 results show revenue of $2.5M, up 15% from Q3. Customer count increased to 1,200
+      (from 950), and average deal size grew from $2,000 to $2,300. However, churn rate rose
+      slightly to 8% from 7%."
+    PROMPT
+  end
+
+  # This cog uses the specific override configured above (gpt-5)
+  chat(:analyze_trends) do
+    <<~PROMPT
+      Analyze these metrics and identify the most important trends:
+
+      #{chat!(:extract_info).text}
+
+      Focus on: growth patterns, concerning signals, and strategic implications.
+    PROMPT
+  end
+
+  # This cog uses the specific configuration above (hidden response)
+  chat(:format_report) do
+    <<~PROMPT
+      Format this analysis as a structured report with clear sections:
+
+      #{chat!(:analyze_trends).text}
+    PROMPT
+  end
+
+  # Final step: display the formatted report
+  ruby(:display) do
+    puts "\n" + "=" * 70
+    puts "QUARTERLY ANALYSIS REPORT"
+    puts "=" * 70
+    puts chat!(:format_report).response
+    puts "=" * 70 + "\n"
+  end
+end

data/dsl/tutorial/05_control_flow/README.md

@@ -0,0 +1,156 @@
+# Chapter 5: Control Flow
+
+In previous chapters, you learned how to chain cogs together and configure them. Now you'll learn how to create
+dynamic workflows that adapt based on conditions: skipping steps when needed, handling failures gracefully, and
+checking whether steps actually ran.
+
+## What You'll Learn
+
+- How to conditionally skip cogs with `skip!`
+- How to handle cog failures with `fail!` and `no_abort_on_failure!`
+- How command failures work and how to control them
+- How to check if a cog ran successfully with three different accessors
+- The difference between `!`, `?`, and non-bang accessors
+
+## Conditional Execution with skip!
+
+Use `skip!` inside a cog's input block to conditionally skip that cog:
+
+```ruby
+execute do
+  cmd(:check_status) { "curl https://api.example.com/status" }
+
+  cmd(:notify) do
+    status = cmd!(:check_status).out
+    skip! if status.include?("healthy")
+    "echo 'Service needs attention!'"
+  end
+end
+```
+
+When `skip!` is called, the cog immediately stops executing and is marked as skipped. Skipped cogs won't have
+output and can be detected using the `?` accessor.
+
+## Checking if Cogs Ran
+
+You have three ways to access cog outputs, each with different behavior:
+
+- `cog!(:name)` - Returns output, raises error if cog didn't run yet, was skipped, or failed
+- `cog?(:name)` - Returns `true` if cog ran and completed successfully, `false` otherwise
+- `cog(:name)` - Returns output or `nil` if cog didn't run yet, was skipped, or failed
+
+```ruby
+execute do
+  chat(:analyze) do
+    data = cmd(:fetch_data).out # Returns nil if fetch_data was skipped
+    skip! unless data
+    "Analyze this: #{data}"
+  end
+
+  ruby do
+    if chat?(:analyze)
+      puts "Analysis completed: #{chat!(:analyze).response}"
+    else
+      puts "Analysis was skipped"
+    end
+  end
+end
+```
+
+The `?` accessor is particularly useful for checking whether optional steps ran.
+
+## Handling Failures
+
+Cogs can fail in two ways: by explicitly calling `fail!`, or by encountering errors during execution (like a command
+returning a non-zero exit code). By default, any cog failure will also abort the entire workflow.
+
+### Explicit Failure with fail!
+
+Use `fail!` to terminate a cog when conditions prevent successful execution:
+
+```ruby
+execute do
+  agent(:process) do |my|
+    file = Pathname.new("my/data/file.json")
+    fail! unless file.exist?
+    my.prompt = "Process this file: #{file.realpath}"
+  end
+end
+```
+
+### Command Failures
+
+By default, the `cmd` cog automatically fails when a command returns a non-zero exit status.
+And also by default, when a cog fails the entire workflow is aborted.
+You can control both aspects of this behavior:
+
+```ruby
+config do
+  cmd(:risky) do
+    # This command might fail, but continue the workflow anyway if it does
+    no_abort_on_failure!
+  end
+  cmd(:grep) do
+    # This command might exit with a non-zero status code, but that doesn't represent a failure for it
+    no_fail_on_error!
+  end
+end
+
+execute do
+  cmd(:risky) { "[ $RANDOM -gt 30000 ] && echo 'it worked!'" } # This command will probably fail
+
+  # We expect a non-zero exit code here as part of normal operations.
+  # `grep` matching no lines does not represent a failure condition for our workflow.
+  cmd(:grep) { "grep 'pattern' file.txt" }
+
+  ruby do
+    puts cmd?(:risky) ? "Risky command succeeded" : "Risky command failed"
+    puts "Grep matched #{cmd(:grep).lines.length} lines"
+  end
+end
+```
+
+Use `no_abort_on_failure!` to let the workflow continue even when a cog fails. The non-bang and `?` accessors let you
+check the result and handle failures gracefully.
+
+Use `no_fail_on_error!` with the `cmd` cog specifically to indicate that a non-zero status code should not
+be considered a failure.
+
+## Running the Workflows
+
+To run the examples in this chapter:
+
+```bash
+# Conditional execution example
+bin/roast execute --executor=dsl dsl/tutorial/05_control_flow/conditional_execution.rb
+```
+
+```bash
+# Handling failures example
+bin/roast execute --executor=dsl dsl/tutorial/05_control_flow/handling_failures.rb
+```
+
+## Try It Yourself
+
+1. **Add conditions** - Use `skip!` to create optional workflow steps
+2. **Check outcomes** - Use the `?` accessor to branch based on whether steps ran
+3. **Handle failures** - Use `fail!` for validation and the non-bang accessor for recovery
+4. **Combine approaches** - Mix conditional execution with the techniques from previous chapters
+
+## Key Takeaways
+
+- Use `skip!` to conditionally skip cogs based on runtime conditions
+- Use `fail!` to explicitly terminate cogs that can't complete successfully
+- Commands automatically fail on non-zero exit status (configurable with `no_fail_on_error!`)
+- Use `no_abort_on_failure!` to continue workflows even when cogs fail
+- Use `cog?(:name)` to check if a cog ran successfully
+- Use `cog(:name)` (non-bang) to safely access outputs that might not exist
+- Use `cog!(:name)` when you expect the cog to have run successfully
+- Control flow makes workflows dynamic and adaptive
+
+## What's Next?
+
+In the next chapter, you'll learn about processing collections: using `map` to apply operations across multiple items
+and building workflows that handle batches of data.
+
+But first, experiment with control flow to create workflows that adapt to different conditions!

data/dsl/tutorial/05_control_flow/conditional_execution.rb

@@ -0,0 +1,62 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates conditional execution using skip! and the ? accessor.
+# It checks a random number and runs different steps based on whether it's even or odd.
+
+config do
+  cmd do
+    display!
+  end
+end
+
+execute do
+  # Generate a random number
+  cmd(:random_number) { "echo $RANDOM" }
+
+  # This step only runs if the number is even
+  cmd(:process_even) do
+    number = cmd!(:random_number).text.to_i
+    skip! if number.odd?
+    "echo 'Processing even number: #{number}'"
+  end
+
+  # This step only runs if the number is odd
+  cmd(:process_odd) do
+    number = cmd!(:random_number).text.to_i
+    skip! if number.even?
+    "echo 'Processing odd number: #{number}'"
+  end
+
+  # This step always runs and reports which path was taken
+  cmd do |my|
+    my.command = "echo"
+
+    # Use the ? accessor to check which steps ran
+    my.args << if cmd?(:process_even)
+      "Even path executed"
+    elsif cmd?(:process_odd)
+      "Odd path executed"
+    else
+      "Neither path executed (unexpected!)"
+    end
+  end
+
+  # Demonstrate using non-bang accessor
+  ruby do
+    puts "\n" + "=" * 70
+    puts "CONDITIONAL EXECUTION RESULTS"
+    puts "=" * 70
+
+    number = cmd!(:random_number).out.to_i
+    puts "Random number was: #{number}"
+
+    # Non-bang accessor returns nil if cog didn't run
+    puts "Even result: #{cmd(:process_even) || "n/a"}"
+    puts "Odd result: #{cmd(:process_odd) || "n/a"}"
+
+    puts "=" * 70 + "\n"
+  end
+end

data/dsl/tutorial/05_control_flow/handling_failures.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates failure handling with both no_abort_on_failure! and no_fail_on_error!
+# It shows how workflows can continue even when individual cogs fail.
+
+config do
+  # This chat cog might fail, but the workflow should continue
+  chat(:followup) do
+    no_abort_on_failure!
+    no_display!
+  end
+
+  # This command might return non-zero, but that's not a failure
+  cmd(:grep) do
+    no_fail_on_error!
+    no_display!
+  end
+end
+
+execute do
+  # Step 1: Ask LLM to make up some data and return it as JSON
+  chat(:generate_data) do
+    <<~PROMPT
+      Make up a simple shopping list with 3-5 items as a JSON object
+      `{ items: [ name: ..., quantity: ... ] }`.
+    PROMPT
+  end
+
+  # Step 2: Ask a follow-up question, but fail if the original response didn't include "milk"
+  chat(:followup) do
+    shopping_list_items = chat!(:generate_data).json![:items].map { |it| it[:name].downcase }
+    fail! unless shopping_list_items.include?("milk")
+
+    <<~PROMPT
+      Based on this shopping list:
+      #{chat!(:generate_data).text}
+
+      Suggest a recipe that uses milk from the list.
+    PROMPT
+  end
+
+  # Step 3: Run a command that might fail (grep returns non-zero when no matches)
+  cmd(:grep) do |my|
+    my.command = "grep -i eggs"
+    my.stdin = chat!(:generate_data).text
+  end
+
+  # Step 4: Print summary results
+  ruby do
+    puts "\n" + "=" * 70
+    puts "WORKFLOW RESULTS"
+    puts "=" * 70
+
+    shopping_list = chat!(:generate_data).json!
+    puts "\nGenerated shopping list:"
+    shopping_list[:items].each { |it| puts "- #{it[:name]}: #{it[:quantity]}" }
+
+    if chat?(:followup)
+      puts "\n✓ Follow-up succeeded (milk was in the list):"
+      puts chat!(:followup).text
+    else
+      puts "\n✗ Follow-up failed (milk was not in the list)"
+    end
+
+    if cmd!(:grep).status.exitstatus == 0
+      puts "\n✓ Grep found matches:"
+      puts cmd!(:grep).text
+    else
+      puts "\n✗ Grep found no matches"
+    end
+
+    puts "\n" + "=" * 70
+  end
+end

data/dsl/tutorial/06_reusable_scopes/README.md

@@ -0,0 +1,172 @@
+# Chapter 6: Reusable Scopes
+
+In previous chapters, all your workflows used a single `execute` block. Now you'll learn how to create reusable scopes
+that can be called multiple times with different inputs, making your workflows more modular and maintainable.
+
+## What You'll Learn
+
+- How to define named execute scopes
+- How to call scopes with the `call` cog
+- How to pass values to scopes
+- How to return values from scopes with `outputs!`
+- How to extract outputs using `from()`
+
+## Named Execute Scopes
+
+Define a named execute scope by providing a name to `execute`. Just like the top-level execute scope, you can define
+however many steps you want, and they'll run in order, top-to-bottom. Cogs can access the outputs of previous
+cog's in their own scope, but cannot access the output of cogs defined in other scopes.
+
+```ruby
+execute(:process_file) do
+  cmd(:word_count) { "wc -w #{filename}" }
+  ruby { puts "Words: #{cmd!(:word_count).text}" }
+end
+```
+You define all execute scopes at the top level of your workflow file. But, you can define them in any order. 
+Named scopes don't run automatically. They must be called explicitly using a cog like the `call` cog.
+
+## The call Cog
+
+Use the `call` cog to invoke a named scope:
+
+```ruby
+execute(:greet) do
+  chat { "say 'Hello, World!'" }
+  chat { "Tell me a funny joke" }
+end
+
+execute do
+  call(run: :greet)  # Invokes the :greet scope
+end
+```
+
+You can call the same scope multiple times:
+
+```ruby
+execute do
+  call(run: :greet)
+  call(run: :greet)
+  call(run: :greet)
+end
+```
+
+## Passing Values to Scopes
+
+Pass values to a called scope, and access them as the second block parameter in any cog's input block:
+
+```ruby
+execute(:greet_person) do
+  chat do |my, name|
+    my.prompt = "Say hello to #{name}!"
+  end
+end
+
+execute do
+  call(run: :greet_person) { "Alice" }
+  call(run: :greet_person) { "Bob" }
+end
+```
+
+The value from the `call` cog becomes available as the second parameter to any cog in the called scope.
+
+## Returning Values with outputs!
+
+Use `outputs!` to specify what a scope returns:
+
+```ruby
+execute(:double_number) do
+  ruby(:calculate) { |_, number| number * 2 }
+
+  outputs! { ruby!(:calculate).value }
+end
+
+execute do
+  call(:result, run: :double_number) { 21 }
+
+  ruby do
+    answer = from(call!(:result))
+    puts "The answer is: #{answer}"  # => 42
+  end
+end
+```
+
+The `from()` helper extracts the final output from a called scope.
+
+## Extracting output values from specific cogs
+
+The `outputs!` block is optional. In its absence, the return value will be the output value of the final cog
+in the scope. You can also pass a block to `from` and access the output of any cog(s) you want from the scope.
+
+```ruby
+execute(:number_math) do
+  ruby(:add_two) { |_, number| number + 2 }
+  ruby(:subtract_two) { |_, number| number - 2 }
+  ruby(:multiply_by_two) { |_, number| number * 2 }
+  ruby(:divide_by_two) { |_, number| number / 2 }
+end
+
+execute do
+  # the return value of the block given to `call` will be the value passed to the scope being run,
+  # but you can also set the value explicitly
+  call(:result, run: :number_math) { |my| my.value = 28 }
+
+  ruby do
+    answer = from(call!(:result)).value # this yields the output of the final cog in :number_math: ruby!(:divide_by_two)
+    puts "The final answer is: #{answer}"  # => 14
+    
+    # pass a block to `from` to access the output of other cogs from the scope that was run
+    # this block runs in the context of the other scope and can access any cogs defined in it
+    subtraction, multiplication = from(call!(:result)) do
+      [
+        ruby!(:subtract_two).value,
+        ruby!(:multiply_by_two).value
+      ]
+    end
+    puts "Some intermediate answers are: #{subtraction} (subtraction) and #{multiplication} (multiplication)"
+  end
+end
+```
+
+## Running the Workflows
+
+To run the examples in this chapter:
+
+```bash
+# Basic scope example
+bin/roast execute --executor=dsl dsl/tutorial/06_reusable_scopes/basic_scope.rb
+```
+
+```bash
+# Parameterized scope example
+bin/roast execute --executor=dsl dsl/tutorial/06_reusable_scopes/parameterized_scope.rb
+```
+
+```bash
+# Accessing specific scope outputs
+bin/roast execute --executor=dsl dsl/tutorial/06_reusable_scopes/accessing_scope_outputs.rb
+```
+
+## Try It Yourself
+
+1. **Create reusable logic** - Extract common operations into named scopes
+2. **Parameterize scopes** - Pass different values to the same scope
+3. **Return values** - Use `outputs!` to capture 'default' result values from scopes
+4. **Chain scopes** - Call scopes from within other scopes
+
+## Key Takeaways
+
+- Use `execute(:name) do ... end` to define reusable scopes
+- Use `call(run: :scope_name)` to invoke named scopes
+- Pass values to scopes using the block parameter of `call`
+- Access passed values as the second parameter in cog input blocks
+- Use `outputs!` to specify what a scope returns
+- Use `from(call!(:name))` to extract the return value
+- Named scopes don't run unless explicitly called
+
+## What's Next?
+
+In the next chapter, you'll learn about `map`—a powerful way to apply a scope to every item in a collection, enabling
+batch processing and parallel execution.
+
+But first, experiment with reusable scopes to make your workflows more modular!

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

@@ -0,0 +1,126 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates accessing specific cog outputs from a called scope.
+# It shows how to use from() with a block to extract outputs from multiple cogs,
+# and how the default return value is the final cog's output when no outputs! block is provided.
+
+config do
+  chat do
+    model "gpt-4o-mini"
+    no_show_response!
+  end
+
+  chat(:final_summary) do
+    show_response!
+  end
+end
+
+# Define a scope that processes text through multiple transformations
+# Note: No outputs! block, so the default return is the last cog's output
+execute(:process_text) do
+  chat(:extract_keywords) do |_, text|
+    <<~PROMPT
+      Extract 3-5 key words or phrases from this text, in JSON form: `{ keywords: [ ... ] }`
+      #{text}
+    PROMPT
+  end
+
+  chat(:determine_sentiment) do |_, text|
+    <<~PROMPT
+      What is the sentiment of this text? Answer with just one word: positive, negative, or neutral.
+      #{text}
+    PROMPT
+  end
+
+  chat(:generate_title) do |_, text|
+    <<~PROMPT
+      Generate a short, catchy title (5-7 words) for this text:
+      #{text}
+    PROMPT
+  end
+
+  chat(:word_count) do |_, text|
+    "Count the approximate number of words in this text and respond with just the number: #{text}"
+  end
+end
+
+# Main workflow
+execute do
+  ruby do
+    puts "=" * 70
+    puts "ACCESSING SCOPE OUTPUTS EXAMPLE"
+    puts "=" * 70
+  end
+
+  # Process a sample text
+  call(:result, run: :process_text) do
+    <<~TEXT
+      Artificial intelligence is revolutionizing software development.
+      Machine learning models can now write code, detect bugs, and
+      suggest improvements. This technology empowers developers to
+      build better software faster than ever before.
+    TEXT
+  end
+
+  # The default return value (without outputs!) is the last cog's output
+  ruby do
+    puts "\nDEFAULT RETURN VALUE (last cog in scope):"
+    word_count = from(call!(:result)).text
+    puts "Word count: #{word_count}"
+  end
+
+  # Use from() with a block to access specific cogs from the scope
+  ruby do
+    puts "\nACCESSING SPECIFIC COGS:"
+
+    # The block runs in the context of the called scope
+    # You can access any cogs defined in that scope
+    keywords, sentiment, title = from(call!(:result)) do
+      [
+        chat!(:extract_keywords).json![:keywords],
+        chat!(:determine_sentiment).text,
+        chat!(:generate_title).text,
+      ]
+    end
+
+    puts "Keywords: #{keywords.join(", ")}"
+    puts "Sentiment: #{sentiment}"
+    puts "Title: #{title}"
+  end
+
+  # Create a final summary combining the extracted information
+  chat(:final_summary) do
+    keywords, sentiment, title, word_count = from(call!(:result)) do
+      [
+        chat!(:extract_keywords).json![:keywords],
+        chat!(:determine_sentiment).text,
+        chat!(:generate_title).text,
+        chat!(:word_count).text,
+      ]
+    end
+
+    <<~PROMPT
+      Create a brief meta-summary (2-3 sentences) using this analysis:
+
+      Title: #{title}
+      Keywords: #{keywords.join(", ")}
+      Sentiment: #{sentiment}
+      Word Count: #{word_count}
+    PROMPT
+  end
+
+  ruby do
+    puts "\n" + "=" * 70
+    puts <<~NOTE
+      KEY POINTS:
+      - Without outputs!, the default return is the last cog's output
+      - Use from(call!(:name)) to access the default return value
+      - Use from(call!(:name)) { ... } with a block to access specific cogs
+      - The block runs in the context of the called scope
+      - You can extract outputs from multiple cogs in one call
+    NOTE
+  end
+end