Basic Concepts

Overview

Triton is a hosted personalization engine. It allows you to tailor your application to each of your users. Our powerful API recommends items or categories based on each individual user’s tastes. Our segmentation dashboard allows you to understand user segments and provide coarse personalization over segments of users. We provide you with a full control panel to override the default recommendation behaviour, and provide the exact experience you desire.

Background

Historically, recommender systems either use exclusively content or collaborative filtering. Collaborative filtering only leverages user actions for recommendations. This can result in problems for new users and new items that have little history. Content based approaches only use the content and attributes of each item to match similarity. Without the context of user behaviour, this approach has trouble identifying the most important factors for recommendations. It also has no way to improve itself with user action feedback. Triton implements a hybrid approach which takes the advantages of both without any of the drawbacks. This allows us to generalize the recommendation model.


Recommendations require you to balance accuracy and serendipity. Models that aggressively focus on accuracy hinder users from discovering new, different content. Generally models tend to fall down this path, since accuracy is easier to quantify and improve. Serendipity provides an extremely powerful user experience, but too much of it leads to randomness. Our models try to balance both; however, each application will have different needs. A music application may want to focus on serendipity, where a academic paper website may favor accuracy. We put the final control in your hands.


Personalization requires more than just recommendations. A personalized experience may require custom pages for different user segments, or changes in UI to leverage recommendation APIs. This requires context on user segments and the defining characteristics of each. Understanding these segments, and the general explanations to recommendations provide a powerful tool to spearhead your personalization efforts.


Vocabulary

  • Recommender System

    A recommender system is a machine learning model that learns user behaviour to effectively recommend content.

  • Personalization

    Techniques to enable your users to solve their needs effectively and to discover new value from your application.

  • Action

    An Action defines a type of event that a user can perform, like a click or a share. It can optionally have a list of named attributes, such as what they clicked on or the rating they gave.

  • Class

    A Class is a template for an Object. It defines an object’s attribute names and types. For example, a song may have a unique ID, a genre, a name, and a release year.

  • User

    A special Class that defines the attributes that make up a user in your application.

  • Event

    An instance of an Action. It should have an attribute specifying the user who performed the Action and an attribute specifying the time which the Action was performed.

  • Object

    An instance of a Class. It should have an ID attribute that uniquely identifies it.

  • Event Listener

    A function in your application that forwards user events to Triton.

  • Recommender

    A recommender defines a recommender system model based on your Classes and Actions. You define what Class or Class attribute to recommend. In a music application, this would allow you to create one recommender for songs and another for genres. You may also choose an Action to optimize for. For example, you may choose to optimize for either clicks or for purchases in an e-commerce application.




Getting Started

Overview

Implementing Triton requires four simple steps. To help illustrate the process, we’ll give examples of each step for a simple music streaming application.

Configure Classes and Actions

First you must configure all the classes in your application. For our music application, the Classes may include users, songs, artists, and genres. Each Class will have a list of associated Fields.


Second, you must configure the Actions performed in your application. Actions specify the potential interactions by users, which often act upon other classes. For our music application, actions may include listens, likes, or shares.


Defining a Class and defining an Action is done in the same way. To outline the properties of Classes and Actions, each Class/Action definition should include a list of Attributes. Each Attribute has a type that defines valid values and provides heuristics for the recommender to use for optimization.


Attributes are represented in JSON as follows:

{
	"type": // one of the following: "integer", "string", "float", "timestamp"
	"categorical": // boolean, specifies if the attribute is categorical/discrete or continuous
	"references": // string, specifes the Class name which the attribute references
	"id": // boolean, specifies if this is the Class's ID
	"array": // boolean, specifies if the value is an array
	"optional": // boolean, specifies if the attribute must be included on upload
}

The Attribute’s type is its primitive type, which must be integer, float, string, or timestamp. Integers and strings can either be continuous or discrete types. Discrete types represent categories, such as enums.


Example Attributes using "type" and "categorical":

  • Description: Continuous String
  • Genre: Categorical String
  • Number of successful trials: Continuous Integer
  • Age: Continuous Integer
  • Color: Categorical String
  • Article Text: Continuous String
  • Zip Code: Categorical Integer

A Class must have one ID attribute. A reference type points to an Object in another Class by its ID.

In a simple music application, I can setup my classes and actions as follows.

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/class/song/_create
-d ‘{
	“id”: {
		“type”: “string”,
		“id”: true
	},
	“name”: {
		“type”: “string”,
		“categorical”: true
	},
	“genres”: {
		“type”: “string”,
		“categorical”: true,
		“array”: true,
		"optional": true
	},
	“artist”: {
		“type”: “string”,
		“categorical”: true
	}
}’

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/class/user/_create
-d ‘{
	“username”: {
		“type”: “string”,
		“id”: true
	},
	# In this application, a user may optionally chose their favorite genres.
	# If they do, we’ll take it into account.
	“top-genres-form”: {
		“type”: “string”,
		“categorical”: true
	}
}’
curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/action/like/_create
-d ‘{
	# An Action must have a required user attribute, that references the user Class.
	“user”: {
		“type”: “string”,
		“references”: “user”
	},
	“quote”: {
		“type”: “string”,
		“references”: “quote”
	},
	# An Action must have a timestamp field. If it's not included, it
	# defaults to the time of upload.
	“timestamp”: {
		“type”: “timestamp”,
		"optional": true
	}
}’
curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/action/click/_create
-d ‘{
	“user”: {
		“type”: “string”,
		“references”: “user”
	},
	“quote”: {
		“type”: “string”,
		“references”: “quote”
	},
	“timestamp”: {
		“type”: “timestamp”
	}
}’

Creating your Recommenders

After configuring Classes and Actions, you detail your recommender behaviour. Each recommender can recommend a Class or Class attributes. For example, in a music application, you can create one recommender for songs and another for the genres. You can also configure the recommender to optimize between different actions. For example, in the music application you can optimize between clicks or likes.


In general you want to choose an Action that an average user will perform at least ten times. You need to balance amount of data with desired behaviour.


We’ll create two recommenders below, one for recommending genres to optimize for likes and another to recommend songs to optimize for clicks.

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/recommender/genres/_create
-d ‘{
	“class”: “song”,
	“attribute”: “genre,
	“action”: “like”
}’
curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X POST https://triton.cloud/recommender/songs/_create
-d ‘{
	“class”: “song”,
	“action”: “click”
}’

Uploading Objects and Events

After configuring your Classes and Actions, you should populate them with Objects and Events. An Object is an instance of a Class. An Event is an instance of an Action. If you have existing data stored, you can use our bulk upload APIs to quickly populate Triton. Your application should be updated with event listeners to stream events directly. This allows for near real time optimization of the recommenders.


We can upload a user, a song, and a like in our simple music app, as follows:

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X PUT https://triton.cloud/class/user 
-d ‘{
	“username”: “simba”
}‘
curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X PUT https://triton.cloud/class/song 
-d ‘{
	“id”: “abc123”,
	“name”: “Graceless”,
	“artist”: “The National”
}‘
curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X PUT https://triton.cloud/action/like 
-d ‘{
	“user”: “simba”,
	“song”: “abc123”
}‘

Fetching Recommendations

After Classes and Actions are configured and data has begun streaming to Triton, we can start fetching recommendations.


The music application may have homepage that requires top songs for a user. We can do this as follows:

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X GET 
            https://triton.cloud/recommender/songs?user=simba&num=10

If a user clicks on a song, and you can show them recommended songs similar to the given song:

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X GET 
            https://triton.cloud/recommender/songs?user=simba&song=abc123&num=25

Segmentation

All recommenders also provide segmentation features. These features are configured and accessed through the dashboard. It takes all of your users and breaks them up into a handful of segments according to their likes and their activity level.


The segmentations each contain defining characteristics, and a list of general recommendations for that segment. This illustrates how the segment behaves and how the recommender reacts to it. Segments may be named and used directly in your application.


To get the segment that a user belongs to, you may do:

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X GET https://triton.cloud/segment?user=simba

You may also want to get a less personalized list of recommendations for a user’s segment. Recommendations by segment chose out of a pool of items to a whole segment of users. This may have slightly worse results due to stereotyping, but provides more control in boosting results and more understanding in recommender behaviour.

curl -H ‘X-Triton-Key: <YOUR API KEY>’ -X GET https://triton.cloud/segment/recommender/songs?user=simba&num=25



API Reference

Identifiers

All names must be valid identifiers. They must be less than 64 characters long, and can only contain letters, numbers, and underscores. They may not begin with an underscore.

Attributes

An Attribute is represented in JSON as follows:

{
	"type": // one of the following: "integer", "string", "float", "timestamp"
	"categorical": // boolean, specifies if the attribute is categorical/discrete or continuous
	"references": // string, specifes the Class name which the attribute references
	"id": // boolean, specifies if this is the Class's ID
	"array": // boolean, specifies if the value is an array
	"optional": // boolean, specifies if the attribute must be included on upload
}

Fields:

  • A timestamp is in the format “YYYY-MM-DD HH:MM:SS”
  • A categorical attribute value should be treated as a discrete category rather than a continuous value. Only strings and integers may be categorical.
  • A Class must have a single ID attribute that uniquely identifies each Object. An ID must be require and may not be an array.
  • A Class may have an attribute that references another Class. In this case the reference value should be the name of the class. The value of the reference attribute should be the ID of the the Object being referenced. This means that the reference attribute type must be the same as the type of the referenced class’s ID.
  • An attribute may be an array, but nested arrays are not supported.
  • An attribute may be optional. By default, attributes are required. If it is optional, it can also be omitted from uploaded objects to default to null.

Classes

This API creates classes of objects, and defines their attributes.

Creating a Class

This specifies the attributes of a Class. A Class must have one ID type set.

URL https://triton.cloud/class/<CLASSNAME>/_create
Headers X-Triton-Key set to your API key.
Method POST
Body
{
	<attribute name>: <type>,
	…
}

Get Classes

See all the classes you've created. This returns a JSON object of all the classes and their attributes.

URL https://triton.cloud/class
Headers X-Triton-Key set to your API key.
Method GET
Returns
{
  <class name>: {
    <attribute name>: <attribute>,
    …
  },
  …
}

Uploading an Object

Uploads an Object to a Class table. If an attribute is not included, it’s value will default to null. If an ID already exists, the other attribute values will be updated.

URL https://triton.cloud/class/<CLASSNAME>
Headers X-Triton-Key set to your API key.
Method PUT
Body
{
	<attribute name>: <value>,
	…
}

Bulk Uploading Objects

Uploads multiple objects to a Class table. If an attribute is not included, it’s value will default to null. If an ID already exists, the other attribute values will be updated. The values are uploaded in order, so a later Object may override a previous one.

URL https://triton.cloud/class/<CLASSNAME>/_bulk
Headers X-Triton-Key set to your API key.
Method PUT
Body

[
	{
		<attribute name>: <value>,
		…
	},
	…
]

Deleting Objects

Deletes an Object from a Class table.

URL https://triton.cloud/class/<CLASSNAME>
Headers X-Triton-Key set to your API key.
Method DELETE
Body
{
	"id": <OBJECT_ID>
}

Deleting User Data

Deletes all a user's data, including their events. We cannot train on this user's data after the fact.

URL https://triton.cloud/class/user
Headers X-Triton-Key set to your API key.
Method DELETE
Body
{
	"id": <OBJECT_ID>,
	"actions": true
}

Merging Users

Pins all events made by one user to another. This can be used on an anonymous user who later logged in or created an account. You must set the base user, which should be treated as the actual user.

URL https://triton.cloud/class/user/_merge
Headers X-Triton-Key set to your API key.
Method POST
Body
{
	"base": <USER_ID>,
	"other": <USER_ID>
}

Actions

This API creates actions

Creating an Action

Creates a new Action. Types are described above. An Action must have a timestamp attribute and a user attribute. By default, the timestamp attribute defaults to the time of upload, but you may set the timestamp to a time in the past to retroactively upload actions.

URL https://triton.cloud/action/<ACTIONNAME>/_create
Headers X-Triton-Key set to your API key.
Method POST
Body
{
	“user”: {
		“type”: <user ID type>,
		“references”: “user”
	},
	“timestamp”: {
		“type”: “timestamp”,
		"optional": true
	},
	<attribute name>: <type>,
	…
}

Get Actions

Fetches all the Actions. Returns a JSON of all actions and their attributes.

URL https://triton.cloud/action
Headers X-Triton-Key set to your API key.
Method GET
Returns
{
	<action name>: {
		<user>: <user id attribute>,
		<attribute name>: <attribute>,
		…
	},
	…
}

Uploading an Event

Uploads an Event to an Action table. If an attribute is not included, it’s value will default to null.

URL https://triton.cloud/action/<ACTIONNAME>
Headers X-Triton-Key set to your API key.
Method PUT
Body
{
	<attribute name>: <value>,
	…
}

Bulk Uploading Events

Uploads multiple Events to an Action table. If an attribute is not included, it’s value will default to null.

URL https://triton.cloud/action/<ACTIONNAME>/_bulk
Headers X-Triton-Key set to your API key.
Method PUT
Body
[
[ 
	{
		<attribute name>: <value>,
		…
	},
	…
]

Segmentation

Get User Segment

Get the segment that a user is a part of.

URL https://triton.cloud/segment?user=<user id, URL encoded>
Headers X-Triton-Key set to your API key.
Method GET

Recommender

Create Recommender

A recommender recommends a Class or Class attribute. It optimizes for a user performing the provided Action. If specified, the attribute must be in the Class, and must me categorical or a reference. This can be used to recommend genres, amongst other things.

URL https://triton.cloud/recommender/<RECOMMENDER_NAME>/_create
Headers X-Triton-Key set to your API key.
Method POST
Body
{
	“action”: <action name>,
	“class”: <class name>,
	“attribute”: <optional, attribute name>
}

Get Recommenders

Fetch all the recommenders. Returns a JSON object of recommenders and their actions, classes, and atrtibutes.

URL https://triton.cloud/recommender
Headers X-Triton-Key set to your API key.
Method GET
Returns
{
	<recommender name>: {
		“action”: <action name>,
		“class”: <class name>,
		“attribute”: <optional, attribute name>
	},
	…
}

General Recommendation

Get general recommendations for a user. It returns a list of IDs or attribute values, depending on how the recommender was configured.

URL https://triton.cloud/recommender/<RECOMMENDER_NAME>?user=<user id>&num=<number of results>
Headers X-Triton-Key set to your API key.
Method GET

Similar Objects Recommendation

Get recommendations for a user that are similar to the given item. It returns a list of IDs or attribute values, depending on how the recommender was configured.

URL https://triton.cloud/recommender/<RECOMMENDER_NAME>?user=<user id>&<class name>=<object ID>&num=<number of results>
Headers X-Triton-Key set to your API key.
Method GET

Segmented Recommendation

Both similar and discovery recommendations can act on the user segment. Simply modify the previous two endpoints above by prepending /segment to the path:

URL https://triton.cloud/segment/recommender/<RECOMMENDER_NAME>?user=<user id>…
Headers X-Triton-Key set to your API key.
Method GET