Invoke Mantissa

Invoking Mantissa means asking for predictive analytics based on the data you have in your collection.

Sending an invocation is a three-step process:

1. Send an invocation
2. Retrieve the request id
3. Poll the platform to check the status of the invocation request

1. Send an invocation

To send an invocation, you need to send a POST request to the following endpoint:

/api/invocation

The request body should contain the following fields:

• collectionId: the id of the collection containing the data you want to use for the invocation;

• InvocationType: the type of the invocation you want to perform. It can be one of the following:

  • demand-prediction
  • lead-time-prediction
  • safety-stock
  • adv-safety-stock
  • reorder-point
  • adv-reorder-point;
• args: a dictionary containing the arguments for the invocation. The arguments depend on the type of invocation you are performing.

The request must also include an header with the authorization token.

Arguments to be specified in the request body for invocations of type demand-prediction and lead-time-prediction are:

• start_date: the start date of the prediction period;
• horizon: the number of periods for which you want to predict the demand;
• aggregation: the desired aggregation level. It can be one of the following:
  • item
  • classification
  • family;
• granularity: the granularity (i.e. the period length) of the prediction. It can be one of the following:
  • W (weekly)
  • M (monthly)
  • Q (quarterly).

Invocations of type safety-stock, adv-safety-stock, reorder-point, and adv-reorder-point do not require any additional arguments.

The following table summarizes the arguments to be specified for each invocation type; for a comprehensive description of the extra arguments, see Customizing Invocations section.

Invocation Type	horizon	start_date	granularity	aggregation
demand-prediction	✔️	✔️	✔️	✔️
lead-time-prediction	✔️	✔️	✔️	✔️
safety-stock
adv-safety-stock
reorder-point
adv-reorder-point

In the example below, we send a demand prediction invocation for the collection my-collection-id. We want to predict the demand for the period starting from 2022-01-01 for 3 weeks, at the item level, with weekly granularity.

Curl

curl --location 'https://nostradamus.u-hopper.com/api/invocation' \
--header 'Authorization: Token my-secret-token' \
--header 'Content-Type: application/json' \
--data '{
    "collectionId": "my-collection-id",
    "invocationType": "demand-prediction",
    "args": {
        "start_date": "2024-01-01",
        "horizon": 3,
        "aggregation": "item",
        "granularity": "W"
    }
}'

Python

import requests
import json

url = "https://nostradamus.u-hopper.com/api/invocation"

payload = json.dumps({
    "collectionId": "my-collection-id",
    "invocationType": "demand-prediction",
    "args": {
        "start_date": "2024-01-01",
        "horizon": 3,
        "aggregation": "item",
        "granularity": "W"
    }
})
headers = {
    'Authorization': 'Token my-secret-token',
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

2. Retrieve the request id

If the invocation request is successful (status code 202), the response will follow the InvocationRequest schema defined in the OpenApi documentation. The id field in the response contains the invocation request id that you will need to check the status of the invocation request, and the status field will be set to queued.

If the request is unsuccessful, the response will contain the error message.

An example of the response is shown below:

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "demand-prediction",
    "args": {
        "start_date": "2024-01-01",
        "horizon": 3,
        "aggregation": "item",
        "granularity": "W"
    },
    "status": "queued",
    "message": null,
    "invocationErrors": null,
    "invocationResults": null
}

3. Poll the platform to check the status of the invocation request

To get the status of the invocation request with id requestId, you can send a GET request to the following endpoint:

/api/invocation/{requestId}

Here is an example of how to check the status of the append request with id my-invocation-request-id:

Curl

curl --location 'https://nostradamus.u-hopper.com/api/invocation/my-invocation-request-id' \
--header 'Authorization: Token my-secret-token'

Python

import requests

url = "https://nostradamus.u-hopper.com/api/invocation/my-invocation-request-id"

payload = {}

headers = {
  'Authorization': 'Token my-secret-token'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The response (if the request succeeded, i.e. status code 200) will follow the InvocationRequest schema defined in the OpenApi documentation. The status field in the response will indicate the status of the request.

The status can be one of the following values: queued, in_progress, completed, error. In particular:

• a status queued indicates that the request has been received by the platform and is waiting to be processed;
• a status in_progress indicates that the request is being processed;
• a status completed indicates that the invocation process is successfully terminated and the predictions or analyses are ready to be retrieved;
• a status error indicates that the invocation process terminated with errors; the failure motivation will appear in the field invocationErrors of the response.

You may need to poll the platform periodically to check the status of your invocation request. This ensures that you receive timely updates on the progress and outcome of your request.

An example of the response is shown below:

{
    "id": "my-invocation-request-id",
    "collectionId": "my-collection-id",
    "invocationType": "demand-prediction",
    "args": {
        "start_date": "2024-01-01",
        "horizon": 3,
        "aggregation": "item",
        "granularity": "W"
    },
    "status": "completed",
    "message": null,
    "invocationErrors": null,
    "invocationResults": {
        "data": {
            "primaryResult": true,
            "status": "completed",
            "jsonAvailable": true,
            "csvAvailable": true,
            "xlsxAvailable": true
        }
    }
}