jev-feels 0.2.0 → 1.1.0

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

data/lib/jev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jev
-  VERSION = "0.2.0"
+  VERSION = "1.1.0"
 end

data/lib/jev-feels/active_model.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "feels/active_model"

data/lib/jev.rb

@@ -3,10 +3,16 @@
 require_relative "jev/version"
 require_relative "jev/errors"
 require_relative "jev/configuration"
+require_relative "jev/definition"
 require_relative "jev/registry"
+require_relative "jev/result"
 require_relative "jev/transport"
 require_relative "jev/client"
+require_relative "jev/query"
+require_relative "jev/match"
+require_relative "jev/harness"
 require_relative "jev/feels"
+require_relative "jev/model"
 
 module Jev
   class << self
@@ -21,31 +27,23 @@ module Jev
       @configuration = Configuration.new
     end
 
-    def define(scope_or_name, name_or_description, description = nil)
-      if scope_or_name.is_a?(Module)
-        raise ArgumentError, "description is required" if description.nil?
-
-        registry.define(scope_or_name, name_or_description, description)
-      else
-        raise ArgumentError, "wrong number of arguments (given 3, expected 2)" unless description.nil?
-
-        registry.define(nil, scope_or_name, name_or_description)
-      end
+    def define(scope_or_name, name_or_description, description = nil, **options)
+      scope, name, instructions = unpack_define(scope_or_name, name_or_description, description)
+      extras = adhoc_options(options)
+      registry.define(scope, name, Definition.build(name: name, instructions: instructions, **extras))
     end
 
     def definition(scope_or_name, name = nil)
-      if name.nil?
-        registry.fetch(scope_or_name, scope: nil, fallback: false)
-      else
-        raise ArgumentError, "scope must be a Module" unless scope_or_name.is_a?(Module)
-
-        registry.fetch(name, scope: scope_or_name, fallback: false)
-      end
+      found =
+        if name.nil?
+          registry.fetch(scope_or_name, scope: nil, fallback: false, inherit: false)
+        else
+          registry.fetch(name, scope: scope_or_name, fallback: false, inherit: false)
+        end
+      found&.public_value
     end
 
     def definitions(scope = nil)
-      raise ArgumentError, "scope must be a Module" unless scope.nil? || scope.is_a?(Module)
-
       registry.all(scope)
     end
 
@@ -54,26 +52,106 @@ module Jev
     end
 
     def feels(text, scope_or_predicate, predicate = nil)
-      scope, predicate = unpack_predicate(scope_or_predicate, predicate)
-      Client.new(configuration).probability(coerce_text(text), resolve(predicate, scope: scope))
+      measure_one(text, scope_or_predicate, predicate, id: Client::QUESTION_ID).probability
     end
 
-    def feels?(text, scope_or_predicate, predicate = nil, threshold: configuration.threshold)
-      feels(text, scope_or_predicate, predicate) >= normalize_threshold(threshold)
+    def feels?(text, scope_or_predicate, predicate = nil, **opts)
+      validate_noul_decision!(opts)
+      decide_noul(feels(text, scope_or_predicate, predicate), opts)
+    end
+
+    def decide(text, scope_or_predicate, predicate = nil, confidence: nil, **options)
+      require_adhoc_type(scope_or_predicate, predicate, options, :choices)
+      confidence = normalize_unit(confidence, "confidence") unless confidence.nil?
+      result = typed_measure(:choice, text, scope_or_predicate, predicate, **options)
+      return if confidence && result.confidence < confidence
+
+      result.choice
+    end
+
+    def score(text, scope_or_predicate, predicate = nil, **options)
+      require_adhoc_type(scope_or_predicate, predicate, options, :levels)
+      typed_measure(:score, text, scope_or_predicate, predicate, **options).score
+    end
+
+    def measure(text, scope_or_predicate = nil, predicate = nil, **options, &block)
+      if block
+        raise ArgumentError, "unknown keyword: #{options.keys.first}" unless options.empty?
+        raise ArgumentError, "predicate is not used with a measure block" unless predicate.nil?
+
+        measure_batch(text, scope_or_predicate, &block)
+      else
+        raise ArgumentError, "question is required" if scope_or_predicate.nil?
+
+        measure_one(text, scope_or_predicate, predicate, **options)
+      end
+    end
+
+    def match(text, scope_or_predicate, predicate = nil, confidence: nil, **, &block)
+      raise ArgumentError, "Jev.match requires a block" unless block
+
+      matcher = Matcher.new(decide(text, scope_or_predicate, predicate, confidence: confidence, **))
+      block.arity.zero? ? matcher.instance_eval(&block) : yield(matcher)
+      matcher.result
+    end
+
+    def stub(answers, &)
+      Harness.stub(answers, &)
+    end
+
+    def record(&)
+      Harness.record(&)
+    end
+
+    def replay(tape, &)
+      Harness.replay(tape, &)
     end
 
     def normalize_threshold(value)
-      raise ArgumentError, "threshold must be a Float between 0.0 and 1.0" unless value.is_a?(Numeric)
+      normalize_unit(value, "threshold")
+    end
+
+    def resolve_definition(predicate, scope: nil, **options)
+      case predicate
+      when Symbol
+        raise ArgumentError, "unknown keyword: #{options.keys.first}" unless options.empty?
+
+        registry.fetch(predicate, scope: scope) ||
+          raise(UndefinedDefinition, undefined_message(predicate, scope))
+      when String
+        Definition.build(name: :adhoc, instructions: predicate, **adhoc_options(options))
+      else
+        raise ArgumentError, "predicate must be a Symbol or String"
+      end
+    end
+
+    def name_for_instructions(instructions)
+      registry.name_for_instructions(instructions)
+    end
+
+    def level_names_for(instructions)
+      registry.find_by_instructions(instructions)&.level_names
+    end
+    private :resolve_definition, :name_for_instructions, :level_names_for
+
+    private
+
+    def normalize_unit(value, name)
+      raise ArgumentError, "#{name} must be a Float between 0.0 and 1.0" unless value.is_a?(Numeric)
 
       value = Float(value)
       unless value.finite? && value.between?(0.0, 1.0)
-        raise ArgumentError, "threshold must be a Float between 0.0 and 1.0"
+        raise ArgumentError, "#{name} must be a Float between 0.0 and 1.0"
       end
 
       value
     end
 
-    private
+    def require_adhoc_type(scope_or_predicate, predicate, options, key)
+      _scope, name = unpack_predicate(scope_or_predicate, predicate)
+      return unless name.is_a?(String)
+      raise ArgumentError, "#{key} is required" unless options.key?(key)
+    end
 
     attr_reader :registry
 
@@ -86,21 +164,13 @@ module Jev
 
     def unpack_predicate(scope_or_predicate, predicate)
       return [nil, scope_or_predicate] if predicate.nil?
-      raise ArgumentError, "scope must be a Module" unless scope_or_predicate.is_a?(Module)
+      raise ArgumentError, "scope must be a Module, String, or Symbol" unless scoped?(scope_or_predicate)
 
       [scope_or_predicate, predicate]
     end
 
-    def resolve(predicate, scope: nil)
-      case predicate
-      when Symbol
-        registry.fetch(predicate, scope: scope) ||
-          raise(UndefinedDefinition, undefined_message(predicate, scope))
-      when String
-        predicate
-      else
-        raise ArgumentError, "predicate must be a Symbol or String"
-      end
+    def scoped?(value)
+      value.is_a?(Module) || value.is_a?(String) || value.is_a?(Symbol)
     end
 
     def undefined_message(predicate, scope)
@@ -110,8 +180,88 @@ module Jev
         "Undefined Jev definition: #{predicate.inspect}"
       end
     end
+
+    def unpack_define(scope_or_name, name_or_description, description)
+      if description.nil?
+        if scope_or_name.is_a?(Module) || name_or_description.is_a?(Symbol)
+          raise ArgumentError, "description is required"
+        end
+
+        [nil, scope_or_name, name_or_description]
+      else
+        [scope_or_name, name_or_description, description]
+      end
+    end
+
+    def adhoc_options(options)
+      choices = options.delete(:choices)
+      levels = options.delete(:levels)
+      raise ArgumentError, "unknown keyword: #{options.keys.first}" unless options.empty?
+
+      { choices: choices, levels: levels }
+    end
+
+    def measure_one(text, scope_or_predicate, predicate, id: nil, **)
+      scope, predicate = unpack_predicate(scope_or_predicate, predicate)
+      definition = resolve_definition(predicate, scope: scope, **)
+      question_id = id || (predicate.is_a?(Symbol) ? predicate.to_s : definition.type.to_s)
+      Client.new(configuration).ask(coerce_text(text), { question_id => definition }).fetch(question_id)
+    end
+
+    def typed_measure(type, text, scope_or_predicate, predicate, **)
+      result = measure_one(text, scope_or_predicate, predicate, **)
+      return result if result.type == type
+
+      label = predicate_label(scope_or_predicate, predicate)
+      raise ArgumentError, "#{label} is a #{result.type} definition, not a #{type}"
+    end
+
+    def predicate_label(scope_or_predicate, predicate)
+      (_scope, name) = unpack_predicate(scope_or_predicate, predicate)
+      name.inspect
+    end
+
+    def measure_batch(text, scope, &)
+      questions = collect_questions(scope, &)
+      answers = Client.new(configuration).ask(coerce_text(text), questions.transform_keys(&:to_s))
+      Result::Batch.new(questions.keys.to_h { |key| [key, answers.fetch(key.to_s)] })
+    end
+
+    def collect_questions(scope)
+      query = Query.new(scope)
+      yield query
+      raise ArgumentError, "measure block must declare at least one question" if query.questions.empty?
+
+      query.questions
+    end
+
+    def validate_noul_decision!(opts)
+      unknown = opts.keys - %i[threshold at_least]
+      raise ArgumentError, "unknown keyword: #{unknown.first}" unless unknown.empty?
+      if opts.key?(:at_least) && opts.key?(:threshold)
+        raise ArgumentError,
+              "cannot use threshold: and at_least: together"
+      end
+
+      normalize_unit(opts[:at_least], "at_least") if opts.key?(:at_least)
+      normalize_threshold(opts[:threshold]) if opts.key?(:threshold)
+    end
+
+    def decide_noul(probability, opts)
+      if opts.key?(:at_least)
+        at_least = normalize_unit(opts[:at_least], "at_least")
+        return true if probability >= at_least
+        return false if probability + at_least <= 1.0
+
+        nil
+      else
+        probability >= normalize_threshold(opts.fetch(:threshold, configuration.threshold))
+      end
+    end
   end
 
+  private_constant :Query, :Matcher, :Harness
+
   reset_configuration!
   @registry = Registry.new
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jev-feels
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Maxim Veysgeym
@@ -11,27 +11,38 @@ cert_chain: []
 date: 2026-09-20 00:00:00.000000000 Z
 dependencies: []
 description: |
-  Tiny Ruby API for semantic text checks. Jev.feels?(:urgent) is an ordinary
-  condition, not an SDK session. Jev stays an implementation detail.
+  Tiny Ruby API for semantic text decisions. Jev.feels?(:urgent), Jev.decide,
+  and Jev.score are ordinary Ruby, not an SDK session. Jev stays an
+  implementation detail.
 email:
 - Qew7@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - context7.json
 - lib/feels.rb
+- lib/feels/active_model.rb
 - lib/feels/string.rb
 - lib/jev-feels.rb
+- lib/jev-feels/active_model.rb
 - lib/jev-feels/string.rb
 - lib/jev.rb
+- lib/jev/active_model.rb
 - lib/jev/client.rb
 - lib/jev/configuration.rb
+- lib/jev/definition.rb
 - lib/jev/errors.rb
 - lib/jev/feels.rb
+- lib/jev/harness.rb
+- lib/jev/match.rb
+- lib/jev/model.rb
+- lib/jev/query.rb
 - lib/jev/registry.rb
+- lib/jev/result.rb
 - lib/jev/transport.rb
 - lib/jev/version.rb
 homepage: https://github.com/Qew7/jev-feels
@@ -40,7 +51,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Qew7/jev-feels
   source_code_uri: https://github.com/Qew7/jev-feels
-  changelog_uri: https://github.com/Qew7/jev-feels/blob/main/README.md
+  changelog_uri: https://github.com/Qew7/jev-feels/blob/master/CHANGELOG.md
   allowed_push_host: https://rubygems.org
 post_install_message:
 rdoc_options: []