savvy_openrouter 0.2.0 → 0.4.2

data/lib/savvy_openrouter/request_plugins.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "patterns/structured_output"
+
+module SavvyOpenrouter
+  # Optional chat / Responses request shaping (OpenRouter plugins). Pure Ruby.
+  #
+  #   require "savvy_openrouter/request_plugins"
+  #   SavvyOpenrouter::RequestPlugins.prepare_chat_body!(body, pdf_engine: "native")
+  module RequestPlugins
+    RESPONSE_HEALING_PLUGIN = { id: "response-healing" }.freeze
+    FILE_PARSER_DEFAULT_ENGINE = "cloudflare-ai"
+
+    module_function
+
+    def prepare_chat_body!(body, pdf_engine: nil)
+      return body unless body.is_a?(Hash)
+
+      ensure_response_healing_for_chat!(body) if SavvyOpenrouter::Patterns.chat_structured_requested?(body)
+      ensure_pdf_file_parser_plugin!(body, pdf_engine: pdf_engine)
+      body
+    end
+
+    def prepare_responses_body!(body)
+      return body unless body.is_a?(Hash)
+
+      ensure_response_healing_for_responses!(body) if SavvyOpenrouter::Patterns.responses_structured_requested?(body)
+      body
+    end
+
+    def ensure_response_healing_for_chat!(body)
+      plugins_arr = plugins_array_from(body)
+      return if response_healing_plugin_present?(plugins_arr)
+
+      body[:plugins] = plugins_arr + [RESPONSE_HEALING_PLUGIN.dup]
+      body.delete("plugins")
+    end
+
+    def ensure_response_healing_for_responses!(body)
+      plugins_arr = plugins_array_from(body)
+      return if response_healing_plugin_present?(plugins_arr)
+
+      body[:plugins] = plugins_arr + [RESPONSE_HEALING_PLUGIN.dup]
+      body.delete("plugins")
+    end
+
+    def plugins_array_from(body)
+      p = body[:plugins] || body["plugins"]
+      p.is_a?(Array) ? p.dup : []
+    end
+
+    def response_healing_plugin_present?(plugins)
+      plugin_present?(plugins, id: "response-healing")
+    end
+
+    # +pdf_engine+ — optional override (e.g. from config: +"native"+ for Gemini, +"mistral-ocr"+ for scans).
+    # When nil, uses {FILE_PARSER_DEFAULT_ENGINE}.
+    def ensure_pdf_file_parser_plugin!(body, pdf_engine: nil)
+      messages = body[:messages] || body["messages"]
+      return unless chat_messages_include_pdf_attachment?(messages)
+
+      engine = normalize_pdf_engine(pdf_engine)
+      plugins = plugins_array_from(body)
+      idx = plugins.find_index { |p| plugin_entry_id(p) == "file-parser" }
+
+      if idx
+        return if file_parser_pdf_engine_set?(plugins[idx])
+
+        fp = plugins[idx].dup
+        pdf_src = fp[:pdf] || fp["pdf"]
+        merged_pdf =
+          if pdf_src.is_a?(Hash)
+            pdf_src.transform_keys(&:to_sym)
+          else
+            {}
+          end
+        merged_pdf[:engine] = engine
+        fp[:pdf] = merged_pdf
+        fp.delete("pdf")
+        plugins[idx] = fp
+        body[:plugins] = plugins
+      else
+        body[:plugins] = plugins + [{ id: "file-parser", pdf: { engine: engine } }]
+      end
+      body.delete("plugins")
+    end
+
+    def normalize_pdf_engine(pdf_engine)
+      s = pdf_engine.to_s.strip
+      s.empty? ? FILE_PARSER_DEFAULT_ENGINE : s
+    end
+
+    def chat_messages_include_pdf_attachment?(messages)
+      return false unless messages.is_a?(Array)
+
+      messages.any? { |msg| message_includes_pdf_file?(msg) }
+    end
+
+    def message_includes_pdf_file?(msg)
+      return false unless msg.is_a?(Hash)
+
+      content = msg[:content] || msg["content"]
+      return false unless content.is_a?(Array)
+
+      content.any? { |part| content_part_is_pdf_file?(part) }
+    end
+
+    def content_part_is_pdf_file?(part)
+      return false unless part.is_a?(Hash)
+
+      type = (part[:type] || part["type"]).to_s
+      return false unless type == "file"
+
+      file = part[:file] || part["file"]
+      return false unless file.is_a?(Hash)
+
+      pdf_file_attachment?(file)
+    end
+
+    def pdf_file_attachment?(file)
+      name = (file[:filename] || file["filename"]).to_s
+      return true if name.match?(/\.pdf\z/i)
+
+      data = file[:file_data] || file["file_data"] || file[:fileData] || file["fileData"]
+      return false unless data.is_a?(String)
+
+      return true if data.match?(%r{\Adata:application/pdf(?:;|\z)}i)
+
+      pdf_url?(data)
+    end
+
+    def pdf_url?(url)
+      return false unless url.match?(%r{\Ahttps?://}i)
+
+      uri = URI.parse(url)
+      uri.path.to_s.match?(/\.pdf\z/i)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def file_parser_pdf_engine_set?(plugin)
+      return false unless plugin.is_a?(Hash)
+
+      pdf = plugin[:pdf] || plugin["pdf"]
+      return false unless pdf.is_a?(Hash)
+
+      eng = (pdf[:engine] || pdf["engine"]).to_s
+      !eng.strip.empty?
+    end
+
+    def plugin_present?(plugins, id:)
+      return false unless plugins.is_a?(Array)
+
+      plugins.any? { |p| plugin_entry_id(p) == id.to_s }
+    end
+
+    def plugin_entry_id(entry)
+      return unless entry.is_a?(Hash)
+
+      (entry[:id] || entry["id"]).to_s
+    end
+  end
+end

data/lib/savvy_openrouter/resources/base.rb

@@ -11,6 +11,14 @@ module SavvyOpenrouter
 
       attr_reader :client
 
+      def logical_model_from_body(body)
+        return nil unless body.is_a?(Hash)
+
+        m = body[:model] || body["model"]
+        s = m.to_s.strip
+        s.empty? ? nil : s
+      end
+
       def conn
         client.connection
       end

data/lib/savvy_openrouter/resources/chat.rb

@@ -10,35 +10,45 @@ module SavvyOpenrouter
       def completions(messages:, **params)
         policy = CompletionRetryPolicy.new(config.chat_retries)
         body = config.merge_chat_body({ messages: messages }.merge(params))
-        attempt = 0
-        last_response = nil
-        loop do
-          attempt += 1
+        lm = logical_model_from_body(body)
+        conn.with_call_context(endpoint: "chat_completions", logical_model: lm) do
+          attempt = 0
+          last_response = nil
           begin
-            last_response = conn.post("/chat/completions", body: body)
-          rescue SavvyOpenrouter::ApiError => e
-            raise e if attempt >= policy.max_attempts || !policy.retry_http_error?(e)
+            loop do
+              attempt += 1
+              begin
+                last_response = conn.post("/chat/completions", body: body)
+              rescue SavvyOpenrouter::ApiError => e
+                raise e if attempt >= policy.max_attempts || !policy.retry_http_error?(e)
 
-            policy.wait_after_attempt(attempt)
-            next
-          end
+                policy.wait_after_attempt(attempt)
+                next
+              end
 
-          return last_response unless policy.retry_response?(last_response)
-          return last_response if attempt >= policy.max_attempts
+              return last_response unless policy.retry_response?(last_response)
+              return last_response if attempt >= policy.max_attempts
 
-          policy.wait_after_attempt(attempt)
+              policy.wait_after_attempt(attempt)
+            end
+          ensure
+            conn.flush_deferred_chat_log!
+          end
         end
       end
 
       # Yields each SSE `data:` payload string (JSON text from the model stream).
       def completions_stream(messages:, **params, &block)
         body = config.merge_chat_body({ messages: messages, stream: true }.merge(params))
-        return enum_for(:completions_stream, messages: messages, **params) unless block
+        lm = logical_model_from_body(body)
+        conn.with_call_context(endpoint: "chat_completions", logical_model: lm) do
+          return enum_for(:completions_stream, messages: messages, **params) unless block
 
-        chunk_enum = Enumerator.new do |y|
-          conn.stream_post("/chat/completions", body) { |ch| y << ch }
+          chunk_enum = Enumerator.new do |y|
+            conn.stream_post("/chat/completions", body) { |ch| y << ch }
+          end
+          Streaming.each_sse_data(chunk_enum, &block)
         end
-        Streaming.each_sse_data(chunk_enum, &block)
       end
     end
   end

data/lib/savvy_openrouter/resources/embeddings.rb

@@ -7,11 +7,16 @@ module SavvyOpenrouter
     class Embeddings < Base
       def create(**params)
         body = config.merge_chat_body(params)
-        conn.post("/embeddings", body: body)
+        lm = logical_model_from_body(body)
+        conn.with_call_context(endpoint: "embeddings", logical_model: lm) do
+          conn.post("/embeddings", body: body)
+        end
       end
 
       def models
-        conn.get("/embeddings/models")
+        conn.with_call_context(endpoint: "embeddings_models", logical_model: nil) do
+          conn.get("/embeddings/models")
+        end
       end
     end
   end

data/lib/savvy_openrouter/resources/generations.rb

@@ -6,11 +6,15 @@ module SavvyOpenrouter
   module Resources
     class Generations < Base
       def get(id:)
-        conn.get("/generation", params: { id: id })
+        conn.with_call_context(endpoint: "generation", logical_model: nil) do
+          conn.get("/generation", params: { id: id })
+        end
       end
 
       def content(**params)
-        conn.get("/generation/content", params: params)
+        conn.with_call_context(endpoint: "generation_content", logical_model: nil) do
+          conn.get("/generation/content", params: params)
+        end
       end
     end
   end

data/lib/savvy_openrouter/resources/models.rb

@@ -8,28 +8,38 @@ module SavvyOpenrouter
       # Query params match OpenRouter GET /models (e.g. category, output_modalities, supported_parameters).
       def list(**params)
         query = stringify_query(params)
-        conn.get("/models", params: query.empty? ? nil : query)
+        conn.with_call_context(endpoint: "models", logical_model: nil) do
+          conn.get("/models", params: query.empty? ? nil : query)
+        end
       end
 
-      # Uses GET /models with filters, then returns the first model whose prompt + completion pricing are zero.
-      # OpenRouter returns models in curated rank order within a category; first matching free model aligns with
-      # site “top free” picks when combined with output_modalities=text.
+      # Uses GET /models with category + free-price filters, then returns the first model whose prompt and
+      # completion pricing are both zero. OpenRouter returns models in curated rank order; the first free
+      # match aligns with site “top free” picks when combined with output_modalities=text.
+      # Models scheduled for removal (expiration_date) are still eligible — callers often want the current
+      # top free pick even when it is temporary.
       def first_ranked_free_text_model(category:, output_modalities: "text")
-        res = list(category: category, output_modalities: output_modalities)
+        res = list(category: category, output_modalities: output_modalities, max_price: 0)
         data = res[:data] || []
         data.find { |m| free_pricing?(m) }
       end
 
       def count
-        conn.get("/models/count")
+        conn.with_call_context(endpoint: "models_count", logical_model: nil) do
+          conn.get("/models/count")
+        end
       end
 
       def user
-        conn.get("/models/user")
+        conn.with_call_context(endpoint: "models_user", logical_model: nil) do
+          conn.get("/models/user")
+        end
       end
 
       def endpoints(author:, slug:)
-        conn.get("/models/#{author}/#{slug}/endpoints")
+        conn.with_call_context(endpoint: "models_endpoints", logical_model: nil) do
+          conn.get("/models/#{author}/#{slug}/endpoints")
+        end
       end
 
       private

data/lib/savvy_openrouter/resources/responses.rb

@@ -1,13 +1,39 @@
 # frozen_string_literal: true
 
 require_relative "base"
+require_relative "../responses_retry_policy"
 
 module SavvyOpenrouter
   module Resources
     class Responses < Base
       def create(**params)
+        policy = ResponsesRetryPolicy.new(config.responses_retries)
         body = config.merge_responses_body(params)
-        conn.post("/responses", body: body)
+        lm = logical_model_from_body(body)
+        conn.with_call_context(endpoint: "responses", logical_model: lm) do
+          attempt = 0
+          last_response = nil
+          begin
+            loop do
+              attempt += 1
+              begin
+                last_response = conn.post("/responses", body: body)
+              rescue SavvyOpenrouter::ApiError => e
+                raise e if attempt >= policy.max_attempts || !policy.retry_http_error?(e)
+
+                policy.wait_after_attempt(attempt)
+                next
+              end
+
+              return last_response unless policy.retry_response?(last_response)
+              return last_response if attempt >= policy.max_attempts
+
+              policy.wait_after_attempt(attempt)
+            end
+          ensure
+            conn.flush_deferred_responses_log!
+          end
+        end
       end
     end
   end

data/lib/savvy_openrouter/responses_retry_policy.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  # Retries for +Resources::Responses#create+ (zero output tokens / selected HTTP errors).
+  class ResponsesRetryPolicy
+    DEFAULT_ON = {
+      "zero_output_tokens" => true,
+      "rate_limit" => true,
+      "bad_gateway" => true,
+      "internal_server_error" => true,
+      "service_unavailable" => true
+    }.freeze
+
+    def initialize(raw)
+      @raw =
+        case raw
+        when false, nil then {}
+        when Hash then Configuration.stringify_keys_static(raw)
+        else
+          raise ArgumentError, "responses_retries must be a Hash or false"
+        end
+    end
+
+    def max_attempts
+      n = @raw["max_attempts"]
+      i = Integer(n, exception: false)
+      i&.positive? ? i : 1
+    end
+
+    def enabled?
+      max_attempts > 1
+    end
+
+    def retry_http_error?(error)
+      return false unless enabled?
+      return false unless error.is_a?(SavvyOpenrouter::ApiError)
+
+      code = error.status_code
+      return false unless code
+
+      flag =
+        case code
+        when 429 then "rate_limit"
+        when 502 then "bad_gateway"
+        when 500, 501 then "internal_server_error"
+        when 503 then "service_unavailable"
+        end
+      flag ? on?(flag) : false
+    end
+
+    def retry_response?(response)
+      return false unless enabled?
+
+      on?("zero_output_tokens") && responses_zero_output_retry?(response)
+    end
+
+    def wait_after_attempt(attempt_number)
+      base = integer_opt(@raw["base_delay_ms"], 400)
+      max_d = integer_opt(@raw["max_delay_ms"], 10_000)
+      exponential = @raw["exponential_backoff"] != false
+      jitter_ratio = float_opt(@raw["jitter_ratio"], 0.15)
+
+      delay_ms =
+        if exponential
+          base * (2**(attempt_number - 1))
+        else
+          base
+        end
+      delay_ms = [delay_ms, max_d].min
+      jitter = jitter_ratio.clamp(0.0, 1.0) * delay_ms * rand
+      sleep((delay_ms + jitter) / 1000.0)
+    end
+
+    private
+
+    def on?(key)
+      DEFAULT_ON.merge(explicit_on)[key.to_s] == true
+    end
+
+    def explicit_on
+      h = @raw["on"]
+      h.is_a?(Hash) ? Configuration.stringify_keys_static(h) : {}
+    end
+
+    # Aligns with OpenRouter zero-completion / empty Responses output heuristics.
+    def responses_zero_output_retry?(json)
+      return false unless json.is_a?(Hash)
+
+      usage = json[:usage] || json["usage"]
+      return false unless usage.is_a?(Hash)
+
+      out = usage[:output_tokens] || usage["output_tokens"]
+      return false if out.nil?
+      return false if out.to_i.positive?
+
+      status = (json[:status] || json["status"]).to_s
+      return true if %w[failed cancelled incomplete queued in_progress].include?(status)
+
+      status == "completed"
+    end
+
+    def integer_opt(val, default)
+      i = Integer(val, exception: false)
+      i&.positive? ? i : default
+    end
+
+    def float_opt(val, default)
+      f = Float(val, exception: false)
+      f.nil? || f.negative? ? default : f
+    end
+  end
+end

data/lib/savvy_openrouter/structured_output_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  # Raised when json_object/json_schema was requested but the successful response body
+  # does not contain usable JSON in assistant/output text. Optional +require "savvy_openrouter/patterns"+.
+  #
+  # reason: +:empty_content+, +:invalid_json+, +:no_choices+
+  class StructuredOutputError < StandardError
+    attr_reader :reason, :response_body
+
+    def initialize(message, reason:, response_body: nil)
+      @reason = reason
+      @response_body = response_body
+      super(message)
+    end
+  end
+end

data/lib/savvy_openrouter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SavvyOpenrouter
-  VERSION = "0.2.0"
+  VERSION = "0.4.2"
 end

data/lib/savvy_openrouter.rb

@@ -4,6 +4,7 @@ require_relative "savvy_openrouter/version"
 require_relative "savvy_openrouter/errors"
 require_relative "savvy_openrouter/configuration"
 require_relative "savvy_openrouter/completion_retry_policy"
+require_relative "savvy_openrouter/responses_retry_policy"
 require_relative "savvy_openrouter/api_call_logger"
 require_relative "savvy_openrouter/connection"
 require_relative "savvy_openrouter/streaming"

data/sig/savvy_openrouter.rbs

@@ -40,6 +40,21 @@ module SavvyOpenrouter
   class TimeoutPollError < Error
   end
 
+  class StructuredOutputError < StandardError
+    attr_reader reason: Symbol
+    attr_reader response_body: untyped
+    def initialize: (String message, reason: Symbol, ?response_body: untyped) -> void
+  end
+
+  class ResponsesRetryPolicy
+    def initialize: (Hash[String, untyped] | false? raw) -> void
+    def max_attempts: () -> Integer
+    def enabled?: () -> bool
+    def retry_http_error?: (ApiError error) -> bool
+    def retry_response?: (Hash[Symbol | String, untyped] response) -> bool
+    def wait_after_attempt: (Integer attempt_number) -> void
+  end
+
   class Configuration
     attr_accessor api_key: String?
     attr_accessor base_url: String
@@ -51,6 +66,8 @@ module SavvyOpenrouter
     attr_reader responses_defaults: Hash[String, untyped]
     attr_reader api_call_log: Hash[String, untyped]
     attr_reader chat_retries: Hash[String, untyped]
+    attr_reader responses_retries: Hash[String, untyped]
+    attr_reader file_parser_pdf_engine: String?
 
     def initialize: (?config_path: String?, **untyped options) -> void
     def merge_chat_body: (Hash[Symbol | String, untyped] body) -> Hash[String, untyped]
@@ -64,6 +81,8 @@ module SavvyOpenrouter
     def initialize: (Hash[String, untyped] config) -> void
     def enabled?: () -> bool
     def max_body_limit: () -> Integer
+    def chat_attempts_final?: () -> bool
+    def responses_attempts_final?: () -> bool
     def record: (Hash[String, untyped] attrs) -> untyped
     def self.format_body_for_log: (untyped obj, ?max_bytes: Integer) -> String
   end
@@ -81,8 +100,13 @@ module SavvyOpenrouter
     DEFAULT_SUCCESS: Array[Integer]
 
     attr_reader config: Configuration
+    attr_reader api_call_logger: ApiCallLogger
 
     def initialize: (Configuration config) -> void
+    def with_call_context: (?Hash[Symbol | String, untyped] context) { () -> untyped } -> untyped
+    def record_manual_api_call: (Hash[Symbol | String, untyped] attrs) -> untyped
+    def flush_deferred_chat_log!: () -> void
+    def flush_deferred_responses_log!: () -> void
     def get: (String path, ?params: Hash[Symbol | String, untyped]?, ?success: Array[Integer]?) -> untyped
     def delete: (String path, ?params: Hash[Symbol | String, untyped]?, ?success: Array[Integer]?) -> untyped
     def post: (String path, body: Hash[Symbol | String, untyped], ?success: Array[Integer]?) -> untyped
@@ -100,6 +124,9 @@ module SavvyOpenrouter
 
     def initialize: (?config_path: String?, **untyped options) -> void
 
+    def api_call_logger: () -> ApiCallLogger
+    def record_api_call: (Hash[Symbol | String, untyped] attrs) -> untyped
+
     def chat: -> Resources::Chat
     def responses: -> Resources::Responses
     def anthropic_messages: -> Resources::AnthropicMessages

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: savvy_openrouter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Bryan Feller
 bindir: exe
 cert_chain: []
-date: 2026-05-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -112,8 +112,13 @@ files:
 - lib/savvy_openrouter/completion_retry_policy.rb
 - lib/savvy_openrouter/configuration.rb
 - lib/savvy_openrouter/connection.rb
+- lib/savvy_openrouter/connection_api_call_recording.rb
+- lib/savvy_openrouter/connection_api_call_recording_transport.rb
 - lib/savvy_openrouter/connection_instrumentation.rb
 - lib/savvy_openrouter/errors.rb
+- lib/savvy_openrouter/patterns.rb
+- lib/savvy_openrouter/patterns/structured_output.rb
+- lib/savvy_openrouter/request_plugins.rb
 - lib/savvy_openrouter/resources/analytics.rb
 - lib/savvy_openrouter/resources/anthropic_messages.rb
 - lib/savvy_openrouter/resources/api_keys.rb
@@ -133,17 +138,18 @@ files:
 - lib/savvy_openrouter/resources/responses.rb
 - lib/savvy_openrouter/resources/videos.rb
 - lib/savvy_openrouter/resources/workspaces.rb
+- lib/savvy_openrouter/responses_retry_policy.rb
 - lib/savvy_openrouter/streaming.rb
+- lib/savvy_openrouter/structured_output_error.rb
 - lib/savvy_openrouter/version.rb
-- savvy_openrouter-0.1.0.gem
 - sig/savvy_openrouter.rbs
-homepage: https://github.com/brizzlefeller/savvy_openrouter
+homepage: https://github.com/bfeller/savvy_openrouter
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/brizzlefeller/savvy_openrouter
-  source_code_uri: https://github.com/brizzlefeller/savvy_openrouter
-  changelog_uri: https://github.com/brizzlefeller/savvy_openrouter/blob/master/CHANGELOG.md
+  homepage_uri: https://github.com/bfeller/savvy_openrouter
+  source_code_uri: https://github.com/bfeller/savvy_openrouter
+  changelog_uri: https://github.com/bfeller/savvy_openrouter/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -159,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Ruby client for the OpenRouter unified AI API.
 test_files: []