bandit 0.0.2 → 0.0.3

data/README.rdoc

@@ -1,3 +1,71 @@
-= bandit - A multi-armed bandit optmization framework for Rails
+= bandit
 
-TODO: Write library.
+Bandit is a multi-armed bandit optmization framework for Rails.
+
+= 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_<expname>" 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 converstion in your controller:
+
+   bandit_convert! :click_test
+
+= Dashboard
+
+    rails generate bandit:dashboard
+
+Then, add the following to your config/routes.rb file:
+
+    match 'bandit' => 'bandit#index'
+
+To see a dashboard with relevant information, go to:
+
+    http://<yourhost>/bandit
+
+= Tests
+To run tests:
+
+    rake test
+
+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]
+
+= Reference
+http://untyped.com/untyping/2011/02/11/stop-ab-testing-and-make-out-like-a-bandit

data/Rakefile

@@ -1 +1,33 @@
 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('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

@@ -16,4 +16,6 @@ Gem::Specification.new do |s|
   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("rdoc")
 end

data/lib/bandit.rb

@@ -1,5 +1,56 @@
 require "bandit/version"
+require "bandit/exceptions"
+require "bandit/config"
+require "bandit/experiment"
+require "bandit/date_hour"
+require "bandit/memoizable"
+
+require "bandit/players/base"
+require "bandit/players/round_robin"
+require "bandit/players/epsilon_greedy"
+
+require "bandit/storage/base"
+require "bandit/storage/memory"
+require "bandit/storage/memcache"
+require "bandit/storage/redis"
+
+require "bandit/extensions/controller_concerns"
+require "bandit/extensions/view_concerns"
+require "bandit/extensions/time"
+require "bandit/extensions/string"
 
 module Bandit
-  # Your code goes here...
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.setup(&block)
+    yield config
+    config.check!
+    # intern keys in storage config
+    config.storage_config = config.storage_config.inject({}) { |n,o| n[o.first.intern] = o.last; n }
+  end  
+
+  def self.storage
+    @storage ||= BaseStorage.get_storage(Bandit.config.storage.intern, Bandit.config.storage_config)
+  end
+
+  def self.player
+    @player ||= BasePlayer.get_player(Bandit.config.player.intern, Bandit.config.player_config)
+  end
+
+  def self.get_experiment(name)
+    exp = Experiment.instances.select { |e| e.name == name } 
+    exp.length > 0 ? exp.first : nil
+  end
+
+  def self.experiments
+    Experiment.instances
+  end
 end
+
+require 'action_controller'
+ActionController::Base.send :include, Bandit::ControllerConcerns
+
+require 'action_view'
+ActionView::Base.send :include, Bandit::ViewConcerns

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 not default.nil? and alternatives.include? default
+        alt = default
+      else
+        alt = Bandit.player.choose_alternative(self)
+      end
+      @storage.incr_participants(self, alt)
+      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/controller_concerns.rb

@@ -0,0 +1,24 @@
+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)
+          # delete cookie so we don't double track
+          cookies.delete(cookiename)
+        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,24 @@
+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
+    end
+
+  end
+end

data/lib/bandit/memoizable.rb

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