typesafe-jev 0.4.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56d8b9176783b02dfd76aa0c59e960fc25d2b936e852cdfa79658578ac5e4e9e
-  data.tar.gz: d534502c6f03804f0f96ea4839dc24c8fe28724e285f1fac53dcabe2fe5f7f8f
+  metadata.gz: 0627352ab282ec9a72607ebbc8d39bc73e2577231c567b4c66a7fc74e6140a0e
+  data.tar.gz: 218abce1d559c90b75e1b6bcf5872ff3f661d453dc6dd5c9bd15613141a89f1a
 SHA512:
-  metadata.gz: 034e9bdc3ae16ef9783612d7eea2ee524a3b457cfb666ce1095c5c43224dc148d1ce9442cd65c7b4a1f6eb0e8d5b88dcf32d3dfe1b0fe5b5e7c5e74f0df5a5b1
-  data.tar.gz: 10fcd78136555393c85d8876a31ac9584f61ce4464b7818d7c537698426b381545a53a768c99e1313d62cc74e19183e590b0aa5f434ab61465a5d36a01aa98eb
+  metadata.gz: ff6c07bf97933605fe0aa29c6d63fc6ed2390fa9cde14e9fc0016d17c373b45a85482f58ccf98b4df5279bb1c43e9174db8521faa4599c0ab2656eb94bb04b48
+  data.tar.gz: d6cd7d83fcff85966c653434fa64a5fd87a0a5fa23a7970643c5669ac298b367a4ead66d7eb44ebefdb32ab4f2a54963af1bdf5a9eeb2254952ecca9b966addd

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.7.0
+
+- **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now raises typed `Typesafe::Error` subclasses on any non-2xx response instead of raw `Net::HTTPClientException`/`Net::HTTPFatalError`: `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422, with `#errors`), `RateLimitError` (429, with `#retry_after`), `OverloadedError` (529) and `ServerError` (5xx), all under the `Typesafe::APIError` base with `status`, `body`, `headers`, `request_id` and `#retryable?`. `Typesafe::Error` is the root rescuable class.
+
+## 0.6.0
+
+- **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now returns a typed `Typesafe::Response` instead of the raw parsed Hash; answers come back as `NoulAnswer`/`ChoiceAnswer`/`ScoreAnswer` objects accessible via `response[question_id]` (String or Symbol). Use `response.to_h` for the previous raw-Hash behavior.
+
+## 0.5.0
+
+- Add response classes mirroring the question classes: abstract `Typesafe::Answer` base with `Answer.from_h` dispatching on the `type` tag, plus `Typesafe::NoulAnswer` (`noul`), `Typesafe::ChoiceAnswer` (`choice`, `probabilities`, `confidence`) and `Typesafe::ScoreAnswer` (`score`, `legend`, `probabilities`, `confidence`). Frozen, immutable value objects that validate their inputs and serialize via `#to_h`/`#to_json`.
+- Add `Typesafe::Usage` (token counts) and `Typesafe::Response` (`model`, `answers`, `usage`), with `Response.from_json`/`from_h` to parse an API response body into typed Answer objects; `Response#[]` accepts String or Symbol question ids.
+
 ## 0.4.1
 
 - Fix gemspec metadata: point `source_code_uri`/`changelog_uri` and author/email at the `dtheofr` GitHub account.

data/lib/typesafe/answer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # Abstract base class for the three answer types returned by the TypeSafe
+  # System One API: {NoulAnswer}, {ChoiceAnswer}, and {ScoreAnswer}.
+  #
+  # An answer is an immutable value object mirroring its question: it carries
+  # what the model returned for one question, but not the question id — that
+  # is the Hash key under which the answer appears in a {Response}.
+  #
+  # Use {Answer.from_h} (or {Response.from_json}) to build typed answers from
+  # a parsed response body:
+  #
+  #   Typesafe::Answer.from_h({ "type" => "noul", "noul" => 0.95 })
+  #   # => #<Typesafe::NoulAnswer @noul=0.95>
+  class Answer
+    # Builds the typed answer matching +hash+'s +type+ tag.
+    #
+    # @param hash [Hash] one entry of the API response's +answers+ map, with
+    #   String or Symbol keys.
+    # @return [NoulAnswer, ChoiceAnswer, ScoreAnswer]
+    # @raise [ArgumentError] if +hash+ is not a Hash or its +type+ is missing
+    #   or unknown.
+    def self.from_h(hash)
+      unless hash.is_a?(Hash)
+        raise ArgumentError, "answer must be a Hash, got #{hash.inspect}"
+      end
+
+      type = hash["type"] || hash[:type]
+      case type
+      when "noul" then NoulAnswer.from_h(hash)
+      when "choice" then ChoiceAnswer.from_h(hash)
+      when "score" then ScoreAnswer.from_h(hash)
+      else
+        raise ArgumentError,
+              "unknown answer type #{type.inspect} (expected \"noul\", \"choice\", or \"score\")"
+      end
+    end
+
+    # @return [String] the API answer type tag ("noul", "choice", or "score").
+    # @raise [NotImplementedError] on the abstract base class.
+    def type
+      raise NotImplementedError, "#{self.class} must implement #type"
+    end
+
+    # @return [Hash] the answer shape returned by the TypeSafe API.
+    def to_h
+      { type: type }
+    end
+
+    # @return [String] the answer serialized as JSON.
+    def to_json(state = nil)
+      JSON.generate(to_h, state)
+    end
+
+    # Answers compare equal when they are of the same class and serialize
+    # to the same API shape.
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    # Validates that +value+ is a non-empty String and returns a frozen copy.
+    def validate_string(value, name)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "#{name} must be a non-empty String"
+      end
+
+      value.dup.freeze
+    end
+
+    # Validates that +value+ is a finite Numeric, optionally within +range+.
+    def validate_number(value, name, range: nil)
+      unless value.is_a?(Numeric) && value.finite?
+        raise ArgumentError, "#{name} must be a finite Numeric, got #{value.inspect}"
+      end
+
+      if range && !range.cover?(value)
+        raise ArgumentError, "#{name} must be between #{range.min} and #{range.max}, got #{value.inspect}"
+      end
+
+      value
+    end
+
+    # Validates that +value+ is a probability between 0 and 1.
+    def validate_probability(value, name)
+      validate_number(value, name, range: 0.0..1.0)
+    end
+
+    # Validates a probability distribution: a non-empty Hash with String or
+    # Symbol keys mapping to probabilities in 0..1 that sum to 1. When
+    # +allowed_keys+ is given, the keys must match it exactly.
+    def normalize_probabilities(probabilities, allowed_keys: nil)
+      unless probabilities.is_a?(Hash) && !probabilities.empty?
+        raise ArgumentError, "probabilities must be a non-empty Hash of option or level keys to probabilities"
+      end
+
+      normalized = probabilities.each_with_object({}) do |(key, probability), result|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "probabilities keys must be Strings or Symbols, got #{key.inspect}"
+        end
+
+        result[key.is_a?(String) ? key.dup.freeze : key] =
+          validate_probability(probability, "probabilities[#{key.inspect}]")
+      end
+
+      sum = normalized.values.sum
+      unless (sum - 1.0).abs <= 1e-6
+        raise ArgumentError, "probabilities must sum to 1, got #{sum}"
+      end
+
+      if allowed_keys
+        expected = allowed_keys.map(&:to_s)
+        actual = normalized.keys.map(&:to_s)
+        missing = expected - actual
+        unexpected = actual - expected
+        unless missing.empty? && unexpected.empty?
+          problems = []
+          problems << "missing #{missing.map(&:inspect).join(", ")}" unless missing.empty?
+          problems << "unexpected #{unexpected.map(&:inspect).join(", ")}" unless unexpected.empty?
+          raise ArgumentError, "probabilities keys must match the legend keys (#{problems.join("; ")})"
+        end
+      end
+
+      normalized.freeze
+    end
+  end
+end

data/lib/typesafe/choice_answer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # The answer to a {Choice} question: the selected option, the probability
+  # distribution across every option, and a confidence between 0 and 1.
+  #
+  #   Typesafe::ChoiceAnswer.new(
+  #     choice: "billing",
+  #     probabilities: { "billing" => 0.88, "technical" => 0.12, "sales" => 0.0 },
+  #     confidence: 0.81
+  #   )
+  class ChoiceAnswer < Answer
+    # @return [String] the highest-probability option.
+    attr_reader :choice
+
+    # @return [Hash] every option mapped to its probability.
+    attr_reader :probabilities
+
+    # @return [Numeric] how certain the model is, between 0 and 1.
+    attr_reader :confidence
+
+    # @param choice [String] the selected option.
+    # @param probabilities [Hash] option keys (String or Symbol) mapped to
+    #   probabilities in 0..1; the values must sum to 1.
+    # @param confidence [Numeric] the model's confidence, between 0 and 1.
+    # @raise [ArgumentError] if any attribute is invalid.
+    def initialize(choice:, probabilities:, confidence:)
+      @choice = validate_string(choice, "choice")
+      @probabilities = normalize_probabilities(probabilities)
+      @confidence = validate_probability(confidence, "confidence")
+      freeze
+    end
+
+    # @param hash [Hash] a +choice+ answer entry from the API response, with
+    #   String or Symbol keys.
+    # @return [ChoiceAnswer]
+    def self.from_h(hash)
+      new(
+        choice: hash["choice"] || hash[:choice],
+        probabilities: hash["probabilities"] || hash[:probabilities],
+        confidence: hash["confidence"] || hash[:confidence]
+      )
+    end
+
+    def type
+      "choice"
+    end
+
+    def to_h
+      { type: type, choice: choice, probabilities: probabilities, confidence: confidence }
+    end
+  end
+end

data/lib/typesafe/client.rb

@@ -40,8 +40,9 @@ module Typesafe
       freeze
     end
 
-    # Evaluates a state against a map of questions and returns the raw JSON
-    # response as a Hash, e.g. +{"model"=>..., "answers"=>{...}, "usage"=>...}+.
+    # Evaluates a state against a map of questions and returns a {Response}
+    # with one typed {Answer} per question, e.g. `response[:refund_requested]`.
+    # `response.to_h` gives the raw parsed body as a Hash.
     #
     # @param state [String, Object, Array] the content to evaluate; passed
     #   through as-is.
@@ -49,11 +50,16 @@ module Typesafe
     #   to Question objects; answers come back under the same keys.
     # @param model [String, nil] model for this call; falls back to the model
     #   given at initialization.
-    # @return [Hash] the parsed response body.
+    # @return [Response] the parsed response.
     # @raise [ArgumentError] if +questions+ is not a non-empty Hash of
-    #   String/Symbol keys to Question values, or +model+ is invalid.
-    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
-    #   HTTP response.
+    #   String/Symbol keys to Question values, +model+ is invalid, or the
+    #   response body is not a valid response shape.
+    # @raise [JSON::ParserError] if the response body is not valid JSON.
+    # @raise [Typesafe::APIError] (or a subclass) on any non-2xx HTTP response:
+    #   {Typesafe::BadRequestError}, {Typesafe::AuthenticationError},
+    #   {Typesafe::PermissionDeniedError}, {Typesafe::NotFoundError},
+    #   {Typesafe::UnprocessableEntityError}, {Typesafe::RateLimitError},
+    #   {Typesafe::OverloadedError} and {Typesafe::ServerError}.
     def evaluate(state:, questions:, model: nil)
       model = model.nil? ? self.model : freeze_string(model, "model must be a non-empty String")
       questions = validate_questions!(questions)
@@ -65,8 +71,11 @@ module Typesafe
       )
 
       response = post(body)
-      response.value
-      JSON.parse(response.body)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Errors.from_response(status: response.code.to_i, headers: response, body: response.body)
+      end
+
+      Response.from_json(response.body)
     end
 
     private

data/lib/typesafe/errors.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # Root of all errors raised by the gem, so users can `rescue Typesafe::Error`.
+  class Error < StandardError; end
+
+  # A non-2xx HTTP response from the TypeSafe API.
+  #
+  #   begin
+  #     client.evaluate(state:, questions:)
+  #   rescue Typesafe::RateLimitError => e
+  #     sleep(e.retry_after || 1.0)
+  #     retry
+  #   end
+  #
+  # The `detail` field of an error body comes in three shapes, all of which
+  # are rendered into the exception message:
+  #
+  # * a plain String — `{"detail": "Unknown model: jev-99"}`
+  # * a Hash with error_type/message —
+  #   `{"detail": {"error_type": "authentication_error", "message": "..."}}`
+  # * an Array of validation entries (FastAPI/pydantic style) —
+  #   `{"detail": [{"type": "missing", "loc": ["body", "questions"], "msg": "Field required"}]}`
+  class APIError < Error
+    # @return [Integer] the HTTP status code.
+    attr_reader :status
+    # @return [Hash, Array, String, nil] the parsed JSON body (Hash or Array),
+    #   the raw body String when it is not valid JSON, or nil for an empty body.
+    attr_reader :body
+    # @return [Hash{String => String}] the response headers, as received.
+    attr_reader :headers
+    # @return [String, nil] the +x-typesafe-request-id+ response header, when present.
+    attr_reader :request_id
+
+    # @param status [Integer] the HTTP status code.
+    # @param body [Hash, Array, String, nil] the parsed or raw response body.
+    # @param headers [Hash{String => String}] the response headers.
+    # @param message [String, nil] overrides the rendered +detail+-based message.
+    def initialize(status:, body: nil, headers: {}, message: nil)
+      @status = status
+      @body = body
+      @headers = headers
+      @request_id = header("x-typesafe-request-id")
+      super(message || "The TypeSafe API returned status #{status}.")
+    end
+
+    # True when the request may succeed if retried after a delay: rate limits
+    # (429), overload (529) and server errors (5xx).
+    # @return [Boolean]
+    def retryable?
+      status == 429 || status == 529 || (500..599).cover?(status)
+    end
+
+    private
+
+    # Case-insensitive header lookup, since header casing depends on the server.
+    def header(name)
+      headers.each { |key, value| return value if key.to_s.downcase == name }
+      nil
+    end
+  end
+
+  # The request was invalid (400).
+  class BadRequestError < APIError; end
+
+  # Missing or invalid API key (401).
+  class AuthenticationError < APIError; end
+
+  # Access denied (403). The API also returns this for a missing API key.
+  class PermissionDeniedError < APIError; end
+
+  # The endpoint or resource was not found (404).
+  class NotFoundError < APIError; end
+
+  # The request body failed server-side validation (422).
+  class UnprocessableEntityError < APIError
+    # The parsed validation entries, e.g.
+    # `{"type" => "missing", "loc" => ["body", "questions"], "msg" => "Field required"}`;
+    # empty when the body carries none.
+    # @return [Array<Hash>]
+    def errors
+      detail = body.is_a?(Hash) ? body["detail"] : nil
+      detail.is_a?(Array) ? detail : []
+    end
+  end
+
+  # The rate limit was exceeded (429).
+  class RateLimitError < APIError
+    # The server's requested wait before retrying, parsed from the
+    # +Retry-After+ (seconds) or +Retry-After-Ms+ (milliseconds) header.
+    # @return [Float, Integer, nil]
+    def retry_after
+      if (ms = header("retry-after-ms"))
+        Float(ms) / 1000
+      elsif (seconds = header("retry-after"))
+        Float(seconds)
+      end
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # TypeSafe is temporarily overloaded (529).
+  class OverloadedError < APIError; end
+
+  # The server failed to process the request (5xx, excluding 529).
+  class ServerError < APIError; end
+
+  # Builds error instances from raw HTTP responses.
+  module Errors
+    module_function
+
+    # Maps a non-2xx response to the matching error class.
+    #
+    # @param status [Integer] the HTTP status code.
+    # @param headers [Hash, #each_header] the response headers.
+    # @param body [String, Hash, Array, nil] the raw or parsed response body.
+    # @return [APIError] an instance of the class matching +status+.
+    def from_response(status:, headers: {}, body: nil)
+      parsed_body = parse_body(body)
+      klass = STATUS_CLASSES.fetch(status) do
+        (500..599).cover?(status) ? ServerError : APIError
+      end
+
+      klass.new(
+        status: status,
+        body: parsed_body.is_a?(String) ? parsed_body.dup.freeze : parsed_body.freeze,
+        headers: normalize_headers(headers).freeze,
+        message: message_from_body(parsed_body, status)
+      )
+    end
+
+    def parse_body(body)
+      return body unless body.is_a?(String)
+
+      JSON.parse(body)
+    rescue JSON::ParserError, TypeError
+      body
+    end
+
+    def message_from_body(parsed_body, status)
+      detail = parsed_body.is_a?(Hash) ? parsed_body["detail"] : nil
+      case detail
+      when String then detail
+      when Hash then detail["message"] || detail[:message] || "Invalid request."
+      when Array then detail.map { |entry| validation_message(entry) }.join("; ")
+      else "The TypeSafe API returned status #{status}."
+      end
+    end
+
+    def validation_message(entry)
+      return entry.to_s unless entry.is_a?(Hash)
+
+      loc = Array(entry["loc"]).join(".")
+      msg = entry["msg"] || entry[:msg]
+      loc.empty? ? msg.to_s : "#{loc}: #{msg}"
+    end
+
+    def normalize_headers(headers)
+      return headers.each_header.to_h if headers.respond_to?(:each_header)
+
+      headers.dup
+    rescue TypeError
+      {}
+    end
+
+    STATUS_CLASSES = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError,
+      529 => OverloadedError
+    }.freeze
+    private_constant :STATUS_CLASSES
+  end
+end

data/lib/typesafe/jev.rb

@@ -31,11 +31,12 @@ module Typesafe
     # @param questions [Hash{String, Symbol => Question}] question ids mapped
     #   to Question objects; answers come back under the same keys.
     # @param model [String, nil] must be nil or "jev-latest".
-    # @return [Hash] the parsed response body.
-    # @raise [ArgumentError] if +questions+ is invalid or +model+ is not the
-    #   pinned one.
-    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
-    #   HTTP response.
+    # @return [Response] the parsed response.
+    # @raise [ArgumentError] if +questions+ is invalid, +model+ is not the
+    #   pinned one, or the response body is not a valid response shape.
+    # @raise [JSON::ParserError] if the response body is not valid JSON.
+    # @raise [Typesafe::APIError] (or a subclass) on any non-2xx HTTP response;
+    #   see {Typesafe::Client#evaluate}.
     def evaluate(state:, questions:, model: nil)
       if model && model != PINNED_MODEL
         raise ArgumentError,
@@ -53,7 +54,7 @@ module Typesafe
     #   to Question objects.
     # @param api_key [String, nil] the TypeSafe API key; falls back to the
     #   +TYPESAFE_API_KEY+ environment variable.
-    # @return [Hash] the parsed response body.
+    # @return [Response] the parsed response.
     def self.evaluate(state:, questions:, api_key: nil)
       new(api_key: api_key).evaluate(state: state, questions: questions)
     end

data/lib/typesafe/noul_answer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # The answer to a {Noul} question: the yes/no probability on a scale from
+  # 0 (no) to 1 (yes).
+  #
+  #   Typesafe::NoulAnswer.new(noul: 0.95)
+  class NoulAnswer < Answer
+    # @return [Numeric] the yes/no answer, between 0 (no) and 1 (yes).
+    attr_reader :noul
+
+    # @param noul [Numeric] the yes/no probability, between 0 and 1.
+    # @raise [ArgumentError] if +noul+ is not a Numeric between 0 and 1.
+    def initialize(noul:)
+      @noul = validate_probability(noul, "noul")
+      freeze
+    end
+
+    # @param hash [Hash] a +noul+ answer entry from the API response, with
+    #   String or Symbol keys.
+    # @return [NoulAnswer]
+    def self.from_h(hash)
+      new(noul: hash["noul"] || hash[:noul])
+    end
+
+    def type
+      "noul"
+    end
+
+    def to_h
+      { type: type, noul: noul }
+    end
+  end
+end

data/lib/typesafe/response.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # A System One evaluation response: the model that performed the
+  # evaluation, one typed {Answer} per question (keyed by the question ids
+  # from the request), and the token {Usage}.
+  #
+  #   response = Typesafe::Response.from_json(json)
+  #   response[:refund_requested] # => #<Typesafe::NoulAnswer @noul=0.95>
+  #
+  # The answer objects do not carry their question id — it is the Hash key
+  # under which each answer appears in {#answers}, mirroring how questions
+  # are sent.
+  class Response
+    # @return [String] the model that performed the evaluation.
+    attr_reader :model
+
+    # @return [Hash] question ids (String or Symbol) mapped to Answer objects.
+    attr_reader :answers
+
+    # @return [Usage] the token usage for the request.
+    attr_reader :usage
+
+    # @param model [String] the model that performed the evaluation.
+    # @param answers [Hash] question ids (String or Symbol) mapped to Answer
+    #   objects or answer Hashes; Hashes are parsed via {Answer.from_h}.
+    # @param usage [Usage, Hash] a Usage object, or a +usage+ Hash parsed
+    #   via {Usage.from_h}.
+    # @raise [ArgumentError] if any attribute is invalid or an answer is not
+    #   parseable.
+    def initialize(model:, answers:, usage:)
+      @model = freeze_string(model, "model must be a non-empty String")
+      @answers = normalize_answers(answers)
+      @usage = usage.is_a?(Usage) ? usage : Usage.from_h(usage)
+      freeze
+    end
+
+    # Parses a raw JSON response body from the TypeSafe API.
+    #
+    # @param json [String] the response body.
+    # @return [Response]
+    # @raise [ArgumentError] if the body is not a valid response shape.
+    # @raise [JSON::ParserError] if +json+ is not valid JSON.
+    def self.from_json(json)
+      from_h(JSON.parse(json))
+    end
+
+    # @param hash [Hash] the parsed response body, with String or Symbol keys.
+    # @return [Response]
+    # @raise [ArgumentError] if +hash+ is not a valid response shape.
+    def self.from_h(hash)
+      unless hash.is_a?(Hash)
+        raise ArgumentError, "response must be a Hash, got #{hash.inspect}"
+      end
+
+      new(
+        model: hash["model"] || hash[:model],
+        answers: hash["answers"] || hash[:answers],
+        usage: hash["usage"] || hash[:usage]
+      )
+    end
+
+    # The answer for a question id.
+    #
+    # @param id [String, Symbol] the question id used in the request.
+    # @return [Answer, nil] the matching answer, or nil if the id is unknown.
+    def [](id)
+      answers[id] || (id.is_a?(Symbol) ? answers[id.to_s] : nil)
+    end
+
+    # @return [Hash] the response shape returned by the TypeSafe API.
+    def to_h
+      { model: model, answers: answers.transform_values(&:to_h), usage: usage.to_h }
+    end
+
+    # @return [String] the response serialized as JSON.
+    def to_json(state = nil)
+      JSON.generate(to_h, state)
+    end
+
+    # Responses compare equal when they are of the same class and serialize
+    # to the same API shape.
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    # Validates that +model+ is a non-empty String and returns a frozen copy.
+    def freeze_string(value, error_message)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, error_message
+      end
+
+      value.dup.freeze
+    end
+
+    # Validates that +answers+ is a non-empty Hash of question ids to
+    # (or parseable) Answer objects, and freezes its keys.
+    def normalize_answers(answers)
+      unless answers.is_a?(Hash) && !answers.empty?
+        raise ArgumentError, "answers must be a non-empty Hash mapping question ids to answers"
+      end
+
+      answers.each_with_object({}) do |(id, answer), normalized|
+        unless (id.is_a?(String) && !id.strip.empty?) || (id.is_a?(Symbol) && !id.to_s.strip.empty?)
+          raise ArgumentError, "answers keys must be non-empty String or Symbol question ids, got #{id.inspect}"
+        end
+
+        normalized[id.is_a?(String) ? id.dup.freeze : id] =
+          if answer.is_a?(Answer)
+            answer
+          elsif answer.is_a?(Hash)
+            Answer.from_h(answer)
+          else
+            raise ArgumentError,
+                  "answers[#{id.inspect}] must be an answer Hash or Answer object, got #{answer.inspect}"
+          end
+      end.freeze
+    end
+  end
+end

data/lib/typesafe/score_answer.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # The answer to a {Score} question: the probability-weighted value across
+  # the levels (which can land between two levels), the legend mapping each
+  # level back to its description, the probability distribution across
+  # levels, and a confidence between 0 and 1.
+  #
+  #   Typesafe::ScoreAnswer.new(
+  #     score: 1.6,
+  #     legend: { "1" => "Calm", "2" => "Frustrated", "3" => "Very angry" },
+  #     probabilities: { "1" => 0.6, "2" => 0.35, "3" => 0.05 },
+  #     confidence: 0.7
+  #   )
+  class ScoreAnswer < Answer
+    # @return [Numeric] the probability-weighted answer across the levels;
+    #   can land between levels.
+    attr_reader :score
+
+    # @return [Hash] each level number mapped back to its description.
+    attr_reader :legend
+
+    # @return [Hash] each level mapped to its probability; keys match the
+    #   legend.
+    attr_reader :probabilities
+
+    # @return [Numeric] how certain the model is, between 0 and 1.
+    attr_reader :confidence
+
+    # @param score [Numeric] the probability-weighted answer across levels.
+    # @param legend [Hash] level keys (String or Symbol) mapped to non-empty
+    #   String descriptions.
+    # @param probabilities [Hash] the same level keys mapped to probabilities
+    #   in 0..1; the values must sum to 1 and the keys must match +legend+.
+    # @param confidence [Numeric] the model's confidence, between 0 and 1.
+    # @raise [ArgumentError] if any attribute is invalid.
+    def initialize(score:, legend:, probabilities:, confidence:)
+      @score = validate_number(score, "score")
+      @legend = normalize_legend(legend)
+      @probabilities = normalize_probabilities(probabilities, allowed_keys: @legend.keys)
+      @confidence = validate_probability(confidence, "confidence")
+      freeze
+    end
+
+    # @param hash [Hash] a +score+ answer entry from the API response, with
+    #   String or Symbol keys.
+    # @return [ScoreAnswer]
+    def self.from_h(hash)
+      new(
+        score: hash["score"] || hash[:score],
+        legend: hash["legend"] || hash[:legend],
+        probabilities: hash["probabilities"] || hash[:probabilities],
+        confidence: hash["confidence"] || hash[:confidence]
+      )
+    end
+
+    def type
+      "score"
+    end
+
+    def to_h
+      { type: type, score: score, legend: legend, probabilities: probabilities, confidence: confidence }
+    end
+
+    private
+
+    # Validates that +legend+ is a non-empty Hash of level keys to
+    # non-empty String descriptions, with frozen copies of the descriptions.
+    def normalize_legend(legend)
+      unless legend.is_a?(Hash) && !legend.empty?
+        raise ArgumentError, "legend must be a non-empty Hash of level keys to descriptions"
+      end
+
+      legend.each_with_object({}) do |(key, description), normalized|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "legend keys must be Strings or Symbols, got #{key.inspect}"
+        end
+
+        normalized[key.is_a?(String) ? key.dup.freeze : key] =
+          validate_string(description, "legend[#{key.inspect}]")
+      end.freeze
+    end
+  end
+end

data/lib/typesafe/usage.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # Token usage for one evaluation request.
+  #
+  #   Typesafe::Usage.new(input_tokens: 296, output_tokens: 20)
+  class Usage
+    # @return [Integer] the number of input tokens.
+    attr_reader :input_tokens
+
+    # @return [Integer] the number of output tokens.
+    attr_reader :output_tokens
+
+    # @param input_tokens [Integer] the number of input tokens.
+    # @param output_tokens [Integer] the number of output tokens.
+    # @raise [ArgumentError] if a token count is not a non-negative Integer.
+    def initialize(input_tokens:, output_tokens:)
+      @input_tokens = validate_token_count(input_tokens, "input_tokens")
+      @output_tokens = validate_token_count(output_tokens, "output_tokens")
+      freeze
+    end
+
+    # @param hash [Hash] a +usage+ entry from the API response, with String
+    #   or Symbol keys.
+    # @return [Usage]
+    # @raise [ArgumentError] if +hash+ is not a Hash or a token count is
+    #   missing or invalid.
+    def self.from_h(hash)
+      unless hash.is_a?(Hash)
+        raise ArgumentError, "usage must be a Hash, got #{hash.inspect}"
+      end
+
+      new(
+        input_tokens: hash["input_tokens"] || hash[:input_tokens],
+        output_tokens: hash["output_tokens"] || hash[:output_tokens]
+      )
+    end
+
+    # @return [Hash] the +usage+ shape returned by the TypeSafe API.
+    def to_h
+      { input_tokens: input_tokens, output_tokens: output_tokens }
+    end
+
+    # Usages compare equal when their token counts match.
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    def validate_token_count(value, name)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "#{name} must be a non-negative Integer, got #{value.inspect}"
+      end
+
+      value
+    end
+  end
+end

data/lib/typesafe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesafe
-  VERSION = "0.4.1"
+  VERSION = "0.7.0"
 end

data/lib/typesafe.rb

@@ -3,10 +3,20 @@
 require "json"
 
 require_relative "typesafe/version"
+
 require_relative "typesafe/question"
 require_relative "typesafe/noul"
 require_relative "typesafe/choice"
 require_relative "typesafe/score"
+
+require_relative "typesafe/answer"
+require_relative "typesafe/noul_answer"
+require_relative "typesafe/choice_answer"
+require_relative "typesafe/score_answer"
+
+require_relative "typesafe/usage"
+require_relative "typesafe/response"
+require_relative "typesafe/errors"
 require_relative "typesafe/client"
 require_relative "typesafe/jev"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typesafe-jev
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.7.0
 platform: ruby
 authors:
 - dtheofr
@@ -62,12 +62,19 @@ files:
 - LICENSE
 - README.md
 - lib/typesafe.rb
+- lib/typesafe/answer.rb
 - lib/typesafe/choice.rb
+- lib/typesafe/choice_answer.rb
 - lib/typesafe/client.rb
+- lib/typesafe/errors.rb
 - lib/typesafe/jev.rb
 - lib/typesafe/noul.rb
+- lib/typesafe/noul_answer.rb
 - lib/typesafe/question.rb
+- lib/typesafe/response.rb
 - lib/typesafe/score.rb
+- lib/typesafe/score_answer.rb
+- lib/typesafe/usage.rb
 - lib/typesafe/version.rb
 homepage: https://docs.typesafe.ai
 licenses: