Your First Model

Shaped provides two APIs that you should be familiar with to get started:

1. Model API
2. Rank API

Model API

The Model API allows you to manage your ranking models. It provides endpoints to create, list and delete your models. You can use Shaped's CLI or REST APIs to make requests.

Installing the CLI

To get started using the CLI to create a model, first install the Shaped CLI from PyPi as follows:

pip install shaped

info

Shaped supports Python 3.8+, take a look at the installation instructions if you need to install pip.

If you are having trouble installing due to package conflicts, use a Python virtual environment, especially if you are using the system default Python installation.

Initialize the client

You can then initialize the shaped client with your API key. If you don't have an API key yet, check out this to get one page.

shaped init --api-key <YOUR_API_KEY>

Creating your first model

Let's say you want to build a video recommendation model and you have your event data (containing clicks and impression events) stored in BigQuery. We could imagine the video table having the following columns:

1. user_id: the user triggering the interaction event.
2. item_id: the video id that was interacted with.
3. created_at: the timestamp of the event.
4. event: the event type with values: 'click' and 'impression'

To create a model from this table you need to add your BigQuery connection details and write a select query to choose the user_id, item_id, created_at and label columns. Shaped's event label column expects numerical values, where anything greater than 0 is positive and anything less than or equal to 0 is negative. For this use-case, we'll make clicks: positive (i.e. label=1) and impressions negative (i.e. label=0). Putting it all together here's a query that would work:

interaction_video_recommendations.yaml

model:
    name: interaction_video_recommendations
connectors:
    - type: BigQuery
      id: bigquery_connector
      location: us-west1
      project_id: rocket-ship-234123
      dataset: video_db
fetch:
    events: |
        SELECT user_id, item_id, created_at, (CASE WHEN event = 'click' THEN 1 ELSE 0 END) as label 
        FROM bigquery_connector.click_events

shaped create-model --file interaction_video_recommendations.yaml

Rank API

The Rank API is what's used to retrieve your recommendation results. It's a real-time, high performance endpoint designed to be integrated directly into your application and supports 1000s of requests a second. Much like the Model API we provide a CLI and REST API to make rank requests. The Rank API supports several discovery endpoints and argument combinations that handle your use-case whether it be a recommendation feed, a similar items carousels or personalized search.

Ranking

Here's how you can use the rank endpoint to retrieve personalized results for the user with user_id=3.

shaped rank --model_name interaction_video_recommendations --user_id 3 --limit 5

Example Response:

{
   "ids":[
      "427010",
      "182094",
      "332874",
      "827918",
      "403528"
   ],
   "scores":[
      0.9,
      0.8,
      0.7,
      0.3,
      0.2
   ],
}

The response contains a list of "ids", which in this case is the unique identifiers for the video (item_ids) that are most relevant to this user. Because we trained the models with 'click' as the positive interaction, these videos are what we predict the user to most likely want to click next.

The response also contains a parallel list of "scores", which has the respective relevance confidence we have that this item is relevant to the query user. You can use this to get a bit more of an understanding of how the relevancy estimates change throughout the ranking.

To learn more about using and evaluating results from the rank endpoint, take a look at some of specific guides on your use-case.

Next steps

Although this video recommendation model is a good starting place, there's a lot of ways we can improve it with Shaped. Notably,

1. Enriching your model with user and item attribute features to improve cold-start performance.
2. Creating personalized item filters that better represent your business logic.
3. Real-time connectors and session-based ranking

We recommend going through the rest of our guides to find out more!