recommendable 1.1.7 → 2.0.0

data/lib/recommendable.rb

@@ -1,34 +1,46 @@
-require 'recommendable/engine'
-require 'recommendable/helpers'
-require 'recommendable/acts_as_recommended_to'
-require 'recommendable/acts_as_recommendable'
-require 'recommendable/exceptions'
-require 'recommendable/railtie' if defined?(Rails)
+require 'active_support'
+
 require 'recommendable/version'
-require 'hooks'
-require 'sidekiq/middleware/client/unique_jobs' if defined?(Sidekiq)
-require 'sidekiq/middleware/server/unique_jobs' if defined?(Sidekiq)
+require 'recommendable/configuration'
+require 'recommendable/helpers'
+
+require 'recommendable/rater'
+require 'recommendable/ratable'
 
 module Recommendable
-  mattr_accessor :redis, :user_class
-  mattr_writer :recommendable_classes
-  
-  def self.recommendable_classes
-    @@recommendable_classes ||= []
-  end
+  class << self
+    def redis() config.redis end
 
-  def self.enqueue(user_id)
-    if defined? Sidekiq
-      SidekiqWorker.perform_async user_id
-    elsif defined? Resque
-      Resque.enqueue ResqueWorker, user_id
-    elsif defined? Delayed::Job
-      Delayed::Job.enqueue DelayedJobWorker.new(user_id)
-    elsif defined? Rails::Queueing
-      unless Rails.queue.any? { |w| w.user_id == user_id }
-        Rails.queue.push RailsWorker.new(user_id)
-        Rails.application.queue_consumer.start
+    def query(klass, ids)
+        Recommendable::Helpers::Queriers.send(Recommendable.config.orm, klass, ids)
+      rescue NoMethodError
+        warn 'Your ORM is not currently supported. Please open an issue at https://github.com/davidcelis/recommendable'
+    end
+
+    def enqueue(user_id)
+      user_id = user_id.id if user_id.is_a?(Recommendable.config.user_class)
+
+      if defined?(::Sidekiq)
+        require 'recommendable/workers/sidekiq'
+        Recommendable::Workers::Sidekiq.perform_async(user_id)
+      elsif defined?(::Resque)
+        require 'recommendable/workers/resque'
+        Resque.enqueue(Recommendable::Workers::Resque, user_id)
+      elsif defined?(::Delayed::Job)
+        require 'recommendable/workers/delayed_job'
+        Delayed::Job.enqueue(Recommendable::Workers::DelayedJob.new(user_id))
+      elsif defined?(::Rails::Queueing)
+        require 'recommendable/workers/rails'
+        unless Rails.queue.any? { |w| w.user_id == user_id }
+          Rails.queue.push(Recommendable::Workers::Rails.new(user_idid))
+          Rails.application.queue_consumer.start
+        end
       end
     end
   end
 end
+
+require 'recommendable/orm/active_record' if defined?(ActiveRecord::Base)
+require 'recommendable/orm/data_mapper' if defined?(DataMapper::Resource)
+require 'recommendable/orm/mongoid' if defined?(Mongoid::Document)
+require 'recommendable/orm/mongo_mapper' if defined?(MongoMapper::Document)

data/lib/recommendable/configuration.rb

@@ -0,0 +1,47 @@
+require 'redis'
+
+module Recommendable
+  class Configuration
+    # The ORM you are using. Currently supported: `:activerecord`, `:mongoid`, and `:datamapper`
+    attr_accessor :orm
+
+    # Recommendable's connection to Redis
+    attr_accessor :redis
+
+    # A prefix for all keys Recommendable uses
+    attr_accessor :redis_namespace
+
+    # Whether or not to automatically enqueue users to have their recommendations
+    # refreshed after they like/dislike an item
+    attr_accessor :auto_enqueue
+
+    # The name of the queue that background jobs will be placed in
+    attr_accessor :queue_name
+
+    # The number of nearest neighbors (k-NN) to check when updating
+    # recommendations for a user. Set to `nil` if you want to check all
+    # neighbors as opposed to a subset of the nearest ones.
+    attr_accessor :nearest_neighbors
+
+    attr_accessor :ratable_classes, :user_class
+
+    # Default values
+    def initialize
+      @redis             = Redis.new
+      @redis_namespace   = :recommendable
+      @auto_enqueue      = true
+      @queue_name        = :recommendable
+      @ratable_classes   = []
+      @nearest_neighbors = nil
+    end
+  end
+
+  class << self
+    attr_accessor :config
+
+    def configure
+      @config ||= Configuration.new
+      yield @config
+    end
+  end
+end

data/lib/recommendable/helpers.rb

@@ -1,9 +1,3 @@
-module Recommendable
-  module Helpers
-    def manual_join(klass, action)
-      table = klass.base_class.table_name
-      inheritance_column = klass.base_class.inheritance_column
-      "JOIN #{table} ON recommendable_#{action.pluralize}.#{action}able_id = #{table}.id AND #{table}.#{inheritance_column} = '#{klass}'"
-    end
-  end
-end
+require 'recommendable/helpers/redis_key_mapper'
+require 'recommendable/helpers/calculations'
+require 'recommendable/helpers/queriers'

data/lib/recommendable/helpers/calculations.rb

@@ -0,0 +1,150 @@
+module Recommendable
+  module Helpers
+    module Calculations
+      class << self
+        # Calculate a numeric similarity value that can fall between -1.0 and 1.0.
+        # A value of 1.0 indicates that both users have rated the same items in
+        # the same ways. A value of -1.0 indicates that both users have rated the
+        # same items in opposite ways.
+        #
+        # @param [Fixnum, String] user_id the ID of the first user
+        # @param [Fixnum, String] other_user_id the ID of another user
+        # @return [Float] the numeric similarity between this user and the passed user
+        # @note Similarity values are asymmetrical. `Calculations.similarity_between(user_id, other_user_id)` will not necessarily equal `Calculations.similarity_between(other_user_id, user_id)`
+        def similarity_between(user_id, other_user_id)
+          similarity = liked_count = disliked_count = 0
+          in_common = Recommendable.config.ratable_classes.each do |klass|
+            liked_set = Recommendable::Helpers::RedisKeyMapper.liked_set_for(klass, user_id)
+            other_liked_set = Recommendable::Helpers::RedisKeyMapper.liked_set_for(klass, other_user_id)
+            disliked_set = Recommendable::Helpers::RedisKeyMapper.disliked_set_for(klass, user_id)
+            other_disliked_set = Recommendable::Helpers::RedisKeyMapper.disliked_set_for(klass, other_user_id)
+
+            # Agreements
+            similarity += Recommendable.redis.sinter(liked_set, other_liked_set).size
+            similarity += Recommendable.redis.sinter(disliked_set, other_disliked_set).size
+
+            # Disagreements
+            similarity -= Recommendable.redis.sinter(liked_set, other_disliked_set).size
+            similarity -= Recommendable.redis.sinter(disliked_set, other_liked_set).size
+
+            liked_count += Recommendable.redis.scard(liked_set)
+            disliked_count += Recommendable.redis.scard(disliked_set)
+          end
+
+          similarity / (liked_count + disliked_count).to_f
+        end
+
+        # Used internally to update the similarity values between this user and all
+        # other users. This is called by the background worker.
+        def update_similarities_for(user_id)
+          user_id = user_id.to_s # For comparison. Redis returns all set members as strings.
+          similarity_set = Recommendable::Helpers::RedisKeyMapper.similarity_set_for(user_id)
+
+          # Only calculate similarities for users who have rated the items that
+          # this user has rated
+          relevant_user_ids = Recommendable.config.ratable_classes.inject([]) do |memo, klass|
+            liked_set = Recommendable::Helpers::RedisKeyMapper.liked_set_for(klass, user_id)
+            disliked_set = Recommendable::Helpers::RedisKeyMapper.disliked_set_for(klass, user_id)
+            item_ids = Recommendable.redis.sunion(liked_set, disliked_set)
+
+            unless item_ids.empty?
+              sets = item_ids.map do |id|
+                liked_by_set = Recommendable::Helpers::RedisKeyMapper.liked_by_set_for(klass, id)
+                disliked_by_set = Recommendable::Helpers::RedisKeyMapper.disliked_by_set_for(klass, id)
+
+                [liked_by_set, disliked_by_set]
+              end
+
+              memo | Recommendable.redis.sunion(sets.flatten)
+            else
+              memo
+            end
+          end
+
+          relevant_user_ids.each do |id|
+            next if id == user_id # Skip comparing with self.
+            Recommendable.redis.zadd(similarity_set, similarity_between(user_id, id), id)
+          end
+
+          true
+        end
+
+        # Used internally to update this user's prediction values across all
+        # recommendable types. This is called by the background worker.
+        #
+        # @private
+        def update_recommendations_for(user_id)
+          nearest_neighbors = Recommendable.config.nearest_neighbors || Recommendable.config.user_class.count
+          Recommendable.config.ratable_classes.each do |klass|
+            similarity_set = Recommendable::Helpers::RedisKeyMapper.similarity_set_for(user_id)
+            recommended_set = Recommendable::Helpers::RedisKeyMapper.recommended_set_for(klass, user_id)
+            similar_user_ids = Recommendable.redis.zrevrange(similarity_set, 0, nearest_neighbors - 1)
+
+            sets_to_union = similar_user_ids.inject([]) do |sets, id|
+              sets << Recommendable::Helpers::RedisKeyMapper.liked_set_for(klass, id)
+            end
+
+            next if sets_to_union.empty?
+            scores = Recommendable.redis.sunion(sets_to_union).map { |id| [predict_for(user_id, klass, id), id] }
+            next if scores.empty?
+            Recommendable.redis.zadd(recommended_set, scores)
+          end
+
+          true
+        end
+
+        # Predict how likely it is that a user will like an item. This probability
+        # is not based on percentage. 0.0 indicates that the user will neither like
+        # nor dislike the item. Values that approach Infinity indicate a rising
+        # likelihood of liking the item while values approaching -Infinity
+        # indicate a rising probability of disliking the item.
+        #
+        # @param [Fixnum, String] user_id the user's ID
+        # @param [Class] klass the item's class
+        # @param [Fixnum, String] item_id the item's ID
+        # @return [Float] the probability that the user will like the item
+        def predict_for(user_id, klass, item_id)
+          similarity_set = Recommendable::Helpers::RedisKeyMapper.similarity_set_for(user_id)
+          liked_by_set = Recommendable::Helpers::RedisKeyMapper.liked_by_set_for(klass, item_id)
+          disliked_by_set = Recommendable::Helpers::RedisKeyMapper.disliked_by_set_for(klass, item_id)
+          similarity_sum = 0.0
+
+          Recommendable.redis.smembers(liked_by_set).inject(similarity_sum) do |sum, id|
+            sum += Recommendable.redis.zscore(similarity_set, id).to_f
+          end
+          Recommendable.redis.smembers(disliked_by_set).inject(similarity_sum) do |sum, id|
+            sum -= Recommendable.redis.zscore(similarity_set, id).to_f
+          end
+
+          liked_by_count = Recommendable.redis.scard(liked_by_set)
+          disliked_by_count = Recommendable.redis.scard(disliked_by_set)
+          prediction = similarity_sum / (liked_by_count + disliked_by_count).to_f
+          prediction.finite? ? prediction : 0.0
+        end
+
+        def update_score_for(klass, id)
+          score_set = Recommendable::Helpers::RedisKeyMapper.score_set_for(klass)
+          liked_by_set = Recommendable::Helpers::RedisKeyMapper.liked_by_set_for(klass, id)
+          disliked_by_set = Recommendable::Helpers::RedisKeyMapper.disliked_by_set_for(klass, id)
+          liked_by_count = Recommendable.redis.scard(liked_by_set)
+          disliked_by_count = Recommendable.redis.scard(disliked_by_set)
+
+          return 0.0 unless liked_by_count + disliked_by_count > 0
+
+          z = 1.96
+          n = liked_by_count + disliked_by_count
+          phat = liked_by_count / n.to_f
+
+          begin
+            score = (phat + z*z/(2*n) - z * Math.sqrt((phat*(1-phat)+z*z/(4*n))/n))/(1+z*z/n)
+          rescue Math::DomainError
+            score = 0
+          end
+
+          Recommendable.redis.zadd(score_set, score, id)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/recommendable/helpers/queriers.rb

@@ -0,0 +1,23 @@
+module Recommendable
+  module Helpers
+    module Queriers
+      class << self
+        def active_record(klass, ids)
+          klass.where(:id => ids)
+        end
+
+        def data_mapper(klass, ids)
+          klass.all(:id => ids)
+        end
+
+        def mongoid(klass, ids)
+          klass.where(:id => ids)
+        end
+
+        def mongo_mapper(klass, ids)
+          klass.where(:id => ids)
+        end
+      end
+    end
+  end
+end

data/lib/recommendable/helpers/redis_key_mapper.rb

@@ -0,0 +1,29 @@
+module Recommendable
+  module Helpers
+    module RedisKeyMapper
+      class << self
+        %w[liked disliked hidden bookmarked recommended].each do |action|
+          define_method "#{action}_set_for" do |klass, id|
+            [Recommendable.config.redis_namespace, Recommendable.config.user_class.to_s.tableize, id, "#{action}_#{klass.to_s.tableize}"].compact.join(':')
+          end
+        end
+
+        def similarity_set_for(id)
+          [Recommendable.config.redis_namespace, Recommendable.config.user_class.to_s.tableize, id, 'similarities'].compact.join(':')
+        end
+
+        def liked_by_set_for(klass, id)
+          [Recommendable.config.redis_namespace, klass.to_s.tableize, id, "liked_by"].compact.join(':')
+        end
+
+        def disliked_by_set_for(klass, id)
+          [Recommendable.config.redis_namespace, klass.to_s.tableize, id, "disliked_by"].compact.join(':')
+        end
+
+        def score_set_for(klass)
+          [Recommendable.config.redis_namespace, klass.to_s.tableize, 'scores'].join(':')
+        end
+      end
+    end
+  end
+end

data/lib/recommendable/orm/active_record.rb

@@ -0,0 +1,6 @@
+require 'active_record'
+
+ActiveRecord::Base.send(:include, Recommendable::Rater)
+ActiveRecord::Base.send(:include, Recommendable::Ratable)
+
+Recommendable.configure { |config| config.orm = :active_record }

data/lib/recommendable/orm/data_mapper.rb

@@ -0,0 +1,7 @@
+require 'dm-core'
+
+DataMapper::Model.append_extensions(Recommendable::Rater::ClassMethods)
+DataMapper::Model.append_extensions(Recommendable::Ratable::ClassMethods)
+DataMapper::Model.append_inclusions(Recommendable::Ratable::InstanceMethods)
+
+Recommendable.configure { |config| config.orm = :data_mapper }

data/lib/recommendable/orm/mongo_mapper.rb

@@ -0,0 +1,8 @@
+require 'mongo_mapper'
+
+MongoMapper::Document.plugin(Recommendable::Rater)
+MongoMapper::Document.plugin(Recommendable::Ratable)
+MongoMapper::EmbeddedDocument.plugin(Recommendable::Rater)
+MongoMapper::EmbeddedDocument.plugin(Recommendable::Ratable)
+
+Recommendable.configure { |config| config.orm = :mongo_mapper }

data/lib/recommendable/orm/mongoid.rb

@@ -0,0 +1,7 @@
+require 'mongoid'
+
+Mongoid::Document::ClassMethods.send(:include, Recommendable::Rater::ClassMethods)
+Mongoid::Document::ClassMethods.send(:include, Recommendable::Ratable::ClassMethods)
+Mongoid::Document.send(:include, Recommendable::Ratable::InstanceMethods)
+
+Recommendable.configure { |config| config.orm = :mongoid }

data/lib/recommendable/ratable.rb

@@ -0,0 +1,83 @@
+require 'recommendable/ratable/likable'
+require 'recommendable/ratable/dislikable'
+
+module Recommendable
+  module Ratable
+    extend ActiveSupport::Concern
+
+    def recommendable?() self.class.recommendable? end
+
+    module ClassMethods
+      def make_recommendable!
+        Recommendable.configure { |config| config.ratable_classes << self }
+
+        class_eval do
+          include Likable
+          include Dislikable
+
+          if ancestors.include?(ActiveRecord::Base) || include?(Mongoid::Document) || include?(MongoMapper::Document) || include?(MongoMapper::EmbeddedDocument)
+            before_destroy :remove_from_recommendable!
+          elsif include?(DataMapper::Resource)
+            before :destroy, :remove_from_recommendable!
+          end
+
+          # Whether or not items belonging to this class can be recommended.
+          #
+          # @return true if a user class `recommends :this`
+          def self.recommendable?() true end
+
+          # Check to see if anybody has rated (liked or disliked) this object
+          #
+          # @return true if anybody has liked/disliked this
+          def rated?
+            liked_by_count > 0 || disliked_by_count > 0
+          end
+
+          # Query for the top-N items sorted by score
+          #
+          # @param [Fixnum] count the number of items to fetch (defaults to 1)
+          # @return [Array] the top items belonging to this class, sorted by score
+          def self.top(count = 1)
+            score_set = Recommendable::Helpers::RedisKeyMapper.score_set_for(self)
+            ids = Recommendable.redis.zrevrange(score_set, 0, count - 1)
+
+            Recommendable.query(self, ids).sort_by { |item| ids.index(item.id.to_s) }
+          end
+
+          private
+
+          # Completely removes this item from redis. Called from a before_destroy hook.
+          # @private
+          def remove_from_recommendable!
+            # Remove this item from the score zset
+            Recommendable.redis.zrem(Recommendable::Helpers::RedisKeyMapper.score_set_for(self.class), id)
+
+            # Remove this item's liked_by/disliked_by sets
+            %w[liked_by disliked_by].each do |action|
+              set = Recommendable::Helpers::RedisKeyMapper.send("#{action}_set_for", self.class, id)
+              Recommendable.redis.del(set)
+            end
+
+            # Remove this item from any user's like/dislike/hidden/bookmark sets
+            %w[liked disliked hidden bookmarked].each do |action|
+              set = Recommendable::Helpers::RedisKeyMapper.send("#{action}_set_for", self.class, id)
+              Recommendable.redis.keys(set).each do |set|
+                Recommendable.redis.srem(set, id)
+              end
+            end
+
+            # Remove this item from any user's recommendation zset
+            Recommendable.redis.keys(Recommendable::Helpers::RedisKeyMapper.recommended_set_for(self.class, '*')).each do |zset|
+              Recommendable.redis.zrem(zset, id)
+            end
+          end
+        end
+      end
+
+      # Whether or not items belonging to this class can be recommended.
+      #
+      # @return true if a user class `recommends :this`
+      def recommendable?() false end
+    end
+  end
+end