activeagent 0.6.3 → 1.0.0

data/lib/active_agent/providers/anthropic_provider.rb

@@ -0,0 +1,254 @@
+# lib/active_agent/providers/anthropic_provider.rb
+
+require_relative "_base_provider"
+
+require_gem!(:anthropic, __FILE__)
+
+require_relative "anthropic/_types"
+require_relative "anthropic/transforms"
+
+module ActiveAgent
+  module Providers
+    # Handles communication with Anthropic's Claude models.
+    #
+    # Supports message creation, streaming responses, tool calling, and Claude-specific
+    # features like thinking mode and content blocks. Manages tool choice cleanup to
+    # prevent endless looping when tools have been used in conversation history.
+    #
+    # @see BaseProvider
+    class AnthropicProvider < BaseProvider
+      # @todo Add support for Anthropic::BedrockClient and Anthropic::VertexClient
+      # @return [Anthropic::Client]
+      def client
+        ::Anthropic::Client.new(**options.serialize)
+      end
+
+      protected
+
+      # Removes forced tool choice after first use to prevent endless looping.
+      #
+      # Clears tool_choice when the specified tool has already been called in the
+      # conversation, preventing the model from being forced to call it repeatedly.
+      #
+      # @see BaseProvider#prepare_prompt_request
+      # @return [Request]
+      def prepare_prompt_request
+        prepare_prompt_request_tools
+        prepare_prompt_request_response_format
+
+        super
+      end
+
+      # @api private
+      def prepare_prompt_request_tools
+        return unless request.tool_choice
+        return unless request.tool_choice.respond_to?(:type)
+
+        functions_used = message_stack.pluck(:content).flatten.select { _1[:type] == "tool_use" }.pluck(:name)
+
+        # tool_choice is always a gem model object (ToolChoiceAny, ToolChoiceTool, ToolChoiceAuto)
+        tool_choice_type = request.tool_choice.type
+        tool_choice_name = request.tool_choice.respond_to?(:name) ? request.tool_choice.name : nil
+
+        if (tool_choice_type == :any && functions_used.any?) ||
+          (tool_choice_type == :tool && tool_choice_name && functions_used.include?(tool_choice_name))
+
+          request.tool_choice = nil
+        end
+      end
+
+      # @api private
+      def prepare_prompt_request_response_format
+        return unless request.response_format&.dig(:type) == "json_object"
+
+        self.message_stack.push({
+          role:    "assistant",
+          content: "Here is the JSON requested:\n{"
+        })
+      end
+
+      # @see BaseProvider#api_prompt_executer
+      # @return [Anthropic::Messages]
+      def api_prompt_executer
+        client.messages
+      end
+
+      # @see BaseProvider#api_response_normalize
+      # @param api_response [Anthropic::Models::Message]
+      # @return [Hash] normalized response hash
+      def api_response_normalize(api_response)
+        return api_response unless api_response
+
+        Anthropic::Transforms.gem_to_hash(api_response)
+      end
+
+      # Processes streaming chunks and builds message incrementally in message_stack.
+      #
+      # Handles chunk types: message_start, content_block_start, content_block_delta,
+      # content_block_stop, message_delta, message_stop. Manages text deltas,
+      # tool use inputs, and Claude's thinking/signature blocks.
+      #
+      # @see BaseProvider#process_stream_chunk
+      # @param api_response_chunk [Anthropic::StreamEvent]
+      # @return [void]
+      def process_stream_chunk(api_response_chunk)
+        chunk_type = api_response_chunk[:type]&.to_sym
+
+        instrument("stream_chunk.active_agent", chunk_type:)
+
+        broadcast_stream_open
+
+        case chunk_type
+        # Message Created
+        when :message_start
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
+          self.message_stack.push(api_message)
+          broadcast_stream_update(message_stack.last)
+
+        # -> Content Block Create
+        when :content_block_start
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
+          self.message_stack.last[:content].push(api_content)
+          broadcast_stream_update(message_stack.last, api_content[:text])
+
+        # -> -> Content Block Append
+        when :content_block_delta
+          index     = api_response_chunk.index
+          content   = self.message_stack.last[:content][index]
+          api_delta = api_response_chunk.delta
+
+          case api_delta.type.to_sym
+          # -> -> -> Content Text Append
+          when :text_delta
+            content[:text] += api_delta.text
+            broadcast_stream_update(message_stack.last, api_delta.text)
+
+          # -> -> -> Content Function Call Append
+          when :input_json_delta
+            # No-Op; Wait for Function call to be complete
+          when :thinking_delta, :signature_delta
+            # TODO: Add with thinking rendering support
+          else
+            raise "Unexpected delta type: #{api_delta.type}"
+          end
+        # -> Content Block Completed [Full Block]
+        when :content_block_stop
+          index       = api_response_chunk.index
+          api_content = Anthropic::Transforms.gem_to_hash(api_response_chunk.content_block)
+          self.message_stack.last[:content][index] = api_content
+
+        # Message Delta
+        when :message_delta
+          delta = Anthropic::Transforms.gem_to_hash(api_response_chunk.delta)
+          self.message_stack.last.merge!(delta)
+
+        # Message Completed [Full Message]
+        when :message_stop
+          api_message = Anthropic::Transforms.gem_to_hash(api_response_chunk.message)
+
+          # Handle _json_buf (gem >= 1.14.0)
+          api_message[:content]&.each do |content_block|
+            content_block.delete(:_json_buf) if content_block[:type] == "tool_use"
+          end
+
+          self.message_stack[-1] = api_message
+
+          # Once we are finished, close out and run tooling callbacks (Recursive)
+          process_prompt_finished if message_stack.last[:stop_reason]
+        when :ping
+          # No-Op Keep Awake
+        when :overloaded_error
+          # TODO: https://docs.claude.com/en/docs/build-with-claude/streaming#error-events
+        else
+          # No-Op: Looks like internal tracking from gem wrapper
+          return if api_response_chunk.respond_to?(:snapshot)
+          raise "Unexpected chunk type: #{api_response_chunk.type}"
+        end
+      end
+
+      # Executes tool calls and appends user message with results to message_stack.
+      #
+      # @param api_function_calls [Array<Hash>] with :name, :input, and :id keys
+      # @return [void]
+      def process_function_calls(api_function_calls)
+        content = api_function_calls.map do |api_function_call|
+          process_tool_call_function(api_function_call)
+        end
+
+        api_message = ::Anthropic::Models::MessageParam.new(role: "user", content:)
+        message     = Anthropic::Transforms.gem_to_hash(api_message)
+
+        message_stack.push(message)
+      end
+
+      # Executes a single tool call via callback.
+      #
+      # @param api_function_call [Hash] with :name, :input, and :id keys
+      # @return [Anthropic::Models::ToolResultBlockParam]
+      def process_tool_call_function(api_function_call)
+        instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+          results = tools_function.call(
+            api_function_call[:name], **api_function_call[:input]
+          )
+
+          ::Anthropic::Models::ToolResultBlockParam.new(
+            type:        "tool_result",
+            tool_use_id: api_function_call[:id],
+            content:     results.to_json,
+            is_error:    false
+          )
+        end
+      end
+
+      # Converts API response message to hash for message_stack.
+      # Converts Anthropic gem response object to hash for storage.
+      #
+      # @param api_response [Anthropic::Models::Message]
+      # @return [Common::PromptResponse, nil]
+      def process_prompt_finished(api_response = nil)
+        # Convert gem object to hash so that raw_response[:usage] works
+        api_response_hash = api_response ? Anthropic::Transforms.gem_to_hash(api_response) : nil
+        super(api_response_hash)
+      end
+
+      #
+      # Handles JSON response format simulation by prepending `{` to the response
+      # content after removing the assistant lead-in message.
+      #
+      # @see BaseProvider#process_prompt_finished_extract_messages
+      # @param api_response [Hash] converted response hash
+      # @return [Array<Hash>, nil]
+      def process_prompt_finished_extract_messages(api_response)
+        return unless api_response
+
+        # Handle JSON response format simulation
+        if request.response_format&.dig(:type) == "json_object"
+          request.pop_message!
+          api_response[:content][0][:text] = "{#{api_response[:content][0][:text]}"
+        end
+
+        [ api_response ]
+      end
+
+      # Extracts tool_use blocks from message_stack and parses JSON inputs.
+      #
+      # Handles JSON buffer parsing for gem versions and string inputs for gem >= 1.14.0.
+      #
+      # @see BaseProvider#process_prompt_finished_extract_function_calls
+      # @return [Array<Hash>] with :name, :input, and :id keys
+      def process_prompt_finished_extract_function_calls
+        message_stack.pluck(:content).flatten.select { _1 in { type: "tool_use" } }.map do |api_function_call|
+          json_buf = api_function_call.delete(:json_buf)
+          api_function_call[:input] = JSON.parse(json_buf, symbolize_names: true) if json_buf
+
+          # Handle case where :input is still a JSON string (gem >= 1.14.0)
+          if api_function_call[:input].is_a?(String)
+            api_function_call[:input] = JSON.parse(api_function_call[:input], symbolize_names: true)
+          end
+
+          api_function_call
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/_types.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "user"
+require_relative "assistant"
+require_relative "tool"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        module Types
+          # Type for a single Message
+          class MessageType < ActiveModel::Type::Value
+            def cast(value)
+              cast_message(value)
+            end
+
+            def serialize(value)
+              serialize_message(value)
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+
+            private
+
+            def cast_message(value)
+              case value
+              when Common::Messages::Base
+                value
+              when String
+                # Convert bare strings to user messages
+                Common::Messages::User.new(content: value)
+              when Hash
+                hash = value.deep_symbolize_keys
+                role = hash[:role]&.to_s
+
+                case role
+                when "system"
+                  nil # System messages are dropped in common format, replaced by Instructions
+                when "user", nil
+                  # Handle both standard format and format with `text` key
+                  if hash[:text] && !hash[:content]
+                    Common::Messages::User.new(content: hash[:text])
+                  else
+                    # Filter to only known attributes for User
+                    filtered_hash = hash.slice(:role, :content, :name)
+                    Common::Messages::User.new(**filtered_hash.merge(role: "user"))
+                  end
+                when "assistant"
+                  # Filter to only known attributes for Assistant
+                  filtered_hash = hash.slice(:role, :content, :name)
+
+                  # Compress content array to string if needed (Anthropic format)
+                  if filtered_hash[:content].is_a?(Array)
+                    filtered_hash[:content] = compress_content_array(filtered_hash[:content])
+                  end
+
+                  Common::Messages::Assistant.new(**filtered_hash)
+                when "tool"
+                  # Filter to only known attributes for Tool
+                  filtered_hash = hash.slice(:role, :content, :tool_call_id)
+                  Common::Messages::Tool.new(**filtered_hash)
+                else
+                  raise ArgumentError, "Unknown message role: #{role}"
+                end
+              else
+                # Check if the value responds to to_common (provider-specific message)
+                if value.respond_to?(:to_common)
+                  cast_message(value.to_common)
+                # Check if it's a gem model object that can be converted to hash
+                # Use JSON round-trip to ensure proper nested serialization
+                elsif value.respond_to?(:to_json)
+                  hash = JSON.parse(value.to_json, symbolize_names: true)
+                  cast_message(hash)
+                elsif value.respond_to?(:to_h)
+                  cast_message(value.to_h)
+                else
+                  raise ArgumentError, "Cannot cast #{value.class} to Message"
+                end
+              end
+            end
+
+            def serialize_message(value)
+              case value
+              when nil
+                nil
+              when Common::Messages::Base
+                value.to_h
+              when Hash
+                value
+              else
+                  raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            # Compresses Anthropic-style content array into a string.
+            #
+            # Anthropic messages can have content as an array of blocks like:
+            # [{type: "text", text: "..."}, {type: "tool_use", ...}]
+            # This extracts and joins text blocks into a single string.
+            #
+            # @param content_array [Array<Hash>]
+            # @return [String]
+            def compress_content_array(content_array)
+              content_array.map do |block|
+                case block[:type]&.to_s
+                when "text"
+                  block[:text]
+                when "tool_use"
+                  # Tool use blocks don't have readable text content
+                  nil
+                else
+                  # Unknown block type, try to extract text if present
+                  block[:text]
+                end
+              end.compact.join("\n")
+            end
+          end
+
+          # Type for Messages array
+          class MessagesType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when Array
+                value.map { |v| message_type.cast(v) }.compact
+              when nil
+                []
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to Messages array"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Array
+                value.map { |v| message_type.serialize(v) }.compact
+              when nil
+                []
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+
+            private
+
+            def message_type
+              @message_type ||= MessageType.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/assistant.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # Represents messages sent by the AI assistant in a conversation.
+        class Assistant < Base
+          attribute :role, :string, as: "assistant"
+          attribute :content, :string
+          attribute :name, :string
+
+          validates :content, presence: true
+
+          # Extracts and parses JSON object or array from message content.
+          #
+          # Searches for the first occurrence of `{` or `[` and last occurrence of `}` or `]`,
+          # then parses the content between them. Useful for extracting structured data from
+          # assistant messages that may contain additional text around the JSON.
+          #
+          # @param symbolize_names [Boolean] whether to symbolize hash keys
+          # @param normalize_names [Symbol, nil] key normalization method (e.g., :underscore)
+          # @return [Hash, Array, nil] parsed JSON structure or nil if parsing fails
+          def parsed_json(symbolize_names: true, normalize_names: :underscore)
+            start_char       = [ content.index("{"),  content.index("[") ].compact.min
+            end_char         = [ content.rindex("}"), content.rindex("]") ].compact.max
+            content_stripped = content[start_char..end_char] if start_char && end_char
+            return unless content_stripped
+
+            content_parsed = JSON.parse(content_stripped)
+
+            transform_hash = ->(hash) do
+              next if hash.nil?
+
+              hash = hash.deep_transform_keys(&normalize_names) if normalize_names
+              hash = hash.deep_symbolize_keys if symbolize_names
+              hash
+            end
+
+            case content_parsed
+            when Hash  then transform_hash.call(content_parsed)
+            when Array then content_parsed.map { |item| item.is_a?(Hash) ? transform_hash.call(item) : item }
+            else content_parsed
+            end
+          rescue JSON::ParserError
+            nil
+          end
+
+          alias_method :json_object, :parsed_json
+          alias_method :parse_json,  :parsed_json
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        class Base < Common::BaseModel
+          attribute :role, :string
+
+          validates :role, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/system.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # System message - provides instructions and context to the AI
+        class System < Base
+          attribute :role, :string, as: "system"
+          attribute :content, :string # Text content
+          attribute :name, :string # Optional name for the system message
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/tool.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # Tool message - messages containing tool call results
+        class Tool < Base
+          attribute :role, :string, as: "tool"
+          attribute :content, :string # Tool result content
+          attribute :tool_call_id, :string # ID of the tool call this is responding to
+          attribute :name, :string # Optional name of the tool
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/messages/user.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Messages
+        # Represents a message sent by the user in a conversation
+        class User < Base
+          attribute :role, :string, as: "user"
+          attribute :content, :string
+          attribute :name, :string
+
+          validates :content, presence: true
+        end
+      end
+    end
+  end
+end