activeagent 0.6.3 → 1.0.0

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/open_ai/chat/requests/messages/content/files/details"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Messages
+          module Content
+            module Files
+              # File details for OpenRouter file attachments
+              #
+              # 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
+                # @!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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Plugin configuration for OpenRouter requests
+        #
+        # 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
+          validates :id, inclusion: { in: %w[file-parser] }, allow_nil: false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "pdf_config"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Plugins
+          # Type for PdfConfig
+          class PdfConfigType < ActiveModel::Type::Value
+            def cast(value)
+              case value
+              when PdfConfig
+                value
+              when Hash
+                PdfConfig.new(**value.deep_symbolize_keys)
+              when nil
+                nil
+              else
+                raise ArgumentError, "Cannot cast #{value.class} to PdfConfig"
+              end
+            end
+
+            def serialize(value)
+              case value
+              when PdfConfig
+                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

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        module Plugins
+          # PDF processing configuration for file-parser plugin
+          #
+          # OpenRouter provides multiple PDF processing engines with different
+          # capabilities and costs:
+          #
+          # - **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
+          #
+          # - **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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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
+          validates :content, presence: true, if: -> { type.present? }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "max_price"
+
+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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Maximum price configuration for 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
+          #   @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
+          validates :image,      numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :audio,      numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+          validates :request,    numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+
+          # Backwards Compatibility
+          alias_attribute :prompt_tokens, :prompt
+          alias_attribute :completion_tokens, :completion
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "provider_preferences/_types"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      module Requests
+        # Provider preferences for routing requests to specific providers
+        #
+        # 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
+          # @!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
+
+          # @!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
+
+          # @!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
+
+          # @!attribute zdr
+          #   @return [Boolean, nil] zero data retention mode (stricter privacy)
+          attribute :zdr, :boolean
+
+          # @!attribute order
+          #   @return [Array<String>] ordered list of provider slugs to try in sequence
+          attribute :order, default: -> { [] }
+
+          # @!attribute only
+          #   @return [Array<String>] allowlist of provider slugs (merged with account settings)
+          attribute :only, default: -> { [] }
+
+          # @!attribute ignore
+          #   @return [Array<String>] blocklist of provider slugs (merged with account settings)
+          attribute :ignore, default: -> { [] }
+
+          # @!attribute quantizations
+          #   @return [Array<String>] quantization levels to filter providers by
+          #     Options: int4, int8, fp4, fp6, fp8, fp16, bf16, fp32, unknown
+          attribute :quantizations, default: -> { [] }
+
+          # @!attribute sort
+          #   @return [String, nil] sorting strategy when order not specified
+          #     Options: price, throughput, latency
+          #     Note: disables load balancing when set
+          attribute :sort, :string
+
+          # @!attribute max_price
+          #   @return [MaxPrice, nil] maximum price constraints per token/operation
+          attribute :max_price, MaxPriceType.new
+
+          # Validations matching the schema
+          validates :data_collection, inclusion: { in: %w[deny allow] }, allow_nil: true
+          validates :sort, inclusion: { in: %w[price throughput latency] }, allow_nil: true
+          validates :quantizations, inclusion: {
+            in: [ %w[int4 int8 fp4 fp6 fp8 fp16 bf16 fp32 unknown].freeze ],
+            message: "must contain valid quantization levels"
+          }, allow_nil: true, if: -> { quantizations.is_a?(Array) && quantizations.any? }
+
+          # Backwards Compatibility
+          alias_attribute :enable_fallbacks, :allow_fallbacks
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+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
+          # @!attribute type
+          #   @return [String] response format type ('json_object' or 'json_schema')
+          attribute :type, :string
+
+          # @!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
+
+          # Validate that json_schema is present when type is json_schema
+          validate :validate_json_schema_presence
+
+          private
+
+          def validate_json_schema_presence
+            if type == "json_schema" && json_schema.blank?
+              errors.add(:json_schema, "must be present when type is 'json_schema'")
+            end
+
+            if json_schema.present? && json_schema.is_a?(Hash)
+              validate_json_schema_structure
+            end
+          end
+
+          def validate_json_schema_structure
+            unless json_schema[:name].present?
+              errors.add(:json_schema, "must include 'name' field")
+            end
+
+            if json_schema[:name].present? && json_schema[:name].length > 64
+              errors.add(:json_schema, "name must be 64 characters or less")
+            end
+
+            # Name must match pattern: a-z, A-Z, 0-9, underscores and dashes
+            if json_schema[:name].present? && json_schema[:name] !~ /^[a-zA-Z0-9_-]+$/
+              errors.add(:json_schema, "name must contain only a-z, A-Z, 0-9, underscores and dashes")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# 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)
+
+            [ openai_params, openrouter_params ]
+          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