open_router_enhanced 2.0.1 → 2.2.0

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

data/lib/open_router/tool_serializer.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module OpenRouter
+  # Mixin providing tool calling and structured output configuration for Client.
+  # rubocop:disable Metrics/ModuleLength
+  module ToolSerializer
+    private
+
+    # Configure tools and structured outputs, returning forced_extraction flag
+    def configure_tools_and_structured_outputs!(parameters, opts)
+      configure_tool_calling!(parameters, opts)
+      configure_structured_outputs!(parameters, opts)
+    end
+
+    def configure_tool_calling!(parameters, opts)
+      return unless opts.tools?
+
+      warn_if_unsupported(opts.model, :function_calling, "tool calling")
+      parameters[:tools] = serialize_tools(opts.tools)
+      parameters[:tool_choice] = opts.tool_choice if opts.tool_choice
+    end
+
+    # Returns forced_extraction boolean
+    def configure_structured_outputs!(parameters, opts)
+      return false unless opts.response_format?
+
+      force_extraction = determine_forced_extraction_mode(opts.model, opts.force_structured_output)
+
+      if force_extraction
+        handle_forced_structured_output!(parameters, opts.model, opts.response_format)
+        true
+      else
+        handle_native_structured_output!(parameters, opts.model, opts.response_format)
+        false
+      end
+    end
+
+    def determine_forced_extraction_mode(model, force_structured_output)
+      return force_structured_output unless force_structured_output.nil?
+
+      if model.is_a?(String) &&
+         !model.start_with?("openrouter/") &&
+         !ModelRegistry.has_capability?(model, :structured_outputs) &&
+         configuration.auto_force_on_unsupported_models
+        OpenRouter.log_warning("[OpenRouter] Model '#{model}' doesn't support native structured outputs. Automatically using forced extraction mode.")
+        true
+      else
+        false
+      end
+    end
+
+    def handle_forced_structured_output!(parameters, model, response_format)
+      warn_if_unsupported(model, :structured_outputs, "structured outputs") if configuration.strict_mode
+      inject_schema_instructions!(parameters[:messages], response_format)
+    end
+
+    def handle_native_structured_output!(parameters, model, response_format)
+      warn_if_unsupported(model, :structured_outputs, "structured outputs")
+      parameters[:response_format] = serialize_response_format(response_format)
+    end
+
+    # Serialize tools to Chat Completions API format: { type: "function", function: { name:, parameters: } }
+    def serialize_tools(tools)
+      tools.map do |tool|
+        case tool
+        when Tool
+          tool.to_h
+        when Hash
+          tool
+        else
+          raise ArgumentError, "Tools must be Tool objects or hashes"
+        end
+      end
+    end
+
+    # Serialize tools to Responses API flat 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
+
+        if tool_hash[:function]
+          {
+            type: "function",
+            name: tool_hash[:function][:name],
+            description: tool_hash[:function][:description],
+            parameters: tool_hash[:function][:parameters]
+          }.compact
+        else
+          tool_hash
+        end
+      end
+    end
+
+    def serialize_response_format(response_format)
+      case response_format
+      when Hash
+        if response_format[:json_schema].is_a?(Schema)
+          response_format.merge(json_schema: response_format[:json_schema].to_h)
+        else
+          response_format
+        end
+      when Schema
+        { type: "json_schema", json_schema: response_format.to_h }
+      else
+        response_format
+      end
+    end
+
+    def inject_schema_instructions!(messages, response_format)
+      schema = extract_schema(response_format)
+      return unless schema
+
+      instruction_content = if schema.respond_to?(:get_format_instructions)
+                              schema.get_format_instructions
+                            else
+                              build_schema_instruction(schema)
+                            end
+
+      messages << { role: "system", content: instruction_content }
+    end
+
+    def extract_schema(response_format)
+      case response_format
+      when Schema
+        response_format
+      when Hash
+        if response_format[:json_schema].is_a?(Schema)
+          response_format[:json_schema]
+        elsif response_format[:json_schema].is_a?(Hash)
+          response_format[:json_schema]
+        else
+          response_format
+        end
+      end
+    end
+
+    def build_schema_instruction(schema)
+      schema_json = schema.respond_to?(:to_h) ? schema.to_h.to_json : schema.to_json
+
+      <<~INSTRUCTION
+        You must respond with valid JSON matching this exact schema:
+
+        ```json
+        #{schema_json}
+        ```
+
+        Rules:
+        - Return ONLY the JSON object, no other text
+        - Ensure all required fields are present
+        - Match the exact data types specified
+        - Follow any format constraints (email, date, etc.)
+        - Do not include trailing commas or comments
+      INSTRUCTION
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/open_router/version.rb

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

data/lib/open_router.rb

@@ -19,6 +19,7 @@ end
 require_relative "open_router/http"
 require_relative "open_router/completion_options"
 require_relative "open_router/tool"
+require_relative "open_router/subagent_tool"
 require_relative "open_router/tool_call_base"
 require_relative "open_router/tool_call"
 require_relative "open_router/schema"
@@ -30,6 +31,7 @@ require_relative "open_router/model_registry"
 require_relative "open_router/model_selector"
 require_relative "open_router/prompt_template"
 require_relative "open_router/usage_tracker"
+require_relative "open_router/routing"
 require_relative "open_router/client"
 require_relative "open_router/streaming_client"
 require_relative "open_router/version"
@@ -60,6 +62,10 @@ module OpenRouter
     # Default structured output mode configuration
     attr_accessor :default_structured_output_mode
 
+    # Optional logger. When set, gem warnings are routed through it (e.g. Rails.logger).
+    # When nil (default), warnings go to Kernel.warn → $stderr.
+    attr_accessor :logger
+
     DEFAULT_API_VERSION = "v1"
     DEFAULT_REQUEST_TIMEOUT = 120
     DEFAULT_URI_BASE = "https://openrouter.ai/api"
@@ -130,4 +136,12 @@ module OpenRouter
   def self.configure
     yield(configuration)
   end
+
+  def self.log_warning(message)
+    if configuration.logger
+      configuration.logger.warn(message)
+    else
+      Kernel.warn(message)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open_router_enhanced
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Eric Stiens
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -134,6 +134,8 @@ files:
 - docs/responses_api.md
 - docs/streaming.md
 - docs/structured_outputs.md
+- docs/superpowers/plans/2026-06-27-openrouter-routing-features.md
+- docs/superpowers/specs/2026-06-27-openrouter-routing-features-design.md
 - docs/tools.md
 - examples/basic_completion.rb
 - examples/dynamic_model_switching_example.rb
@@ -148,21 +150,28 @@ files:
 - examples/tool_calling_example.rb
 - examples/tool_loop_example.rb
 - lib/open_router.rb
+- lib/open_router/callbacks.rb
 - lib/open_router/client.rb
 - lib/open_router/completion_options.rb
 - lib/open_router/http.rb
 - lib/open_router/json_healer.rb
 - lib/open_router/model_registry.rb
 - lib/open_router/model_selector.rb
+- lib/open_router/parameter_builder.rb
 - lib/open_router/prompt_template.rb
+- lib/open_router/request_handler.rb
 - lib/open_router/response.rb
+- lib/open_router/response_parsing.rb
 - lib/open_router/responses_response.rb
 - lib/open_router/responses_tool_call.rb
+- lib/open_router/routing.rb
 - lib/open_router/schema.rb
 - lib/open_router/streaming_client.rb
+- lib/open_router/subagent_tool.rb
 - lib/open_router/tool.rb
 - lib/open_router/tool_call.rb
 - lib/open_router/tool_call_base.rb
+- lib/open_router/tool_serializer.rb
 - lib/open_router/usage_tracker.rb
 - lib/open_router/version.rb
 - sig/open_router.rbs