savvy_openrouter 0.2.0

data/lib/savvy_openrouter/api_call_logger.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SavvyOpenrouter
+  # Persists OpenRouter HTTP exchanges when configured via +api_call_log+ (YAML or Client kwargs).
+  # Failures while saving never raise into application code.
+  class ApiCallLogger
+    DEFAULT_MAX_BODY_BYTES = 65_536
+
+    CANONICAL_KEYS = %w[
+      method path status duration_ms request_body response_body error_class error_message streaming
+    ].freeze
+
+    class << self
+      def format_body_for_log(obj, max_bytes: DEFAULT_MAX_BODY_BYTES)
+        str =
+          case obj
+          when nil then +""
+          when String then obj.b
+          else
+            JSON.generate(obj)
+          end
+        str = redact_secrets(str)
+        truncate_bytes(str, max_bytes)
+      end
+
+      private
+
+      def redact_secrets(str)
+        s = str.dup
+        s.gsub!(/sk-or-v1-[A-Za-z0-9_-]+/, "sk-or-v1-[REDACTED]")
+        s.gsub!(/Bearer\s+[A-Za-z0-9._-]+/i, "Bearer [REDACTED]")
+        s
+      end
+
+      def truncate_bytes(str, max_bytes)
+        return str if str.bytesize <= max_bytes
+
+        "#{str.byteslice(0, max_bytes)}…(truncated)"
+      end
+    end
+
+    def initialize(config)
+      @config = config.is_a?(Hash) ? Configuration.stringify_keys_static(config) : {}
+    end
+
+    def enabled?
+      m = @config["model"]
+      !m.nil? && !m.to_s.strip.empty? &&
+        @config["columns"].is_a?(Hash) && !@config["columns"].empty?
+    end
+
+    def max_body_limit
+      n = @config["max_body_bytes"]
+      n.is_a?(Integer) && n.positive? ? n : DEFAULT_MAX_BODY_BYTES
+    end
+
+    # +attrs+ uses canonical string keys (see CANONICAL_KEYS). Column mapping is applied before create.
+    def record(attrs)
+      return unless enabled?
+
+      row = build_row(attrs)
+      return if row.empty?
+
+      constantize_model(@config["model"].to_s.strip).create!(row)
+    rescue StandardError => e
+      warn "[savvy_openrouter] api_call_log skipped: #{e.class}: #{e.message}" if $VERBOSE
+      nil
+    end
+
+    private
+
+    def build_row(attrs)
+      cols = @config["columns"] || {}
+      attrs = Configuration.stringify_keys_static(attrs)
+      cols.each_with_object({}) do |(canonical, column_name), acc|
+        next unless CANONICAL_KEYS.include?(canonical.to_s)
+        next unless attrs.key?(canonical.to_s)
+
+        acc[column_name.to_s] = attrs[canonical.to_s]
+      end
+    end
+
+    def constantize_model(name)
+      raise NameError, "blank model" if name.empty?
+      raise NameError, "invalid model name #{name.inspect}" if name.include?("..") || /[^A-Za-z0-9_:]/.match?(name)
+
+      parts = name.delete_prefix("::").split("::")
+      parts.reduce(Object) { |mod, piece| mod.const_get(piece) }
+    end
+  end
+end

data/lib/savvy_openrouter/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "connection"
+require_relative "resources/chat"
+require_relative "resources/responses"
+require_relative "resources/anthropic_messages"
+require_relative "resources/embeddings"
+require_relative "resources/rerank"
+require_relative "resources/models"
+require_relative "resources/credits"
+require_relative "resources/providers"
+require_relative "resources/generations"
+require_relative "resources/endpoints"
+require_relative "resources/analytics"
+require_relative "resources/audio"
+require_relative "resources/videos"
+require_relative "resources/oauth"
+require_relative "resources/api_keys"
+require_relative "resources/organization"
+require_relative "resources/guardrails"
+require_relative "resources/workspaces"
+
+module SavvyOpenrouter
+  class Client
+    attr_reader :config, :connection
+
+    def initialize(config_path: nil, **options)
+      @config = Configuration.new(config_path: config_path, **options)
+      @connection = Connection.new(@config)
+    end
+
+    def chat
+      @chat ||= Resources::Chat.new(self)
+    end
+
+    def responses
+      @responses ||= Resources::Responses.new(self)
+    end
+
+    def anthropic_messages
+      @anthropic_messages ||= Resources::AnthropicMessages.new(self)
+    end
+
+    def embeddings
+      @embeddings ||= Resources::Embeddings.new(self)
+    end
+
+    def rerank
+      @rerank ||= Resources::Rerank.new(self)
+    end
+
+    def models
+      @models ||= Resources::Models.new(self)
+    end
+
+    def credits
+      @credits ||= Resources::Credits.new(self)
+    end
+
+    def providers
+      @providers ||= Resources::Providers.new(self)
+    end
+
+    def generations
+      @generations ||= Resources::Generations.new(self)
+    end
+
+    def endpoints
+      @endpoints ||= Resources::Endpoints.new(self)
+    end
+
+    def analytics
+      @analytics ||= Resources::Analytics.new(self)
+    end
+
+    def audio
+      @audio ||= Resources::Audio.new(self)
+    end
+
+    def videos
+      @videos ||= Resources::Videos.new(self)
+    end
+
+    def oauth
+      @oauth ||= Resources::OAuth.new(self)
+    end
+
+    def api_keys
+      @api_keys ||= Resources::ApiKeys.new(self)
+    end
+
+    def organization
+      @organization ||= Resources::Organization.new(self)
+    end
+
+    def guardrails
+      @guardrails ||= Resources::Guardrails.new(self)
+    end
+
+    def workspaces
+      @workspaces ||= Resources::Workspaces.new(self)
+    end
+  end
+end

data/lib/savvy_openrouter/completion_retry_policy.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  # Controls optional retries for +Chat#completions+ (non-streaming): empty/zero-token
+  # completions and selected HTTP errors from OpenRouter.
+  class CompletionRetryPolicy
+    DEFAULT_ON = {
+      "zero_completion_tokens" => true,
+      "empty_assistant_content" => 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, "chat_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_completion_tokens") && zero_completion_tokens?(response)) ||
+        (on?("empty_assistant_content") && empty_assistant_content?(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)
+      merged_on[key.to_s] == true
+    end
+
+    def merged_on
+      @merged_on ||= DEFAULT_ON.merge(explicit_on)
+    end
+
+    def explicit_on
+      h = @raw["on"]
+      h.is_a?(Hash) ? Configuration.stringify_keys_static(h) : {}
+    end
+
+    def zero_completion_tokens?(response)
+      usage = dig_usage(response)
+      return false unless usage
+
+      ct = usage[:completion_tokens] || usage["completion_tokens"]
+      ct.nil? ? false : ct.to_i.zero?
+    end
+
+    def empty_assistant_content?(response)
+      msg = first_assistant_message(response)
+      return false unless msg
+
+      tool_calls = msg[:tool_calls] || msg["tool_calls"]
+      return false if tool_calls.is_a?(Array) && !tool_calls.empty?
+
+      content = msg[:content] || msg["content"]
+      return true if content.nil?
+
+      !content.is_a?(String) || content.strip.empty?
+    end
+
+    def dig_usage(response)
+      response[:usage] || response["usage"]
+    end
+
+    def first_assistant_message(response)
+      choices = response[:choices] || response["choices"]
+      return nil unless choices.is_a?(Array) && choices.first
+
+      choice = choices.first
+      choice[:message] || choice["message"]
+    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/configuration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module SavvyOpenrouter
+  class Configuration
+    attr_accessor :api_key, :base_url, :default_model, :http_referer, :app_title
+    attr_reader :defaults, :video_defaults, :responses_defaults, :api_call_log, :chat_retries
+
+    alias llm_model default_model
+    alias llm_model= default_model=
+
+    def self.load_file(path)
+      return {} unless path && File.file?(path)
+
+      data = YAML.safe_load(File.read(path), permitted_classes: [], permitted_symbols: [], aliases: true)
+      data.is_a?(Hash) ? stringify_keys_static(data) : {}
+    end
+
+    def self.stringify_keys_static(hash)
+      hash.each_with_object({}) do |(k, v), acc|
+        acc[k.to_s] = v.is_a?(Hash) ? stringify_keys_static(v) : v
+      end
+    end
+
+    # Precedence: explicit keyword args (highest) > YAML file > ENV (lowest).
+    def initialize(config_path: nil, **options)
+      @defaults = {}
+      @video_defaults = {}
+      @responses_defaults = {}
+      @api_call_log = {}
+      @chat_retries = {}
+      load_from_env!
+      yaml_path = config_path || self.class.discover_config_file
+      merge_hash!(self.class.load_file(yaml_path)) if yaml_path
+      apply_options!(options)
+    end
+
+    def self.discover_config_file(cwd = Dir.pwd)
+      %w[config/savvy_openrouter.yml .savvy_openrouter.yml].each do |rel|
+        path = File.join(cwd, rel)
+        return path if File.file?(path)
+      end
+      nil
+    end
+
+    def merge_hash!(hash)
+      return unless hash.is_a?(Hash)
+
+      hash = self.class.stringify_keys_static(hash)
+      @api_key = hash["api_key"] if hash.key?("api_key")
+      @base_url = hash["base_url"] if hash.key?("base_url")
+      @default_model = hash["default_model"] || hash["llm_model"] if hash.key?("default_model") || hash.key?("llm_model")
+      @http_referer = hash["http_referer"] if hash.key?("http_referer")
+      @app_title = hash["app_title"] || hash["x_title"] if hash.key?("app_title") || hash.key?("x_title")
+      @defaults = @defaults.merge(self.class.stringify_keys_static(hash["defaults"] || {}))
+      vd = hash["video_defaults"] || hash["defaults_video"]
+      @video_defaults = @video_defaults.merge(self.class.stringify_keys_static(vd || {}))
+      rd = hash["responses_defaults"] || hash["defaults_responses"]
+      @responses_defaults = @responses_defaults.merge(self.class.stringify_keys_static(rd || {}))
+      assign_api_call_log(hash["api_call_log"]) if hash.key?("api_call_log")
+      assign_chat_retries(hash["chat_retries"]) if hash.key?("chat_retries")
+      assign_chat_retries(hash["completion_retries"]) if hash.key?("completion_retries")
+    end
+
+    def merge_chat_body(body)
+      body = stringify_keys(body)
+      merged = @defaults.merge(body)
+      merged["model"] ||= @default_model if @default_model && merged["model"].nil?
+      merged
+    end
+
+    def merge_video_body(body)
+      body = stringify_keys(body)
+      merged = @video_defaults.merge(body)
+      merged["model"] ||= @default_model if @default_model && merged["model"].nil?
+      merged
+    end
+
+    # Defaults only for `POST /responses` (Responses API beta): `plugins`, `tools`,
+    # `max_output_tokens`, `x_search_filter`, etc. Keeps web-search settings off chat/embeddings bodies.
+    def merge_responses_body(body)
+      body = stringify_keys(body)
+      merged = @responses_defaults.merge(body)
+      merged["model"] ||= @default_model if @default_model && merged["model"].nil?
+      merged
+    end
+
+    private
+
+    def load_from_env!
+      @api_key = ENV.fetch("OPENROUTER_API_KEY", nil)
+      @base_url = ENV.fetch("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1")
+      @default_model = ENV.fetch("OPENROUTER_DEFAULT_MODEL", nil)
+      @http_referer = ENV.fetch("OPENROUTER_HTTP_REFERER", nil)
+      @app_title = ENV.fetch("OPENROUTER_APP_TITLE", nil)
+    end
+
+    def apply_options!(options)
+      opts = options.dup
+      @defaults = @defaults.merge(stringify_keys(opts.delete(:defaults) || {}))
+      vd = opts.delete(:video_defaults) || opts.delete(:defaults_video)
+      @video_defaults = @video_defaults.merge(stringify_keys(vd || {}))
+      rd = opts.delete(:responses_defaults) || opts.delete(:defaults_responses)
+      @responses_defaults = @responses_defaults.merge(stringify_keys(rd || {}))
+
+      @api_key = opts.delete(:api_key) if opts.key?(:api_key)
+      @base_url = opts.delete(:base_url) if opts.key?(:base_url)
+      if opts.key?(:default_model) || opts.key?(:llm_model)
+        @default_model = opts.delete(:default_model) || opts.delete(:llm_model)
+      end
+      @http_referer = opts.delete(:http_referer) if opts.key?(:http_referer)
+      @app_title = opts.delete(:app_title) if opts.key?(:app_title)
+      assign_api_call_log(opts.delete(:api_call_log)) if opts.key?(:api_call_log)
+      if opts.key?(:chat_retries)
+        assign_chat_retries(opts.delete(:chat_retries))
+      elsif opts.key?(:completion_retries)
+        assign_chat_retries(opts.delete(:completion_retries))
+      end
+
+      return if opts.empty?
+
+      raise ArgumentError, "Unknown keywords: #{opts.keys.join(", ")}"
+    end
+
+    def stringify_keys(hash)
+      self.class.stringify_keys_static(hash || {})
+    end
+
+    def assign_api_call_log(value)
+      case value
+      when false, nil
+        @api_call_log = {}
+      when Hash
+        h = self.class.stringify_keys_static(value)
+        h["columns"] = self.class.stringify_keys_static(h["columns"]) if h["columns"].is_a?(Hash)
+        @api_call_log = h
+      else
+        raise ArgumentError, "api_call_log must be a Hash or false"
+      end
+    end
+
+    def assign_chat_retries(value)
+      case value
+      when false, nil
+        @chat_retries = {}
+      when Hash
+        h = self.class.stringify_keys_static(value)
+        h["on"] = self.class.stringify_keys_static(h["on"]) if h["on"].is_a?(Hash)
+        @chat_retries = h
+      else
+        raise ArgumentError, "chat_retries must be a Hash or false"
+      end
+    end
+  end
+end