roast-ai 0.4.10 → 0.5.1

data/dsl/parallel_map.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  cmd { display! }
+  map(:words) do
+    # By default, maximum parallelism is 1 and map executions will run synchronously
+    # Calling `parallel` with a larger value will allow multiple map items to be run in parallel, up to the limit given
+    # Calling `parallel!` or `parallel(0)` will allow unlimited parallelism, processing all map items in parallel
+    parallel 3
+  end
+end
+
+execute(:capitalize_a_word) do
+  cmd(:to_upper) do |_, word, index|
+    sleep(0.1) if index == 3 # "three" will be slow --> finishing second last
+    sleep(0.2) if index == 1 # "one" will be slowest --> finishing last
+    ["sh", "-c", "echo \"#{word}\" | tr '[:lower:]' '[:upper:]'"]
+  end
+end
+
+execute do
+  # Call a subroutine with `map`
+  map(:words, run: :capitalize_a_word) do |my|
+    my.items = ["one", "two", "three", "four", "five", "six"]
+    my.initial_index = 1 # for convenience, just because our items begin with "one"
+  end
+
+  cmd do |my|
+    my.command = "echo"
+    # Regardless of the order in which the items were processed by a parallel map,
+    # their results will always be provided to `collect` and `reduce` in the order in which they were given.
+    my.args << collect(map!(:words)) { cmd!(:to_upper).text }.join(", ")
+  end
+end

data/dsl/prompts/simple_prompt.md.erb

@@ -0,0 +1,3 @@
+You just told me the following about a lake. Make some stuff up about why that's nonsense.
+
+<%= lake_answer %>

data/dsl/prototype.rb

@@ -4,12 +4,8 @@
 #: self as Roast::DSL::Workflow
 
 config do
-  # TODO: make a way to do print_all on all and turn off printing on one
-  cmd(:echo) { print_all! }
-  cmd(:date) { print_stdout! }
-  chat { "" }
-  # TODO: add a way to apply config to a subset of named cog by pattern
-  # cmd(/^date.*/) { print_all! }
+  cmd(:echo) { display! }
+  cmd(/date/) { display! }
 end
 
 execute do
@@ -21,5 +17,7 @@ execute do
   cmd(:echo) { |my| my.command = "echo 'Hello World!'" }
 
   # Cogs can implement input coercion for simple return values
-  cmd(:date) { "date" }
+  fmt = "\"+%a %b %d %T %Z %Y\""
+  cmd(:date_today) { "/bin/date #{fmt}" }
+  cmd(:date_yesterday) { RUBY_PLATFORM.include?("darwin") ? "/bin/date -jv -1d #{fmt}" : "/bin/date -d '-1 day' #{fmt}" }
 end

data/dsl/repeat_loop_results.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+end
+
+execute do
+  repeat(:loop, run: :loop_body) { 7 }
+
+  ruby do
+    # You can access the final output value of a `repeat` cog directly
+    result = repeat!(:loop)
+    puts "Ultimate Loop Result: #{result.value}"
+  end
+
+  ruby do
+    puts "---"
+    # You can also access the final result, or individual cog results, of any specific iteration
+    # In the same manner as you would use `from` to access the results of a single `call` invocation.
+    puts "First Iteration Result: #{from(repeat!(:loop).first)}"
+    puts "Final Iteration Result: #{from(repeat!(:loop).last)}"
+    puts "Second-to-last Iteration Result: #{from(repeat!(:loop).iteration(-2))}"
+    # NOTE: accessing a specific iteration will raise an IndexException if the requested index is out of bounds
+    # for the number of iterations that ran.
+  end
+
+  ruby do
+    puts "---"
+    # You can access the results of all iterations in the same manner as you would use `collect` or `reduce`
+    # to access the complete results of a `map` invocation.
+    puts "All :add cog outputs: #{collect(repeat!(:loop).results) { ruby!(:add).value }}"
+    puts "Sum of :add cog output: #{reduce(repeat!(:loop).results, 0) { |acc| acc + ruby!(:add).value }}"
+  end
+end
+
+execute(:loop_body) do
+  # on each loop iteration, the input value provided will be the output value of the previous iteration
+  # the initial value will be what was provided when `repeat` was called in the outer scope.
+  ruby(:add) do |_, num, idx|
+    new_num = num + idx
+    s = "iteration #{idx}: #{num} + #{idx} -> #{new_num}"
+    puts s
+    new_num
+  end
+
+  ruby { |_, _, idx| break! if idx >= 3 }
+
+  # The value provided to `outputs` will be the input value for the next iteration
+  # On the final iteration, it will also be the `repeat` cog's own output value
+  outputs { ruby!(:add).value }
+end

data/dsl/ruby_cog.rb

@@ -0,0 +1,72 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+class MyClass
+  class << self
+    def add_stuff(a, b)
+      a + b
+    end
+  end
+end
+
+config do
+  cmd { display! }
+end
+
+execute do
+  cmd(:roast) { "echo Roast" }
+
+  # The `ruby` cog just passes the return value from its input block directly to its output.
+  # Letting you write whatever ruby code you want to generate that output
+  ruby(:whatever) do
+    # Do whatever you want in this block
+    value = cmd!(:roast).text
+    puts "Hello, #{value.upcase}"
+    puts "Calling a method: #{MyClass.add_stuff(3, 4)}"
+    # The value you return will be exposed as the .value attribute on the cog's output
+    1..5
+  end
+
+  cmd(:numbers) do |my|
+    my.command = "echo"
+    value = ruby!(:whatever).value.map { |n| n.to_s * n }
+    my.args = value
+  end
+
+  ruby(:advanced_hash_output) do
+    {
+      some_number: 7,
+      some_string: "Hello, world!",
+      multiply: proc { |a, b| a * b },
+    }
+  end
+
+  ruby do
+    result = ruby!(:advanced_hash_output) #: untyped
+
+    # If the output's `value` is a Hash, you can access its items directly from the output object
+    puts "Some Number + 1: #{result[:some_number] + 1}"
+    # You can also access its items as getter methods on the output object
+    puts "Some String to Upper: #{result.some_string.upcase}"
+    # And, if one of those items is a proc, you can call it directly on the output object
+    puts "Multiply 4 * 3: #{result.multiply(4, 3)}"
+  end
+
+  ruby(:advanced_object_output) do |my|
+    my.value = <<~STRING
+      This is a long block of test
+      Consisting of many lines
+      Three, to be precise
+    STRING
+  end
+
+  ruby do
+    result = ruby!(:advanced_object_output) #: untyped
+
+    # You can also call methods on the output's `value` directly, regardless of its type
+    puts "The long string has #{result.lines.length} lines"
+    puts "And it has #{result.length} characters"
+  end
+end

data/dsl/simple_agent.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  agent do
+    provider :claude
+    model "haiku"
+    initial_prompt "Always respond in haiku form"
+    show_prompt!
+    dump_raw_agent_messages_to "tmp/claude-messages.log"
+  end
+end
+
+execute do
+  agent { "What is the world's largest lake?" }
+end

data/dsl/simple_chat.rb

@@ -4,9 +4,23 @@
 #: self as Roast::DSL::Workflow
 
 config do
-  # ...
+  chat(:lake) { model("gpt-4o") }
+  chat(:next) { model("gpt-4o-mini") }
 end
 
 execute do
+  # Ask a question
   chat(:lake) { "What is the deepest lake?" }
+
+  # Continue the conversation (with a different model!)
+  chat(:next) do |my|
+    my.prompt = "What answer did you just give, and why?"
+    my.session = chat!(:lake).session
+  end
+
+  # Ask a question with a template prompt. You can pass variables to it as you would an ERB template
+  chat { template("dsl/prompts/simple_prompt.md.erb", { lake_answer: chat!(:lake).response }) }
+
+  # Shorthand to look up a template prompt
+  # chat { template("simple_prompt", { lake_answer: chat!(:lake).response }) }
 end

data/dsl/simple_repeat.rb

@@ -0,0 +1,29 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+end
+
+execute do
+  # You can use `repeat` to repeat an executor multiple times
+  # The executor will run forever until it breaks according to its internal logic
+  repeat(:loop, run: :loop_body) {}
+end
+
+execute(:loop_body) do
+  ruby(:one) do |_, _, idx|
+    s = "iteration #{idx}"
+    puts s
+    s
+  end
+
+  # Use `break!` to terminate the repeat loop
+  # Cogs that occur after `break!` is called will not run on the final iteration
+  ruby { |_, _, idx| break! if idx >= 3 }
+
+  # The `outputs` block will *always* run, including on the iteration in which the `break!` was issued
+  # NOTE: Be careful not to depend on the output of cogs that only run after the break point
+  outputs { |_, idx| "output of iteration #{idx}" }
+end

data/dsl/skip.rb

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+  cmd { display! }
+end
+
+execute do
+  cmd(:seconds) { "date +'%S'" }
+
+  cmd(:even) do
+    # `cmd!` output accessor bang method will raise an exception if the named cog did not complete successfully
+    seconds = cmd!(:seconds).out.to_i
+    # Use the `skip!` method in a cog's input proc to conditionally skip this cog
+    # If `skip!` is called, the input proc will immediately terminate
+    skip! if seconds.odd?
+    "echo '#{seconds} is even'"
+  end
+
+  cmd(:odd) do
+    seconds = cmd!(:seconds).out.to_i
+    skip! if seconds.even?
+    "echo '#{seconds} is odd'"
+  end
+
+  cmd do |my|
+    my.command = "echo"
+    # `cmd` output accessor non-bang method will return the cog's output or
+    # nil if the named cog did not run yet or did not complete successfully
+    my.args << "'even' cog ran" unless cmd(:even).nil?
+    # `cmd?` output accessor question method will return true/false if the cog did / did not complete successfully yet
+    my.args << "'odd' cog ran" if cmd?(:odd)
+  end
+end

data/dsl/step_communication.rb

@@ -14,9 +14,8 @@ execute do
   cmd(:ls) { "ls -al" }
   cmd(:echo) do |my|
     my.command = "echo"
-    # TODO: this is a bespoke output object for cmd, is there a generic one we can offer
-    first_line = cmd(:ls).out.split("\n").second
-    last_line = cmd(:ls).out.split("\n").last
+    first_line = cmd!(:ls).lines.second
+    last_line = cmd!(:ls).lines.last
     my.args << first_line unless first_line.blank?
     my.args << "\n---\n"
     my.args << last_line if last_line != first_line && last_line.present?

data/dsl/targets_and_params.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+end
+
+execute do
+  ruby do |_, params|
+    # Any files listed after the standard roast command-line args are collected as your workflows targets
+    # (shell globs are expanded as you would expect)
+    # e.g., `roast execute --executor=dsl dsl/targets_and_params.rb Gemfile Gemfile.lock`
+    # or, `roast execute --executor=dsl dsl/targets_and_params.rb Gemfile*`
+    puts "workflow targets: #{params.targets}"
+
+    # You can specify custom arguments for your workflow. Anything coming after `--` on the roast command
+    # line will be parsed as custom arguments.
+    # Simple word tokens are collected as `args`. Tokens in the form `key=value` are parsed into the `kwargs` hash.
+    # e.g., `roast execute --executor=dsl dsl/targets_and_params.rb Gemfile* -- foo=bar abc=pqr hello world`
+    puts "workflow args: #{params.args}" # [:hello, :world] (args are parsed as symbols)
+
+    # {abc: "pqr", foo: "bar"} (keys are parsed as symbols, values as strings)
+    # (Note: using explicit formatting for compatibility with Ruby versions < 3.4)
+    puts "workflow kwargs: {#{params.kwargs.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")}}"
+  end
+
+  # There are convenience methods to access the workflow params from any cog input context in any scope
+  ruby do
+    puts
+    # `target!` will raise an exception unless exactly one target is provided
+    # puts "Explicit target = #{target!}"
+
+    # `targets` will return the (possibly empty) array of targets
+    puts "All targets = #{targets}"
+
+    # `arg?` will return a boolean indicating whether a specific value / flag argument is present
+    puts "Argument 'foo' provided? #{arg?(:foo) ? "yes" : "no"}"
+
+    # `args` will return the (possibly empty) array of simple value / flag arguments
+    puts "All args = #{args}"
+
+    # `kwarg` will return the value associated with a specific keyword argument,
+    # or nil if that keyword argument was not provided
+    puts "Keyword argument 'name': '#{kwarg(:name)}'"
+
+    # `kwarg!` will return the value associated with a specific keyword argument,
+    # or raise an exception if that keyword argument was not provided
+    # puts "Keyword argument 'name': #{kwarg!(:name)}"
+
+    # `kwarg?` will return a boolean indicating whether a specific keyword argument was provided
+    puts "Keyword argument 'name' provided: #{kwarg?(:name) ? "yes" : "no"}"
+
+    # `kwargs` will return the (possibly empty) hash of all keyword arguments
+    # puts "All kwargs = #{kwargs}"
+  end
+end

data/dsl/temperature.rb

@@ -0,0 +1,17 @@
+# typed: false
+# frozen_string_literal: true
+
+config do
+  chat(:low_temp) do
+    temperature(0.0)
+  end
+
+  chat(:high_temp) do
+    temperature(1.0)
+  end
+end
+
+execute do
+  chat(:low_temp) { "Write a haiku about the capital of France." }
+  chat(:high_temp) { "Write a haiku about the capital of France." }
+end

data/dsl/temporary_directory.rb

@@ -0,0 +1,22 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+config do
+end
+
+execute do
+  ruby do
+    # The workflow automatically gets a temporary directory created for it
+    # unique to a single execution of the workflow, but shared across all executor scopes.
+    # This working directory will be cleaned up automatically when the workflow completes or fails.
+    puts tmpdir
+
+    # The value of `tmpdir` will always be a directory that exists
+    raise StandardError, "temporary directory does not exist" unless tmpdir.exist?
+
+    # The value of `tmpdir` will always be an absolute path
+    raise StandardError, "temporary directory is not an absolute path" unless tmpdir.absolute?
+  end
+end

data/dsl/tutorial/01_your_first_workflow/README.md

@@ -0,0 +1,179 @@
+# Chapter 1: Your First Workflow
+
+In this chapter, you'll create and run your first Roast workflow. We'll start with the absolute simplest example, then
+show you how to add basic configuration.
+
+## What You'll Learn
+
+- The basic structure of a Roast workflow file
+- How to use the `chat` cog to interact with an LLM
+- How to run workflows from the command line
+- How to configure model settings
+
+## Understanding Workflows
+
+Before we dive into code, let's understand what a Roast workflow is:
+
+**A workflow is a sequence of steps that accomplish a task.** Think of it like a recipe: you define each step in order,
+specify what inputs each step needs, and describe how they connect together.
+
+### Key Concepts
+
+- **Steps** - Individual units of work (like "analyze this code" or "summarize this text")
+- **Cogs** - The building blocks that implement step types (Roast comes with a comprehensive set of basic cogs for
+  interacting with LLMs, invoking coding agents, running shell commands, processing data, as wells as complex flow
+  control)
+- **Declarative style** - You describe *what* you want done, the inputs each step needs, and how they connect together.
+  Roast takes care of the rest
+
+For example, instead of writing code to open files, parse them, call APIs, handle errors, etc., you write:
+
+```ruby
+execute do
+  chat { "Analyze this code and suggest improvements: #{my_code}" }
+end
+```
+
+Roast handles the details. You focus on the workflow.
+
+In this chapter, we'll start with the simplest workflow: a single step using the `chat` cog. In later chapters, you'll
+learn how to invoke coding agents, run shell commands, and chain multiple steps together to build sophisticated
+workflows.
+
+## The Basics
+
+Every Roast workflow is a Ruby file that defines what work to do. The simplest workflow has just one part:
+
+1. **Execute block** - Contains the work to perform
+
+### Minimal Syntax
+
+```ruby
+execute do
+  # Your workflow goes here
+end
+```
+
+That's it! Everything happens inside the `execute do ... end` block.
+
+## Your First Chat Cog
+
+The `chat` cog sends a prompt to a cloud-based LLM and gets a response back. Here's a simplest example:
+
+```ruby
+execute do
+  chat { "Say hello!" }
+end
+```
+
+When you run this, Roast will:
+
+1. Send the prompt "Say hello!" to default LLM provider and model (OpenAI gpt-4o-mini)
+2. Wait for the response
+3. Display the response in your terminal, along with LLM usage statistics
+
+### Longer Prompts
+
+For real workflows, you'll want more detailed prompts. Use Ruby's heredoc syntax for multi-line prompts:
+
+```ruby
+execute do
+  chat do
+    <<~PROMPT
+      You are a helpful AI assistant.
+
+      Please introduce yourself and explain what Roast is in 2-3 sentences.
+      Keep your response friendly and concise.
+    PROMPT
+  end
+end
+```
+
+Or define your prompts in a template file using ERB syntax and include them in your workflow
+
+```ruby
+execute do
+  chat { template("path_to_prompt_file.md.erb", { context: }) }
+end
+```
+
+## Adding Configuration
+
+You can configure which model to use, which provider, and other settings. Configuration goes in a `config do ... end`
+block:
+
+```ruby
+config do
+  chat do
+    model "gpt-4o-mini" # Use OpenAI's fast model
+    provider :openai # Use OpenAI (can also be :anthropic)
+    show_prompt! # Display the prompt before sending
+  end
+end
+
+execute do
+  chat do
+    <<~PROMPT
+      Explain what an AI workflow is in simple terms.
+    PROMPT
+  end
+end
+```
+
+### Configuration Options
+
+Common options you can set:
+
+- `model "name"` - Which LLM model to use
+    - OpenAI: "gpt-4o", "gpt-4o-mini", "gpt-4-turbo"
+    - Anthropic: "claude-3-5-sonnet-20241022", "claude-3-5-haiku-20241022"
+- `provider :name` - Which LLM provider
+    - `:openai` or `:anthropic`
+- `show_prompt!` - Display the prompt being sent
+- `show_response!` - Display the response (on by default)
+- `show_stats!` - Display token usage statistics (on by default)
+- `no_display!` - Turn off all output (useful when you just want to pass the output to a subsequent cog)
+
+## Running the Workflows
+
+To run any workflow in this chapter:
+
+```bash
+# From the project root
+bin/roast execute --executor=dsl dsl/tutorial/01_your_first_workflow/hello.rb
+```
+
+Or the configured version:
+
+```bash
+bin/roast execute --executor=dsl dsl/tutorial/01_your_first_workflow/configured_chat.rb
+```
+
+You should see:
+
+1. The prompt being sent (if you enabled `show_prompt!`)
+2. The LLM's response
+3. Statistics about token usage
+
+## Try It Yourself
+
+1. **Run both example workflows** in this chapter
+2. **Modify the prompts** - Ask different questions
+3. **Try different models** - Change "gpt-4o-mini" to "gpt-4o" in the config
+4. **Experiment with display settings** - Try `no_show_stats!` and see what happens
+
+## Key Takeaways
+
+- The `execute do ... end` block contains your workflow logic
+- The `chat` cog sends prompts to cloud-based LLMs
+- Use `<<~PROMPT ... PROMPT` for multi-line prompts
+- The `config do ... end` block (before execute) sets up cog behavior
+- Run workflows with `bin/roast execute --executor=dsl path/to/workflow.rb`
+
+## What's Next?
+
+In the next chapter, you'll learn how to chain multiple cogs together, so the output of one becomes the input to
+another. This is where Roast becomes powerful!
+
+But first, make sure you can successfully run both workflows in this chapter. Experiment with different prompts and
+configurations until you're comfortable.

data/dsl/tutorial/01_your_first_workflow/configured_chat.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::DSL::Workflow
+
+# This workflow demonstrates how to configure chat cogs.
+# Configuration is set in a 'config' block before the 'execute' block.
+
+config do
+  # Configure all chat cogs in this workflow
+  chat do
+    model "gpt-4o-mini"      # Use OpenAI's fast, cost-effective model
+    provider :openai         # Use OpenAI (alternative: :anthropic)
+    show_prompt!             # Display the prompt before sending it
+    show_response!           # Display the response (this is the default)
+    show_stats!              # Display token usage statistics (default)
+  end
+end
+
+execute do
+  chat do
+    <<~PROMPT
+      You are a knowledgeable software development assistant.
+
+      Explain what a "workflow" is in the context of software automation,
+      using simple language that a beginner could understand.
+
+      Provide a brief example of when you might use a workflow.
+
+      Keep your response to 3-4 sentences.
+    PROMPT
+  end
+end

data/dsl/tutorial/01_your_first_workflow/hello.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+# This type annotation helps Sorbet type-check your workflow.
+# It's optional if you don't want to use Sorbet.
+#: self as Roast::DSL::Workflow
+
+# This is the simplest possible Roast workflow.
+# It sends a single prompt to a chat LLM and displays the response.
+
+config {}
+
+execute do
+  chat do
+    <<~PROMPT
+      You are a friendly AI assistant helping someone learn Roast,
+      a Ruby-based workflow system for AI tasks.
+
+      Say hello and give them one encouraging tip about learning
+      new tools. Keep it brief and friendly!
+    PROMPT
+  end
+end