jev-feels 0.2.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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Jev
+  module Model
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def inherited(subclass)
+        super
+        subclass.extend ClassMethods
+      end
+
+      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_feels_attributes ||= {})[name.to_sym] = attribute
+      end
+
+      def jev_feels_attribute(name)
+        current = self
+        while current && current != Object
+          found = current.instance_variable_get(:@jev_feels_attributes)&.[](name)
+          return found if found
+
+          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, **)
+      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
+
+    def jev_text_for(predicate)
+      attribute = self.class.jev_feels_attribute(predicate.to_sym) || raise(
+        UndefinedDefinition, "Undefined Jev definition: #{predicate.inspect} for #{self.class}"
+      )
+
+      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,32 +7,96 @@ 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] = value
+        (@definitions[scope_key] ||= {})[key] = definition
       end
-      value
+      definition.public_value
     end
 
-    def fetch(name, scope: nil, fallback: true)
+    def fetch(name, scope: nil, fallback: true, inherit: true)
       key = name.to_sym
       @mutex.synchronize do
-        scoped = @definitions.dig(scope, key) if scope
-        return scoped if scoped
-        return unless fallback || scope.nil?
+        return @definitions.dig(nil, key) if scope.nil?
 
-        @definitions.dig(nil, key)
+        lookup_keys(scope, inherit: inherit).each do |scope_key|
+          found = @definitions.dig(scope_key, key)
+          return found if found
+        end
+        return @definitions.dig(nil, key) if fallback
+
+        nil
       end
     end
 
     def all(scope = nil)
-      @mutex.synchronize { (@definitions[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!
       @mutex.synchronize { @definitions.clear }
     end
+
+    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?
+
+      key =
+        case scope
+        when String, Symbol then scope.to_s
+        when Module then scope.name || scope
+        else raise ArgumentError, "scope must be a Module, String, or Symbol"
+        end
+      raise ArgumentError, "scope must be a non-empty String" if key.is_a?(String) && key.empty?
+
+      key
+    end
+
+    def lookup_keys(scope, inherit:)
+      keys = [storage_key(scope)]
+      return keys unless inherit
+
+      klass = scope.is_a?(Class) ? scope : constantize(scope)
+      return keys unless klass.is_a?(Class)
+
+      current = klass.superclass
+      while current && current != Object
+        keys << (current.name || current)
+        current = current.superclass
+      end
+      keys.uniq
+    end
+
+    def constantize(name)
+      name = name.to_s if name.is_a?(Symbol)
+      return unless name.is_a?(String)
+
+      name.split("::").reduce(Object) { |mod, part| mod.const_get(part, false) }
+    rescue NameError
+      nil
+    end
   end
 end