open_router_enhanced 1.2.5 → 2.0.1

data/docs/tools.md

@@ -9,7 +9,7 @@ The OpenRouter gem provides comprehensive support for OpenRouter's function call
 weather_tool = OpenRouter::Tool.define do
   name "get_weather"
   description "Get current weather for a location"
-  
+
   parameters do
     string :location, required: true, description: "City name or coordinates"
     string :units, enum: ["celsius", "fahrenheit"], description: "Temperature units"
@@ -23,6 +23,37 @@ response = client.complete(
   tools: [weather_tool],
   tool_choice: "auto"
 )
+```
+
+## Using CompletionOptions (v2.0+)
+
+For cleaner, reusable configurations, use the `CompletionOptions` class:
+
+```ruby
+# Create reusable tool configuration
+tool_opts = OpenRouter::CompletionOptions.new(
+  model: "anthropic/claude-3.5-sonnet",
+  tools: [weather_tool, calculator_tool],
+  tool_choice: "auto",
+  max_tokens: 1000
+)
+
+# Use with complete
+response = client.complete(messages, tool_opts)
+
+# Override tool_choice per request
+response = client.complete(messages, tool_opts, tool_choice: "required")
+
+# Configure parallel tool calling
+parallel_opts = OpenRouter::CompletionOptions.new(
+  model: "openai/gpt-4o",
+  tools: tools,
+  tool_choice: "auto",
+  parallel_tool_calls: true  # Allow multiple tool calls simultaneously
+)
+```
+
+All keyword argument patterns continue to work for backward compatibility.
 
 # Handle tool calls
 if response.has_tool_calls?

data/lib/open_router/client.rb

@@ -4,7 +4,6 @@ require "active_support/core_ext/object/blank"
 require "active_support/core_ext/hash/indifferent_access"
 
 require_relative "http"
-require "pry"
 
 module OpenRouter
   class ServerError < StandardError; end
@@ -13,15 +12,19 @@ module OpenRouter
   class Client
     include OpenRouter::HTTP
 
-    attr_reader :callbacks, :usage_tracker
+    attr_reader :callbacks, :usage_tracker, :configuration
 
     # Initializes the client with optional configurations.
     def initialize(access_token: nil, request_timeout: nil, uri_base: nil, extra_headers: {}, track_usage: true)
-      OpenRouter.configuration.access_token = access_token if access_token
-      OpenRouter.configuration.request_timeout = request_timeout if request_timeout
-      OpenRouter.configuration.uri_base = uri_base if uri_base
-      OpenRouter.configuration.extra_headers = extra_headers if extra_headers.any?
-      yield(OpenRouter.configuration) if block_given?
+      # Build a per-instance configuration to avoid mutating the global singleton,
+      # which would cause credential leakage across Client instances in concurrent use.
+      @configuration = OpenRouter.configuration.dup
+      @configuration.extra_headers = OpenRouter.configuration.extra_headers.dup
+      @configuration.access_token = access_token if access_token
+      @configuration.request_timeout = request_timeout if request_timeout
+      @configuration.uri_base = uri_base if uri_base
+      @configuration.extra_headers = @configuration.extra_headers.merge(extra_headers) if extra_headers.any?
+      yield(@configuration) if block_given?
 
       # Instance-level tracking of capability warnings to avoid memory leaks
       @capability_warnings_shown = Set.new
@@ -41,10 +44,6 @@ module OpenRouter
       @usage_tracker = UsageTracker.new if @track_usage
     end
 
-    def configuration
-      OpenRouter.configuration
-    end
-
     # Register a callback for a specific event
     #
     # @param event [Symbol] The event to register for (:before_request, :after_response, :on_tool_call, :on_error, :on_stream_chunk, :on_healing)
@@ -92,27 +91,31 @@ module OpenRouter
     end
 
     # Performs a chat completion request to the OpenRouter API.
-    # @param messages [Array<Hash>] Array of message hashes with role and content, like [{role: "user", content: "What is the meaning of life?"}]
-    # @param model [String|Array] Model identifier, or array of model identifiers if you want to fallback to the next model in case of failure
-    # @param providers [Array<String>] Optional array of provider identifiers, ordered by priority
-    # @param transforms [Array<String>] Optional array of strings that tell OpenRouter to apply a series of transformations to the prompt before sending it to the model. Transformations are applied in-order
-    # @param plugins [Array<Hash>] Optional array of plugin hashes like [{id: "response-healing"}]. Available plugins: response-healing, web-search, pdf-inputs
-    # @param tools [Array<Tool>] Optional array of Tool objects or tool definition hashes for function calling
-    # @param tool_choice [String|Hash] Optional tool choice: "auto", "none", "required", or specific tool selection
-    # @param response_format [Hash] Optional response format for structured outputs
-    # @param prediction [Hash] Optional predicted output for latency reduction, e.g. {type: "content", content: "predicted text"}
-    # @param extras [Hash] Optional hash of model-specific parameters to send to the OpenRouter API
+    #
+    # @param messages [Array<Hash>] Array of message hashes with role and content
+    # @param options [CompletionOptions, Hash, nil] Options object or hash with configuration
     # @param stream [Proc, nil] Optional callable object for streaming
-    # @return [Response] The completion response wrapped in a Response object.
-    # rubocop:disable Metrics/ParameterLists
-    def complete(messages, model: "openrouter/auto", providers: [], transforms: [], plugins: [], tools: [], tool_choice: nil,
-                 response_format: nil, force_structured_output: nil, prediction: nil, extras: {}, stream: nil)
-      # rubocop:enable Metrics/ParameterLists
-      parameters = prepare_base_parameters(messages, model, providers, transforms, plugins, prediction, stream, extras)
-      forced_extraction = configure_tools_and_structured_outputs!(parameters, model, tools, tool_choice,
-                                                                  response_format, force_structured_output)
-      configure_plugins!(parameters, response_format, stream)
-      validate_vision_support(model, messages)
+    # @param kwargs [Hash] Additional options (merged with options parameter)
+    # @return [Response] The completion response wrapped in a Response object
+    #
+    # @example Simple usage (unchanged)
+    #   client.complete(messages, model: "gpt-4")
+    #
+    # @example With CompletionOptions
+    #   opts = CompletionOptions.new(model: "gpt-4", temperature: 0.7, tools: my_tools)
+    #   client.complete(messages, opts)
+    #
+    # @example Hash options
+    #   client.complete(messages, { model: "gpt-4", temperature: 0.7 })
+    #
+    # @example Options with override
+    #   client.complete(messages, base_opts, temperature: 0.9)
+    def complete(messages, options = nil, stream: nil, **kwargs)
+      opts = normalize_options(options, kwargs)
+      parameters = prepare_base_parameters(messages, opts, stream)
+      forced_extraction = configure_tools_and_structured_outputs!(parameters, opts)
+      configure_plugins!(parameters, opts.response_format, stream)
+      validate_vision_support(opts.model, messages)
 
       # Trigger before_request callbacks
       trigger_callbacks(:before_request, parameters)
@@ -120,10 +123,11 @@ module OpenRouter
       raw_response = execute_request(parameters)
       validate_response!(raw_response, stream)
 
-      response = build_response(raw_response, response_format, forced_extraction)
+      response = build_response(raw_response, opts.response_format, forced_extraction)
 
       # Track usage if enabled
-      @usage_tracker&.track(response, model: model.is_a?(String) ? model : model.first)
+      model_for_tracking = opts.model.is_a?(String) ? opts.model : opts.model.first
+      @usage_tracker&.track(response, model: model_for_tracking)
 
       # Trigger after_response callbacks
       trigger_callbacks(:after_response, response)
@@ -152,39 +156,42 @@ module OpenRouter
     # This is an OpenAI-compatible stateless API with support for reasoning.
     #
     # @param input [String, Array] The input text or structured message array
-    # @param model [String] Model identifier (e.g., "openai/o4-mini")
-    # @param reasoning [Hash, nil] Optional reasoning config, e.g. {effort: "high"}
-    #   Effort levels: "minimal", "low", "medium", "high"
-    # @param tools [Array<Tool, Hash>] Optional array of tool definitions
-    # @param tool_choice [String, Hash, nil] Optional: "auto", "none", "required", or specific tool
-    # @param max_output_tokens [Integer, nil] Maximum tokens to generate
-    # @param temperature [Float, nil] Sampling temperature (0-2)
-    # @param top_p [Float, nil] Nucleus sampling parameter (0-1)
-    # @param extras [Hash] Additional parameters to pass to the API
+    # @param options [CompletionOptions, Hash, nil] Options object or hash with configuration
+    # @param kwargs [Hash] Additional options (merged with options parameter)
     # @return [ResponsesResponse] The response wrapped in a ResponsesResponse object
     #
     # @example Basic usage
     #   response = client.responses("What is 2+2?", model: "openai/o4-mini")
     #   puts response.content
     #
-    # @example With reasoning
-    #   response = client.responses(
-    #     "Solve this step by step: What is 15% of 80?",
+    # @example With reasoning using CompletionOptions
+    #   opts = CompletionOptions.new(
     #     model: "openai/o4-mini",
     #     reasoning: { effort: "high" }
     #   )
+    #   response = client.responses("Solve this step by step: What is 15% of 80?", opts)
     #   puts response.reasoning_summary
     #   puts response.content
-    def responses(input, model:, reasoning: nil, tools: [], tool_choice: nil,
-                  max_output_tokens: nil, temperature: nil, top_p: nil, extras: {})
-      parameters = { model: model, input: input }
-      parameters[:reasoning] = reasoning if reasoning
-      parameters[:tools] = serialize_tools_for_responses(tools) if tools.any?
-      parameters[:tool_choice] = tool_choice if tool_choice
-      parameters[:max_output_tokens] = max_output_tokens if max_output_tokens
-      parameters[:temperature] = temperature if temperature
-      parameters[:top_p] = top_p if top_p
-      parameters.merge!(extras)
+    #
+    # @example With kwargs (still works)
+    #   response = client.responses("Question", model: "openai/o4-mini", reasoning: { effort: "high" })
+    def responses(input, options = nil, **kwargs)
+      opts = normalize_options(options, kwargs)
+
+      # Model is required for Responses API
+      if opts.model == "openrouter/auto"
+        raise ArgumentError, "model is required for responses API (cannot use default 'openrouter/auto')"
+      end
+
+      parameters = { model: opts.model, input: input }
+      parameters[:reasoning] = opts.reasoning if opts.reasoning
+      parameters[:tools] = serialize_tools_for_responses(opts.tools) if opts.tools?
+      parameters[:tool_choice] = opts.tool_choice if opts.tool_choice
+      # Prefer max_completion_tokens over max_tokens (consistent with complete() method)
+      parameters[:max_output_tokens] = opts.max_completion_tokens || opts.max_tokens if opts.max_completion_tokens || opts.max_tokens
+      parameters[:temperature] = opts.temperature if opts.temperature
+      parameters[:top_p] = opts.top_p if opts.top_p
+      parameters.merge!(opts.extras || {})
 
       raw = post(path: "/responses", parameters: parameters)
       ResponsesResponse.new(raw)
@@ -314,18 +321,47 @@ module OpenRouter
 
     private
 
+    # Normalize options from various input formats into CompletionOptions
+    #
+    # @param options [CompletionOptions, Hash, nil] Options object or hash
+    # @param kwargs [Hash] Additional keyword arguments
+    # @return [CompletionOptions] Normalized options object
+    def normalize_options(options, kwargs)
+      case options
+      when CompletionOptions
+        kwargs.empty? ? options : options.merge(**kwargs)
+      when Hash
+        # Symbolize keys to handle both string and symbol key hashes
+        symbolized = options.transform_keys(&:to_sym)
+        CompletionOptions.new(**symbolized.merge(kwargs))
+      when nil
+        CompletionOptions.new(**kwargs)
+      else
+        raise ArgumentError, "options must be CompletionOptions, Hash, or nil"
+      end
+    end
+
     # Prepare the base parameters for the API request
-    def prepare_base_parameters(messages, model, providers, transforms, plugins, prediction, stream, extras)
+    #
+    # @param messages [Array<Hash>] Array of message hashes
+    # @param opts [CompletionOptions] Normalized options object
+    # @param stream [Proc, nil] Optional streaming handler
+    # @return [Hash] Parameters hash for the API request
+    def prepare_base_parameters(messages, opts, stream)
       parameters = { messages: messages.dup }
 
-      configure_model_parameter!(parameters, model)
-      configure_provider_parameter!(parameters, providers)
-      configure_transforms_parameter!(parameters, transforms)
-      configure_plugins_parameter!(parameters, plugins)
-      configure_prediction_parameter!(parameters, prediction)
+      configure_model_parameter!(parameters, opts.model)
+      configure_provider_parameter!(parameters, opts)
+      configure_transforms_parameter!(parameters, opts.transforms)
+      configure_plugins_parameter!(parameters, opts.plugins)
+      configure_prediction_parameter!(parameters, opts.prediction)
       configure_stream_parameter!(parameters, stream)
+      configure_sampling_parameters!(parameters, opts)
+      configure_output_parameters!(parameters, opts)
+      configure_routing_parameters!(parameters, opts)
 
-      parameters.merge!(extras)
+      # Merge any extras last (allows overriding anything)
+      parameters.merge!(opts.extras || {})
       parameters
     end
 
@@ -339,9 +375,66 @@ module OpenRouter
       end
     end
 
-    # Configure the provider parameter if providers are specified
-    def configure_provider_parameter!(parameters, providers)
-      parameters[:provider] = { order: providers } if providers.any?
+    # Configure the provider parameter from options
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    def configure_provider_parameter!(parameters, opts)
+      # Full provider config takes precedence over simple providers array
+      if opts.provider && !opts.provider.empty?
+        parameters[:provider] = opts.provider
+      elsif opts.providers.any?
+        parameters[:provider] = { order: opts.providers }
+      end
+
+      # Route parameter for fallback models
+      parameters[:route] = opts.route if opts.route
+    end
+
+    # Configure sampling parameters (temperature, top_p, etc.)
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    def configure_sampling_parameters!(parameters, opts)
+      parameters[:temperature] = opts.temperature if opts.temperature
+      parameters[:top_p] = opts.top_p if opts.top_p
+      parameters[:top_k] = opts.top_k if opts.top_k
+      parameters[:frequency_penalty] = opts.frequency_penalty if opts.frequency_penalty
+      parameters[:presence_penalty] = opts.presence_penalty if opts.presence_penalty
+      parameters[:repetition_penalty] = opts.repetition_penalty if opts.repetition_penalty
+      parameters[:min_p] = opts.min_p if opts.min_p
+      parameters[:top_a] = opts.top_a if opts.top_a
+      parameters[:seed] = opts.seed if opts.seed
+    end
+
+    # Configure output control parameters
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    def configure_output_parameters!(parameters, opts)
+      # Prefer max_completion_tokens over max_tokens if both are set
+      if opts.max_completion_tokens
+        parameters[:max_completion_tokens] = opts.max_completion_tokens
+      elsif opts.max_tokens
+        parameters[:max_tokens] = opts.max_tokens
+      end
+
+      parameters[:stop] = opts.stop if opts.stop
+      parameters[:logprobs] = opts.logprobs unless opts.logprobs.nil?
+      parameters[:top_logprobs] = opts.top_logprobs if opts.top_logprobs
+      parameters[:logit_bias] = opts.logit_bias if opts.logit_bias && !opts.logit_bias.empty?
+      parameters[:parallel_tool_calls] = opts.parallel_tool_calls unless opts.parallel_tool_calls.nil?
+      parameters[:verbosity] = opts.verbosity if opts.verbosity
+    end
+
+    # Configure OpenRouter-specific routing parameters
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    def configure_routing_parameters!(parameters, opts)
+      parameters[:metadata] = opts.metadata if opts.metadata && !opts.metadata.empty?
+      parameters[:user] = opts.user if opts.user
+      parameters[:session_id] = opts.session_id if opts.session_id
     end
 
     # Configure the transforms parameter if transforms are specified
@@ -396,32 +489,42 @@ module OpenRouter
     end
 
     # Configure tools and structured outputs, returning forced_extraction flag
-    def configure_tools_and_structured_outputs!(parameters, model, tools, tool_choice, response_format,
-                                                force_structured_output)
-      configure_tool_calling!(parameters, model, tools, tool_choice)
-      configure_structured_outputs!(parameters, model, response_format, force_structured_output)
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    # @return [Boolean] Whether forced extraction mode is being used
+    def configure_tools_and_structured_outputs!(parameters, opts)
+      configure_tool_calling!(parameters, opts)
+      configure_structured_outputs!(parameters, opts)
     end
 
     # Configure tool calling support
-    def configure_tool_calling!(parameters, model, tools, tool_choice)
-      return unless tools.any?
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    def configure_tool_calling!(parameters, opts)
+      return unless opts.tools?
 
-      warn_if_unsupported(model, :function_calling, "tool calling")
-      parameters[:tools] = serialize_tools(tools)
-      parameters[:tool_choice] = tool_choice if tool_choice
+      warn_if_unsupported(opts.model, :function_calling, "tool calling")
+      parameters[:tools] = serialize_tools(opts.tools)
+      parameters[:tool_choice] = opts.tool_choice if opts.tool_choice
     end
 
     # Configure structured output support and return forced_extraction flag
-    def configure_structured_outputs!(parameters, model, response_format, force_structured_output)
-      return false unless response_format
+    #
+    # @param parameters [Hash] Request parameters hash
+    # @param opts [CompletionOptions] Options object
+    # @return [Boolean] Whether forced extraction mode is being used
+    def configure_structured_outputs!(parameters, opts)
+      return false unless opts.response_format?
 
-      force_structured_output = determine_forced_extraction_mode(model, force_structured_output)
+      force_extraction = determine_forced_extraction_mode(opts.model, opts.force_structured_output)
 
-      if force_structured_output
-        handle_forced_structured_output!(parameters, model, response_format)
+      if force_extraction
+        handle_forced_structured_output!(parameters, opts.model, opts.response_format)
         true
       else
-        handle_native_structured_output!(parameters, model, response_format)
+        handle_native_structured_output!(parameters, opts.model, opts.response_format)
         false
       end
     end

data/lib/open_router/completion_options.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # CompletionOptions provides a structured way to configure API requests.
+  #
+  # Supports all OpenRouter API parameters plus client-side options.
+  # Can be used with complete(), stream_complete(), and responses() methods.
+  #
+  # @example Simple usage with kwargs (unchanged)
+  #   client.complete(messages, model: "gpt-4")
+  #
+  # @example Using CompletionOptions for complex requests
+  #   options = OpenRouter::CompletionOptions.new(
+  #     model: "anthropic/claude-3.5-sonnet",
+  #     temperature: 0.7,
+  #     tools: [weather_tool],
+  #     providers: ["anthropic"]
+  #   )
+  #   client.complete(messages, options)
+  #
+  # @example Merging options with overrides
+  #   base_opts = CompletionOptions.new(model: "gpt-4", temperature: 0.5)
+  #   client.complete(messages, base_opts, temperature: 0.9)  # overrides temperature
+  #
+  class CompletionOptions
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Common params (used by both Complete and Responses APIs)
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [String, Array<String>] Model ID or array for fallback routing
+    attr_accessor :model
+
+    # @return [Array<Tool, Hash>] Tool/function definitions for function calling
+    attr_accessor :tools
+
+    # @return [String, Hash, nil] Tool selection: "auto", "none", "required", or specific
+    attr_accessor :tool_choice
+
+    # @return [Hash] Pass-through for any additional/future API params
+    attr_accessor :extras
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Sampling parameters (OpenRouter passes these to underlying models)
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [Float, nil] Sampling temperature (0.0-2.0, default 1.0)
+    attr_accessor :temperature
+
+    # @return [Float, nil] Nucleus sampling (0.0-1.0)
+    attr_accessor :top_p
+
+    # @return [Integer, nil] Limits token selection to top K options
+    attr_accessor :top_k
+
+    # @return [Float, nil] Frequency penalty (-2.0 to 2.0)
+    attr_accessor :frequency_penalty
+
+    # @return [Float, nil] Presence penalty (-2.0 to 2.0)
+    attr_accessor :presence_penalty
+
+    # @return [Float, nil] Repetition penalty (0.0-2.0)
+    attr_accessor :repetition_penalty
+
+    # @return [Float, nil] Minimum probability threshold (0.0-1.0)
+    attr_accessor :min_p
+
+    # @return [Float, nil] Dynamic filtering based on confidence (0.0-1.0)
+    attr_accessor :top_a
+
+    # @return [Integer, nil] Random seed for reproducibility
+    attr_accessor :seed
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Output control
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [Integer, nil] Legacy max tokens limit
+    attr_accessor :max_tokens
+
+    # @return [Integer, nil] Preferred max completion tokens limit
+    attr_accessor :max_completion_tokens
+
+    # @return [String, Array<String>, nil] Stop sequences
+    attr_accessor :stop
+
+    # @return [Boolean, nil] Return log probabilities of output tokens
+    attr_accessor :logprobs
+
+    # @return [Integer, nil] Number of top logprobs to return (0-20)
+    attr_accessor :top_logprobs
+
+    # @return [Hash, nil] Token ID to bias mapping (-100 to 100)
+    attr_accessor :logit_bias
+
+    # @return [Hash, Schema, nil] Structured output schema/format
+    attr_accessor :response_format
+
+    # @return [Boolean, nil] Allow parallel tool calls
+    attr_accessor :parallel_tool_calls
+
+    # @return [Symbol, String, nil] Output verbosity (:low, :medium, :high)
+    attr_accessor :verbosity
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # OpenRouter-specific routing & features
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [Array<String>] Simple provider ordering (becomes provider.order)
+    attr_accessor :providers
+
+    # @return [Hash, nil] Full provider config (overrides :providers if set)
+    #   Supports: order, only, ignore, allow_fallbacks, require_parameters,
+    #   data_collection, zdr, quantizations, sort, max_price, etc.
+    attr_accessor :provider
+
+    # @return [Array<String>] Transform identifiers (e.g., ["middle-out"])
+    attr_accessor :transforms
+
+    # @return [Array<Hash>] Plugin configurations
+    attr_accessor :plugins
+
+    # @return [Hash, nil] Predicted output for latency reduction
+    #   Format: { type: "content", content: "predicted text" }
+    attr_accessor :prediction
+
+    # @return [String, nil] Routing strategy: "fallback" or "sort"
+    attr_accessor :route
+
+    # @return [Hash, nil] Custom key-value metadata
+    attr_accessor :metadata
+
+    # @return [String, nil] End-user identifier for tracking
+    attr_accessor :user
+
+    # @return [String, nil] Session grouping identifier (max 128 chars)
+    attr_accessor :session_id
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Responses API specific
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [Hash, nil] Reasoning configuration for Responses API
+    #   Format: { effort: "minimal"|"low"|"medium"|"high" }
+    attr_accessor :reasoning
+
+    # ═══════════════════════════════════════════════════════════════════════════
+    # Client-side options (not sent to API)
+    # ═══════════════════════════════════════════════════════════════════════════
+
+    # @return [Boolean, nil] Override forced extraction mode for structured outputs
+    #   true: Force extraction via system message injection
+    #   false: Use native structured output
+    #   nil: Auto-determine based on model capability
+    attr_accessor :force_structured_output
+
+    # All supported parameters with their defaults
+    DEFAULTS = {
+      # Common
+      model: "openrouter/auto",
+      tools: [],
+      tool_choice: nil,
+      extras: {},
+      # Sampling
+      temperature: nil,
+      top_p: nil,
+      top_k: nil,
+      frequency_penalty: nil,
+      presence_penalty: nil,
+      repetition_penalty: nil,
+      min_p: nil,
+      top_a: nil,
+      seed: nil,
+      # Output
+      max_tokens: nil,
+      max_completion_tokens: nil,
+      stop: nil,
+      logprobs: nil,
+      top_logprobs: nil,
+      logit_bias: nil,
+      response_format: nil,
+      parallel_tool_calls: nil,
+      verbosity: nil,
+      # OpenRouter routing
+      providers: [],
+      provider: nil,
+      transforms: [],
+      plugins: [],
+      prediction: nil,
+      route: nil,
+      metadata: nil,
+      user: nil,
+      session_id: nil,
+      # Responses API
+      reasoning: nil,
+      # Client-side
+      force_structured_output: nil
+    }.freeze
+
+    # Parameters that are client-side only (not sent to API)
+    CLIENT_SIDE_PARAMS = %i[force_structured_output extras].freeze
+
+    # Initialize with keyword arguments
+    #
+    # @param attrs [Hash] Parameter values (see DEFAULTS for available keys)
+    def initialize(**attrs)
+      DEFAULTS.each do |key, default|
+        value = attrs.key?(key) ? attrs[key] : default
+        # Deep dup arrays/hashes to prevent mutation of shared defaults
+        value = value.dup if value.is_a?(Array) || value.is_a?(Hash)
+        instance_variable_set(:"@#{key}", value)
+      end
+    end
+
+    # Convert to hash, excluding nil values and empty collections
+    #
+    # @return [Hash] Non-empty parameter values
+    def to_h
+      DEFAULTS.keys.each_with_object({}) do |key, hash|
+        value = instance_variable_get(:"@#{key}")
+        next if value.nil?
+        next if value.respond_to?(:empty?) && value.empty?
+
+        hash[key] = value
+      end
+    end
+
+    # Create a new CompletionOptions with merged overrides
+    #
+    # @param overrides [Hash] Values to override
+    # @return [CompletionOptions] New instance with merged values
+    def merge(**overrides)
+      self.class.new(**to_h.merge(overrides))
+    end
+
+    # Build API request parameters hash
+    # Excludes client-side-only options and merges extras
+    #
+    # @return [Hash] Parameters ready for API request
+    def to_api_params
+      api_params = to_h.reject { |key, _| CLIENT_SIDE_PARAMS.include?(key) }
+      api_params.merge(extras || {})
+    end
+
+    # Check if this options object has any tools defined
+    #
+    # @return [Boolean]
+    def tools?
+      tools.is_a?(Array) && !tools.empty?
+    end
+
+    # Check if response format is configured
+    #
+    # @return [Boolean]
+    def response_format?
+      !response_format.nil?
+    end
+
+    # Check if using model fallback (array of models)
+    #
+    # @return [Boolean]
+    def fallback_models?
+      model.is_a?(Array)
+    end
+  end
+end