REST APIs

NeoPulse® AI Studio exposes the following REST APIs on port 46921 of the machine to manage the training and querying of models.

delete

Delete can be used to remove an entire project, clear all the queries, or remove a specific queryID. Providing a project_name will completely remove the project from the instance. Deleting a queryID removes the query results from the instance.

Method Type Path
POST application/json /api/ai/delete

Request Body Parameters:

Parameter Data Type Description
*project_name String Name of the project that is to be deleted
*query_id String Query ID that is to be deleted
Note: “all” - will delete all the queries
*is_forceful Boolean Flag that will delete currently training projects if set to true

Note: Either project_name or query_id should be present

Response Body Parameters:

Parameter Data Type Description
success String Status of deleting the project or query
*error String Error message
*code Number Error code

cURL example (removing an entire project):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"project_name": "test_import"}'

Example response:

{
    "success":true
}

cURL example (Clearing a query_id):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "ryfHIQ3XM"}'

Example response:

{
    "success":true
}

cURL example (Clearing all queries):

$ curl -s -X POST http://localhost:46921/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "all"}'

Example response:

{
    "success": true
}

export

Exports a Portable Inference Model (PIM) file which can then be imported into NeoPulse® AI Studio or NeoPulse® Query Runtime running on a different instance.

Method Type Path
POST application/json /api/ai/export

Request Body Parameters:

Parameter Data Type Description
model_id String ID of a model in a trained project
model_iter Number Iteration number of a model that needs to be exported
output_path String Absolute path to a directory where the exported model needs to be saved
*file_name String Name to exported model file without extension <.pim>
Note: defaulted to model ID if this value is not provided

Response Body Parameters:

Parameter Data Type Description
success Boolean Status of model export job
*error String Error message
*code Number Error code if present

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/export -H 'Content-Type: application/json' -d '{"model_id": "test_1", "model_iter": 1, "output_path": "/path/to/desired/directory", "file_name": "<Name_of_output_file>"}'

Example response:

{
    "success":true
}

import

Import a model that was trained and exported elsewhere into NeoPulse® AI Studio.

Method Type Path
POST application/json /api/ai/import

Request Body Parameters:

Parameter Data Type Description
project_name String Name for this imported project
file_path String Absolute path to the PIM file that is being imported

Response Body Parameters:

Parameter Data Type Description
success Boolean Status of import job
*error String Error message
*code Number Error code

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/import -H 'Content-Type: application/json' -d '{"project_name": "test_import", "file_path": "/path/to/model.pim"}'

Example response:

{
    "success": true
}

list

List is used to get information about submitted training jobs. When providing a model_id the list API will return a document containing all available information for that model. If a project_name is provided, an array of documents for all the models associated with that project is returned. When the request doesn’t contain either a model_id or project_name an array of all the projects is returned.

Method Type Path
POST application/json /api/ai/list

Request Body Parameters:

Parameter Data Type Description
*model_id String ID of a model
*project_name String Name of the project

Response Body Parameters:

Parameter Data Type Description
*<name of the project> Object database document of the project
*<model ID> Object Database document of the model
*error String Error message
*code String Error code

cURL example (List all projects):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d ''

Assuming there are 3 projects.

[
    {
        "_id": "test_error",
        "error": "Unable to compile",
        "model_list": [],
        "name": "test_error10",
        "num_models": 0,
        "num_trained": 0,
        "status": "ERROR",
        "uuid": "BJwe6pPVLN",
        "version": "3.0.0"
    },
    {
        "_id": "test",
        "model_list": [
            "test_1"
        ],
        "name": "test",
        "num_models": 1,
        "num_trained": 1,
        "status": "TRAINING_COMPLETED",
        "uuid": "SyVe6pDEU4",
        "version": "3.0.0"
    },
    {
        "_id": "test_import",
        "model_list": [
            "test_import_0"
        ],
        "name": "test_import",
        "num_models": 1,
        "num_trained": 1,
        "status": "IMPORTED_PROJECT",
        "uuid": "Skygga6v4UV",
        "version": "3.0.0"
    }
]

cURL example (List project_name):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d '{"project_name": "test"}'

Assuming the test project has 1 model.

{
    "test": [
        {
            "_id": "test_1",
            "acc": [
                0.4500000023841858,
                0.5599999964237213
            ],
            "auto": [
                {
                    "compile_9__0": "'categorical_crossentropy'"
                },
                {
                    "inp_size_e": 21862
                },
                {
                    "compile_8__0": "'adadelta'"
                },
                {
                    "2_0": [
                        {
                            "filter_length": 5
                        },
                        {
                            "pool_length": 7
                        },
                        {
                            "filters_cn": 112
                        },
                        {
                            "bi_lstm_size": 105
                        },
                        {
                            "lstm_size": 86
                        }
                    ]
                },
                {
                    "embed_dimension": 54
                }
            ],
            "loss": [
                0.6946831297874451,
                0.6927492642402648
            ],
            "metric_list": [
                "val_loss",
                "val_acc",
                "loss",
                "acc"
            ],
            "num_iterations": 2,
            "project_name": "test",
            "status": "TRAINING_COMPLETED",
            "time_updated": "2019-02-27 20:06:15",
            "val_acc": [
                0.4848484857515855,
                0.5353535455886764
            ],
            "val_loss": [
                0.693558607438598,
                0.692483000683062
            ],
            "version": "3.0.0"
        }
    ]
}

cURL example (List model_id):

$ curl -s -X POST http://localhost:46921/api/ai/list -H 'Content-Type: application/json' -d '{"model_id": "test_1"}'

Example response:

{
    "test_1": {
        "_id": "test_1",
        "acc": [
            0.4500000023841858,
            0.5599999964237213
        ],
        "auto": [
            {
                "compile_9__0": "'categorical_crossentropy'"
            },
            {
                "inp_size_e": 21862
            },
            {
                "compile_8__0": "'adadelta'"
            },
            {
                "2_0": [
                    {
                        "filter_length": 5
                    },
                    {
                        "pool_length": 7
                    },
                    {
                        "filters_cn": 112
                    },
                    {
                        "bi_lstm_size": 105
                    },
                    {
                        "lstm_size": 86
                    }
                ]
            },
            {
                "embed_dimension": 54
            }
        ],
        "loss": [
            0.6946831297874451,
            0.6927492642402648
        ],
        "metric_list": [
            "val_loss",
            "val_acc",
            "loss",
            "acc"
        ],
        "num_iterations": 2,
        "project_name": "test",
        "status": "TRAINING_COMPLETED",
        "time_updated": "2019-02-27 20:06:15",
        "val_acc": [
            0.4848484857515855,
            0.5353535455886764
        ],
        "val_loss": [
            0.693558607438598,
            0.692483000683062
        ],
        "version": "3.0.0"
    }
}

query

Used to submit a batch query job for a model that has completed training.

Method Type Path
POST application/json /api/ai/query

Request Body Parameters:

Parameter Data Type Description
model_id String model_id for a specific model in a trained project
model_iter String model_iter for a specific iteration number associated with the model_id
csv String absolute path to a csv file on the machine running NeoPulse® containing input to query

Response Body Parameters:

Parameter Data Type Description
success Boolean Query job submission status
query_id String uuid generated for this query job
*error String Error message
*code Number Error code if error

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "test_1","model_iter": "1", "csv": "/path/to/query.csv"}'

Example response:

{
    "success":true,
    "query_id":"ryfHIQ3XM"
}

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "test_error","model_iter": "1", "csv": "/query.csv"}' | python -m json.tool

Example response:

{
    "code": 261,
    "error": "Model or iteration of the model that is being queried is invalid."
}

results

Provided a specific query_id, it will return status of the query associated with that id. Additionally, the result CSV can be retrieved with this API if both a query_id and the show keys are provided in the request (assuming the status of the requested document is QUERY_COMPLETED).

Method Type Path
POST application/json /api/ai/results

Request Body Parameters:

Parameter Data Type Description
query_id String query_id in the query collection to return document for
*show Boolean return the results of query

Response Body Parameters:

Parameter Data Type Description
*results String Document of the results file
* * Query document
*error String Error message
*code Number Error code if in case of error

cURL example results for a query_id:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "SkH1L9J4V"}' | python -m json.tool

Example Response:

{
    "_id": "SkH1L9J4V",
    "input_file_path": "/absolute/path/to/query1.csv",
    "model_id": "test_1",
    "model_iter": "001",
    "status": "QUERY_COMPLETED",
    "time_updated": "2019-01-30 21:23:41",
    "version": "3.0.0"
}

When query results have error:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "H15oS91EN"}' | python -m json.tool

Example Response:

{
    "_id": "H15oS91EN",
    "error": "Error loading query CSV file.Make sure the number of columns are equal to the number of inputs and that they are in the same order used for training.",
    "input_file_path": "/absolute/path/to/query.csv",
    "model_id": "test_1",
    "model_iter": "001",
    "status": "ERROR",
    "time_updated": "2019-01-30 21:22:42",
    "version": "3.0.0"
}

cURL example retrieving results for a query_id using show:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "SkH1L9J4V", "show": true}' | python -m json.tool

Example Response:

{
    "_id": "SkH1L9J4V",
    "results": "0.4961142,0.50388587\n0.4962748,0.5037252\n0.49729934,0.50270057\n0.49726972,0.5027303\n0.49468577,0.5053143\n0.49725237,0.5027476\n0.49193063,0.50806934\n0.5004346,0.49956545\n0.5116662,0.4883339\n0.49684286,0.5031571\n0.50167054,0.49832943\n0.5005348,0.49946523\n0.4910176,0.5089825\n0.5018504,0.4981495\n0.49455598,0.505444\n0.50737834,0.49262166\n0.49599665,0.5040034\n0.4986556,0.5013443\n0.49964067,0.5003593\n0.4968565,0.50314355\n0.50329053,0.49670947\n0.50993,0.49006996\n0.5066415,0.49335846\n0.49716932,0.5028307\n0.4974647,0.5025354\n0.50237805,0.49762192\n0.50951856,0.4904814\n0.51113683,0.48886314\n0.4960988,0.50390124\n0.49836245,0.5016375\n0.49418578,0.5058142\n0.5093612,0.49063873\n0.49954656,0.5004534\n0.508187,0.491813\n0.49370107,0.5062989\n0.50705296,0.49294704\n0.50126415,0.49873585\n0.49884957,0.5011504\n0.5064257,0.49357435\n"
}

cURL response for a query when show is passed that failed:

$ curl -s -X POST http://localhost:46921/api/ai/results -H 'Content-Type: application/json' -d '{"query_id": "ry_ZSskN4", "show": true}' | python -m json.tool

Example Response:

{
    "code": 142,
    "error": "Unable to show the results for queries that are either not complete or contains error."
}

Real Time Query (RTQ) New in v4!

With this release of NeoPulse®, users now have the ability to deploy a model for real-time inference, in addition the batch query API discussed above. To support this functionality five new APIs have been added to enable users to deploy, list, redeploy, and remove real-time query (RTQ) models, as well as an API for performing the query.

To allow for flexible deployment, NeoPulse® allows the user to specify what port on which they would like to deploy a given model.

The default port is 46926.

realtime_query

This is the API for querying the deployed model. Please note that this API is on a different port from the rest of the APIs. That port is set when a model is deployed for RTQ.

It supports two data formats: text/csv and application/zip.

Method Type Path
POST text/csv OR application/zip /realtime_query

The request headers must include the following:

Rtq-Id: <String> - the unique rtq_id for the deployed model to query(see below).

Depending on the model output, the response will either be in the form of a CSV file with the query result, or a zip file containing the model output files. The content type in the response header will specify which one.

rtq/deploy

This API deploys a model for real-time query. Models deployed in this way will be available on a specific port, at the realtime_query API described below. Note that this is a different port from the rest of the APIs. By allowing users to specify a specific port, they can deploy models to dedicated ports, or have several models deployed to the same port, depending on the expected usage of the realtime_query API.

Method Type Path
POST application/json /api/ai/rtq/deploy

Request Body Parameters:

Parameter Data Type Description
model_id String valid model_id to deploy
model_iter int valid iteration for the given model_id
*rtq_id String unique rtq_id for the deployed model. If not provided, one will be automatically generated.
*port_number int valid port to expose for querying the model. Default value: 46926
*description String Text describing the model

Response Body Parameters:

Parameter Data Type Description
rtq_id String unique id for the RTQ model
success Boolean True
info {rtq_id:String, usage:String} unique rtq_id and instructions describing how to make the real-time query.
*error String Error description
*code Number Error ID

Example Response:

On Success:

{
    "success": <Boolean>,
    "info": {
                "rtq_id": <String>,
                "info": {
                    "rtq_id": <String>,
                    "usage": <String>
                }
            }
}

On Error:

{
    "error": <String> - Error description,
    "code": <Number>
}

rtq/list

This API lists all the models deployed for real-time query.

Method Type Path
POST application/json /api/ai/rtq/list

Request Body Parameters:

Parameter Data Type Description
*rtq_id String unique rtq_id for a deployed model.

If the list API is not passed an rtq_id, it will return a list of all the deployed real-time query models.

Response Body Parameters:

Parameter Data Type Description
success Boolean True
info list of rtq documents See below
*error String Error description
*code Number Error ID

Example Response:

On Success:
{
    "success": <Boolean>,
    "info": [
                {
                    "rtq_id": <String>,
                    "model_id": <String>,
                    "model_iter": <Number>,
                    "port_number": <Number>,
                    "description": <String>,
                    "lastModified": <String>,
                    "status": [ INIT | DEPLOYED | REMOVED | ERROR ],
                    "version": <String>
                },
                ...
            ]
}

On Error:

{
    "error": <String>,
    "code": <Number>
}

rtq/redeploy

This API allows the user to update an RTQ model that has already been deployed, i.e. the user can replace a model deployed to a particular rtq_id, with another model. This is useful for real-time query models deployed in production, as the underlying model can be updated, and existing infrastructure that calls the realtime-query API does not have to be changed in any way to take advantage of the new model.

Parameters:

Method Type Path
POST application/json /api/ai/rtq/redeploy

Request Body Parameters:

Parameter Data Type Description
rtq_id String The rtq_id of the deployed model to be replaced
model_id String valid model_id to deploy
model_iter int valid iteration for the given model_id
*description String Text describing the model

Response Body Parameters:

Parameter Data Type Description
success Boolean True
info {usage:String} instructions describing how to make the real-time query.
*error String Error description
*code Number Error ID

Example Response: On success:

{
    "success": <Boolean>,
    "info": {
                "usage": <String>
            }
}

On Error:

{
    "error": <String>,
    "code": <Number>
}

rtq/remove

This API removes the ability to interrogate a model using real-time query. It does not remove the model from NeoPulse®.

Parameters:

Method Type Path
POST application/json /api/ai/rtq/remove

Request Body Parameters:

Parameter Data Type Description
rtq_id String The rtq_id of the deployed model to be removed from RTQ

Response Body Parameters:

Parameter Data Type Description
success Boolean True
info String Confirmation that the model has been removed
*error String Error description
*code Number Error ID

Example Response: On success:

{
    "success": <Boolean>,
    "info": <String>
}

On Error:

{
    "error": <String>,
    "code": <Number>
}

status

This API can be used to check the NeoPulse® application status. If any of the components of the application which is needed for the correct functioning the application is down, it reports it with the info message.

Method Type Path
POST application/json /api/ai/status

Request Body Parameters:

Parameter Data Type Description

Response Body Parameters:

Parameter Data Type Description
status Boolean Status of NeoPulse® application
*info String Any information that is to be communicated to the user
*error String Error message
*code Number Error code

cURL example (successful status):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "status": true,
    "info": ""
}

cURL example (failure status):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "status": false,
    "info": "Some entities of NeoPulse® application is running. Please shutdown the NeoPulse® application with force flag and start it again."
}

cURL example (error):

$ curl -s -X POST http://localhost:46921/api/ai/status -H 'Content-Type:application/json' -d ''

Example response:

{
    "code": 380,
    "error": "Unknown error checking the status of NeoPulse® entities."
}

stop

Stops models from training. Models that are actively being trained will be stopped mid training and no more iterations will be completed. Models that are waiting to train on the queue will never start training.

Method Type Path
POST application/json /api/ai/stop

Request Body Parameters:

Parameter Data Type Description
project_name String Name of the project that needs to stop training

Response Body Parameters:

Parameter Data Type Description
success Boolean Signifies the result of stopping
stopped_models Array<String> List of model IDs that were successfully requested to be stopped
*code String Error code
*error String Error message

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/stop -H 'Content-Type: application/json' -d '{"project_name": "test"}'

Example response (success):

{
    "success":true,
    "stopped_models": ["test_1", "test_2"]
}

Example response (error):

{
    "code": 151,
    "error": "Cannot stop project that is neither training nor waiting to be trained."
}

top

Sort the models in a given project by the metric provided, and return the top model iterations.

Method Type Path
POST application/json /api/ai/top

Request Body Parameters:

Parameter Data Type Description
project_name String name of the project to list
metric String sorting metric
top_num Number number of top models to return

Response Body Parameters:

Parameter Data Type Description
top_models Array<Object> Array of objects that contains the details of the model in a sorted order
*error String Error message
*code String Error code

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/top -H 'Content-Type: application/json' -d '{"project_name": "test", "metric": "acc", "top_num": 1}'

Example response:

{
    "success": true,
    "top_models": {
        "is_training": false,
        "model_list": [
            {
                "iteration_num": 2,
                "metric_value": 0.5899999928474426,
                "model_id": "test_2",
                "print_format": "model: test_2 iter: 2"
            }
        ]
    }
}

cURL example:

curl -s -X POST http://localhost:46921/api/ai/top -H 'Content-Type: application/json' -d '{"project_name": "test_error", "metric": "acc", "top_num": 2}'

Example response:

{
    "code": 164,
    "error": "The project document is curpt try training the project again."
}

train

Used to submit a training job.

Method Type Path
POST application/json /api/ai/train

Request Body Parameters:

Parameter Data Type Description
*project_name String Name for the project
file_path String Absolute path to the nml script for the training job
*is_overwrite Boolean Flag that will delete any existing project of the same name if set to true

Note: If project_name is not provided, then the NML file name will be used

Response Body Parameters:

Parameter Data Type Description
project_id Integer ID of the project
project_name String Name of the project that was given by the user
*error String Error message
*code String Error code

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/train -H 'Content-Type:application/json' -d '{"project_name": "test", "file_path": "/path/to/nml/file"}'

Example response (successful):

{
     "project_id":S1zg8XhQf,    "project_name":"project_name"
}

Example response (error):

{
    "code": 406,
    "error": "Can not use a project_name that already exists"
}

trim

Permanently deletes all models and model iterations except for the provided model_id and model_iter for a given project. Trim should be used after training has completed to avoid running out of disk space on the root drive. Once you have viewed the metrics of trained models you should remove all the models except the top performing model, which is also likely the one you would want to export for use elsewhere.

Method Type Path
POST application/json /api/ai/trim

Request Body Parameters:

Parameter Data Type Description
project_name String Name of the project that is to be trimmed
model_id String ID of the model that is selected
model_iter Number Iteration number of the model which is being saved

Response Body Parameters:

Parameter Data Type Description
success Boolean True if trimming the project was successful
False otherwise
*error String Error message
*code Number Error Code if in case of error

cURL example:

$ curl -s -X POST http://localhost:46921/api/ai/trim -H 'Content-Type: application/json' -d '{"project_name": "test", "model_id": "test_1",  "model_iter": 1}'

Example response:

{
    "success": true
}

visualize

This API can be used to look at the architecture of the training that was performed. This either starts architecture visualization for a given project or shutdown any existing visualization. Providing the “project_name” will start the architecture visualization for the project and providing “shutdown” parameter with the valid Boolean value [true, false] will shut down any existing visualization session.

Method Type Path
POST application/json /api/ai/visualize

Request Body Parameters:

Parameter Data Type Description
*project_name String Name of the project that is to be deleted
*shutdown Boolean true – if any visualization session needs to be shut down
false – Otherwise

Note: At-least one of the parameters should be present. Also, having both with “shutdown” parameter set will result in error as it is an ambiguous request.

Response Body Parameters:

Parameter Data Type Description
success String Status of visualizing the project
*info String Success message that gives information on the task that was completed
*error String Error message
*code Number Error code

cURL example (visualizing a project):

$ curl -s -X POST http://localhost:46921/api/ai/visualize -H 'Content-Type: application/json' -d '{"project_name": "test"}'

Example response:

{
    "success": true,
    "info": "Successfully started to visualize on the port 6006 for the project: test"
}

cURL example (stopping visualization session):

$ curl -s -X POST http://localhost:46921/api/ai/visualize -H 'Content-Type: application/json' -d '{"shutdown": true}'

Example response:

{
    "success": true,
    "info": "Successfully shutdown running visualization."
}