activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/open_ai_provider.rb

@@ -0,0 +1,97 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai/_base"
+require_relative "open_ai/chat_provider"
+require_relative "open_ai/responses_provider"
+require_relative "open_ai/embedding/_types"
+
+module ActiveAgent
+  module Providers
+    # Router for OpenAI's API versions based on supported features.
+    #
+    # This provider acts as a thin wrapper that routes requests between different versions
+    # of OpenAI's API (Chat API and Responses API) depending on the features used in the prompt.
+    # It automatically selects the appropriate API version based on:
+    # - Explicit API version specification (+:api_version+ option)
+    # - Presence of audio content in the request
+    #
+    # @example Basic usage
+    #   provider = ActiveAgent::Providers::OpenAIProvider.new(...)
+    #   result = provider.generate
+    #
+    # @see https://platform.openai.com/docs/guides/migrate-to-responses
+    class OpenAIProvider < OpenAI::Base
+      # Returns the embedding request type for OpenAI.
+      #
+      # @return [ActiveModel::Type::Value] The OpenAI embedding request type
+      def self.embed_request_type
+        OpenAI::Embedding::RequestType.new
+      end
+
+      attr_internal :api_version
+      attr_internal :raw_options
+
+      # Initializes the OpenAI provider router.
+      #
+      # Since this layer is just routing based on API version, we want to wait
+      # to cast values into their types.
+      #
+      # @param kwargs [Hash] Configuration options for the provider
+      # @option kwargs [Symbol] :service The service name to validate
+      # @option kwargs [Symbol] :api_version The OpenAI API version to use (:chat or :responses)
+      def initialize(kwargs = {})
+        # For Routing Prompt APIs
+        self.api_version = kwargs.delete(:api_version)
+        self.raw_options = kwargs.deep_dup
+
+        super
+      end
+
+      # Generates a response by routing to the appropriate OpenAI API version.
+      #
+      # This method determines which API version to use based on the prompt context:
+      # - Uses Chat API if +api_version: :chat+ is specified or audio is present
+      # - Uses Responses API otherwise (default)
+      #
+      # @return [Object] The generation result from the selected API provider
+      #
+      # @see https://platform.openai.com/docs/guides/migrate-to-responses
+      def prompt
+        if api_version == :chat || context[:audio].present?
+          instrument("api_routing.provider.active_agent", api_type: :chat, api_version: api_version, has_audio: context[:audio].present?)
+          OpenAI::ChatProvider.new(raw_options).prompt
+        else # api_version == :responses || true
+          instrument("api_routing.provider.active_agent", api_type: :responses, api_version: api_version)
+          OpenAI::ResponsesProvider.new(raw_options).prompt
+        end
+      end
+
+      # Generates a preview by routing to the appropriate OpenAI API version.
+      #
+      # Routes to Chat API or Responses API using the same logic as {#prompt}.
+      #
+      # @return [String] markdown-formatted preview
+      # @see #prompt
+      def preview
+        if api_version == :chat || context[:audio].present?
+          OpenAI::ChatProvider.new(raw_options).preview
+        else # api_version == :responses || true
+          OpenAI::ResponsesProvider.new(raw_options).preview
+        end
+      end
+
+      protected
+
+      # Executes an embedding request via OpenAI's API.
+      #
+      # @param parameters [Hash] The embedding request parameters
+      # @return [Object] The embedding response from OpenAI
+      def api_embed_execute(parameters)
+        instrument("embeddings_request.provider.active_agent")
+        client.embeddings.create(**parameters).as_json.deep_symbolize_keys
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "requests/_types"
+
+require_relative "request"
+require_relative "options"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      # Type for Request model
+      class RequestType < ActiveModel::Type::Value
+        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
+
+        def serialize(value)
+          case value
+          when Request
+            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

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+require_relative "requests/response_format"
+require_relative "requests/prediction"
+require_relative "requests/provider_preferences"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      class Options < ActiveAgent::Providers::OpenAI::Options
+        attribute :base_url, :string, as: "https://openrouter.ai/api/v1"
+        attribute :app_name, :string, fallback: "ActiveAgent"
+        attribute :site_url, :string, fallback: "https://activeagents.ai/"
+
+        def initialize(kwargs = {})
+          kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
+
+          super(**deep_compact(kwargs.merge(
+            app_name: kwargs[:app_name] || resolve_app_name(kwargs),
+            site_url: kwargs[:site_url] || resolve_site_url(kwargs),
+          )))
+        end
+
+        def serialize
+          super.except(:app_name, :site_url)
+        end
+
+        # We fallback to ActiveAgent but allow empty strings to unset
+        def extra_headers
+          deep_compact(
+            "http-referer" => site_url.presence,
+            "x-title"      => app_name.presence
+          )
+        end
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs["api_key"] ||
+            ENV["OPENROUTER_API_KEY"] ||
+            ENV["OPEN_ROUTER_API_KEY"] ||
+            ENV["OPENROUTER_ACCESS_TOKEN"] ||
+            ENV["OPEN_ROUTER_ACCESS_TOKEN"]
+        end
+
+        # Not Used as Part of Open Router
+        def resolve_organization_id(kwargs) = nil
+        def resolve_project_id(kwargs)      = nil
+
+        def resolve_app_name(kwargs)
+          if defined?(Rails) && Rails.application
+            Rails.application.class.name.split("::").first
+          end
+        end
+
+        def resolve_site_url(kwargs)
+          # First check ActiveAgent kwargs
+          return kwargs[:default_url_options][:host] if kwargs.dig(:default_url_options, :host)
+
+          # Then check Rails routes default_url_options
+          if defined?(Rails) && Rails.application&.routes&.default_url_options&.any?
+            host     = Rails.application.routes.default_url_options[:host]
+            port     = Rails.application.routes.default_url_options[:port]
+            protocol = Rails.application.routes.default_url_options[:protocol] || "https"
+
+            if host
+              url = "#{protocol}://#{host}"
+              url += ":#{port}" if port && port != 80 && port != 443
+              return url
+            end
+          end
+
+          # Finally check ActionMailer options as fallback
+          if defined?(Rails) && Rails.application&.config&.action_mailer&.default_url_options
+            options = Rails.application.config.action_mailer.default_url_options
+            host = options[:host]
+            port = options[:port]
+            protocol = options[:protocol] || "https"
+
+            if host
+              url = "#{protocol}://#{host}"
+              url += ":#{port}" if port && port != 80 && port != 443
+              return url
+            end
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/_types"
+require_relative "requests/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      class Request < OpenAI::Chat::Request
+        # Prompting Options
+        attribute :model,           :string, fallback: "openrouter/auto"
+        attribute :response_format, Requests::ResponseFormatType.new
+        attribute :max_tokens,      :integer
+        attribute :stop # Can be string or array
+
+        # Messages array (required)
+        attribute :messages, Requests::Messages::MessagesType.new
+
+        # LLM Parameters
+        attribute :seed,               :integer
+        attribute :top_p,              :float
+        attribute :top_k,              :integer
+        attribute :frequency_penalty,  :float
+        attribute :presence_penalty,   :float
+        attribute :repetition_penalty, :float
+        attribute :top_logprobs,       :integer
+        attribute :min_p,              :float
+        attribute :top_a,              :float
+        attribute :logit_bias # Hash of token_id => bias value
+
+        # Tool calling (inherited from OpenAI but explicitly documented)
+        # attribute :tools, :json
+        # attribute :tool_choice, :json
+
+        # Predicted outputs
+        attribute :prediction, Requests::PredictionType.new
+
+        # OpenRouter-specific parameters
+        attribute :transforms,                                      default: -> { [] } # Array of strings
+        attribute :models,                                          default: -> { [] } # Array of model strings for fallback
+        attribute :route,    :string,                               default: "fallback"
+        attribute :provider, Requests::ProviderPreferencesType.new, default: {}
+        attribute :user,     :string # Stable identifier for end-users
+        attribute :plugins,  Requests::PluginsType.new # Array of plugin configurations (e.g., file-parser for PDFs)
+
+        # Validations for parameters with specific ranges
+        validates :max_tokens,         numericality: { greater_than_or_equal_to: 1 },                            allow_nil: true
+        validates :top_p,              numericality: { greater_than: 0, less_than_or_equal_to: 1 },              allow_nil: true
+        validates :top_k,              numericality: { greater_than_or_equal_to: 1 },                            allow_nil: true
+        validates :frequency_penalty,  numericality: { greater_than_or_equal_to: -2, less_than_or_equal_to: 2 }, allow_nil: true
+        validates :presence_penalty,   numericality: { greater_than_or_equal_to: -2, less_than_or_equal_to: 2 }, allow_nil: true
+        validates :repetition_penalty, numericality: { greater_than: 0, less_than_or_equal_to: 2 },              allow_nil: true
+        validates :min_p,              numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 },  allow_nil: true
+        validates :top_a,              numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 },  allow_nil: true
+        validates :route,              inclusion:    { in: [ "fallback" ] },                                     allow_nil: true
+
+        # Backwards Compatibility
+        delegate_attributes :data_collection, :enable_fallbacks, :sort, :ignore, :only, :quantizations, :max_price, to: :provider
+        alias_attribute :fallback_models, :models
+
+        # Common Format Compatability
+        def messages=(value)
+          case value
+          when Array
+            super((messages || []) | value)
+          else
+            super((messages || []) | [ value ])
+          end
+        end
+
+        # Common Format Compatability
+        def response_format=(value)
+          # If we are doing structured output, we need to ensure that we route to models that support it.
+          if %i[json_object json_schema].include?(value[:type].to_sym)
+            self.provider.require_parameters = true
+          end
+
+          super(value)
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/_types.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "messages/_types"
+require_relative "provider_preferences/_types"
+require_relative "plugins/_types"
+
+require_relative "message"
+require_relative "prediction"
+require_relative "provider_preferences"
+require_relative "response_format"
+require_relative "plugin"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Type for MaxPrice
+        class MaxPriceType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when MaxPrice
+              value
+            when Hash
+              MaxPrice.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to MaxPrice"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when MaxPrice
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+
+        # Type for Prediction
+        class PredictionType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when Prediction
+              value
+            when Hash
+              Prediction.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to Prediction"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when Prediction
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+
+        # Type for ProviderPreferences
+        class ProviderPreferencesType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when ProviderPreferences
+              value
+            when Hash
+              ProviderPreferences.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to ProviderPreferences"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when ProviderPreferences
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+
+        # Type for ResponseFormat
+        class ResponseFormatType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when ResponseFormat
+              value
+            when Hash
+              ResponseFormat.new(**value.deep_symbolize_keys)
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to ResponseFormat"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when ResponseFormat
+              value.serialize
+            when Hash
+              value
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+
+        # Type for Plugins (array of Plugin objects)
+        class PluginsType < ActiveModel::Type::Value
+          def cast(value)
+            case value
+            when Array
+              value.map do |item|
+                case item
+                when Plugin
+                  item
+                when Hash
+                  Plugin.new(**item.deep_symbolize_keys)
+                else
+                  raise ArgumentError, "Cannot cast #{item.class} to Plugin"
+                end
+              end
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot cast #{value.class} to Array of Plugins"
+            end
+          end
+
+          def serialize(value)
+            case value
+            when Array
+              value.map do |item|
+                case item
+                when Plugin
+                  item.serialize
+                when Hash
+                  item
+                else
+                  raise ArgumentError, "Cannot serialize #{item.class}"
+                end
+              end
+            when nil
+              nil
+            else
+              raise ArgumentError, "Cannot serialize #{value.class}"
+            end
+          end
+
+          def deserialize(value)
+            cast(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/message.rb

@@ -0,0 +1 @@
+require_relative "messages/assistant"

data/lib/active_agent/providers/open_router/requests/messages/_types.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/_types"
+
+require_relative "assistant"
+require_relative "user"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          # Type for Messages array - uses OpenRouter's MessageType
+          class MessagesType < OpenAI::Chat::Requests::Messages::MessagesType
+            def initialize
+              super
+              @message_type = MessageType.new
+            end
+          end
+
+          class MessageType < OpenAI::Chat::Requests::Messages::MessageType
+            def cast(value)
+              case value
+              when OpenAI::Chat::Requests::Messages::Base
+                value
+              when String
+                User.new(content: value)
+              when Hash
+                hash = value.deep_symbolize_keys
+                role = hash[:role]&.to_sym
+
+              case role
+              when :developer
+                OpenAI::Chat::Requests::Messages::Developer.new(**hash)
+              when :system
+                OpenAI::Chat::Requests::Messages::System.new(**hash)
+              when :user, nil
+                User.new(**hash)
+              when :assistant
+                Assistant.new(**hash)
+              when :tool
+                OpenAI::Chat::Requests::Messages::Tool.new(**hash)
+              when :function
+                OpenAI::Chat::Requests::Messages::Function.new(**hash)
+              else
+                raise ArgumentError, "Unknown message role: #{role.inspect}"
+              end
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to Message (expected Base, String, Hash, or nil)"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/messages/assistant.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          # Assistant message for OpenRouter API.
+          #
+          # Extends OpenAI's assistant message with OpenRouter-specific behavior.
+          # Drops reasoning fields during message reconstruction since they're not
+          # part of the standard request format.
+          class Assistant < OpenAI::Chat::Requests::Messages::Assistant
+            drop_attributes :reasoning, :reasoning_details
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router/requests/messages/content/_types.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/content/_types"
+require_relative "file"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            # Type for handling content (string or array of content parts) in OpenRouter.
+            #
+            # Extends OpenAI's ContentsType to use OpenRouter's ContentType which
+            # handles files differently (preserves data URI prefix).
+            class ContentsType < OpenAI::Chat::Requests::Messages::Content::ContentsType
+              def initialize
+                super
+                @content_type = ContentType.new
+              end
+            end
+
+            # Type for individual content items in OpenRouter.
+            #
+            # Uses OpenRouter's File class for file content which preserves
+            # the data URI prefix that OpenAI strips.
+            class ContentType < ActiveModel::Type::Value
+              def cast(value)
+                case value
+                when OpenAI::Chat::Requests::Messages::Content::Base
+                  value
+                when Hash
+                  hash = value.deep_symbolize_keys
+                  type = hash[:type]&.to_sym
+
+                  case type
+                  when :text
+                    OpenAI::Chat::Requests::Messages::Content::Text.new(**hash)
+                  when :image_url
+                    OpenAI::Chat::Requests::Messages::Content::Image.new(**hash)
+                  when :input_audio
+                    OpenAI::Chat::Requests::Messages::Content::Audio.new(**hash)
+                  when :file
+                    # Use OpenRouter's File class instead of OpenAI's
+                    File.new(**hash)
+                  when :refusal
+                    OpenAI::Chat::Requests::Messages::Content::Refusal.new(**hash)
+                  when nil
+                    # When type is nil, check for specific content keys to infer type
+                    if hash.key?(:text)
+                      OpenAI::Chat::Requests::Messages::Content::Text.new(**hash)
+                    elsif hash.key?(:image)
+                      OpenAI::Chat::Requests::Messages::Content::Image.new(**hash.merge(image_url: hash.delete(:image)))
+                    elsif hash.key?(:document)
+                      # Use OpenRouter's File class for document content
+                      File.new(**hash.merge(file: hash.delete(:document)))
+                    else
+                      raise ArgumentError, "Cannot determine content type from hash keys: #{hash.keys.inspect}"
+                    end
+                  else
+                    raise ArgumentError, "Unknown content type: #{type.inspect}"
+                  end
+                when String
+                  # Plain text string becomes text content
+                  OpenAI::Chat::Requests::Messages::Content::Text.new(text: value)
+                when nil
+                  nil
+                else
+                  raise ArgumentError, "Cannot cast #{value.class} to Content (expected Base, Hash, String, or nil)"
+                end
+              end
+
+              def serialize(value)
+                case value
+                when OpenAI::Chat::Requests::Messages::Content::Base
+                  value.serialize
+                when Hash
+                  value
+                when String
+                  { type: "text", text: value }
+                when nil
+                  nil
+                else
+                  raise ArgumentError, "Cannot serialize #{value.class} as Content"
+                end
+              end
+
+              def deserialize(value)
+                cast(value)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end