FOLIO circ rules evaluation

circ_index_profile.rb

# frozen_string_literal: true

# require 'ruby-prof'
require 'csv'

# locations
## institution
SU_ID = '8d433cdd-4e8f-4dc1-aa24-8a4ddb7dc929'

## campus
SUL_ID = 'c365047a-51f2-45ce-8601-e421ca3615c5'
MED_ID = '40b76104-95ea-4360-a2be-5fd887222e2d'

## library
GREEN_ID = 'f6b5519e-88d9-413e-924d-9ed96255f72e'
ARS_ID = 'fe87087a-108b-4771-8ab9-5a4a5fc40960'
MEDIA_CENTER_ID = '0acfabb7-0a71-47be-82c0-c0200dd47952'
SAL3_ID = 'ddd3bce1-9f8f-4448-8d6d-b6c1b3907ba9'
LANE_ID = '5b2c8449-eed6-4bd3-bcef-af1e5a225400'

## location
GRE_STACKS_ID = '4573e824-9273-4f13-972f-cff7bf504217'
ARS_REF_ID = '4492a47c-6975-48de-aa50-0e7f15a1da62'
MEDIA_CAGE_ID = 'b3d15dd8-a053-4c06-93e9-e76e2dc59385'
SAL3_PAGE_MU_ID = '77779df8-61f3-4475-8f2a-b7ef97ec2c96'
LANE_EDOC_ID = 'ce250ebb-807f-460a-9afa-b2087645e4a8'
ARS_FOLIO_ID = '75115f9b-71d6-4106-8ab9-962f2ca9dd4c'

# material types
BOOK_ID = '1a54b431-2e4f-452d-9cae-9cee66c9a892'
MICROFORM_ID = 'fd6c6515-d470-4561-9c32-3e3290d4ca98'
PERIODICAL_ID = 'd934e614-215d-4667-b231-aed97887f289'
SCORE_ID = '8cea2cd7-6a61-494e-a602-17045da7e3cb'

# loan types
CAN_CIRCULATE_ID = '2b94c631-fca9-4892-a730-03ee529ffe27'
NON_CIRCULATING_ID = '52d7b849-b6d8-4fb3-b2ab-a9b0eb41b6fd'

# inspect individual rules with translate_rule_criteria(rule, uuid_map)
rules = CirculationRules::PolicyService.default_rules
uuid_map = CSV.read('uuids.csv').to_h

# Profile the two different circ rule indexing strategies
linear_index = CirculationRules::PolicyService.new(index_class: CirculationRules::LinearIndex, rules: rules)
inverted_index = CirculationRules::PolicyService.new(index_class: CirculationRules::InvertedIndex, rules: rules)

green_stacks_circulating_book = {
  'material-type' => BOOK_ID,
  'loan-type' => CAN_CIRCULATE_ID,
  'location-institution' => SU_ID,
  'location-campus' => SUL_ID,
  'location-library' => GREEN_ID,
  'location-location' => GRE_STACKS_ID
}

sal3_page_mu_score = {
  'material-type' => SCORE_ID,
  'loan-type' => CAN_CIRCULATE_ID,
  'location-institution' => SU_ID,
  'location-campus' => SUL_ID,
  'location-library' => SAL3_ID,
  'location-location' => SAL3_PAGE_MU_ID
}

lane_edoc = {
  'material-type' => PERIODICAL_ID,
  'loan-type' => NON_CIRCULATING_ID,
  'location-institution' => SU_ID,
  'location-campus' => MED_ID,
  'location-library' => LANE_ID,
  'location-location' => LANE_EDOC_ID
}

ars_folio_thing = {
  'material-type' => PERIODICAL_ID,
  'loan-type' => NON_CIRCULATING_ID,
  'location-institution' => SU_ID,
  'location-campus' => SUL_ID,
  'location-library' => ARS_ID,
  'location-location' => ARS_FOLIO_ID
}

def timed_search(service, item, uuid_map)
  puts format("Searching for item with criteria: %s", translate_item_criteria(item, uuid_map))
  result = nil
  time = Benchmark.realtime do
    result = service.item_policies(item)
  end
  puts format("Rule: %s", translate_rule_criteria(result, uuid_map))
  puts "Result has priority #{result.priority}; appears on line #{result.line}"
  puts format("Search took %0.5f seconds\n\n", time)
end

def translate_item_criteria(item, uuid_map)
  item.as_json.filter_map do |_criterium, value|
    uuid_map[value] || value
  end.join('; ')
end

def translate_rule_criteria(rule, uuid_map)
  output = rule.as_json
  output['criteria'].filter_map do |_criterium, values|
    # next if criterium == 'group'

    fmt_values = case values
                 when Hash
                   op, contents = values.first
                   contents.map { |value| uuid_map[value] || value }.join(" #{op} ")
                 else
                   uuid_map[values] || values
                 end

    fmt_values.to_s
  end.join("; ")
end

[linear_index, inverted_index].each do |service|
  puts "\nTesting with #{service.index_class}\n\n"
  timed_search(service, green_stacks_circulating_book, uuid_map)
  timed_search(service, sal3_page_mu_score, uuid_map)
  timed_search(service, lane_edoc, uuid_map)
  timed_search(service, ars_folio_thing, uuid_map)
end

# uncomment require for ruby-prof above to use these

# inverted_profile = RubyProf::Profile.profile do
#   100.times do
#     inverted_index.item_policies(green_stacks_circulating_book)
#     inverted_index.item_policies(sal3_page_mu_score)
#     inverted_index.item_policies(lane_edoc)
#   end
# end

# printer = RubyProf::GraphPrinter.new(linear_profile)
# printer.print(File.open('linear_index_profile.txt', 'w'))

# printer = RubyProf::GraphPrinter.new(inverted_profile)
# printer.print(File.open('inverted_index_profile.txt', 'w'))

hierarchical_index.rb

# frozen_string_literal: true

module CirculationRules
  # A simple rule index that iterates through rules to find the first match
  class HierarchicalIndex
    def initialize(rules)
      @rules = rules
    end

    # Iterate through the rules in order, returning the first one that matches
    def search(search_criteria)
      criteria_indexes = indexed_order.map do |k|
        [search_criteria[k], '*']
      end.reduce(&:product).map(&:flatten)

      i = criteria_indexes.map do |v|
        index[v] || 9999999
      end.min

      @rules[i] || @rules.last
    end

    def index
      @index ||= begin
        h = {}
        @rules.each_with_index do |rule, i|
          index_values(rule.criteria).each do |v|
            h[v] ||= i
          end
        end

        h
      end
    end

    def index_values(criteria)
      sorted_values = indexed_order.map do |k|
        values = criteria[k]

        case values
        when Hash
          values[:or] || []
        when String
          [values]
        else
          values
        end
      end

      sorted_values.reduce(&:product).map(&:flatten)
    end

    def indexed_order
      CirculationRules::Transform::INVERTED_CRITERIA_TYPES.keys - ['group']
    end
  end
end

inverted_index.rb

# frozen_string_literal: true

module CirculationRules
  # An index for searching circulation rules
  class InvertedIndex
    attr_reader :rules

    # We don't index the 'group' criteria type
    INDEXED_CRITERIA = Transform::INVERTED_CRITERIA_TYPES.keys.excluding('group').freeze

    def initialize(rules = [])
      @rules = Set[]
      @pos_indices = init_indices
      @neg_indices = init_indices

      # If rules don't have a priority, assign them one based on their order
      rules.each_with_index do |rule, index|
        rule.priority ||= index
        add_rule rule
      end
    end

    # Find the highest-priority rule that matches the given criteria
    def search(criteria)
      # Find the rules that match *all* positive criteria (intersection) and the
      # rules that match *any* negative criteria (union)
      pos_results, neg_results = criteria.reduce([@rules, Set[]]) do |(pos, neg), (criterium, value)|
        raise ArgumentError, "invalid rule criterium:  #{criterium}" unless @pos_indices.key? criterium

        [
          pos & (@pos_indices[criterium].fetch(value, Set[]) | @pos_indices[criterium].fetch('*', Set[])),
          neg | (@neg_indices[criterium].fetch(value, nil) || Set[])
        ]
      end

      # Eliminate any rules that match a negative criteria and find the highest
      # priority rule remaining, or use the fallback rule if none
      (pos_results - neg_results).to_a.min || fallback_rule
    end

    private

    # Index a rule by its criteria
    def add_rule(rule)
      @rules << rule

      rule.criteria.each do |criterium, values|
        # Ignore the 'group' criteria type
        next if criterium == 'group'

        # Protect against other invalid criteria types
        raise ArgumentError, "invalid rule criterium: #{criterium}" unless INDEXED_CRITERIA.include? criterium

        # Treat single values as an 'or' with one value
        values = { or: [values] } unless values.is_a?(Hash)

        # Determine which set of indexes to add the values to
        operator, values = values.first
        index_set = case operator
                    when :or
                      @pos_indices
                    when :not
                      @neg_indices
                    else
                      raise ArgumentError, "invalid rule operator: #{operator}"
                    end

        # Index the rule by each value for the criterium
        values.each do |value|
          index_set[criterium][value] ||= Set[]
          index_set[criterium][value] << rule
        end
      end
    end

    # Create a set of indexes for each criteria type
    def init_indices
      INDEXED_CRITERIA.index_with { |_criterium| {} }.with_indifferent_access
    end

    # The lowest-priority rule is the fallback rule
    def fallback_rule
      @fallback_rule ||= @rules.to_a.max
    end
  end
end

linear_index.rb

# frozen_string_literal: true

module CirculationRules
  # A simple rule index that iterates through rules to find the first match
  class LinearIndex
    def initialize(rules)
      @rules = []

      # If rules don't have a priority, assign them one based on their order
      rules.each_with_index do |rule, index|
        rule.priority ||= index
        @rules << rule
      end
    end

    # Iterate through the rules in order, returning the first one that matches
    def search(search_criteria)
      @rules.find do |rule|
        # Skip rules that have negative criteria that match
        return false if rule.criteria.any? do |criterium, values|
          values.is_a?(Hash) && values[:not]&.any?(search_criteria[criterium])
        end

        # Return the first rule that matches all positive criteria
        rule.criteria.all? do |criterium, values|
          values = case values
                   when Hash
                     values[:or] || []
                   when String
                     [values]
                   else
                     values
                   end

          # Always treat 'group' criterium (ignored) and the wildcard as matching
          criterium == 'group' || values == ['*'] || values.any?(search_criteria[criterium])
        end
      end || @rules.max
    end
  end
end

uuids.csv