Repository files navigation

This repository holds the Acumos R Client(https://gerrit.acumos.org/r/acumos-R-client) which helps provide a way to use R in the Acumos Platform.It has to be used in conjunction with the Model Runner (https://gerrit.acumos.org/r/generic-model-runner).

Please see the documentation in the "docs" folder.

Under Debian/Ubuntu, please installremotes andacumos dependencies first:

apt-get updateapt install -y libssl-dev libcurl4-openssl-dev make protobuf-compiler libprotoc-dev libprotobuf-dev

Installacumos:

install.packages("acumos")

To install this development version, please useremotes ordevtools:

remotes::install_github("acumos/acumos-r-client", subdir="acumos-package")

or

devtools::install_github("acumos/acumos-r-client", subdir="acumos-package")

To create a deployment component, useacumos::compose() with the functions to expose. If type specs are not defined, they default toc(x="character").

The component consists of a bundlecomponent.zip which is a ZIP file withmeta.json defining the component and its metadata,component.bin the binary payload,component.proto with the protobuf specsandcomponent.swagger.yaml with the Swagger API definition.

Please consult R documentation page for details, i.e., use?compose in R.

Example:

if(!require("randomForest")) install.packages("randomForest")library(randomForest)library(acumos)compose(predict=function(..., inputs=lapply(iris[-5], class)) as.character(predict(rf, as.data.frame(list(...)))),    aux = list(rf = randomForest(Species ~ ., data=iris)),    name="Random Forest",    file="component.zip"    )

You can also compose your model bundle directly from the R source code you used to build your model.

A regular component source code file is an R script in which at least one of the three following functions are defined:acumos_predict,acumos_transform oracumos_fit. They respectively correspond to the functionspredict,transformandfit ofcompose(). In that script, if the functionsacumos_generate,acumos_service oracumos_initialize are defined,they will also correspond to the other function type arguments ofcompose(), namelygenerate,service andinitialize.

acumos::composeFromSource(file = "path/to/your/R/script/acumos.R",    name = "MyComponentName",    outputfile = "component.zip",    addSource = TRUE)

TheaddSource parameter is a boolean that allows you to add the R source code (component.R) in your model bundle.

The path to an example component source code file can be found by executing the following R command:

print(system.file("examples", "example_0", "acumos.R", package = "acumos"))

To run the component you have to create aruntime.json file with at least{"input_port":8100} or similar to define which port the component should listen to. If there are output components there should also be a"output_url" entry to specify where to send the result to. It can be either a single entry or a list if the results are to be sent to multiple components. Example:

{"input_port":8100, "output_url":"http://127.0.0.1:8101/predict"}

With the component bundlecomponent.zip plusruntime.json in place the component can be run using

R -e 'acumos:::run()'

Therun() function can be configured to set the component directory and/or location of the component bundle. If you don't want to create a file, theruntime parameter also accepts the runtime structure, so you can also use

R -e 'acumos:::run(runtime=list(input_port=8100, data_response=TRUE))'

See also?run in R.

Once the model bundle is created, you can use thepush() API client to on-board it on Acumos. This is CLI(Command Line Interface) on-boarding. An example R command is the following:

acumos::push(url = "https://<hostname>/onboarding-app/v2/models",    file = "component.zip",    token = "<username>:<token>",    create = FALSE, deploy = FALSE,    license = "path/to/your/license.json")

url: can be found in the ON-BOARDING MODEL page of your Acumos portal and looks like :<hostname>/onboarding-app/v2/models

file: component.zip (your model bundle)

username : your Acumos username

token: API token available in the Acumos portal in your profile section

create : logical parameter (Boolean) to trigger the creation of microservice at the end ofon-boarding process. By defaultcreate = TRUE, if you don't want to create the microservice modify thevalue to FALSE (create = FALSE)

deploy : logical parameter (Boolean) to trigger the deployment of microservice at the end ofon-boarding process. By defaultdeploy = FALSE, if you want the Acumos platform to deploy automaticallythe microservice modify the value to TRUE (deploy = TRUE). Note that this parameter cannot takethe value TRUE, when the parametercreate takes the value FALSE.

license: path to the license profile file : The license profile file name must be "license.json".

Rather than creating the model bundle withcompose() and then on-boarding it withpush(), you can use thepushFromSource() function that allow you to on-board your model directly from your R source code and put this Rsource code inside the model bundle.

acumos::pushFromSource(url = "https://<hostname>/onboarding-app/v2/models",file = "path/to/your/R/script/acumos.R",name = "MyComponentName", addSource = FALSE,token = "<username>:<token>",create = FALSE, deploy = FALSE,license = "path/to/your/license.json")

The path to an example component source code file can be found by executing the following R command:

print(system.file("examples", "example_0", "acumos.R", package = "acumos"))

The use of API token is recommended to avoid typing your password in command line, but you can also authenticate yourself by using theauth() API:

acumos::auth("https://<hostname>", "username", "password")

url: can be found in the ON-BOARDING MODEL page of your Acumos portal and looks like "https:///onboarding-app/v2/auth"

username : your Acumos username

password : your Acumos password

In response, you will receive an authentication token to be used in thepush() orpushFromSource() function instead of ":"

Whatever the function you used, at the end of a successful CLI on-boarding with microservice creation, you will receive a message with the Acumos docker URIof your model.

You can also drag & drop your model bundle on the "ON-BORADING BY WEB" page in your Acumos instance,or browse you model bundle from this page. This is Web on-boarding.

You can on-board your model with a license profile, you just have to browse your license profile file or drag and drop it.

Whatever the case, CLI or WEB on-boarding, if the license profile file extension is not 'json' the licenseon-boarding will not be possible and if the name is not 'license' Acumos will rename your licensefile as license.json and you will see your license profile file as "license-1.json" in the artifacts table.If you upload a new version of your license through the portal, the license number revision will beincreased by one like that "license-2.json". To help user create the license profile file expected by Acumosa license profile editor user guide is available here :https://docs.acumos.org/en/latest/submodules/license-manager/docs/user-guide-license-profile-editor.html