savvy_openrouter 0.2.0

data/lib/savvy_openrouter/connection.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require_relative "connection_instrumentation"
+
+require "faraday"
+require "json"
+require "net/http"
+require "uri"
+
+module SavvyOpenrouter
+  class Connection
+    include Instrumentation
+
+    DEFAULT_SUCCESS = [200, 201, 202, 204].freeze
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @api_call_logger = ApiCallLogger.new(config.api_call_log)
+      base = normalize_base(config.base_url)
+      headers = build_headers
+      @conn = Faraday.new(url: base, headers: headers) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson/, parser_options: { symbolize_names: true }
+        faraday.adapter Faraday.default_adapter
+      end
+      @raw = Faraday.new(url: base, headers: headers) do |faraday|
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def get(path, params: nil, success: DEFAULT_SUCCESS)
+      timed_json(:get, path, params: params, success: success)
+    end
+
+    def delete(path, params: nil, success: DEFAULT_SUCCESS)
+      timed_json(:delete, path, params: params, success: success)
+    end
+
+    def post(path, body:, success: DEFAULT_SUCCESS)
+      timed_json(:post, path, body: body, success: success)
+    end
+
+    def patch(path, body:, success: DEFAULT_SUCCESS)
+      timed_json(:patch, path, body: body, success: success)
+    end
+
+    def put(path, body:, success: DEFAULT_SUCCESS)
+      timed_json(:put, path, body: body, success: success)
+    end
+
+    def get_raw(path, params: nil, success: [200])
+      rel = rel_path(path)
+      started = monotonic_ms
+      response = @raw.get(rel) do |req|
+        req.params.update(params) if params
+      end
+      duration_ms = elapsed_ms(started)
+      record_faraday_raw(
+        method: "GET",
+        rel_path: rel,
+        params: params,
+        request_body: nil,
+        response: response,
+        duration_ms: duration_ms
+      )
+      status = response.status
+      return response.body.b.freeze if success.include?(status)
+
+      raise_api_error(status, response.body)
+    rescue SavvyOpenrouter::ApiError
+      raise
+    rescue StandardError => e
+      record_transport_error(
+        method: "GET",
+        rel_path: rel,
+        params: params,
+        request_body: nil,
+        duration_ms: elapsed_ms(started),
+        error: e
+      )
+      raise
+    end
+
+    def post_raw(path, body:, success: [200])
+      rel = rel_path(path)
+      started = monotonic_ms
+      response = @raw.post(rel) do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(stringify_body(body))
+      end
+      duration_ms = elapsed_ms(started)
+      record_faraday_raw(
+        method: "POST",
+        rel_path: rel,
+        params: nil,
+        request_body: body,
+        response: response,
+        duration_ms: duration_ms
+      )
+      status = response.status
+      return response.body.b.freeze if success.include?(status)
+
+      raise_api_error(status, response.body)
+    rescue SavvyOpenrouter::ApiError
+      raise
+    rescue StandardError => e
+      record_transport_error(
+        method: "POST",
+        rel_path: rel,
+        params: nil,
+        request_body: body,
+        duration_ms: elapsed_ms(started),
+        error: e
+      )
+      raise
+    end
+
+    def stream_get(path, params: nil, &block)
+      ensure_api_key!
+      uri = join_uri(path)
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+
+      req = Net::HTTP::Get.new(uri)
+      build_headers.each { |k, v| req[k] = v }
+
+      started = monotonic_ms
+      status, err_buf = stream_via_net_http(uri, req, &block)
+      duration_ms = elapsed_ms(started)
+      record_stream(
+        method: "GET",
+        rel_path: rel_path(path),
+        params: params,
+        request_body: nil,
+        status: status,
+        response_body: err_buf,
+        duration_ms: duration_ms
+      )
+      return if status == 200
+
+      raise_api_error(status, err_buf) if status
+    rescue SavvyOpenrouter::ApiError
+      raise
+    rescue StandardError => e
+      record_transport_error(
+        method: "GET",
+        rel_path: rel_path(path),
+        params: params,
+        request_body: nil,
+        duration_ms: elapsed_ms(started),
+        error: e
+      )
+      raise
+    end
+
+    def stream_post(path, body, &)
+      ensure_api_key!
+      uri = join_uri(path)
+      req = Net::HTTP::Post.new(uri)
+      build_headers.each { |k, v| req[k] = v }
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "text/event-stream"
+      req.body = JSON.generate(stringify_body(body))
+
+      started = monotonic_ms
+      status, err_buf = stream_via_net_http(uri, req, &)
+      duration_ms = elapsed_ms(started)
+      record_stream(
+        method: "POST",
+        rel_path: rel_path(path),
+        params: nil,
+        request_body: body,
+        status: status,
+        response_body: err_buf,
+        duration_ms: duration_ms
+      )
+      return if status == 200
+
+      raise_api_error(status, err_buf) if status
+    rescue SavvyOpenrouter::ApiError
+      raise
+    rescue StandardError => e
+      record_transport_error(
+        method: "POST",
+        rel_path: rel_path(path),
+        params: nil,
+        request_body: body,
+        duration_ms: elapsed_ms(started),
+        error: e
+      )
+      raise
+    end
+
+    private
+
+    def stream_via_net_http(uri, req, &block)
+      status = nil
+      err_buf = nil
+      Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(req) do |res|
+          status = res.code.to_i
+          unless status == 200
+            buf = +""
+            res.read_body { |c| buf << c }
+            err_buf = buf
+            next
+          end
+
+          res.read_body(&block)
+        end
+      end
+      [status, err_buf]
+    end
+
+    def stringify_body(body)
+      case body
+      when Hash
+        body.transform_keys(&:to_s)
+      else
+        body
+      end
+    end
+
+    def parse_json_response(response, success:)
+      status = response.status
+      return response.body if success.include?(status)
+      return nil if status == 204
+
+      raise_api_error(status, response.body)
+    end
+
+    def raise_api_error(status, body)
+      payload = parse_error_payload(body)
+      message = extract_message(payload)
+      exception_class = error_class_for(status)
+      raise exception_class.new(
+        message,
+        status_code: status,
+        response_body: payload
+      )
+    end
+
+    def parse_error_payload(body)
+      case body
+      when Hash
+        body
+      when String
+        return {} if body.strip.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      else
+        {}
+      end
+    rescue JSON::ParserError
+      { raw: body.to_s }
+    end
+
+    def extract_message(payload)
+      err = payload[:error] || payload["error"]
+      case err
+      when Hash
+        err[:message] || err["message"] || err.inspect
+      when String
+        err
+      else
+        "HTTP error (#{payload.inspect})"
+      end
+    end
+
+    def error_class_for(status)
+      case status
+      when 400 then BadRequestError
+      when 401 then AuthenticationError
+      when 402 then PaymentRequiredError
+      when 403 then ForbiddenError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500, 501 then InternalServerError
+      when 502 then BadGatewayError
+      else ApiError
+      end
+    end
+
+    def ensure_api_key!
+      return if config.api_key && !config.api_key.to_s.empty?
+
+      raise ConfigurationError, "OpenRouter api_key is missing; set OPENROUTER_API_KEY or pass api_key: to SavvyOpenrouter::Client"
+    end
+
+    def build_headers
+      ensure_api_key!
+      h = {
+        "Authorization" => "Bearer #{config.api_key}",
+        "Accept" => "application/json"
+      }
+      h["HTTP-Referer"] = config.http_referer if config.http_referer && !config.http_referer.to_s.empty?
+      h["X-Title"] = config.app_title if config.app_title && !config.app_title.to_s.empty?
+      h
+    end
+
+    def normalize_base(url)
+      url.to_s.chomp("/")
+    end
+
+    def rel_path(path)
+      path.to_s.delete_prefix("/")
+    end
+
+    def join_uri(path)
+      base = normalize_base(config.base_url)
+      rel = rel_path(path)
+      URI.parse("#{base}/#{rel}")
+    end
+  end
+end

data/lib/savvy_openrouter/connection_instrumentation.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  class Connection
+    # Timing + persistence hooks for optional request logging ({api_call_log} config).
+    module Instrumentation
+      private
+
+      def timed_json(method_sym, path, params: nil, body: nil, success: DEFAULT_SUCCESS)
+        rel = rel_path(path)
+        started = monotonic_ms
+        response =
+          case method_sym
+          when :get then @conn.get(rel) { |req| req.params.update(params) if params }
+          when :delete then @conn.delete(rel) { |req| req.params.update(params) if params }
+          when :post then @conn.post(rel, body)
+          when :patch then @conn.patch(rel, body)
+          when :put then @conn.put(rel, body)
+          else raise ArgumentError, "unsupported #{method_sym}"
+          end
+        duration_ms = elapsed_ms(started)
+        record_faraday_json(method: method_sym.to_s.upcase, rel_path: rel, params: params, request_body: body, response: response,
+                            duration_ms: duration_ms)
+        parse_json_response(response, success: success)
+      rescue SavvyOpenrouter::ApiError
+        raise
+      rescue StandardError => e
+        record_transport_error(method: method_sym.to_s.upcase, rel_path: rel, params: params, request_body: body,
+                               duration_ms: elapsed_ms(started), error: e)
+        raise
+      end
+
+      def record_faraday_json(method:, rel_path:, params:, request_body:, response:, duration_ms:)
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        @api_call_logger.record(
+          "method" => method,
+          "path" => full_url(rel_path, params),
+          "status" => response.status,
+          "duration_ms" => duration_ms.round(3),
+          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+          "response_body" => ApiCallLogger.format_body_for_log(response.body, max_bytes: lim),
+          "error_class" => nil,
+          "error_message" => nil,
+          "streaming" => false
+        )
+      end
+
+      def record_faraday_raw(method:, rel_path:, params:, request_body:, response:, duration_ms:)
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        body_for_resp =
+          if response.body.is_a?(String) && response.body.encoding == Encoding::ASCII_8BIT
+            "[binary #{response.body.bytesize} bytes]"
+          else
+            response.body
+          end
+        @api_call_logger.record(
+          "method" => method,
+          "path" => full_url(rel_path, params),
+          "status" => response.status,
+          "duration_ms" => duration_ms.round(3),
+          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+          "response_body" => ApiCallLogger.format_body_for_log(body_for_resp, max_bytes: lim),
+          "error_class" => nil,
+          "error_message" => nil,
+          "streaming" => false
+        )
+      end
+
+      def record_stream(method:, rel_path:, params:, request_body:, status:, response_body:, duration_ms:)
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        preview =
+          if status == 200
+            "[stream completed]"
+          else
+            response_body
+          end
+        @api_call_logger.record(
+          "method" => method,
+          "path" => full_url(rel_path, params),
+          "status" => status,
+          "duration_ms" => duration_ms.round(3),
+          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+          "response_body" => ApiCallLogger.format_body_for_log(preview, max_bytes: lim),
+          "error_class" => nil,
+          "error_message" => nil,
+          "streaming" => true
+        )
+      end
+
+      def record_transport_error(method:, rel_path:, params:, request_body:, duration_ms:, error:)
+        return unless @api_call_logger.enabled?
+
+        lim = @api_call_logger.max_body_limit
+        msg = ApiCallLogger.format_body_for_log(error.message, max_bytes: lim)
+
+        @api_call_logger.record(
+          "method" => method,
+          "path" => full_url(rel_path, params),
+          "status" => nil,
+          "duration_ms" => duration_ms.round(3),
+          "request_body" => ApiCallLogger.format_body_for_log(request_body, max_bytes: lim),
+          "response_body" => "",
+          "error_class" => error.class.name,
+          "error_message" => msg,
+          "streaming" => false
+        )
+      end
+
+      def full_url(rel_path, params)
+        u = join_uri(rel_path)
+        if params && !params.empty?
+          flat = params.transform_keys(&:to_s)
+          u.query = URI.encode_www_form(flat)
+        end
+        u.to_s
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000
+      end
+
+      def elapsed_ms(started)
+        monotonic_ms - started
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  class Error < StandardError
+    attr_reader :status_code, :response_body
+
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      super(message || self.class.name)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error; end
+
+  class BadRequestError < ApiError; end
+
+  class AuthenticationError < ApiError; end
+
+  class PaymentRequiredError < ApiError; end
+
+  class ForbiddenError < ApiError; end
+
+  class NotFoundError < ApiError; end
+
+  class RateLimitError < ApiError; end
+
+  class InternalServerError < ApiError; end
+
+  class BadGatewayError < ApiError; end
+
+  class TimeoutPollError < Error; end
+end

data/lib/savvy_openrouter/resources/analytics.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Analytics < Base
+      def activity(**params)
+        conn.get("/activity", params: params)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/anthropic_messages.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class AnthropicMessages < Base
+      def create(**params)
+        body = config.merge_chat_body(params)
+        conn.post("/messages", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/api_keys.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class ApiKeys < Base
+      def current
+        conn.get("/key")
+      end
+
+      def list(**params)
+        conn.get("/keys", params: params)
+      end
+
+      def create(**body)
+        conn.post("/keys", body: body, success: [201])
+      end
+
+      def get(hash)
+        conn.get("/keys/#{hash}")
+      end
+
+      def update(hash, **body)
+        conn.patch("/keys/#{hash}", body: body)
+      end
+
+      def delete(hash)
+        conn.delete("/keys/#{hash}")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/audio.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Audio < Base
+      def speech(**params)
+        body = config.merge_chat_body(params)
+        conn.post_raw("/audio/speech", body: body)
+      end
+
+      def transcribe(**params)
+        body = config.merge_chat_body(params)
+        conn.post("/audio/transcriptions", body: body)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SavvyOpenrouter
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      def conn
+        client.connection
+      end
+
+      def config
+        client.config
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/chat.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../streaming"
+require_relative "../completion_retry_policy"
+
+module SavvyOpenrouter
+  module Resources
+    class Chat < Base
+      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
+          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
+
+          return last_response unless policy.retry_response?(last_response)
+          return last_response if attempt >= policy.max_attempts
+
+          policy.wait_after_attempt(attempt)
+        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
+
+        chunk_enum = Enumerator.new do |y|
+          conn.stream_post("/chat/completions", body) { |ch| y << ch }
+        end
+        Streaming.each_sse_data(chunk_enum, &block)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/credits.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Credits < Base
+      def get
+        conn.get("/credits")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/embeddings.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Embeddings < Base
+      def create(**params)
+        body = config.merge_chat_body(params)
+        conn.post("/embeddings", body: body)
+      end
+
+      def models
+        conn.get("/embeddings/models")
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/endpoints.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Endpoints < Base
+      def zdr(**params)
+        conn.get("/endpoints/zdr", params: params)
+      end
+    end
+  end
+end

data/lib/savvy_openrouter/resources/generations.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SavvyOpenrouter
+  module Resources
+    class Generations < Base
+      def get(id:)
+        conn.get("/generation", params: { id: id })
+      end
+
+      def content(**params)
+        conn.get("/generation/content", params: params)
+      end
+    end
+  end
+end