Query TANGO Models

note

At the moment of writing this documentation, the TANGO Public API server to make the requests is hosted at this link.

Query the Metadata of a TANGO Model

GET /api/model/{modelCode}/version/{modelVersion}

Retrieves the metadata of a specific TANGO Model identified by its modelCode and modelVersion.

In a different way with respect to the List TANGO Models endpoint, this method returns also the explainer model metadata associated with the requested model. The explainers are returned in a nested structure, meaning that each model metadata contains the metadata of its explainer model, if available.

Explainable TANGO Models will therefore have an additional field explainer_metadata in the response, which contains the metadata of the explainer model associated with the main model.

• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1

Response Format

If successful, it returns the metadata of the requested model, including its explainer model if available.

For example:

{
  "model_code": "proto_model",
  "name": "proto-model",
  "description": "proto-model is the best ever!",
  "version": "1",
  "workspace": "default_workspace",
  "realtime_execution": false,
  "allow_download": false,
  "need_context": false,
  "input_schema": {},
  "output_schema": {},
  "native_metadata": {},
  "explainer_metadata": {
    "model_code": "proto_model_explainer",
    "name": "proto-model-explainer",
    "description": "proto-model-explainer is the best ever!",
    "version": "1",
    "workspace": "default_workspace",
    "realtime_execution": false,
    "allow_download": false,
    "need_context": false,
    "input_schema": {},
    "output_schema": {},
    "native_metadata": {}
  }
}

Attributes

Name	Type	Description
realtime_execution	boolean	Indicates if the model supports real-time execution.
allow_download	boolean	Indicates if the model can be downloaded.
need_context	boolean	Indicates if the model requires the session context for execution. All explainers should have this attribute set to True.
input_schema	object	The schema of the model input data.
output_schema	object	The schema of the model output data.
native_metadata	object	Additional metadata specific to the model implementation.
explainer_metadata	object	Metadata of the explainer model associated with the main model, if available.

Notes

• Every TANGO Model can only have one explainer model associated with it.

Invoke a TANGO Model

POST /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation

Invokes a specific TANGO Model (identified by modelCode and modelVersion) within a given TANGO Session ( identified by sessionId).

This endpoint allows users to create an invocation for a model within a session, providing the necessary input data.

• The available TANGO Models can be listed using the apposite method as shown in List TANGO Models.
• To use a TANGO Model, you must first create a session for it using the Start a new Session endpoint.
• Requires bearer token authentication (bearerAuth).

Path Parameters

Name	Type	Required	Description	Example
modelCode	string	Yes	The unique code identifying the model.	proto_model
modelVersion	string	Yes	The version of the model.	1
sessionId	string	Yes	The identifier of the session.	1

Request Body

The body of the request should contain data defining the type of invocation to perform, as well as the model input data.

The input parameters are:

• type: A string indicating the type of invocation (PREDICT or EXPLAIN).
• request: An object containing information about the invocation request. The request object should include:
  • type: A string indicating the type of request (FEATURES, PROMPT, FEEDBACK or OTHER).
  • body: A string containing the input data for the model.

For example:

{
  "order": 1,
  "type": "PREDICT",
  "request": {
    "type": "FEATURES",
    "body": "{'invocation_request_key': 'invocation_request_value'}"
  }
}

Response Format

If successful, it returns the details of the newly created invocation.

For example:

{
  "id": "1",
  "order": 0,
  "type": "PREDICT",
  "request": {
    "session_id": "1",
    "request_type": "FEATURES",
    "body": "{'invocation_request_key': 'invocation_request_value'}"
  },
  "status": "QUEUED",
  "response": "",
  "model_key": ""
}

Check the Result

You can then check the result of the invocation by making a GET request to the endpoint:

GET /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation/{invocationId}

Where invocationId is the ID of the invocation you just created before ("id": "1" in the previous example).

After the request has been processed, you will see its status updated as well as the response data.

Notes

• The method will return an error if the session does not exist for the specified model code and version for the authenticated user.
• The invocation is not executed immediately, but instead is queued for processing.
• The model_key attribute is used to reference the explanation model when used.
• You can also invoke the model and automatically request its explanation by using the with_explanation flag, as described in the next section.

Ask for Explanation

The explanation of a model invocation can be requested in two main ways:

1. Using the EXPLAIN type in the invocation request: This is done by specifying the type as EXPLAIN in the invocation request body when invoking the model. In this case the model to be invoked (defined by modelCode and modelVersion) must be the explanation model.
2. Using the flag with_explanation in the invocation: When invoking a model, you can set the with_explanation flag to true. This will trigger the explanation model to be invoked automatically after the main model invocation is completed.

EXPLAIN Invocation Type

When you want to obtain only the explanation of a model invocation, you can directly query the explanation model by specifying the EXPLAIN type in the invocation request body.

In a similar way to the invocation of a model (as shown in Invoke a TANGO Model), you can make a POST request to the endpoint:

POST /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation

Where modelCode and modelVersion refer to the explanation model.

With the request body structured as follows:

{
  "order": 1,
  "type": "EXPLAIN",
  "request": {
    "type": "FEATURES",
    "body": "{'invocation_request_key': 'invocation_request_value'}"
  }
}

The request body will depend on the type of explanation model you are using.

with_explanation Flag

When invoking a model, you can set the with_explanation flag to true to automatically trigger the explanation model invocation after the main model invocation is completed.

In particular, the explanation tree will be invoked in a recursive way, meaning that if the main model has an explainer associated with it, the explainer will be invoked and its own explainer will be invoked as well, and so on.

To use this feature, you can make a POST request to the endpoint:

POST /api/model/{modelCode}/version/{modelVersion}/session/{sessionId}/invocation

Where modelCode and modelVersion refer to the main model.

With the request body for example structured as follows:

{
  "order": 1,
  "type": "PREDICT",
  "request": {
    "type": "FEATURES",
    "body": "{'invocation_request_key': 'invocation_request_value'}"
  },
  "with_explanation": true
}

Besides the addition of the with_explanation flag, the remaining aspects of the request are similar to the standard invocation request explained in Invoke a TANGO Model.

• Requires bearer token authentication (bearerAuth).

Notes

• The explanation invocation will be created and queued automatically only AFTER the main model invocation has been successfully processed.
• The status of each request created in this way will be updated only according to that particular invocation. This means that if the explainer invocation fails, the invocation status of the main model will remain unchanged to COMPLETED. The same applies to successive explainers of explainers.