Training

When the elements (items, users, or user-item interactions) are updated, it may be desirable to perform model training, aimed at making accurate recommendations with the latest data. The training endpoint allows a model to be trained on-demand.

There are seven possible statuses for the training process:

Status	Description
queued	The training request has been logged, but it has not been processed yet.
processing	The training request is being processed.
canceled	The training request has been canceled at the request of the user.
error	An error occurred while training the model. No changes have been applied.
completed_with_errors	The training did not complete successfully. Some of the interactions could not be processed. Recommendations can be made but the output will not be optimal.
completed	The training completed successfully.
training_time_out	Training could not be conducted: free tier training time is over.

When training is requested for the first time (see Schedule Training), the API automatically assigns queued status. To check the updated status, please refer to Get Training Status.

Schedule Training

The training of the model for the given table will be scheduled.

Note: Interactions with less than 500 entries will be ignored.

URL
POST /{tableId}/train

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table

Fields to be included in the request body:

Field	Mandatory	Type	Description
engine	✓	String	Engine to perform the training: content_based or hybrid.
interactionsFilter		Set<String>	List of interaction identifiers for training. If no filter values are present, all interactions will be trained.

Engine
A valid recommendation engine must be provided.

Example:

{
    "engine" : "content_based"
}

Interactions Filter
Optional parameter to explicitly indicate a sublist of interactions to train. If no value is provided, all interactions will be trained. Only applies on interactions based recommendation engines. The interaction id must exist on the referenced table.

Example:

{
    "engine" : "hybrid",
    "interactionsFilter" : ["rating", "share"]
}

Response

Code	Name	Description
202	Accepted
400	Bad Request
401	Unauthorized
403	Forbidden	Training time is over.
404	Not Found
500	Internal Server Error
503	Service Unavailable

JSON that includes the ID and the status of the request.

Example
Schedule content_based training of the products table.

curl -X POST "https://recom.sherpa.ai/v2/recomm/products/train" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-d  "{\"engine\":\"content_based\"}"

{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "queued"
}

Get Training Status

Items

Return the status of a training request.

URL
GET /{tableId}/train/{requestId}

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
requestId	✓	String	ID returned by a training request

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

JSON that includes the current status of the request.

Example
Get the current status of the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/train/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "completed"
}

Cancel Training

Cancel a training request. This can only be done when the status of the request is queued.

URL
DELETE /{tableId}/train/{requestId}

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
requestId	✓	String	ID returned by a training request

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error
503	Service Unavailable

JSON that includes the current status of the request.

Example
Cancel the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/train/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "canceled"
}