activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/anthropic/requests/thinking_config/_types.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "enabled"
+require_relative "disabled"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ThinkingConfig
+          # Type for ThinkingConfig
+          class ThinkingConfigType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when Base
+                value
+              when Hash
+                hash = value.deep_symbolize_keys
+                type = hash[:type]&.to_sym
+
+                case type
+                when :enabled
+                  Enabled.new(**hash)
+                when :disabled
+                  Disabled.new(**hash)
+                when nil
+                  nil
+                else
+                  raise ArgumentError, "Unknown thinking config type: #{type}"
+                end
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to ThinkingConfig"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Base
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/thinking_config/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ThinkingConfig
+          # Base class for thinking configuration
+          class Base < Common::BaseModel
+            attribute :type, :string
+
+            validates :type, presence: true, inclusion: { in: %w[enabled disabled] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/thinking_config/disabled.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ThinkingConfig
+          # Disabled thinking configuration
+          class Disabled < Base
+            attribute :type, :string, as: "disabled"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/thinking_config/enabled.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ThinkingConfig
+          # Enabled thinking configuration with budget
+          class Enabled < Base
+            attribute :type,          :string,  as: "enabled"
+            attribute :budget_tokens, :integer
+
+            validates :budget_tokens, presence: true
+            validates :budget_tokens, numericality: { greater_than_or_equal_to: 1024 }, allow_nil: false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/_types.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "auto"
+require_relative "any"
+require_relative "tool"
+require_relative "none"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # Type for ToolChoice
+          class ToolChoiceType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when Base
+                value
+              when Hash
+                hash = value.deep_symbolize_keys
+                type = hash[:type]&.to_sym
+
+                case type
+                when :auto
+                  Auto.new(**hash)
+                when :any
+                  Any.new(**hash)
+                when :tool
+                  Tool.new(**hash)
+                when :none
+                  None.new(**hash)
+                when nil
+                  nil
+                else
+                  raise ArgumentError, "Unknown tool choice type: #{type}"
+                end
+              when String, Symbol
+                # Allow string shortcuts like "auto", "any", "none"
+                case value.to_sym
+                when :auto
+                  Auto.new
+                when :any
+                  Any.new
+                when :none
+                  None.new
+                else
+                  raise ArgumentError, "Unknown tool choice: #{value}"
+                end
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to ToolChoice"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when Base
+                value.serialize
+              when Hash
+                value
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot serialize #{value.class}"
+              end
+            end
+
+            def deserialize(value)
+              cast(value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/any.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # Any tool choice - model will use any available tools
+          class Any < Base
+            attribute :type,                      :string,  as: "any"
+            attribute :disable_parallel_tool_use, :boolean
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/auto.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # Auto tool choice - model decides whether to use tools
+          class Auto < Base
+            attribute :type,                      :string,  as: "auto"
+            attribute :disable_parallel_tool_use, :boolean
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/base.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # Base class for tool choice configurations
+          class Base < Common::BaseModel
+            attribute :type, :string
+
+            validates :type, presence: true, inclusion: { in: %w[auto any tool none] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/none.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # None tool choice - model will not use tools
+          class None < Base
+            attribute :type, :string, as: "none"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/requests/tool_choice/tool.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      module Requests
+        module ToolChoice
+          # Tool choice - model will use the specified tool
+          class Tool < Base
+            attribute :type,                      :string, as: "tool"
+            attribute :name,                      :string
+            attribute :disable_parallel_tool_use, :boolean
+
+            validates :name, presence: true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic_provider.rb

@@ -0,0 +1,211 @@
+# lib/active_agent/providers/anthropic_provider.rb
+
+require_relative "_base_provider"
+
+require_gem!(:anthropic, __FILE__)
+
+require_relative "anthropic/_types"
+
+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
+
+      # Prepares the request and handles tool choice cleanup.
+      #
+      # Removes forced tool choice from subsequent requests to prevent endless looping
+      # when the tool has already been used in the conversation.
+      #
+      # @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
+
+        functions_used = message_stack.pluck(:content).flatten.select { _1[:type] == "tool_use" }.pluck(:name)
+
+        if (request.tool_choice.type == "any" && functions_used.any?) ||
+          (request.tool_choice.type == "tool" && functions_used.include?(request.tool_choice.name))
+
+          instrument("tool_choice_removed.provider.active_agent")
+          request.tool_choice = nil
+        end
+      end
+
+      # @api private
+      def prepare_prompt_request_response_format
+        return unless request.response_format&.type == "json_object"
+
+        self.message_stack.push({
+          role:    "assistant",
+          content: "Here is the JSON requested:\n{"
+        })
+      end
+
+      def api_prompt_executer
+        client.messages
+      end
+
+      # Processes streaming response chunks from Anthropic's API.
+      #
+      # 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.
+      #
+      # @param api_response_chunk [Object]
+      # @return [void]
+      def process_stream_chunk(api_response_chunk)
+        api_response_chunk = api_response_chunk.as_json.deep_symbolize_keys
+        chunk_type = api_response_chunk[:type].to_sym
+
+        instrument("stream_chunk_processing.provider.active_agent", chunk_type:)
+
+        broadcast_stream_open
+
+        case chunk_type
+        # Message Created
+        when :message_start
+          api_message = api_response_chunk.fetch(:message)
+          self.message_stack.push(api_message)
+          broadcast_stream_update(message_stack.last)
+
+        # -> Content Block Create
+        when :content_block_start
+          api_content = api_response_chunk.fetch(: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.fetch(:index)
+          content   = self.message_stack.last[:content][index]
+          api_delta = api_response_chunk.fetch(:delta)
+
+          case (delta_type = 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
+            fail "Unexpected Delta Type #{delta_type}"
+          end
+        # -> Content Block Completed [Full Block]
+        when :content_block_stop
+          index       = api_response_chunk.fetch(:index)
+          api_content = api_response_chunk.fetch(:content_block)
+          self.message_stack.last[:content][index] = api_content
+
+        # Message Delta
+        when :message_delta
+          self.message_stack.last.merge!(api_response_chunk.fetch(:delta))
+
+        # Message Completed [Full Message]
+        when :message_stop
+          self.message_stack[-1] = api_response_chunk.fetch(: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.key?(:snapshot)
+          fail "Unexpected Chunk Type: #{api_response_chunk[:type]}"
+        end
+      end
+
+      # Executes tool calls and creates user message with results.
+      #
+      # @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
+
+        message = Anthropic::Requests::Messages::User.new(content:)
+
+        message_stack.push(message.serialize)
+      end
+
+      # Executes a single tool call and returns the result.
+      #
+      # @param api_function_call [Hash] with :name, :input, and :id keys
+      # @return [Anthropic::Requests::Content::ToolResult]
+      def process_tool_call_function(api_function_call)
+        instrument("tool_execution.provider.active_agent", tool_name: api_function_call[:name])
+
+        results = tools_function.call(
+          api_function_call[:name], **api_function_call[:input]
+        )
+
+        Anthropic::Requests::Content::ToolResult.new(
+          tool_use_id: api_function_call[:id],
+          content:     results.to_json,
+        )
+      end
+
+      # Extracts messages from completed API response.
+      #
+      # Handles JSON response format by merging the leading `{` prefix back into
+      # the message content after removing the assistant lead-in message.
+      #
+      # @param api_response [Object]
+      # @return [Array<Hash>, nil]
+      def process_prompt_finished_extract_messages(api_response)
+        return unless api_response
+
+        message = api_response.as_json.deep_symbolize_keys
+
+        if request.response_format&.type == "json_object"
+          request.messages.pop # Remove the `Here is the JSON requested:\n{` lead in message
+          message[:content][0][:text] = "{#{message[:content][0][:text]}" # Merge in `{` prefix
+        end
+
+        [ message ]
+      end
+
+      # Extracts function calls from message stack.
+      #
+      # Processes tool_use content blocks and converts JSON buffers into proper
+      # input parameters for function execution.
+      #
+      # @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
+          api_function_call
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# 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)
+                  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)
+                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
+          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