In this tutorial, we will show you how to build a high-quality restaurant recommendation app with TappingStone in 3 simple steps, without a PhD team. TappingStone Python SDK is used this time.

1. Setup the Project

Provided in the demo is a sample restaurant recommender data set courtesy of the UCI Machine Learning Repository. Completed sample application with source code and dataset can be downloaded here. If you need help in getting the repo, please see “forking a repo“.

Once you have successfully forked and cloned the repo to your machine you can import the project into your favorite IDE (A IML project file for IntelliJ is included. Use it if you do not want to go through the project creation wizard yourself) or just a plain ole’ text editor of your choice.

Below is a screenshot of  how your directories and files should look:

There is an included README that gives an overview of all the files and a basic howto on how to get started. If that’s enough to get you started great! Else, read on!

The first thing you’ll notice is that there are two distinct directories under the com/tappingstone folder, app and data. If you plan to import your own data  you can more or less ignore the data folder unless you want to use the mock_data.py script as a template for your own data import script. Below is a snippet of the mock_data.py

if __name__ == '__main__':
    import re
    import stoneapi

    #Initalize Stone Client
    appKey = ''
    apiUrl = 'https://stoneapi.com'
    apiVer = 'v1'
    threadCount = 100

    #Create client for usage
    client = stoneapi.Client(appkey=appKey, threads=threadCount, apiurl=apiUrl, apiversion=apiVer)

What’s important to notice in this snippet of code is that the appKey variable is blank. You need to enter in your own application key here using single quotes. For example,

appKey=’thisIsMyTappingStoneAppKey‘

Otherwise without a valid application key you will be unable to import any data into your TappingStone account, nor will you be able to use any of the recommendation calls we provide. If you need to get an application key, please sign up here.

The other variables that deal with communicating with the TappingStone server are apiUrl and apiVer. These you should generally leave alone for this demo application but if you have your own custom apiURL or you are testing a newer api version feel free to edit them. The variable threadCount can also be changed to any positive integer though you generally want to keep it under 100 to prevent the script from sucking up all the available threads. Note that if you want to make asynchronous calls you will need at least two threads. For a brief overview of what asynchronous means, see here. We’ll also go further into detail about the thread count below but for now just set it to some positive integer greater than 0. If you’re running the mock_data.py script, leave the threadCount as is unless you run into memory issues if any.

2. Import Data into TappingStone

Once you have entered in all variables you can test the script by running it! Simply hit the run button on your IDE or through command line with the following command,

python mock_data.py

You’ll see the console print messages as it goes about it’s business  Note that this script takes anywhere from 15-30 minutes depending on how many threads you specified and your network speed. Below is a sample of what your IDE console or terminal window should be printing out.

Once the data has been successfully imported it will take some time (usually about one hour) for our servers to generate some recommendations for you. You can check the status in your application web control panel. Once the “Behavior Prediction Status” is “Ready” you’re ready to move onto the next step.

3. Retrieve Personalized Recommendations

Now that a unique prediction model is built for your data set, we can start using the API to get some recommendations as well as use a few other nifty API calls for our purposes. Again, let’s refer to the screenshot below for the directory structure:

You’ll want to edit core_actions.py and enter in your application key just like you did in mock_data.py.

class ServerActions:
    client = None

    def __init__(self):
        #Initalize Stone Client
        appKey = '{yourApplicationKeyGoesHere}'
        apiUrl = 'https://stoneapi.com'
        apiVer = 'v1'
        threadCount = 100

If you’re not using our provided sample data set, please edit tappingStoneDemo.py accordingly to ensure that when the application is run that you don’t run into any funny errors. For those of you that are using our imported data set, run tappingStoneDemo.py through your IDE or the following command

python tappingStoneDemo.py

You should see something similar to the screenshot below:

Note that if you do not use a sample user ID from the sampleUserIDList.txt found under the com/tappingstone/data folder the application will generate whatever user ID you input and import that user ID into your TappingStone application data. Feel free at this point to play around with the application and get some recommendations One thing to note is that the TappingStone demo application is coded to give you 10 random restaurants every time when you select view restaurants. If you want to consistently execute an action on a particular restaurant (such as viewing, liking, disliking, or rating) just jot down the restaurant ID number and enter that number in every time you are asked to input a restaurant ID. Alternatively, you can edit tappingStoneDemo.py to give you a fixed number of restaurants every time such as only the first 10 restaurants or however many you want to display. Below is some sample console output again:

Now that you’ve gotten a taste of what the application looks like!

Code Explained

Let’s dive into the code to see the different functions being used and how to use them.

core_actions.py

core_actions.py contains functions that handle server side client calls for actions and functions that do not deal with user related behavioral actions. These actions include  for example

• creating new users
• creating new items
• accessing item details
• accessing user details
• parsing server responses

def __init__(self):
    #Initalize Stone Client
    appKey = '5x4h1i4p33k3m5h552i615s521c313h'
    apiUrl = 'https://stoneapi.com'
    apiVer = 'v1'
    threadCount = 100

    #Create client for usage
    self.client = stoneapi.Client(appkey=appKey, threads=threadCount, apiurl=apiUrl, apiversion=apiVer)

# Returns the Stone Client for usage
def getStoneClient(self):
    return self.client

# Closes the Stone Client connection
def closeStoneClient(self, client):
    client.close()

Let’s examine a function and go over it and their usage.

# Method to create a user
def createUser(self, client, uid, async):
    if async is True:
        client.acreate_user(uid=uid)
    else:
        client.create_user(uid=uid)

This particular function has a parameter that is of particular interest to us and that is the async parameter which is a meant to be a boolean value of True or False. Depending on what is passed in from tappingStoneDemo.py it will determine which function to call. At this point let’s take a minute to discuss what the difference is between asynchronous calls and synchronous calls. For a detailed explanation see the Wikipedia article here. Otherwise, in the most general terms possible, asynchronous calls as implemented by the TappingStone API mean that whenever you call an asynchronous function it will not block your app. What does blocked mean? If you do not use asynchronous calls or if you’ve somehow maxed out the thread count your application will “hang” or be blocked from taking further action until the function either completes (regardless of whether it’s successful or not), more threads are allocated, or if other threads have completed their jobs and are freed and able to be used again. Generally speaking you want to take advantage of asynchronous calls because it lets you send off a request and continue doing something else more interesting in the application. The main downside to using asynchronous calls is that you must check the response by feeding it to the response parsing function see below:

# Method to unpack the response object
# TODO seperate into different response unpacks
def parseResponse(self, client, response, uid):
"""
* This is a generic response parser to parse the responses returned by the server
"""
    try:
        parsedResponse = client.aresp(response)
        return parsedResponse
    except(stoneapi.UserNotFoundError):
        print 'User was not found'
        # Create a new user if user ID is not found
        self.createUser(client, uid=uid, async=True)
    except(stoneapi.ItemNotCreatedError):
        print 'There is no such item.'
    except(stoneapi.ItemNotFoundError):
        print 'There is no such item.'

All asynchronous function responses must be passed to the above function to get the response result if there are any. NOT ALL ASYNC FUNCTIONS RETURN SOMETHING USABLE. For example, creating a user or deleting a user when you pass in the response you are returned None as the return if it was successful. Otherwise it will throw it’s specified exception. Please see the TappingStone python SDK documentation for more in-depth documentation of function parameters, return objects, and exceptions.

The rest of the functions in core_actions.py should be self-explanatory so let’s move onto the next class.

behavior_actions.py

On the other hand, behavior_actions.py is a Python class that contains all the “behavioral” function calls to the TappingStone server. This means any action a user performs that is collected and aggregated into the recommendation calculations such as viewing items, liking items, rating items, friending, de-friending, following, unfollowing, etc.

Most of these functions should be pretty self-explanatory from the Python SDK documentation. However, there are a few things I’d like to go over regarding the actual Python SDK functions.

Most of these behavioral action functions should be done asynchronously. You don’t want your application user to view an item and have the whole application hang while waiting for the thread to complete it’s task. For example, you can have your application make an asynchronous call to get a list of recommendations for a particular user login and cache it so that a user can immediately get results or prepare an error handler in the background while your user uses your application. This way your user will not experience a loading screen when they go to fetch recommendations. They will immediately know their desired information or know that there may be some problem with their data connection or your application’s network connection right away instead of watching your application try to retrieve data and eventually timing out. Note that in our demo application we’ve coded our demo application to allow you to experiment with asynchronous and synchronous calls so you can get a feel for the different functions. Note that the speed of sending and receiving a response is dependent on your network as well as TappingStone’s network for the demo application.

Sample code for getting recommendations either asynchronously or synchronously.

# Method to get N recommendations for given user, call can be done async or non-async
def getRecommend(self, client, uid, numRecs, async):
    if async is True:
        response = client.aget_recommendations(uid=uid, n=numRecs)
    else:
        response = client.get_recommendations(uid=uid, n=numRecs)
    return response

Note that the Python SDK for this function returns a dictionary list which returns ONLY item IDs. See below for an example:

Your demo application most likely will hook into your own system’s database or an in-app database that’s already been setup with all the proper values for every item’s properties. However, as an example, if you wanted to completely use TappingStone to also host your item database you can pass in optional parameters when creating items which would then allow you to query item information to get all the optional values. An example of such code as well as it’s return value is shown below:

And an example of how you would add such an item into your TappingStone account,

if __name__ == '__main__':
    import re
    import stoneapi

    #Initalize Stone Client
    appKey = '5x4h1i4p33k3m5h552i615s521c313h'
    apiUrl = 'https://stoneapi.com'
    apiVer = 'v1'
    threadCount = 100

    #Create client for usage
    client = stoneapi.Client(appkey=appKey, threads=threadCount, apiurl=apiUrl, apiversion=apiVer)

    file = open('mock_data.txt', 'r')
    lines = file.readlines()
    try:
        client.create_item(iid='9999', itypes=(1,), name='test item', special='A special value here', value='Priceless')

    except (stoneapi.ItemNotCreatedError):
        print 'Error creating item!'

    client.close()
    print 'Done'

Also if you wanted to create a custom user with some customized information such as their birthday and sex,

if __name__ == '__main__':
    import re
    import stoneapi

    #Initalize Stone Client
    appKey = '5x4h1i4p33k3m5h552i615s521c313h'
    apiUrl = 'https://stoneapi.com'
    apiVer = 'v1'
    threadCount = 100

    #Create client for usage
    client = stoneapi.Client(appkey=appKey, threads=threadCount, apiurl=apiUrl, apiversion=apiVer)

    file = open('mock_data.txt', 'r')
    lines = file.readlines()
    try:
        client.create_user(uid='customuser', birthday='09-24-12', sex='male')

    except (stoneapi.UserNotCreatedError):
        print 'Error creating user!'

    client.close()
    print 'Done'