predictionio Legacy Package Documentation¶
PredictoinIO Python SDK
The PredictoinIO Python SDK provides easy-to-use functions for integrating Python applications with PredictionIO REST API services.
predictionio.Client (Deprecated) Usage Overview¶
Deprecated since version 0.8.0.
Before making any request through the PredictionIO API, you need to create a client object for your App.
>>> client = predictionio.Client(<your App Key>)
Note
The App Key can be found in the PredictionIO Admin Server web control panel.
Afterwards, you can import data or retrieve recommendations for your App by calling methods of this object. For example,
User
To import a user record from you App with user id = “u100”:
>>> client.create_user("u100")To import a user record with the optional predefined location attribute “pio_latlng”:
>>> client.create_user("u100", { "pio_latlng" : [1.23, 4.56] })You may also define your own custom attribute “custom” = “value”:
>>> client.create_user("u100", { "pio_latlng" : [1.23, 4.56], "custom": "value" })Note
custom attributes and values could be any string but all attribute names with prefix
'pio_'are reserved. You should not use the prefix'pio_'when define your custom attributes to avoid conflicts.
Item
To import an item record from your App with item id = “i200” and item type = “type3”:
>>> client.create_item("i200", ("type3",))To import an item record with the predefined optional attribute “pio_latlng”:
>>> client.create_item("i200", ("type3",), { "pio_latlng" : [1.23, 4.56] })You may also define your own custom attribute “custom” = “value”:
>>> client.create_item("i200", ("type3",), { "pio_latlng" : [1.23, 4.56], "custom": "value" })Note
custom attributes and values could be any string but all attribute names with prefix
'pio_'are reserved. You should not use the prefix'pio_'when define your custom attributes to avoid conflicts.
User Action on Item
To import a user “rate” action record from your App with user id = “u100”, item id = “i200” and rating = 2:
>>> client.identify("u100") >>> client.record_action_on_item("rate", "i200", { "pio_rate": 2 })Note
the “pio_rate” attribute is required for “rate” action.
To import a “view” action record from your App for the same user and item:
>>> client.record_action_on_item("view", "i200" )To import a “like” record with predefined optional timestamp attribute “pio_t”:
>>> client.record_action_on_item("like", "i200", { "pio_t": 12345678 })Note
predefined actions: “like”, “dislike”, “rate”, “view”, “conversion”
Item Recommendation Engine
When there is enough data imported from your App and the prediction results are ready, you can get recommendations for a user.
To get top 5 item recommendation for the same user id from the item recommendation engine “engine-1”
>>> result = client.get_itemrec_topn("engine-1", 5)
Item Similarity Engine
To get top 5 similar items of the item i200 from the item similarity engine “engine-2”
>>> result = client.get_itemsim_topn("engine-2", "i200", 5)To get top 5 similar items given a list of items i200,i300,i400 from the item similarity engine “engine-2”
>>> result = client.get_itemsim_topn("engine-2", "i200,i300,i400", 5)
Item Rank Engine
To rank a list of items i100, i101, i102, i103 for user “u100” from the item rank engine “engine-3”
>>> client.identify("u100") >>> result = client.get_itemrank_ranked("engine-3", ["i100","i101","i102", "i103"])
Please refer to the documentation of the predictionio.Client class for more details of all available methods.
Error Handling¶
An exception will be raised when an error occur during the request. Please refer to the documentation of the predictionio.Client class for details.
In general, you may want to catch the exception and decide what to do with the error (such as logging it).
For example, the method record_action_on_item() may raise U2IActionNotCreatedError.
>>> try:
>>> client.record_action_on_item("view", "i200")
>>> except:
>>> <log the error>
Asynchronous Requests¶
In addition to normal blocking (synchronous) request methods, this SDK also provides methods which can generate asynchronous requests.
All methods prefixed with ‘a’ are asynchronous (eg, acreate_user(), acreate_item()).
Asynchronous requests are handled by separate threads in the background, so you can generate multiple requests at the same time without waiting for any of them to finish.
These methods return immediately without waiting for results, allowing your code to proceed to work on something else.
The concept is to break a normal blocking request (such as create_user()) into two steps:
- generate the request (e.g., calling
acreate_user()); - get the request status and return data (calling
aresp());
This allows you to do other work between these two steps.
Note
In some cases you may not care whether the request is successful for performance or application-specific reasons, then you can simply skip step 2.
Note
If you do care about the request status or need to get the return data, then at a later time you will need to call aresp() with the AsyncRequest object returned in step 1.
Please refer to the documentation of asynchronous request methods for more details.
For example, the following code first generates an asynchronous request to retrieve recommendations, then get the result at later time:
>>> # Generates asynchronous request and return an AsyncRequest object
>>> request = client.aget_itemrec_topn("engine-1", 5)
>>> <...you can do other things here...>
>>> try:
>>> result = client.aresp(request) # check the request status and get the return data.
>>> except:
>>> <log the error>
Batch Import Data¶
When you import large amount of data at once, you may also use asynchronous request methods to generate lots of requests in the beginning and then check the status at a later time to minimize run time.
For example, to import 100000 of user records:
>>> # generate 100000 asynchronous requests and store the AsyncRequest objects
>>> req = {}
>>> for i in range(100000):
>>> req[i] = client.acreate_user(user_record[i].uid)
>>>
>>> <...you can do other things here...>
>>>
>>> # now check the status of the previous asynchronous requests
>>> for i in range(100000):
>>> try:
>>> result = client.aresp(req[i])
>>> except:
>>> <log the error>
Alternatively, you can use blocking requests to import large amount of data, but this has significantly lower performance:
>>> for i in range(100000):
>>> try:
>>> client.create_user(user_record[i].uid)
>>> except:
>>> <log the error>
predictionio.Client Class¶
-
class
predictionio.Client(appkey, threads=1, apiurl='http://localhost:8000', apiversion='', qsize=0, timeout=5)¶ PredictionIO client object.
This is an object representing a PredictionIO’s client. This object provides methods for making PredictionIO API requests.
Parameters: - appkey – the App Key provided by PredictionIO.
- threads – number of threads to handle PredictionIO API requests. Must be >= 1.
- apiurl – the PredictionIO API URL path.
- apiversion – the PredictionIO API version. (optional) (eg. “”, or “/v1”)
- qsize – the max size of the request queue (optional). The asynchronous request becomes blocking once this size has been reached, until the queued requests are handled. Default value is 0, which means infinite queue size.
- timeout – timeout for HTTP connection attempts and requests in seconds (optional). Default value is 5.
Deprecated since version 0.8.0: Use EventClient and EngineClient instead.
Note
The following is blocking (synchronous) request methods
Note
The following is non-blocking (asynchronous) request methods