jevrb 0.1.0

data/lib/jevrb/errors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class APIError < Error
+    attr_reader :status, :body, :headers, :endpoint
+
+    def initialize(status:, body:, headers:, endpoint:, message: nil)
+      @status = status
+      @body = body
+      @headers = headers.freeze
+      @endpoint = endpoint
+
+      super(message || "TypeSafe API request failed with status #{status}")
+    end
+
+    def request_id
+      headers["x-typesafe-request-id"]
+    end
+  end
+
+  class BadRequestError < APIError; end
+  class AuthenticationError < APIError; end
+  class PermissionDeniedError < APIError; end
+  class NotFoundError < APIError; end
+  class UnprocessableEntityError < APIError; end
+
+  class RateLimitError < APIError
+    def retry_after_ms
+      value = headers["retry-after-ms"]
+      return if value.nil?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  class InternalServerError < APIError; end
+
+  class ConnectionError < Error
+    attr_reader :endpoint
+
+    def initialize(endpoint:, message: nil)
+      @endpoint = endpoint
+      super(message || "TypeSafe API connection failed")
+    end
+  end
+
+  class TimeoutError < ConnectionError
+    attr_reader :timeout
+
+    def initialize(endpoint:, timeout:, message: nil)
+      @timeout = timeout
+      super(endpoint: endpoint, message: message || "TypeSafe API request exceeded #{timeout} seconds")
+    end
+  end
+
+  class ResponseValidationError < APIError
+    attr_reader :field_path
+
+    def initialize(status:, body:, headers:, field_path:, endpoint:, message: nil)
+      @field_path = field_path
+      super(
+        status: status,
+        body: body,
+        headers: headers,
+        endpoint: endpoint,
+        message: message || "TypeSafe API response is invalid at #{field_path}"
+      )
+    end
+  end
+end

data/lib/jevrb/noul.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Noul < Question
+    CRITERIA_KEYS = %w[true false].freeze
+
+    def self.build(instructions:, criteria: nil)
+      new(instructions: instructions, criteria: criteria)
+    end
+
+    private
+
+    def initialize(instructions:, criteria:)
+      super(type: "noul", instructions: instructions, criteria: normalize_criteria(criteria))
+    end
+
+    def normalize_criteria(criteria)
+      return if criteria.nil?
+      raise ArgumentError, "criteria must be a hash" unless criteria.is_a?(Hash)
+
+      normalized = criteria.each_with_object({}) do |(key, value), result|
+        normalized_key = key.to_s
+        raise ArgumentError, "criteria accepts only true and false keys" unless CRITERIA_KEYS.include?(normalized_key)
+        raise ArgumentError, "criteria contains duplicate key #{normalized_key.inspect}" if result.key?(normalized_key)
+
+        result[normalized_key.freeze] = Support.normalize_json_content(
+          value,
+          path: "criteria.#{normalized_key}",
+          allow_nil: true
+        )
+      end
+
+      normalized.freeze
+    end
+  end
+end

data/lib/jevrb/question.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Question
+    attr_reader :type, :instructions, :criteria
+
+    def to_h
+      hash = { type: type, instructions: instructions }
+      hash[:criteria] = criteria unless criteria.nil?
+      hash
+    end
+
+    private
+
+    def initialize(type:, instructions:, criteria:)
+      @type = type.freeze
+      @instructions = Support.normalize_json_content(instructions, path: "instructions")
+      @criteria = criteria
+      freeze
+    end
+  end
+end

data/lib/jevrb/result.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Result
+    ANSWER_CLASSES = {
+      "noul" => NoulAnswer,
+      "choice" => ChoiceAnswer,
+      "score" => ScoreAnswer
+    }.freeze
+
+    attr_reader :model, :answers, :usage, :request_id, :nouls, :choices, :scores
+
+    def self.from_hash(value, key_map: {}, request_id: nil)
+      value = ResponseSupport.hash(value, "response")
+      model = ResponseSupport.string(ResponseSupport.required(value, "model", "response"), "model")
+      usage = Usage.from_hash(ResponseSupport.required(value, "usage", "response"))
+      answers = parse_answers(ResponseSupport.required(value, "answers", "response"), key_map)
+
+      new(model: model, answers: answers, usage: usage, request_id: request_id)
+    end
+
+    def self.parse_answers(value, key_map)
+      ResponseSupport.hash(value, "answers").each_with_object({}) do |(key, answer), result|
+        key = ResponseSupport.string(key, "answers key")
+        answer = ResponseSupport.hash(answer, "answers.#{key}")
+        type = ResponseSupport.string(
+          ResponseSupport.required(answer, "type", "answers.#{key}"),
+          "answers.#{key}.type"
+        )
+        answer_class = ANSWER_CLASSES[type]
+        raise ResponseDataError.new("answers.#{key}.type", "unknown answer type #{type.inspect}") unless answer_class
+
+        result[key_map.fetch(key, key)] = answer_class.from_hash(answer, path: "answers.#{key}")
+      end.freeze
+    end
+    private_class_method :parse_answers
+
+    def to_h
+      {
+        model: model,
+        answers: answers.transform_values(&:to_h),
+        usage: usage.to_h
+      }
+    end
+
+    private
+
+    def initialize(model:, answers:, usage:, request_id:)
+      @model = model
+      @answers = answers
+      @usage = usage
+      @request_id = request_id&.dup&.freeze
+      @nouls = answers.select { |_key, answer| answer.is_a?(NoulAnswer) }.freeze
+      @choices = answers.select { |_key, answer| answer.is_a?(ChoiceAnswer) }.freeze
+      @scores = answers.select { |_key, answer| answer.is_a?(ScoreAnswer) }.freeze
+      freeze
+    end
+  end
+end

data/lib/jevrb/retry_policy.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Jevrb
+  class RetryPolicy
+    DEFAULT_HTTP_STATUSES = [408, 429, *(500..599)].freeze
+
+    attr_reader :max_retries, :backoff_initial, :backoff_max, :backoff_jitter,
+                :http_statuses, :respect_retry_after, :retry_connection_errors,
+                :retry_timeout_errors, :timeout
+
+    def initialize(
+      max_retries: 2,
+      backoff_initial: 0.5,
+      backoff_max: 5.0,
+      backoff_jitter: 0.25,
+      http_statuses: DEFAULT_HTTP_STATUSES,
+      respect_retry_after: true,
+      retry_connection_errors: true,
+      retry_timeout_errors: true,
+      timeout: 30.0,
+      sleeper: nil,
+      random: nil,
+      clock: nil
+    )
+      @max_retries = nonnegative_integer(max_retries, "max_retries")
+      @backoff_initial = nonnegative_number(backoff_initial, "backoff_initial")
+      @backoff_max = nonnegative_number(backoff_max, "backoff_max")
+      @backoff_jitter = fraction(backoff_jitter, "backoff_jitter")
+      @http_statuses = http_statuses.to_a.uniq.freeze
+      @respect_retry_after = boolean(respect_retry_after, "respect_retry_after")
+      @retry_connection_errors = boolean(retry_connection_errors, "retry_connection_errors")
+      @retry_timeout_errors = boolean(retry_timeout_errors, "retry_timeout_errors")
+      @timeout = timeout.nil? ? nil : nonnegative_number(timeout, "timeout")
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @random = random || Random.new
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      freeze
+    end
+
+    def execute
+      retries = 0
+      started_at = @clock.call
+
+      begin
+        yield
+      rescue Error => e
+        raise unless retries < max_retries && retryable?(e)
+
+        delay = retry_delay(e, retries)
+        elapsed = @clock.call - started_at
+        raise if timeout && elapsed + delay >= timeout
+
+        @sleeper.call(delay)
+        retries += 1
+        retry
+      end
+    end
+
+    def retryable?(error)
+      return retry_timeout_errors if error.is_a?(TimeoutError)
+      return retry_connection_errors if error.is_a?(ConnectionError)
+      return http_statuses.include?(error.status) if error.is_a?(APIError)
+
+      false
+    end
+
+    def retry_delay(error, retry_number)
+      header_delay = retry_after_delay(error)
+      return header_delay unless header_delay.nil?
+
+      base = [backoff_initial * (2**retry_number), backoff_max].min
+      base * (1.0 - (@random.rand * backoff_jitter))
+    end
+
+    private
+
+    def retry_after_delay(error)
+      return unless respect_retry_after && error.is_a?(APIError)
+
+      milliseconds = parse_nonnegative_number(error.headers["retry-after-ms"])
+      return milliseconds / 1000.0 unless milliseconds.nil?
+
+      value = error.headers["retry-after"]
+      return if value.nil?
+
+      seconds = parse_nonnegative_number(value)
+      return seconds unless seconds.nil?
+
+      [Time.httpdate(value) - Time.now, 0.0].max
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_nonnegative_number(value)
+      return if value.nil?
+
+      number = Float(value)
+      number if number.finite? && number >= 0
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def nonnegative_integer(value, name)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError, "#{name} must be a nonnegative integer"
+    end
+
+    def nonnegative_number(value, name)
+      return value.to_f if (value.is_a?(Integer) || value.is_a?(Float)) && value.finite? && value >= 0
+
+      raise ArgumentError, "#{name} must be a nonnegative number"
+    end
+
+    def fraction(value, name)
+      number = nonnegative_number(value, name)
+      return number if number <= 1.0
+
+      raise ArgumentError, "#{name} must be between 0 and 1"
+    end
+
+    def boolean(value, name)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} must be true or false"
+    end
+  end
+end

data/lib/jevrb/score.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Score < Question
+    MIN_LEVELS = 2
+    MAX_LEVELS = 10
+
+    def self.build(instructions:, criteria:)
+      new(instructions: instructions, criteria: criteria)
+    end
+
+    private
+
+    def initialize(instructions:, criteria:)
+      super(type: "score", instructions: instructions, criteria: normalize_criteria(criteria))
+    end
+
+    def normalize_criteria(criteria)
+      raise ArgumentError, "criteria must be an array" unless criteria.is_a?(Array)
+      unless (MIN_LEVELS..MAX_LEVELS).cover?(criteria.length)
+        raise ArgumentError, "criteria must contain #{MIN_LEVELS} through #{MAX_LEVELS} levels"
+      end
+
+      criteria.each_with_index.map do |value, index|
+        Support.normalize_json_content(value, path: "criteria[#{index}]")
+      end.freeze
+    end
+  end
+end

data/lib/jevrb/support.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Jevrb
+  module Support
+    module_function
+
+    def normalize_json_content(value, path:, allow_nil: false)
+      return nil if value.nil? && allow_nil
+
+      unless value.is_a?(String) || value.is_a?(Hash) || value.is_a?(Array)
+        raise ArgumentError, "#{path} must be a string, hash, or array"
+      end
+
+      normalize_json_value(value, path: path)
+    end
+
+    def normalize_json_value(value, path:)
+      case value
+      when String
+        value.dup.freeze
+      when Integer, TrueClass, FalseClass, NilClass
+        value
+      when Float
+        raise ArgumentError, "#{path} must contain only finite numbers" unless value.finite?
+
+        value
+      when Array
+        value.each_with_index.map do |entry, index|
+          normalize_json_value(entry, path: "#{path}[#{index}]")
+        end.freeze
+      when Hash
+        normalize_json_hash(value, path: path)
+      else
+        raise ArgumentError, "#{path} contains a non-JSON value: #{value.class}"
+      end
+    end
+
+    def normalize_json_hash(value, path:)
+      value.each_with_object({}) do |(key, entry), result|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "#{path} contains a non-string key: #{key.inspect}"
+        end
+
+        normalized_key = key.to_s
+        raise ArgumentError, "#{path} contains duplicate key #{normalized_key.inspect}" if result.key?(normalized_key)
+
+        result[normalized_key.freeze] = normalize_json_value(entry, path: "#{path}.#{normalized_key}")
+      end.freeze
+    end
+
+    def required_hash_value(hash, key, path:)
+      return hash[key] if hash.key?(key)
+
+      raise KeyError, "missing required field #{path}.#{key}"
+    end
+  end
+end

data/lib/jevrb/transport.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Jevrb
+  class Transport
+    Response = Struct.new(:status, :body, :headers, keyword_init: true)
+    private_constant :Response
+
+    def initialize(base_url:, http_factory: Net::HTTP.method(:new))
+      @base_url = base_url.chomp("/")
+      @http_factory = http_factory
+    end
+
+    def endpoint(path)
+      "#{@base_url}/#{path.sub(%r{\A/+}, "")}"
+    end
+
+    def post(path, body:, headers:, timeout:)
+      url = endpoint(path)
+      uri = URI.parse(url)
+      http = @http_factory.call(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      request = Net::HTTP::Post.new(uri.request_uri, headers)
+      request.body = body
+      response = http.request(request)
+
+      Response.new(
+        status: response.code.to_i,
+        body: response.body,
+        headers: response.each_header.to_h.freeze
+      ).freeze
+    rescue Timeout::Error => e
+      raise TimeoutError.new(endpoint: "POST #{url}", timeout: timeout, message: e.message)
+    rescue IOError, SocketError, SystemCallError, OpenSSL::SSL::SSLError, Net::ProtocolError => e
+      raise ConnectionError.new(endpoint: "POST #{url}", message: e.message)
+    end
+  end
+end

data/lib/jevrb/usage.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Jevrb
+  class Usage
+    attr_reader :input_tokens, :output_tokens
+
+    def self.from_hash(value, path: "usage")
+      value = ResponseSupport.hash(value, path)
+      new(
+        input_tokens: ResponseSupport.integer_or_nil(value["input_tokens"], "#{path}.input_tokens"),
+        output_tokens: ResponseSupport.integer_or_nil(value["output_tokens"], "#{path}.output_tokens")
+      )
+    end
+
+    def to_h
+      { input_tokens: input_tokens, output_tokens: output_tokens }
+    end
+
+    private
+
+    def initialize(input_tokens:, output_tokens:)
+      @input_tokens = input_tokens
+      @output_tokens = output_tokens
+      freeze
+    end
+  end
+end

data/lib/jevrb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Jevrb
+  VERSION = "0.1.0"
+end

data/lib/jevrb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "jevrb/version"
+require_relative "jevrb/constants"
+require_relative "jevrb/errors"
+require_relative "jevrb/support"
+require_relative "jevrb/question"
+require_relative "jevrb/noul"
+require_relative "jevrb/choice"
+require_relative "jevrb/score"
+require_relative "jevrb/answer"
+require_relative "jevrb/usage"
+require_relative "jevrb/result"
+require_relative "jevrb/retry_policy"
+require_relative "jevrb/transport"
+require_relative "jevrb/client"
+
+module Jevrb
+  private_constant :Support, :Transport
+end
+
+Jev = Jevrb