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

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
success boolean was the train job submitted successfully
models array list of uuid’s generated for each model in the project
project_name string the project_name submitted in the request
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/train -H 'Content-Type:application/json' -d '{"project_name": "test", "file_path": "/DM-Dash/test_studio/test.nml"}'

Example response (successful):

{
    "success":true,
    "models":["S1zg8XhQf-0","S1zg8XhQf-1"],
    "project_name":"test"
}

Example response (error):

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

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
model_id array list of model_id’s to set to status TRAINING_TERMINATED

Response Body Parameters:

Parameter Data Type Description
*success string If training was stopped for the provided models
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/stop -H 'Content-Type: application/json' -d '{"model_id": [ "S1zg8XhQf-0", "S1zg8XhQf-1" ]}'

Example response (success):

{
    "success":true
}

Example response (error):

{
  "error": "no models are training or waiting to train"
}

info

Returns the database collection document associated with project_name or query_id respectively. The database collections are described here.

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

Request Body Parameters:

Parameter Data Type Description
*project_name string name of a project submitted for training
*query_id string id associated with a submitted query job

Response Body Parameters:

Parameter Data Type Description
_id string _id key value used as the index in the database
* * the entire database document is returned; its structure varies by collection
*error string error message
*info string other information string

cURL example:

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

Example response:

{
    "_id":"test",
    "uuid":"Sk2eUm2mz",
    "path":"/DM-Dash/projects/test",
    "models":["Sk2eUm2mz-0","Sk2eUm2mz-1"],
    "num_models":"2",
    "completed":0
}

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/list

Request Body Parameters:

Parameter Data Type Description
*project_name string name of a project to list all models for
*model_id string a specific model to list information for

Response Body Parameters:

Parameter Data Type Description
* * database document, or an array of documents
*error string error message
*info string other information string

cURL example (List all projects):

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

Example response (one project in list):

[
    {
        "_id":"test",
        "uuid":"Sk2eUm2mz",
        "path":"/DM-Dash/projects/test",
        "models":["Sk2eUm2mz-0","Sk2eUm2mz-1"],
        "num_models":"2",
        "completed":2
    }
]

cURL example (List project_name):

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

Example response:

[
    {
        "_id":"Sk2eUm2mz-0",
        "path":"/DM-Dash/projects/test/Sk2eUm2mz-0",
        "train_id":"test",
        "status":"TRAINING_COMPLETED",
        "time_updated":"2018-01-04 22:09:28.446049",
        "auto":{"auto":[{"conv_1":"64"}]},
        "headers":["val_loss","val_acc","loss","acc"],
        "val_loss":[2.308385491371155, 2.3128185987472536, 2.355952429771423, 2.3721513986587524, 2.376945662498474],
        "val_acc":[0.10000000149011612, 0, 0, 0.10000000149011612, 0.20000000298023224],
        "loss":[5.166418340471056, 2.8731135924657187, 2.043014599217309, 1.5508959657616086, 1.2481874128182728],
        "acc":[0.1444444465968344, 0.23333333929379782, 0.3444444512327512, 0.42222223182519275, 0.600000009768539]
    },
    {
        "_id":"Sk2eUm2mz-1",
        "path":"/DM-Dash/projects/test/Sk2eUm2mz-1",
        "train_id":"test",
        "status":"TRAINING_COMPLETED",
        "time_updated":"2018-01-04 22:10:01.017527",
        "auto":{"auto":[{"conv_1":"128"}]},
        "headers":["val_loss","val_acc","loss","acc"],
        "val_loss":[2.3198147296905516, 2.3034270763397218, 2.354711389541626, 2.3634750843048096, 2.443640041351318],
        "val_acc":[0, 0.0800000011920929, 0, 0.180000002682209, 0.0800000011920929],
        "loss":[5.1362545357810125, 2.4682129157914057, 2.0315925214025707, 1.6034690174791548, 1.0303350935379665],
        "acc":[0.13333333532015482, 0.2666666722959942, 0.30000000695387524, 0.4111111205485132, 0.6888889032933447]
    }    
]

cURL example (List model_id):

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

Example response:

{
    "_id":"Sk2eUm2mz-0",
    "path":"/DM-Dash/projects/test/Sk2eUm2mz-0",
    "train_id":"test",
    "status":"TRAINING_COMPLETED",
    "time_updated":"2018-01-04 22:09:28.446049",
    "auto":{"auto":[{"conv_1":"64"}]},
    "headers":["val_loss","val_acc","loss","acc"],
    "val_loss":[2.308385491371155, 2.3128185987472536, 2.355952429771423, 2.3721513986587524, 2.376945662498474],
    "val_acc":[0.10000000149011612, 0, 0, 0.10000000149011612, 0.20000000298023224],
    "loss":[5.166418340471056, 2.8731135924657187, 2.043014599217309, 1.5508959657616086, 1.2481874128182728],
    "acc":[0.1444444465968344, 0.23333333929379782, 0.3444444512327512, 0.42222223182519275, 0.600000009768539]
}

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
success boolean successfully returned top models
top array array of strings in a human readable format for top models
*error string error message
*info string other information string

cURL example:

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

Example response:

{
    "success":true,
    "top":["model: Sk2eUm2mz-1 iter: weights-004.model acc: 0.6888889032933447"]
}

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 weights file 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 was the train job submitted successfully
models array list of uuid’s generated for each model in the project
query_id string uuid generated for this query job
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/query -H 'Content-Type: application/json' -d '{"model_id": "Sk2eUm2mz-1","model_iter": "weights-004.model", "csv": "/DM-Dash/test_studio/query.csv"}'

Example response:

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

Results

Similar to list, 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 string return the .csv for this query_id in the response

Response Body Parameters:

Parameter Data Type Description
*success string if reading the results was successful
*results string database document, or an array of documents
* * document or array of documents in the query collection
*error string error message
*info string other information string

cURL example results for a query_id:

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

Example Response:

{
    "_id":"ryfHIQ3XM",
    "status":"QUERY_COMPLETED",
    "time_updated":"2018-01-04 22:10:11.668449",
    "path":"/DM-Dash/query_results",
    "csv_path":"/DM-Dash/test_studio/query.csv",
    "model_id":"Sk2eUm2mz-1",
    "model_iter":"weights-004.model",
    "result_path":"/DM-Dash/query_results/ryfHIQ3XM.csv"
}

cURL example retrieving results for a query_id using show:

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

Example Response:

{
    "success":true,
    "results":"7.899592071771621704e-02,8.888762444257736206e-02,3.699111193418502808e-02,1.532766669988632202e-01,2.468210458755493164e-01,7.835777848958969116e-02,6.246567890048027039e-02,7.288023829460144043e-02,7.770781964063644409e-02,1.036161705851554871e-01\n9.234872460365295410e-02,8.732064813375473022e-02,4.415083676576614380e-02,1.170373708009719849e-01,2.183997631072998047e-01,1.144875660538673401e-01,5.782150849699974060e-02,6.450401246547698975e-02,9.527406096458435059e-02,1.086555346846580505e-01\n1.123168990015983582e-01,7.283395528793334961e-02,5.184032768011093140e-02,1.088215634226799011e-01,2.290325313806533813e-01,7.215893268585205078e-02,5.400124937295913696e-02,6.886436045169830322e-02,1.201111823320388794e-01,1.100188568234443665e-01\n",
    "_id":"ryfHIQ3XM"
}

Example response for a query that failed:

{
    "_id": "BkTd4OFXM",
    "status": "ERROR",
    "time_updated":
    "2018-01-02 21:07:00.813117",
    "path": "/DM-Dash/query_results",
    "csv_path": "/DM-Dash/test_studio/quer.csv",
    "model_id":"Sk2eUm2mz-1",
    "model_iter":"weights-004.model",
    "error": "CSV Path DNE csv_path=/DM-Dash/test_npqr/quer.csv"
}

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 project_name to trim
model_id string model_id that contains the model_iter to save
model_iter string model_iter in the given model_id to save and not delete

Response Body Parameters:

Parameter Data Type Description
success string if trimming the project was successful
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/trim -H 'Content-Type: application/json' -d '{"project_name": "test", "model_id": "Sk2eUm2mz-1","model_iter": "weights-004.model"}'

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 model_id for a specific model in a trained project
model_iter string model_iter for a specific weights file associated with the model_id
*file_name string name to same file as: .pim

Response Body Parameters:

Parameter Data Type Description
success boolean was model successfully exported
saved_path string path of the pim file that was exported
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/export -H 'Content-Type: application/json' -d '{"project_name": "test", "model_id": "Sk2eUm2mz-1","model_iter": "weights-000.model"}'

Example response:

{
    "success":true,
    "saved_path":"/DM-Dash/exports/Sk2eUm2mz-1.pim"
}

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 you are importing

Response Body Parameters:

Parameter Data Type Description
success boolean successful import
*error string error message
*info string other information string

cURL example:

$ curl -s -X POST http://localhost:8081/api/ai/import -H 'Content-Type: application/json' -d '{"project_name": "test_import", "file_path": "/DM-Dash/exports/Sk2eUm2mz-1.pim"}'

Example response:

{
  "success": true
}

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 project_name to delete
*query_id string query_id to delete or 'all' to delete all queries

Response Body Parameters:

Parameter Data Type Description
success string if deleting the project or query was successful
*error string error message
*info string other information string

cURL example (removing an entire project):

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

Example response:

{
    "success":true,
    "info":"project test_import deleted"
}

cURL example (Clearing a query_id):

$ curl -s -X POST http://localhost:8081/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:8081/api/ai/delete -H 'Content-Type: application/json' -d '{"query_id": "all"}'

Example response:

{
    "success": true
}