roast-ai 0.4.10 → 0.5.1

data/lib/roast/dsl/cogs/chat.rb

@@ -4,73 +4,76 @@
 module Roast
   module DSL
     module Cogs
+      # Chat cog for pure LLM interaction
+      #
+      # The chat cog provides pure LLM interaction without local system access. While it
+      # cannot access local files or run local tools, it can still perform complex reasoning and
+      # access any cloud-based tools and MCP servers according to the capabilities of the model and
+      # the capabilities that may be provided to it by the LLM provider.
+      #
+      # Key characteristics:
+      # - No access to local filesystem (cannot read or write local files)
+      # - Cannot run local tools or commands
+      # - Can access cloud-based tools and MCP servers provided by the LLM provider
+      # - Performs request-response interactions
+      # - Does not currently maintain conversation state across invocations (not yet implemented)
+      # - Does not currently support automatic session resumption (not yet implemented)
+      #
+      # For tasks requiring local filesystem access or locally-configured tools, use the `agent` cog instead.
       class Chat < Cog
-        class Input < Cog::Input
-          #: String?
-          attr_accessor :prompt
+        # The configuration object for this chat cog instance
+        #
+        #: Roast::DSL::Cogs::Chat::Config
+        attr_reader :config
 
-          #: () -> void
-          def initialize
-            super
-            @prompt = nil #: String?
-          end
-
-          #: () -> void
-          def validate!
-            raise Cog::Input::InvalidInputError, "'prompt' is required" unless prompt.present?
-          end
+        # Execute the chat completion with the given input and return the output
+        #
+        #: (Input) -> Output
+        def execute(input)
+          chat = ruby_llm_context.chat(
+            model: config.valid_model,
+            provider: config.valid_provider!,
+            assume_model_exists: !config.verify_model_exists?,
+          )
+          input.valid_session&.apply!(chat)
+          chat = chat.with_temperature(config.valid_temperature) if config.valid_temperature
+          num_existing_messages = chat.messages.length
 
-          #: (untyped) -> void
-          def coerce!(input_return_value)
-            if input_return_value.is_a?(String)
-              self.prompt = input_return_value
+          response = chat.ask(input.valid_prompt!)
+          chat.messages[num_existing_messages..].each do |message|
+            case message.role
+            when :user
+              puts "[USER PROMPT] #{message.content}" if config.show_prompt?
+            when :assistant
+              puts "[LLM RESPONSE] #{message.content}" if config.show_response?
+            else
+              # No other message types are expected, but let's show them if they do appear
+              # but only the user has requested some form of output
+              puts "[UNKNOWN] #{message.content}" if config.show_prompt? || config.show_response?
             end
           end
-        end
-
-        class Output < Cog::Output
-          #: String
-          attr_reader :response
-
-          #: (String response) -> void
-          def initialize(response)
-            super()
-            @response = response
+          if config.show_stats?
+            temperature = chat.instance_variable_get(:@temperature)
+            puts "[LLM STATS]"
+            puts "\tModel: #{response.model_id}"
+            puts "\tTemperature: #{format("%0.2f", temperature)}" if temperature
+            puts "\tInput Tokens: #{response.input_tokens}"
+            puts "\tOutput Tokens: #{response.output_tokens}"
           end
-        end
 
-        class Config < Cog::Config
-          #: () -> String?
-          def openai_api_key
-            @values[:openai_api_key] ||= ENV["OPENAI_API_KEY"]
-          end
-
-          #: () -> String?
-          def openai_api_base_url
-            @values[:openai_api_base_url] ||= ENV["OPENAI_API_BASE_URL"]
-          end
+          Output.new(Session.from_chat(chat), response.content)
         end
 
-        #: (Input) -> Output
-        def execute(input)
-          config = @config #: as Config
-          RubyLLM.configure do |ruby_llm_config|
-            ruby_llm_config.openai_api_key = config.openai_api_key
-            ruby_llm_config.openai_api_base = config.openai_api_base_url
-          end
-
-          chat = RubyLLM.chat
-          resp = chat.ask(input.prompt)
-          puts "Model: #{resp.model_id}"
-          puts "Role: #{resp.role}"
-          puts "Input Tokens: #{resp.input_tokens}"
-          puts "Output Tokens: #{resp.output_tokens}"
+        private
 
-          chat.messages.each do |message|
-            puts "[#{message.role.to_s.upcase}] #{message.content}"
+        # Get a RubyLLM context configured for this chat cog
+        #
+        #: () -> RubyLLM::Context
+        def ruby_llm_context
+          @ruby_llm_context ||= RubyLLM.context do |context|
+            context.openai_api_key = config.valid_api_key!
+            context.openai_api_base = config.valid_base_url
           end
-
-          Output.new(resp.content)
         end
       end
     end

data/lib/roast/dsl/cogs/cmd.rb

@@ -5,25 +5,244 @@ module Roast
   module DSL
     module Cogs
       class Cmd < Cog
+        # Configure the `cmd` cog
+        #
+        # See sorbet/rbi/shims/lib/roast/dsl/config_context.rbi for full class documentation.
+        class Config < Cog::Config
+          # Configure the cog to consider itself failed if the command returns a non-zero exit status
+          #
+          # Enabled by default. When enabled, a non-zero exit status will mark the cog as failed,
+          # which may also abort the workflow depending on the cog's `abort_on_failure` configuration.
+          #
+          # #### Inverse Methods
+          # - `no_fail_on_error!`
+          #
+          # #### See Also
+          # - `fail_on_error?`
+          # - `abort_on_failure!`
+          #
+          #: () -> void
+          def fail_on_error!
+            @values[:fail_on_error] = true
+          end
+
+          # Configure the cog __not__ to consider itself failed if the command returns a non-zero exit status
+          #
+          # When disabled, the cog will complete successfully regardless of the command's exit status.
+          # The exit status will still be available in the output for inspection.
+          #
+          # #### Inverse Methods
+          # - `fail_on_error!`
+          #
+          # #### See Also
+          # - `fail_on_error?`
+          #
+          #: () -> void
+          def no_fail_on_error!
+            @values[:fail_on_error] = false
+          end
+
+          # Check if the cog is configured to fail when the command returns a non-zero exit status
+          #
+          # #### See Also
+          # - `fail_on_error!`
+          # - `no_fail_on_error!`
+          #
+          #: () -> bool
+          def fail_on_error?
+            @values[:fail_on_error] != false
+          end
+
+          # Configure the cog to write STDOUT to the console
+          #
+          # Disabled by default.
+          #
+          # #### See Also
+          # - `no_show_stdout!`
+          # - `show_stdout?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_stdout!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = true
+          end
+
+          # Configure the cog __not__ to write STDOUT to the console
+          #
+          # #### See Also
+          # - `show_stdout!`
+          # - `show_stdout?`
+          # - `no_display!`
+          #
+          #: () -> void
+          def no_show_stdout!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = false
+          end
+
+          # Check if the cog is configured to write STDOUT to the console
+          #
+          # #### See Also
+          # - `show_stdout!`
+          # - `no_show_stdout!`
+          #
+          #: () -> bool
+          def show_stdout?
+            !!@values[:show_stdout]
+          end
+
+          # Configure the cog to write STDERR to the console
+          #
+          # Disabled by default.
+          #
+          # #### See Also
+          # - `no_show_stderr!`
+          # - `show_stderr?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_stderr!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stderr] = true
+          end
+
+          # Configure the cog __not__ to write STDERR to the console
+          #
+          # #### See Also
+          # - `show_stderr!`
+          # - `show_stderr?`
+          # - `no_display!`
+          #
+          #: () -> void
+          def no_show_stderr!
+            raise "⚠️ DEPRECATION: use #{__callee__.to_s.sub("print_", "show_")} instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stderr] = false
+          end
+
+          # Check if the cog is configured to write STDERR to the console
+          #
+          # #### See Also
+          # - `show_stderr!`
+          # - `no_show_stderr!`
+          #
+          #: () -> bool
+          def show_stderr?
+            !!@values[:show_stderr]
+          end
+
+          # Configure the cog to write both STDOUT and STDERR to the console
+          #
+          # #### Alias Methods
+          # - `display!`
+          # - `print_all!`
+          #
+          # #### See Also
+          # - `no_display!`
+          # - `show_stdout!`
+          # - `show_stderr!`
+          #
+          #: () -> void
+          def display!
+            raise "⚠️ DEPRECATION: use display! instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = true
+            @values[:show_stderr] = true
+          end
+
+          # Configure the cog to write __no output__ to the console, neither STDOUT nor STDERR
+          #
+          # #### Alias Methods
+          # - `no_display!`
+          # - `print_none!`
+          # - `quiet!`
+          #
+          # #### See Also
+          # - `display!`
+          # - `no_show_stdout!`
+          # - `no_show_stderr!`
+          #
+          #: () -> void
+          def no_display!
+            raise "⚠️ DEPRECATION: use no_display! instead of #{__callee__}" if __callee__.to_s.include?("print_")
+
+            @values[:show_stdout] = false
+            @values[:show_stderr] = false
+          end
+
+          # Check if the cog is configured to display any output while running
+          #
+          # #### See Also
+          # - `display!`
+          # - `no_display!`
+          # - `show_stdout?`
+          # - `show_stderr?`
+          #
+          #: () -> bool
+          def display?
+            show_stdout? || show_stderr?
+          end
+
+          alias_method(:quiet!, :no_display!)
+          alias_method(:print_all!, :display!)
+          alias_method(:print_none!, :no_display!)
+          alias_method(:print_stdout!, :show_stdout!)
+          alias_method(:no_print_stdout!, :no_show_stdout!)
+          alias_method(:print_stderr!, :show_stderr!)
+          alias_method(:no_print_stderr!, :no_show_stderr!)
+        end
+
+        # Input specification for the cmd cog
+        #
+        # The cmd cog requires a command to execute, optionally with arguments.
+        # The command will be executed in the configured working directory.
         class Input < Cog::Input
+          # The command to execute
+          #
           #: String?
           attr_accessor :command
 
+          # Arguments to pass to the command
+          #
           #: Array[String]
           attr_accessor :args
 
+          # Data to pass to command's standard input
+          #
+          #: String?
+          attr_accessor :stdin
+
           #: () -> void
           def initialize
             super
-            @command = nil
             @args = []
           end
 
+          # Validate that the input has all required parameters
+          #
+          # This method ensures that a command has been provided before the cmd cog executes.
+          #
+          # #### See Also
+          # - `coerce`
+          #
           #: () -> void
           def validate!
             raise Cog::Input::InvalidInputError, "'command' is required" unless command.present?
           end
 
+          # Coerce the input from the return value of the input block
+          #
+          # If the input block returns a String, it will be used as the command value.
+          # If the input block returns an Array, the first element will be used as the command
+          # and the remaining elements will be used as arguments.
+          #
+          # #### See Also
+          # - `validate!`
+          #
           #: (String | Array[untyped]) -> void
           def coerce(input_return_value)
             case input_return_value
@@ -37,13 +256,27 @@ module Roast
           end
         end
 
+        # Output from running the cmd cog
+        #
+        # Contains the standard output, standard error, and exit status from the executed command.
+        # Includes JSON and text parsing capabilities via `WithJson` and `WithText` modules.
         class Output < Cog::Output
+          include Cog::Output::WithJson
+          include Cog::Output::WithNumber
+          include Cog::Output::WithText
+
+          # The standard output (STDOUT) from the command
+          #
           #: String
           attr_reader :out
 
+          # The standard error (STDERR) from the command
+          #
           #: String
           attr_reader :err
 
+          # The exit status of the command process
+          #
           #: Process::Status
           attr_reader :status
 
@@ -54,77 +287,34 @@ module Roast
             @err = err #: String
             @status = status #: Process::Status
           end
-        end
 
-        class Config < Cog::Config
-          #: () -> void
-          def print_all!
-            @values[:print_stdout] = true
-            @values[:print_stderr] = true
-          end
+          private
 
-          #: () -> void
-          def print_stdout!
-            @values[:print_stdout] = true
-          end
-
-          #: () -> void
-          def print_stderr!
-            @values[:print_stderr] = true
-          end
-
-          #: () -> bool
-          def print_stdout?
-            !!@values[:print_stdout]
-          end
-
-          #: () -> bool
-          def print_stderr?
-            !!@values[:print_stderr]
-          end
-
-          #: () -> void
-          def display!
-            print_all!
+          def raw_text
+            out
           end
         end
 
         #: (Input) -> Output
         def execute(input)
           config = @config #: as Config
-          result = T.unsafe(Roast::Helpers::CmdRunner).popen3(input.command, *input.args) do |stdin, stdout, stderr, wait_thread|
-            stdin.close
-            command_output = ""
-            command_error = ""
-
-            # Thread to read and accumulate stdout
-            stdout_thread = Thread.new do
-              stdout.each_line do |line|
-                command_output += line
-                $stdout.puts(line) if config.print_stdout?
-              end
-            rescue IOError => e
-              Roast::Helpers::Logger.debug("IOError while reading stdout: #{e.message}")
-            end
-
-            # Thread to read and accumulate stderr
-            stderr_thread = Thread.new do
-              stderr.each_line do |line|
-                command_error += line
-                $stderr.puts(line) if config.print_stderr?
-              end
-            rescue IOError => e
-              Roast::Helpers::Logger.debug("IOError while reading stderr: #{e.message}")
-            end
 
-            # Wait for threads to finish
-            stdout_thread.join
-            stderr_thread.join
+          stdout_handler = config.show_stdout? ? ->(line) { $stdout.print(line) } : nil
+          stderr_handler = config.show_stderr? ? ->(line) { $stderr.print(line) } : nil
 
-            [command_output, command_error, wait_thread.value]
-          end #: as [String, String, Process::Status]
+          stdout, stderr, status = CommandRunner #: as untyped
+            .execute(
+              [input.command] + input.args,
+              working_directory: config.valid_working_directory,
+              stdin_content: input.stdin,
+              stdout_handler: stdout_handler,
+              stderr_handler: stderr_handler,
+            )
+          if !status.success? && config.fail_on_error?
+            raise ControlFlow::FailCog, "Process exited with status code #{status.exitstatus}"
+          end
 
-          Output.new(*result)
+          Output.new(stdout, stderr, status)
         end
       end
     end

data/lib/roast/dsl/cogs/ruby.rb

@@ -0,0 +1,171 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Ruby < Cog
+        class Config < Cog::Config; end
+
+        # Input specification for the ruby cog
+        #
+        # The ruby cog accepts any Ruby value from the input block, which will be directly
+        # passed through to the output without modification.
+        class Input < Cog::Input
+          # The value to pass through to the output
+          #
+          # This value will be directly returned as the `value` attribute on the cog's output object.
+          #
+          #: untyped
+          attr_accessor :value
+
+          # Validate that the input has all required parameters
+          #
+          # This method ensures that a value has been provided, either directly via the `value`
+          # attribute or through the input block (via `coerce`).
+          #
+          # #### See Also
+          # - `coerce`
+          #
+          #: () -> void
+          def validate!
+            raise Cog::Input::InvalidInputError if value.nil? && !coerce_ran?
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # The return value from the input block will be used directly as the `value` attribute.
+          # This allows any Ruby object to be passed through the ruby cog.
+          #
+          # #### See Also
+          # - `validate!`
+          #
+          #: (untyped) -> void
+          def coerce(input_return_value)
+            super
+            @value = input_return_value
+          end
+        end
+
+        # Output from running the ruby cog
+        #
+        # Contains the value that was provided to the input block, passed through unchanged.
+        # This allows Ruby values to be used directly in workflow steps.
+        #
+        # The output provides convenient dynamic method dispatch with the following priority:
+        # 1. If the value object responds to a method, it delegates to that method
+        # 2. If the value is a Hash, methods correspond to hash keys
+        # 3. Hash values that are Procs can be called directly as methods
+        #
+        # Additional conveniences:
+        # - Use `[]` for direct hash key access when the value is a Hash
+        # - Use `call()` to invoke the value if it's a Proc, or to call a Proc stored in a Hash
+        class Output < Cog::Output
+          # The value passed through from the input
+          #
+          #: untyped
+          attr_reader :value
+
+          #: (untyped) -> void
+          def initialize(value)
+            super()
+            @value = value
+          end
+
+          # Access a hash key directly when the value is a Hash
+          #
+          # Provides direct bracket notation access to hash keys without going through
+          # method dispatch. This is useful when you need explicit hash key access.
+          #
+          # #### See Also
+          # - `call`
+          # - `method_missing`
+          #
+          #: (Symbol) -> untyped
+          def [](key)
+            value[key]
+          end
+
+          # Call the value as a Proc, or call a Proc stored in a Hash
+          #
+          # This method provides two calling patterns:
+          # - If the value is a Proc, calls it directly with the provided arguments
+          # - If the value is a Hash, expects the first argument to be a Symbol key, retrieves
+          #   the Proc at that key, and calls it with the remaining arguments
+          #
+          # Raises `ArgumentError` if called on a Hash without a Symbol key.
+          # Raises `NoMethodError` if the Hash key doesn't contain a Proc.
+          #
+          # #### See Also
+          # - `[]`
+          # - `method_missing`
+          #
+          #: (*untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+          def call(*args, **kwargs, &blk)
+            return value.call(*args, **kwargs, &blk) if value.is_a?(Proc)
+
+            key = args.first
+            raise ArgumentError unless key.is_a?(Symbol)
+
+            proc = value[key]
+            raise NoMethodError, key unless proc.is_a?(Proc)
+
+            proc = proc #: as untyped
+            proc.call(*args, **kwargs, &blk)
+          end
+
+          # Handle dynamic method calls with intelligent dispatch
+          #
+          # This method implements a multi-level dispatch strategy:
+          #
+          # 1. **Value delegation**: If the value object responds to the method, delegates directly to it.
+          #    This allows calling methods like `lines`, `length`, `upcase` on String values, or any
+          #    method on the underlying object.
+          #
+          # 2. **Hash key access**: If the value is a Hash and contains the method name as a key,
+          #    returns the value at that key. If the value is a Proc, calls it with the provided arguments.
+          #
+          # 3. **Fallback**: If neither condition is met, calls `super` to trigger standard Ruby behavior.
+          #
+          # #### See Also
+          # - `respond_to_missing?`
+          # - `[]`
+          # - `call`
+          #
+          #: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+          def method_missing(name, *args, **kwargs, &blk)
+            return value.public_send(name, *args, **kwargs, &blk) if value.respond_to?(name, false)
+            return super unless value.is_a?(Hash) && value.key?(name)
+
+            if value[name].is_a?(Proc)
+              proc = value[name] #: as untyped
+              proc.call(*args, **kwargs, &blk)
+            else
+              value[name]
+            end
+          end
+
+          # Check if a dynamic method should respond
+          #
+          # Returns `true` if any of the following conditions are met:
+          # 1. The value object responds to the method
+          # 2. The value is a Hash and contains the method name as a key
+          # 3. The parent class would respond to the method
+          #
+          # #### See Also
+          # - `method_missing`
+          #
+          #: (Symbol | String, ?bool) -> bool
+          def respond_to_missing?(name, include_private = false)
+            value.respond_to?(name, false) || value.is_a?(Hash) && value.key?(name) || super
+          end
+        end
+
+        #: (Input) -> Output
+        def execute(input)
+          Output.new(input.value)
+        end
+      end
+    end
+  end
+end