roast-ai 1.2.0 → 1.3.0

data/lib/roast/config_manager.rb

@@ -3,15 +3,18 @@
 
 module Roast
   class ConfigManager
+    include WorkflowParamAccessors
+
     class ConfigManagerError < Roast::Error; end
     class ConfigManagerNotPreparedError < ConfigManagerError; end
     class ConfigManagerAlreadyPreparedError < ConfigManagerError; end
     class IllegalCogNameError < ConfigManagerError; end
 
-    #: (Cog::Registry, Array[^() -> void]) -> void
-    def initialize(cog_registry, config_procs)
+    #: (Cog::Registry, Array[^() -> void], WorkflowContext) -> void
+    def initialize(cog_registry, config_procs, workflow_context)
       @cog_registry = cog_registry
       @config_procs = config_procs
+      @workflow_context = workflow_context
       @config_context = ConfigContext.new #: ConfigContext
       @global_config = Cog::Config.new #: Cog::Config
       @general_configs = {} #: Hash[singleton(Cog), Cog::Config]
@@ -117,6 +120,7 @@ module Roast
       # NOTE: Sorbet expects the proc passed to instance_exec to be declared as taking an argument
       # but our cog_config_proc does not get an argument
       cog_config_proc = cog_config_proc #: as ^(untyped) -> void
+      bind_workflow_params(config_object)
       config_object.instance_exec(&cog_config_proc) if cog_config_proc
       nil
     end
@@ -134,8 +138,31 @@ module Roast
     #: (^() -> void ) -> void
     def on_global(global_config_proc)
       global_config_proc = global_config_proc #: as ^(untyped) -> void
+      bind_workflow_params(@global_config)
       @global_config.instance_exec(&global_config_proc) if global_config_proc
       nil
     end
+
+    #: (Cog::Config) -> void
+    def bind_workflow_params(object)
+      target_bang_method = method(:target!)
+      targets_method = method(:targets)
+      arg_question_method = method(:arg?)
+      args_method = method(:args)
+      kwarg_method = method(:kwarg)
+      kwarg_bang_method = method(:kwarg!)
+      kwarg_question_method = method(:kwarg?)
+      kwargs_method = method(:kwargs)
+      object.instance_eval do
+        define_singleton_method(:target!, proc { target_bang_method.call })
+        define_singleton_method(:targets, proc { targets_method.call })
+        define_singleton_method(:arg?, proc { |value| arg_question_method.call(value) })
+        define_singleton_method(:args, proc { args_method.call })
+        define_singleton_method(:kwarg, proc { |key| kwarg_method.call(key) })
+        define_singleton_method(:kwarg!, proc { |key| kwarg_bang_method.call(key) })
+        define_singleton_method(:kwarg?, proc { |key| kwarg_question_method.call(key) })
+        define_singleton_method(:kwargs, proc { kwargs_method.call })
+      end
+    end
   end
 end

data/lib/roast/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Roast
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/roast/workflow.rb

@@ -19,12 +19,15 @@ module Roast
         Sync do
           Dir.mktmpdir("roast-") do |tmpdir|
             EventMonitor.start!
-            workflow_dir = Pathname.new(workflow_path).dirname
-            workflow_context = WorkflowContext.new(params: params, tmpdir: tmpdir, workflow_dir: workflow_dir)
-            workflow = new(workflow_path, workflow_context)
-            workflow.prepare!
-            workflow.start!
-            EventMonitor.stop!
+            begin
+              workflow_dir = Pathname.new(workflow_path).dirname
+              workflow_context = WorkflowContext.new(params: params, tmpdir: tmpdir, workflow_dir: workflow_dir)
+              workflow = new(workflow_path, workflow_context)
+              workflow.prepare!
+              workflow.start!
+            ensure
+              EventMonitor.stop! if EventMonitor.running?
+            end
           end
         end
       end
@@ -48,7 +51,7 @@ module Roast
 
       @preparing = true
       extract_dsl_procs!
-      @config_manager = ConfigManager.new(@cog_registry, @config_procs)
+      @config_manager = ConfigManager.new(@cog_registry, @config_procs, @workflow_context)
       @config_manager.not_nil!.prepare!
       # TODO: probably we should just not pass the params as the top-level scope value anymore
       @execution_manager = ExecutionManager.new(@cog_registry, @config_manager.not_nil!, @execution_procs, @workflow_context, scope_value: @workflow_context.params)

data/lib/roast/workflow_param_accessors.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  # @requires_ancestor: Kernel
+  module WorkflowParamAccessors
+    private
+
+    #: () -> String
+    def target!
+      raise ArgumentError, "expected exactly one target" unless @workflow_context.params.targets.length == 1
+
+      @workflow_context.params.targets.first #: as String
+    end
+
+    #: () -> Array[String]
+    def targets
+      @workflow_context.params.targets.dup
+    end
+
+    #: (Symbol) -> bool
+    def arg?(value)
+      @workflow_context.params.args.include?(value)
+    end
+
+    #: () -> Array[Symbol]
+    def args
+      @workflow_context.params.args.dup
+    end
+
+    #: (Symbol) -> String?
+    def kwarg(key)
+      @workflow_context.params.kwargs[key]
+    end
+
+    #: (Symbol) -> String
+    def kwarg!(key)
+      raise ArgumentError, "expected keyword argument '#{key}' to be present" unless @workflow_context.params.kwargs.include?(key)
+
+      @workflow_context.params.kwargs[key] #: as String
+    end
+
+    #: (Symbol) -> bool
+    def kwarg?(key)
+      @workflow_context.params.kwargs.include?(key)
+    end
+
+    #: () -> Hash[Symbol, String]
+    def kwargs
+      @workflow_context.params.kwargs.dup
+    end
+  end
+end

data/sorbet/rbi/shims/lib/roast/cog/config.rbi

@@ -0,0 +1,251 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  class Cog
+    class Config
+      ########################################
+      #             Workflow Methods
+      ########################################
+
+      # Get the single target value passed to the workflow
+      #
+      # Returns the target when exactly one target was provided to the workflow. Raises an
+      # `ArgumentError` if the workflow was invoked with zero or multiple targets.
+      #
+      # Targets are file paths, URLs, or other identifiers passed to the workflow when it is
+      # invoked. Use this method when your workflow expects exactly one target.
+      #
+      # ### Invocation
+      # Invoke a workflow with a single target like this:
+      # ```bash
+      # roast execute my_workflow.rb my_target_file.txt
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Configure based on the single target
+      #     temperature(target!.end_with?(".md") ? 0.7 : 0.2)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `targets` - Get all targets as an array (works with any number of targets)
+      #
+      #: () -> String
+      def target!; end
+
+      # Get all targets passed to the workflow
+      #
+      # Returns an array of all targets provided to the workflow. Works with any number of targets
+      # (zero, one, or many). Targets are file paths, URLs, or other identifiers passed when the
+      # workflow is invoked.
+      #
+      # ### Invocation
+      # Invoke a workflow with multiple targets like this:
+      # ```bash
+      # roast execute my_workflow.rb target_one.txt target_two.txt
+      # ```
+      # or using shell globs like this:
+      # ```bash
+      # roast execute my_workflow.rb target_*.txt
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   map do
+      #     # Process targets in parallel when there are several
+      #     parallel! if targets.length > 3
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `target!` - Get the single target (raises an error if there isn't exactly one)
+      #
+      #: () -> Array[String]
+      def targets; end
+
+      # Check if a flag argument was passed to the workflow
+      #
+      # Returns `true` if the specified flag argument symbol was provided when the workflow
+      # was invoked, `false` otherwise.
+      #
+      # Flag arguments are symbolic flags passed to the workflow (e.g., `retry`, `force`)
+      # that enable or modify behavior.
+      #
+      # ### Invocation
+      # Invoke a workflow with flag arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- retry force
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Pick a cheaper model when invoked with the `fast` flag
+      #     model(arg?(:fast) ? "gpt-5.4-nano" : "gpt-5")
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `args` - Get all flag arguments as an array
+      # - `kwarg?` - Check for keyword arguments (key-value pairs)
+      #
+      #: (Symbol) -> bool
+      def arg?(value); end
+
+      # Get all flag arguments passed to the workflow
+      #
+      # Returns an array of all flag argument symbols provided when the workflow was invoked.
+      # Flag arguments are symbolic flags (e.g., `retry`, `force`) that enable or modify
+      # workflow behavior.
+      #
+      # ### Invocation
+      # Invoke a workflow with flag arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- retry force
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   global do
+      #     # Show full output whenever any flags were passed
+      #     display! unless args.empty?
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `arg?` - Check if a specific flag argument was provided
+      # - `kwargs` - Get all keyword arguments
+      #
+      #: () -> Array[Symbol]
+      def args; end
+
+      # Get a keyword argument value passed to the workflow
+      #
+      # Returns the string value for the specified keyword argument key, or `nil` if the key was
+      # not provided. Keyword arguments are key-value pairs passed to the workflow for configuration.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Use a provided model override, or fall back to a default
+      #     model(kwarg(:model) || "gpt-5")
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg!` - Get a keyword argument value (raises an error if not provided)
+      # - `kwarg?` - Check if a keyword argument was provided
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> String?
+      def kwarg(key); end
+
+      # Get a required keyword argument value passed to the workflow
+      #
+      # Returns the string value for the specified keyword argument key. Raises an `ArgumentError`
+      # if the key was not provided.
+      #
+      # Use this when your workflow requires a specific keyword argument to function correctly.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Require the 'model' keyword argument
+      #     model(kwarg!(:model))
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a keyword argument value (returns nil if not provided)
+      # - `kwarg?` - Check if a keyword argument was provided
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> String
+      def kwarg!(key); end
+
+      # Check if a keyword argument was passed to the workflow
+      #
+      # Returns `true` if the specified keyword argument key was provided when the workflow was
+      # invoked, `false` otherwise.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     temperature(0.9) if kwarg?(:creative)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a keyword argument value (returns nil if not provided)
+      # - `kwarg!` - Get a keyword argument value (raises an error if not provided)
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> bool
+      def kwarg?(key); end
+
+      # Get all keyword arguments passed to the workflow
+      #
+      # Returns a hash of all keyword argument key-value pairs provided when the workflow was invoked.
+      # All keys are symbols and all values are strings.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     model(kwargs[:model] || "gpt-5")
+      #     temperature(kwargs[:temperature]&.to_f || 0.3)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a single keyword argument value
+      # - `kwarg!` - Get a required keyword argument value
+      # - `kwarg?` - Check if a keyword argument was provided
+      #
+      #: () -> Hash[Symbol, String]
+      def kwargs; end
+    end
+  end
+end

data/sorbet/rbi/shims/lib/roast/config_context.rbi

@@ -141,7 +141,7 @@ module Roast
     #
     # #### Configure the agent provider
     # - `provider(symbol)` - Set the agent provider (e.g., `:claude`)
-    # - `use_default_provider!` - Use the default provider (`:claude`)
+    # - `use_default_provider!` - Use the default provider (`:pi`, or `$ROAST_DEFAULT_AGENT_PROVIDER` when set)
     #
     # #### Configure the base command used to run the coding agent
     # - `command(string_or_array)` - Set the base command for invoking the agent
@@ -151,6 +151,10 @@ module Roast
     # - `model(string)` - Set the model to use
     # - `use_default_model!` - Use the provider's default model
     #
+    # #### Configure a time limit
+    # - `timeout(seconds)` - Kill the agent and fail the cog if it runs longer than this
+    # - `no_timeout!` - Let the agent run for as long as it takes (default)
+    #
     # #### Configure the system prompt
     # - `replace_system_prompt(string)` - Completely replace the agent's default system prompt
     # - `no_replace_system_prompt!` - Don't replace the default system prompt (default)

data/tutorial/01_your_first_workflow/README.md

@@ -106,7 +106,7 @@ block:
 config do
   chat do
     model "gpt-4o-mini" # Use OpenAI's fast model
-    provider :openai # Use OpenAI (can also be :anthropic, :perplexity or :gemini)
+    provider :openai # Use OpenAI (can also be :anthropic, :perplexity, :gemini or :bedrock)
     show_prompt! # Display the prompt before sending
   end
 end
@@ -129,8 +129,9 @@ Common options you can set:
     - Anthropic: "claude-haiku-4-5" (default), "claude-sonnet-4-6", "claude-opus-4-7", etc.
     - Perplexity: "sonar" (default), "sonar-pro", "sonar-deep-research", etc.
     - Gemini: "gemini-3.1-flash-lite" (default), "gemini-3-flash-preview", "gemini-3.1-pro-preview", etc.
+    - Bedrock: "us.anthropic.claude-haiku-4-5-20251001-v1:0" (default), or any other Bedrock model or inference profile ID your account can use
 - `provider :name` - Which LLM provider
-    - `:openai`, `:anthropic`, `:perplexity` or `:gemini`
+    - `:openai`, `:anthropic`, `:perplexity`, `:gemini` or `:bedrock`
 - `show_prompt!` - Display the prompt being sent
 - `show_response!` - Display the response (on by default)
 - `show_stats!` - Display token usage statistics (on by default)

data/tutorial/01_your_first_workflow/configured_chat.rb

@@ -10,7 +10,7 @@ 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, :perplexity or :gemini)
+    provider :openai         # Use OpenAI (alternative: :anthropic, :perplexity, :gemini or :bedrock)
     show_prompt!             # Display the prompt before sending it
     show_response!           # Display the response (this is the default)
     show_stats!              # Display token usage statistics (default)

data/tutorial/02_chaining_cogs/README.md

@@ -127,8 +127,29 @@ execute do
 end
 ```
 
-The `agent` cog is backed by a locally installed coding agent -- Anthropic's Claude Code is the default provider.
-You'll need to have Claude Code installed and configured correctly for this cog to run.
+The `agent` cog is backed by a locally installed coding agent -- Pi is the default provider (set `ROAST_DEFAULT_AGENT_PROVIDER` to change it globally, e.g. to `claude`).
+You'll need to have Pi installed and configured correctly for this cog to run.
+Roast also supports Claude code, which must be set explicitly in provider or an environment variable.
+
+### Specifying a Model
+
+Use a fully-qualified `provider/model` id:
+
+```ruby
+config do
+  agent do
+    model "anthropic/claude-haiku-4-5-20251001"
+  end
+end
+```
+
+Pi requires this qualified form. Claude Code expects a bare model name, so Roast strips the leading
+`anthropic/` prefix automatically when the `:claude` provider is used. Because of this, the same `model`
+string is portable across providers -- you can switch the agent provider without rewriting it.
+
+A bare name like `"claude-haiku-4-5-20251001"` (or a shorthand like `"haiku"`) still works when you've set
+`provider :claude`, but it will fail on the default Pi provider, which can't resolve an unqualified model name.
+Prefer the qualified form unless you have a reason not to.
 
 ### When to Use Agent vs Chat
 

data/tutorial/02_chaining_cogs/code_review.rb

@@ -8,8 +8,8 @@
 
 config do
   agent do
-    model "claude-haiku-4-5-20251001"
-    provider :claude
+    model "anthropic/claude-haiku-4-5-20251001"
+    provider :pi
   end
 
   chat do

data/tutorial/02_chaining_cogs/session_resumption.rb

@@ -13,6 +13,7 @@ config do
     model "gpt-5.4-nano"
   end
   agent do
+    provider :claude
     model "haiku"
     no_display!
     show_stats!

data/tutorial/03_targets_and_params/README.md

@@ -187,6 +187,15 @@ execute do
 end
 ```
 
+Parameter accessors are also available inside cog `config` blocks and the `global` block:
+
+```ruby
+config do
+  chat { model(arg?(:fast) ? "gpt-5.4-nano" : "gpt-5") }
+  global { abort_on_failure! if arg?(:strict) }
+end
+```
+
 ## Running the Workflows
 
 To run the examples in this chapter:
@@ -220,7 +229,7 @@ bin/roast execute tutorial/03_targets_and_params/multiple_targets.rb \
 - Use `arg?(:name)` to check if an argument is present
 - Use `kwarg(:name)` to get a kwarg value (returns nil if missing)
 - Use `kwarg!(:name)` to require a kwarg (errors if missing)
-- All accessors work in any cog's input block
+- All accessors work in any cog's input block, and inside cog `config` / `global` blocks
 
 ## What's Next?
 

data/tutorial/04_configuration_options/README.md

@@ -111,6 +111,25 @@ end
 
 This is useful when you have multiple similar cogs that need the same configuration.
 
+### Configuring Based on Parameters
+
+Workflow parameter accessors (`target!`, `targets`, `arg?`, `args`, `kwarg`, `kwarg!`, `kwarg?`, `kwargs`; see Chapter 3)
+are available inside cog `config` blocks and the `global` block, so you can configure cogs based on how the workflow was
+invoked:
+
+```ruby
+config do
+  chat do
+    # Pick a cheaper model when invoked with the `fast` flag: `-- fast`
+    model(arg?(:fast) ? "gpt-5.4-nano" : "gpt-5")
+  end
+
+  global do
+    abort_on_failure! if arg?(:strict)
+  end
+end
+```
+
 ## Display Options
 
 Control what gets printed during workflow execution using display methods in your `config` block:

data/tutorial/README.md

@@ -15,7 +15,7 @@ run coding agents, process data, and so much more.
 - Ruby installed (3.4.2+)
 - Roast gem installed
 - API keys for your AI provider (see [Configuration](https://github.com/Shopify/roast/blob/main/README.md#configuration) for setup)
-- Claude Code CLI installed and configured (to use coding agents)
+- Pi CLI installed and configured for default agent examples; Claude Code CLI installed and configured for examples that set `provider :claude`
 
 ## How to Use This Tutorial
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roast-ai
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Shopify
@@ -245,6 +245,7 @@ files:
 - lib/roast/version.rb
 - lib/roast/workflow.rb
 - lib/roast/workflow_context.rb
+- lib/roast/workflow_param_accessors.rb
 - lib/roast/workflow_params.rb
 - roast-ai.gemspec
 - shipit.rubygems.yml
@@ -349,6 +350,7 @@ files:
 - sorbet/rbi/gems/vcr@6.3.1.rbi
 - sorbet/rbi/gems/webmock@3.25.1.rbi
 - sorbet/rbi/gems/zeitwerk@2.7.3.rbi
+- sorbet/rbi/shims/lib/roast/cog/config.rbi
 - sorbet/rbi/shims/lib/roast/cog_input_context.rbi
 - sorbet/rbi/shims/lib/roast/config_context.rbi
 - sorbet/rbi/shims/lib/roast/execution_context.rbi
@@ -406,7 +408,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.21
 specification_version: 4
 summary: A framework for executing structured AI workflows in Ruby
 test_files: []