bynn-decisionnode 0.4.1

data/lib/decisionnode/results.rb

@@ -0,0 +1,539 @@
+# frozen_string_literal: true
+
+class DecisionNode
+  # The base of every answer. `raw` holds every field the server sent.
+  class Answer
+    attr_reader :raw, :type
+
+    # The typed answer for a known type whose fields are all present and of
+    # the right type; an UnknownAnswer holding the raw fields otherwise, so a
+    # new or malformed answer never fails the decision.
+    def self.from(raw)
+      return UnknownAnswer.new({ "value" => raw }) unless raw.is_a?(Hash)
+
+      klass = TYPES[raw["type"]]
+      # A point or box question asked with `max` answers a list of places,
+      # told by the answer's own list, so a batch line reads the same.
+      klass = PLACES[raw["type"]] if PLACES.key?(raw["type"]) && (raw.key?("points") || raw.key?("boxes"))
+      klass&.well_formed?(raw) ? klass.new(raw) : UnknownAnswer.new(raw)
+    end
+
+    # Answers by question id, each typed with Answer.from.
+    def self.map(answers)
+      return {} unless answers.is_a?(Hash)
+
+      answers.each_with_object({}) { |(id, a), h| h[id] = from(a) }
+    end
+
+    def self.number?(value)
+      value.is_a?(Numeric)
+    end
+
+    # A string of decimal digits, as score probabilities and legends are keyed.
+    def self.index?(key)
+      key.is_a?(String) && key.match?(/\A(0|[1-9][0-9]*)\z/)
+    end
+
+    def initialize(raw)
+      @raw = raw
+      @type = raw["type"]
+    end
+
+    # A field of the answer as the server sent it.
+    def [](key)
+      raw[key.to_s]
+    end
+
+    def to_h
+      raw
+    end
+  end
+
+  # An answer of a type this gem does not know yet. `raw` holds every field the
+  # server sent, so a new question type does not break an older client.
+  class UnknownAnswer < Answer; end
+
+  # The answer to a `truth` question. An answer under the API's older name
+  # for the type, which a raw question may still use, is read the same way.
+  class TruthAnswer < Answer
+    OLD_TYPE = "noul"
+    private_constant :OLD_TYPE
+
+    # The probability that the answer is true.
+    attr_reader :truth
+
+    def self.well_formed?(raw)
+      number?(raw[value_field(raw)])
+    end
+
+    def self.value_field(raw)
+      raw["type"] == OLD_TYPE ? OLD_TYPE : "truth"
+    end
+
+    def initialize(raw)
+      super
+      @truth = raw[self.class.value_field(raw)]
+    end
+  end
+
+  # The answer to a `choice` question.
+  class ChoiceAnswer < Answer
+    # The chosen option's name, exactly as sent.
+    attr_reader :choice
+    attr_reader :confidence
+    # Probability by option name, exactly as sent.
+    attr_reader :probabilities
+
+    def self.well_formed?(raw)
+      probs = raw["probabilities"]
+      raw["choice"].is_a?(String) && number?(raw["confidence"]) &&
+        probs.is_a?(Hash) && probs.each_value.all? { |v| number?(v) }
+    end
+
+    def initialize(raw)
+      super
+      @choice = raw["choice"]
+      @confidence = raw["confidence"]
+      @probabilities = raw["probabilities"].dup
+    end
+  end
+
+  # The answer to a `score` question.
+  class ScoreAnswer < Answer
+    # The expected level, a number from 0 to the number of levels minus one.
+    attr_reader :score
+    attr_reader :confidence
+    # Probability by level index (Integer).
+    attr_reader :probabilities
+    # Level index (Integer) to the level as it was sent.
+    attr_reader :legend
+
+    def self.well_formed?(raw)
+      probs = raw["probabilities"]
+      legend = raw["legend"]
+      number?(raw["score"]) && number?(raw["confidence"]) &&
+        probs.is_a?(Hash) && probs.all? { |k, v| index?(k) && number?(v) } &&
+        legend.is_a?(Hash) && legend.each_key.all? { |k| index?(k) }
+    end
+
+    def initialize(raw)
+      super
+      @score = raw["score"]
+      @confidence = raw["confidence"]
+      @probabilities = int_keys(raw["probabilities"])
+      @legend = int_keys(raw["legend"])
+    end
+
+    private
+
+    def int_keys(map)
+      map.each_with_object({}) { |(k, v), h| h[Integer(k, 10)] = v }
+    end
+  end
+
+  # The answer to a `number` question.
+  class NumberAnswer < Answer
+    # The most probable value of the grid, the JSON number as received.
+    attr_reader :number
+    # The probability-weighted mean over the grid, as received.
+    attr_reader :expected
+    # The probability of `number`.
+    attr_reader :confidence
+    # Probability by grid value, keyed by the value exactly as the server
+    # wrote it ("7", "3.5").
+    attr_reader :probabilities
+
+    def self.well_formed?(raw)
+      probs = raw["probabilities"]
+      number?(raw["number"]) && number?(raw["expected"]) && number?(raw["confidence"]) &&
+        probs.is_a?(Hash) && probs.each_value.all? { |v| number?(v) }
+    end
+
+    def initialize(raw)
+      super
+      @number = raw["number"]
+      @expected = raw["expected"]
+      @confidence = raw["confidence"]
+      @probabilities = raw["probabilities"].dup
+    end
+  end
+
+  # What the answers to `point` and `box` questions share: a place in an
+  # image. Every number is as received: integers in pixels, fractions when
+  # the question asked for normalized units.
+  class PlaceAnswer < Answer
+    # The probability that what the instructions describe is in the image
+    # at all; under a low value the place is only the best guess.
+    attr_reader :present
+    # The probability that the place is right if the thing is there.
+    attr_reader :confidence
+    # The id of the image looked in.
+    attr_reader :image
+    # The image's size in pixels.
+    attr_reader :width, :height
+
+    def self.well_formed?(raw)
+      (self::COORDINATES + %w[present confidence width height]).all? { |k| number?(raw[k]) } && raw["image"].is_a?(String)
+    end
+
+    def initialize(raw)
+      super
+      @present = raw["present"]
+      @confidence = raw["confidence"]
+      @image = raw["image"]
+      @width = raw["width"]
+      @height = raw["height"]
+    end
+  end
+
+  # The answer to a `point` question: the spot `x`, `y` from the top-left
+  # corner of the image, `x` to the right and `y` down.
+  class PointAnswer < PlaceAnswer
+    COORDINATES = %w[x y].freeze
+
+    attr_reader :x, :y
+
+    def initialize(raw)
+      super
+      @x = raw["x"]
+      @y = raw["y"]
+    end
+  end
+
+  # The answer to a `box` question: the top-left corner `x1`, `y1` and the
+  # bottom-right corner `x2`, `y2`.
+  class BoxAnswer < PlaceAnswer
+    COORDINATES = %w[x1 y1 x2 y2].freeze
+
+    attr_reader :x1, :y1, :x2, :y2
+
+    def initialize(raw)
+      super
+      @x1 = raw["x1"]
+      @y1 = raw["y1"]
+      @x2 = raw["x2"]
+      @y2 = raw["y2"]
+    end
+  end
+
+  private_constant :PlaceAnswer
+
+  # What the answers to `point` and `box` questions asked with `max` share:
+  # up to `max` places, one per thing the instructions describe, in a fixed
+  # order (left to right by the centre, ties from the top). Every number is
+  # as received.
+  class PlacesAnswer < Answer
+    # How many places follow, 0 to the question's `max`.
+    attr_reader :count
+    # The probability that at least one such thing is in the image.
+    attr_reader :present
+    # The probability that nothing was left out: low when the image holds
+    # more than `max`.
+    attr_reader :complete
+    # The id of the image looked in, and its size in pixels.
+    attr_reader :image, :width, :height
+
+    def self.well_formed?(raw)
+      list = raw[self::LIST]
+      raw["count"].is_a?(Integer) && !raw["count"].negative? &&
+        number?(raw["present"]) && number?(raw["complete"]) &&
+        list.is_a?(Array) && list.all? { |p| p.is_a?(Hash) && self::PLACE.members.all? { |k| number?(p[k.to_s]) } } &&
+        raw["image"].is_a?(String) && number?(raw["width"]) && number?(raw["height"])
+    end
+
+    def initialize(raw)
+      super
+      @count = raw["count"]
+      @present = raw["present"]
+      @complete = raw["complete"]
+      @image = raw["image"]
+      @width = raw["width"]
+      @height = raw["height"]
+      @places = raw[self.class::LIST].map { |p| self.class::PLACE.new(*self.class::PLACE.members.map { |k| p[k.to_s] }) }.freeze
+    end
+  end
+
+  # The answer to a `point` question asked with `max`: `points`, each a
+  # PointsAnswer::Point with `x`, `y` and its own `confidence`.
+  class PointsAnswer < PlacesAnswer
+    # One spot of the answer.
+    Point = Struct.new(:x, :y, :confidence)
+    PLACE = Point
+    LIST = "points"
+
+    def points
+      @places
+    end
+  end
+
+  # The answer to a `box` question asked with `max`: `boxes`, each a
+  # BoxesAnswer::Box with `x1`, `y1`, `x2`, `y2` and its own `confidence`.
+  class BoxesAnswer < PlacesAnswer
+    # One rectangle of the answer.
+    Box = Struct.new(:x1, :y1, :x2, :y2, :confidence)
+    PLACE = Box
+    LIST = "boxes"
+
+    def boxes
+      @places
+    end
+  end
+
+  private_constant :PlacesAnswer
+
+  class Answer
+    TYPES = {
+      "truth" => TruthAnswer, "noul" => TruthAnswer, "choice" => ChoiceAnswer,
+      "score" => ScoreAnswer, "number" => NumberAnswer, "point" => PointAnswer, "box" => BoxAnswer
+    }.freeze
+    PLACES = { "point" => PointsAnswer, "box" => BoxesAnswer }.freeze
+  end
+
+  # Token counts of a decision and, for a request with videos, the frames the
+  # API read (an Integer) and the seconds of video they cover (a number as
+  # received); for a request that named boosters, `booster_tokens` (the share
+  # of `input_tokens` the boosters' readings take) and `boosters` (the booster
+  # calls billed); `cost`, what the answer cost (a Cost). Each is nil when the
+  # response has none.
+  Usage = Struct.new(:input_tokens, :output_tokens, :video_frames, :video_seconds, :booster_tokens, :boosters,
+                     :cost)
+
+  # What an answer cost, Usage#cost: `usd` in all, `model_usd` for the model,
+  # `boosters_usd` for the boosters (each the JSON number as received, in USD)
+  # and `free_tier` (true when the free tier paid for it). Read as sent: `usd`
+  # is the server's figure, never the sum of the parts here.
+  Cost = Struct.new(:usd, :model_usd, :boosters_usd, :free_tier) do
+    # The `cost` of a response's usage, or nil when it has none. An amount
+    # that is not a number, or a `free_tier` that is not true or false, is nil.
+    def self.parse(value)
+      return nil unless value.is_a?(Hash)
+
+      amount = ->(v) { v.is_a?(Integer) || v.is_a?(Float) ? v : nil }
+      free = value["free_tier"]
+      new(amount.call(value["usd"]), amount.call(value["model_usd"]), amount.call(value["boosters_usd"]),
+          [true, false].include?(free) ? free : nil)
+    end
+  end
+
+  # A fallback answer, Decision#fallback: a request for one model answered by
+  # another because no worker of the model asked for was ready at once.
+  # `served_model` is the model that answered (also Decision#model), from the
+  # `x-decisionnode-fallback` header; `requested_model` the one asked for, from
+  # `x-decisionnode-requested-model`: the family id for a family id or an older
+  # id, the pinned id for a pinned id (nil when the header is absent).
+  Fallback = Struct.new(:served_model, :requested_model)
+
+  # The result of the safety check that runs on every decision on the hosted API,
+  # parsed from the `x-decisionnode-safety` response header.
+  class Safety
+    # The header value as received.
+    attr_reader :header
+    # Category name to its number, for example {"harm" => 0.031, "self_harm" => 0.004}.
+    attr_reader :scores
+    # The categories above the key's thresholds, in header order.
+    attr_reader :flagged
+    # Why the check did not run, when it did not.
+    attr_reader :reason
+
+    # Parses the header value. Returns nil when there is no header.
+    def self.parse(value)
+      return nil if value.nil?
+
+      new(value.to_s.strip)
+    end
+
+    def initialize(header)
+      @header = header
+      @scores = {}
+      @flagged = []
+      @reason = nil
+      if header.start_with?("unchecked")
+        @checked = false
+        header.split(";").drop(1).each do |param|
+          key, _, val = param.strip.partition("=")
+          @reason = val.strip.delete_prefix('"').delete_suffix('"') if key == "reason"
+        end
+      else
+        @checked = true
+        header.split(",").each do |member|
+          member = member.strip
+          next if member.empty?
+
+          head, *params = member.split(";")
+          name, _, num = head.partition("=")
+          name = name.strip
+          @scores[name] = parse_number(num)
+          @flagged << name if params.any? { |p| %w[flagged blocked].include?(p.strip) }
+        end
+      end
+    end
+
+    def checked
+      @checked
+    end
+    alias checked? checked
+
+    def harm
+      @scores["harm"]
+    end
+
+    def self_harm
+      @scores["self_harm"]
+    end
+
+    def [](name)
+      @scores[name.to_s]
+    end
+
+    def to_h
+      return { "checked" => false, "reason" => reason } unless checked
+
+      { "checked" => true, "harm" => nil, "self_harm" => nil }.merge(@scores).merge("flagged" => flagged)
+    end
+
+    private
+
+    def parse_number(text)
+      f = Float(text.strip)
+      f
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # The answers to one request, with the metadata the server sent with them.
+  class Decision
+    include DecisionResult
+
+    # Question id to Answer.
+    attr_reader :answers
+    # The resolved model version.
+    attr_reader :model
+    attr_reader :usage
+    # From the `x-request-id` header.
+    attr_reader :request_id
+    # The server's processing time, from the `x-decisionnode-latency-ms` header.
+    attr_reader :latency_ms
+    # A Safety, or nil when the server sent no safety header.
+    attr_reader :safety
+    # What the API says it changed while reading the request's videos (a
+    # lower rate or resolution), each sentence as sent; empty when it sent none.
+    attr_reader :warnings
+    # What each booster the request named found, as booster name to
+    # Evidence in the request's order; nil when the request named none.
+    attr_reader :evidence
+    # A Fallback when another model answered in place of the one asked for;
+    # nil on an ordinary answer.
+    attr_reader :fallback
+    # The parsed response body.
+    attr_reader :raw
+    # The response headers, names in lower case.
+    attr_reader :headers
+
+    def initialize(body, headers = {})
+      body = {} unless body.is_a?(Hash)
+      @raw = body
+      @headers = headers
+      @model = body["model"]
+      @answers = Answer.map(body["answers"])
+      usage = body["usage"].is_a?(Hash) ? body["usage"] : {}
+      @usage = Usage.new(usage["input_tokens"], usage["output_tokens"],
+                         usage["video_frames"].is_a?(Integer) ? usage["video_frames"] : nil,
+                         usage["video_seconds"].is_a?(Numeric) ? usage["video_seconds"] : nil,
+                         usage["booster_tokens"].is_a?(Integer) ? usage["booster_tokens"] : nil,
+                         usage["boosters"].is_a?(Integer) ? usage["boosters"] : nil,
+                         Cost.parse(usage["cost"]))
+      @evidence = Evidence.map(body["evidence"])
+      @warnings = body["warnings"].is_a?(Array) ? body["warnings"].grep(String).freeze : [].freeze
+      @request_id = headers["x-request-id"]
+      @latency_ms = parse_latency(headers["x-decisionnode-latency-ms"])
+      @safety = Safety.parse(headers["x-decisionnode-safety"])
+      served = headers["x-decisionnode-fallback"]
+      @fallback = served.nil? ? nil : Fallback.new(served, headers["x-decisionnode-requested-model"])
+    end
+
+    # The answer to the question with this id.
+    def [](id)
+      answers.fetch(id.to_s) { raise KeyError, "no answer with the id #{id.to_s.inspect}" }
+    end
+
+    def key?(id)
+      answers.key?(id.to_s)
+    end
+
+    private
+
+    def parse_latency(value)
+      return nil if value.nil?
+
+      f = Float(value.strip)
+      f == f.floor ? f.to_i : f
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # A model listed by `GET /v1/models`: a model of the catalogue, or one of
+  # the key's workspace's fine-tuned models.
+  class ModelInfo
+    attr_reader :name, :description, :release_date
+    # Every other field of the entry: the model's published limits, the
+    # `sessions` and `batch` objects included.
+    attr_reader :limits
+    attr_reader :raw
+    # true for a fine-tuned model; nil for a model of the catalogue.
+    attr_reader :fine_tuned
+    # A fine-tuned model's base model (its pinned name), else nil.
+    attr_reader :base
+    # A fine-tuned model's version number (an Integer), else nil.
+    attr_reader :adapter_version
+    # A fine-tuned model's status: "deployed" (it answers decisions), "ready"
+    # (trained, not deployed), or another value as sent; else nil.
+    attr_reader :status
+    # The prices in USD per million input, output, image and video tokens,
+    # as sent; nil when the entry states none.
+    attr_reader :price_per_million_input, :price_per_million_output,
+                :price_per_million_image, :price_per_million_video
+    # The share of the live prices a batch line on this model pays, as sent;
+    # nil when the entry states none, as on a fine-tuned model.
+    attr_reader :batch_price_factor
+
+    # The prices an entry states, read into the readers of the same names.
+    PRICES = %w[price_per_million_input price_per_million_output price_per_million_image
+                price_per_million_video batch_price_factor].freeze
+
+    def initialize(raw)
+      @raw = raw.is_a?(Hash) ? raw : {}
+      @name = @raw["name"]
+      @description = @raw["description"]
+      @release_date = @raw["release_date"]
+      @limits = @raw.reject { |k, _| %w[name description release_date].include?(k) }
+      @fine_tuned = [true, false].include?(@raw["fine_tuned"]) ? @raw["fine_tuned"] : nil
+      @base = @raw["base"].is_a?(String) ? @raw["base"] : nil
+      @adapter_version = @raw["adapter_version"].is_a?(Integer) ? @raw["adapter_version"] : nil
+      @status = @raw["status"].is_a?(String) ? @raw["status"] : nil
+      PRICES.each { |k| instance_variable_set("@#{k}", @raw[k].is_a?(Numeric) ? @raw[k] : nil) }
+    end
+
+    # Whether this is a fine-tuned model.
+    def fine_tuned?
+      fine_tuned == true
+    end
+
+    # One published limit by name, for example "context_tokens", or a path
+    # into a nested one: limit("sessions", "max_per_key").
+    def limit(*path)
+      limits.dig(*path.map(&:to_s))
+    end
+
+    # The session limits (`max_per_key`, `max_window`, `max_frame_tokens`, ...), or nil.
+    def sessions
+      limits["sessions"]
+    end
+
+    # The Batch API limits (`requests_per_batch`, `add_bytes`, ...), or nil.
+    def batch
+      limits["batch"]
+    end
+  end
+end