langchainrb 0.17.1 → 0.19.0

data/lib/langchain/assistant/messages/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class Base
+        attr_reader :role,
+          :content,
+          :image_url,
+          :tool_calls,
+          :tool_call_id
+
+        # Check if the message came from a user
+        #
+        # @return [Boolean] true/false whether the message came from a user
+        def user?
+          role == "user"
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @raise NotImplementedError if the subclass does not implement this method
+        def llm?
+          raise NotImplementedError, "Class #{self.class.name} must implement the method 'llm?'"
+        end
+
+        # Check if the message is a tool call
+        #
+        # @raise NotImplementedError if the subclass does not implement this method
+        def tool?
+          raise NotImplementedError, "Class #{self.class.name} must implement the method 'tool?'"
+        end
+
+        # Check if the message is a system prompt
+        #
+        # @raise NotImplementedError if the subclass does not implement this method
+        def system?
+          raise NotImplementedError, "Class #{self.class.name} must implement the method 'system?'"
+        end
+
+        # Returns the standardized role symbol based on the specific role methods
+        #
+        # @return [Symbol] the standardized role symbol (:system, :llm, :tool, :user, or :unknown)
+        def standard_role
+          return :user if user?
+          return :llm if llm?
+          return :tool if tool?
+          return :system if system?
+
+          # TODO: Should we return :unknown or raise an error?
+          :unknown
+        end
+      end
+    end
+  end
+end

data/lib/langchain/assistant/messages/google_gemini_message.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class GoogleGeminiMessage < Base
+        # Google Gemini uses the following roles:
+        ROLES = [
+          "user",
+          "model",
+          "function"
+        ].freeze
+
+        TOOL_ROLE = "function"
+
+        # Initialize a new Google Gemini message
+        #
+        # @param role [String] The role of the message
+        # @param content [String] The content of the message
+        # @param tool_calls [Array<Hash>] The tool calls made in the message
+        # @param tool_call_id [String] The ID of the tool call
+        def initialize(role:, content: nil, tool_calls: [], tool_call_id: nil)
+          raise ArgumentError, "Role must be one of #{ROLES.join(", ")}" unless ROLES.include?(role)
+          raise ArgumentError, "Tool calls must be an array of hashes" unless tool_calls.is_a?(Array) && tool_calls.all? { |tool_call| tool_call.is_a?(Hash) }
+
+          @role = role
+          # Some Tools return content as a JSON hence `.to_s`
+          @content = content.to_s
+          @tool_calls = tool_calls
+          @tool_call_id = tool_call_id
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def llm?
+          model?
+        end
+
+        # Convert the message to a Google Gemini API-compatible hash
+        #
+        # @return [Hash] The message as a Google Gemini API-compatible hash
+        def to_hash
+          {}.tap do |h|
+            h[:role] = role
+            h[:parts] = if function?
+              [{
+                functionResponse: {
+                  name: tool_call_id,
+                  response: {
+                    name: tool_call_id,
+                    content: content
+                  }
+                }
+              }]
+            elsif tool_calls.any?
+              tool_calls
+            else
+              [{text: content}]
+            end
+          end
+        end
+
+        # Google Gemini does not implement system prompts
+        def system?
+          false
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def tool?
+          function?
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def function?
+          role == "function"
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def model?
+          role == "model"
+        end
+      end
+    end
+  end
+end

data/lib/langchain/assistant/messages/mistral_ai_message.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class MistralAIMessage < Base
+        # MistralAI uses the following roles:
+        ROLES = [
+          "system",
+          "assistant",
+          "user",
+          "tool"
+        ].freeze
+
+        TOOL_ROLE = "tool"
+
+        # Initialize a new MistralAI message
+        #
+        # @param role [String] The role of the message
+        # @param content [String] The content of the message
+        # @param image_url [String] The URL of the image
+        # @param tool_calls [Array<Hash>] The tool calls made in the message
+        # @param tool_call_id [String] The ID of the tool call
+        def initialize(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil) # TODO: Implement image_file: reference (https://platform.openai.com/docs/api-reference/messages/object#messages/object-content)
+          raise ArgumentError, "Role must be one of #{ROLES.join(", ")}" unless ROLES.include?(role)
+          raise ArgumentError, "Tool calls must be an array of hashes" unless tool_calls.is_a?(Array) && tool_calls.all? { |tool_call| tool_call.is_a?(Hash) }
+
+          @role = role
+          # Some Tools return content as a JSON hence `.to_s`
+          @content = content.to_s
+          # Make sure you're using the Pixtral model if you want to send image_url
+          @image_url = image_url
+          @tool_calls = tool_calls
+          @tool_call_id = tool_call_id
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def llm?
+          assistant?
+        end
+
+        # Convert the message to an MistralAI API-compatible hash
+        #
+        # @return [Hash] The message as an MistralAI API-compatible hash
+        def to_hash
+          if assistant?
+            assistant_hash
+          elsif system?
+            system_hash
+          elsif tool?
+            tool_hash
+          elsif user?
+            user_hash
+          end
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def assistant?
+          role == "assistant"
+        end
+
+        # Check if the message are system instructions
+        #
+        # @return [Boolean] true/false whether this message are system instructions
+        def system?
+          role == "system"
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def tool?
+          role == "tool"
+        end
+
+        # Convert the message to an MistralAI API-compatible hash
+        # @return [Hash] The message as an MistralAI API-compatible hash, with the role as "assistant"
+        def assistant_hash
+          {
+            role: "assistant",
+            content: content,
+            tool_calls: tool_calls,
+            prefix: false
+          }
+        end
+
+        # Convert the message to an MistralAI API-compatible hash
+        # @return [Hash] The message as an MistralAI API-compatible hash, with the role as "system"
+        def system_hash
+          {
+            role: "system",
+            content: build_content_array
+          }
+        end
+
+        # Convert the message to an MistralAI API-compatible hash
+        # @return [Hash] The message as an MistralAI API-compatible hash, with the role as "tool"
+        def tool_hash
+          {
+            role: "tool",
+            content: content,
+            tool_call_id: tool_call_id
+          }
+        end
+
+        # Convert the message to an MistralAI API-compatible hash
+        # @return [Hash] The message as an MistralAI API-compatible hash, with the role as "user"
+        def user_hash
+          {
+            role: "user",
+            content: build_content_array
+          }
+        end
+
+        # Builds the content value for the message hash
+        # @return [Array<Hash>] An array of content hashes, with keys :type and :text or :image_url.
+        def build_content_array
+          content_details = []
+
+          if content && !content.empty?
+            content_details << {
+              type: "text",
+              text: content
+            }
+          end
+
+          if image_url
+            content_details << {
+              type: "image_url",
+              image_url: image_url
+            }
+          end
+
+          content_details
+        end
+      end
+    end
+  end
+end

data/lib/langchain/assistant/messages/ollama_message.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class OllamaMessage < Base
+        # OpenAI uses the following roles:
+        ROLES = [
+          "system",
+          "assistant",
+          "user",
+          "tool"
+        ].freeze
+
+        TOOL_ROLE = "tool"
+
+        # Initialize a new OpenAI message
+        #
+        # @param role [String] The role of the message
+        # @param content [String] The content of the message
+        # @param tool_calls [Array<Hash>] The tool calls made in the message
+        # @param tool_call_id [String] The ID of the tool call
+        def initialize(role:, content: nil, tool_calls: [], tool_call_id: nil)
+          raise ArgumentError, "Role must be one of #{ROLES.join(", ")}" unless ROLES.include?(role)
+          raise ArgumentError, "Tool calls must be an array of hashes" unless tool_calls.is_a?(Array) && tool_calls.all? { |tool_call| tool_call.is_a?(Hash) }
+
+          @role = role
+          # Some Tools return content as a JSON hence `.to_s`
+          @content = content.to_s
+          @tool_calls = tool_calls
+          @tool_call_id = tool_call_id
+        end
+
+        # Convert the message to an OpenAI API-compatible hash
+        #
+        # @return [Hash] The message as an OpenAI API-compatible hash
+        def to_hash
+          {}.tap do |h|
+            h[:role] = role
+            h[:content] = content if content # Content is nil for tool calls
+            h[:tool_calls] = tool_calls if tool_calls.any?
+            h[:tool_call_id] = tool_call_id if tool_call_id
+          end
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def llm?
+          assistant?
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def assistant?
+          role == "assistant"
+        end
+
+        # Check if the message are system instructions
+        #
+        # @return [Boolean] true/false whether this message are system instructions
+        def system?
+          role == "system"
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def tool?
+          role == "tool"
+        end
+      end
+    end
+  end
+end

data/lib/langchain/assistant/messages/openai_message.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class OpenAIMessage < Base
+        # OpenAI uses the following roles:
+        ROLES = [
+          "system",
+          "assistant",
+          "user",
+          "tool"
+        ].freeze
+
+        TOOL_ROLE = "tool"
+
+        # Initialize a new OpenAI message
+        #
+        # @param role [String] The role of the message
+        # @param content [String] The content of the message
+        # @param image_url [String] The URL of the image
+        # @param tool_calls [Array<Hash>] The tool calls made in the message
+        # @param tool_call_id [String] The ID of the tool call
+        def initialize(
+          role:,
+          content: nil,
+          image_url: nil,
+          tool_calls: [],
+          tool_call_id: nil
+        )
+          raise ArgumentError, "Role must be one of #{ROLES.join(", ")}" unless ROLES.include?(role)
+          raise ArgumentError, "Tool calls must be an array of hashes" unless tool_calls.is_a?(Array) && tool_calls.all? { |tool_call| tool_call.is_a?(Hash) }
+
+          @role = role
+          # Some Tools return content as a JSON hence `.to_s`
+          @content = content.to_s
+          @image_url = image_url
+          @tool_calls = tool_calls
+          @tool_call_id = tool_call_id
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def llm?
+          assistant?
+        end
+
+        # Convert the message to an OpenAI API-compatible hash
+        #
+        # @return [Hash] The message as an OpenAI API-compatible hash
+        def to_hash
+          {}.tap do |h|
+            h[:role] = role
+
+            if tool_calls.any?
+              h[:tool_calls] = tool_calls
+            else
+              h[:tool_call_id] = tool_call_id if tool_call_id
+
+              h[:content] = []
+
+              if content && !content.empty?
+                h[:content] << {
+                  type: "text",
+                  text: content
+                }
+              end
+
+              if image_url
+                h[:content] << {
+                  type: "image_url",
+                  image_url: {
+                    url: image_url
+                  }
+                }
+              end
+            end
+          end
+        end
+
+        # Check if the message came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def assistant?
+          role == "assistant"
+        end
+
+        # Check if the message are system instructions
+        #
+        # @return [Boolean] true/false whether this message are system instructions
+        def system?
+          role == "system"
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def tool?
+          role == "tool"
+        end
+      end
+    end
+  end
+end

data/lib/langchain/{assistants/assistant.rb → assistant.rb}

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "llm/adapter"
-
 module Langchain
   # Assistants are Agent-like objects that leverage helpful instructions, LLMs, tools and knowledge to respond to user queries.
   # Assistants can be configured with an LLM of your choice, any vector search database and easily extended with additional tools.
@@ -14,9 +12,19 @@ module Langchain
   #       tools: [Langchain::Tool::NewsRetriever.new(api_key: ENV["NEWS_API_KEY"])]
   #     )
   class Assistant
-    attr_reader :llm, :instructions, :state, :llm_adapter, :tool_choice
-    attr_reader :total_prompt_tokens, :total_completion_tokens, :total_tokens, :messages
-    attr_accessor :tools, :add_message_callback
+    attr_reader :llm,
+      :instructions,
+      :state,
+      :llm_adapter,
+      :messages,
+      :tool_choice,
+      :total_prompt_tokens,
+      :total_completion_tokens,
+      :total_tokens
+
+    attr_accessor :tools,
+      :add_message_callback,
+      :parallel_tool_calls
 
     # Create a new assistant
     #
@@ -24,12 +32,15 @@ module Langchain
     # @param tools [Array<Langchain::Tool::Base>] Tools that the assistant has access to
     # @param instructions [String] The system instructions
     # @param tool_choice [String] Specify how tools should be selected. Options: "auto", "any", "none", or <specific function name>
-    # @params add_message_callback [Proc] A callback function (Proc or lambda) that is called when any message is added to the conversation
+    # @param parallel_tool_calls [Boolean] Whether or not to run tools in parallel
+    # @param messages [Array<Langchain::Assistant::Messages::Base>] The messages
+    # @param add_message_callback [Proc] A callback function (Proc or lambda) that is called when any message is added to the conversation
     def initialize(
       llm:,
       tools: [],
       instructions: nil,
       tool_choice: "auto",
+      parallel_tool_calls: true,
       messages: [],
       add_message_callback: nil,
       &block
@@ -49,18 +60,15 @@ module Langchain
 
       self.messages = messages
       @tools = tools
+      @parallel_tool_calls = parallel_tool_calls
       self.tool_choice = tool_choice
-      @instructions = instructions
+      self.instructions = instructions
       @block = block
       @state = :ready
 
       @total_prompt_tokens = 0
       @total_completion_tokens = 0
       @total_tokens = 0
-
-      # The first message in the messages array should be the system instructions
-      # For Google Gemini, and Anthropic system instructions are added to the `system:` param in the `chat` method
-      initialize_instructions
     end
 
     # Add a user message to the messages array
@@ -104,7 +112,7 @@ module Langchain
     # @param messages [Array<Langchain::Message>] The messages to set
     # @return [Array<Langchain::Message>] The messages
     def messages=(messages)
-      raise ArgumentError, "messages array must only contain Langchain::Message instance(s)" unless messages.is_a?(Array) && messages.all? { |m| m.is_a?(Langchain::Messages::Base) }
+      raise ArgumentError, "messages array must only contain Langchain::Message instance(s)" unless messages.is_a?(Array) && messages.all? { |m| m.is_a?(Messages::Base) }
 
       @messages = messages
     end
@@ -167,10 +175,8 @@ module Langchain
     # @param output [String] The output of the tool
     # @return [Array<Langchain::Message>] The messages
     def submit_tool_output(tool_call_id:, output:)
-      tool_role = determine_tool_role
-
       # TODO: Validate that `tool_call_id` is valid by scanning messages and checking if this tool call ID was invoked
-      add_message(role: tool_role, content: output, tool_call_id: tool_call_id)
+      add_message(role: @llm_adapter.tool_role, content: output, tool_call_id: tool_call_id)
     end
 
     # Delete all messages
@@ -181,9 +187,6 @@ module Langchain
       @messages = []
     end
 
-    # TODO: Remove in the next major release
-    alias_method :clear_thread!, :clear_messages!
-
     # Set new instructions
     #
     # @param new_instructions [String] New instructions that will be set as a system message
@@ -191,11 +194,8 @@ module Langchain
     def instructions=(new_instructions)
       @instructions = new_instructions
 
-      # This only needs to be done that support Message#@role="system"
-      if !llm.is_a?(Langchain::LLM::GoogleGemini) &&
-          !llm.is_a?(Langchain::LLM::GoogleVertexAI) &&
-          !llm.is_a?(Langchain::LLM::Anthropic)
-        # Find message with role: "system" in messages and delete it from the messages array
+      if @llm_adapter.support_system_message?
+        # TODO: Should we still set a system message even if @instructions is "" or nil?
         replace_system_message!(content: new_instructions)
       end
     end
@@ -217,6 +217,7 @@ module Langchain
     # @return [Array<Langchain::Message>] The messages
     def replace_system_message!(content:)
       messages.delete_if(&:system?)
+      return if content.nil?
 
       message = build_message(role: "system", content: content)
       messages.unshift(message)
@@ -330,30 +331,6 @@ module Langchain
       :failed
     end
 
-    # Determine the tool role based on the LLM type
-    #
-    # @return [String] The tool role
-    def determine_tool_role
-      case llm
-      when Langchain::LLM::Anthropic
-        Langchain::Messages::AnthropicMessage::TOOL_ROLE
-      when Langchain::LLM::GoogleGemini, Langchain::LLM::GoogleVertexAI
-        Langchain::Messages::GoogleGeminiMessage::TOOL_ROLE
-      when Langchain::LLM::MistralAI
-        Langchain::Messages::MistralAIMessage::TOOL_ROLE
-      when Langchain::LLM::Ollama
-        Langchain::Messages::OllamaMessage::TOOL_ROLE
-      when Langchain::LLM::OpenAI
-        Langchain::Messages::OpenAIMessage::TOOL_ROLE
-      end
-    end
-
-    def initialize_instructions
-      if llm.is_a?(Langchain::LLM::OpenAI) || llm.is_a?(Langchain::LLM::MistralAI)
-        self.instructions = @instructions if @instructions
-      end
-    end
-
     # Call to the LLM#chat() method
     #
     # @return [Langchain::LLM::BaseResponse] The LLM response object
@@ -364,7 +341,8 @@ module Langchain
         instructions: @instructions,
         messages: array_of_message_hashes,
         tools: @tools,
-        tool_choice: tool_choice
+        tool_choice: tool_choice,
+        parallel_tool_calls: parallel_tool_calls
       )
       @llm.chat(**params, &@block)
     end

data/lib/langchain/llm/ai21.rb

@@ -8,7 +8,7 @@ module Langchain::LLM
   #   gem "ai21", "~> 0.2.1"
   #
   # Usage:
-  #     ai21 = Langchain::LLM::AI21.new(api_key: ENV["AI21_API_KEY"])
+  #     llm = Langchain::LLM::AI21.new(api_key: ENV["AI21_API_KEY"])
   #
   class AI21 < Base
     DEFAULTS = {