langchainrb 0.17.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7061ef2090d35626239ca575b60edb291dbbadab7de85a5a2796792e1691437
-  data.tar.gz: 30cb1f14b602a22e7df8f2dba42660383d44482cbe83fb35dc9539afa836739c
+  metadata.gz: 89fdd6c82d689f6e7057133eab08ef8367e72e211d3a59df423ce26cd3b2c04d
+  data.tar.gz: e77493aec62198a014b0296490779b18016407c1808de45020e25b63a8d42d17
 SHA512:
-  metadata.gz: dd08fb29bd0ff9237cc27980c3bac607baeb9d54a93f297b1e81fb863b7cbb9720db4adacb3dae92bcbe71d2eb59b38d4de0ee321face467a0b82bde627d2929
-  data.tar.gz: 4a3661afd2d9d75a64e02f6f173cd0bf0e016207c444ca4506bab907f00dc906f5bbf82c96aad9521280265f214b0f3e82dd5e4ee54dc40f3afb415a6f50b365
+  metadata.gz: 9040755869f6cbf666f8ec1225b976d095a809915c533e8102b281bc8c66d4751e93abbef19a4c27d806e5abd9555690a4d89401e7d06c29d8e4e9b6252bff4f
+  data.tar.gz: 23287eb713d76ed824e13e4b2e07e66f342a08177b39b7fa2d6fb85af25f3f0ed2bc898d6b1316c2859963526f7cf1e635c413a8786ae671399ff50b87697f82

data/CHANGELOG.md

@@ -1,5 +1,35 @@
+# CHANGELOG
+
+## Key
+- [BREAKING]: A breaking change. After an upgrade, your app may need modifications to keep working correctly.
+- [FEATURE]: A non-breaking improvement to the app. Either introduces new functionality, or improves on an existing feature.
+- [BUGFIX]: Fixes a bug with a non-breaking change.
+- [COMPAT]: Compatibility improvements - changes to make Administrate more compatible with different dependency versions.
+- [OPTIM]: Optimization or performance increase.
+- [DOCS]: Documentation changes. No changes to the library's behavior.
+- [SECURITY]: A change which fixes a security vulnerability.
+
 ## [Unreleased]
 
+## [0.19.0] - 2024-10-23
+- [BREAKING] [https://github.com/patterns-ai-core/langchainrb/pull/840] Rename `chat_completion_model_name` parameter to `chat_model` in Langchain::LLM parameters.
+- [BREAKING] [https://github.com/patterns-ai-core/langchainrb/pull/840] Rename `completion_model_name` parameter to `completion_model` in Langchain::LLM parameters.
+- [BREAKING] [https://github.com/patterns-ai-core/langchainrb/pull/840] Rename `embeddings_model_name` parameter to `embedding_model` in Langchain::LLM parameters.
+- [BUGFIX] [https://github.com/patterns-ai-core/langchainrb/pull/850/] Fix MistralAIMessage to handle "Tool" Output
+- [BUGFIX] [https://github.com/patterns-ai-core/langchainrb/pull/837] Fix bug when tool functions with no input variables are used with Langchain::LLM::Anthropic
+- [BUGFIX] [https://github.com/patterns-ai-core/langchainrb/pull/836] Fix bug when assistant.instructions = nil did not remove the system message
+- [FEATURE] [https://github.com/patterns-ai-core/langchainrb/pull/838] Allow setting safety_settings: [] in default_options for Langchain::LLM::GoogleGemini and Langchain::LLM::GoogleVertexAI constructors
+
+## [0.18.0] - 2024-10-12
+- [BREAKING] Remove `Langchain::Assistant#clear_thread!` method
+- [BREAKING] `Langchain::Messages::*` namespace had migrated to `Langchain::Assistant::Messages::*`
+- [BREAKING] Modify `Langchain::LLM::AwsBedrock` constructor to pass model options via default_options: {...}
+- Introduce `Langchain::Assistant#parallel_tool_calls` options whether to allow the LLM to make multiple parallel tool calls. Default: true
+- Minor improvements to the Langchain::Assistant class
+- Added support for streaming with Anthropic
+- Bump anthropic gem
+- Default Langchain::LLM::Anthropic chat model is "claude-3-5-sonnet-20240620" now
+
 ## [0.17.1] - 2024-10-07
 - Move Langchain::Assistant::LLM::Adapter-related classes to separate files
 - Fix Langchain::Tool::Database#describe_table method

data/README.md

@@ -86,7 +86,7 @@ Most LLM classes can be initialized with an API key and optional default options
 ```ruby
 llm = Langchain::LLM::OpenAI.new(
   api_key: ENV["OPENAI_API_KEY"],
-  default_options: { temperature: 0.7, chat_completion_model_name: "gpt-4o" }
+  default_options: { temperature: 0.7, chat_model: "gpt-4o" }
 )
 ```
 
@@ -132,6 +132,8 @@ Use the `chat` method to generate chat completions:
 messages = [
   { role: "system", content: "You are a helpful assistant." },
   { role: "user", content: "What's the weather like today?" }
+  # Google Gemini and Google VertexAI expect messages in a different format:
+  # { role: "user", parts: [{ text: "why is the sky blue?" }]
 ]
 response = llm.chat(messages: messages)
 chat_completion = response.chat_completion
@@ -503,7 +505,7 @@ assistant.add_message_and_run!(content: "What's the latest news about AI?")
 # Supply an image to the assistant
 assistant.add_message_and_run!(
   content: "Show me a picture of a cat",
-  image: "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
+  image_url: "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
 )
 
 # Access the conversation thread
@@ -525,11 +527,14 @@ assistant.add_message(content: "Hello")
 assistant.run(auto_tool_execution: true)
 ```
 
+Note that streaming is not currently supported for all LLMs.
+
 ### Configuration
 * `llm`: The LLM instance to use (required)
 * `tools`: An array of tool instances (optional)
 * `instructions`: System instructions for the assistant (optional)
 * `tool_choice`: Specifies how tools should be selected. Default: "auto". A specific tool function name can be passed. This will force the Assistant to **always** use this function.
+* `parallel_tool_calls`: Whether to make multiple parallel tool calls. Default: true
 * `add_message_callback`: A callback function (proc, lambda) that is called when any message is added to the conversation (optional)
 
 ### Key Methods

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

@@ -1,4 +1,4 @@
-Dir[Pathname.new(__FILE__).dirname.join("adapters", "*.rb")].sort.each { |file| require file }
+# frozen_string_literal: true
 
 module Langchain
   class Assistant

data/lib/langchain/assistant/llm/adapters/anthropic.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module LLM
+      module Adapters
+        class Anthropic < Base
+          # Build the chat parameters for the Anthropic API
+          #
+          # @param messages [Array<Hash>] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array<Hash>] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
+            params = {messages: messages}
+            if tools.any?
+              params[:tools] = build_tools(tools)
+              params[:tool_choice] = build_tool_choice(tool_choice, parallel_tool_calls)
+            end
+            params[:system] = instructions if instructions
+            params
+          end
+
+          # Build an Anthropic message
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array<Hash>] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::AnthropicMessage] The Anthropic message
+          def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
+            Langchain.logger.warn "WARNING: Image URL is not supported by Anthropic currently" if image_url
+
+            Messages::AnthropicMessage.new(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+          end
+
+          # Extract the tool call information from the Anthropic tool call hash
+          #
+          # @param tool_call [Hash] The tool call hash, format: {"type"=>"tool_use", "id"=>"toolu_01TjusbFApEbwKPRWTRwzadR", "name"=>"news_retriever__get_top_headlines", "input"=>{"country"=>"us", "page_size"=>10}}], "stop_reason"=>"tool_use"}
+          # @return [Array] The tool call information
+          def extract_tool_call_args(tool_call:)
+            tool_call_id = tool_call.dig("id")
+            function_name = tool_call.dig("name")
+            tool_name, method_name = function_name.split("__")
+            tool_arguments = tool_call.dig("input").transform_keys(&:to_sym)
+            [tool_call_id, tool_name, method_name, tool_arguments]
+          end
+
+          # Build the tools for the Anthropic API
+          def build_tools(tools)
+            tools.map { |tool| tool.class.function_schemas.to_anthropic_format }.flatten
+          end
+
+          # Get the allowed assistant.tool_choice values for Anthropic
+          def allowed_tool_choices
+            ["auto", "any"]
+          end
+
+          # Get the available tool function names for Anthropic
+          #
+          # @param tools [Array<Hash>] The tools
+          # @return [Array<String>] The tool function names
+          def available_tool_names(tools)
+            build_tools(tools).map { |tool| tool.dig(:name) }
+          end
+
+          def tool_role
+            Messages::AnthropicMessage::TOOL_ROLE
+          end
+
+          def support_system_message?
+            Messages::AnthropicMessage::ROLES.include?("system")
+          end
+
+          private
+
+          def build_tool_choice(choice, parallel_tool_calls)
+            tool_choice_object = {disable_parallel_tool_use: !parallel_tool_calls}
+
+            case choice
+            when "auto"
+              tool_choice_object[:type] = "auto"
+            when "any"
+              tool_choice_object[:type] = "any"
+            else
+              tool_choice_object[:type] = "tool"
+              tool_choice_object[:name] = choice
+            end
+
+            tool_choice_object
+          end
+        end
+      end
+    end
+  end
+end

data/lib/langchain/assistant/llm/adapters/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module LLM
+      module Adapters
+        class Base
+          # Build the chat parameters for the LLM
+          #
+          # @param messages [Array] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
+            raise NotImplementedError, "Subclasses must implement build_chat_params"
+          end
+
+          # Extract the tool call information from the tool call hash
+          #
+          # @param tool_call [Hash] The tool call hash
+          # @return [Array] The tool call information
+          def extract_tool_call_args(tool_call:)
+            raise NotImplementedError, "Subclasses must implement extract_tool_call_args"
+          end
+
+          # Build a message for the LLM
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::Base] The message
+          def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
+            raise NotImplementedError, "Subclasses must implement build_message"
+          end
+
+          # Does this adapter accept messages with role="system"?
+          #
+          # @return [Boolean] Whether the adapter supports system messages
+          def support_system_message?
+            raise NotImplementedError, "Subclasses must implement support_system_message?"
+          end
+
+          # Role name used to return the tool output
+          #
+          # @return [String] The tool role
+          def tool_role
+            raise NotImplementedError, "Subclasses must implement tool_role"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/langchain/{assistants → assistant}/llm/adapters/google_gemini.rb

@@ -1,9 +1,27 @@
+# frozen_string_literal: true
+
 module Langchain
   class Assistant
     module LLM
       module Adapters
         class GoogleGemini < Base
-          def build_chat_params(tools:, instructions:, messages:, tool_choice:)
+          # Build the chat parameters for the Google Gemini LLM
+          #
+          # @param messages [Array] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
+            Langchain.logger.warn "WARNING: `parallel_tool_calls:` is not supported by Google Gemini currently"
+
             params = {messages: messages}
             if tools.any?
               params[:tools] = build_tools(tools)
@@ -13,10 +31,18 @@ module Langchain
             params
           end
 
+          # Build a Google Gemini message
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::GoogleGeminiMessage] The Google Gemini message
           def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
-            warn "Image URL is not supported by Google Gemini" if image_url
+            Langchain.logger.warn "Image URL is not supported by Google Gemini" if image_url
 
-            Langchain::Messages::GoogleGeminiMessage.new(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+            Messages::GoogleGeminiMessage.new(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
           end
 
           # Extract the tool call information from the Google Gemini tool call hash
@@ -31,18 +57,32 @@ module Langchain
             [tool_call_id, tool_name, method_name, tool_arguments]
           end
 
+          # Build the tools for the Google Gemini LLM
+          #
+          # @param tools [Array<Langchain::Tool::Base>] The tools
+          # @return [Array] The tools in Google Gemini format
           def build_tools(tools)
             tools.map { |tool| tool.class.function_schemas.to_google_gemini_format }.flatten
           end
 
+          # Get the allowed assistant.tool_choice values for Google Gemini
           def allowed_tool_choices
             ["auto", "none"]
           end
 
+          # Get the available tool names for Google Gemini
           def available_tool_names(tools)
             build_tools(tools).map { |tool| tool.dig(:name) }
           end
 
+          def tool_role
+            Messages::GoogleGeminiMessage::TOOL_ROLE
+          end
+
+          def support_system_message?
+            Messages::GoogleGeminiMessage::ROLES.include?("system")
+          end
+
           private
 
           def build_tool_config(choice)

data/lib/langchain/{assistants → assistant}/llm/adapters/mistral_ai.rb

@@ -1,9 +1,27 @@
+# frozen_string_literal: true
+
 module Langchain
   class Assistant
     module LLM
       module Adapters
         class MistralAI < Base
-          def build_chat_params(tools:, instructions:, messages:, tool_choice:)
+          # Build the chat parameters for the Mistral AI LLM
+          #
+          # @param messages [Array] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
+            Langchain.logger.warn "WARNING: `parallel_tool_calls:` is not supported by Mistral AI currently"
+
             params = {messages: messages}
             if tools.any?
               params[:tools] = build_tools(tools)
@@ -12,8 +30,16 @@ module Langchain
             params
           end
 
+          # Build a Mistral AI message
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::MistralAIMessage] The Mistral AI message
           def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
-            Langchain::Messages::MistralAIMessage.new(role: role, content: content, image_url: image_url, tool_calls: tool_calls, tool_call_id: tool_call_id)
+            Messages::MistralAIMessage.new(role: role, content: content, image_url: image_url, tool_calls: tool_calls, tool_call_id: tool_call_id)
           end
 
           # Extract the tool call information from the OpenAI tool call hash
@@ -36,18 +62,29 @@ module Langchain
             [tool_call_id, tool_name, method_name, tool_arguments]
           end
 
+          # Build the tools for the Mistral AI LLM
           def build_tools(tools)
             tools.map { |tool| tool.class.function_schemas.to_openai_format }.flatten
           end
 
+          # Get the allowed assistant.tool_choice values for Mistral AI
           def allowed_tool_choices
             ["auto", "none"]
           end
 
+          # Get the available tool names for Mistral AI
           def available_tool_names(tools)
             build_tools(tools).map { |tool| tool.dig(:function, :name) }
           end
 
+          def tool_role
+            Messages::MistralAIMessage::TOOL_ROLE
+          end
+
+          def support_system_message?
+            Messages::MistralAIMessage::ROLES.include?("system")
+          end
+
           private
 
           def build_tool_choice(choice)

data/lib/langchain/assistant/llm/adapters/ollama.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module LLM
+      module Adapters
+        class Ollama < Base
+          # Build the chat parameters for the Ollama LLM
+          #
+          # @param messages [Array] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
+            Langchain.logger.warn "WARNING: `parallel_tool_calls:` is not supported by Ollama currently"
+            Langchain.logger.warn "WARNING: `tool_choice:` is not supported by Ollama currently"
+
+            params = {messages: messages}
+            if tools.any?
+              params[:tools] = build_tools(tools)
+            end
+            params
+          end
+
+          # Build an Ollama message
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::OllamaMessage] The Ollama message
+          def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
+            Langchain.logger.warn "WARNING: Image URL is not supported by Ollama currently" if image_url
+
+            Messages::OllamaMessage.new(role: role, content: content, tool_calls: tool_calls, tool_call_id: tool_call_id)
+          end
+
+          # Extract the tool call information from the OpenAI tool call hash
+          #
+          # @param tool_call [Hash] The tool call hash
+          # @return [Array] The tool call information
+          def extract_tool_call_args(tool_call:)
+            tool_call_id = tool_call.dig("id")
+
+            function_name = tool_call.dig("function", "name")
+            tool_name, method_name = function_name.split("__")
+
+            tool_arguments = tool_call.dig("function", "arguments")
+            tool_arguments = if tool_arguments.is_a?(Hash)
+              Langchain::Utils::HashTransformer.symbolize_keys(tool_arguments)
+            else
+              JSON.parse(tool_arguments, symbolize_names: true)
+            end
+
+            [tool_call_id, tool_name, method_name, tool_arguments]
+          end
+
+          # Build the tools for the Ollama LLM
+          def available_tool_names(tools)
+            build_tools(tools).map { |tool| tool.dig(:function, :name) }
+          end
+
+          # Get the allowed assistant.tool_choice values for Ollama
+          def allowed_tool_choices
+            ["auto", "none"]
+          end
+
+          def tool_role
+            Messages::OllamaMessage::TOOL_ROLE
+          end
+
+          def support_system_message?
+            Messages::OllamaMessage::ROLES.include?("system")
+          end
+
+          private
+
+          def build_tools(tools)
+            tools.map { |tool| tool.class.function_schemas.to_openai_format }.flatten
+          end
+        end
+      end
+    end
+  end
+end

data/lib/langchain/{assistants → assistant}/llm/adapters/openai.rb

@@ -1,19 +1,44 @@
+# frozen_string_literal: true
+
 module Langchain
   class Assistant
     module LLM
       module Adapters
         class OpenAI < Base
-          def build_chat_params(tools:, instructions:, messages:, tool_choice:)
+          # Build the chat parameters for the OpenAI LLM
+          #
+          # @param messages [Array] The messages
+          # @param instructions [String] The system instructions
+          # @param tools [Array] The tools to use
+          # @param tool_choice [String] The tool choice
+          # @param parallel_tool_calls [Boolean] Whether to make parallel tool calls
+          # @return [Hash] The chat parameters
+          def build_chat_params(
+            messages:,
+            instructions:,
+            tools:,
+            tool_choice:,
+            parallel_tool_calls:
+          )
             params = {messages: messages}
             if tools.any?
               params[:tools] = build_tools(tools)
               params[:tool_choice] = build_tool_choice(tool_choice)
+              params[:parallel_tool_calls] = parallel_tool_calls
             end
             params
           end
 
+          # Build a OpenAI message
+          #
+          # @param role [String] The role of the message
+          # @param content [String] The content of the message
+          # @param image_url [String] The image URL
+          # @param tool_calls [Array] The tool calls
+          # @param tool_call_id [String] The tool call ID
+          # @return [Messages::OpenAIMessage] The OpenAI message
           def build_message(role:, content: nil, image_url: nil, tool_calls: [], tool_call_id: nil)
-            Langchain::Messages::OpenAIMessage.new(role: role, content: content, image_url: image_url, tool_calls: tool_calls, tool_call_id: tool_call_id)
+            Messages::OpenAIMessage.new(role: role, content: content, image_url: image_url, tool_calls: tool_calls, tool_call_id: tool_call_id)
           end
 
           # Extract the tool call information from the OpenAI tool call hash
@@ -36,18 +61,29 @@ module Langchain
             [tool_call_id, tool_name, method_name, tool_arguments]
           end
 
+          # Build the tools for the OpenAI LLM
           def build_tools(tools)
             tools.map { |tool| tool.class.function_schemas.to_openai_format }.flatten
           end
 
+          # Get the allowed assistant.tool_choice values for OpenAI
           def allowed_tool_choices
             ["auto", "none"]
           end
 
+          # Get the available tool names for OpenAI
           def available_tool_names(tools)
             build_tools(tools).map { |tool| tool.dig(:function, :name) }
           end
 
+          def tool_role
+            Messages::OpenAIMessage::TOOL_ROLE
+          end
+
+          def support_system_message?
+            Messages::OpenAIMessage::ROLES.include?("system")
+          end
+
           private
 
           def build_tool_choice(choice)

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Langchain
+  class Assistant
+    module Messages
+      class AnthropicMessage < Base
+        ROLES = [
+          "assistant",
+          "user",
+          "tool_result"
+        ].freeze
+
+        TOOL_ROLE = "tool_result"
+
+        # Initialize a new Anthropic 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 Anthropic API-compatible hash
+        #
+        # @return [Hash] The message as an Anthropic API-compatible hash
+        def to_hash
+          {}.tap do |h|
+            h[:role] = tool? ? "user" : role
+
+            h[:content] = if tool?
+              [
+                {
+                  type: "tool_result",
+                  tool_use_id: tool_call_id,
+                  content: content
+                }
+              ]
+            elsif tool_calls.any?
+              tool_calls
+            else
+              content
+            end
+          end
+        end
+
+        # Check if the message is a tool call
+        #
+        # @return [Boolean] true/false whether this message is a tool call
+        def tool?
+          role == "tool_result"
+        end
+
+        # Anthropic does not implement system prompts
+        def system?
+          false
+        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 came from an LLM
+        #
+        # @return [Boolean] true/false whether this message was produced by an LLM
+        def llm?
+          assistant?
+        end
+      end
+    end
+  end
+end