open_router_enhanced 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a260aa7386fa0f23bc13f963953db3b35f560b18bae0d39c93e4aa8c28562837
-  data.tar.gz: af442633daa38c99141fbda7b27d5708f101338c98375863fafd56425b1bdf21
+  metadata.gz: 34c685a89892a839ba66999ed50a0ed066db83f3a21c95c96edfdc25ade6a2b5
+  data.tar.gz: e3fdeb547d1588933cb85984f582d5d18db0b12e40c9adaa2dcb02f400f1b012
 SHA512:
-  metadata.gz: 2eef8670903a1b78b17731ab9cc6b75db36d4894c7f1b2361e7978e910c7a5e48e3bdb490a681ace1043d83460a65ab79ba4a2084b1478ea37f0eae8d25d0c40
-  data.tar.gz: cd027929c19afd7fb18a042a9c097e5f052aaecf4567be972edd564158e56bd4d2e76feac6b68b4f89b27b6b2d70105e80c93bf659f5cba0862d30aa4dba877c
+  metadata.gz: c33bca90ab16de26ba7bc7d6c995314f2a5b93b99b1b60a8ffb3fae0eaac94edb275b3777e6bbdd86b34aafe11526aab946b857334013b40cb327620cb91a55c
+  data.tar.gz: 790593fb868bb3728ae91630ecbbd85e660fcc1d00a51400cdcfb1fc10f0ef3395eb46dc2624a5af1590cfe6f8a788ae37f3fac651db362bb4556d6fc4e8ee46

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [1.2.1] - 2025-12-24
+
+### Fixed
+- Memoized `output_id` in `ResponsesToolResult` to ensure consistent IDs across multiple calls
+- Memoized `message_output` and `reasoning_output` finders in `ResponsesResponse` for performance
+
+## [1.2.0] - 2025-12-24
+
+### Added
+- **Responses API**: Full support for OpenRouter's Responses API Beta (`/api/v1/responses`)
+  - Simple string or structured array input
+  - Reasoning with configurable effort levels (`minimal`, `low`, `medium`, `high`)
+  - `ResponsesResponse` wrapper with convenient accessors
+- **Responses API Tool Calling**: Complete function calling support for Responses API
+  - `ResponsesToolCall` and `ResponsesToolResult` classes
+  - `execute_tool_calls` for easy tool execution with blocks
+  - `build_follow_up_input` for multi-turn tool conversations
+  - `tool_choice` parameter (`auto`, `required`, `none`)
+  - Automatic format conversion from Chat Completions tool format
+- **Shared Tool Call Infrastructure**: Extracted `ToolCallBase` and `ToolResultBase` modules
+  - DRY shared behavior for argument parsing and execution
+  - Consistent interface across Chat Completions and Responses APIs
+
+### Documentation
+- New `docs/responses_api.md` with comprehensive Responses API guide
+- Tool calling examples with Tool DSL and hash formats
+
 ## [1.1.0] - 2025-12-24
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    open_router_enhanced (1.1.0)
+    open_router_enhanced (1.2.1)
       activesupport (>= 6.0, < 9.0)
       dotenv (>= 2.0, < 4.0)
       faraday (>= 1.0, < 3.0)
@@ -11,33 +11,32 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.3)
+    activesupport (8.1.1)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    benchmark (0.4.1)
-    bigdecimal (3.3.0)
+    bigdecimal (4.0.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.4)
-    crack (1.0.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    crack (1.0.1)
       bigdecimal
       rexml
     diff-lcs (1.6.2)
-    dotenv (3.1.8)
+    dotenv (3.2.0)
     drb (2.2.3)
     faraday (2.14.0)
       faraday-net_http (>= 2.0, < 3.5)
@@ -45,50 +44,51 @@ GEM
       logger
     faraday-multipart (1.1.1)
       multipart-post (~> 2.0)
-    faraday-net_http (3.4.1)
-      net-http (>= 0.5.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
     hashdiff (1.2.1)
-    i18n (1.14.7)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.15.1)
+    json (2.18.0)
     json-schema (4.3.1)
       addressable (>= 2.8)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
-    minitest (5.25.5)
+    minitest (6.0.0)
+      prism (~> 1.5)
     multipart-post (2.4.1)
-    net-http (0.6.0)
-      uri
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    prism (1.5.1)
+    prism (1.7.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (6.0.2)
+    public_suffix (7.0.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.3.1)
     regexp_parser (2.11.3)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.81.1)
+    rubocop (1.82.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -96,10 +96,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     ruby-progressbar (1.13.0)
@@ -108,11 +108,10 @@ GEM
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    uri (1.0.4)
-    vcr (6.3.1)
-      base64
-    webmock (3.25.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
+    vcr (6.4.0)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/docs/responses_api.md

@@ -0,0 +1,298 @@
+# Responses API (Beta)
+
+The Responses API is an OpenAI-compatible stateless endpoint that provides access to multiple AI models with advanced reasoning capabilities.
+
+> **Beta**: This API may have breaking changes. Use with caution in production.
+
+## Basic Usage
+
+```ruby
+client = OpenRouter::Client.new
+
+response = client.responses(
+  "What is the capital of France?",
+  model: "openai/gpt-4o-mini"
+)
+
+puts response.content  # => "Paris"
+```
+
+## With Reasoning
+
+The Responses API supports reasoning with configurable effort levels:
+
+```ruby
+response = client.responses(
+  "What is 15% of 80? Show your work.",
+  model: "openai/o4-mini",
+  reasoning: { effort: "high" },
+  max_output_tokens: 500
+)
+
+# Access reasoning steps
+if response.has_reasoning?
+  puts "Reasoning steps:"
+  response.reasoning_summary.each { |step| puts "  - #{step}" }
+end
+
+puts "Answer: #{response.content}"
+puts "Reasoning tokens used: #{response.reasoning_tokens}"
+```
+
+### Effort Levels
+
+| Level | Description |
+|-------|-------------|
+| `minimal` | Basic reasoning with minimal computational effort |
+| `low` | Light reasoning for simple problems |
+| `medium` | Balanced reasoning for moderate complexity |
+| `high` | Deep reasoning for complex problems |
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input` | String or Array | The input text or structured message array (required) |
+| `model` | String | Model identifier, e.g. `"openai/o4-mini"` (required) |
+| `reasoning` | Hash | Reasoning config with `effort` key |
+| `tools` | Array | Tool definitions for function calling |
+| `tool_choice` | String/Hash | `"auto"`, `"none"`, `"required"`, or specific tool |
+| `max_output_tokens` | Integer | Maximum tokens to generate |
+| `temperature` | Float | Sampling temperature (0-2) |
+| `top_p` | Float | Nucleus sampling parameter (0-1) |
+| `extras` | Hash | Additional API parameters |
+
+## Structured Input
+
+You can also use structured message arrays:
+
+```ruby
+response = client.responses(
+  [
+    {
+      "type" => "message",
+      "role" => "user",
+      "content" => [
+        { "type" => "input_text", "text" => "Hello, world!" }
+      ]
+    }
+  ],
+  model: "openai/gpt-4o-mini"
+)
+```
+
+## Response Object
+
+The `ResponsesResponse` class provides convenient accessors:
+
+```ruby
+response.id              # Response ID
+response.status          # "completed", "failed", etc.
+response.model           # Model used
+response.content         # Assistant's text response
+response.output          # Raw output array
+
+# Reasoning
+response.has_reasoning?     # Boolean
+response.reasoning_summary  # Array of reasoning steps
+
+# Tool calls
+response.has_tool_calls?  # Boolean
+response.tool_calls       # Array of ResponsesToolCall objects
+response.tool_calls_raw   # Array of raw hash data
+
+# Token usage
+response.input_tokens     # Input token count
+response.output_tokens    # Output token count
+response.total_tokens     # Total token count
+response.reasoning_tokens # Tokens used for reasoning
+```
+
+## Tool/Function Calling
+
+The Responses API supports function calling with a simplified format. Tool calls are wrapped in `ResponsesToolCall` objects for easy execution.
+
+### Defining Tools
+
+You can use the same tool format as Chat Completions - the gem automatically converts it:
+
+```ruby
+tools = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Get current weather for a location",
+      parameters: {
+        type: "object",
+        properties: {
+          location: { type: "string", description: "City name" },
+          units: { type: "string", enum: ["celsius", "fahrenheit"] }
+        },
+        required: ["location"]
+      }
+    }
+  }
+]
+
+response = client.responses(
+  "What's the weather in San Francisco?",
+  model: "openai/gpt-4o-mini",
+  tools: tools
+)
+```
+
+You can also use the `Tool` DSL:
+
+```ruby
+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"
+    string :units, enum: %w[celsius fahrenheit]
+  end
+end
+
+response = client.responses(
+  "What's the weather in Tokyo?",
+  model: "openai/gpt-4o-mini",
+  tools: [weather_tool]
+)
+```
+
+### Tool Choice
+
+Control when the model uses tools with `tool_choice`:
+
+```ruby
+# Let model decide (default)
+response = client.responses(input, model: model, tools: tools, tool_choice: "auto")
+
+# Force tool use
+response = client.responses(input, model: model, tools: tools, tool_choice: "required")
+
+# Prevent tool use
+response = client.responses(input, model: model, tools: tools, tool_choice: "none")
+```
+
+### Executing Tool Calls
+
+```ruby
+if response.has_tool_calls?
+  # Execute each tool call with a block
+  results = response.execute_tool_calls do |name, arguments|
+    case name
+    when "get_weather"
+      fetch_weather(arguments["location"], arguments["units"])
+    when "search_web"
+      search(arguments["query"])
+    else
+      { error: "Unknown function: #{name}" }
+    end
+  end
+
+  # Results are ResponsesToolResult objects
+  results.each do |result|
+    if result.success?
+      puts "#{result.tool_call.name}: #{result.result}"
+    else
+      puts "Error: #{result.error}"
+    end
+  end
+end
+```
+
+### Multi-turn Tool Conversations
+
+Use `build_follow_up_input` to continue conversations after tool execution:
+
+```ruby
+# First call - model requests tool use
+original_input = "What's the weather in NYC and Paris?"
+response = client.responses(original_input, model: "openai/gpt-4o-mini", tools: tools)
+
+# Execute the tool calls
+results = response.execute_tool_calls do |name, args|
+  fetch_weather(args["location"])
+end
+
+# Build follow-up input with tool results
+next_input = response.build_follow_up_input(
+  original_input: original_input,
+  tool_results: results
+)
+
+# Continue the conversation - model will use the tool results
+final_response = client.responses(next_input, model: "openai/gpt-4o-mini")
+puts final_response.content
+# => "In NYC it's 72°F and sunny. In Paris it's 18°C and cloudy."
+```
+
+### Adding Follow-up Messages
+
+You can include a follow-up question when building the input:
+
+```ruby
+next_input = response.build_follow_up_input(
+  original_input: original_input,
+  tool_results: results,
+  follow_up_message: "Which city has better weather for a picnic?"
+)
+```
+
+### Tool Call Objects
+
+`ResponsesToolCall` provides:
+
+```ruby
+tool_call.id              # Tool call ID
+tool_call.call_id         # Call ID for result matching
+tool_call.name            # Function name
+tool_call.function_name   # Alias for name
+tool_call.arguments       # Parsed arguments hash
+tool_call.arguments_string # Raw JSON string
+tool_call.to_input_item   # Convert to input format
+```
+
+`ResponsesToolResult` provides:
+
+```ruby
+result.tool_call  # Reference to the tool call
+result.result     # Execution result (if successful)
+result.error      # Error message (if failed)
+result.success?   # Boolean
+result.failure?   # Boolean
+result.to_input_item  # Convert to function_call_output format
+```
+
+## Comparison with Chat Completions
+
+| Aspect | `complete()` | `responses()` |
+|--------|--------------|---------------|
+| Endpoint | `/chat/completions` | `/responses` |
+| Input | `messages` array | `input` string or array |
+| Output | `choices[].message` | `output[]` typed items |
+| Reasoning | Not supported | `reasoning` parameter |
+| Tool calling | Supported | Supported |
+| Token limit | `max_tokens` | `max_output_tokens` |
+| Streaming | Supported | Not yet supported |
+
+## When to Use
+
+Use the Responses API when you need:
+- Built-in reasoning with effort control
+- OpenAI Responses API compatibility
+- Simpler input format (string instead of messages)
+
+Use Chat Completions when you need:
+- Streaming responses
+- Full callback system integration
+- Usage tracking integration
+- Response healing features
+
+## Future Enhancements
+
+The following features are planned but not yet implemented:
+- Streaming support
+- Callbacks integration

data/lib/open_router/client.rb

@@ -9,6 +9,7 @@ require "pry"
 module OpenRouter
   class ServerError < StandardError; end
 
+  # rubocop:disable Metrics/ClassLength
   class Client
     include OpenRouter::HTTP
 
@@ -103,8 +104,10 @@ module OpenRouter
     # @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.
+    # 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)
@@ -145,6 +148,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
@@ -510,7 +555,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
@@ -524,6 +570,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
@@ -595,4 +669,5 @@ module OpenRouter
       INSTRUCTION
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/open_router/model_registry.rb

@@ -367,9 +367,9 @@ module OpenRouter
         total_size = Dir.glob(File.join(CACHE_DIR, "**/*"))
                         .select { |f| File.file?(f) }
                         .sum do |f|
-          File.size(f)
-        rescue StandardError
-          0
+                          File.size(f)
+                        rescue StandardError
+                          0
         end
         total_size / (1024.0 * 1024.0)
       end

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 reasoning?
+      !reasoning_output.nil?
+    end
+    alias has_reasoning? reasoning?
+
+    # 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 tool_calls?
+      tool_calls.any?
+    end
+    alias has_tool_calls? tool_calls?
+
+    # 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
+      input_items << message_output if message_output
+
+      # 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["input_tokens"] || 0
+    end
+
+    def output_tokens
+      usage["output_tokens"] || 0
+    end
+
+    def total_tokens
+      usage["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
+      @message_output ||= output.find { |o| o["type"] == "message" }
+    end
+
+    def reasoning_output
+      @reasoning_output ||= output.find { |o| o["type"] == "reasoning" }
+    end
+  end
+end

data/lib/open_router/responses_tool_call.rb

@@ -0,0 +1,94 @@
+# 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
+    attr_reader :name
+
+    # 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, :output_id
+
+    def initialize(tool_call, result = nil, error = nil)
+      @tool_call = tool_call
+      @result = result
+      @error = error
+      @output_id = "fc_output_#{SecureRandom.hex(8)}"
+    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" => @output_id,
+        "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,70 @@
+# 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
+
+    # Factory methods for creating tool results
+    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.1.0"
+  VERSION = "1.2.1"
 end

data/lib/open_router.rb

@@ -18,10 +18,13 @@ end
 
 require_relative "open_router/http"
 require_relative "open_router/tool"
+require_relative "open_router/tool_call_base"
 require_relative "open_router/tool_call"
 require_relative "open_router/schema"
 require_relative "open_router/json_healer"
 require_relative "open_router/response"
+require_relative "open_router/responses_response"
+require_relative "open_router/responses_tool_call"
 require_relative "open_router/model_registry"
 require_relative "open_router/model_selector"
 require_relative "open_router/prompt_template"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: open_router_enhanced
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Eric Stiens
@@ -131,6 +131,7 @@ files:
 - docs/observability.md
 - docs/plugins.md
 - docs/prompt_templates.md
+- docs/responses_api.md
 - docs/streaming.md
 - docs/structured_outputs.md
 - docs/tools.md
@@ -150,10 +151,13 @@ files:
 - lib/open_router/model_selector.rb
 - lib/open_router/prompt_template.rb
 - lib/open_router/response.rb
+- lib/open_router/responses_response.rb
+- lib/open_router/responses_tool_call.rb
 - lib/open_router/schema.rb
 - lib/open_router/streaming_client.rb
 - lib/open_router/tool.rb
 - lib/open_router/tool_call.rb
+- lib/open_router/tool_call_base.rb
 - lib/open_router/usage_tracker.rb
 - lib/open_router/version.rb
 - sig/open_router.rbs