activeagent 1.0.0.rc1 → 1.0.0

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

@@ -1,81 +1,247 @@
 # frozen_string_literal: true
 
-require_relative "../open_ai/_types"
+require "delegate"
+require "json"
+require_relative "transforms"
 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
+      # 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)
-          case value
-          when Array
-            super((messages || []) | value)
-          else
-            super((messages || []) | [ value ])
-          end
+          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
 
-        # 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
+        # @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
 
-          super(value)
+          params
         end
       end
     end

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

@@ -4,7 +4,6 @@ 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"

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

@@ -1,55 +1,52 @@
 # frozen_string_literal: true
 
-require "active_agent/providers/open_ai/chat/requests/messages/_types"
-
-require_relative "assistant"
-require_relative "user"
+require_relative "../../transforms"
 
 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
+          # 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
 
-          class MessageType < OpenAI::Chat::Requests::Messages::MessageType
+          # Kept for backwards compatibility but delegates to MessagesType
+          class MessageType < MessagesType
             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
+              # Single message - wrap in array then unwrap
+              result = super(value.is_a?(Array) ? value : [ value ])
+              result&.first
             end
           end
         end

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

@@ -9,12 +9,28 @@ module ActiveAgent
       module Requests
         module Messages
           module Content
-            # File content part for OpenRouter.
+            # File content part for OpenRouter messages
             #
-            # Uses OpenRouter's Files::DetailsType which preserves the data URI prefix
-            # instead of stripping it like OpenAI does.
+            # 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

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

@@ -9,12 +9,23 @@ module ActiveAgent
         module Messages
           module Content
             module Files
-              # Represents the nested file object within File content part for OpenRouter.
+              # File details for OpenRouter file attachments
               #
-              # Unlike OpenAI which strips the data URI prefix, OpenRouter keeps it intact
-              # (e.g., data:application/pdf;base64,) in the file_data field.
+              # Represents the nested file object within a file content part.
+              # Unlike OpenAI which strips the data URI prefix (e.g., data:application/pdf;base64,),
+              # OpenRouter requires it to be present in the file_data field.
+              #
+              # @example With data URI
+              #   details = Details.new(
+              #     file_data: 'data:application/pdf;base64,JVBERi0xLjQK...',
+              #     filename: 'report.pdf'
+              #   )
+              #
+              # @see Content::File
               class Details < OpenAI::Chat::Requests::Messages::Content::Files::Details
-                # Override the setter to NOT strip the data URI prefix
+                # @!attribute file_data
+                #   @return [String] file data with data URI prefix intact
+                #     Format: "data:<mime-type>;base64,<base64-data>"
                 attribute :file_data, :string
               end
             end

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

@@ -4,16 +4,32 @@ module ActiveAgent
   module Providers
     module OpenRouter
       module Requests
-        # Represents a plugin configuration for OpenRouter requests.
-        # Currently supports the file-parser plugin for PDF processing.
+        # Plugin configuration for OpenRouter requests
         #
-        # @example
+        # OpenRouter supports plugins that enhance model capabilities.
+        # Currently supports the file-parser plugin for processing PDF documents.
+        #
+        # @example File parser plugin with PDF text extraction
         #   plugin = Plugin.new(
         #     id: 'file-parser',
         #     pdf: { engine: 'pdf-text' }
         #   )
+        #
+        # @example File parser plugin with OCR
+        #   plugin = Plugin.new(
+        #     id: 'file-parser',
+        #     pdf: { engine: 'mistral-ocr' }
+        #   )
+        #
+        # @see https://openrouter.ai/docs/plugins OpenRouter Plugins
+        # @see Plugins::PdfConfig
         class Plugin < Common::BaseModel
+          # @!attribute id
+          #   @return [String] plugin identifier (currently only 'file-parser' is supported)
           attribute :id, :string
+
+          # @!attribute pdf
+          #   @return [Plugins::PdfConfig, nil] PDF processing configuration
           attribute :pdf, Plugins::PdfConfigType.new
 
           validates :id, presence: true

data/lib/active_agent/providers/open_router/requests/plugins/pdf_config.rb

@@ -5,19 +5,41 @@ module ActiveAgent
     module OpenRouter
       module Requests
         module Plugins
-          # Configuration for PDF processing in the file-parser plugin.
+          # PDF processing configuration for file-parser plugin
           #
-          # OpenRouter provides several PDF processing engines:
-          # - "mistral-ocr": Best for scanned documents or PDFs with images ($2 per 1,000 pages)
-          # - "pdf-text": Best for well-structured PDFs with clear text content (Free)
-          # - "native": Only available for models that support file input natively (charged as input tokens)
+          # OpenRouter provides multiple PDF processing engines with different
+          # capabilities and costs:
           #
-          # If you don't explicitly specify an engine, OpenRouter will default first to the model's
-          # native file processing capabilities, and if that's not available, will use the "mistral-ocr" engine.
+          # - **mistral-ocr**: Best for scanned documents or PDFs with images
+          #   - Cost: $2 per 1,000 pages
+          #   - Use when: Document is image-heavy or has poor text extraction
           #
-          # @example
+          # - **pdf-text**: Best for well-structured PDFs with clear text content
+          #   - Cost: Free
+          #   - Use when: Document has clean, extractable text
+          #
+          # - **native**: Use model's native file processing capabilities
+          #   - Cost: Charged as input tokens
+          #   - Use when: Model supports native file input
+          #
+          # If no engine is specified, OpenRouter defaults to the model's native
+          # file processing if available, otherwise uses mistral-ocr.
+          #
+          # @example Text extraction (free)
           #   pdf_config = PdfConfig.new(engine: 'pdf-text')
+          #
+          # @example OCR for scanned documents
+          #   pdf_config = PdfConfig.new(engine: 'mistral-ocr')
+          #
+          # @example Use model's native processing
+          #   pdf_config = PdfConfig.new(engine: 'native')
+          #
+          # @see https://openrouter.ai/docs/plugins#file-parser OpenRouter File Parser Plugin
+          # @see Plugin
           class PdfConfig < Common::BaseModel
+            # @!attribute engine
+            #   @return [String, nil] PDF processing engine
+            #     Options: 'mistral-ocr', 'pdf-text', 'native'
             attribute :engine, :string
 
             validates :engine, inclusion: { in: %w[mistral-ocr pdf-text native] }, allow_nil: true

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

@@ -4,8 +4,25 @@ module ActiveAgent
   module Providers
     module OpenRouter
       module Requests
+        # Prediction configuration for prefilling responses
+        #
+        # Allows prefilling the start of the model's response. When provided,
+        # the model continues from this predicted content.
+        #
+        # @example Content prediction
+        #   prediction = Prediction.new(
+        #     type: 'content',
+        #     content: 'Once upon a time'
+        #   )
+        #
+        # @see https://platform.openai.com/docs/api-reference/chat/create#chat-create-prediction
         class Prediction < Common::BaseModel
+          # @!attribute type
+          #   @return [String] prediction type (currently only 'content' is supported)
           attribute :type, :string
+
+          # @!attribute content
+          #   @return [String] predicted content to prefill the response
           attribute :content, :string
 
           validates :type, inclusion: { in: %w[content] }, allow_nil: true

data/lib/active_agent/providers/open_router/requests/provider_preferences/max_price.rb

@@ -5,14 +5,48 @@ module ActiveAgent
     module OpenRouter
       module Requests
         # Maximum price configuration for provider routing
-        # Specifies USD price per million tokens for different operations
-        # See: https://openrouter.ai/docs/provider-routing
+        #
+        # Specifies maximum acceptable prices (in USD per million tokens or per
+        # operation) for filtering providers. OpenRouter will only route to
+        # providers within these price constraints.
+        #
+        # @example Setting prompt and completion limits
+        #   max_price = MaxPrice.new(
+        #     prompt: 0.01,      # $0.01 per million input tokens
+        #     completion: 0.03   # $0.03 per million output tokens
+        #   )
+        #
+        # @example Setting all constraints
+        #   max_price = MaxPrice.new(
+        #     prompt: 0.01,
+        #     completion: 0.03,
+        #     image: 0.001,
+        #     audio: 0.002,
+        #     request: 0.0001
+        #   )
+        #
+        # @see https://openrouter.ai/docs/provider-routing OpenRouter Provider Routing
+        # @see ProviderPreferences
         class MaxPrice < Common::BaseModel
-          attribute :prompt,     :float # Price per million prompt tokens (input)
-          attribute :completion, :float # Price per million completion tokens (output)
-          attribute :image,      :float # Price per image
-          attribute :audio,      :float # Price per audio unit
-          attribute :request,    :float # Price per request
+          # @!attribute prompt
+          #   @return [Float, nil] maximum price per million prompt tokens (input)
+          attribute :prompt,     :float
+
+          # @!attribute completion
+          #   @return [Float, nil] maximum price per million completion tokens (output)
+          attribute :completion, :float
+
+          # @!attribute image
+          #   @return [Float, nil] maximum price per image operation
+          attribute :image,      :float
+
+          # @!attribute audio
+          #   @return [Float, nil] maximum price per audio operation
+          attribute :audio,      :float
+
+          # @!attribute request
+          #   @return [Float, nil] maximum price per request
+          attribute :request,    :float
 
           validates :prompt,     numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
           validates :completion, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true