bynn-decisionnode 0.4.1

data/lib/decisionnode/boosters.rb

@@ -0,0 +1,692 @@
+# frozen_string_literal: true
+
+class DecisionNode
+  # A booster named with settings, for the `boosters:` argument of #decide,
+  # the helpers, #decide_many requests and batch requests. A booster reads the
+  # request's images before the decision; its reading comes back in
+  # Decision#evidence and the model sees it as evidence.
+  #
+  #   DecisionNode::Booster.new("ai_generated", images: ["c3d4"], require: true)
+  #
+  # name::    the booster's name, for example "age" or "ai_generated".
+  # images::  the ids of the request's images it reads; left out, every image.
+  # require:: true: a booster that fails or does not answer in time fails the
+  #           request with the 529 `booster_unavailable` (an OverloadedError,
+  #           retried). Left out or false: the decision runs without it.
+  # options:: the booster's settings, a Hash.
+  #
+  # A plain name ("age") or a Hash in the API's wire form is accepted wherever
+  # a Booster is. Nothing about boosters is checked before sending: the API
+  # answers a malformed list, an unknown name and a booster turned off.
+  class Booster
+    attr_reader :name, :images, :options
+
+    def initialize(name, images: nil, require: nil, options: nil)
+      @name = name.is_a?(Symbol) ? name.to_s : name
+      @images = images.is_a?(Array) ? images.dup.freeze : images
+      @require = require
+      @options = options.is_a?(Hash) ? options.dup.freeze : options
+    end
+
+    # Whether a failed booster fails the request, as given (nil when not given).
+    def require
+      @require
+    end
+
+    # The booster's object form: `images`, `require` and `options` only when given.
+    def to_h
+      wire = { "name" => name }
+      wire["images"] = images unless images.nil?
+      wire["require"] = @require unless @require.nil?
+      wire["options"] = options unless options.nil?
+      wire
+    end
+
+    # The booster as it is sent: its name alone when no setting is given, so
+    # a list of such boosters is the plain list of names; else #to_h.
+    def wire
+      images.nil? && @require.nil? && options.nil? ? name : to_h
+    end
+
+    # The wire form as JSON, wherever the Booster sits in a value.
+    def to_json(*args)
+      wire.to_json(*args)
+    end
+
+    def inspect
+      "#<#{self.class.name} #{name.inspect}>"
+    end
+
+    KNOWLEDGE_OPTIONS = %i[query scope match filter top_k max_tokens pinned min_score include_text].freeze
+    private_constant :KNOWLEDGE_OPTIONS
+
+    # The `knowledge` booster, reading the passages of one knowledge base that
+    # apply to the request:
+    #
+    #   DecisionNode.knowledge("col_...", scope: "M-42", require: true)
+    #
+    # collection::    the knowledge base's `col_` id (required).
+    # query::         replaces the query built from the questions and the state.
+    # scope::         the value of the knowledge base's scope key.
+    # match, filter:: metadata conditions, JSON values sent as given.
+    # top_k::         the most retrieved passages, pins not counted; 0 reads the pins only.
+    # max_tokens::    the passages' token budget, an Integer or "auto".
+    # pinned::        false leaves the pinned documents out.
+    # min_score::     a similarity floor for passages found by meaning alone.
+    # include_text::  true adds each passage's text to the reading (a full-scope key).
+    # require::       true: a reading that did not run fails the request.
+    #
+    # Each option is sent only when given, as given; none is checked here.
+    def self.knowledge(collection, require: false, **options)
+      unknown = options.keys - KNOWLEDGE_OPTIONS
+      raise ArgumentError, "unknown knowledge option(s) #{unknown.join(', ')}" unless unknown.empty?
+
+      wire = { "collection" => collection }
+      KNOWLEDGE_OPTIONS.each { |k| wire[k.to_s] = options[k] unless options[k].nil? }
+      new("knowledge", require: require == true ? true : nil, options: wire)
+    end
+  end
+
+  class << self
+    # See Booster.knowledge.
+    def knowledge(collection, require: false, **options)
+      Booster.knowledge(collection, require: require, **options)
+    end
+  end
+
+  # The status and time of one booster on a request, from the
+  # `x-decisionnode-boosters` response header: `status` ("ok", "timeout",
+  # "error", "skipped", or another value as sent) and `latency_ms` (an Integer,
+  # or nil when the header gave none).
+  BoosterStatus = Struct.new(:status, :latency_ms) do
+    # The header's value as booster name to BoosterStatus, in the header's
+    # order; an empty Hash when there is no header. An entry it cannot read is
+    # left out; it never raises.
+    def self.parse(value)
+      out = {}
+      return out unless value.is_a?(String)
+
+      value.split(",").each do |item|
+        name, eq, rest = item.strip.partition("=")
+        name = name.strip
+        next if eq.empty? || name.empty?
+
+        status, _, ms = rest.partition(":")
+        ms = ms.strip
+        out[name] = new(status.strip, ms.match?(/\A[0-9]+\z/) ? Integer(ms, 10) : nil)
+      end
+      out
+    end
+  end
+
+  # What one booster found on a request, an entry of Decision#evidence.
+  class Evidence
+    # The version of the booster that read, for example "age-v3".
+    attr_reader :version
+    # "ok", "timeout" (no answer in time), "error", "skipped" (none of the
+    # request's images is one it reads), or another value as sent.
+    attr_reader :status
+    # How long the booster took, in milliseconds, as sent.
+    attr_reader :latency_ms
+    # The calls of this booster billed on this request, or nil when the server
+    # did not send it.
+    attr_reader :billed_calls
+    # One reading per image the booster was to read: an AgeReading, an
+    # AiGeneratedReading or an UnknownReading. A picture it did not read (it
+    # timed out or failed) or could not decode (`readable` false) is an
+    # UnknownReading holding those fields; `status` says why.
+    attr_reader :results
+    # The entry as received.
+    attr_reader :raw
+
+    # The `evidence` of a response body as booster name to Evidence, in the
+    # body's order, or nil when the body has none.
+    def self.map(evidence)
+      return nil unless evidence.is_a?(Hash)
+
+      evidence.each_with_object({}) { |(name, entry), h| h[name] = new(name, entry) }
+    end
+
+    def initialize(booster, raw)
+      @raw = raw
+      entry = raw.is_a?(Hash) ? raw : {}
+      @version = entry["version"].is_a?(String) ? entry["version"] : nil
+      @status = entry["status"].is_a?(String) ? entry["status"] : nil
+      @latency_ms = entry["latency_ms"].is_a?(Numeric) ? entry["latency_ms"] : nil
+      @billed_calls = entry["billed_calls"].is_a?(Integer) ? entry["billed_calls"] : nil
+      results = entry["results"].is_a?(Array) ? entry["results"] : []
+      @results = results.map { |r| Reading.from(booster, r) }.freeze
+    end
+
+    def to_h
+      raw
+    end
+  end
+
+  # The base of every booster reading. `raw` holds every field the server sent.
+  class Reading
+    # The id of the image read, or nil when the server sent none.
+    attr_reader :image
+    attr_reader :raw
+
+    # The typed reading for a booster this gem knows, when every field is
+    # present and of the right type; an UnknownReading holding the raw fields
+    # otherwise, so a new booster or a malformed reading never fails the decision.
+    def self.from(booster, raw)
+      klass = KINDS[booster]
+      return UnknownReading.new({ "value" => raw }) unless raw.is_a?(Hash)
+
+      klass&.well_formed?(raw) ? klass.new(raw) : UnknownReading.new(raw)
+    end
+
+    def self.number?(value)
+      value.is_a?(Numeric)
+    end
+
+    # A whole number of 0 or more: a grid's rows and columns, a picture's sides.
+    def self.count?(value)
+      value.is_a?(Integer) && !value.negative?
+    end
+
+    # Absent (nil) or of the class given.
+    def self.optional?(value, klass)
+      value.nil? || value.is_a?(klass)
+    end
+
+    def initialize(raw)
+      @raw = raw
+      @image = raw.is_a?(Hash) && raw["image"].is_a?(String) ? raw["image"] : nil
+    end
+
+    # A field of the reading as the server sent it.
+    def [](key)
+      raw.is_a?(Hash) ? raw[key.to_s] : nil
+    end
+
+    def to_h
+      raw
+    end
+  end
+
+  # A reading of a booster this gem does not know, or one with a field
+  # missing or of the wrong type. `raw` holds it as received (a reading that
+  # is not an object as `{"value" => reading}`).
+  class UnknownReading < Reading; end
+
+  # A reading of the `age` booster: the age of the largest face in the image.
+  # With `faces` 0 the image shows no face and the age fields are nil.
+  class AgeReading < Reading
+    INTEGER_FIELDS = %w[age_years low high].freeze
+    private_constant :INTEGER_FIELDS
+
+    # How many faces were found; the largest is read.
+    attr_reader :faces
+    # The age in years, and the range `low` to `high`.
+    attr_reader :age_years, :low, :high
+    # From 0 to 1.
+    attr_reader :confidence
+
+    def self.well_formed?(raw)
+      faces = raw["faces"]
+      return false unless raw["image"].is_a?(String) && faces.is_a?(Integer) && !faces.negative?
+
+      # With no face the age fields are left out; with one, each is required.
+      INTEGER_FIELDS.all? { |k| raw[k].is_a?(Integer) || (raw[k].nil? && faces.zero?) } &&
+        (number?(raw["confidence"]) || (raw["confidence"].nil? && faces.zero?))
+    end
+
+    def initialize(raw)
+      super
+      @faces = raw["faces"]
+      @age_years = raw["age_years"]
+      @low = raw["low"]
+      @high = raw["high"]
+      @confidence = raw["confidence"]
+    end
+  end
+
+  # The likeliest generator of an AiGeneratedReading: its `name` and `probability`.
+  TopGenerator = Struct.new(:name, :probability)
+
+  # A reading of the `ai_generated` booster: how likely the image was made by
+  # an image generator, and who signed its Content Credentials (C2PA) if it
+  # carries any.
+  class AiGeneratedReading < Reading
+    # The probability that the image was made by a generator, from 0 to 1.
+    attr_reader :generated
+    # From 0 to 1.
+    attr_reader :confidence
+    # "inference" (read from the pixels), "c2pa" (the file's Content
+    # Credentials say so), or another value as sent.
+    attr_reader :method
+    # The likeliest generator, a TopGenerator, when the reading says the image
+    # is likely generated; nil otherwise, and always on a "c2pa" reading.
+    attr_reader :top_generator
+    # Who signed the file's Content Credentials when they are trusted; nil
+    # otherwise.
+    attr_reader :c2pa_signer
+    # "untrusted" when the file carries Content Credentials that validate but
+    # are not trusted (they name no signer and change nothing in the reading),
+    # another value as sent, or nil when the reading has none.
+    attr_reader :c2pa
+
+    def self.well_formed?(raw)
+      top = raw["top_generator"]
+      raw["image"].is_a?(String) && number?(raw["generated"]) && number?(raw["confidence"]) &&
+        raw["method"].is_a?(String) &&
+        # top_generator and c2pa_signer are always sent, null when unset; c2pa
+        # only when the file's Content Credentials are not trusted.
+        raw.key?("top_generator") && raw.key?("c2pa_signer") &&
+        (top.nil? || (top.is_a?(Hash) && top["name"].is_a?(String) && number?(top["probability"]))) &&
+        (raw["c2pa_signer"].nil? || raw["c2pa_signer"].is_a?(String)) &&
+        (raw["c2pa"].nil? || raw["c2pa"].is_a?(String))
+    end
+
+    def initialize(raw)
+      super
+      @generated = raw["generated"]
+      @confidence = raw["confidence"]
+      @method = raw["method"]
+      top = raw["top_generator"]
+      @top_generator = top && TopGenerator.new(top["name"], top["probability"])
+      @c2pa_signer = raw["c2pa_signer"]
+      @c2pa = raw["c2pa"]
+    end
+  end
+
+  # A reading of the `ocr` booster: the text the image shows, in reading
+  # order, or the answer to the booster's `prompt` option.
+  class OcrReading < Reading
+    # The text read; empty when the image shows none, which is a reading, not
+    # a failure.
+    attr_reader :text
+    # true when the reading was cut at the model's context limit.
+    attr_reader :truncated
+
+    def self.well_formed?(raw)
+      raw["image"].is_a?(String) && raw["text"].is_a?(String) &&
+        [true, false].include?(raw["truncated"])
+    end
+
+    def initialize(raw)
+      super
+      @text = raw["text"]
+      @truncated = raw["truncated"]
+    end
+  end
+
+  # A face's box: its corners `x1`, `y1` (top left) and `x2`, `y2` (bottom
+  # right), the numbers as sent: pixels of the image, or fractions of its
+  # width and height when every place question of the request asks for
+  # normalized units.
+  FaceBox = Struct.new(:x1, :y1, :x2, :y2) do
+    def self.well_formed?(raw)
+      raw.is_a?(Hash) && %w[x1 y1 x2 y2].all? { |k| raw[k].is_a?(Numeric) }
+    end
+
+    def self.from(raw)
+      new(raw["x1"], raw["y1"], raw["x2"], raw["y2"])
+    end
+  end
+
+  # One face a `face_detection` reading found: its `box` (a FaceBox) and its
+  # `confidence`, from 0 to 1.
+  FaceDetection = Struct.new(:box, :confidence)
+
+  # One face a `face_recognition` reading matched in a collection: its `box`
+  # (a FaceBox), the match `score` from 0 to 1, the `collection` searched, the
+  # matched item's `reference`, and its `name` (a public figure) or `label`
+  # (an item of your own collection that has one), each nil when absent.
+  # `collection_name` is an own collection's display name (or its id), or a
+  # public collection's id; `metadata` is an own item's metadata, a Hash of
+  # JSON values as sent. Each is nil when absent, never an empty Hash.
+  FaceMatch = Struct.new(:box, :score, :collection, :reference, :name, :label, :collection_name, :metadata)
+
+  # The faces of a face reading, checked alike for both boosters.
+  module FaceReadings
+    module_function
+
+    def counted?(raw)
+      raw["image"].is_a?(String) && raw["faces"].is_a?(Integer) && !raw["faces"].negative?
+    end
+
+    def list?(raw, key)
+      raw[key].is_a?(Array) && raw[key].all? { |entry| entry.is_a?(Hash) && FaceBox.well_formed?(entry["box"]) && yield(entry) }
+    end
+  end
+  private_constant :FaceReadings
+
+  # A reading of the `face_detection` booster: how many faces the image
+  # shows, and each face's box and confidence.
+  class FaceDetectionReading < Reading
+    # How many faces were found; it can be more than the faces listed, which
+    # are at most 64.
+    attr_reader :faces
+    # The faces found, in the order sent: each a FaceDetection.
+    attr_reader :detections
+
+    def self.well_formed?(raw)
+      FaceReadings.counted?(raw) && FaceReadings.list?(raw, "detections") { |d| number?(d["confidence"]) }
+    end
+
+    def initialize(raw)
+      super
+      @faces = raw["faces"]
+      @detections = raw["detections"].map { |d| FaceDetection.new(FaceBox.from(d["box"]), d["confidence"]) }.freeze
+    end
+  end
+
+  # A reading of the `face_recognition` booster: how many faces it searched,
+  # and each face that matched an item of the collection, by score.
+  class FaceRecognitionReading < Reading
+    # How many faces were searched.
+    attr_reader :faces
+    # An own collection's display name, or nil when absent (a public
+    # collection, or an answer from before the field).
+    attr_reader :collection_name
+    # The faces that matched, in the order sent: each a FaceMatch. Empty when
+    # none did.
+    attr_reader :matches
+
+    def self.well_formed?(raw)
+      FaceReadings.counted?(raw) &&
+        (raw["collection_name"].nil? || raw["collection_name"].is_a?(String)) &&
+        FaceReadings.list?(raw, "matches") do |m|
+          number?(m["score"]) && m["collection"].is_a?(String) && m["reference"].is_a?(String) &&
+            %w[name label collection_name].all? { |k| m[k].nil? || m[k].is_a?(String) } &&
+            (m["metadata"].nil? || m["metadata"].is_a?(Hash))
+        end
+    end
+
+    def initialize(raw)
+      super
+      @faces = raw["faces"]
+      @collection_name = raw["collection_name"]
+      @matches = raw["matches"].map do |m|
+        FaceMatch.new(FaceBox.from(m["box"]), m["score"], m["collection"], m["reference"], m["name"], m["label"],
+                      m["collection_name"], m["metadata"])
+      end.freeze
+    end
+  end
+
+  # A reading of the `bynn_depth` booster (Depth Vision): how far away things
+  # are in the picture, in meters. The distances are estimates from one
+  # picture, for decisions and planning, never a safety stop.
+  class DepthReading < Reading
+    # Meters to the nearest obstacle straight ahead (the middle third of the
+    # picture, the floor or ground left out); nil when none is found.
+    attr_reader :ahead
+    # The same in 7 equal vertical strips of the picture, left to right, each
+    # meters or nil; a reading with another number of them is an
+    # UnknownReading.
+    attr_reader :directions
+    # true when a floor or ground was found and left out of `ahead` and
+    # `directions`; false when none was, and they include everything.
+    attr_reader :ground
+    # The grid's rows and columns.
+    attr_reader :grid_rows, :grid_cols
+    # The grid, row by row from the top left of the picture turned upright,
+    # each cell the distance of its part of the picture in meters.
+    attr_reader :grid
+    # The nearest, the farthest and the median distance in the picture.
+    attr_reader :depth_min, :depth_max, :depth_median
+    # The picture's size in pixels, turned upright.
+    attr_reader :width, :height
+
+    # A reading's directions: 7 equal vertical strips of the picture.
+    DIRECTIONS = 7
+
+    def self.well_formed?(raw)
+      raw["image"].is_a?(String) && (raw["ahead"].nil? || number?(raw["ahead"])) &&
+        raw["directions"].is_a?(Array) && raw["directions"].size == DIRECTIONS &&
+        raw["directions"].all? { |d| d.nil? || number?(d) } &&
+        [true, false].include?(raw["ground"]) &&
+        count?(raw["grid_rows"]) && count?(raw["grid_cols"]) &&
+        raw["grid"].is_a?(Array) && raw["grid"].all? { |row| row.is_a?(Array) && row.all? { |c| number?(c) } } &&
+        %w[depth_min depth_max depth_median].all? { |k| number?(raw[k]) } &&
+        count?(raw["width"]) && count?(raw["height"])
+    end
+
+    def initialize(raw)
+      super
+      @ahead = raw["ahead"]
+      @directions = raw["directions"]
+      @ground = raw["ground"]
+      @grid_rows = raw["grid_rows"]
+      @grid_cols = raw["grid_cols"]
+      @grid = raw["grid"]
+      @depth_min = raw["depth_min"]
+      @depth_max = raw["depth_max"]
+      @depth_median = raw["depth_median"]
+      @width = raw["width"]
+      @height = raw["height"]
+    end
+  end
+
+  # The opening a `bynn_segment` instance encloses, such as the hole of a
+  # gate, a doorway or a ring: its `polygon` (`[x, y]` points), `centroid`
+  # (`[x, y]`), `width` and `height`, `offset` (`[dx, dy]`, -1 to 1) and
+  # `area`, as fractions of the picture from its top left.
+  SegmentOpening = Struct.new(:polygon, :centroid, :width, :height, :offset, :area)
+
+  # How far away a `bynn_segment` instance is, with depth on: the `median`
+  # distance inside its outline, the `opening_median` seen through its
+  # opening and the `opening_rim_median` of the opening's rim, each meters or
+  # nil.
+  SegmentDepth = Struct.new(:median, :opening_median, :opening_rim_median)
+
+  # A `width` and a `height` in meters.
+  SegmentExtent = Struct.new(:width, :height)
+
+  # How large a `bynn_segment` instance is, with depth on: its `width` and
+  # `height` in meters, and its `opening`'s, a SegmentExtent or nil.
+  SegmentSize = Struct.new(:width, :height, :opening)
+
+  # One thing a `bynn_segment` reading found: the phrase it matched
+  # (`label`), its `score` from 0 to 1, `box` (`[x1, y1, x2, y2]`), `polygon`
+  # (its outline, `[x, y]` points), `area` and `centroid` (`[x, y]`), as
+  # fractions of the picture from its top left, turned upright; its
+  # `opening` (a SegmentOpening or nil), and with depth on its `depth` (a
+  # SegmentDepth) and `size_m` (a SegmentSize), each nil with depth off.
+  SegmentInstance = Struct.new(:label, :score, :box, :polygon, :area, :centroid, :opening, :depth, :size_m)
+
+  # The shapes of a segment reading, checked as sent.
+  module SegmentShapes
+    module_function
+
+    def numbers?(value, count = nil)
+      value.is_a?(Array) && value.all? { |v| v.is_a?(Numeric) } && (count.nil? || value.size == count)
+    end
+
+    def points?(value)
+      value.is_a?(Array) && value.all? { |p| numbers?(p, 2) }
+    end
+
+    # An object, or nil or absent.
+    def object_or_nil?(raw, key)
+      raw[key].nil? || raw[key].is_a?(Hash)
+    end
+
+    # A number, or nil or absent.
+    def nullable?(raw, key)
+      raw[key].nil? || raw[key].is_a?(Numeric)
+    end
+
+    def opening?(raw)
+      raw.nil? ||
+        (points?(raw["polygon"]) && numbers?(raw["centroid"], 2) && numbers?(raw["offset"], 2) &&
+         %w[width height area].all? { |k| raw[k].is_a?(Numeric) })
+    end
+
+    def depth?(raw)
+      raw.nil? || %w[median opening_median opening_rim_median].all? { |k| nullable?(raw, k) }
+    end
+
+    def size?(raw)
+      raw.nil? ||
+        (raw["width"].is_a?(Numeric) && raw["height"].is_a?(Numeric) && object_or_nil?(raw, "opening") &&
+         (raw["opening"].nil? || (raw["opening"]["width"].is_a?(Numeric) && raw["opening"]["height"].is_a?(Numeric))))
+    end
+
+    def instance?(raw)
+      raw.is_a?(Hash) && raw["label"].is_a?(String) && raw["score"].is_a?(Numeric) &&
+        numbers?(raw["box"], 4) && points?(raw["polygon"]) && raw["area"].is_a?(Numeric) &&
+        numbers?(raw["centroid"], 2) &&
+        %w[opening depth size_m].all? { |k| object_or_nil?(raw, k) } &&
+        opening?(raw["opening"]) && depth?(raw["depth"]) && size?(raw["size_m"])
+    end
+
+    def instance(raw)
+      opening = raw["opening"]
+      depth = raw["depth"]
+      size = raw["size_m"]
+      SegmentInstance.new(
+        raw["label"], raw["score"], raw["box"], raw["polygon"], raw["area"], raw["centroid"],
+        opening && SegmentOpening.new(opening["polygon"], opening["centroid"], opening["width"], opening["height"],
+                                      opening["offset"], opening["area"]),
+        depth && SegmentDepth.new(depth["median"], depth["opening_median"], depth["opening_rim_median"]),
+        size && SegmentSize.new(size["width"], size["height"],
+                                size["opening"] && SegmentExtent.new(size["opening"]["width"], size["opening"]["height"]))
+      )
+    end
+  end
+  private_constant :SegmentShapes
+
+  # A reading of the `bynn_segment` booster (Segment Vision): where the things
+  # the request's `prompt` names are in the picture.
+  class SegmentReading < Reading
+    # The picture's size in pixels, turned upright.
+    attr_reader :width, :height
+    # The phrases searched for, cleaned as the request's `prompt` is.
+    attr_reader :prompts
+    # What was found, best first: each a SegmentInstance. Empty when nothing
+    # was, which is a reading.
+    attr_reader :instances
+    # Where the distances come from ("bynn_depth"); nil with depth off.
+    attr_reader :depth_source
+    # The horizontal field of view the sizes in meters assume, in degrees; nil
+    # when the reading has none.
+    attr_reader :assumed_hfov_deg
+
+    def self.well_formed?(raw)
+      raw["image"].is_a?(String) && count?(raw["width"]) && count?(raw["height"]) &&
+        raw["prompts"].is_a?(Array) && raw["prompts"].all? { |p| p.is_a?(String) } &&
+        raw["instances"].is_a?(Array) && raw["instances"].all? { |i| SegmentShapes.instance?(i) } &&
+        (raw["depth_source"].nil? || raw["depth_source"].is_a?(String)) &&
+        (raw["assumed_hfov_deg"].nil? || number?(raw["assumed_hfov_deg"]))
+    end
+
+    def initialize(raw)
+      super
+      @width = raw["width"]
+      @height = raw["height"]
+      @prompts = raw["prompts"]
+      @instances = raw["instances"].map { |i| SegmentShapes.instance(i) }.freeze
+      @depth_source = raw["depth_source"]
+      @assumed_hfov_deg = raw["assumed_hfov_deg"]
+    end
+  end
+
+  # One passage of a KnowledgeReading, in the order the model saw them
+  # (pinned first). `n` is its number in the block; `item` and `chunk` cite
+  # where it comes from, and `byte_start` to `byte_end` (end exclusive) are
+  # UTF-8 byte offsets into the item's stored text, as
+  # `collections.get_item(..., include_text: true)` returns it. `reference`,
+  # `title` and `heading` are nil for a publishable key's reading. `score` is
+  # the similarity (4 decimals), nil for a pin. `rendered` is false when the
+  # passage was left out to fit, and nil on a search's passages. `text` is
+  # there only with `include_text`, and always on a search. Every value is as
+  # sent.
+  class KnowledgePassage
+    attr_reader :n, :pinned, :item, :chunk, :byte_start, :byte_end, :reference, :title, :heading, :tokens,
+                :score, :lexical, :rendered, :text, :raw
+
+    def self.well_formed?(raw)
+      raw.is_a?(Hash) && raw["n"].is_a?(Integer) && [true, false].include?(raw["pinned"]) &&
+        raw["item"].is_a?(String) && raw["chunk"].is_a?(Integer) &&
+        raw["byte_start"].is_a?(Integer) && raw["byte_end"].is_a?(Integer) &&
+        %w[reference title heading text].all? { |k| Reading.optional?(raw[k], String) } &&
+        Reading.optional?(raw["score"], Numeric) && Reading.optional?(raw["tokens"], Integer) &&
+        %w[lexical rendered].all? { |k| raw[k].nil? || [true, false].include?(raw[k]) }
+    end
+
+    def initialize(raw)
+      @raw = raw
+      %w[n pinned item chunk byte_start byte_end reference title heading tokens score lexical rendered
+         text].each { |k| instance_variable_set(:"@#{k}", raw[k]) }
+    end
+
+    def pinned?
+      @pinned == true
+    end
+
+    # A field of the passage as the server sent it.
+    def [](key)
+      raw[key.to_s]
+    end
+
+    def to_h
+      raw
+    end
+  end
+
+  # A reading of the `knowledge` booster, and the answer of
+  # `collections.search`: the passages found in one knowledge base.
+  #
+  # `corpus` (`{"version"}`), `query` (`{"source", "tokens", "text"}`, the
+  # text only with `include_text` and on a search), `budget` (`{"mode",
+  # "tokens", "entry", "cause"}`), `scope` (`{"key", "value"}`) and `search`
+  # (`{"plan", "candidates", "fallback"}`) are Hashes as sent, nil when
+  # absent; `omitted` is the count of passages left out by cause, as sent.
+  class KnowledgeReading < Reading
+    # The knowledge base's id.
+    attr_reader :collection
+    # Its name, or nil (always for a publishable key's reading).
+    attr_reader :collection_name
+    attr_reader :corpus, :query, :budget, :scope, :search, :omitted
+    # Strings such as "scope_not_named", "over_budget", "budget_floor" and
+    # "pinned_filtered"; empty when there are none.
+    attr_reader :warnings
+    # Each a KnowledgePassage, in the order sent.
+    attr_reader :passages
+    # Items not ready yet.
+    attr_reader :pending_items
+    # true when a passage was dropped to fit the model's context; nil on a
+    # search's answer, which has none.
+    attr_reader :truncated
+
+    def self.well_formed?(raw)
+      warnings = raw["warnings"]
+      raw["collection"].is_a?(String) && raw["passages"].is_a?(Array) &&
+        raw["passages"].all? { |p| KnowledgePassage.well_formed?(p) } &&
+        optional?(raw["collection_name"], String) && optional?(raw["pending_items"], Integer) &&
+        (raw["truncated"].nil? || [true, false].include?(raw["truncated"])) &&
+        (warnings.nil? || (warnings.is_a?(Array) && warnings.all?(String))) &&
+        %w[corpus query budget scope omitted search].all? { |k| optional?(raw[k], Hash) }
+    end
+
+    def initialize(raw)
+      super
+      @collection = raw["collection"]
+      @collection_name = raw["collection_name"]
+      %w[corpus query budget scope search omitted pending_items truncated].each do |k|
+        instance_variable_set(:"@#{k}", raw[k])
+      end
+      @warnings = raw["warnings"].is_a?(Array) ? raw["warnings"] : []
+      @passages = raw["passages"].map { |p| KnowledgePassage.new(p) }.freeze
+    end
+  end
+
+  class Reading
+    KINDS = {
+      "age" => AgeReading,
+      "ai_generated" => AiGeneratedReading,
+      "face_detection" => FaceDetectionReading,
+      "face_recognition" => FaceRecognitionReading,
+      "ocr" => OcrReading,
+      "bynn_depth" => DepthReading,
+      "bynn_segment" => SegmentReading,
+      "knowledge" => KnowledgeReading
+    }.freeze
+  end
+end