judge_rails 0.0.1

data/lib/judge/rails/jobs.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    module Jobs
+      extend ActiveSupport::Concern
+
+      RETRYABLE_ERRORS = [Judge::RateLimitError, Judge::ServerError, Judge::TransportError,
+                          ActiveRecord::Deadlocked, ActiveRecord::LockWaitTimeout].freeze
+
+      Payload = Struct.new(:model, :ids, :names, keyword_init: true) do
+        def model_name
+          model.name
+        end
+      end
+
+      class << self
+        def enqueuer
+          @enqueuer || method(:default_enqueue)
+        end
+
+        def enqueuer=(callable)
+          unless callable.respond_to?(:call)
+            raise ArgumentError, "enqueuer must respond to call. Use reset_enqueuer! to restore ActiveJob"
+          end
+
+          @enqueuer = callable
+        end
+
+        def reset_enqueuer!
+          @enqueuer = nil
+        end
+
+        def enqueue_record(record, names)
+          enqueuer.call(Payload.new(model: record.class, ids: [record.id], names: Array(names)))
+        end
+
+        def perform(payload, batch_size: 100, adapter: nil, raise_retryable: false)
+          model = payload.model.is_a?(String) ? payload.model.constantize : payload.model
+          names = payload.names
+          model.where(id: payload.ids).find_each(batch_size: batch_size) do |record|
+            refresh_safely(record, names, adapter: adapter, raise_retryable: raise_retryable)
+          end
+        end
+
+        def refresh_safely(record, names = [], adapter: nil, raise_retryable: false)
+          record.judge_refresh!(*names, adapter: adapter)
+          true
+        rescue *RETRYABLE_ERRORS => e
+          raise if raise_retryable
+
+          Judge::Rails.log_failure(record.class, e)
+          false
+        rescue StandardError => e
+          Judge::Rails.log_failure(record.class, e)
+          false
+        end
+
+        private
+
+        def default_enqueue(payload)
+          refresh_job.perform_later(payload.model_name, payload.ids.first, payload.names.map(&:to_s))
+        end
+
+        def refresh_job
+          require "judge/rails/refresh_job" if defined?(::ActiveJob)
+          return Judge::Rails::RefreshJob if defined?(Judge::Rails::RefreshJob)
+
+          raise Judge::ConfigurationError,
+                "async judge attributes need ActiveJob or a custom Judge::Rails::Jobs.enqueuer. " \
+                "Otherwise declare them with sync: true or callbacks: false"
+        end
+      end
+
+      class_methods do
+        def judge_install_callbacks(definition)
+          judge_install_save_callback if definition.sync? || definition.enqueue?
+          judge_install_commit_callback if definition.enqueue?
+        end
+
+        private
+
+        def judge_install_save_callback
+          return if defined?(@judge_save_callback) && @judge_save_callback
+
+          @judge_save_callback = true
+          before_save :judge_before_save
+        end
+
+        def judge_install_commit_callback
+          return if defined?(@judge_commit_callback) && @judge_commit_callback
+
+          @judge_commit_callback = true
+          after_commit :judge_enqueue_refresh, on: %i[create update]
+          after_rollback :judge_forget_flagged
+        end
+      end
+
+      def judge_refresh_later(*names)
+        names = names.flatten
+        names = self.class.judge_attributes.names if names.empty?
+        Jobs.enqueue_record(self, names)
+      end
+
+      private
+
+      def judge_before_save
+        automatic = self.class.judge_attributes.select { |d| d.sync? || d.enqueue? }
+        pending, blank = Storage.plan(self, automatic)
+        blank.each { |definition| Storage.clear(self, definition) }
+        judge_flag_async(pending.keys.select(&:enqueue?))
+        return if @judge_skip_inline
+
+        Storage.groups(pending.select { |definition, _| definition.sync? }).each do |(state, model), group|
+          compute_group_inline(state, model, group)
+        end
+      end
+
+      def judge_flag_async(definitions)
+        (@judge_flagged_async ||= Set.new).merge(definitions.map(&:name))
+      end
+
+      def judge_forget_flagged
+        @judge_flagged_async = nil
+      end
+
+      def compute_group_inline(state, model, group)
+        Storage.ask(self, state, model, group, adapter: @judge_refresh_adapter)
+      rescue StandardError => e
+        handle_inline_error(e, group)
+      end
+
+      def handle_inline_error(error, group)
+        modes = group.map(&:on_error)
+        raise error if modes.include?(:raise)
+
+        Judge::Rails.log_failure(self.class, error)
+        return unless modes.include?(:fail)
+
+        names = group.select { |d| d.on_error == :fail }.map(&:name)
+        errors.add(:base, "could not judge #{names.join(", ")}: #{error.class}")
+        throw :abort
+      end
+
+      def judge_enqueue_refresh
+        flagged = @judge_flagged_async
+        judge_forget_flagged
+        return if flagged.nil? || flagged.empty?
+
+        definitions = flagged.map { |name| self.class.judge_definition(name) }
+        pending = Storage.stale_definitions(self, definitions)
+        Jobs.enqueue_record(self, pending.map(&:name)) if pending.any?
+      end
+    end
+  end
+end

data/lib/judge/rails/locale/en.yml

@@ -0,0 +1,6 @@
+en:
+  errors:
+    messages:
+      judge_refuted: 'matched "%{instruction}"'
+      judge_unmatched: 'did not match "%{instruction}"'
+      judge_unavailable: 'could not be checked against "%{instruction}"'

data/lib/judge/rails/migration.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Judge
+  module Rails
+    module Migration
+      VALUE_TYPES = { noul: :float, score: :float, choice: :string }.freeze
+
+      class << self
+        def value_type(type)
+          VALUE_TYPES.fetch(type.to_s.to_sym) do
+            raise ArgumentError,
+                  "unknown judge attribute type #{type.inspect}, expected one of #{VALUE_TYPES.keys.inspect}"
+          end
+        end
+
+        def value_options(type, connection = nil)
+          value_type(type) == :float && mysql?(connection) ? { limit: 53 } : {}
+        end
+
+        def nullable!(null)
+          return if null
+
+          raise ArgumentError, "a judge value column must allow NULL: it is empty until judged and cleared " \
+                               "when its text goes blank"
+        end
+
+        def sidecar_column(name)
+          :"#{name}_judge"
+        end
+
+        def sidecar_type(connection = nil)
+          postgresql?(connection) ? :jsonb : :json
+        end
+
+        def sidecar_options(connection = nil)
+          mysql?(connection) ? {} : { null: false, default: {} }
+        end
+
+        def postgresql?(connection = nil)
+          adapter_name(connection).start_with?("postg")
+        end
+
+        def mysql?(connection = nil)
+          adapter_name(connection).match?(/mysql|trilogy/)
+        end
+
+        def adapter_name(connection = nil)
+          target = connection.respond_to?(:delegate) ? connection.delegate : connection
+          target = ActiveRecord::Base.lease_connection unless target.respond_to?(:adapter_name)
+          target.adapter_name.to_s.downcase
+        end
+      end
+
+      def judge_attribute(table, name, type, index: true, null: true)
+        Migration.nullable!(null)
+        add_column table, name, Migration.value_type(type), null: null,
+                                                            **Migration.value_options(type, connection)
+        add_column table, Migration.sidecar_column(name), Migration.sidecar_type(connection),
+                   **Migration.sidecar_options(connection)
+        add_index table, name if index
+      end
+
+      def remove_judge_attribute(table, name, type = nil, index: true, null: true)
+        if type.nil? && connection.is_a?(ActiveRecord::Migration::CommandRecorder)
+          raise ActiveRecord::IrreversibleMigration,
+                "remove_judge_attribute #{table.inspect}, #{name.inspect} needs its type " \
+                "(:noul, :choice or :score) to be reversible"
+        end
+
+        sidecar = Migration.sidecar_column(name)
+        remove_index table, name, if_exists: true if index
+        remove_column table, sidecar, Migration.sidecar_type(connection),
+                      **Migration.sidecar_options(connection)
+        value_options = type ? Migration.value_options(type, connection) : {}
+        remove_column table, name, (type && Migration.value_type(type)), null: null, **value_options
+      end
+
+      module TableDefinition
+        def judge_attribute(name, type, index: true, null: true)
+          Migration.nullable!(null)
+          conn = judge_connection
+          column name, Migration.value_type(type), null: null, index: index,
+                                                   **Migration.value_options(type, conn)
+          column Migration.sidecar_column(name), Migration.sidecar_type(conn),
+                 **Migration.sidecar_options(conn)
+        end
+
+        private
+
+        def judge_connection
+          conn = instance_variable_get(:@conn)
+          conn if conn.respond_to?(:adapter_name)
+        end
+      end
+
+      module Table
+        def judge_attribute(name, type, index: true, null: true)
+          Migration.nullable!(null)
+          column name, Migration.value_type(type), null: null, **Migration.value_options(type, @base)
+          column Migration.sidecar_column(name), Migration.sidecar_type(@base),
+                 **Migration.sidecar_options(@base)
+          index name if index
+        end
+      end
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Migration.include(Judge::Rails::Migration)
+  ActiveRecord::ConnectionAdapters::TableDefinition.include(Judge::Rails::Migration::TableDefinition)
+  ActiveRecord::ConnectionAdapters::Table.include(Judge::Rails::Migration::Table)
+end

data/lib/judge/rails/refresh.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    module Refresh
+      extend ActiveSupport::Concern
+
+      Summary = Struct.new(:records, :computed, :skipped, :failed, :calls, keyword_init: true) do
+        def to_h
+          { records: records, computed: computed, skipped: skipped, failed: failed, calls: calls }
+        end
+      end
+
+      class_methods do
+        def judge_refresh_all(scope = all, batch_size: 100, force: false, resume: false, adapter: nil)
+          summary = Summary.new(records: 0, computed: 0, skipped: 0, failed: 0, calls: 0)
+          effective_force = force && !resume
+          scope.find_each(batch_size: batch_size) do |record|
+            summary.records += 1
+            judge_refresh_record(record, effective_force, adapter, summary)
+          end
+          summary
+        end
+
+        private
+
+        def judge_refresh_record(record, force, adapter, summary)
+          changed = record.judge_refresh!(force: force, adapter: adapter) { summary.calls += 1 }
+          changed.empty? ? summary.skipped += 1 : summary.computed += 1
+        rescue StandardError => e
+          summary.failed += 1
+          Judge::Rails.log_failure(record.class, e)
+        end
+      end
+    end
+  end
+end

data/lib/judge/rails/refresh_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    class RefreshJob < ActiveJob::Base
+      queue_as { "default" }
+      retry_on(*Jobs::RETRYABLE_ERRORS, wait: :polynomially_longer, attempts: 5)
+
+      def perform(model_name, id, names = [])
+        payload = Jobs::Payload.new(model: model_name.constantize, ids: [id], names: names)
+        Jobs.perform(payload, raise_retryable: true)
+      end
+    end
+  end
+end

data/lib/judge/rails/registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    class Registry
+      include Enumerable
+
+      def initialize(parent = nil)
+        @parent = parent
+        @own = {}
+        @version = 0
+      end
+
+      def add(definition)
+        @own[definition.name] = definition
+        @version += 1
+        definition
+      end
+
+      def version
+        @version + (@parent ? @parent.version : 0)
+      end
+
+      def [](name)
+        @own[name.to_sym] || @parent&.[](name)
+      end
+
+      def fetch(name)
+        self[name] || raise(ArgumentError, "no judge attribute named #{name.inspect}")
+      end
+
+      def to_h
+        current = version
+        return @flattened if @flattened_version == current
+
+        @flattened_version = current
+        @flattened = (@parent ? @parent.to_h : {}).merge(@own).freeze
+      end
+
+      def each(&)
+        to_h.each_value(&)
+      end
+
+      def names
+        to_h.keys
+      end
+
+      def empty?
+        to_h.empty?
+      end
+
+      def inherit
+        self.class.new(self)
+      end
+    end
+  end
+end

data/lib/judge/rails/relation.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    module Relation
+      ADHOC_NAME = :judge_adhoc
+
+      Target = Struct.new(:question, :option, :level) do
+        def measure(result)
+          case question.type
+          when "choice" then result.probability_of(option) || 0.0
+          else result.value
+          end
+        end
+
+        def passes?(result, threshold)
+          return result.value >= level - 0.5 if question.type == "score"
+
+          measure(result) >= threshold
+        end
+      end
+
+      module ClassMethods
+        def judge_filter(question, limit: nil, source: nil, threshold: 0.5, option: nil, at_least: nil,
+                         model: nil, adapter: nil, concurrency: nil)
+          question = judge_adhoc_question(question)
+          target = judge_target(question, :judge_filter, option: option, at_least: at_least)
+          judge_check_threshold!(threshold)
+          judged = judge_judge(question, :judge_filter, limit: limit, source: source, model: model,
+                                                        adapter: adapter, concurrency: concurrency)
+          judged.select { |_record, result| target.passes?(result, threshold) }.keys
+        end
+
+        def judge_map(question, limit: nil, source: nil, model: nil, adapter: nil, concurrency: nil)
+          judge_judge(judge_adhoc_question(question), :judge_map, limit: limit, source: source, model: model,
+                                                                  adapter: adapter, concurrency: concurrency)
+        end
+
+        def judge_sort(question, limit: nil, source: nil, dir: :desc, option: nil, model: nil, adapter: nil,
+                       concurrency: nil)
+          direction = dir.to_s.downcase.to_sym
+          unless %i[asc desc].include?(direction)
+            raise ArgumentError, "dir must be :asc or :desc, got #{dir.inspect}"
+          end
+
+          question = judge_adhoc_question(question)
+          target = judge_target(question, :judge_sort, option: option, at_least: :any)
+          judged = judge_judge(question, :judge_sort, limit: limit, source: source, model: model,
+                                                      adapter: adapter, concurrency: concurrency)
+          sign = direction == :asc ? 1 : -1
+          judged.sort_by { |_record, result| sign * target.measure(result) }.map(&:first)
+        end
+
+        private
+
+        def judge_adhoc_question(question)
+          question.is_a?(Judge::Question) ? question : Judge.noul(question.to_s)
+        end
+
+        def judge_target(question, caller_name, option:, at_least:)
+          case question.type
+          when "choice" then Target.new(question, judge_target_option(question, option, caller_name), nil)
+          when "score" then Target.new(question, nil, judge_target_level(question, at_least, caller_name))
+          else Target.new(question, nil, nil)
+          end
+        end
+
+        def judge_target_option(question, option, caller_name)
+          return option.to_s if question.options.include?(option.to_s)
+
+          raise ArgumentError, "#{caller_name} with a choice question needs option: one of " \
+                               "#{question.options.inspect}, got #{option.inspect}"
+        end
+
+        def judge_target_level(question, at_least, caller_name)
+          return nil if at_least == :any
+
+          if at_least.nil?
+            raise ArgumentError, "#{caller_name} with a score question needs at_least: one of " \
+                                 "#{question.levels.inspect}"
+          end
+          judge_level(at_least, question.levels, caller_name)
+        end
+
+        def judge_check_threshold!(threshold)
+          return if threshold.is_a?(Numeric) && threshold.between?(0, 1)
+
+          raise ArgumentError, "threshold must be a number between 0 and 1, got #{threshold.inspect}"
+        end
+
+        def judge_judge(question, caller_name, limit:, source:, model:, adapter:, concurrency:)
+          judge_check_limit!(limit, caller_name)
+          definition = Definition.new(name: ADHOC_NAME, question: question,
+                                      source: judge_adhoc_source(source, caller_name))
+
+          records = all.limit([all.limit_value&.then { |value| Integer(value) }, limit].compact.min).to_a
+          # Built here so the workers below never check out a database connection.
+          judgeable = records.map { |record| [record, definition.state_for(record)] }
+                             .reject { |_record, state| state.empty? }
+
+          texts = judgeable.map(&:last).uniq
+          answers = Judge::Pool.map(texts, concurrency: concurrency) do |text|
+            Judge.ask(definition.question, text: text, model: model, adapter: adapter)
+          end
+          by_text = texts.zip(answers).to_h
+
+          judgeable.to_h { |record, state| [record, by_text.fetch(state)] }
+        end
+
+        def judge_check_limit!(limit, caller_name)
+          if limit.nil?
+            raise ArgumentError,
+                  "#{caller_name} requires limit:. It makes one API call per row, so an unbounded " \
+                  "scan would judge the whole table. Pass an explicit limit: you are willing to pay for."
+          end
+          return if limit.is_a?(Integer) && limit.positive?
+
+          raise ArgumentError, "limit: must be a positive Integer, got #{limit.inspect}"
+        end
+
+        def judge_adhoc_source(source, caller_name)
+          resolved = source || (respond_to?(:judge_default_source) && judge_default_source)
+          return resolved if resolved
+
+          raise ArgumentError,
+                "#{caller_name} needs source: (a column symbol or a callable returning the text to judge), " \
+                "or a model-level judge_source"
+        end
+      end
+    end
+  end
+end

data/lib/judge/rails/scopes.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Judge
+  module Rails
+    module Scopes
+      extend ActiveSupport::Concern
+
+      DIRECTIONS = %i[asc desc].freeze
+      NUMERIC_LEVEL = /\A-?\d+\z/
+
+      class_methods do
+        def judge_define_scopes(definition)
+          column = definition.value_column
+          name = definition.name
+
+          judge_scope(:"#{name}_unknown") { all.where(column => nil) }
+          judge_scope(:"order_by_#{name}") { |dir = :desc| all.order(column => judge_order_direction(dir)) }
+
+          case definition.type
+          when "noul" then judge_define_noul_scopes(name, column)
+          when "choice" then judge_define_choice_scopes(name, column, definition.question.options)
+          when "score" then judge_define_score_scopes(name, column, definition.question.levels)
+          end
+          judge_define_model_scopes
+        end
+
+        private
+
+        def judge_define_noul_scopes(name, column)
+          judge_scope(:"#{name}_above") do |probability|
+            all.where(arel_table[column].gteq(judge_probability(probability, name)))
+          end
+          judge_scope(:"#{name}_below") do |probability|
+            all.where(arel_table[column].lteq(judge_probability(probability, name)))
+          end
+          judge_scope(:"#{name}_between") do |low, high|
+            all.where(arel_table[column].gt(judge_probability(low, name)))
+               .where(arel_table[column].lt(judge_probability(high, name)))
+          end
+        end
+
+        def judge_define_choice_scopes(name, column, options)
+          judge_scope(:"#{name}_is") { |*values| all.where(column => judge_options(values, options, name)) }
+          judge_scope(:"#{name}_not") do |*values|
+            all.where.not(column => judge_options(values, options, name))
+          end
+        end
+
+        def judge_define_score_scopes(name, column, levels)
+          judge_scope(:"#{name}_at_least") do |level|
+            all.where(arel_table[column].gteq(judge_level(level, levels, name) - 0.5))
+          end
+          judge_scope(:"#{name}_at_most") do |level|
+            all.where(arel_table[column].lt(judge_level(level, levels, name) + 0.5))
+          end
+          judge_scope(:"#{name}_level") do |level|
+            index = judge_level(level, levels, name)
+            all.where(column => (index - 0.5)...(index + 0.5))
+          end
+        end
+
+        def judge_define_model_scopes
+          judge_scope(:judge_computed) do
+            judge_value_columns.reduce(all) { |relation, column| relation.where.not(column => nil) }
+          end
+          judge_scope(:judge_uncomputed) do
+            columns = judge_value_columns
+            columns.empty? ? all : all.where(columns.map { |c| arel_table[c].eq(nil) }.reduce(:or))
+          end
+        end
+
+        def judge_scope(name, &body)
+          return if singleton_class.method_defined?(name) && !judge_generated_scope?(name)
+
+          (@judge_generated_scopes ||= Set.new) << name
+          singleton_class.send(:define_method, name, &body)
+        end
+
+        def judge_generated_scope?(name)
+          ancestors.grep(Class).any? do |klass|
+            klass.instance_variable_get(:@judge_generated_scopes)&.include?(name)
+          end
+        end
+
+        def judge_value_columns
+          judge_attributes.map(&:value_column)
+        end
+
+        def judge_order_direction(dir)
+          direction = dir.to_s.downcase.to_sym
+          return direction if DIRECTIONS.include?(direction)
+
+          raise ArgumentError, "order direction must be one of #{DIRECTIONS.inspect}, got #{dir.inspect}"
+        end
+
+        def judge_probability(value, name)
+          return value if value.is_a?(Numeric) && value.between?(0, 1)
+
+          raise ArgumentError, "#{name} scopes take a probability between 0 and 1, got #{value.inspect}"
+        end
+
+        def judge_options(values, options, name)
+          picked = values.flatten.map(&:to_s)
+          raise ArgumentError, "#{name} needs at least one option" if picked.empty?
+
+          unknown = picked - options
+          return picked if unknown.empty?
+
+          raise ArgumentError,
+                "unknown #{name} option(s) #{unknown.inspect}, expected one of #{options.inspect}"
+        end
+
+        def judge_level(level, levels, name)
+          by_index = level.is_a?(Integer) && !levels.all? { |label| label.match?(NUMERIC_LEVEL) }
+          index = by_index ? level : levels.index(level.to_s)
+          return index if index&.between?(0, levels.size - 1)
+
+          raise ArgumentError, "unknown #{name} level #{level.inspect}, expected one of #{levels.inspect} " \
+                               "or 0..#{levels.size - 1}"
+        end
+      end
+    end
+  end
+end