activeagent 1.0.0.rc1 → 1.0.1

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

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

@@ -7,44 +7,85 @@ module ActiveAgent
     module OpenRouter
       module Requests
         # Provider preferences for routing requests to specific providers
-        # See: https://openrouter.ai/docs/provider-routing
+        #
+        # Controls how OpenRouter selects and routes requests to underlying model
+        # providers. Enables filtering by parameters, cost constraints, privacy
+        # settings, and provider-specific preferences.
+        #
+        # @example Basic provider routing
+        #   prefs = ProviderPreferences.new(
+        #     require_parameters: true,
+        #     allow_fallbacks: false
+        #   )
+        #
+        # @example Privacy-focused routing
+        #   prefs = ProviderPreferences.new(
+        #     data_collection: 'deny',
+        #     zdr: true
+        #   )
+        #
+        # @example Cost-optimized routing
+        #   prefs = ProviderPreferences.new(
+        #     sort: 'price',
+        #     max_price: { prompt: 0.01, completion: 0.03 }
+        #   )
+        #
+        # @example Provider ordering
+        #   prefs = ProviderPreferences.new(
+        #     order: ['OpenAI', 'Anthropic'],
+        #     ignore: ['Together']
+        #   )
+        #
+        # @see https://openrouter.ai/docs/provider-routing OpenRouter Provider Routing
+        # @see MaxPrice
         class ProviderPreferences < Common::BaseModel
-          # Whether to allow backup providers to serve requests
-          # - true: (default) when primary provider is unavailable, use next best provider
-          # - false: use only primary/custom provider, return upstream error if unavailable
+          # @!attribute allow_fallbacks
+          #   @return [Boolean, nil] whether to allow backup providers when primary is unavailable
+          #     - true: (default) use next best provider when primary unavailable
+          #     - false: only use primary/custom provider, return error if unavailable
           attribute :allow_fallbacks, :boolean
 
-          # Whether to filter providers to only those that support provided parameters
-          # If false, providers receive only parameters they support and ignore the rest
+          # @!attribute require_parameters
+          #   @return [Boolean, nil] whether to filter to providers supporting all parameters
+          #     - true: only use providers that support all provided parameters
+          #     - false: providers receive only the parameters they support
           attribute :require_parameters, :boolean
 
-          # Data collection setting
-          # - allow: (default) allow providers which store user data and may train on it
-          # - deny: use only providers which do not collect user data
+          # @!attribute data_collection
+          #   @return [String, nil] data collection preference
+          #     - 'allow': (default) allow providers which store/train on user data
+          #     - 'deny': only use providers that don't collect user data
           attribute :data_collection, :string
 
-          # Zero Data Retention - stricter privacy mode
+          # @!attribute zdr
+          #   @return [Boolean, nil] zero data retention mode (stricter privacy)
           attribute :zdr, :boolean
 
-          # Ordered list of provider slugs to try in order
+          # @!attribute order
+          #   @return [Array<String>] ordered list of provider slugs to try in sequence
           attribute :order, default: -> { [] }
 
-          # List of provider slugs to allow (merged with account-wide settings)
+          # @!attribute only
+          #   @return [Array<String>] allowlist of provider slugs (merged with account settings)
           attribute :only, default: -> { [] }
 
-          # List of provider slugs to ignore (merged with account-wide settings)
+          # @!attribute ignore
+          #   @return [Array<String>] blocklist of provider slugs (merged with account settings)
           attribute :ignore, default: -> { [] }
 
-          # List of quantization levels to filter providers by
-          # Options: int4, int8, fp4, fp6, fp8, fp16, bf16, fp32, unknown
+          # @!attribute quantizations
+          #   @return [Array<String>] quantization levels to filter providers by
+          #     Options: int4, int8, fp4, fp6, fp8, fp16, bf16, fp32, unknown
           attribute :quantizations, default: -> { [] }
 
-          # Sorting strategy to use if "order" is not specified
-          # Options: price, throughput, latency
-          # When set, no load balancing is performed
+          # @!attribute sort
+          #   @return [String, nil] sorting strategy when order not specified
+          #     Options: price, throughput, latency
+          #     Note: disables load balancing when set
           attribute :sort, :string
 
-          # Maximum price constraints (USD per million tokens)
+          # @!attribute max_price
+          #   @return [MaxPrice, nil] maximum price constraints per token/operation
           attribute :max_price, MaxPriceType.new
 
           # Validations matching the schema

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

@@ -4,11 +4,39 @@ module ActiveAgent
   module Providers
     module OpenRouter
       module Requests
+        # Response format configuration for structured output
+        #
+        # Enables JSON-formatted responses using OpenAI's structured output format.
+        # When using structured output, OpenRouter automatically sets
+        # provider.require_parameters=true to route to compatible models.
+        #
+        # @example JSON object format
+        #   format = ResponseFormat.new(type: 'json_object')
+        #
+        # @example JSON schema format
+        #   format = ResponseFormat.new(
+        #     type: 'json_schema',
+        #     json_schema: {
+        #       name: 'user_profile',
+        #       description: 'A user profile',
+        #       schema: { type: 'object', properties: { name: { type: 'string' } } },
+        #       strict: true
+        #     }
+        #   )
+        #
+        # @see https://openrouter.ai/docs/structured-outputs OpenRouter Structured Outputs
+        # @see https://platform.openai.com/docs/guides/structured-outputs OpenAI Structured Outputs
         class ResponseFormat < Common::BaseModel
-          # Type of response format (json_object, json_schema)
+          # @!attribute type
+          #   @return [String] response format type ('json_object' or 'json_schema')
           attribute :type, :string
 
-          # JSON schema configuration (only for json_schema type)
+          # @!attribute json_schema
+          #   @return [Hash, nil] JSON schema configuration (required when type is 'json_schema')
+          #   @option json_schema [String] :name schema name (max 64 chars, alphanumeric/underscore/dash)
+          #   @option json_schema [String] :description schema description
+          #   @option json_schema [Hash] :schema JSON schema definition
+          #   @option json_schema [Boolean] :strict whether to enforce strict schema adherence
           attribute :json_schema # Hash with name, description, schema, strict
 
           validates :type, inclusion: { in: %w[json_object json_schema] }, allow_nil: true

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+require_relative "../open_ai/chat/transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      # Provides transformation methods for normalizing OpenRouter parameters
+      # to work with OpenAI gem's native format plus OpenRouter extensions
+      #
+      # Leverages OpenAI::Chat::Transforms for base message normalization while
+      # adding handling for OpenRouter-specific parameters like plugins, provider
+      # preferences, and model fallbacks.
+      module Transforms
+        class << self
+          # Converts gem model object to hash via JSON round-trip
+          #
+          # @param gem_object [Object]
+          # @return [Hash] with symbolized keys
+          def gem_to_hash(gem_object)
+            OpenAI::Chat::Transforms.gem_to_hash(gem_object)
+          end
+
+          # Normalizes all request parameters for OpenRouter API
+          #
+          # Handles both OpenAI-compatible parameters and OpenRouter-specific extensions.
+          # OpenRouter-specific params (plugins, provider, transforms, models, route) are
+          # extracted and returned separately for manual serialization.
+          #
+          # @param params [Hash]
+          # @return [Array<Hash, Hash>] tuple of [openai_params, openrouter_params]
+          def normalize_params(params)
+            params = params.dup
+
+            # Extract OpenRouter-specific parameters
+            openrouter_params = {}
+            openrouter_params[:plugins] = params.delete(:plugins) if params.key?(:plugins)
+            openrouter_params[:provider] = params.delete(:provider) if params.key?(:provider)
+            openrouter_params[:transforms] = params.delete(:transforms) if params.key?(:transforms)
+            openrouter_params[:models] = params.delete(:models) if params.key?(:models)
+            openrouter_params[:route] = params.delete(:route) if params.key?(:route)
+
+            # Extract OpenRouter-specific sampling parameters not in OpenAI
+            openrouter_params[:top_k] = params.delete(:top_k) if params.key?(:top_k)
+            openrouter_params[:min_p] = params.delete(:min_p) if params.key?(:min_p)
+            openrouter_params[:top_a] = params.delete(:top_a) if params.key?(:top_a)
+            openrouter_params[:repetition_penalty] = params.delete(:repetition_penalty) if params.key?(:repetition_penalty)
+
+            # Handle response_format special logic for OpenRouter
+            # OpenRouter requires provider.require_parameters=true for structured output
+            if params[:response_format]
+              response_format = params[:response_format]
+              response_format_hash = response_format.is_a?(Hash) ? response_format : { type: response_format }
+
+              if %i[json_object json_schema].include?(response_format_hash[:type].to_sym)
+                openrouter_params[:provider] ||= {}
+                openrouter_params[:provider][:require_parameters] = true
+              end
+            end
+
+            # Use OpenAI transforms for the base parameters
+            openai_params = OpenAI::Chat::Transforms.normalize_params(params)
+
+            # Override tool_choice normalization for OpenRouter's "any" vs "required" difference
+            if openai_params[:tool_choice]
+              openai_params[:tool_choice] = normalize_tool_choice(openai_params[:tool_choice])
+            end
+
+            [ openai_params, openrouter_params ]
+          end
+
+          # Normalizes tools using OpenAI transforms
+          #
+          # @param tools [Array<Hash>]
+          # @return [Array<Hash>]
+          def normalize_tools(tools)
+            OpenAI::Chat::Transforms.normalize_tools(tools)
+          end
+
+          # Normalizes tool_choice for OpenRouter API differences
+          #
+          # OpenRouter uses "any" instead of OpenAI's "required" for forcing tool use.
+          # Converts common format to OpenRouter-specific format:
+          # - "required" (common) → "any" (OpenRouter)
+          # - Everything else delegates to OpenAI transforms
+          #
+          # @param tool_choice [String, Hash, Symbol]
+          # @return [String, Hash, Symbol]
+          def normalize_tool_choice(tool_choice)
+            # Convert "required" to OpenRouter's "any"
+            return "any" if tool_choice.to_s == "required"
+
+            # For everything else, use OpenAI transforms
+            OpenAI::Chat::Transforms.normalize_tool_choice(tool_choice)
+          end
+
+          # Normalizes messages using OpenAI transforms
+          #
+          # @param messages [Array, String, Hash, nil]
+          # @return [Array<OpenAI::Models::Chat::ChatCompletionMessageParam>, nil]
+          def normalize_messages(messages)
+            OpenAI::Chat::Transforms.normalize_messages(messages)
+          end
+
+          # Normalizes response_format for OpenRouter
+          #
+          # Delegates to OpenAI transforms. The special handling for structured output
+          # (setting provider.require_parameters=true) is handled in normalize_params.
+          #
+          # @param format [Hash, Symbol, String]
+          # @return [Hash]
+          def normalize_response_format(format)
+            OpenAI::Chat::Transforms.normalize_response_format(format)
+          end
+
+          # Cleans up serialized request for API submission
+          #
+          # Merges OpenAI-compatible params with OpenRouter-specific params.
+          #
+          # @param openai_hash [Hash] serialized OpenAI request
+          # @param openrouter_params [Hash] OpenRouter-specific parameters
+          # @param defaults [Hash] default values to remove
+          # @param gem_object [Object] original gem object
+          # @return [Hash] cleaned and merged request hash
+          def cleanup_serialized_request(openai_hash, openrouter_params, defaults, gem_object)
+            # Start with OpenAI cleanup
+            cleaned = OpenAI::Chat::Transforms.cleanup_serialized_request(openai_hash, defaults, gem_object)
+
+            # Merge OpenRouter-specific params, but skip default values
+            openrouter_params.each do |key, value|
+              # Skip if value is nil, empty, or matches the default
+              next if value.nil?
+              next if value.respond_to?(:empty?) && value.empty?
+              next if defaults.key?(key) && defaults[key] == value
+
+              cleaned[key] = serialize_openrouter_param(key, value)
+            end
+
+            cleaned
+          end
+
+          # Serializes OpenRouter-specific parameters
+          #
+          # @param key [Symbol]
+          # @param value [Object]
+          # @return [Object] serialized value
+          def serialize_openrouter_param(key, value)
+            case key
+            when :provider
+              # Serialize provider preferences object
+              value.respond_to?(:serialize) ? value.serialize : value
+            when :plugins
+              # Serialize plugins array
+              value.respond_to?(:map) ? value.map { |p| p.respond_to?(:serialize) ? p.serialize : p } : value
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_router_provider.rb

@@ -33,6 +33,20 @@ module ActiveAgent
 
       protected
 
+      # @see BaseProvider#prepare_prompt_request
+      # @return [Request]
+      def prepare_prompt_request
+        prepare_prompt_request_tools
+        super
+      end
+
+      # Returns true if tool_choice == "any" (OpenRouter's equivalent of "required").
+      #
+      # @return [Boolean]
+      def tool_choice_forces_required?
+        request.tool_choice == "any"
+      end
+
       # Merges streaming delta into the message with role cleanup.
       #
       # Overrides parent to handle OpenRouter's role copying behavior which duplicates
@@ -48,6 +62,15 @@ module ActiveAgent
 
         hash_merge_delta(message, delta)
       end
+
+      # @see BaseProvider#api_response_normalize
+      # @param api_response [OpenAI::Models::ChatCompletion]
+      # @return [Hash] normalized response hash
+      def api_response_normalize(api_response)
+        return api_response unless api_response
+
+        OpenAI::Chat::Transforms.gem_to_hash(api_response)
+      end
     end
   end
 end

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.0.0.rc1"
+  VERSION = "1.0.1"
 end