Personalized recommendations in 10 minutes

We have just released a video tutorial that will guide you through the integration of the Recombee recommendation service to your environment.

With this tutorial, all you need for trying our service out is a free account at Recombee, few minutes of time and some interaction data. Programming language Python is used in the video, but it shouldn’t be a problem if you’re not familiar with this language, as only very basic constructs are used. Here you can check the resulting scripts also in other languages, namely Java, PHP and Ruby.

Sample data

Suppose that I run a website which offers tickets to cultural events and I already have some collected data from the past, namely views of the events and purchases of the tickets by the users. For simplicity I have the interactions in two .csv files with the same structure.

purchases.csv:
user-145      event-112       2016-04-20T12:47:29+02:00
user-7        event-12        2016-04-20T12:52:11+02:00
user-77       event-9         2016-04-20T14:13:47+02:00
user-19       event-159       2016-04-20T15:40:01+02:00
...
detail_views.csv:
user-7        event-12        2016-04-20T12:50:42+02:00
user-384      event-5         2016-04-20T13:06:03+02:00
user-12       event-159       2016-04-20T13:07:10+02:00
user-456      event-113       2016-04-20T13:25:55+02:00
...

Sending interactions

I need the Recombee client so I’ll import it from the already installed package. I’ll import also all the classes for the requests in order to spare some typing. Then I create the instance of the client. It is initialized with the ID of my database and the secret token, which I both gained when I created the instant account, so I’ll just copy and paste them from the UI at admin.recombee.com.

from recombee_api_client.api_client import RecombeeClient
from recombee_api_client.api_requests import *

client = RecombeeClient(id_of_my_db, secret_token)

Now I want to upload some interactions to the recommender system. I’ll start by reading the purchases from the csv file line by line and creating an AddPurchase request object for each purchase in the file. It takes two mandatory parameters - the userId and the itemId. I’ll set the optional parameter timestamp to time (because the default value is the current time, but I want a particular time from past) and I’ll also set cascadeCreate to True, in order to create in the system the yet non existing items and users.

import csv
with open('purchases.csv') as csvfile:
    csvreader = csv.reader(csvfile)
    for row in csvreader:
        user_id = row[0]
        item_id = row[1]
        time = row[2]
        r = AddPurchase(user_id, item_id,
                        timestamp=time, cascade_create=True)

We could send the purchases one by one, using the send method of the client.

client.send(r)

Sending individual requests is very beneficial when you have the recommender already deployed in production, as the system can immediately modify its recommendations using the just received interaction.

But uploading larger data from the past with individual requests would be quite slow (because of the network latencies etc.), and therefore for sending the list of purchases we’ll use the Batch request, which can encapsulate many requests into a single request.

purchases = []
with open('purchases.csv') as csvfile:
    ...
        r = AddPurchase(user_id, item_id,
                        timestamp=time, cascade_create=True)
        purchases.append(r)

br = Batch(purchases)
client.send(br)

Now let’s run the script and see the result in the web interface.

You should see the uploaded items in the Catalog listing. You can also check interactions of an item by clicking its id.

Now let’s change the code to send the detail views by changing the name of file with interactions (purchases.csv to detail_views.csv ) and the name of the class from AddPurchase to AddDetailView.

r = AddDetailView(user_id, item_id,
                  timestamp=time, cascade_create=True)

After running the changed code, detail views should appear in the interface.

You can also see the visualization in the KPI console, which is updated up to every few minutes.

Getting recommendations

Now it’s time to get some recommendations based on the uploaded interactions.

Suppose that user-27 just came to my website. I want to immediately show him 5 events that he will most likely favor. I’ll use the UserBasedRecommendation for this task.

recommended = client.send(UserBasedRecommendation('user-27', 5))
print(recommended)

It returns IDs of the 5 recommended items:

['event-5', 'event-17', 'event-32', 'event-19', 'event-92']

Now I can show these recommended events to user-27 at my homepage.

Let’s say that the user likes the recommended events, and clicked one of them, namely event-32, to see the details. The page of the event contains box with related events, which are obtained by requesting the ItemBasedRecommendation. I want the related items to be personalized for user-27, so I pass the targetUserId.

recommended = client.send(
   ItemBasedRecommendation('event-32', 5, target_user_id='user-27'))

It returns:

['event-59', 'event-19', 'event-17', 'event-38', 'event-3']

Conclusion

As you can see sending interactions and getting recommendations is very easy, and took just few lines of code.

In the next tutorial I’ll show you how to send properties of the items to Recombee and how to use these properties in filtering and boosting according to your business rules.