typesafe-ai-ruby 0.1.0

data/lib/typesafe/questions/score.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Questions
+    # Rates the state against ordered levels. Each level's index is its score, starting at zero.
+    #
+    # For example:
+    #   TypeSafe::Score.new(
+    #     instructions: "How urgent is this?",
+    #     criteria: ["Can wait", "Needs attention this week", "Needs attention today"]
+    #   )
+    class Score < Question
+      TYPE = "score"
+      MIN_LEVELS = 2
+
+      def initialize(criteria:, instructions: nil)
+        super(TYPE, instructions: instructions, criteria: self.class.normalize_criteria(criteria))
+      end
+
+      def self.normalize_criteria(criteria)
+        raise ValidationError, "Score criteria must be an Array of at least #{MIN_LEVELS} levels" unless
+          criteria.is_a?(Array) && criteria.length >= MIN_LEVELS
+
+        criteria.map do |level|
+          raise ValidationError, "Score levels must not be nil" if level.nil?
+
+          Util.deep_stringify(level)
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/request_options.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Per-call overrides accepted by Client#system_one and Resources::Models#list.
+  class RequestOptions
+    KEYS = %i[timeout headers extra_body retry_policy].freeze
+
+    # Timeout per attempt in seconds for this call only.
+    attr_reader :timeout
+    # Additional headers for this call only.
+    attr_reader :headers
+    # Extra top-level body fields, shallow-merged last-write-wins.
+    attr_reader :extra_body
+    # Retry policy override for this call only: a RetryPolicy, or a Hash applied on the client policy.
+    attr_reader :retry_policy
+
+    def self.from(options)
+      case options
+      when RequestOptions then options
+      when nil then new
+      when Hash then new(**options.transform_keys(&:to_sym))
+      else raise ArgumentError, "request_options must be a Hash, got #{options.class}"
+      end
+    end
+
+    def initialize(timeout: nil, headers: nil, extra_body: nil, retry_policy: nil)
+      @timeout = validate_timeout(timeout)
+      @headers = (headers || {}).each_with_object({}) { |(name, value), result| result[name.to_s] = value.to_s }
+      @extra_body = validate_extra_body(extra_body)
+      @retry_policy = validate_retry_policy(retry_policy)
+      freeze
+    end
+
+    private
+
+    def validate_timeout(timeout)
+      return nil if timeout.nil?
+      return timeout if timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+
+      raise ArgumentError, "timeout must be a positive number of seconds, got #{timeout.inspect}"
+    end
+
+    def validate_retry_policy(retry_policy)
+      return retry_policy if retry_policy.nil? || retry_policy.is_a?(RetryPolicy) || retry_policy.is_a?(Hash)
+
+      raise ArgumentError, "retry_policy must be a RetryPolicy or a Hash, got #{retry_policy.class}"
+    end
+
+    def validate_extra_body(extra_body)
+      return nil if extra_body.nil?
+      raise ArgumentError, "extra_body must be a Hash, got #{extra_body.class}" unless extra_body.is_a?(Hash)
+
+      Util.deep_stringify(extra_body)
+    end
+  end
+end

data/lib/typesafe/resources/models.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Resources
+    # Access to the models available to the account, reached through Client#models.
+    class Models
+      def initialize(requestor)
+        @requestor = requestor
+      end
+
+      # List the models and aliases the account can send in the model field.
+      def list(request_options: {})
+        response = @requestor.get(Constants::MODELS_PATH, options: RequestOptions.from(request_options))
+        Responses::ListModelsResponse.from_http(response)
+      end
+    end
+  end
+end

data/lib/typesafe/responses/answer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Responses
+    # Base class for answers. .from_hash dispatches on the "type" field.
+    class Answer
+      # "noul", "choice", "score", or an unrecognized type.
+      attr_reader :type
+      # The answer exactly as the API returned it, including unknown fields.
+      attr_reader :raw
+
+      def self.from_hash(hash, path)
+        data = Reader.hash!(hash, path)
+        type = Reader.string!(data["type"], "#{path}.type")
+        klass = TYPES.fetch(type, UnknownAnswer)
+        klass.parse(data, path)
+      end
+
+      def initialize(raw)
+        @raw = raw.freeze
+        @type = raw["type"]
+      end
+
+      # The raw answer.
+      def to_h
+        raw
+      end
+
+      def to_json(*args)
+        JSON.generate(raw, *args)
+      end
+
+      def ==(other)
+        other.class == self.class && raw == other.raw
+      end
+      alias eql? ==
+
+      def hash
+        raw.hash
+      end
+
+      def inspect
+        "#<#{self.class.name} #{raw.inspect}>"
+      end
+    end
+
+    # A yes/no answer.
+    class NoulAnswer < Answer
+      # Probability of yes, from 0 to 1.
+      attr_reader :noul
+
+      def self.parse(data, path)
+        new(data, noul: Reader.number!(data["noul"], "#{path}.noul"))
+      end
+
+      def initialize(raw, noul:)
+        @noul = noul
+        super(raw)
+        freeze
+      end
+    end
+
+    # A selected option with its probability distribution.
+    class ChoiceAnswer < Answer
+      # The highest-probability option.
+      attr_reader :choice
+      # Probability per option.
+      attr_reader :probabilities
+      # Certainty derived from the distribution, from 0 to 1.
+      attr_reader :confidence
+
+      def self.parse(data, path)
+        new(
+          data,
+          choice: Reader.string!(data["choice"], "#{path}.choice"),
+          probabilities: Reader.number_map!(data["probabilities"], "#{path}.probabilities"),
+          confidence: Reader.number!(data["confidence"], "#{path}.confidence")
+        )
+      end
+
+      def initialize(raw, choice:, probabilities:, confidence:)
+        @choice = choice
+        @probabilities = IndifferentHash.from(probabilities).freeze
+        @confidence = confidence
+        super(raw)
+        freeze
+      end
+    end
+
+    # An expected score with its rubric and probability per level.
+    class ScoreAnswer < Answer
+      # Probability-weighted score; may fall between integer levels.
+      attr_reader :score
+      # Level index to description.
+      attr_reader :legend
+      # Probability per level index.
+      attr_reader :probabilities
+      # Certainty derived from the distribution, from 0 to 1.
+      attr_reader :confidence
+
+      def self.parse(data, path)
+        new(
+          data,
+          score: Reader.number!(data["score"], "#{path}.score"),
+          legend: Reader.integer_keyed(Reader.hash!(data["legend"], "#{path}.legend"), "#{path}.legend"),
+          probabilities: Reader.integer_keyed(Reader.number_map!(data["probabilities"], "#{path}.probabilities"),
+                                              "#{path}.probabilities"),
+          confidence: Reader.number!(data["confidence"], "#{path}.confidence")
+        )
+      end
+
+      def initialize(raw, score:, legend:, probabilities:, confidence:)
+        @score = score
+        @legend = legend.freeze
+        @probabilities = probabilities.freeze
+        @confidence = confidence
+        super(raw)
+        freeze
+      end
+
+      # Legend with the original string keys.
+      def raw_legend
+        raw["legend"]
+      end
+
+      # Probabilities with the original string keys.
+      def raw_probabilities
+        raw["probabilities"]
+      end
+    end
+
+    # An answer whose type this gem does not recognize. Only #raw is available.
+    class UnknownAnswer < Answer
+      def self.parse(data, _path)
+        new(data)
+      end
+    end
+
+    Answer::TYPES = {
+      "noul" => NoulAnswer, "choice" => ChoiceAnswer, "score" => ScoreAnswer
+    }.freeze
+  end
+end

data/lib/typesafe/responses/list_models_response.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Responses
+    # One model or alias the account can send in the model field.
+    class ModelCard
+      # The model ID or alias, e.g. "jev-latest".
+      attr_reader :name
+      # What the model is for.
+      attr_reader :description
+      # When the model or alias was released.
+      attr_reader :release_date
+      # The entry as returned by the API.
+      attr_reader :raw
+
+      def self.from_hash(hash, path)
+        data = Reader.hash!(hash, path)
+        new(
+          data,
+          name: Reader.string!(data["name"], "#{path}.name"),
+          description: Reader.optional_string(data["description"], "#{path}.description"),
+          release_date: Reader.optional_string(data["release_date"], "#{path}.release_date")
+        )
+      end
+
+      def initialize(raw, name:, description: nil, release_date: nil)
+        @raw = raw.freeze
+        @name = name
+        @description = description
+        @release_date = release_date
+        freeze
+      end
+
+      def to_h
+        raw
+      end
+
+      def ==(other)
+        other.is_a?(ModelCard) && raw == other.raw
+      end
+      alias eql? ==
+
+      def hash
+        raw.hash
+      end
+    end
+
+    # The models available to the account.
+    class ListModelsResponse
+      include Enumerable
+
+      attr_reader :models, :http_response, :raw
+
+      def self.from_http(response)
+        json = response.json
+        data = Reader.hash!(json, "$")
+        new(models: parse_models(data["models"]), http_response: response, raw: data)
+      rescue InvalidField => e
+        raise Reader.validation_error(e, response, json)
+      end
+
+      def self.parse_models(list)
+        raise InvalidField.new("models", "expected an array, got #{list.class}") unless list.is_a?(Array)
+
+        list.each_with_index.map { |entry, index| ModelCard.from_hash(entry, "models[#{index}]") }
+      end
+
+      def initialize(models:, http_response: nil, raw: nil)
+        @models = models.freeze
+        @http_response = http_response
+        @raw = raw
+        freeze
+      end
+
+      def each(&)
+        models.each(&)
+      end
+
+      # Model names.
+      def names
+        models.map(&:name)
+      end
+
+      def request_id
+        http_response&.request_id
+      end
+
+      def to_h
+        raw || { "models" => models.map(&:to_h) }
+      end
+    end
+  end
+end

data/lib/typesafe/responses/reader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Responses
+    # Raised internally while parsing a response body; converted to APIResponseValidationError.
+    class InvalidField < StandardError
+      attr_reader :field_path
+
+      def initialize(field_path, message)
+        @field_path = field_path
+        super("#{field_path}: #{message}")
+      end
+    end
+
+    # Typed accessors for JSON values that record the dotted path of any violation.
+    module Reader
+      module_function
+
+      # Build the public error for an InvalidField raised while parsing a response.
+      def validation_error(error, response, json)
+        APIResponseValidationError.new(
+          "Invalid response body: #{error.message}",
+          field_path: error.field_path,
+          status: response.status,
+          body: json || response.body,
+          headers: response.headers,
+          endpoint: response.request&.endpoint
+        )
+      end
+
+      def hash!(value, path)
+        raise InvalidField.new(path, "expected an object, got #{value.class}") unless value.is_a?(Hash)
+
+        value
+      end
+
+      def string!(value, path)
+        raise InvalidField.new(path, "expected a string, got #{value.class}") unless value.is_a?(String)
+
+        value
+      end
+
+      def number!(value, path)
+        raise InvalidField.new(path, "expected a number, got #{value.class}") unless value.is_a?(Numeric)
+        raise InvalidField.new(path, "expected a finite number") if value.is_a?(Float) && !value.finite?
+
+        value.to_f
+      end
+
+      def optional_integer(value, path)
+        return nil if value.nil?
+        raise InvalidField.new(path, "expected an integer, got #{value.class}") unless value.is_a?(Integer)
+
+        value
+      end
+
+      def optional_string(value, path)
+        value.nil? ? nil : string!(value, path)
+      end
+
+      def number_map!(value, path)
+        hash!(value, path).each_with_object({}) { |(key, v), result| result[key.to_s] = number!(v, "#{path}.#{key}") }
+      end
+
+      # Convert "0", "1", ... keys into Integers.
+      def integer_keyed(hash, path)
+        hash.each_with_object({}) do |(key, value), result|
+          raise InvalidField.new("#{path}.#{key}", "expected an integer level key") unless key.match?(/\A\d+\z/)
+
+          result[key.to_i] = value
+        end
+      end
+    end
+  end
+end

data/lib/typesafe/responses/system_one_response.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Responses
+    # Answers keyed by question name, with the model that answered and token usage.
+    class SystemOneResponse
+      # The versioned model that answered, e.g. "jev-1.13.0".
+      attr_reader :model
+      attr_reader :usage
+      # Every answer keyed by question name.
+      attr_reader :answers
+      # The underlying HTTP response.
+      attr_reader :http_response
+      # The parsed JSON body.
+      attr_reader :raw
+
+      def self.from_http(response)
+        json = response.json
+        parse(json, response)
+      rescue InvalidField => e
+        raise Reader.validation_error(e, response, json)
+      end
+
+      def self.parse(json, response)
+        data = Reader.hash!(json, "$")
+        new(
+          model: Reader.string!(data["model"], "model"),
+          usage: Usage.from_hash(data["usage"], "usage"),
+          answers: parse_answers(data["answers"]),
+          http_response: response,
+          raw: data
+        )
+      end
+
+      def self.parse_answers(answers)
+        return {} if answers.nil?
+
+        Reader.hash!(answers, "answers").each_with_object({}) do |(name, answer), result|
+          result[name] = Answer.from_hash(answer, "answers.#{name}")
+        end
+      end
+
+      def initialize(model:, usage:, answers:, http_response: nil, raw: nil)
+        @model = model
+        @usage = usage
+        @answers = IndifferentHash.from(answers).freeze
+        @http_response = http_response
+        @raw = raw
+        freeze
+      end
+
+      # The answer for a question name.
+      def [](name)
+        answers[name]
+      end
+
+      # The x-typesafe-request-id header.
+      def request_id
+        http_response&.request_id
+      end
+
+      def nouls
+        answers_of(NoulAnswer)
+      end
+
+      def choices
+        answers_of(ChoiceAnswer)
+      end
+
+      def scores
+        answers_of(ScoreAnswer)
+      end
+
+      def to_h
+        raw || { "model" => model, "usage" => usage.to_h, "answers" => answers.transform_values(&:to_h) }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      private
+
+      def answers_of(klass)
+        IndifferentHash.from(answers.select { |_, answer| answer.is_a?(klass) }).freeze
+      end
+    end
+  end
+end

data/lib/typesafe/responses/usage.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  module Responses
+    # Token counts for a request, when reported by the API.
+    class Usage
+      attr_reader :input_tokens, :output_tokens
+
+      def self.from_hash(hash, path = "usage")
+        data = Reader.hash!(hash, path)
+        new(
+          input_tokens: Reader.optional_integer(data["input_tokens"], "#{path}.input_tokens"),
+          output_tokens: Reader.optional_integer(data["output_tokens"], "#{path}.output_tokens")
+        )
+      end
+
+      def initialize(input_tokens: nil, output_tokens: nil)
+        @input_tokens = input_tokens
+        @output_tokens = output_tokens
+        freeze
+      end
+
+      def to_h
+        { "input_tokens" => input_tokens, "output_tokens" => output_tokens }
+      end
+
+      def ==(other)
+        other.is_a?(Usage) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+    end
+  end
+end

data/lib/typesafe/retry_policy.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module TypeSafe
+  # Retry configuration. Defaults match the official TypeSafe SDKs: two retries with
+  # exponential backoff and jitter, honoring Retry-After, for 408, 429 and 5xx responses
+  # as well as connection failures and timeouts.
+  #
+  # Policies are frozen values. Build one with keyword overrides, or derive a new one
+  # from an existing policy with #with.
+  class RetryPolicy
+    DEFAULT_HTTP_STATUSES = ([408, 429] + (500..599).to_a).freeze
+
+    # Maximum retries after the initial attempt; 0 disables retries.
+    attr_reader :max_retries
+    # First backoff delay in seconds, doubled each attempt up to backoff_max.
+    attr_reader :backoff_initial
+    # Maximum backoff delay in seconds.
+    attr_reader :backoff_max
+    # Fraction of each backoff delay randomly subtracted, from 0 to 1.
+    attr_reader :backoff_jitter
+    # HTTP status codes that are retried.
+    attr_reader :http_statuses
+    # Whether to honor Retry-After and retry-after-ms response headers.
+    attr_reader :respect_retry_after
+    # Maximum server-requested delay in seconds; longer delays fall back to backoff.
+    attr_reader :max_retry_after
+    # Whether to retry APIConnectionError.
+    attr_reader :api_connection_error
+    # Whether to retry APITimeoutError.
+    attr_reader :api_timeout_error
+    # Total budget in seconds per call including delays; nil disables the limit.
+    attr_reader :timeout
+
+    # Coerce nil, a Hash of overrides, or a RetryPolicy into a RetryPolicy.
+    # Hash overrides are applied on top of +base+ (the SDK defaults unless given).
+    def self.from(value, base: nil)
+      base ||= DEFAULT
+      case value
+      when nil then base
+      when RetryPolicy then value
+      when Hash then base.with(**value.transform_keys(&:to_sym))
+      else raise ArgumentError, "retry_policy must be a RetryPolicy or a Hash, got #{value.class}"
+      end
+    end
+
+    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, max_retry_after: 60.0,
+                   api_connection_error: true, api_timeout_error: true, timeout: 30.0)
+      @max_retries = non_negative_integer(:max_retries, max_retries)
+      @backoff_initial = non_negative_number(:backoff_initial, backoff_initial)
+      @backoff_max = non_negative_number(:backoff_max, backoff_max)
+      @backoff_jitter = fraction(:backoff_jitter, backoff_jitter)
+      @http_statuses = http_statuses.to_a.map(&:to_i).freeze
+      @respect_retry_after = respect_retry_after ? true : false
+      @max_retry_after = non_negative_number(:max_retry_after, max_retry_after)
+      @api_connection_error = api_connection_error ? true : false
+      @api_timeout_error = api_timeout_error ? true : false
+      @timeout = timeout.nil? ? nil : non_negative_number(:timeout, timeout)
+      freeze
+    end
+
+    def to_h
+      {
+        max_retries: max_retries, backoff_initial: backoff_initial, backoff_max: backoff_max,
+        backoff_jitter: backoff_jitter, http_statuses: http_statuses, respect_retry_after: respect_retry_after,
+        max_retry_after: max_retry_after, api_connection_error: api_connection_error,
+        api_timeout_error: api_timeout_error, timeout: timeout
+      }
+    end
+
+    # A copy of this policy with the given fields replaced.
+    def with(**overrides)
+      self.class.new(**to_h, **overrides)
+    end
+
+    def ==(other)
+      other.is_a?(RetryPolicy) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def retry_status?(status)
+      http_statuses.include?(status)
+    end
+
+    # Whether a connection-level error should be retried.
+    def retry_error?(error)
+      case error
+      when APITimeoutError then api_timeout_error
+      when APIConnectionError then api_connection_error
+      else false
+      end
+    end
+
+    # Seconds to wait before the retry following +attempt+ (0 for the first retry).
+    # Uses the server's Retry-After when present and within max_retry_after, otherwise
+    # capped exponential backoff with jitter.
+    def delay_for(attempt, headers: nil, random: Kernel)
+      if respect_retry_after && headers
+        server_delay = Util.parse_retry_after(headers)
+        return server_delay if server_delay && server_delay <= max_retry_after
+      end
+
+      exponential = [backoff_initial * (2**attempt), backoff_max].min
+      exponential * (1 - (random.rand * backoff_jitter))
+    end
+
+    private
+
+    def non_negative_integer(name, value)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative Integer, got #{value.inspect}"
+    end
+
+    def non_negative_number(name, value)
+      return value if value.is_a?(Numeric) && value.finite? && value >= 0
+
+      raise ArgumentError, "#{name} must be a non-negative number, got #{value.inspect}"
+    end
+
+    def fraction(name, value)
+      return value if value.is_a?(Numeric) && value >= 0 && value <= 1
+
+      raise ArgumentError, "#{name} must be between 0 and 1, got #{value.inspect}"
+    end
+  end
+
+  RetryPolicy::DEFAULT = RetryPolicy.new
+end