open_router_enhanced 2.1.0 → 2.2.1

data/lib/open_router/completion_options.rb

@@ -147,11 +147,18 @@ module OpenRouter
     # 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
+    # @return [Boolean, nil] Request provider-side native json_schema enforcement.
+    #   true:  Send response_format: { type: "json_schema", ... } (grammar-constrained,
+    #          only supported by some models/providers — can 400 on unsupported ones).
+    #   false/nil (default): Send response_format: { type: "json_object" } and describe
+    #          the schema in the prompt. Widely supported; validated/healed client-side.
+    attr_accessor :native
+
+    # @return [Boolean, nil] Validation strictness for structured outputs.
+    #   true:  Raise StructuredOutputError if the response doesn't match the schema.
+    #   false/nil (default): Best-effort — return the parsed JSON as-is.
+    #   When nil, falls back to configuration.structured_output_strict.
+    attr_accessor :strict
 
     # All supported parameters with their defaults
     DEFAULTS = {
@@ -193,11 +200,12 @@ module OpenRouter
       # Responses API
       reasoning: nil,
       # Client-side
-      force_structured_output: nil
+      native: nil,
+      strict: nil
     }.freeze
 
     # Parameters that are client-side only (not sent to API)
-    CLIENT_SIDE_PARAMS = %i[force_structured_output extras].freeze
+    CLIENT_SIDE_PARAMS = %i[native strict extras].freeze
 
     # Initialize with keyword arguments
     #

data/lib/open_router/parameter_builder.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Mixin providing request parameter construction for Client.
+  module ParameterBuilder
+    private
+
+    # Prepare the base parameters for the API request
+    def prepare_base_parameters(messages, opts, stream)
+      parameters = { messages: messages.dup }
+
+      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!(opts.extras || {})
+      parameters
+    end
+
+    def configure_model_parameter!(parameters, model)
+      if model.is_a?(String)
+        parameters[:model] = model
+      elsif model.is_a?(Array)
+        parameters[:models] = model
+        parameters[:route] = "fallback"
+      end
+    end
+
+    def configure_provider_parameter!(parameters, opts)
+      if opts.provider && !opts.provider.empty?
+        parameters[:provider] = opts.provider
+      elsif opts.providers.any?
+        parameters[:provider] = { order: opts.providers }
+      end
+
+      parameters[:route] = opts.route if opts.route
+    end
+
+    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
+
+    def configure_output_parameters!(parameters, opts)
+      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
+
+    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
+
+    def configure_transforms_parameter!(parameters, transforms)
+      parameters[:transforms] = transforms if transforms.any?
+    end
+
+    def configure_plugins_parameter!(parameters, plugins)
+      parameters[:plugins] = plugins.dup if plugins.any?
+    end
+
+    def configure_prediction_parameter!(parameters, prediction)
+      parameters[:prediction] = prediction if prediction
+    end
+
+    def configure_stream_parameter!(parameters, stream)
+      parameters[:stream] = stream if stream
+    end
+
+    # Auto-add response-healing plugin when using structured outputs (non-streaming only)
+    def configure_plugins!(parameters, response_format, stream)
+      return unless should_auto_add_healing?(response_format, stream)
+
+      parameters[:plugins] ||= []
+      return if parameters[:plugins].any? { |p| p[:id] == "response-healing" || p["id"] == "response-healing" }
+
+      parameters[:plugins] << { id: "response-healing" }
+    end
+
+    def should_auto_add_healing?(response_format, stream)
+      return false unless configuration.auto_native_healing
+      return false if stream
+      return false unless response_format
+
+      case response_format
+      when OpenRouter::Schema
+        true
+      when Hash
+        type = response_format[:type] || response_format["type"]
+        %w[json_schema json_object].include?(type.to_s)
+      else
+        false
+      end
+    end
+  end
+end

data/lib/open_router/request_handler.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Mixin providing HTTP execution, error handling, and capability validation for Client.
+  module RequestHandler
+    private
+
+    def execute_request(parameters)
+      post(path: "/chat/completions", parameters: parameters)
+    rescue ConfigurationError => e
+      trigger_callbacks(:on_error, e)
+      raise ServerError, e.message
+    rescue Faraday::Error => e
+      trigger_callbacks(:on_error, e)
+      handle_faraday_error(e)
+    end
+
+    def handle_faraday_error(error)
+      case error
+      when Faraday::UnauthorizedError
+        raise error
+      when Faraday::BadRequestError
+        error_message = extract_error_message(error)
+        raise ServerError, "Bad Request: #{error_message}"
+      when Faraday::ServerError
+        raise ServerError, "Server Error: #{error.message}"
+      else
+        raise ServerError, "Network Error: #{error.message}"
+      end
+    end
+
+    def extract_error_message(error)
+      return error.message unless error.response&.dig(:body)
+
+      body = error.response[:body]
+
+      if body.is_a?(Hash)
+        body.dig("error", "message") || error.message
+      elsif body.is_a?(String)
+        extract_error_from_json_string(body) || error.message
+      else
+        error.message
+      end
+    end
+
+    def extract_error_from_json_string(json_string)
+      parsed_body = JSON.parse(json_string)
+      parsed_body.dig("error", "message")
+    rescue JSON::ParserError
+      nil
+    end
+
+    def validate_response!(raw_response, stream)
+      raise ServerError, raw_response.dig("error", "message") if raw_response.presence&.dig("error", "message").present?
+
+      return unless stream.blank? && raw_response.blank?
+
+      raise ServerError, "Empty response from OpenRouter. Might be worth retrying once or twice."
+    end
+
+    def build_response(raw_response, response_format, forced_extraction, strict: false)
+      response = Response.new(raw_response, response_format: response_format, forced_extraction: forced_extraction,
+                                            strict: strict)
+      response.client = self
+      response
+    end
+
+    def validate_vision_support(model, messages)
+      warn_if_unsupported(model, :vision, "vision/image processing") if messages_contain_images?(messages)
+    end
+
+    def warn_if_unsupported(model, capability, feature_name)
+      return if model.is_a?(Array) || model == "openrouter/auto"
+      return if ModelRegistry.has_capability?(model, capability)
+
+      if configuration.strict_mode
+        raise CapabilityError,
+              "Model '#{model}' does not support #{feature_name} (missing :#{capability} capability). Enable non-strict mode to allow this request."
+      end
+
+      warning_key = "#{model}:#{capability}"
+      return if @capability_warnings_shown.include?(warning_key)
+
+      warn "[OpenRouter Warning] Model '#{model}' may not support #{feature_name} (missing :#{capability} capability). The request will still be attempted."
+      @capability_warnings_shown << warning_key
+    end
+
+    def messages_contain_images?(messages)
+      messages.any? do |msg|
+        content = msg[:content] || msg["content"]
+        if content.is_a?(Array)
+          content.any? { |part| part.is_a?(Hash) && (part[:type] == "image_url" || part["type"] == "image_url") }
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/open_router/response.rb

@@ -2,18 +2,22 @@
 
 require "json"
 require "active_support/core_ext/hash/indifferent_access"
+require_relative "response_parsing"
 
 module OpenRouter
   class StructuredOutputError < Error; end
 
   class Response
-    attr_reader :raw_response, :response_format, :forced_extraction
+    include OpenRouter::ResponseParsing
+
+    attr_reader :raw_response, :response_format, :forced_extraction, :strict
     attr_accessor :client
 
-    def initialize(raw_response, response_format: nil, forced_extraction: false)
+    def initialize(raw_response, response_format: nil, forced_extraction: false, strict: false)
       @raw_response = raw_response.is_a?(Hash) ? raw_response.with_indifferent_access : {}
       @response_format = response_format
       @forced_extraction = forced_extraction
+      @strict = strict
       @client = nil
     end
 
@@ -77,14 +81,7 @@ module OpenRouter
 
     # Structured output methods
     def structured_output(mode: nil, auto_heal: nil)
-      # Use global default mode if not specified
-      if mode.nil?
-        mode = if @client&.configuration.respond_to?(:default_structured_output_mode)
-                 @client.configuration.default_structured_output_mode || :strict
-               else
-                 :strict
-               end
-      end
+      mode ||= default_structured_output_mode
       # Validate mode parameter
       raise ArgumentError, "Invalid mode: #{mode}. Must be :strict or :gentle." unless %i[strict gentle].include?(mode)
 
@@ -101,6 +98,10 @@ module OpenRouter
 
         result = parse_and_heal_structured_output(auto_heal: should_heal)
 
+        # In the json_object path (lenient extraction) a parse failure yields nil rather
+        # than raising. Strict mode must surface that as an error rather than returning nil.
+        raise StructuredOutputError, "Failed to parse structured output from response" if result.nil?
+
         # Only validate after parsing if healing is disabled (healing handles its own validation)
         if result && !should_heal
           schema_obj = extract_schema_from_response_format
@@ -256,121 +257,10 @@ module OpenRouter
 
     private
 
-    def parse_tool_calls
-      tool_calls_data = choices.first&.dig("message", "tool_calls")
-      return [] unless tool_calls_data.is_a?(Array)
-
-      tool_calls_data.map { |tc| ToolCall.new(tc) }
-    rescue StandardError => e
-      raise ToolCallError, "Failed to parse tool calls: #{e.message}"
-    end
-
-    def raw_tool_calls
-      choices.first&.dig("message", "tool_calls") || []
-    end
-
-    def parse_and_heal_structured_output(auto_heal: false)
-      return nil unless structured_output_expected?
-      return nil unless has_content?
-
-      content_to_parse = @forced_extraction ? extract_json_from_text(content) : content
-
-      if auto_heal && @client
-        # For forced extraction: always send full content to provide context for healing
-        # For normal responses: send the content as-is
-        healing_content = if @forced_extraction
-                            content # Always send full response for better healing context
-                          else
-                            content_to_parse || content
-                          end
-        heal_structured_response(healing_content, extract_schema_from_response_format)
-      else
-        return nil if content_to_parse.nil? # No JSON found in forced extraction
-
-        begin
-          JSON.parse(content_to_parse)
-        rescue JSON::ParserError => e
-          # For forced extraction, be more lenient and return nil on parse failures
-          # For regular structured outputs, return nil if content looks like it contains markdown
-          # (indicates it's not actually structured JSON output)
-          if @forced_extraction
-            nil
-          elsif content_to_parse&.include?("```")
-            # Content contains markdown blocks - this is not structured output
-            nil
-          else
-            raise StructuredOutputError, "Failed to parse structured output: #{e.message}"
-          end
-        end
-      end
-    end
-
-    # Extract JSON from text content (for forced structured output)
-    def extract_json_from_text(text)
-      return nil if text.nil? || text.empty?
-
-      # First try to find JSON in code blocks
-      if text.include?("```")
-        # Look for ```json or ``` blocks
-        json_match = text.match(/```(?:json)?\s*\n?(.*?)\n?```/m)
-        if json_match
-          candidate = json_match[1].strip
-          return candidate unless candidate.empty?
-        end
-      end
-
-      # Try to parse the entire text as JSON
-      begin
-        JSON.parse(text)
-        return text
-      rescue JSON::ParserError
-        # Look for JSON-like content (starts with { or [)
-        json_match = text.match(/(\{.*\}|\[.*\])/m)
-        return json_match[1] if json_match
-      end
-
-      # No JSON found
-      nil
-    end
-
-    def structured_output_expected?
-      return false unless @response_format
-
-      if @response_format.is_a?(Schema)
-        true
-      elsif @response_format.is_a?(Hash) && @response_format[:type] == "json_schema"
-        true
-      else
-        false
-      end
-    end
-
-    def extract_schema_from_response_format
-      case @response_format
-      when Schema
-        @response_format
-      when Hash
-        schema_def = @response_format[:json_schema]
-        if schema_def.is_a?(Schema)
-          schema_def
-        elsif schema_def.is_a?(Hash) && schema_def[:schema]
-          # Create a temporary schema object for validation
-          Schema.new(
-            schema_def[:name] || "response",
-            schema_def[:schema],
-            strict: schema_def.key?(:strict) ? schema_def[:strict] : true
-          )
-        end
-      end
-    end
-
-    # Backward compatibility method that delegates to JsonHealer
-    def heal_structured_response(content, schema)
-      return JSON.parse(content) unless schema
-
-      healer = JsonHealer.new(@client)
-      context = @forced_extraction ? :forced_extraction : :generic
-      healer.heal(content, schema, context: context)
+    # :strict raises on schema mismatch; :gentle returns best-effort. Driven by the
+    # `strict:` flag resolved at request time (per-call option or configured default).
+    def default_structured_output_mode
+      @strict ? :strict : :gentle
     end
   end
 end

data/lib/open_router/response_parsing.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Private parsing helpers for Response — structured output extraction and tool call parsing.
+  module ResponseParsing
+    private
+
+    def parse_tool_calls
+      tool_calls_data = choices.first&.dig("message", "tool_calls")
+      return [] unless tool_calls_data.is_a?(Array)
+
+      tool_calls_data.map { |tc| ToolCall.new(tc) }
+    rescue StandardError => e
+      raise ToolCallError, "Failed to parse tool calls: #{e.message}"
+    end
+
+    def raw_tool_calls
+      choices.first&.dig("message", "tool_calls") || []
+    end
+
+    def parse_and_heal_structured_output(auto_heal: false)
+      return nil unless structured_output_expected?
+      return nil unless has_content?
+
+      content_to_parse = @forced_extraction ? extract_json_from_text(content) : content
+
+      if auto_heal && @client
+        healing_content = @forced_extraction ? content : (content_to_parse || content)
+        heal_structured_response(healing_content, extract_schema_from_response_format)
+      else
+        return nil if content_to_parse.nil?
+
+        begin
+          JSON.parse(content_to_parse)
+        rescue JSON::ParserError => e
+          if @forced_extraction
+            nil
+          elsif content_to_parse&.include?("```")
+            nil
+          else
+            raise StructuredOutputError, "Failed to parse structured output: #{e.message}"
+          end
+        end
+      end
+    end
+
+    def extract_json_from_text(text)
+      return nil if text.nil? || text.empty?
+
+      if text.include?("```")
+        json_match = text.match(/```(?:json)?\s*\n?(.*?)\n?```/m)
+        if json_match
+          candidate = json_match[1].strip
+          return candidate unless candidate.empty?
+        end
+      end
+
+      begin
+        JSON.parse(text)
+        return text
+      rescue JSON::ParserError
+        json_match = text.match(/(\{.*\}|\[.*\])/m)
+        return json_match[1] if json_match
+      end
+
+      nil
+    end
+
+    def structured_output_expected?
+      return false unless @response_format
+
+      if @response_format.is_a?(Schema)
+        true
+      elsif @response_format.is_a?(Hash) && @response_format[:type] == "json_schema"
+        true
+      else
+        false
+      end
+    end
+
+    def extract_schema_from_response_format
+      case @response_format
+      when Schema
+        @response_format
+      when Hash
+        schema_def = @response_format[:json_schema]
+        if schema_def.is_a?(Schema)
+          schema_def
+        elsif schema_def.is_a?(Hash) && schema_def[:schema]
+          Schema.new(
+            schema_def[:name] || "response",
+            schema_def[:schema],
+            strict: schema_def.key?(:strict) ? schema_def[:strict] : true
+          )
+        end
+      end
+    end
+
+    def heal_structured_response(content, schema)
+      return JSON.parse(content) unless schema
+
+      healer = JsonHealer.new(@client)
+      context = @forced_extraction ? :forced_extraction : :generic
+      healer.heal(content, schema, context: context)
+    end
+  end
+end

data/lib/open_router/schema.rb

@@ -30,24 +30,40 @@ module OpenRouter
 
     # Convert to the format expected by OpenRouter API
     def to_h
-      # Apply OpenRouter-specific transformations
-      openrouter_schema = @schema.dup
-
-      # OpenRouter/Azure requires ALL properties to be in the required array
-      # even if they are logically optional. This is a deviation from JSON Schema spec
-      # but necessary for compatibility.
-      if openrouter_schema[:properties]&.any?
-        all_properties = openrouter_schema[:properties].keys.map(&:to_s)
-        openrouter_schema[:required] = all_properties
-      end
-
       {
         name: @name,
         strict: @strict,
-        schema: openrouter_schema
+        schema: enforce_all_required(@schema)
       }
     end
 
+    # OpenRouter / OpenAI strict mode requires EVERY object — at every nesting
+    # level, including nested objects and array items — to list all of its
+    # properties in its `required` array. Forcing this only at the top level
+    # makes nested objects come back with `required: []`, which strict providers
+    # reject with a 400. Walk the schema and enforce it recursively.
+    #
+    # (Optional fields are expressed in strict mode by adding "null" to the
+    # property's type union, not by omitting them from `required`.)
+    def enforce_all_required(node)
+      case node
+      when Hash
+        transformed = node.each_with_object({}) { |(key, value), acc| acc[key] = enforce_all_required(value) }
+
+        props = transformed[:properties] || transformed["properties"]
+        if props.is_a?(Hash) && props.any?
+          key = transformed.key?(:properties) ? :required : "required"
+          transformed[key] = props.keys.map(&:to_s)
+        end
+
+        transformed
+      when Array
+        node.map { |element| enforce_all_required(element) }
+      else
+        node
+      end
+    end
+
     # Get the pure JSON Schema (respects required flags) for testing/validation
     def pure_schema
       @schema