Video Recommendations

Configuring entities and interactions

Entity data model

To train your video recommender, the first step is to define the data available to train on. The more entities and interactions available, the better the recommendations can be. Examples of entities that can be used include:

• Videos (movies, episodes, etc.)

• Series info (e.g., the series or season a TV episode is part of)

• Creator

• Genre

• Cast member (actors, directors, writiers, etc.)

In addition, users of your site and their attributes can comprise additional entities:

• Users

• Country

• Demographics (if available)

Note that you don't need to create all of these entities yourself! You can just create the basics and supply metadata. Lucid will read your metadata and generate entities for you.

Let's look at what our entity data feed might look like to get our video recommender going:

entity_type	entity_name	metadata
video	Jurassic Park	{ "creator": "Universal", "writer": "Michael Crichton", "director": "Steven Spielberg", "release_year": 1993, "genre": "sci-fi", "starring": [...], "description": "..." }
video	Lost World	{ "creator": "Universal", "writer": "David Koepp", "director": "Steven Spielberg", "release_year": 1997, "genre": "sci-fi", "starring": [...], "description": "..." }
video	Rick & Morty S1-1	{ "season": 1, "episode": 1, "genre": "sci-fi", "creator": "Adult Swim", "starring": [...], "description": "..." }
video	Rick & Morth S1-2	{ "season": 1, "episode": 2, "genre": "sci-fi", "creator": "Adult Swim", "starring": [...], "description": "..." }

From here, we also need entities and metadata about our users:

entity_type	entity_name	metadata
user	user_0001	{ "genre": ["sci-fi", "action"], "country": "United States", city: "San Francisco" }
user	user_0002	{ "genre": ["sci-fi", "romance"], "country": "United States", city: "New York" }
user	user_0003	{ "genre": ["mystery", "action"], "country": "France", city: "Paris" }

Note that we could have broken out the metadata into separate entities, but the Lucid backend will do this automatically. For example, entities could have been created for countries, genres, or cast members, specifying it in JSON format as metadata is faster. For complex cases where more control is needed on the interactions between the entities they can be broken out and connected using the interaction table.

Interaction model

Once the entities are tabulated, the interactions can be listed out. Interactions for video recommendation may include things like:

• Watched videos

• Favorited videos

• Clicks

• Shares

• Mouse-overs

Forming the interaction model simply involves linking together entities and naming that interaction:

source_entity	interaction_name	target_entity
user_0001	watched	Jurassic Park
user_0001	clicked	Lost World
user_0002	clicked	Rick & Morty S1-2
user_0003	watched	Jurassic Park
user_0003	watched	Rick & Morty S1-1

Training the model

Once the entity and interaction tables are created, they can be uploaded to the API through the data_batch endpoint. Be sure to add a tag to the datasets, such as video-data to differentiate it from other recommender projects you may start. You can upload as many entity and interaction tables as needed prior to training the model.

When the data is in place, trigger a training run:

POST <your-endpoint>/v1/recommend/train

You can optionally include parameters to filter the datasets or to only use interactions from the last 30 or 90 days. A typical training run will take several minutes, and a callback can be used to get an indication of completion.

Rolling it out

Personalized video recommendations for each user

With your trained model you can get out many different types of recommendations and trends. For example, let's say you want to get the top 100 recommendations for each user. To do so, you want to query the /recommended_items endpoint with the following parameters:

{
    "model_id": "<your model id>",
    "entity_type": "user",
    "target_entity_type": "video",
    "max_recommendations": 100,
    "output_format": "csv"
}

This query will give you back a large batch of recommendations for all users targeting videos. Because of the batched approach, you can query the results once and then cache them for fast access on your site or app.

An example of what these results might look like are:

entity_id	recommendation_id	#	score
user_0001	Lost World	1	0.91
user_0001	Rick & Morty S1-1	2	0.86
user_0001	Alien	3	0.84
...	...	...	...
user_0001	Titanic	100	0.61
user_0002	Jurassic Park	1	0.83
...	...	...	...

Recommending series instead of episodes

For video recommendation, it may be better to recommend a series instead of an episode. For example, it probably doesn't make sense to recommend specific episodes from a 10 season series; either you want to recommend the series as a whole or not.

To enable recommendations at the series level, simply change the target_entity parameter from videos to series. This requires that all of your video entities have a series metadata value, or that you create series entities and then link them to your videos using an interaction. However, doing so will improve the quality of results coming out of the recommender to meet the expected outcome.

Adding a Watch Next feature

You can use the same model to generate a watch next feature. Such a feature recommends similar videos based on a target video. To get watch-next results, you can use a query like this:

{
    "model_id": "<your model id>",
    "entity_type": "video",
    "target_entity_type": "series",
    "max_recommendations": 20,
    "output_format": "csv"
}

This will generate 20 recommendations of related series for each video in your dataset. If you want to generate user-specific watch-next recommendations for a given user and video, you can use the following query:

{
    "model_id": "<your model id>",
    "entity_id": ["user_0001", "Jurassic Park"],
    "target_entity_type": "series",
    "max_recommendations": 20,
    "output_format": "json"
}

This will generate 20 recommendations for that user related to Jurassic Park. Note that caching all such results in CSV is impractical, so the results are instead generate in JSON form (e.g., this would be a real-time query and not a batched query operation).

Getting fallback video recommendations

It may be convenient to have some fallback recommendations ready to go for new users that don't yet have any history. This can help address the cold-start problem but still give quality, localized recommendations. One method is to query for recommendations based on a user's country:

{
    "model_id": "<your model id>",
    "entity_type": "country",
    "target_entity_type": "series",
    "max_recommendations": 100,
    "output_format": "csv"
}

Thus, even if you have no information on a user, you can at least geolocate their IP address to get a country, and then serve local favorites as initial recommendations.