open_router_enhanced 1.0.0 → 1.2.0

data/lib/open_router/client.rb

@@ -95,17 +95,20 @@ module OpenRouter
     # @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 stream [Proc, nil] Optional callable object for streaming
     # @return [Response] The completion response wrapped in a Response object.
-    def complete(messages, model: "openrouter/auto", providers: [], transforms: [], tools: [], tool_choice: nil,
-                 response_format: nil, force_structured_output: nil, extras: {}, stream: nil)
-      parameters = prepare_base_parameters(messages, model, providers, transforms, stream, extras)
+    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)
+      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)
 
       # Trigger before_request callbacks
@@ -142,6 +145,48 @@ module OpenRouter
       response["data"]
     end
 
+    # Performs a request to the Responses API Beta (/api/v1/responses)
+    # 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
+    # @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?",
+    #     model: "openai/o4-mini",
+    #     reasoning: { effort: "high" }
+    #   )
+    #   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)
+
+      raw = post(path: "/responses", parameters: parameters)
+      ResponsesResponse.new(raw)
+    end
+
     # Create a new ModelSelector for intelligent model selection
     #
     # @return [ModelSelector] A new ModelSelector instance
@@ -267,12 +312,14 @@ module OpenRouter
     private
 
     # Prepare the base parameters for the API request
-    def prepare_base_parameters(messages, model, providers, transforms, stream, extras)
+    def prepare_base_parameters(messages, model, providers, transforms, plugins, prediction, stream, extras)
       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_stream_parameter!(parameters, stream)
 
       parameters.merge!(extras)
@@ -299,11 +346,52 @@ module OpenRouter
       parameters[:transforms] = transforms if transforms.any?
     end
 
+    # Configure the plugins parameter if plugins are specified
+    def configure_plugins_parameter!(parameters, plugins)
+      parameters[:plugins] = plugins.dup if plugins.any?
+    end
+
+    # Configure the prediction parameter for latency optimization
+    def configure_prediction_parameter!(parameters, prediction)
+      parameters[:prediction] = prediction if prediction
+    end
+
     # Configure the stream parameter if streaming is enabled
     def configure_stream_parameter!(parameters, stream)
       parameters[:stream] = stream if stream
     end
 
+    # Auto-add response-healing plugin when using structured outputs (non-streaming only)
+    # This leverages OpenRouter's native JSON healing for better reliability
+    def configure_plugins!(parameters, response_format, stream)
+      return unless should_auto_add_healing?(response_format, stream)
+
+      parameters[:plugins] ||= []
+
+      # Don't duplicate if user already specified response-healing
+      return if parameters[:plugins].any? { |p| p[:id] == "response-healing" || p["id"] == "response-healing" }
+
+      parameters[:plugins] << { id: "response-healing" }
+    end
+
+    # Determine if we should auto-add the response-healing plugin
+    def should_auto_add_healing?(response_format, stream)
+      return false unless configuration.auto_native_healing
+      return false if stream # Response healing doesn't work with streaming
+      return false unless response_format
+
+      # Check if response_format is a structured output type
+      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
+
     # 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)
@@ -464,7 +552,8 @@ module OpenRouter
       end
     end
 
-    # Serialize tools to the format expected by OpenRouter API
+    # Serialize tools to the format expected by OpenRouter Chat Completions API
+    # Format: { type: "function", function: { name: ..., parameters: ... } }
     def serialize_tools(tools)
       tools.map do |tool|
         case tool
@@ -478,6 +567,34 @@ module OpenRouter
       end
     end
 
+    # Serialize tools to the flat format expected by Responses API
+    # Format: { type: "function", name: ..., parameters: ... }
+    def serialize_tools_for_responses(tools)
+      tools.map do |tool|
+        tool_hash = case tool
+                    when Tool
+                      tool.to_h
+                    when Hash
+                      tool.transform_keys(&:to_sym)
+                    else
+                      raise ArgumentError, "Tools must be Tool objects or hashes"
+                    end
+
+        # Flatten the nested function structure if present
+        if tool_hash[:function]
+          {
+            type: "function",
+            name: tool_hash[:function][:name],
+            description: tool_hash[:function][:description],
+            parameters: tool_hash[:function][:parameters]
+          }.compact
+        else
+          # Already in flat format
+          tool_hash
+        end
+      end
+    end
+
     # Serialize response format to the format expected by OpenRouter API
     def serialize_response_format(response_format)
       case response_format

data/lib/open_router/responses_response.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Response wrapper for the Responses API Beta (/api/v1/responses)
+  # This API differs from chat completions in its response structure,
+  # using an `output` array with typed items instead of `choices`.
+  class ResponsesResponse
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw || {}
+    end
+
+    # Core accessors
+    def id
+      raw["id"]
+    end
+
+    def status
+      # Status can be at top level or derived from message output
+      raw["status"] || message_output&.dig("status")
+    end
+
+    def model
+      raw["model"]
+    end
+
+    def created_at
+      raw["created_at"]
+    end
+
+    def output
+      raw["output"] || []
+    end
+
+    def usage
+      raw["usage"] || {}
+    end
+
+    # Convenience method to get the assistant's text content
+    def content
+      message_output&.dig("content", 0, "text")
+    end
+
+    # Get reasoning summary steps (array of strings)
+    def reasoning_summary
+      reasoning_output&.dig("summary") || []
+    end
+
+    # Check if reasoning was included in the response
+    def has_reasoning?
+      !reasoning_output.nil?
+    end
+
+    # Get tool/function calls from the response as ResponsesToolCall objects
+    #
+    # @return [Array<ResponsesToolCall>] Array of tool call objects
+    def tool_calls
+      @tool_calls ||= output
+                      .select { |o| o["type"] == "function_call" }
+                      .map { |tc| ResponsesToolCall.new(tc) }
+    end
+
+    # Get raw tool call data (hashes) from the response
+    #
+    # @return [Array<Hash>] Array of raw tool call hashes
+    def tool_calls_raw
+      output.select { |o| o["type"] == "function_call" }
+    end
+
+    def has_tool_calls?
+      tool_calls.any?
+    end
+
+    # Execute all tool calls and return results
+    #
+    # @yield [name, arguments] Block to execute each tool
+    # @return [Array<ResponsesToolResult>] Results from all tool executions
+    #
+    # @example
+    #   results = response.execute_tool_calls do |name, args|
+    #     case name
+    #     when "get_weather" then fetch_weather(args["location"])
+    #     when "search" then search_web(args["query"])
+    #     end
+    #   end
+    def execute_tool_calls(&block)
+      tool_calls.map { |tc| tc.execute(&block) }
+    end
+
+    # Build a follow-up input array that includes tool results
+    # Use this to continue the conversation after executing tools
+    #
+    # @param original_input [String, Array] The original input sent to the API
+    # @param tool_results [Array<ResponsesToolResult>] Results from execute_tool_calls
+    # @param follow_up_message [String, nil] Optional follow-up user message
+    # @return [Array] Input array for the next API call
+    #
+    # @example
+    #   # First call with tools
+    #   response = client.responses("What's the weather?", model: "...", tools: [...])
+    #
+    #   # Execute tools
+    #   results = response.execute_tool_calls { |name, args| ... }
+    #
+    #   # Build follow-up input
+    #   next_input = response.build_follow_up_input(
+    #     original_input: "What's the weather?",
+    #     tool_results: results,
+    #     follow_up_message: "Is that good for a picnic?"
+    #   )
+    #
+    #   # Continue conversation
+    #   next_response = client.responses(next_input, model: "...")
+    def build_follow_up_input(original_input:, tool_results:, follow_up_message: nil)
+      input_items = []
+
+      # Add original user message
+      if original_input.is_a?(String)
+        input_items << {
+          "type" => "message",
+          "role" => "user",
+          "content" => [{ "type" => "input_text", "text" => original_input }]
+        }
+      elsif original_input.is_a?(Array)
+        input_items.concat(original_input)
+      end
+
+      # Add function calls from this response
+      tool_calls_raw.each do |tc|
+        input_items << tc
+      end
+
+      # Add function call outputs
+      tool_results.each do |result|
+        input_items << result.to_input_item
+      end
+
+      # Add assistant message if present
+      if message_output
+        input_items << message_output
+      end
+
+      # Add follow-up user message if provided
+      if follow_up_message
+        input_items << {
+          "type" => "message",
+          "role" => "user",
+          "content" => [{ "type" => "input_text", "text" => follow_up_message }]
+        }
+      end
+
+      input_items
+    end
+
+    # Token counts
+    def input_tokens
+      usage.dig("input_tokens") || 0
+    end
+
+    def output_tokens
+      usage.dig("output_tokens") || 0
+    end
+
+    def total_tokens
+      usage.dig("total_tokens") || 0
+    end
+
+    def reasoning_tokens
+      usage.dig("output_tokens_details", "reasoning_tokens") || 0
+    end
+
+    # Hash-like access for raw data
+    def [](key)
+      raw[key]
+    end
+
+    def dig(*keys)
+      raw.dig(*keys)
+    end
+
+    private
+
+    def message_output
+      output.find { |o| o["type"] == "message" }
+    end
+
+    def reasoning_output
+      output.find { |o| o["type"] == "reasoning" }
+    end
+  end
+end

data/lib/open_router/responses_tool_call.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module OpenRouter
+  # Represents a tool/function call from the Responses API.
+  # Format: type="function_call" with name/arguments at top level (not nested)
+  class ResponsesToolCall
+    include ToolCallBase
+
+    attr_reader :id, :call_id, :arguments_string
+
+    def initialize(tool_call_data)
+      @id = tool_call_data["id"]
+      @call_id = tool_call_data["call_id"]
+      @name = tool_call_data["name"]
+      @arguments_string = tool_call_data["arguments"] || "{}"
+    end
+
+    # Get the function name
+    def name
+      @name
+    end
+
+    # Alias for consistency with ToolCall
+    def function_name
+      @name
+    end
+
+    # Build result for execute method (required by ToolCallBase)
+    def build_result(result, error = nil)
+      ResponsesToolResult.new(self, result, error)
+    end
+
+    # Convert to the function_call format for conversation continuation
+    def to_input_item
+      {
+        "type" => "function_call",
+        "id" => @id,
+        "call_id" => @call_id,
+        "name" => @name,
+        "arguments" => @arguments_string
+      }
+    end
+
+    def to_h
+      to_input_item
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+
+  # Represents the result of executing a Responses API tool call
+  class ResponsesToolResult
+    include ToolResultBase
+
+    attr_reader :tool_call, :result, :error
+
+    def initialize(tool_call, result = nil, error = nil)
+      @tool_call = tool_call
+      @result = result
+      @error = error
+    end
+
+    # Convert to function_call_output format for conversation continuation
+    #
+    # @return [Hash] The output item for the input array
+    def to_input_item
+      output_content = if @error
+                         { error: @error }.to_json
+                       elsif @result.is_a?(String)
+                         @result
+                       else
+                         @result.to_json
+                       end
+
+      {
+        "type" => "function_call_output",
+        "id" => "fc_output_#{SecureRandom.hex(8)}",
+        "call_id" => @tool_call.call_id,
+        "output" => output_content
+      }
+    end
+
+    def to_h
+      to_input_item
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end

data/lib/open_router/tool_call.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "json"
-
 module OpenRouter
-  class ToolCallError < Error; end
-
+  # Represents a tool/function call from the Chat Completions API.
+  # Format: tool_calls[].function.name/arguments (nested under function key)
   class ToolCall
+    include ToolCallBase
+
     attr_reader :id, :type, :function_name, :arguments_string
 
     def initialize(tool_call_data)
@@ -15,34 +15,17 @@ module OpenRouter
       raise ToolCallError, "Invalid tool call data: missing function" unless tool_call_data["function"]
 
       @function_name = tool_call_data["function"]["name"]
-      @arguments_string = tool_call_data["function"]["arguments"]
-    end
-
-    # Parse the arguments JSON string into a Ruby hash
-    def arguments
-      @arguments ||= begin
-        JSON.parse(@arguments_string)
-      rescue JSON::ParserError => e
-        raise ToolCallError, "Failed to parse tool call arguments: #{e.message}"
-      end
+      @arguments_string = tool_call_data["function"]["arguments"] || "{}"
     end
 
-    # Get the function name (alias for consistency)
+    # Get the function name
     def name
       @function_name
     end
 
-    # Execute the tool call with a provided block
-    # The block should accept (name, arguments) and return the result
-    def execute(&block)
-      raise ArgumentError, "Block required for tool execution" unless block_given?
-
-      begin
-        result = block.call(@function_name, arguments)
-        ToolResult.new(self, result)
-      rescue StandardError => e
-        ToolResult.new(self, nil, e.message)
-      end
+    # Build result for execute method (required by ToolCallBase)
+    def build_result(result, error = nil)
+      ToolResult.new(self, result, error)
     end
 
     # Convert this tool call to a message format for conversation continuation
@@ -50,16 +33,7 @@ module OpenRouter
       {
         role: "assistant",
         content: nil,
-        tool_calls: [
-          {
-            id: @id,
-            type: @type,
-            function: {
-              name: @function_name,
-              arguments: @arguments_string
-            }
-          }
-        ]
+        tool_calls: [to_h]
       }
     end
 
@@ -95,8 +69,6 @@ module OpenRouter
 
     # Validate against a provided array of tools (Tool instances or hashes)
     def valid?(tools:)
-      # tools is now a required keyword argument
-
       schema = find_schema_for_call(tools)
       return true unless schema # No validation if tool not found
 
@@ -110,8 +82,6 @@ module OpenRouter
     end
 
     def validation_errors(tools:)
-      # tools is now a required keyword argument
-
       schema = find_schema_for_call(tools)
       return [] unless schema # No errors if tool not found
 
@@ -144,8 +114,10 @@ module OpenRouter
     end
   end
 
-  # Represents the result of executing a tool call
+  # Represents the result of executing a Chat Completions tool call
   class ToolResult
+    include ToolResultBase
+
     attr_reader :tool_call, :result, :error
 
     def initialize(tool_call, result = nil, error = nil)
@@ -154,27 +126,9 @@ module OpenRouter
       @error = error
     end
 
-    def success?
-      @error.nil?
-    end
-
-    def failure?
-      !success?
-    end
-
     # Convert to message format for conversation continuation
     def to_message
       @tool_call.to_result_message(@error || @result)
     end
-
-    # Create a failed result
-    def self.failure(tool_call, error)
-      new(tool_call, nil, error)
-    end
-
-    # Create a successful result
-    def self.success(tool_call, result)
-      new(tool_call, result, nil)
-    end
   end
 end

data/lib/open_router/tool_call_base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenRouter
+  class ToolCallError < Error; end
+
+  # Shared behavior for tool call parsing across different API formats.
+  # Include this module and define `name` and `arguments_string` accessors.
+  module ToolCallBase
+    # Parse the arguments JSON string into a Ruby hash
+    def arguments
+      @arguments ||= begin
+        JSON.parse(arguments_string)
+      rescue JSON::ParserError => e
+        raise ToolCallError, "Failed to parse tool call arguments: #{e.message}"
+      end
+    end
+
+    # Execute the tool call with a provided block
+    # The block receives (name, arguments) and should return the result
+    #
+    # @yield [name, arguments] Block to execute the tool
+    # @return [ToolResultBase] The result of execution
+    def execute(&block)
+      raise ArgumentError, "Block required for tool execution" unless block_given?
+
+      begin
+        result = block.call(name, arguments)
+        build_result(result)
+      rescue StandardError => e
+        build_result(nil, e.message)
+      end
+    end
+
+    # Subclasses must implement this to return the appropriate result type
+    def build_result(_result, _error = nil)
+      raise NotImplementedError, "Subclasses must implement build_result"
+    end
+  end
+
+  # Shared behavior for tool execution results.
+  # Include this module and define `tool_call`, `result`, and `error` accessors.
+  module ToolResultBase
+    def success?
+      error.nil?
+    end
+
+    def failure?
+      !success?
+    end
+
+    module ClassMethods
+      # Create a failed result
+      def failure(tool_call, error)
+        new(tool_call, nil, error)
+      end
+
+      # Create a successful result
+      def success(tool_call, result)
+        new(tool_call, result, nil)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/open_router/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenRouter
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end