jev-feels 1.0.0 → 1.1.0

data/lib/jev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jev
-  VERSION = "1.0.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,9 +3,14 @@
 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"
 
@@ -22,24 +27,20 @@ module Jev
       @configuration = Configuration.new
     end
 
-    def define(scope_or_name, name_or_description, description = nil)
-      if description.nil?
-        if scope_or_name.is_a?(Module) || name_or_description.is_a?(Symbol)
-          raise ArgumentError, "description is required"
-        end
-
-        registry.define(nil, scope_or_name, name_or_description)
-      else
-        registry.define(scope_or_name, name_or_description, 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, inherit: false)
-      else
-        registry.fetch(name, scope: scope_or_name, fallback: false, inherit: 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)
@@ -51,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, **opts)
+      validate_noul_decision!(opts)
+      decide_noul(feels(text, scope_or_predicate, predicate), opts)
     end
 
-    def feels?(text, scope_or_predicate, predicate = nil, threshold: configuration.threshold)
-      feels(text, scope_or_predicate, predicate) >= normalize_threshold(threshold)
+    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
 
@@ -92,18 +173,6 @@ module Jev
       value.is_a?(Module) || value.is_a?(String) || value.is_a?(Symbol)
     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
-    end
-
     def undefined_message(predicate, scope)
       if scope
         "Undefined Jev definition: #{predicate.inspect} for #{scope}"
@@ -111,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: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Maxim Veysgeym
@@ -11,28 +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
@@ -41,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/master/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: []