ruby-laya 0.1.0

data/lib/laya/question.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Laya
+  # One typed question, validated and rendered the way the checkpoints were trained on.
+  #
+  # A question definition arrives as a Hash, with either String or Symbol keys:
+  #
+  #   { "type" => "choice", "instructions" => "...", "criteria" => { "billing" => "invoices" } }
+  #   { type: :score, instructions: "...", criteria: ["not urgent", "soon", "urgent"] }
+  #   { type: :noul, instructions: "..." }
+  #
+  # Each type knows how to check itself, how to render its options, and how to turn the model's
+  # probabilities into an {Answer}, so nothing downstream switches on the type again.
+  class Question
+    attr_reader :id, :instructions, :criteria
+
+    # Build the question `definition` describes, raising ArgumentError when it cannot be answered.
+    def self.build(id, definition)
+      unless definition.is_a?(Hash)
+        raise ArgumentError, "question #{id.inspect}: definition must be a Hash, got #{definition.class}"
+      end
+
+      type = Util.get(definition, "type")
+      klass = TYPES[type.to_s]
+      unless klass
+        raise ArgumentError, "question #{id.inspect}: unknown type #{type.inspect}; " \
+                             "use one of #{TYPES.keys.sort}"
+      end
+      unless Util.key?(definition, "instructions")
+        raise ArgumentError, "question #{id.inspect}: no 'instructions'; " \
+                             "add the text the model should answer"
+      end
+
+      klass.new(id, Util.get(definition, "instructions"), Util.get(definition, "criteria"))
+    end
+
+    def initialize(id, instructions, criteria)
+      @id = id
+      @instructions = instructions.is_a?(String) ? instructions : PyJSON.dumps(instructions, ensure_ascii: true)
+      @criteria = normalise_criteria(criteria)
+      validate!
+    end
+
+    def type
+      self.class::TYPE
+    end
+
+    def qtype
+      QTYPES.fetch(type)
+    end
+
+    # The option texts the model scores, in label order.
+    def options
+      Common.render_options(internal)
+    end
+
+    # The shape `Laya::Common` and upstream's Python both work in.
+    def internal
+      { t: type, ins: instructions, crit: criteria }
+    end
+
+    # Build this question's answer from the probabilities over its options.
+    def answer(**)
+      raise NotImplementedError, "#{self.class} must build its own answer"
+    end
+
+    # Pick one label from a set of options.
+    class Choice < Question
+      TYPE = "choice"
+
+      def labels
+        criteria.keys
+      end
+
+      def answer(probabilities:, confidence:, action_probability:)
+        Answer::Choice.new(
+          choice: labels[probabilities.each_with_index.max_by { |p, i| [p, -i] }.last],
+          probabilities: labels.zip(probabilities.map { |p| p.round(4) }).to_h,
+          confidence: confidence, action_probability: action_probability
+        )
+      end
+
+      private
+
+      # A list of labels is the same question as a Hash of labels with no descriptions.
+      def normalise_criteria(criteria)
+        criteria.is_a?(Array) ? criteria.to_h { |label| [label, nil] } : criteria
+      end
+
+      def validate!
+        unless criteria.is_a?(Hash)
+          raise ArgumentError, "question #{id.inspect}: a choice question takes 'criteria' as a Hash " \
+                               "of label => description, or an Array of labels"
+        end
+        return unless criteria.empty?
+
+        raise ArgumentError, "question #{id.inspect}: a choice question needs at least one criterion"
+      end
+    end
+
+    # Place the state on an ordinal rubric, level 0 first.
+    class Score < Question
+      TYPE = "score"
+
+      def answer(probabilities:, confidence:, action_probability:)
+        Answer::Score.new(
+          score: probabilities.each_with_index.sum { |p, i| i * p }.round(4),
+          legend: criteria.each_with_index.to_h { |level, i| [i.to_s, level] },
+          probabilities: probabilities.each_with_index.to_h { |p, i| [i.to_s, p.round(4)] },
+          confidence: confidence, action_probability: action_probability
+        )
+      end
+
+      private
+
+      def validate!
+        unless criteria.is_a?(Array)
+          raise ArgumentError, "question #{id.inspect}: a score question takes 'criteria' as an Array " \
+                               "of level descriptions, index 0 first"
+        end
+        return unless criteria.empty?
+
+        raise ArgumentError, "question #{id.inspect}: a score question needs at least one level"
+      end
+    end
+
+    # Answer a yes/no statement with a calibrated probability.
+    class Noul < Question
+      TYPE = "noul"
+
+      # A noul question's confidence is how far the probability sits from a coin flip, computed
+      # from the unrounded value as upstream does, so the caller's `confidence` is not used.
+      def answer(probabilities:, action_probability:, confidence: nil) # rubocop:disable Lint/UnusedMethodArgument
+        probability = probabilities[1]
+        Answer::Noul.new(
+          probability: probability.round(4),
+          confidence: [probability, 1.0 - probability].max.round(4),
+          action_probability: action_probability
+        )
+      end
+
+      private
+
+      # `true:` and `false:` may arrive as booleans, symbols or strings; the renderer wants strings.
+      def normalise_criteria(criteria)
+        return criteria unless criteria.is_a?(Hash)
+
+        criteria.to_h { |key, value| [key.to_s.downcase, value] }
+      end
+
+      def validate!
+        return if criteria.nil? || criteria.is_a?(Hash)
+
+        raise ArgumentError, "question #{id.inspect}: a noul question takes 'criteria' as a Hash with " \
+                             "optional 'true'/'false' descriptions, or omits it"
+      end
+    end
+
+    TYPES = { Choice::TYPE => Choice, Score::TYPE => Score, Noul::TYPE => Noul }.freeze
+
+    private
+
+    def normalise_criteria(criteria)
+      criteria
+    end
+
+    def validate!
+      nil
+    end
+  end
+end

data/lib/laya/questions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Laya
+  # Builds the question hash the runtime takes, from the three declarations that describe a
+  # decision. {Decision} and {Ask} both delegate here, so the two front doors cannot drift.
+  module Questions
+    module_function
+
+    # One label from a set.
+    #
+    #   choice(:department, "Which team?", billing: "invoices", technical: "outages")
+    #   choice(:intent, "Which intent?", criteria_hash)   # labels that are not valid keywords
+    #   choice(:tone, "Which tone?", %w[formal casual])   # labels with no description
+    def choice(instructions, criteria = nil, **labels)
+      criteria = labels if criteria.nil? || (criteria.respond_to?(:empty?) && criteria.empty? && labels.any?)
+      criteria = criteria.to_h { |label| [label, nil] } if criteria.is_a?(Array)
+      { "type" => "choice", "instructions" => instructions, "criteria" => stringify(criteria) }
+    end
+
+    # A position on ordered levels, lowest first.
+    #
+    #   score(:urgency, "How urgent?", levels: ["not urgent", "soon", "critical"])
+    def score(instructions, levels)
+      { "type" => "score", "instructions" => instructions, "criteria" => Array(levels) }
+    end
+
+    # The probability that a statement holds. `yes` and `no` describe the two ends when the
+    # statement alone is ambiguous.
+    def noul(instructions, yes: nil, no: nil)
+      question = { "type" => "noul", "instructions" => instructions }
+      criteria = { "true" => yes, "false" => no }.compact
+      question["criteria"] = criteria unless criteria.empty?
+      question
+    end
+
+    # Criteria keys reach the model as text, so a symbol label is sent as its name.
+    def stringify(criteria)
+      raise ArgumentError, "criteria must be a Hash or an Array of labels" unless criteria.is_a?(Hash)
+
+      criteria.to_h { |label, description| [label.to_s, description] }
+    end
+  end
+end

data/lib/laya/result.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Laya
+  # One question's answer.
+  #
+  # Subclasses carry what their question type produces, and every one of them renders the payload
+  # upstream's Python returns through {#to_h}, so a Ruby result can be logged, compared or served
+  # exactly as the Python one.
+  class Answer
+    attr_reader :type, :confidence, :action_probability
+
+    def initialize(type:, confidence:, action_probability:)
+      @type = type
+      @confidence = confidence
+      @action_probability = action_probability
+    end
+
+    def to_h
+      payload.merge("confidence" => confidence, "action" => { "act_probability" => action_probability })
+    end
+
+    def inspect
+      "#<#{self.class.name} #{summary}>"
+    end
+
+    def to_s
+      summary
+    end
+
+    private
+
+    def payload
+      raise NotImplementedError
+    end
+
+    def summary
+      raise NotImplementedError
+    end
+
+    # The top label of a `choice` question, with a probability per option.
+    class Choice < Answer
+      attr_reader :choice, :probabilities
+
+      def initialize(choice:, probabilities:, **rest)
+        super(type: "choice", **rest)
+        @choice = choice
+        @probabilities = probabilities
+      end
+
+      # The probability of the chosen label, or of `label` when one is given.
+      def probability(label = choice)
+        probabilities.fetch(label) do
+          probabilities.fetch(label.to_s) do
+            raise KeyError, "no option #{label.inspect}; this question offered #{probabilities.keys.inspect}"
+          end
+        end
+      end
+
+      # The chosen label stands in for itself, so a call site reads as the decision it is:
+      #
+      #   answer == :billing        # => true
+      #   answer.billing?           # => true
+      #   case answer.to_sym ...    # Ruby asks the `when` value, so compare the symbol there
+      def ==(other)
+        case other
+        when Symbol, String then choice.to_s == other.to_s
+        when Answer::Choice then choice == other.choice
+        else super
+        end
+      end
+      alias eql? ==
+
+      def hash = [self.class, choice].hash
+      def to_sym = choice.to_sym
+      def to_s = choice.to_s
+
+      # `answer.billing?` for any label this question offered.
+      def method_missing(name, *args)
+        label = name.to_s.delete_suffix("?")
+        return super unless name.to_s.end_with?("?") && args.empty? && offered?(label)
+
+        choice.to_s == label
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        (name.to_s.end_with?("?") && offered?(name.to_s.delete_suffix("?"))) || super
+      end
+
+      def offered?(label)
+        probabilities.keys.any? { |option| option.to_s == label }
+      end
+
+      private
+
+      def payload
+        { "type" => "choice", "choice" => choice, "probabilities" => probabilities }
+      end
+
+      def summary
+        format("%s %.1f%%", choice, probability * 100)
+      end
+    end
+
+    # The expected level of a `score` question on its ordinal rubric.
+    class Score < Answer
+      attr_reader :score, :legend, :probabilities
+
+      def initialize(score:, legend:, probabilities:, **rest)
+        super(type: "score", **rest)
+        @score = score
+        @legend = legend
+        @probabilities = probabilities
+      end
+
+      # The rubric text nearest the expected level.
+      def label
+        legend.fetch(score.round.clamp(0, legend.length - 1).to_s)
+      end
+
+      def to_f = score
+      def levels = legend.length
+
+      # Compare against a level index or its text.
+      def ==(other)
+        case other
+        when Numeric then score == other
+        when Symbol, String then label.to_s == other.to_s
+        when Answer::Score then score == other.score
+        else super
+        end
+      end
+
+      private
+
+      def payload
+        { "type" => "score", "score" => score, "legend" => legend, "probabilities" => probabilities }
+      end
+
+      def summary
+        format("%.2f of %d (%s)", score, legend.length - 1, label)
+      end
+    end
+
+    # The calibrated probability that a `noul` statement holds.
+    class Noul < Answer
+      attr_reader :probability
+
+      def initialize(probability:, **rest)
+        super(type: "noul", **rest)
+        @probability = probability
+      end
+      alias noul probability
+
+      # True when the statement is more likely than `threshold` to hold.
+      def true?(threshold = 0.5)
+        probability > threshold
+      end
+
+      def false?(threshold = 0.5) = !true?(threshold)
+      def to_f = probability
+
+      def ==(other)
+        case other
+        when true, false then true? == other
+        when Numeric then probability == other
+        when Answer::Noul then probability == other.probability
+        else super
+        end
+      end
+
+      private
+
+      def payload
+        { "type" => "noul", "noul" => probability }
+      end
+
+      def summary
+        format("%.1f%%", probability * 100)
+      end
+    end
+  end
+
+  # Everything one `predict` produced: an answer per question, the token usage, and the routing
+  # decision when a {Router} made one.
+  class Result
+    include Enumerable
+
+    MODEL_NAME = "laya-rl-agent"
+
+    attr_reader :model, :answers, :usage, :routing, :shortlist
+
+    def initialize(answers:, usage:, model: MODEL_NAME, routing: nil, shortlist: nil)
+      @answers = answers
+      @usage = usage
+      @model = model
+      @routing = routing
+      @shortlist = shortlist
+    end
+
+    # The answer to `id`. A question asked under a symbol can be read back as a string and the
+    # other way around, so a result reads the same whichever form the caller reached for.
+    def [](id)
+      answers.fetch(id) do
+        answers.fetch(id.to_s) do
+          answers.fetch(id.to_sym) do
+            raise KeyError, "no question #{id.inspect} in this result; asked: #{answers.keys.inspect}"
+          end
+        end
+      end
+    rescue NoMethodError
+      raise KeyError, "no question #{id.inspect} in this result; asked: #{answers.keys.inspect}"
+    end
+
+    # Answers are also readable by name: `result.department` is `result[:department]`.
+    def method_missing(name, *args)
+      return super unless args.empty? && answered?(name)
+
+      self[name]
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      answered?(name) || super
+    end
+
+    def answered?(name)
+      answers.key?(name) || answers.key?(name.to_s) || answers.key?(name.to_sym)
+    rescue NoMethodError
+      false
+    end
+
+    def each(&)
+      answers.each(&)
+    end
+
+    def input_tokens
+      usage.fetch("input_tokens")
+    end
+
+    # The payload upstream's Python `predict` returns, ready for JSON.
+    def to_h
+      payload = { "model" => model, "answers" => answers.transform_values(&:to_h), "usage" => usage }
+      payload["routing"] = routing.to_h if routing
+      payload["shortlist"] = shortlist if shortlist
+      payload
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    def with_routing(decision)
+      Result.new(answers: answers, usage: usage, model: model, routing: decision, shortlist: shortlist)
+    end
+
+    def with_shortlist(meta)
+      Result.new(answers: answers, usage: usage, model: model, routing: routing, shortlist: meta)
+    end
+
+    def inspect
+      "#<Laya::Result #{answers.keys.inspect}#{" via #{routing.model}" if routing}>"
+    end
+  end
+end