activeagent 1.0.0.rc1 → 1.0.1

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

@@ -8,11 +8,48 @@ require_relative "requests/provider_preferences"
 module ActiveAgent
   module Providers
     module OpenRouter
+      # Configuration options for OpenRouter provider
+      #
+      # Extends OpenAI::Options with OpenRouter-specific settings including
+      # HTTP-Referer and X-Title headers for app identification and ranking.
+      #
+      # @example Basic configuration
+      #   options = Options.new(
+      #     api_key: 'sk-or-v1-...',
+      #     app_name: 'MyApp',
+      #     site_url: 'https://myapp.com'
+      #   )
+      #
+      # @example Rails auto-configuration
+      #   # Automatically resolves app_name from Rails.application
+      #   # and site_url from routes.default_url_options
+      #   options = Options.new(api_key: ENV['OPENROUTER_API_KEY'])
+      #
+      # @see https://openrouter.ai/docs/api-keys OpenRouter API Keys
+      # @see https://openrouter.ai/docs/rankings OpenRouter App Rankings
       class Options < ActiveAgent::Providers::OpenAI::Options
+        # @!attribute base_url
+        #   @return [String] API endpoint (default: "https://openrouter.ai/api/v1")
         attribute :base_url, :string, as: "https://openrouter.ai/api/v1"
+
+        # @!attribute app_name
+        #   @return [String] application name for X-Title header (default: "ActiveAgent" or Rails app name)
         attribute :app_name, :string, fallback: "ActiveAgent"
+
+        # @!attribute site_url
+        #   @return [String] site URL for HTTP-Referer header (default: "https://activeagents.ai/" or Rails URL)
         attribute :site_url, :string, fallback: "https://activeagents.ai/"
 
+        # Creates new OpenRouter options with auto-resolution
+        #
+        # Automatically resolves app_name from Rails application name and
+        # site_url from Rails routes/ActionMailer default_url_options.
+        #
+        # @param kwargs [Hash] configuration options
+        # @option kwargs [String] :api_key OpenRouter API key
+        # @option kwargs [String] :app_name application name for rankings
+        # @option kwargs [String] :site_url site URL for rankings
+        # @return [Options]
         def initialize(kwargs = {})
           kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
 
@@ -22,11 +59,22 @@ module ActiveAgent
           )))
         end
 
+        # Serializes options for API requests
+        #
+        # Excludes app_name and site_url as they're sent via headers.
+        #
+        # @return [Hash] serialized options
         def serialize
           super.except(:app_name, :site_url)
         end
 
-        # We fallback to ActiveAgent but allow empty strings to unset
+        # Returns extra headers for OpenRouter API
+        #
+        # Maps app_name and site_url to OpenRouter's required headers:
+        # - HTTP-Referer: site_url
+        # - X-Title: app_name
+        #
+        # @return [Hash] headers hash
         def extra_headers
           deep_compact(
             "http-referer" => site_url.presence,

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

@@ -1,81 +1,267 @@
 # 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
+
+        # @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
 
-        # 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
+        # Gets tool_choice bypassing gem validation
+        #
+        # OpenRouter supports "any" which isn't valid in OpenAI gem types.
+        #
+        # @return [String, Hash, nil]
+        def tool_choice
+          __getobj__.instance_variable_get(:@data)[:tool_choice]
+        end
+
+        # Sets tool_choice bypassing gem validation
+        #
+        # OpenRouter supports "any" which isn't valid in OpenAI gem types,
+        # so we bypass the gem's type validation by setting @data directly.
+        #
+        # @param value [String, Hash, nil]
+        # @return [void]
+        def tool_choice=(value)
+          __getobj__.instance_variable_get(:@data)[:tool_choice] = value
+        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