activeagent 0.6.3 → 1.0.0

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "json"
+require_relative "transforms"
+require_relative "requests/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      # Wraps OpenAI gem's CompletionCreateParams with OpenRouter-specific extensions
+      #
+      # Delegates to OpenAI::Models::Chat::CompletionCreateParams for OpenAI-compatible
+      # parameters while adding support for OpenRouter-specific features like plugins,
+      # provider preferences, model fallbacks, and extended sampling parameters.
+      #
+      # OpenRouter-specific parameters:
+      # - plugins: Array of plugin configurations (e.g., file-parser for PDFs)
+      # - provider: ProviderPreferences object with require_parameters, data_collection, etc.
+      # - transforms: Array of transformation strings
+      # - models: Array of model strings for fallback routing
+      # - route: Routing strategy (default: "fallback")
+      # - top_k, min_p, top_a, repetition_penalty: Extended sampling parameters
+      #
+      # @example Basic usage
+      #   request = Request.new(
+      #     model: "openai/gpt-4",
+      #     messages: [{role: "user", content: "Hello"}]
+      #   )
+      #
+      # @example With OpenRouter-specific features
+      #   request = Request.new(
+      #     model: "openai/gpt-4",
+      #     messages: [{role: "user", content: "Hello"}],
+      #     models: ["anthropic/claude-3", "openai/gpt-4"],
+      #     provider: {require_parameters: true}
+      #   )
+      class Request < SimpleDelegator
+        # Default parameter values
+        DEFAULTS = {
+          frequency_penalty: 0,
+          logprobs: false,
+          n: 1,
+          presence_penalty: 0,
+          temperature: 1,
+          top_p: 1,
+          route: "fallback",
+          models: [],
+          transforms: []
+        }.freeze
+
+        # @return [Boolean, nil]
+        attr_reader :stream
+
+        # @return [Hash] OpenRouter-specific parameters
+        attr_reader :openrouter_params
+
+        # Creates a new OpenRouter request
+        #
+        # @param params [Hash] request parameters
+        # @option params [String] :model model identifier (default: "openrouter/auto")
+        # @option params [Array, String, Hash] :messages required conversation messages
+        # @option params [Array] :plugins plugin configurations
+        # @option params [Hash] :provider provider preferences
+        # @option params [Array<String>] :transforms transformation strings
+        # @option params [Array<String>] :models fallback model list
+        # @option params [String] :route routing strategy
+        # @option params [Integer] :top_k sampling parameter
+        # @option params [Float] :min_p minimum probability sampling
+        # @option params [Float] :top_a top-a sampling
+        # @option params [Float] :repetition_penalty repetition penalty
+        # @raise [ArgumentError] when parameters are invalid
+        def initialize(**params)
+          # Step 1: Extract stream flag
+          @stream = params[:stream]
+
+          # Step 2: Apply defaults
+          params = apply_defaults(params)
+
+          # Step 3: Normalize parameters and split into OpenAI vs OpenRouter-specific
+          # This handles response_format special logic for structured output
+          openai_params, @openrouter_params = Transforms.normalize_params(params)
+
+          # Step 4: Create gem model with OpenAI-compatible params
+          gem_model = ::OpenAI::Models::Chat::CompletionCreateParams.new(**openai_params)
+
+          # Step 5: Delegate to the gem model
+          super(gem_model)
+        rescue ArgumentError => e
+          raise ArgumentError, "Invalid OpenRouter request parameters: #{e.message}"
+        end
+
+        # Serializes request for API submission
+        #
+        # Merges OpenAI-compatible parameters with OpenRouter-specific extensions.
+        #
+        # @return [Hash] cleaned request hash
+        def serialize
+          # Get OpenAI params from gem model
+          openai_hash = Transforms.gem_to_hash(__getobj__)
+
+          # Merge with OpenRouter-specific params
+          Transforms.cleanup_serialized_request(openai_hash, @openrouter_params, DEFAULTS, __getobj__)
+        end
+
+        # @return [Array<Hash>, nil]
+        def messages
+          __getobj__.instance_variable_get(:@data)[:messages]
+        end
+
+        # Sets messages with normalization
+        #
+        # Merges new messages with existing ones for compatibility.
+        #
+        # @param value [Array, String, Hash]
+        # @return [void]
+        def messages=(value)
+          normalized_value = Transforms.normalize_messages(value)
+          current_messages = messages || []
+
+          # Merge behavior for OpenRouter compatibility
+          merged = current_messages | Array(normalized_value)
+          __getobj__.instance_variable_get(:@data)[:messages] = merged
+        end
+
+        # Alias for messages (common format compatibility)
+        #
+        # @return [Array<Hash>, nil]
+        def message
+          messages
+        end
+
+        # @param value [Array, String, Hash]
+        # @return [void]
+        def message=(value)
+          self.messages = value
+        end
+
+        # Sets instructions as developer messages
+        #
+        # Prepends developer messages to the messages array.
+        #
+        # @param values [Array<String>, String]
+        # @return [void]
+        def instructions=(*values)
+          instructions_messages = OpenAI::Chat::Transforms.normalize_instructions(values.flatten)
+          current_messages = messages || []
+          self.messages = instructions_messages + current_messages
+        end
+
+        # Accessor for OpenRouter-specific provider preferences
+        #
+        # @return [Hash, nil]
+        def provider
+          @openrouter_params[:provider]
+        end
+
+        # Sets provider preferences
+        #
+        # @param value [Hash]
+        # @return [void]
+        def provider=(value)
+          @openrouter_params[:provider] = value
+        end
+
+        # Accessor for OpenRouter plugins
+        #
+        # @return [Array, nil]
+        def plugins
+          @openrouter_params[:plugins]
+        end
+
+        # Sets plugins
+        #
+        # @param value [Array]
+        # @return [void]
+        def plugins=(value)
+          @openrouter_params[:plugins] = value
+        end
+
+        # Accessor for OpenRouter transforms
+        #
+        # @return [Array]
+        def transforms
+          @openrouter_params[:transforms] || []
+        end
+
+        # Sets transforms
+        #
+        # @param value [Array]
+        # @return [void]
+        def transforms=(value)
+          @openrouter_params[:transforms] = value
+        end
+
+        # Accessor for fallback models
+        #
+        # @return [Array]
+        def models
+          @openrouter_params[:models] || []
+        end
+
+        # Sets fallback models
+        #
+        # @param value [Array]
+        # @return [void]
+        def models=(value)
+          @openrouter_params[:models] = value
+        end
+
+        # Alias for backwards compatibility
+        alias_method :fallback_models, :models
+        alias_method :fallback_models=, :models=
+
+        # Accessor for routing strategy
+        #
+        # @return [String]
+        def route
+          @openrouter_params[:route] || DEFAULTS[:route]
+        end
+
+        # Sets routing strategy
+        #
+        # @param value [String]
+        # @return [void]
+        def route=(value)
+          @openrouter_params[:route] = value
+        end
+
+        private
+
+        # @api private
+        # @param params [Hash]
+        # @return [Hash]
+        def apply_defaults(params)
+          # Set default model if not provided
+          params[:model] ||= "openrouter/auto"
+
+          # Apply other defaults
+          DEFAULTS.each do |key, value|
+            params[key] = value unless params.key?(key)
+          end
+
+          params
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "messages/_types"
+require_relative "provider_preferences/_types"
+require_relative "plugins/_types"
+
+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/messages/_types.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          # ActiveModel type for casting and normalizing messages
+          #
+          # Delegates to OpenRouter transforms which use OpenAI's message normalization.
+          class MessagesType < ActiveModel::Type::Value
+            # Casts value to normalized messages array
+            #
+            # @param value [Array, String, Hash, nil]
+            # @return [Array, nil]
+            def cast(value)
+              return nil if value.nil?
+              Transforms.normalize_messages(value)
+            end
+
+            # Serializes messages to hash array
+            #
+            # @param value [Array, nil]
+            # @return [Array, nil]
+            def serialize(value)
+              return nil if value.nil?
+
+              # If already serialized as hashes, return as-is
+              return value if value.is_a?(Array) && value.all? { |m| m.is_a?(Hash) }
+
+              # Otherwise convert gem objects to hashes
+              value.map { |msg| Transforms.gem_to_hash(msg) }
+            end
+
+            # @param value [Object]
+            # @return [Array, nil]
+            def deserialize(value)
+              cast(value)
+            end
+          end
+
+          # Kept for backwards compatibility but delegates to MessagesType
+          class MessageType < MessagesType
+            def cast(value)
+              # Single message - wrap in array then unwrap
+              result = super(value.is_a?(Array) ? value : [ value ])
+              result&.first
+            end
+          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

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/content/base"
+require_relative "files/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            # File content part for OpenRouter messages
+            #
+            # Represents a file attachment in a message. Unlike OpenAI which strips
+            # the data URI prefix, OpenRouter preserves it in the file_data field.
+            #
+            # @example PDF file attachment
+            #   file = File.new(
+            #     file: {
+            #       file_data: 'data:application/pdf;base64,JVBERi0...',
+            #       filename: 'document.pdf'
+            #     }
+            #   )
+            #
+            # @see Files::Details
+            # @see https://openrouter.ai/docs/file-uploads OpenRouter File Uploads
+            class File < OpenAI::Chat::Requests::Messages::Content::Base
+              # @!attribute type
+              #   @return [String] always "file"
+              attribute :type, :string, as: "file"
+
+              # @!attribute file
+              #   @return [Files::Details] file details with data URI
+              attribute :file, Files::DetailsType.new
+
+              validates :file, presence: true
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "details"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            module Files
+              # Type for the nested file object in OpenRouter.
+              #
+              # Uses OpenRouter's Details class which preserves the data URI prefix.
+              class DetailsType < ActiveModel::Type::Value
+                def cast(value)
+                  case value
+                  when Details
+                    value
+                  when Hash
+                    Details.new(**value.deep_symbolize_keys)
+                  when String
+                    # Accept both data URIs and plain base64, but preserve the format
+                    if value.start_with?("data:")
+                      Details.new(file_data: value)
+                    elsif value.match?(%r{\Ahttps?://})
+                      raise ArgumentError, "HTTP/S URLs are not supported. Use a base64 data URI instead"
+                    else
+                      Details.new(file_data: value)
+                    end
+                  when nil
+                    nil
+                  else
+                    raise ArgumentError, "Cannot cast #{value.class} to File::Details"
+                  end
+                end
+
+                def serialize(value)
+                  case value
+                  when Details
+                    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
+  end
+end