roast-ai 0.4.9 → 0.5.0

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

@@ -1,6 +1,8 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 
+#: self as Roast::DSL::Workflow
+
 # How do we pass information between steps?
 # Demonstrate by passing result of a command output to another step
 
@@ -10,9 +12,12 @@ end
 
 execute do
   cmd(:ls) { "ls -al" }
-  cmd(:echo) do
-    # TODO: this is a bespoke output object for cmd, is there a generic one we can offer
-    first_line = cmd(:ls).command_output.split("\n").second
-    "echo '#{first_line}'"
+  cmd(:echo) do |my|
+    my.command = "echo"
+    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?
   end
 end

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