ruby_decision_model 0.0.1 → 0.2.0

data/lib/ruby_decision_model/client.rb

@@ -2,137 +2,242 @@
 
 require "json"
 require "net/http"
+require "openssl"
 require "uri"
 
 module RubyDecisionModel
   class Client
-    DEFAULT_BASE_URL = "https://openrouter.ai/api/alpha"
-    DEFAULT_MODEL = "typesafe/jev-1.13"
-    MAX_ATTEMPTS = 2
-    RETRYABLE_STATUSES = [429, 500, 502, 503, 504, 524, 529].freeze
-    RETRYABLE_EXCEPTIONS = [
-      Net::OpenTimeout,
-      Net::ReadTimeout,
-      Errno::ECONNRESET,
-      Errno::ECONNREFUSED,
-      Errno::EPIPE,
-      SocketError,
-      IOError
-    ].freeze
-
-    def initialize(api_key:, model: DEFAULT_MODEL, base_url: DEFAULT_BASE_URL, timeout: 5,
-                    transport: nil, sleeper: ->(seconds) { sleep(seconds) })
-      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
-      raise ConfigurationError, "model is required" if model.nil? || model.to_s.strip.empty?
-      raise ConfigurationError, "base_url is required" if base_url.nil? || base_url.to_s.strip.empty?
-
-      @api_key = api_key
-      @model = model
-      @base_url = base_url.to_s.chomp("/")
-      @timeout = timeout
+    # Kept from 0.0.1 for callers that referenced them. They describe the
+    # Typesafe and OpenRouter providers and the default RetryPolicy; prefer
+    # those directly. Each provider now names its own request id header.
+    REQUEST_ID_HEADER = "x-typesafe-request-id"
+    DEFAULT_BASE_URL = Providers::OpenRouter.new.default_base_url
+    DEFAULT_MODEL = Providers::OpenRouter.new.default_model
+    MAX_ATTEMPTS = RetryPolicy.new.max_retries + 1
+    RETRYABLE_STATUSES = RetryPolicy::DEFAULT_STATUSES
+    RETRYABLE_EXCEPTIONS = (RetryPolicy::TIMEOUT_EXCEPTIONS + RetryPolicy::CONNECTION_EXCEPTIONS).freeze
+
+    # Connecting is quick wherever the answer is slow, so the open timeout
+    # stays short unless the caller sets timeout: explicitly.
+    DEFAULT_OPEN_TIMEOUT = 5
+
+    attr_reader :provider, :model, :retry_policy, :timeout, :open_timeout
+
+    # provider:  a name from Providers.names or a Providers::Base instance.
+    #            When nil, RUBY_DECISION_MODEL_PROVIDER names one if set;
+    #            otherwise api_key: alone selects OpenRouter, and with no
+    #            api_key: the environment decides (see Providers.from_env).
+    # api_key:   overrides the provider's env var.
+    # model:     nil means the provider default; aliases resolve per provider.
+    # base_url:  overrides the provider base URL.
+    # timeout:   read timeout in seconds, and open timeout too when given;
+    #            nil means the provider's read default (5 for Jev-speed APIs,
+    #            30 where the vendor documents multi-second responses) with a
+    #            5 second open timeout.
+    # transport: callable(url:, headers:, body:) returning
+    #            [status, body_string, headers_hash] (a 2-element return is
+    #            still accepted and treated as having no headers).
+    # retry:     a RetryPolicy or a Hash of overrides.
+    # random:    callable returning a Float in 0...1, used for backoff jitter.
+    # clock:     callable returning monotonic seconds, used for total_timeout.
+    def initialize(provider: nil, api_key: nil, model: nil, base_url: nil, timeout: nil,
+                   transport: nil, sleeper: ->(seconds) { sleep(seconds) }, retry: {},
+                   random: -> { rand }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @provider = resolve_provider(provider, api_key: api_key, base_url: base_url)
+      @provider.validate!
+
+      @model = @provider.resolve_model(model)
+      @timeout = timeout || @provider.default_timeout
+      @open_timeout = timeout || DEFAULT_OPEN_TIMEOUT
       @transport = transport || default_transport
       @sleeper = sleeper
+      @retry_policy = RetryPolicy.from(binding.local_variable_get(:retry))
+      @random = random
+      @clock = clock
     end
 
-    def ask(state:, questions:)
-      raise RequestError, "questions must not be empty" if questions.nil? || questions.empty?
+    def base_url
+      @provider.base_url
+    end
 
-      body = JSON.generate({ "model" => @model, "state" => state, "questions" => questions })
-      headers = {
-        "Authorization" => "Bearer #{@api_key}",
-        "Content-Type" => "application/json",
-        "Accept" => "application/json"
-      }
+    # images: data URLs (see Images) for providers that read images. Each
+    # provider places them where its API expects.
+    def ask(state:, questions:, images: nil)
+      raise RequestError, "questions must not be empty" if questions.nil? || questions.empty?
 
-      status, response_body = perform_with_retry(url: "#{@base_url}/decisions", headers: headers, body: body)
-      handle_response(status, response_body, questions)
+      body = build_body(state, questions, images)
+      status, response_body, response_headers = perform_with_retry(
+        url: request_url, headers: @provider.headers, body: body
+      )
+      handle_response(status, response_body, response_headers, questions)
     end
 
     private
 
+    # Providers written against 0.1.0 may override url without the model
+    # argument added in 0.2.0.
+    def request_url
+      takes_model = @provider.method(:url).parameters.any? { |type, _| %i[req opt rest].include?(type) }
+      takes_model ? @provider.url(@model) : @provider.url
+    end
+
+    def build_body(state, questions, images)
+      images = Array(images)
+      return @provider.request_body(model: @model, state: state, questions: questions) if images.empty?
+
+      raise RequestError, "#{@provider.name} does not accept images" unless @provider.supports_images?
+
+      images.each do |image|
+        next if image.is_a?(String) && image.start_with?("data:image/")
+
+        raise RequestError, "images must be data URLs (data:image/...); see RubyDecisionModel::Images"
+      end
+
+      @provider.request_body(model: @model, state: state, questions: questions, images: images)
+    rescue JSON::GeneratorError, JSON::NestingError => e
+      # The generator's message can quote the offending value, so it stays
+      # on #cause rather than in a message that may be logged.
+      raise RequestError, "state or questions could not be encoded as JSON (#{e.class})"
+    end
+
+    def resolve_provider(provider, api_key:, base_url:)
+      case provider
+      when Providers::Base
+        return provider if api_key.nil? && base_url.nil?
+
+        # Never mutate a provider the caller may share between clients.
+        provider.dup.configure(api_key: api_key, base_url: base_url)
+      when Symbol, String
+        Providers.build(provider, api_key: api_key, base_url: base_url)
+      when nil
+        if api_key.nil?
+          Providers.from_env&.configure(base_url: base_url) || raise(
+            ConfigurationError,
+            "no provider configured: pass provider: or api_key:, or set one of #{Providers.env_vars.join(', ')}"
+          )
+        else
+          Providers.build(Providers.named_in_env || :open_router, api_key: api_key, base_url: base_url)
+        end
+      else
+        raise ConfigurationError, "provider must be a Symbol or a Providers::Base, got #{provider.class}"
+      end
+    end
+
     def default_transport
       lambda do |url:, headers:, body:|
         uri = URI.parse(url)
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == "https"
-        http.open_timeout = @timeout
+        http.open_timeout = @open_timeout
         http.read_timeout = @timeout
+        http.write_timeout = @timeout
 
         request = Net::HTTP::Post.new(uri.request_uri)
         headers.each { |k, v| request[k] = v }
         request.body = body
 
         response = http.request(request)
-        [response.code.to_i, response.body]
+        [response.code.to_i, response.body, response.each_header.to_h]
       end
     end
 
     def perform_with_retry(url:, headers:, body:)
-      attempts = 0
+      policy = @retry_policy
+      started_at = @clock.call
+      retries = 0
 
       loop do
-        attempts += 1
         begin
-          status, response_body = @transport.call(url: url, headers: headers, body: body)
-        rescue *RETRYABLE_EXCEPTIONS => e
-          raise_transport_error(e) if attempts >= MAX_ATTEMPTS
-
-          @sleeper.call(backoff_seconds)
-          next
+          status, response_body, response_headers = normalize_transport_result(
+            @transport.call(url: url, headers: headers, body: body)
+          )
         rescue Error
           raise
         rescue StandardError => e
-          raise_transport_error(e)
+          raise_transport_error(e) unless policy.retryable_exception?(e) && retries < policy.max_retries
+
+          delay = policy.backoff(retries, random: @random)
+          raise_transport_error(e) if budget_exceeded?(policy, started_at, delay)
+
+          @sleeper.call(delay)
+          raise_transport_error(e) if budget_exceeded?(policy, started_at, 0.0)
+
+          retries += 1
+          next
         end
 
-        return [status, response_body] unless RETRYABLE_STATUSES.include?(status) && attempts < MAX_ATTEMPTS
+        result = [status, response_body, response_headers]
+        return result unless policy.retryable_status?(status) && retries < policy.max_retries
+
+        delay = policy.delay(retries, headers: response_headers, random: @random)
+        return result if budget_exceeded?(policy, started_at, delay)
+
+        @sleeper.call(delay)
+        return result if budget_exceeded?(policy, started_at, 0.0)
 
-        @sleeper.call(backoff_seconds)
+        retries += 1
       end
     end
 
-    def backoff_seconds
-      0.5 + (rand * 0.25)
+    def budget_exceeded?(policy, started_at, delay)
+      return false if policy.total_timeout.nil?
+
+      (@clock.call - started_at) + delay > policy.total_timeout
+    end
+
+    def normalize_transport_result(result)
+      status, response_body, response_headers = Array(result)
+      [status, response_body, response_headers.is_a?(Hash) ? response_headers : {}]
     end
 
     def raise_transport_error(exception)
-      if exception.is_a?(Net::OpenTimeout) || exception.is_a?(Net::ReadTimeout)
+      if @retry_policy.timeout_exception?(exception)
         raise TimeoutError.new("request timed out: #{exception.message}", cause_error: exception)
       end
 
       raise TransportError.new("transport error: #{exception.message}", cause_error: exception)
     end
 
-    def handle_response(status, response_body, questions)
-      case status
-      when 200..299
-        parse_success(response_body, questions)
-      when 401
-        raise Unauthorized.new("unauthorized", status: status, body: response_body)
-      when 413
-        raise PayloadTooLarge.new("payload too large", status: status, body: response_body)
-      when 429
-        raise RateLimited.new("rate limited", status: status, body: response_body)
-      else
-        raise ApiError.new("api error (status #{status})", status: status, body: response_body)
-      end
+    ERROR_CLASSES = {
+      401 => [Unauthorized, "unauthorized"],
+      413 => [PayloadTooLarge, "payload too large"],
+      422 => [UnprocessableEntity, "unprocessable entity"],
+      429 => [RateLimited, "rate limited"],
+      529 => [Overloaded, "overloaded"]
+    }.freeze
+    private_constant :ERROR_CLASSES
+
+    def handle_response(status, response_body, response_headers, questions)
+      return parse_success(response_body, response_headers, questions) if (200..299).cover?(status)
+
+      klass, message = ERROR_CLASSES.fetch(status) { [ApiError, "api error (status #{status})"] }
+      detail = @provider.error_message(response_body)
+      message = "#{message}: #{detail}" if detail
+
+      raise klass.new(message, status: status, body: response_body, headers: response_headers)
     end
 
-    def parse_success(response_body, questions)
+    def parse_success(response_body, response_headers, questions)
+      raise InvalidResponse, "response body was empty" if response_body.nil? || response_body.to_s.strip.empty?
+
       parsed = begin
-        JSON.parse(response_body)
+        JSON.parse(response_body.to_s)
       rescue JSON::ParserError => e
         raise InvalidResponse, "response body was not valid JSON: #{e.message}"
       end
 
       raise InvalidResponse, "response body was not a JSON object" unless parsed.is_a?(Hash)
 
-      raw_answers = parsed["answers"]
+      canonical = @provider.normalize_response(parsed, questions: questions)
+      raise InvalidResponse, "response body was not a JSON object" unless canonical.is_a?(Hash)
+
+      raw_answers = canonical["answers"]
       raw_answers = {} unless raw_answers.is_a?(Hash)
 
       normalized = {}
       malformed = []
       missing = []
+      refused = []
 
       questions.each do |raw_id, question|
         id = raw_id.to_s
@@ -146,6 +251,7 @@ module RubyDecisionModel
             malformed << id
           end
         else
+          refused << id if answer_hash.is_a?(Hash) && answer_hash["type"] == "refusal"
           missing << id
         end
       end
@@ -158,29 +264,40 @@ module RubyDecisionModel
       end
 
       if missing.any?
-        raise MissingAnswers.new(
-          "missing or wrong-type answers for: #{missing.join(', ')}",
-          answers: normalized,
-          missing: missing
-        )
+        message = "missing or wrong-type answers for: #{missing.join(', ')}"
+        message += " (refused: #{refused.join(', ')})" if refused.any?
+        raise MissingAnswers.new(message, answers: normalized, missing: missing, refused: refused)
       end
 
       Response.new(
         answers: normalized,
-        usage: normalize_usage(parsed["usage"]),
-        model: parsed["model"],
-        id: parsed["id"],
-        raw: parsed
+        usage: @provider.usage(canonical),
+        model: canonical["model"],
+        id: canonical["id"],
+        raw: parsed,
+        request_id: request_id_from(response_headers)
       )
     end
 
+    def request_id_from(headers)
+      header = @provider.request_id_header
+      return nil unless header && headers.is_a?(Hash)
+
+      headers.each do |key, value|
+        next unless key.to_s.casecmp?(header)
+
+        return value.is_a?(Array) ? value.first : value
+      end
+      nil
+    end
+
     class MalformedAnswer < StandardError; end
 
     def normalize_answer(type, hash)
       case type
       when "noul"
         noul = hash["noul"]
-        raise MalformedAnswer unless noul.is_a?(Numeric)
+        raise MalformedAnswer unless noul.is_a?(Numeric) && noul.between?(0, 1)
 
         Answers::Noul.new(noul: noul.to_f, probabilities: hash_or_empty(hash["probabilities"]))
       when "choice"
@@ -218,15 +335,5 @@ module RubyDecisionModel
     def hash_or_empty(value)
       value.is_a?(Hash) ? value : {}
     end
-
-    def normalize_usage(usage)
-      usage = {} unless usage.is_a?(Hash)
-
-      Response::Usage.new(
-        input_tokens: Integer(usage["input_tokens"], exception: false),
-        output_tokens: Integer(usage["output_tokens"], exception: false),
-        cost: Float(usage["cost"], exception: false)
-      )
-    end
   end
 end

data/lib/ruby_decision_model/errors.rb

@@ -19,12 +19,13 @@ module RubyDecisionModel
   class TimeoutError < TransportError; end
 
   class ApiError < Error
-    attr_reader :status, :body
+    attr_reader :status, :body, :headers
 
-    def initialize(message, status:, body:)
+    def initialize(message, status:, body:, headers: {})
       super(message)
       @status = status
       @body = body
+      @headers = headers || {}
     end
   end
 
@@ -32,8 +33,12 @@ module RubyDecisionModel
 
   class PayloadTooLarge < ApiError; end
 
+  class UnprocessableEntity < ApiError; end
+
   class RateLimited < ApiError; end
 
+  class Overloaded < ApiError; end
+
   class InvalidResponse < Error
     attr_reader :answers
 
@@ -43,12 +48,16 @@ module RubyDecisionModel
     end
   end
 
+  # Raised when any question went unanswered. `missing` lists every such id.
+  # `refused` lists the ones the provider explicitly declined, a subset of
+  # `missing`. Answers that did arrive are on `answers`.
   class MissingAnswers < InvalidResponse
-    attr_reader :missing
+    attr_reader :missing, :refused
 
-    def initialize(message, answers: {}, missing: [])
+    def initialize(message, answers: {}, missing: [], refused: [])
       super(message, answers: answers)
       @missing = missing
+      @refused = refused
     end
   end
 end

data/lib/ruby_decision_model/images.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyDecisionModel
+  # Builds the base64 data URLs that Client#ask takes as images:. Every
+  # provider that reads images wants them embedded; none fetch a remote URL.
+  module Images
+    CONTENT_TYPES = {
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+      ".gif" => "image/gif"
+    }.freeze
+
+    module_function
+
+    def data_url(bytes, content_type:)
+      raise ArgumentError, "content_type must be an image/* type, got #{content_type.inspect}" unless content_type.to_s.start_with?("image/")
+
+      # pack("m0") is strict base64 without the base64 gem, which leaves the
+      # default gems in Ruby 3.4.
+      "data:#{content_type};base64,#{[bytes].pack('m0')}"
+    end
+
+    # Reads a file and infers its type from the extension.
+    def from_file(path, content_type: nil)
+      content_type ||= CONTENT_TYPES[File.extname(path.to_s).downcase]
+      raise ArgumentError, "cannot infer an image type for #{path}; pass content_type:" if content_type.nil?
+
+      data_url(File.binread(path), content_type: content_type)
+    end
+  end
+end