open_router_enhanced 2.1.0 → 2.2.1

data/lib/open_router/tool_serializer.rb

@@ -0,0 +1,152 @@
+# 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
+
+    # Configure the structured-output request.
+    #
+    # Default (native: false): ask the provider for a plain JSON object — the most
+    # widely supported response_format across models/providers — and describe the
+    # schema in the prompt. The model's capability registry never gates the request.
+    #
+    # Opt-in (native: true): send response_format: { type: "json_schema", ... } for
+    # grammar-constrained decoding. Only some models/providers support this; it can
+    # 400 on the rest, which is why it is explicit rather than auto-detected.
+    #
+    # Returns the lenient-extraction flag (true when the schema was injected into the
+    # prompt, so the response may need JSON extracted from surrounding text).
+    def configure_structured_outputs!(parameters, opts)
+      return false unless opts.response_format?
+
+      schema = extract_schema(opts.response_format)
+
+      if opts.native && schema
+        warn_if_unsupported(opts.model, :structured_outputs, "structured outputs")
+        parameters[:response_format] = serialize_response_format(opts.response_format)
+        return false
+      end
+
+      # Default json_object path.
+      parameters[:response_format] = { type: "json_object" }
+      return false unless schema
+
+      inject_schema_instructions!(parameters[:messages], schema)
+      true
+    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, schema)
+      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
+
+    # Pull the schema out of a response_format. Returns nil for a plain
+    # { type: "json_object" } directive (no schema to describe or validate).
+    def extract_schema(response_format)
+      case response_format
+      when Schema
+        response_format
+      when Hash
+        json_schema = response_format[:json_schema] || response_format["json_schema"]
+        json_schema if json_schema.is_a?(Schema) || json_schema.is_a?(Hash)
+      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.1.0"
+  VERSION = "2.2.1"
 end

data/lib/open_router.rb

@@ -54,11 +54,11 @@ module OpenRouter
     # Capability validation configuration
     attr_accessor :strict_mode
 
-    # Automatic forcing configuration
-    attr_accessor :auto_force_on_unsupported_models
-
-    # Default structured output mode configuration
-    attr_accessor :default_structured_output_mode
+    # Default validation strictness for structured outputs.
+    # false (default): best-effort, return parsed JSON as-is.
+    # true: raise StructuredOutputError when the response doesn't match the schema.
+    # Overridden per-call by the `strict:` option.
+    attr_accessor :structured_output_strict
 
     DEFAULT_API_VERSION = "v1"
     DEFAULT_REQUEST_TIMEOUT = 120
@@ -93,11 +93,8 @@ module OpenRouter
       # Capability validation defaults
       self.strict_mode = ENV.fetch("OPENROUTER_STRICT_MODE", "false").downcase == "true"
 
-      # Auto forcing defaults
-      self.auto_force_on_unsupported_models = ENV.fetch("OPENROUTER_AUTO_FORCE", "true").downcase == "true"
-
-      # Default structured output mode
-      self.default_structured_output_mode = ENV.fetch("OPENROUTER_DEFAULT_MODE", "strict").to_sym
+      # Default structured output validation strictness (loose/best-effort by default)
+      self.structured_output_strict = ENV.fetch("OPENROUTER_STRUCTURED_STRICT", "false").downcase == "true"
     end
 
     def access_token

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open_router_enhanced
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Eric Stiens
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -148,14 +148,18 @@ 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/schema.rb
@@ -163,6 +167,7 @@ files:
 - 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