jev-feels 1.0.0 → 1.1.0

data/lib/jev/definition.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Jev
+  Definition = Data.define(:name, :type, :instructions, :choices, :levels) do
+    def self.build(name:, instructions:, choices: nil, levels: nil)
+      instructions = instructions.to_s.dup.freeze
+      raise ArgumentError, "cannot use choices: and levels: together" if choices && levels
+
+      new(name: name.to_sym, instructions: instructions, **typed_fields(choices, levels))
+    end
+
+    def simple_noul?
+      type == :noul
+    end
+
+    def public_value
+      simple_noul? ? instructions : self
+    end
+
+    def level_names
+      levels&.keys
+    end
+
+    def level_descriptions
+      levels&.values
+    end
+
+    def to_question
+      question = { "type" => type.to_s, "instructions" => instructions }
+      criteria = question_criteria
+      question["criteria"] = criteria if criteria
+      question
+    end
+
+    def self.typed_fields(choices, levels)
+      if choices
+        { type: :choice, choices: normalize_choices(choices), levels: nil }
+      elsif levels
+        { type: :score, levels: normalize_levels(levels), choices: nil }
+      else
+        { type: :noul, choices: nil, levels: nil }
+      end
+    end
+    private_class_method :typed_fields
+
+    def self.normalize_choices(choices)
+      raise ArgumentError, "choices must be a Hash" unless choices.is_a?(Hash)
+      raise ArgumentError, "choices cannot be empty" if choices.empty?
+
+      unique_keys(choices, "choice").freeze
+    end
+    private_class_method :normalize_choices
+
+    def self.normalize_levels(levels)
+      raise ArgumentError, "levels must be a Hash" unless levels.is_a?(Hash)
+      raise ArgumentError, "levels must have at least 2 entries" if levels.size < 2
+
+      unique_keys(levels, "level").freeze
+    end
+    private_class_method :normalize_levels
+
+    def self.unique_keys(pairs, label)
+      seen = {}
+      pairs.each do |key, description|
+        symbol = normalize_key(key, label)
+        raise ArgumentError, "duplicate #{label} key: #{symbol.inspect}" if seen.key?(symbol)
+
+        seen[symbol] = description.to_s.dup.freeze
+      end
+      seen
+    end
+    private_class_method :unique_keys
+
+    def self.normalize_key(key, label)
+      raise ArgumentError, "invalid #{label} key: #{key.inspect}" unless key.is_a?(Symbol) || key.is_a?(String)
+      raise ArgumentError, "invalid #{label} key: #{key.inspect}" if key.to_s.empty?
+
+      key.to_sym
+    end
+    private_class_method :normalize_key
+
+    private
+
+    def question_criteria
+      case type
+      when :choice then choices.transform_keys(&:to_s)
+      when :score then level_descriptions
+      end
+    end
+  end
+end

data/lib/jev/errors.rb

@@ -8,4 +8,5 @@ module Jev
   class AuthenticationError < RequestError; end
   class RateLimitError < RequestError; end
   class InvalidResponseError < Error; end
+  class ReplayError < Error; end
 end

data/lib/jev/feels.rb

@@ -10,6 +10,18 @@ module Jev
       def feels?(...)
         Jev.feels?(self, ...)
       end
+
+      def decide(...)
+        Jev.decide(self, ...)
+      end
+
+      def score(...)
+        Jev.score(self, ...)
+      end
+
+      def measure(...)
+        Jev.measure(self, ...)
+      end
     end
   end
 end

data/lib/jev/harness.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Jev
+  module Harness
+    THREAD_KEY = :jev_transport
+
+    module_function
+
+    def current_transport(configuration)
+      Thread.current[THREAD_KEY] || configuration.transport || Transport.new(configuration)
+    end
+
+    def stub(answers, &)
+      raise ArgumentError, "Jev.stub requires a block" unless block_given?
+
+      overlay(StubTransport.new(answers), &)
+    end
+
+    def record(&)
+      raise ArgumentError, "Jev.record requires a block" unless block_given?
+
+      tape = Tape.new
+      inner = current_transport(Jev.configuration)
+      overlay(RecordingTransport.new(inner, tape), &)
+      tape
+    end
+
+    def replay(tape, &)
+      raise ArgumentError, "Jev.replay requires a block" unless block_given?
+
+      tape = Tape.parse(tape) unless tape.is_a?(Tape)
+      overlay(ReplayTransport.new(tape), &)
+    end
+
+    def overlay(transport)
+      previous = Thread.current[THREAD_KEY]
+      Thread.current[THREAD_KEY] = transport
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+    private_class_method :overlay
+
+    class Tape
+      def initialize(entries = [])
+        @entries = entries
+      end
+
+      def record(payload, response)
+        @entries << { "request" => canonical(payload), "response" => canonical(response) }
+      end
+
+      def lookup(payload)
+        request = canonical(payload)
+        entry = @entries.find { |item| item["request"] == request }
+        raise ReplayError, replay_message(payload) unless entry
+
+        entry["response"]
+      end
+
+      def to_json(*)
+        JSON.generate({ "version" => 1, "entries" => @entries })
+      end
+
+      def self.parse(json)
+        payload = json.is_a?(String) ? JSON.parse(json) : json
+        raise ArgumentError, "tape is not a JSON object" unless payload.is_a?(Hash)
+
+        entries = payload["entries"]
+        raise ArgumentError, "tape is missing entries" unless entries.is_a?(Array)
+
+        new(entries)
+      end
+
+      private
+
+      def canonical(value)
+        case value
+        when Hash
+          value.to_h.transform_keys(&:to_s).sort.to_h.transform_values { |item| canonical(item) }
+        when Array
+          value.map { |item| canonical(item) }
+        else
+          value
+        end
+      end
+
+      def replay_message(payload)
+        ids = payload.is_a?(Hash) ? payload["questions"]&.keys : nil
+        "Jev replay has no recorded answer for questions #{ids.inspect}"
+      end
+    end
+
+    class RecordingTransport
+      def initialize(inner, tape)
+        @inner = inner
+        @tape = tape
+      end
+
+      def call(payload)
+        response = @inner.call(payload)
+        @tape.record(payload, response)
+        response
+      end
+    end
+
+    class ReplayTransport
+      def initialize(tape)
+        @tape = tape
+      end
+
+      def call(payload)
+        @tape.lookup(payload)
+      end
+    end
+
+    class StubTransport
+      def initialize(answers)
+        @answers = answers.to_h.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+      end
+
+      def call(payload)
+        questions = payload.fetch("questions")
+        {
+          "answers" => questions.to_h { |id, question| [id, answer_for(id, question)] }
+        }
+      end
+
+      private
+
+      def answer_for(id, question)
+        stub = @answers[id.to_sym] || @answers[Jev.send(:name_for_instructions, question["instructions"])]
+        raise ArgumentError, "unstubbed Jev question: #{id}" if stub.nil?
+
+        case question["type"]
+        when "noul" then noul_answer(stub)
+        when "choice" then choice_answer(stub, question)
+        when "score" then score_answer(stub, question)
+        else
+          raise ArgumentError, "unstubbed Jev question: #{id}"
+        end
+      end
+
+      def noul_answer(stub)
+        noul = stub.is_a?(Hash) ? stub[:noul] || stub["noul"] || stub[:probability] : stub
+        { "type" => "noul", "noul" => Float(noul) }
+      end
+
+      def choice_answer(stub, question)
+        winner, confidence, probabilities = unpack_stub(stub, :choice) { stub.to_s }
+        probabilities ||= default_choice_probabilities(question["criteria"] || {}, winner)
+        {
+          "type" => "choice",
+          "choice" => winner.to_s,
+          "confidence" => Float(confidence),
+          "probabilities" => probabilities.to_h { |key, value| [key.to_s, Float(value)] }
+        }
+      end
+
+      def default_choice_probabilities(criteria, winner)
+        keys = criteria.keys.map(&:to_s)
+        keys << winner unless keys.include?(winner)
+        keys.to_h { |key| [key, key == winner ? 1.0 : 0.0] }
+      end
+
+      def score_answer(stub, question)
+        score, confidence, probabilities = unpack_stub(stub, :score) { stub }
+        probabilities ||= default_score_probabilities(question["criteria"] || [], score)
+        {
+          "type" => "score",
+          "score" => Float(score),
+          "confidence" => Float(confidence),
+          "probabilities" => score_probability_hash(probabilities, question)
+        }
+      end
+
+      def unpack_stub(stub, key)
+        return [yield, 1.0, nil] unless stub_hash?(stub, key)
+
+        [stub_field(stub, key), stub_field(stub, :confidence) || 1.0, stub_field(stub, :probabilities)]
+      end
+
+      def stub_hash?(stub, key)
+        stub.is_a?(Hash) && (stub.key?(key) || stub.key?(key.to_s))
+      end
+
+      def stub_field(stub, key)
+        stub[key] || stub[key.to_s]
+      end
+
+      def default_score_probabilities(criteria, score)
+        size = [criteria.size, 1].max
+        nearest = Float(score).round.clamp(0, size - 1)
+        size.times.to_h { |index| [index.to_s, index == nearest ? 1.0 : 0.0] }
+      end
+
+      def score_probability_hash(probabilities, question)
+        names = Jev.send(:level_names_for, question["instructions"])
+        probabilities.to_h do |key, value|
+          index = score_index(key, names)
+          [index.to_s, Float(value)]
+        end
+      end
+
+      def score_index(key, names)
+        return key if key.is_a?(Integer)
+        return Integer(key) if key.is_a?(String) && key.match?(/\A\d+\z/)
+
+        names&.index(key.to_sym) || Integer(key)
+      end
+    end
+  end
+end

data/lib/jev/match.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Jev
+  class Matcher
+    def initialize(choice)
+      @choice = choice
+      @handled = false
+      @result = nil
+    end
+
+    def on(*keys)
+      return @result if @handled
+      return unless keys.map(&:to_sym).include?(@choice)
+
+      @handled = true
+      @result = yield
+    end
+
+    def otherwise
+      return @result if @handled
+
+      @handled = true
+      @result = yield
+    end
+
+    attr_reader :result
+  end
+end

data/lib/jev/model.rb

@@ -12,10 +12,21 @@ module Jev
         subclass.extend ClassMethods
       end
 
-      def feels(attribute, name, description)
+      def feels(attribute, name, description = nil, **options)
+        declare_jev(attribute, name, description, options)
+      end
+
+      def decide(attribute, name, description = nil, **options)
+        declare_jev(attribute, name, description, options)
+      end
+
+      def score(attribute, name, description = nil, **options)
+        declare_jev(attribute, name, description, options)
+      end
+
+      def bind_jev_attribute(attribute, name)
         raise ArgumentError, "attribute must be a Symbol" unless attribute.is_a?(Symbol)
 
-        Jev.define(self, name, description)
         (@jev_feels_attributes ||= {})[name.to_sym] = attribute
       end
 
@@ -28,14 +39,55 @@ module Jev
           current = current.superclass
         end
       end
+
+      def jev_bound_fields
+        fields = []
+        current = self
+        while current && current != Object
+          fields.concat(Array(current.instance_variable_get(:@jev_feels_attributes)&.values))
+          current = current.superclass
+        end
+        fields.uniq
+      end
+
+      private
+
+      def declare_jev(attribute, name, description, options)
+        bind_jev_attribute(attribute, name)
+        return if description.nil? && options.empty?
+
+        Jev.define(self, name, description, **options)
+      end
     end
 
     def feels(predicate)
       Jev.feels(jev_text_for(predicate), self.class, predicate)
     end
 
-    def feels?(predicate, threshold: Jev.configuration.threshold)
-      Jev.feels?(jev_text_for(predicate), self.class, predicate, threshold: threshold)
+    def feels?(predicate, **)
+      Jev.feels?(jev_text_for(predicate), self.class, predicate, **)
+    end
+
+    def decide(predicate, **)
+      Jev.decide(jev_text_for(predicate), self.class, predicate, **)
+    end
+
+    def score(predicate, **)
+      Jev.score(jev_text_for(predicate), self.class, predicate, **)
+    end
+
+    def measure(predicate = nil, **, &)
+      if block_given?
+        Jev.measure(jev_batch_text, self.class, **, &)
+      else
+        raise ArgumentError, "question is required" if predicate.nil?
+
+        Jev.measure(jev_text_for(predicate), self.class, predicate, **)
+      end
+    end
+
+    def match(predicate, **, &)
+      Jev.match(jev_text_for(predicate), self.class, predicate, **, &)
     end
 
     private
@@ -47,5 +99,13 @@ module Jev
 
       public_send(attribute).to_s
     end
+
+    def jev_batch_text
+      fields = self.class.jev_bound_fields
+      raise ArgumentError, "no Jev field is bound for #{self.class}" if fields.empty?
+      raise ArgumentError, "measure block needs one field, got #{fields.inspect}" if fields.size > 1
+
+      public_send(fields.first).to_s
+    end
   end
 end

data/lib/jev/query.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Jev
+  class Query
+    attr_reader :questions
+
+    def initialize(scope)
+      @scope = scope
+      @questions = {}
+    end
+
+    def feels(name, **options)
+      add(name, options)
+    end
+
+    def decide(name, **options)
+      add(name, options)
+    end
+
+    def score(name, **options)
+      add(name, options)
+    end
+
+    private
+
+    def add(name, options)
+      raise ArgumentError, "batch questions must be a defined Symbol" unless name.is_a?(Symbol)
+      raise ArgumentError, "duplicate batch question: #{name.inspect}" if @questions.key?(name)
+
+      @questions[name] = Jev.send(:resolve_definition, name, scope: @scope, **options)
+    end
+  end
+end

data/lib/jev/registry.rb

@@ -7,14 +7,13 @@ module Jev
       @definitions = {}
     end
 
-    def define(scope, name, description)
+    def define(scope, name, definition)
       key = name.to_sym
-      value = description.to_s.dup.freeze
       scope_key = storage_key(scope)
       @mutex.synchronize do
-        (@definitions[scope_key] ||= {})[key] = value
+        (@definitions[scope_key] ||= {})[key] = definition
       end
-      value
+      definition.public_value
     end
 
     def fetch(name, scope: nil, fallback: true, inherit: true)
@@ -33,7 +32,19 @@ module Jev
     end
 
     def all(scope = nil)
-      @mutex.synchronize { (@definitions[storage_key(scope)] || {}).dup.freeze }
+      @mutex.synchronize do
+        (@definitions[storage_key(scope)] || {}).transform_values(&:public_value).freeze
+      end
+    end
+
+    def name_for_instructions(instructions)
+      each_definition { |name, definition| return name if definition.instructions == instructions }
+      nil
+    end
+
+    def find_by_instructions(instructions)
+      each_definition { |_name, definition| return definition if definition.instructions == instructions }
+      nil
     end
 
     def reset!
@@ -42,6 +53,14 @@ module Jev
 
     private
 
+    def each_definition(&block)
+      @mutex.synchronize do
+        @definitions.each_value do |defs|
+          defs.each(&block)
+        end
+      end
+    end
+
     def storage_key(scope)
       return if scope.nil?
 

data/lib/jev/result.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Jev
+  module Result
+    def self.parse(answer, definition)
+      raise InvalidResponseError, "Jev response is missing an answer" unless answer.is_a?(Hash)
+
+      case definition.type
+      when :noul then Noul.parse(answer)
+      when :choice then Choice.parse(answer)
+      when :score then Score.parse(answer, definition)
+      else
+        raise InvalidResponseError, "unknown Jev definition type: #{definition.type.inspect}"
+      end
+    end
+
+    def self.finite_unit(value, label)
+      raise InvalidResponseError, "Jev response is missing #{label}" unless value.is_a?(Numeric)
+
+      value = Float(value)
+      raise InvalidResponseError, "Jev #{label} is not finite" unless value.finite?
+
+      value
+    end
+
+    class Noul
+      attr_reader :probability
+
+      def initialize(probability:)
+        @probability = probability
+        freeze
+      end
+
+      def self.parse(answer)
+        noul = answer["noul"]
+        raise InvalidResponseError, "Jev response is missing a noul probability" unless noul.is_a?(Numeric)
+
+        noul = Float(noul)
+        raise InvalidResponseError, "Jev noul probability is not finite" unless noul.finite?
+
+        # ponytail: clamp out-of-range noul; raise if Jev starts returning uncalibrated values
+        new(probability: noul.clamp(0.0, 1.0))
+      end
+
+      def type
+        :noul
+      end
+
+      def collapsed(threshold: 0.5)
+        probability >= threshold
+      end
+    end
+
+    class Choice
+      attr_reader :choice, :confidence, :probabilities
+
+      def initialize(choice:, confidence:, probabilities:)
+        @choice = choice
+        @confidence = confidence
+        @probabilities = probabilities
+        freeze
+      end
+
+      def self.parse(answer)
+        winner = answer["choice"]
+        raise InvalidResponseError, "Jev response is missing a choice" if winner.nil?
+
+        raw = answer["probabilities"]
+        raise InvalidResponseError, "Jev response is missing choice probabilities" unless raw.is_a?(Hash)
+
+        probabilities = raw.to_h { |key, value| [key.to_sym, Result.finite_unit(value, "choice probability")] }
+        new(
+          choice: winner.to_sym,
+          confidence: Result.finite_unit(answer["confidence"], "choice confidence").clamp(0.0, 1.0),
+          probabilities: probabilities.freeze
+        )
+      end
+
+      def type
+        :choice
+      end
+
+      def collapsed(*)
+        choice
+      end
+    end
+
+    class Score
+      attr_reader :score, :confidence, :probabilities, :levels, :level
+
+      def initialize(score:, confidence:, probabilities:, levels:, level:)
+        @score = score
+        @confidence = confidence
+        @probabilities = probabilities
+        @levels = levels
+        @level = level
+        freeze
+      end
+
+      def self.parse(answer, definition)
+        names = definition.level_names
+        probabilities = score_probabilities(answer["probabilities"], names)
+        score = Result.finite_unit(answer["score"], "score")
+        new(
+          score: score,
+          confidence: Result.finite_unit(answer["confidence"], "score confidence").clamp(0.0, 1.0),
+          probabilities: probabilities,
+          levels: definition.levels,
+          level: named_level(probabilities, names)
+        )
+      end
+
+      def self.score_probabilities(raw, names)
+        raise InvalidResponseError, "Jev response is missing score probabilities" unless raw.is_a?(Hash)
+
+        raw.to_h do |key, value|
+          index = Integer(key)
+          [names ? names.fetch(index, index) : index, Result.finite_unit(value, "score probability")]
+        end.freeze
+      rescue ArgumentError, TypeError
+        raise InvalidResponseError, "Jev score probabilities are not keyed by level number"
+      end
+
+      def self.named_level(probabilities, names)
+        return unless names
+
+        key, = probabilities.max_by { |_, weight| weight }
+        key if key.is_a?(Symbol)
+      end
+      private_class_method :named_level
+
+      def type
+        :score
+      end
+
+      def collapsed(*)
+        score
+      end
+    end
+
+    class Batch
+      def initialize(results)
+        @results = results.transform_keys(&:to_sym).freeze
+        freeze
+      end
+
+      def [](key)
+        @results[key.to_sym]
+      end
+
+      def to_h
+        @results.transform_values(&:collapsed)
+      end
+
+      def deconstruct_keys(keys)
+        collapsed = to_h
+        keys ? collapsed.slice(*keys.map(&:to_sym)) : collapsed
+      end
+
+      def type
+        :batch
+      end
+    end
+  end
+end