README.md

Recommendable

Recommendable is a gem that allows you to quickly add a recommendation engine for Likes and Dislikes to your Ruby application using my version of Jaccardian similarity and memory-based collaborative filtering.

Requirements

• Ruby 1.8.7 or 1.9.x
• ActiveRecord, DataMapper, Mongoid, or MongoMapper (your models must have an id field)
• Sidekiq, Resque, DelayedJob (optional but highly recommended)

Bundling one of the queueing systems above is highly recommended to avoid having to manually refresh users' recommendations. If running on Rails 4, the built-in queueing system is supported. If you bundle Sidekiq, Resque, or DelayedJob, Recommendable will use your bundled queueing system instead. If bundling Sidekiq, you should also include 'sidekiq-middleware' in your Gemfile to ensure that a user will not get enqueued more than once at a time. If bundling Resque, you should include 'resque-loner' for this. As far as I know, there is no current way to avoid duplicate jobs in DelayedJob.

Installation

Add the following to your application's Gemfile:

  gem 'recommendable'

For correct detection of your ORM, you may need to place Recommendable below your ORM in the Gemfile.

After bundling, you should configure Recommendable. Do this somewhere after you've required it, but before it's actually used. For example, Rails users would create an initializer (config/initializers/recommendable.rb):

require 'redis'

Recommendable.configure do |config|
  # Recommendable's connection to Redis
  config.redis = Redis.new(:host => 'localhost', :port => 6379, :db => 0)

  # A prefix for all keys Recommendable uses
  config.redis_namespace = :recommendable

  # Whether or not to automatically enqueue users to have their recommendations
  # refreshed after they like/dislike an item
  config.auto_enqueue = true

  # The name of the queue that background jobs will be placed in
  config.queue_name = :recommendable

  # The number of nearest neighbors (k-NN) to check when updating
  # recommendations for a user. Set to `nil` if you want to check all
  # other users as opposed to a subset of the nearest ones.
  config.nearest_neighbors = nil
end

The values listed above are the defaults. I recommend playing around with the nearest_neighbors setting. A higher value will provide more accurate recommendations at the cost of more time spent generating them.

Usage

In your model that will be receiving recommendations:

class User
  recommends :movies, :books, :minerals, :other_things

  # ...
end

To ensure that users' recommendations are processed after they rate items, make sure your bundled queue system is running:

# sidekiq
$ [bundle exec] sidekiq -q recommendable
# resque
$ QUEUE=recommendable [bundle exec] rake environment resque:work
# delayed_job
$ [bundle exec] rake jobs:work

That's it! Please note, however, that currently only one model may receive recommendations.

For more details on how to use Recommendable in your application, check out the detailed guide or see the documentation.

Installing Redis

Recommendable requires Redis to deliver recommendations. The collaborative filtering logic is based almost entirely on set math, and Redis is blazing fast for this.

NOTE: Your Redis database MUST be persistent. All ratings are stored permanently in Redis. If you're worried about Redis losing data, keep backups.

Mac OS X

For Mac OS X users, homebrew is by far the easiest way to install Redis. Make sure to read the caveats after installation!

$ brew install redis

Linux

For Linux users, there is a package on apt-get.

$ sudo apt-get install redis-server
$ redis-server

Redis will now be running on localhost:6379. After a second, you can hit ctrl-\ to detach and keep Redis running in the background.

Why not stars?

I'll let Randall Munroe of XKCD take this one for me:

Contributing to recommendable

Once you've made your great commits:

1. Fork recommendable
2. Create a feature branch
3. Write your code (and tests please)
4. Push to your branch's origin
5. Create a Pull Request from your branch
6. That's it!

Links

• Code: git clone git://github.com/davidcelis/recommendable.git
• Home: http://github.com/davidcelis/recommendable
• Docs: http://rubydoc.info/gems/recommendable/frames
• Bugs: http://github.com/davidcelis/recommendable/issues
• Gems: http://rubygems.org/gems/recommendable

Copyright

Copyright © 2012 David Celis. See LICENSE.txt for further details.