Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A recommendation engine using Likes and Dislikes for your Ruby/Redis application.
tree: 5b71922a5b

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app
config
db/migrate
lib
script
spec
.gitignore
.travis.yml
CHANGELOG.markdown
Gemfile
Gemfile.lock
LICENSE.txt
README.markdown
Rakefile
TODO
recommendable.gemspec

README.markdown

Recommendable Build Status

Recommendable is an engine for Rails 3 applications to quickly add the ability for your users to Like/Dislike items and receive recommendations for new items. It uses Redis to store your recommendations and keep them sorted by how good the recommendation is.

Requirements

  • Ruby 1.9.x
  • Rails 3.x or 4.x
  • Sidekiq or Resque (or DelayedJob)

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 Resque, you should also include 'resque-loner' in your Gemfile to ensure your users only get queued once (Sidekiq does this by default, and there is no current way to avoid duplicate jobs in DelayedJob).

Installation

Add the following to your Rails application's Gemfile:

  gem 'recommendable'

After bundling, run the installation generator:

$ rails g recommendable:install

Double check config/initializers/recommendable.rb for options on configuring your Redis connection. After a user likes or dislikes something new, they are placed in a queue to have their recommendations updated. If you're using the basic Rails 4.0 queue, you don't need to do anything explicit. If using Sidekiq, Resque, or DelayedJob, start your workers from the command line:

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

Usage

In your Rails model that will be receiving recommendations:

class User < ActiveRecord::Base
  recommends :movies, :shows, :other_things

  # ...
end

That's it! Please note, however, that you may only do this in one model at this time.

For more details on how to use Recommendable once it's installed and configured, check out the more detailed README 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.

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.

Redis problems?

Oops, did you kill your Redis database? Not to worry. Likes, Dislikes, Ignores, and StashedItems are stored as models in your regular database. As long as these still exist, you can regenerate the similarity values and recommendations on the fly. But try not to have to do it!

User.all.each do |user|
  user.send :update_similarities
  user.send :update_recommendations
end

Why not stars?

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

I got lost and wandered into the world's creepiest cemetery, where the headstones just had names and star ratings. Freaked me out. When I got home I tried to leave the cemetery a bad review on Yelp, but as my hand hovered over the 'one star' button I felt this distant chill ...

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

Copyright

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

Something went wrong with that request. Please try again.