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.
- Ruby 1.8.7 or 1.9.x
- ActiveRecord, DataMapper, Mongoid, or MongoMapper (your models must have an
- 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.
Add the following to your application's
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 (
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.
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.
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
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:
- Fork recommendable
- Create a feature branch
- Write your code (and tests please)
- Push to your branch's origin
- Create a Pull Request from your branch
- That's it!
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 © 2012 David Celis. See LICENSE.txt for further details.