activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/_base_provider.rb

@@ -0,0 +1,410 @@
+require "active_support/delegation"
+
+require_relative "common/response"
+require_relative "concerns/exception_handler"
+require_relative "concerns/previewable"
+
+# Maps provider types to their gem dependencies.
+# @private
+GEM_LOADERS = {
+  anthropic: [ "anthropic", "~> 1.12", "anthropic" ],
+  openai:    [ "openai",    "~> 0.34", "openai" ]
+}
+
+# Loads and requires a provider's gem dependency.
+#
+# @param type [Symbol] provider type (:anthropic, :openai)
+# @param file_name [String] provider file path for error context
+# @return [void]
+# @raise [LoadError] when the required gem is not available
+def require_gem!(type, file_name)
+  gem_name, requirement, package_name = GEM_LOADERS.fetch(type)
+  provider_name = file_name.split("/").last.delete_suffix(".rb").camelize
+
+  begin
+    gem(gem_name, requirement)
+    require(package_name)
+  rescue LoadError
+    raise LoadError, "The '#{gem_name}' gem is required for #{provider_name}. Please add it to your Gemfile and run `bundle install`."
+  end
+end
+
+module ActiveAgent
+  module Providers
+    # Base class for LLM provider integrations.
+    #
+    # Orchestrates API requests, streaming responses, and multi-turn tool calling.
+    # Each provider (OpenAI, Anthropic, etc.) subclasses this to implement
+    # provider-specific API interactions.
+    #
+    # @abstract Subclasses must implement {#api_prompt_execute},
+    #   {#process_stream_chunk}, {#process_prompt_finished_extract_messages},
+    #   and {#process_prompt_finished_extract_function_calls}
+    class BaseProvider
+      extend ActiveSupport::Delegation
+
+      include ExceptionHandler
+      include Previewable
+
+      class ProvidersError < StandardError; end
+
+      attr_internal :options, :context, :trace_id,   # Setup
+                    :request, :message_stack,        # Runtime
+                    :stream_broadcaster, :streaming, # Callback (Streams)
+                    :tools_function                  # Callback (Tools)
+
+      # @return [String] provider name extracted from class name (e.g., "Anthropic", "OpenAI")
+      def self.service_name
+        name.split("::").last.delete_suffix("Provider")
+      end
+
+      # @return [String] module-qualified provider name (e.g., "Anthropic", "OpenAI::Chat")
+      def self.tag_name
+        name.delete_prefix("ActiveAgent::Providers::").delete_suffix("Provider")
+      end
+
+      # @return [Module] provider's namespace module (e.g., ActiveAgent::Providers::OpenAI)
+      def self.namespace
+        "#{name.deconstantize}::#{service_name}".safe_constantize
+      end
+
+      # @return [Class] provider's options class
+      def self.options_klass
+        namespace::Options
+      end
+
+      # @return [ActiveModel::Type::Value] provider-specific request type for prompt casting/serialization
+      def self.prompt_request_type
+        namespace::RequestType.new
+      end
+
+      # @return [ActiveModel::Type::Value] provider-specific request type for embedding casting/serialization
+      # @raise [NotImplementedError] when provider doesn't support embeddings
+      def self.embed_request_type
+        fail(NotImplementedError)
+      end
+
+      delegate :service_name, :tag_name, :namespace, :options_klass, :prompt_request_type, :embed_request_type, to: :class
+
+      # Initializes a provider instance.
+      #
+      # @param kwargs [Hash] configuration and callbacks
+      # @option kwargs [Symbol] :service validates against provider's service name
+      # @option kwargs [Proc] :stream_broadcaster callback for streaming events (:open, :update, :close)
+      # @option kwargs [Proc] :tools_function callback to execute tool/function calls
+      # @raise [RuntimeError] when service name doesn't match provider
+      def initialize(kwargs = {})
+        assert_service!(kwargs.delete(:service))
+
+        configure_exception_handler(
+          exception_handler: kwargs.delete(:exception_handler)
+        )
+
+        self.trace_id           = kwargs[:trace_id]
+        self.stream_broadcaster = kwargs.delete(:stream_broadcaster)
+        self.streaming          = false
+        self.tools_function     = kwargs.delete(:tools_function)
+        self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
+        self.context            = kwargs
+        self.message_stack      = []
+      end
+
+      # Executes a prompt request with error handling and instrumentation.
+      #
+      # @return [ActiveAgent::Providers::Common::PromptResponse]
+      def prompt
+        instrument("prompt_start.provider.active_agent") do
+          self.request = prompt_request_type.cast(context.except(:trace_id))
+          resolve_prompt
+        end
+      end
+
+      # Generates a preview of the prompt without executing the API call.
+      #
+      # Casts context into a request object and renders it as markdown for inspection.
+      #
+      # @return [String] markdown-formatted preview
+      def preview
+        self.request = prompt_request_type.cast(context.except(:trace_id))
+        preview_prompt
+      end
+
+      # Executes an embedding request with error handling and instrumentation.
+      #
+      # Converts text into vector representations for semantic search and similarity operations.
+      #
+      # @return [ActiveAgent::Providers::Common::EmbedResponse]
+      def embed
+        instrument("embed_start.provider.active_agent") do
+          self.request = embed_request_type.cast(context.except(:trace_id))
+          resolve_embed
+        end
+      end
+
+      protected
+
+      # @param name [String, nil]
+      # @raise [RuntimeError] when service name doesn't match provider
+      def assert_service!(name)
+        fail "Unexpected Service Name: #{name} != #{service_name}" if name && name != service_name
+      end
+
+      # Instruments an event for logging and metrics.
+      #
+      # @param name [String]
+      # @param payload [Hash]
+      # @yield block to instrument
+      # @return [Object] block result
+      def instrument(name, payload = {}, &block)
+        full_payload = { provider: service_name, provider_module: tag_name, trace_id: }.merge(payload)
+        ActiveSupport::Notifications.instrument(name, full_payload, &block)
+      end
+
+      # Orchestrates the complete prompt request lifecycle.
+      #
+      # Prepares request, executes API call, processes response, and handles
+      # recursive tool/function calling until completion.
+      #
+      # @return [ActiveAgent::Providers::Common::PromptResponse]
+      def resolve_prompt
+        request = prepare_prompt_request
+
+        instrument("request_prepared.provider.active_agent", message_count: request.messages.size)
+
+        # @todo Validate Request
+        api_parameters = api_request_build(request, prompt_request_type)
+        api_response   = instrument("api_call.provider.active_agent", streaming: api_parameters[:stream].present?) do
+          with_exception_handling { api_prompt_execute(api_parameters) }
+        end
+
+        process_prompt_finished(api_response.as_json&.deep_symbolize_keys)
+      end
+
+      # Orchestrates the complete embedding request lifecycle.
+      #
+      # @return [ActiveAgent::Providers::Common::EmbedResponse]
+      def resolve_embed
+        # @todo Validate Request
+        api_parameters = api_request_build(request, embed_request_type)
+        api_response   = instrument("embed_call.provider.active_agent") do
+          with_exception_handling { api_embed_execute(api_parameters) }
+        end
+
+        process_embed_finished(api_response)
+      end
+
+      # Prepares request for next iteration in multi-turn conversation.
+      #
+      # Appends accumulated messages from message stack and resets buffer for next cycle.
+      #
+      # @return [Request]
+      def prepare_prompt_request
+        self.request.messages = [ *request.messages, *message_stack ]
+        self.message_stack    = []
+
+        self.request
+      end
+
+      # Builds API request parameters from request object.
+      #
+      # @param request [Request]
+      # @param request_type [ActiveModel::Type::Value] type for serialization
+      # @return [Hash]
+      def api_request_build(request, request_type)
+        parameters          = request_type.serialize(request)
+        parameters[:stream] = process_stream if request.try(:stream)
+
+        if options.extra_headers.present?
+          parameters[:request_options] = { extra_headers: options.extra_headers }.deep_merge(parameters[:request_options] || {})
+        end
+
+        parameters
+      end
+
+      # @return [Proc] invoked for each response chunk
+      def process_stream
+        proc do |api_response_chunk|
+          process_stream_chunk(api_response_chunk)
+        end
+      end
+
+      # Executes prompt request against provider's API.
+      #
+      # @abstract
+      # @param request_parameters [Hash]
+      # @return [Object] provider-specific API response
+      # @raise [NotImplementedError]
+      def api_prompt_execute(parameters)
+        instrument("api_request.provider.active_agent", model: parameters[:model], streaming: !!parameters[:stream])
+
+        unless parameters[:stream]
+          api_prompt_executer.create(**parameters)
+        else
+          api_prompt_executer.stream(**parameters.except(:stream)).each(&parameters[:stream])
+          nil
+        end
+      end
+
+      # Returns provider-specific API executer for prompt requests.
+      #
+      # Since all currently implemented providers use stainless gems, subclasses
+      # only need to override endpoint selection.
+      #
+      # @abstract
+      # @return [Object] provider-specific API client
+      # @raise [NotImplementedError]
+      def api_prompt_executer
+        fail NotImplementedError, "Subclass expected to implement"
+      end
+
+      # Executes embedding request against provider's API.
+      #
+      # @abstract
+      # @param request_parameters [Hash]
+      # @return [Object] provider-specific embedding response
+      # @raise [NotImplementedError]
+      def api_embed_execute(request_parameters)
+        fail NotImplementedError, "Subclass expected to implement"
+      end
+
+      # Processes a single streaming response chunk.
+      #
+      # @abstract
+      # @param api_response_chunk [Object] provider-specific chunk format
+      # @raise [NotImplementedError]
+      def process_stream_chunk(api_response_chunk)
+        fail NotImplementedError, "Subclass expected to implement"
+      end
+
+      # Broadcasts stream open event.
+      #
+      # Fires once per request cycle even during multi-turn tool calling.
+      #
+      # @return [void]
+      def broadcast_stream_open
+        return if streaming
+        self.streaming = true
+
+        instrument("stream_open.provider.active_agent")
+        stream_broadcaster.call(nil, nil, :open)
+      end
+
+      # Broadcasts stream update with message content delta.
+      #
+      # @param message [Hash, Object]
+      # @param delta [String, nil] incremental content chunk
+      # @return [void]
+      def broadcast_stream_update(message, delta = nil)
+        stream_broadcaster.call(message, delta, :update)
+      end
+
+      # Broadcasts stream close event.
+      #
+      # Fires once per request cycle even during multi-turn tool calling.
+      #
+      # @return [void]
+      def broadcast_stream_close
+        return unless streaming
+        self.streaming = false
+
+        instrument("stream_close.provider.active_agent")
+        stream_broadcaster.call(message_stack.last, nil, :close)
+      end
+
+      # Processes completed API response and handles tool calling recursion.
+      #
+      # Extracts messages and function calls from the response. If tools were invoked,
+      # executes them and recursively continues the prompt until completion.
+      #
+      # @param api_response [Object, nil] provider-specific response
+      # @return [Common::PromptResponse, nil]
+      def process_prompt_finished(api_response = nil)
+        if (api_messages = process_prompt_finished_extract_messages(api_response))
+          instrument("messages_extracted.provider.active_agent", message_count: api_messages.size)
+          message_stack.push(*api_messages)
+        end
+
+        if (tool_calls = process_prompt_finished_extract_function_calls)&.any?
+          instrument("tool_calls_processing.provider.active_agent", tool_count: tool_calls.size)
+          process_function_calls(tool_calls)
+
+          instrument("multi_turn_continue.provider.active_agent")
+          resolve_prompt
+        else
+
+          # During a multi iteration process, we will internally open/close the stream
+          # with the provider, but this should all look like one big stream to the agents
+          # as they continue to work.
+          broadcast_stream_close
+
+          instrument("prompt_complete.provider.active_agent", message_count: message_stack.size)
+
+          # To convert the messages into common format we first need to merge the current
+          # stack and then cast them to the provider type, so we can cast them out to common.
+          messages = prompt_request_type.cast(
+            messages: [ *request.messages, *message_stack ]
+          ).messages
+
+          # This will returned as it closes up the recursive stack
+          Common::PromptResponse.new(
+            context:,
+            raw_request:  prompt_request_type.serialize(request),
+            raw_response: api_response,
+            messages:,
+            format: request.response_format
+          )
+        end
+      end
+
+      # Extracts messages from API response.
+      #
+      # @abstract
+      # @param api_response [Object]
+      # @return [Array<Message>, nil]
+      # @raise [NotImplementedError]
+      def process_prompt_finished_extract_messages(api_response)
+        fail NotImplementedError, "Subclass expected to implement"
+      end
+
+      # Extracts tool/function calls from API response.
+      #
+      # @abstract
+      # @return [Array<Hash>, nil]
+      # @raise [NotImplementedError]
+      def process_prompt_finished_extract_function_calls
+        fail NotImplementedError, "Subclass expected to implement"
+      end
+
+      # @param api_response [Hash]
+      # @return [Common::EmbedResponse]
+      def process_embed_finished(api_response)
+        Common::EmbedResponse.new(
+          context:,
+          raw_request:  embed_request_type.serialize(request),
+          raw_response: api_response,
+          data: process_embed_finished_data(api_response)
+        )
+      end
+
+      # Extracts embedding vectors from API response.
+      #
+      # Handles both list and single embedding response formats:
+      # - List: `{ "data": [{ "embedding": [...] }] }`
+      # - Single: `{ "embedding": [...] }`
+      #
+      # @param api_response [Hash]
+      # @return [Array<Hash>] embedding objects with :index, :object, :embedding keys
+      # @raise [RuntimeError] when response format is unexpected
+      def process_embed_finished_data(api_response)
+        case (type = api_response[:object].to_sym)
+        when :list
+          api_response[:data]
+        when :embedding
+          [ { index: 0 }.merge(api_response.slice(:index, :object, :embedding)) ]
+        else
+          fail "Unexpected Embed Object Type: #{type}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "requests/_types"
+
+require_relative "options"
+require_relative "request"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      # ActiveModel type for casting and serializing Anthropic Request objects.
+      #
+      # Handles conversion between Hash, Request, and serialized formats for API calls.
+      class RequestType < ActiveModel::Type::Value
+        # Casts input to Request object.
+        #
+        # @param value [Request, Hash, nil]
+        # @return [Request, nil]
+        # @raise [ArgumentError] when value cannot be cast to Request
+        def cast(value)
+          case value
+          when Request
+            value
+          when Hash
+            Request.new(**value.deep_symbolize_keys)
+          when nil
+            nil
+          else
+            raise ArgumentError, "Cannot cast #{value.class} to Request"
+          end
+        end
+
+        # Serializes Request to Hash for API submission.
+        #
+        # Removes `:response_format` key as it's a simulated feature not directly
+        # supported by Anthropic's API.
+        #
+        # @param value [Request, Hash, nil]
+        # @return [Hash, nil]
+        # @raise [ArgumentError] when value cannot be serialized
+        def serialize(value)
+          case value
+          when Request
+            # Response Format is a simulated feature, not directly supported by API
+            value.serialize.except(:response_format)
+          when Hash
+            value
+          when nil
+            nil
+          else
+            raise ArgumentError, "Cannot serialize #{value.class}"
+          end
+        end
+
+        # @param value [Object]
+        # @return [Request, nil]
+        def deserialize(value)
+          cast(value)
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/options.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      class Options < Common::BaseModel
+        attribute :api_key,  :string
+        attribute :base_url, :string,  default: "https://api.anthropic.com"
+
+        attribute :anthropic_beta, :string
+
+        attribute :max_retries,         :integer, default: ::Anthropic::Client::DEFAULT_MAX_RETRIES
+        attribute :timeout,             :float,   default: ::Anthropic::Client::DEFAULT_TIMEOUT_IN_SECONDS
+        attribute :initial_retry_delay, :float,   default: ::Anthropic::Client::DEFAULT_INITIAL_RETRY_DELAY
+        attribute :max_retry_delay,     :float,   default: ::Anthropic::Client::DEFAULT_MAX_RETRY_DELAY
+
+        # Common Interface Compatibility
+        alias_attribute :access_token, :api_key
+
+        def initialize(kwargs = {})
+          kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
+
+          super(**deep_compact(kwargs.except(:default_url_options).merge(
+            api_key: kwargs[:api_key] || resolve_access_token(kwargs),
+          )))
+        end
+
+        def serialize
+          super.except(:anthropic_beta).tap do |hash|
+            hash[:extra_headers] = extra_headers unless extra_headers.blank?
+          end
+        end
+
+        def extra_headers
+          deep_compact(
+            "anthropic-beta" => anthropic_beta.presence,
+          )
+        end
+
+        private
+
+        def resolve_access_token(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["ANTHROPIC_ACCESS_TOKEN"] ||
+            ENV["ANTHROPIC_API_KEY"]
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/anthropic/request.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+require_relative "_types"
+
+module ActiveAgent
+  module Providers
+    module Anthropic
+      class Request < Common::BaseModel
+        # Required parameters
+        attribute :model,      :string
+        attribute :messages,   Requests::Messages::MessagesType.new
+        attribute :max_tokens, :integer, fallback: 4096
+
+        # Optional parameters - Prompting
+        attribute :system,         Requests::Messages::SystemType.new
+        attribute :temperature,    :float
+        attribute :top_k,          :integer
+        attribute :top_p,          :float
+        attribute :stop_sequences, default: -> { [] } # Array of strings
+
+        # Optional parameters - Tools
+        attribute :tools       # Array of tool definitions
+        attribute :tool_choice, Requests::ToolChoice::ToolChoiceType.new
+
+        # Optional parameters - Thinking
+        attribute :thinking, Requests::ThinkingConfig::ThinkingConfigType.new
+
+        # Optional parameters - Streaming
+        attribute :stream, :boolean, default: false
+
+        # Optional parameters - Metadata
+        attribute :metadata, Requests::MetadataType.new
+
+        # Optional parameters - Context Management
+        attribute :context_management, Requests::ContextManagementConfigType.new
+
+        # Optional parameters - Container
+        attribute :container, Requests::ContainerParamsType.new
+
+        # Optional parameters - Service tier
+        attribute :service_tier, :string
+
+        # Optional parameters - MCP Servers
+        attribute :mcp_servers, default: -> { [] } # Array of MCP server definitions
+
+        # Common Format Compatibility
+        attribute :response_format, Requests::ResponseFormatType.new
+
+        # Validations for required fields
+        validates :model, :messages, :max_tokens, presence: true
+
+        # Validations for numeric parameters
+        validates :max_tokens,  numericality: { greater_than_or_equal_to: 1 },                          allow_nil: true
+        validates :temperature, numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 }, allow_nil: true
+        validates :top_k,       numericality: { greater_than_or_equal_to: 0 },                           allow_nil: true
+        validates :top_p,       numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 }, allow_nil: true
+
+        # Validations for specific values
+        validates :service_tier, inclusion: { in: %w[auto standard_only] }, allow_nil: true
+
+        # Custom validations
+        validate :validate_stop_sequences
+        validate :validate_tools_format
+        validate :validate_mcp_servers_format
+
+        # Common Format Compatibility
+        alias_attribute :instructions, :system
+
+        # Handle merging in the common format
+        def message=(value)
+          self.messages ||= []
+          self.messages << Requests::Messages::MessageType.new.cast(value)
+        end
+
+        private
+
+        def validate_stop_sequences
+          return if stop_sequences.nil? || stop_sequences.empty?
+
+          unless stop_sequences.is_a?(Array)
+            errors.add(:stop_sequences, "must be an array")
+          end
+        end
+
+        def validate_tools_format
+          return if tools.nil?
+
+          unless tools.is_a?(Array)
+            errors.add(:tools, "must be an array")
+          end
+        end
+
+        def validate_mcp_servers_format
+          return if mcp_servers.nil? || mcp_servers.empty?
+
+          unless mcp_servers.is_a?(Array)
+            errors.add(:mcp_servers, "must be an array")
+            return
+          end
+
+          if mcp_servers.length > 20
+            errors.add(:mcp_servers, "can have at most 20 servers")
+          end
+        end
+      end
+    end
+  end
+end