best_choice 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2e6e75982850ff066a696cdb4b59c075d3842719
+  data.tar.gz: d85afa3104d948cc738f4e9481d60a6072e86e2f
+SHA512:
+  metadata.gz: a7b1352cae375f7465245be07ef977320c048cec1f053cc85f63106470b85b71b141f8c1acb2786992c259cfd5cdfc79bedd3469fe0e93fde72c15b6c6ca398a
+  data.tar.gz: 10dd60b5a74bcca468a1507b33f69b583e719d58a9ae43f094824b589882f61367777f1cfdaf315cd5e3eb185b5271b5598e9abbeb5302777e5c56a6d5802ec3

data/README.rdoc

@@ -0,0 +1,3 @@
+= BestChoice
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BestChoice'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/best_choice.rb

@@ -0,0 +1,26 @@
+require './lib/best_choice/algorithm'
+require './lib/best_choice/selector'
+
+require './lib/best_choice/algorithms/epsilon_greedy'
+require './lib/best_choice/storage/redis_hash'
+
+require './lib/best_choice/selectors/greedy_redis'
+
+
+module BestChoice
+  
+  module_function
+  
+  def for selector_name, selector: default_selector, **opts
+    selector.new(selector_name, opts)
+  end
+  
+  def default_selector
+    @default_selector ||= Selectors::GreedyRedis
+  end
+  
+  def default_selector= selector
+    @default_selector = selector
+  end
+
+end

data/lib/best_choice/algorithm.rb

@@ -0,0 +1,65 @@
+module BestChoice
+
+  class Algorithm
+
+    class NoAvailableOptionsError < StandardError ; end
+    
+    
+    def initialize
+      raise NotImplementedError.new 'Expected subclass to implement'
+    end
+
+    def pick_option stats
+      unless stats.kind_of? Array
+        raise ArgumentError.new 'Expected an array'
+      end
+
+      case stats.length
+      when 0
+        raise NoAvailableOptionsError
+      when 1
+        stats.first
+      else
+        do_actual_pick stats
+      end
+    end
+
+
+    protected
+    
+    def do_actual_pick stats=[]
+      raise NotImplementedError.new 'Expected subclass to implement'
+    end
+    
+    def choice_rate option_data
+      display_count = option_data[:display_count]
+      success_count = option_data[:success_count]
+
+      unless is_non_negative_int?(display_count)
+        raise ArgumentError.new "Invalid display_count: #{display_count.inspect}"
+      end
+      unless is_non_negative_int?(success_count)
+        raise ArgumentError.new "Invalid success_count: #{success_count.inspect}"
+      end
+      if option_data[:success_count] > option_data[:display_count]
+        raise ArgumentError.new "success_count: #{success_count} " \
+                                "higher than display_count: #{display_count}"
+      end
+
+      if option_data[:display_count] == 0
+        100
+      else
+        option_data[:success_count].to_f / option_data[:display_count]
+      end
+    end
+
+
+    private
+    
+    def is_non_negative_int? arg
+      arg.kind_of?(Integer) && arg >= 0
+    end
+
+  end
+
+end

data/lib/best_choice/algorithms/epsilon_greedy.rb

@@ -0,0 +1,31 @@
+module BestChoice 
+  module Algorithms
+
+    class EpsilonGreedy < BestChoice::Algorithm
+
+      DEFAULT_RANDOMNESS_FACTOR = 10
+
+
+      def initialize randomness_factor: DEFAULT_RANDOMNESS_FACTOR
+        unless randomness_factor.between? 0, 100
+          raise ArgumentError.new "Invalid randomness_factor: #{randomness_factor}"
+        end
+        @randomness_factor = randomness_factor
+      end
+
+
+      protected
+      
+      def do_actual_pick stats
+        options_by_rate = stats.sort_by{ |o| choice_rate(o) }
+        if rand(100)+1 > @randomness_factor
+          options_by_rate.last
+        else
+          options_by_rate[0..-2].sample
+        end
+      end
+      
+    end
+
+  end
+end

data/lib/best_choice/rails_util.rb

@@ -0,0 +1,76 @@
+require 'set'
+
+module BestChoice
+  module RailsUtil
+
+    extend ActiveSupport::Concern
+
+
+    included do
+      before_filter do
+        RailsUtil.instance_variable_set('@session', session)
+      end
+         
+      after_filter do
+        if @_best_choice_selectors
+          RailsUtil.best_choice_picks = @_best_choice_selectors.inject(
+            RailsUtil.best_choice_picks) do |picks, (_, selector)|
+              picks.merge!(selector.name => selector.picked_option)
+            end
+        end
+      end
+    end
+    
+    
+    module SelectorExtension
+      
+      def self.extended klass
+        klass.class_eval do
+          define_method :mark_success do
+            if pick = RailsUtil.best_choice_picks[name]
+              super pick
+              RailsUtil.best_choice_picks.delete name
+            end
+          end
+        end
+      end
+      
+    end
+    
+    
+    # -------------------------------------------------
+    # Module functions
+    
+    def self.best_choice_picks
+      @session[:_best_choice_picks] ||= {}
+    end
+    
+    def self.best_choice_picks= picked_options
+      @session[:_best_choice_picks] = picked_options
+    end
+    
+
+    # -------------------------------------------------
+    # Methods visible to Rails controller
+    
+    def best_choice_for s_name, selector: BestChoice.default_selector, **opts
+      s = selector.new s_name, opts
+      s.extend SelectorExtension
+      best_choice_selector_register s
+      s.picked_option = RailsUtil.best_choice_picks[s_name]
+      s
+    end
+    
+    
+    private
+    
+    # Save the test data in the instance variable, so that
+    # it can be later retrieved in the after_filter.
+    #
+    def best_choice_selector_register selector
+      @_best_choice_selectors ||= {}
+      @_best_choice_selectors[selector.name] ||= selector
+    end
+    
+  end
+end

data/lib/best_choice/selector.rb

@@ -0,0 +1,51 @@
+module BestChoice
+
+  class Selector
+    
+    attr_reader :name
+    attr_writer :picked_option
+    
+
+    def initialize name, storage:, algorithm:, **opts
+      @name      = name
+      @storage   = storage.new(name)
+      @algorithm = algorithm.new(opts)
+    end
+
+    def option option
+      @storage.add option
+      
+      if should_display? option
+        mark_display option
+        yield
+      end
+    end
+
+    def mark_success option
+      @marked_success ||= !!@storage.success_count_incr(option)
+    end
+    
+    def picked_option
+      @picked_option ||= @algorithm.pick_option(@storage.stats)[:name]
+    end
+    
+    def equal? selector
+      self.class == selector.class && name == selector.name
+    end
+    
+    alias :== :equal?
+
+
+    private
+
+    def should_display? option
+      picked_option == option
+    end
+
+    def mark_display option
+      @marked_display ||= !!@storage.display_count_incr(option)
+    end
+
+  end
+
+end

data/lib/best_choice/selectors/greedy_redis.rb

@@ -0,0 +1,16 @@
+module BestChoice
+  module Selectors
+
+    class GreedyRedis < BestChoice::Selector
+
+      def initialize name, opts={}
+        super name, opts.merge({
+                storage:   Storage::RedisHash,
+                algorithm: Algorithms::EpsilonGreedy
+              })
+      end
+
+    end
+    
+  end
+end

data/lib/best_choice/storage/redis_hash.rb

@@ -0,0 +1,71 @@
+require 'json'
+require 'redis-objects'
+
+module BestChoice
+  module Storage
+    
+    class RedisHash
+
+      def initialize storage_name
+        @hash_key = Redis::HashKey.new "best_choice:#{storage_name}"
+      end
+
+      def options
+        if @hash_key[:options]
+          JSON.parse @hash_key[:options]
+        else
+          []
+        end
+      end
+
+      def add option
+        unless has_option? option
+          @hash_key[:options] = (options << option).to_json
+        end
+      end
+
+      def display_count_incr option
+        @hash_key.incr display_count_key(option)
+      end
+
+      def success_count_incr option
+        @hash_key.incr success_count_key(option)
+      end
+
+      def stats
+        options.inject([]) { |memo, option|
+          memo << {
+            name:          option,
+            display_count: display_count(option),
+            success_count: success_count(option)
+          }
+        }
+      end
+
+
+      private
+
+      def has_option? option
+        !!options.index(option)
+      end
+
+      def display_count option
+        (@hash_key[display_count_key(option)] || 0).to_i
+      end
+
+      def success_count option
+        (@hash_key[success_count_key(option)] || 0).to_i
+      end
+
+      def display_count_key option
+        "display_#{option}"
+      end
+
+      def success_count_key option
+        "success_#{option}"
+      end
+
+    end
+
+  end
+end

data/lib/best_choice/version.rb

@@ -0,0 +1,5 @@
+module BestChoice
+  
+  VERSION = '0.0.1'
+  
+end

data/test/algorithm_test.rb

@@ -0,0 +1,40 @@
+require 'test_helper'
+
+class AlgorithmTest < ActiveSupport::TestCase
+
+  def setup
+    @algorithm = DummyAlgorithm.new
+  end
+
+  test 'pick_option' do
+    # Empty stats
+    assert_raises(BestChoice::Algorithm::NoAvailableOptionsError) do
+      @algorithm.pick_option []
+    end
+
+    # One option
+    assert_equal 'an_option', @algorithm.pick_option(['an_option'])
+
+    # Multiple options
+    options = ['a','b']
+    mock(@algorithm).do_actual_pick options
+    @algorithm.pick_option options
+  end
+
+  test 'the class itself does not implement do_actual_pick method' do
+    assert_raises(NotImplementedError) do
+      @algorithm.send :do_actual_pick
+    end
+  end
+
+  test 'is_non_negative_int?' do
+    [ nil, '', 'a', -1, -0.01, 0.1, 12.23 ].each do |arg|
+      refute @algorithm.send :is_non_negative_int?, arg
+    end
+
+    [ 0, 1 ].each do |arg|
+      assert @algorithm.send :is_non_negative_int?, arg
+    end
+  end
+
+end

data/test/algorithms/epsilon_greedy_test.rb

@@ -0,0 +1,152 @@
+require 'test_helper'
+
+class EpsilonGreedyTest < ActiveSupport::TestCase
+
+  def setup
+    @algorithm = BestChoice::Algorithms::EpsilonGreedy.new
+  end
+
+  test 'randomness_factor validation' do
+    invalid_values = [ -1, -0.1, 100.5, 101 ]
+    invalid_values.each { |val|
+      assert_raises(ArgumentError) do
+        BestChoice::Algorithms::EpsilonGreedy.new(randomness_factor: val)
+      end
+    }
+
+    valid_values = [ 0.1, 1, 100 ]
+    valid_values.each { |val|
+      assert_nothing_raised do
+        BestChoice::Algorithms::EpsilonGreedy.new(randomness_factor: val)
+      end
+    }
+  end
+
+  test 'choice_rate' do
+    invalid_data = [
+      { display_count: nil , success_count: 0 },
+      { display_count: 1   , success_count: nil },
+      { display_count: 0   , success_count: -1 },
+      { display_count: -1  , success_count: -2 },
+      { display_count: 1.0 , success_count: 0 },
+      { display_count: 1.1 , success_count: 0 },
+      { display_count: 1   , success_count: 2 },
+    ]
+
+    invalid_data.each { |data| 
+      assert_raises(ArgumentError) do
+        @algorithm.send :choice_rate, data
+      end
+    }
+
+    assert_equal 100, 
+      @algorithm.send(:choice_rate, { display_count: 0, success_count: 0 })
+    assert_equal 0.5,
+      @algorithm.send(:choice_rate, { display_count: 6, success_count: 3 })
+    assert_equal 2/3.to_f,
+      @algorithm.send(:choice_rate, { display_count: 6, success_count: 4 })
+  end
+
+  test 'actual picking via pick_option' do
+
+    # --------------------------------------------------------
+    # Non-random version
+    # --------------------------------------------------------
+
+    non_random_algorithm = BestChoice::Algorithms::EpsilonGreedy.new(
+                            randomness_factor: 0)
+
+    # The first option should be always chosen.
+    stats = [
+      { display_count: 2 , success_count: 2 },
+      { display_count: 2 , success_count: 1 },
+      { display_count: 1 , success_count: 0 }
+    ]
+
+    10.times {
+      assert_equal stats[0], non_random_algorithm.pick_option(stats)
+    }
+
+    # If the second option has the same success_count as the first one, but
+    # a higher display_count, the first option should still be chosen.
+    #
+    stats = [
+      { display_count: 2 , success_count: 2 },
+      { display_count: 3 , success_count: 2 },
+      { display_count: 1 , success_count: 0 }
+    ]
+
+    10.times {
+      assert_equal stats[0], non_random_algorithm.pick_option(stats)
+    }
+
+    # Even if the ratio of success_count to display_count of the first option
+    # drops to the ratio of the second option, it would still be preferred
+    # if its display_count is higher.
+    #
+    stats = [
+      { display_count: 6 , success_count: 4 },
+      { display_count: 3 , success_count: 2 },
+      { display_count: 1 , success_count: 0 }
+    ]
+
+    10.times {
+      assert_equal stats[0], non_random_algorithm.pick_option(stats)
+    }
+
+    # Changing the ratio in favor of the second option, should make it the
+    # new optimal choice.
+    #
+    stats = [
+      { display_count: 6 , success_count: 3 },
+      { display_count: 4 , success_count: 3 },
+      { display_count: 1 , success_count: 0 }
+    ]
+
+    10.times {
+      assert_equal stats[1], non_random_algorithm.pick_option(stats)
+    }
+
+    # --------------------------------------------------------
+    # 100% random version
+    # --------------------------------------------------------
+
+    totally_random_algorithm = BestChoice::Algorithms::EpsilonGreedy.new(
+                                randomness_factor: 100)
+
+    stats = [
+      { display_count: 5, success_count: 2 },
+      { display_count: 5, success_count: 1 },
+      { display_count: 2, success_count: 0 }
+    ]
+
+    # The probability of choosing each non-optimal option should be equal.
+    #
+    chosen_options = []
+    20.times {
+      chosen_options << totally_random_algorithm.pick_option(stats)
+    }
+    assert_equal stats[1..2],
+                 chosen_options.uniq.sort_by{ |d| d[:success_count] }.reverse
+
+    # --------------------------------------------------------
+    # Default version
+    # --------------------------------------------------------
+
+    stats = [
+      { display_count: 5, success_count: 2 },
+      { display_count: 5, success_count: 1 }
+    ]
+
+    # The second option should be chosen only in ~10% of cases.
+    #
+    chosen_options = []
+    1000.times { chosen_options << @algorithm.pick_option(stats) }
+
+    counts = Hash.new 0
+    chosen_options.each { |opt| counts[opt] += 1 }
+
+    assert counts[stats[1]] > 80   # Leave some margin.
+  end
+
+end