open_router_enhanced 2.1.0 → 2.2.0

data/lib/open_router/json_healer.rb

@@ -133,7 +133,7 @@ module OpenRouter
     rescue StandardError => e
       # If the healing call itself fails, we can't proceed.
       # Return the original broken content to let the loop fail naturally.
-      warn "[OpenRouter Warning] JSON healing request failed: #{e.message}"
+      OpenRouter.log_warning("[OpenRouter Warning] JSON healing request failed: #{e.message}")
 
       # Trigger callback for failed healing
       if @client.respond_to?(:trigger_callbacks)

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,98 @@
+# 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)
+      response = Response.new(raw_response, response_format: response_format, forced_extraction: forced_extraction)
+      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.to_s.start_with?("openrouter/")
+      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)
+
+      OpenRouter.log_warning("[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,11 +2,14 @@
 
 require "json"
 require "active_support/core_ext/hash/indifferent_access"
+require_relative "response_parsing"
 
 module OpenRouter
   class StructuredOutputError < Error; end
 
   class Response
+    include OpenRouter::ResponseParsing
+
     attr_reader :raw_response, :response_format, :forced_extraction
     attr_accessor :client
 
@@ -182,6 +185,10 @@ module OpenRouter
       @raw_response["model"]
     end
 
+    # Alias for #model — returns the concrete model the API/router used.
+    # Useful for Pareto, Auto, and Fusion routing ("which model answered?").
+    alias selected_model model
+
     def created
       @raw_response["created"]
     end
@@ -253,124 +260,5 @@ module OpenRouter
     def error_message
       @raw_response.dig("error", "message")
     end
-
-    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)
-    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/routing.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Mixin providing ergonomic access to OpenRouter router/meta-model features
+  # (Fusion, Pareto Code Router). Builds the right model alias + plugin config
+  # and delegates to Client#complete.
+  module Routing
+    FUSION_MODEL = "openrouter/fusion"
+    PARETO_CODE_MODEL = "openrouter/pareto-code"
+
+    # Route to the cheapest code-capable model meeting a quality bar.
+    #
+    # @param min_coding_score [Float, nil] 0.0–1.0 (1.0 = best). Optional.
+    def pareto_complete(messages, min_coding_score: nil, **opts)
+      validate_min_coding_score!(min_coding_score)
+
+      plugin = { id: "pareto-router" }
+      plugin[:min_coding_score] = min_coding_score unless min_coding_score.nil?
+
+      kwargs = merge_plugin(opts, plugin)
+      complete(messages, model: PARETO_CODE_MODEL, **kwargs)
+    end
+
+    # Fan a prompt out to a panel of models and synthesize one answer.
+    # NOTE: Fusion costs ~4–5x a single completion (panel calls + judge).
+    #
+    # @param analysis_models [Array<String>, nil] 1–8 panel model ids.
+    # @param judge [String, nil] synthesis model id (defaults to the fusion model server-side).
+    # @param preset [String, Symbol, nil] curated panel slug (e.g. "general-budget").
+    # @param max_tool_calls [Integer, nil] 1–16.
+    def fuse(messages, analysis_models: nil, judge: nil, preset: nil, max_tool_calls: nil, **opts)
+      validate_analysis_models!(analysis_models)
+      validate_max_tool_calls!(max_tool_calls)
+
+      plugin = {
+        id: "fusion",
+        analysis_models: analysis_models,
+        model: judge, # OpenRouter Fusion plugin field is 'model', not 'judge'
+        preset: preset&.to_s,
+        max_tool_calls: max_tool_calls
+      }.compact
+
+      kwargs = merge_plugin(opts, plugin)
+      complete(messages, model: FUSION_MODEL, **kwargs)
+    end
+
+    private
+
+    def validate_min_coding_score!(score)
+      return if score.nil?
+
+      return if score.is_a?(Numeric) && score >= 0.0 && score <= 1.0
+
+      raise ArgumentError, "min_coding_score must be a number between 0.0 and 1.0 (got #{score.inspect})"
+    end
+
+    def validate_analysis_models!(models)
+      return if models.nil?
+
+      return if models.is_a?(Array) && (1..8).cover?(models.size) && models.all? { |m| m.is_a?(String) && !m.strip.empty? }
+
+      raise ArgumentError, "analysis_models must be an array of 1–8 model id strings (got #{models.inspect})"
+    end
+
+    def validate_max_tool_calls!(value)
+      return if value.nil?
+
+      return if value.is_a?(Integer) && (1..16).cover?(value)
+
+      raise ArgumentError, "max_tool_calls must be an integer between 1 and 16 (got #{value.inspect})"
+    end
+
+    # Merge a router plugin into any caller-supplied plugins, de-duped by :id.
+    def merge_plugin(opts, plugin)
+      existing = Array(opts[:plugins]).map { |p| p.transform_keys(&:to_sym) }
+      existing = existing.reject { |p| p[:id].to_s == plugin[:id].to_s }
+      opts.merge(plugins: existing + [plugin])
+    end
+  end
+end

data/lib/open_router/streaming_client.rb

@@ -135,7 +135,7 @@ module OpenRouter
       @streaming_callbacks[event].each do |callback|
         callback.call(data)
       rescue StandardError => e
-        warn "[OpenRouter] Streaming callback error for #{event}: #{e.message}"
+        OpenRouter.log_warning("[OpenRouter] Streaming callback error for #{event}: #{e.message}")
       end
     end
 

data/lib/open_router/subagent_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "tool"
+
+module OpenRouter
+  # Represents the `openrouter:subagent` server tool, which lets an orchestrator
+  # model delegate self-contained subtasks to a cheaper worker model mid-generation.
+  #
+  # Unlike a function Tool, it serializes to the server-tool shape:
+  #   { type: "openrouter:subagent", parameters: { model:, instructions:, ... } }
+  #
+  # @example
+  #   sub = OpenRouter::SubagentTool.new(model: "z-ai/glm-5.2", instructions: "Be concise.")
+  #   client.complete(messages, model: "anthropic/claude-3.5-sonnet", tools: [sub])
+  class SubagentTool < Tool
+    SERVER_TOOL_TYPE = "openrouter:subagent"
+
+    # We deliberately do not call super: Tool#initialize expects a function
+    # definition with a name/description and validates it, neither of which a
+    # server tool has. The server-tool shape is built directly here instead.
+    def initialize(model:, instructions: nil, max_completion_tokens: nil, # rubocop:disable Lint/MissingSuper
+                   temperature: nil, reasoning: nil)
+      raise ArgumentError, "model is required for SubagentTool" if model.nil? || model.to_s.strip.empty?
+
+      @type = SERVER_TOOL_TYPE
+      @parameters_config = {
+        model: model,
+        instructions: instructions,
+        max_completion_tokens: max_completion_tokens,
+        temperature: temperature,
+        reasoning: reasoning
+      }.compact
+    end
+
+    def to_h
+      { type: @type, parameters: @parameters_config }
+    end
+
+    def name
+      @type
+    end
+
+    def description
+      "OpenRouter subagent server tool (worker: #{@parameters_config[:model]})"
+    end
+
+    def parameters
+      nil
+    end
+  end
+end