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 PIM from the instance. Deleting a query removes the query from the database and deletes the .csv file containing the 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

Note: At-least one of the parameters 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 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 query the AI Collections Database about submitted training jobs. When providing a model_id the document for that model from the "Models" collection is returned. If a project_name is provided, an array of documents for all 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 in the "Train" collection is returned.

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

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
                        },
                        {
                            "nb_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
                    },
                    {
                        "nb_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 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 for a local csv file 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

Like LIST API, except results is for managing query submissions rather than those for training. If provided no keys are provided to the API, an array of all the documents in the query collection is returned. If provided a specific query_id, it will return just the document 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
* * Database document of the query
*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."
}

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

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. Renames the model file for that iteration to weights-000.model. When specifying model_iter, either the full filename (e.g. weights-097.model), or the iteration number (e.g. 97) may be used. 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."
}