bandit 0.0.2 → 0.0.3

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.choice
+      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.choice
+    end
+  end
+end

data/lib/bandit/storage/base.rb

@@ -0,0 +1,124 @@
+# 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
+  end
+end

data/lib/bandit/storage/memcache.rb

@@ -0,0 +1,34 @@
+module Bandit
+  class MemCacheStorage < BaseStorage
+    def initialize(config)
+      require 'memcache'
+      config[:namespace] ||= 'bandit'
+      @memcache = MemCache.new(config.fetch(:host, 'localhost:11211'), config)
+    end
+
+    # increment key by count
+    def incr(key, count=1)
+      # memcache incr seems to be broken in memcache-client gem
+      set(key, get(key, 0) + count)
+    end
+
+    # initialize key if not set
+    def init(key, value)      
+      @memcache.add(key, value)
+    end
+
+    # get key if exists, otherwise 0
+    def get(key, default=0)
+      @memcache.get(key) || default
+    end
+
+    # set key with value, regardless of whether it is set or not
+    def set(key, value)
+      @memcache.set(key, value)
+    end
+
+    def clear!
+      @memcache.flush_all
+    end
+  end
+end

data/lib/bandit/storage/memory.rb

@@ -0,0 +1,31 @@
+module Bandit
+  class MemoryStorage < BaseStorage
+    def initialize(config)
+      @memory = Hash.new nil
+    end
+
+    # increment key by count
+    def incr(key, count=1)
+      @memory[key] = get(key) + count
+    end
+
+    # initialize key if not set
+    def init(key, value)
+      @memory[key] = value if @memory[key].nil?
+    end
+
+    # get key if exists, otherwise 0
+    def get(key, default=0)
+      @memory.fetch(key, default)
+    end
+
+    # set key with value, regardless of whether it is set or not
+    def set(key, value)
+      @memory[key] = value
+    end
+
+    def clear!
+      @memory = Hash.new nil
+    end
+  end
+end

data/lib/bandit/storage/redis.rb

@@ -0,0 +1,37 @@
+module Bandit
+  class RedisStorage < BaseStorage
+    def initialize(config)
+      require 'redis'
+      config[:host] ||= 'localhost'
+      config[:port] ||= 6379
+      config[:db] ||= "bandit"
+      @redis = Redis.new config
+    end
+
+    # increment key by count
+    def incr(key, count=1)
+      @redis.incrby(key, count)
+    end
+
+    # initialize key if not set
+    def init(key, value)
+      @redis.set(key, value) if get(key, nil).nil?
+    end
+
+    # get key if exists, otherwise 0
+    def get(key, default=0)
+      val = @redis.get(key)
+      return default if val.nil?
+      val.numeric? ? val.to_i : val
+    end
+
+    # set key with value, regardless of whether it is set or not
+    def set(key, value)
+      @redis.set(key, value)
+    end
+
+    def clear!
+      @redis.flushdb
+    end
+  end
+end

data/lib/bandit/version.rb

@@ -1,3 +1,3 @@
 module Bandit
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/generators/bandit/USAGE

@@ -0,0 +1,3 @@
+To copy bandit config and initilizer:
+
+    rails generate bandit:install

data/lib/generators/bandit/dashboard_generator.rb

@@ -0,0 +1,31 @@
+module Bandit
+  module Generators
+
+    class DashboardGenerator < Rails::Generators::Base
+      desc "Create a bandit dashboard controller"
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_controller
+        copy_file 'bandit_controller.rb', 'app/controllers/bandit_controller.rb'
+      end
+      
+      def copy_view
+        directory 'dashboard/view', 'app/views/bandit'
+        copy_file 'dashboard/bandit.html.erb', 'app/views/layouts/bandit.html.erb'
+        directory 'dashboard/helpers', 'app/helpers'
+      end
+
+      def copy_assets
+        directory 'dashboard/js', 'public/javascripts/bandit'
+        directory 'dashboard/css', 'public/stylesheets/bandit'
+      end
+
+      def message
+        say "\n\tNow, add the following to your config/routes.rb file:"
+        say "\t\tresources :bandit\n\n"
+      end
+
+   end
+
+  end
+end

data/lib/generators/bandit/install_generator.rb

@@ -0,0 +1,22 @@
+module Bandit
+  module Generators
+
+    class InstallGenerator < Rails::Generators::Base
+      desc "Copy Bandit default config/initialization files"
+      source_root File.expand_path('../templates', __FILE__)
+
+      def copy_initializers
+        copy_file 'bandit.rb', 'config/initializers/bandit.rb'
+      end
+
+      def copy_config
+        copy_file 'bandit.yml', 'config/bandit.yml'
+      end
+
+      def copy_rakefile
+        copy_file 'bandit.rake', 'lib/tasks/bandit.rake'
+      end
+    end
+
+  end
+end

data/lib/generators/bandit/templates/bandit.rake

@@ -0,0 +1,20 @@
+namespace :bandit do
+
+  desc "Generate fake data for a named experiment"
+  task :populate_data, [:experiment] => [:environment] do |t, args|
+    storage = Bandit.storage
+    exp = Bandit.get_experiment args[:experiment].intern
+    raise "No such experiment defined: #{args[:experiment]}" if exp.nil?
+
+    start = Bandit::DateHour.new((Date.today - 7), 0)
+    start.upto(Bandit::DateHour.now) { |dh|
+      puts "Adding data for alternatives on #{dh}"
+      exp.alternatives.each { |alt|
+        count = 1000 + rand(1000)
+        storage.incr_participants(exp, alt, count, dh)
+        storage.incr_conversions(exp, alt, (rand * count).floor, dh)
+      }
+    }
+  end
+
+end

data/lib/generators/bandit/templates/bandit.rb

@@ -0,0 +1,18 @@
+# Use this setup block to configure all options for Bandit.
+Bandit.setup do |config|
+  yml = YAML.load_file("#{Rails.root}/config/bandit.yml")[Rails.env]
+
+  config.player = yml['player']
+  config.player_config = yml['player_config']
+  
+  config.storage = yml['storage']
+  config.storage_config = yml['storage_config']
+end
+
+# Create your experiments here - like this:
+# 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."
+# }
+

data/lib/generators/bandit/templates/bandit.yml

@@ -0,0 +1,16 @@
+development: 
+  player: round_robin
+  storage: memcache
+
+test: 
+  player: round_robin
+  storage: memcache
+
+production: 
+  player: epsilon_greedy
+  player_config:
+    epsilon: 0.1
+  storage: redis
+  storage_config:
+    host: localhost
+    port: 6379

data/lib/generators/bandit/templates/bandit_controller.rb

@@ -0,0 +1,28 @@
+class BanditController < ApplicationController                                                                                                                                                   
+  layout 'bandit'
+
+  def index
+    @experiments = Bandit.experiments
+  end
+
+  def show
+    @experiment = Bandit.get_experiment params[:id].intern
+    respond_to do |format|
+      format.html
+      format.csv { render :text => experiment_csv(@experiment) }
+    end
+  end
+
+  private
+  def experiment_csv(experiment)
+    rows = []
+    experiment.alternatives.each { |alt|
+      experiment.alternative_start(alt).date.upto(Date.today) { |d|
+        pcount = Bandit::DateHour.date_inject(d, 0) { |sum,dh| sum + experiment.participant_count(alt, dh) }
+        ccount = Bandit::DateHour.date_inject(d, 0) { |sum,dh| sum + experiment.conversion_count(alt, dh) }
+        rows << [ alt, d.year, d.month, d.day, pcount, ccount ].join("\t")
+      }
+    }
+    rows.join("\n")
+  end
+end