bandido 0.0.6

data/README.rdoc

@@ -0,0 +1,77 @@
+= bandit
+
+Bandit is a multi-armed bandit optimization framework for Rails.  It provides an alternative to A/B testing in Rails.  For background and a comparison with A/B testing, see the whybandit.rdoc document or the blog post here[http://findingscience.com/rails/vanity/statistics/testing/2011/11/12/bandit:-a-b-testing-alternative-for-rails.html].
+
+= Installation
+First, add the following to your Gemfile in your Rails 3 app:
+
+    gem 'bandit'
+
+Then, run the following:
+
+    bundle install
+    rails generate bandit:install
+
+You can then edit the bandit.yml file in your config directory to set your storage and player parameters.  Redis, memcache, and memory storage options are available.  Memory storage should only be used for testing.
+
+See the file players.rdoc for information about available players.
+
+== Configuration
+To set up an experiment, add it either somewhere in your code or in the bandit initializer.  Creating an experiment is simple:
+
+    Bandit::Experiment.create(:click_test) { |exp|
+      exp.alternatives = [ 20, 30, 40 ]
+      exp.title = "Click Test"
+      exp.description = "A test of clicks on purchase page with varying link sizes."
+    }
+
+
+== View
+To get an alternative (per viewer, based on cookies):
+
+    <%= bandit_choose :click_test %>
+
+For instance, in a link:
+
+    <%= link_to "new purchase", new_purchase_path, :style => "font-size: #{bandit_choose(:click_test)}px;" %>
+
+You can force a particular alternative by adding a query parameter named "bandit_<experiment name>" and setting it's value to the alternative you want.  For instance, given the above experiment in the configuration example:
+
+    http://<yourhost>/<path>?bandit_click_test=40
+
+will then force the alternative to be "40".
+
+== Controller
+To track a conversion in your controller:
+
+   bandit_convert! :click_test
+
+= Dashboard
+
+    rails generate bandit:dashboard
+
+Then, add the following to your config/routes.rb file:
+
+    resources :bandit
+
+To see a dashboard with relevant information, go to:
+
+    http://<yourhost>/bandit
+
+= Tests
+To run tests:
+
+    rake test_memory
+    rake test_memcache
+    rake test_redis
+
+To produce fake data for the past week, first create an experiment definition.  Then, run the following rake task:
+
+    rake bandit:populate_data[<experiment_name>]
+
+For instance, to generate a week's worth of fake data for the click_test above:
+
+    rake bandit:populate_data[click_test]
+
+= Fault Tolerance
+If the storage mechanism fails, then Bandit will automatically switch to in memory storage.  It will then check every 5 minutes after that to see if the original storage mechanism is back up.  If you have distributed front ends then each front end will continue to optimize (based on the in memory storage), but this optimization will be inefficient compared to shared storage among all front ends.

data/Rakefile

@@ -0,0 +1,34 @@
+require 'bundler/gem_tasks'
+require 'rdoc/task'
+require 'rake/testtask'
+
+desc "Create documentation"
+Rake::RDocTask.new("doc") { |rdoc|
+  rdoc.title = "bandit - A multi-armed bandit optmization framework for Rails"
+  rdoc.rdoc_dir = 'docs'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('players.rdoc')
+  rdoc.rdoc_files.include('whybandit.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+desc "Run all unit tests with memory storage"
+Rake::TestTask.new("test_memory") { |t|
+  t.libs << "lib"
+  t.test_files = FileList['test/memory_*.rb']
+  t.verbose = true
+}
+
+desc "Run all unit tests with memcache storage"
+Rake::TestTask.new("test_memcache") { |t|
+  t.libs << "lib"
+  t.test_files = FileList['test/memcache_*.rb']
+  t.verbose = true
+}
+
+desc "Run all unit tests with redis storage"
+Rake::TestTask.new("test_redis") { |t|
+  t.libs << "lib"
+  t.test_files = FileList['test/redis_*.rb']
+  t.verbose = true
+}

data/bandit.gemspec

@@ -0,0 +1,22 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "bandit/version"
+
+Gem::Specification.new do |s|
+  s.name        = "bandit"
+  s.version     = Bandit::VERSION
+  s.authors     = ["Brian Muller"]
+  s.email       = ["brian.muller@livingsocial.com"]
+  s.homepage    = "https://github.com/bmuller/bandit"
+  s.summary     = "Multi-armed bandit testing in rails"
+  s.description = "Bandit provides a way to do multi-armed bandit optimization of alternatives in a rails website"
+
+  s.rubyforge_project = "bandit"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_dependency("rails", ">= 3.0.5")
+  s.add_dependency("redis", "= 2.2.2")
+  s.add_development_dependency('rdoc')
+end

data/lib/bandit/config.rb

@@ -0,0 +1,33 @@
+module Bandit
+
+  class Config
+    def self.required_fields
+      [:storage, :player]
+    end
+    
+    # storage should be name of storage engine
+    attr_accessor :storage
+
+    # storage_config should be hash of storage config values
+    attr_accessor :storage_config
+
+    # player should be name of player
+    attr_accessor :player
+
+    # player_config should be hash of player config values
+    attr_accessor :player_config
+
+    def check!
+      self.class.required_fields.each do |required_field|
+        unless send(required_field)
+          raise MissingConfigurationError, "#{required_field} must be set"
+        end
+      end
+
+      @storage_config ||= {}
+      @player_config ||= {}
+    end
+
+  end
+
+end

data/lib/bandit/date_hour.rb

@@ -0,0 +1,82 @@
+require 'date'
+
+module Bandit
+
+  class DateHour
+    attr_accessor :date, :hour
+
+    def initialize(date, hour)
+      @date = date
+      @hour = hour
+    end
+
+    def self.now
+      DateHour.new Date.today, Time.now.hour
+    end
+
+    def upto(other)
+      n = DateHour.new(@date, @hour)
+      while n <= other
+        yield n
+        n += 1
+      end
+    end
+
+    # given a block that is called w/ each DateHour for a day, inject over all DateHours
+    def self.date_inject(date, initial=0)
+      DateHour.new(date, 0).upto(DateHour.new(date, 23)) { |dh|
+        initial = yield initial, dh
+      }
+      initial
+    end
+
+    def +(hours)
+      (to_time + (hours * 3600)).to_date_hour
+    end
+
+    def ==(other)
+      @date == other.date and @hour == other.hour
+    end
+
+    def <(other)
+      @date < other.date or (@date == other.date and @hour < other.hour)
+    end
+
+    def >(other)
+      @date > other.date or (@date == other.date and @hour > other.hour)
+    end
+
+    def >=(other)
+      self > other or self == other
+    end
+
+    def <=(other)
+      self < other or self == other
+    end
+
+    def to_time
+      Time.mktime year, month, day, hour, 0
+    end
+
+    def to_s
+      "#{@date.to_s} #{@hour}:00:00"
+    end
+
+    def to_i
+      to_time.to_i
+    end
+
+    def year
+      @date.year
+    end
+
+    def month
+      @date.month
+    end
+
+    def day
+      @date.day
+    end
+  end
+
+end

data/lib/bandit/exceptions.rb

@@ -0,0 +1,10 @@
+module Bandit
+  class UnknownStorageEngineError < RuntimeError
+  end
+
+  class UnknownPlayerEngineError < RuntimeError
+  end
+
+  class MissingConfigurationError < ArgumentError
+  end
+end

data/lib/bandit/experiment.rb

@@ -0,0 +1,63 @@
+module Bandit
+  class Experiment
+    attr_accessor :name, :title, :description, :alternatives
+    @@instances = []
+
+    def self.create(name)
+      e = Experiment.new(:name => name)
+      yield e
+      e.validate!
+      e
+    end
+
+    def initialize(args=nil)
+      args.each { |k,v| send "#{k}=", v } unless args.nil?
+      @@instances << self
+      @storage = Bandit.storage
+    end
+
+    def self.instances
+      @@instances
+    end
+
+    def choose(default=nil)
+      if default && alternatives.include?(default)
+        alt = default
+      else
+        alt = Bandit.player.choose_alternative(self)
+        @storage.incr_participants(self, alt)
+      end
+      alt
+    end
+
+    def convert!(alt, count=1)
+      @storage.incr_conversions(self, alt, count)
+    end
+
+    def validate!
+      [:title, :alternatives].each { |field|        
+        unless send(field)
+          raise MissingConfigurationError, "#{field} must be set in experiment #{name}"
+        end
+      }
+    end
+
+    def conversion_count(alt, date_hour=nil)
+      @storage.conversion_count(self, alt, date_hour)
+    end
+
+    def participant_count(alt, date_hour=nil)
+      @storage.participant_count(self, alt, date_hour)
+    end
+
+    def conversion_rate(alt)
+      pcount = participant_count(alt)
+      ccount = conversion_count(alt)
+      (pcount == 0 or ccount == 0) ? 0 : (ccount.to_f / pcount.to_f * 100.0)
+    end
+
+    def alternative_start(alt)
+      @storage.alternative_start_time(self, alt)
+    end
+  end
+end

data/lib/bandit/extensions/array.rb

@@ -0,0 +1,3 @@
+class Array
+  alias_method :sample, :choice unless method_defined?(:sample)
+end

data/lib/bandit/extensions/controller_concerns.rb

@@ -0,0 +1,33 @@
+require 'active_support/concern'
+
+module Bandit
+  module ControllerConcerns
+    extend ActiveSupport::Concern
+  
+    module ClassMethods
+      
+    end
+
+    module InstanceMethods
+      def bandit_convert!(exp, alt=nil, count=1)
+        cookiename = "bandit_#{exp}".intern
+        alt ||= cookies.signed[cookiename]
+        unless alt.nil?
+          Bandit.get_experiment(exp).convert!(alt, count)
+          cookies.delete(cookiename)
+        end
+      end
+
+      def bandit_final_convert!(exp, alt=nil, count=1)
+        cookiename = "bandit_#{exp}".intern
+        cookiename_converted = "bandit_#{exp}_converted".intern
+        alt ||= cookies.signed[cookiename]
+        unless alt.nil? or cookies.signed[cookiename_converted]
+          cookies.permanent.signed[cookiename_converted] = "true"
+          Bandit.get_experiment(exp).convert!(alt, count)
+        end
+      end
+    end
+
+  end
+end

data/lib/bandit/extensions/string.rb

@@ -0,0 +1,5 @@
+class String
+  def numeric?
+    true if Integer(self) rescue false
+  end
+end

data/lib/bandit/extensions/time.rb

@@ -0,0 +1,5 @@
+class Time
+  def to_date_hour
+    Bandit::DateHour.new Date.new(year, month, day), hour
+  end
+end

data/lib/bandit/extensions/view_concerns.rb

@@ -0,0 +1,40 @@
+require 'active_support/concern'
+
+module Bandit
+  module ViewConcerns
+    extend ActiveSupport::Concern
+  
+    module ClassMethods
+      
+    end
+
+    module InstanceMethods
+      def bandit_choose(exp)
+        name = "bandit_#{exp}".intern
+
+        # choose url param with preference
+        value = params[name].nil? ? cookies.signed[name] : params[name]
+
+        # choose with default, and set cookie
+        cookies.signed[name] = Bandit.get_experiment(exp).choose(value)
+      end
+
+      def bandit_sticky_choose(exp)
+        name = "bandit_#{exp}".intern
+
+        # choose url param with preference
+        value = params[name].nil? ? cookies.signed[name] : params[name]
+
+        # sticky choice may outlast a given alternative
+        alternative = if Bandit.get_experiment(exp).alternatives.include?(value)
+                        value
+                      else
+                        Bandit.get_experiment(exp).choose(value)
+                      end
+
+        # re-set cookie
+        cookies.permanent.signed[name] = alternative
+      end
+    end
+  end
+end

data/lib/bandit/memoizable.rb

@@ -0,0 +1,32 @@
+module Bandit
+  module Memoizable
+    # remember a block for some time (60 seconds by default)
+    def memoize(key, time=60)
+      @memoized ||= {}
+      @memoized_times ||= {}
+      now = Time.now.to_i
+      if not @memoized.has_key?(key) or now > @memoized_times[key]
+        @memoized[key] = yield
+        @memoized_times[key] = now + time
+      end
+      @memoized[key]
+    end
+  
+    module ClassMethods
+      def memoize_method(method, time=60)
+        original_method = "unmemoized_#{method}_#{Time.now.to_i}"
+        alias_method original_method, method
+        module_eval(<<-EVAL, __FILE__, __LINE__)
+        def #{method}(*args, &block)
+          memoize(:#{original_method}, #{time}) { send(:#{original_method}, *args, &block) }
+        end
+        EVAL
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+  end
+end

data/lib/bandit/players/base.rb

@@ -0,0 +1,37 @@
+module Bandit
+  class BasePlayer
+    def self.get_player(name, config)
+      config ||= {}
+
+      case name 
+      when :round_robin then RoundRobinPlayer.new(config)
+      when :epsilon_greedy then EpsilonGreedyPlayer.new(config)
+      else raise UnknownPlayerEngineError, "#{name} not a known player type"
+      end
+    end
+
+    def initialize(config)
+      @config = config
+      @storage = Bandit.storage
+    end
+    
+    def choose_alternative(experiment)
+      # return the alternative that should be chosen
+      raise NotImplementedError
+    end
+
+    # store state variable by name
+    def set(name, value)
+      @storage.player_state_set(self, name, value)
+    end
+
+    # get state variable by name
+    def get(name)
+      @storage.player_state_get(self, name)
+    end
+
+    def name
+      self.class.to_s
+    end
+  end
+end

data/lib/bandit/players/epsilon_greedy.rb

@@ -0,0 +1,32 @@
+module Bandit
+  class EpsilonGreedyPlayer < BasePlayer
+    include Memoizable
+
+    def choose_alternative(experiment)
+      epsilon = @config['epsilon'].to_f || 0.1
+
+      # choose best with probability of 1-epsilon
+      if rand <= (1-epsilon)
+        best_alternative(experiment)
+      else
+        experiment.alternatives.sample
+      end
+    end
+
+    def best_alternative(experiment)
+      memoize(experiment.name) { 
+        best = nil
+        best_rate = nil
+        experiment.alternatives.each { |alt|
+          rate = experiment.conversion_rate(alt)
+          if best_rate.nil? or rate > best_rate
+            best = alt
+            best_rate = rate
+          end
+        }
+        best
+      }
+    end
+    
+  end
+end

data/lib/bandit/players/round_robin.rb

@@ -0,0 +1,7 @@
+module Bandit
+  class RoundRobinPlayer < BasePlayer
+    def choose_alternative(experiment)
+      experiment.alternatives.sample
+    end
+  end
+end

data/lib/bandit/storage/base.rb

@@ -0,0 +1,134 @@
+# store total count for this alternative
+# conversions:<experiment>:<alternative> = count
+# participants:<experiment>:<alternative> = count
+
+# store first time an alternative is used
+# altstart:<experiment>:<alternative> = timestamp
+
+# store total count for this alternative per day and hour
+# conversions:<experiment>:<alternative>:<date>:<hour> = count
+# participants:<experiment>:<alternative>:<date>:<hour> = count
+
+# every so often store current epsilon
+# state:<experiment>:<player>:epsilon = 0.1
+
+module Bandit
+  class BaseStorage
+    def self.get_storage(name, config)
+      config ||= {}
+
+      case name 
+      when :memory then MemoryStorage.new(config)
+      when :memcache then MemCacheStorage.new(config)
+      when :redis then RedisStorage.new(config)
+      else raise UnknownStorageEngineError, "#{name} not a known storage method"
+      end
+    end
+
+    # increment key by count
+    def incr(key, count)
+      raise NotImplementedError
+    end
+
+    # initialize key if not set
+    def init(key, value)
+      raise NotImplementedError
+    end
+
+    # get key if exists, otherwise 0
+    def get(key, default=0)
+      raise NotImplementedError
+    end
+
+    # set key with value, regardless of whether it is set or not
+    def set(key, value)
+      raise NotImplementedError
+    end
+
+    # clear all stored values
+    def clear!
+      raise NotImplementedError
+    end
+
+    def incr_participants(experiment, alternative, count=1, date_hour=nil)      
+      date_hour ||= DateHour.now
+
+      # initialize first start time for alternative if we haven't inited yet
+      init alt_started_key(experiment, alternative), date_hour.to_i
+      
+      # increment total count and per hour count
+      incr part_key(experiment, alternative), count
+      incr part_key(experiment, alternative, date_hour), count
+    end
+    
+    def incr_conversions(experiment, alternative, count=1, date_hour=nil)
+      # increment total count and per hour count
+      incr conv_key(experiment, alternative), count
+      incr conv_key(experiment, alternative, date_hour || DateHour.now), count
+    end
+
+    # if date_hour isn't specified, get total count
+    # if date_hour is specified, return count for DateHour
+    def participant_count(experiment, alternative, date_hour=nil)
+      get part_key(experiment, alternative, date_hour)
+    end
+
+    # if date_hour isn't specified, get total count
+    # if date_hour is specified, return count for DateHour
+    def conversion_count(experiment, alternative, date_hour=nil)
+      get conv_key(experiment, alternative, date_hour)
+    end
+    
+    def player_state_set(experiment, player, name, value)
+      set player_state_key(experiment, player, name), value
+    end
+
+    def player_state_get(experiment, player, name)
+      get player_state_key(experiment, player, name), nil
+    end
+
+    def alternative_start_time(experiment, alternative)
+      secs = get alt_started_key(experiment, alternative), nil
+      secs.nil? ? nil : Time.at(secs).to_date_hour
+    end
+    
+    # if date_hour is nil, create key for total
+    # otherwise, create key for hourly based
+    def part_key(exp, alt, date_hour=nil)
+      parts = [ "participants", exp.name, alt ]
+      parts += [ date_hour.date, date_hour.hour ] unless date_hour.nil?
+      make_key parts
+    end
+
+    # key for alternative start
+    def alt_started_key(experiment, alternative)
+      make_key [ "altstarted", experiment.name, alternative ]
+    end
+
+    # if date_hour is nil, create key for total
+    # otherwise, create key for hourly based
+    def conv_key(exp, alt, date_hour=nil)
+      parts = [ "conversions", exp.name, alt ]
+      parts += [ date_hour.date, date_hour.hour ] unless date_hour.nil?
+      make_key parts
+    end
+
+    def player_state_key(exp, player, varname)
+      make_key [ "state", exp.name, player.name, varname ]
+    end
+
+    def make_key(parts)
+      parts.join(":")
+    end
+
+    def with_failure_grace(fail_default=0)
+      begin
+        yield
+      rescue
+        Bandit.storage_failed!
+        Rails.logger.error "Storage method #{self.class} failed.  Falling back to memory storage."
+        fail_default
+      end
+    end
+  end
+end