@coherentglobal/wasm-runner

WASM Runner

For managing and executing WASM on browser, mobile and NodeJS applications.

Here's a Demo App for reference.

Getting Started

Prerequisites

Here are the tools that you need for your setup.

• NodeJS (we recommend to use v20 or later) for running and developing this project.

• AWS CLI for publishing and downloading this package. Once installed, create a profile name manila-dev then execute the command below:

  aws sso login --profile manila-dev;
  aws codeartifact login --tool npm --repository coherent-global --domain coherent-global --domain-owner 792307798794 --region ap-southeast-1 --profile manila-dev

  This should update your .npmrc. To confirm, you may check if you have this line and if tokens are updated.

  @coherentglobal:registry=https://coherent-global-792307798794.d.codeartifact.ap-southeast-1.amazonaws.com/npm/coherent-global/

Install

To have it installed in your new project, run this command.

npm install "@coherentglobal/wasm-runner"

or

yarn add "@coherentglobal/wasm-runner"

Usage

Browser ( HTML )

Runner can be used in an HTML by adding the minified JS file to your project.

<script src="https://wasm-runner-sdk.s3.ap-southeast-1.amazonaws.com/wasmrunner.min.js"></script>

Have your javascript initialize the model and run some values through the execute function.

/**
 * `id` defines the model version ID and the `url` is
 * the path of the zip relative to this file.
 */
const modelConfig = {
  id: "f30f5935-36c2-4155-aede-523ab2245fd6",
  url: "<zip url>",
};

/**
 * Input values to be executed on the model. The structure and sample
 * data can be found on Spark API Tester.
 */
const payload = {
  request_data: {
    inputs: {
      age: 60,
      insure: "Insure",
      medical: "Yes",
      plan: "Plan 1",
    },
  },
  request_meta: {
    service_uri: "",
    service_uuid: "",
    version: "",
    version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
    transaction_date: "2021-08-18T04:17:17.142Z",
    call_purpose: "postman_request",
    source_system: "",
    correlation_id: "",
    requested_output: "",
  },
};

const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
  .execute(payload)
  .catch((err) => console.log(err));

// Do something with the response

ReactJS

You may follow the normal installation follow then import the packge into your project.

import { WasmRunner } from "@coherentglobal/wasm-runner";

Then do model initialize and execute.

/**
 * `id` defines the model version ID and the `url` is
 * the path of the zip relative to this file.
 */
const modelConfig = {
  id: "f30f5935-36c2-4155-aede-523ab2245fd6",
  url: "<zip url>",
};

/**
 * Input values to be executed on the model. The structure and sample
 * data can be found on Spark API Tester.
 */
const payload = {
  request_data: {
    inputs: {
      age: 60,
      insure: "Insure",
      medical: "Yes",
      plan: "Plan 1",
    },
  },
  request_meta: {
    service_uri: "",
    service_uuid: "",
    version: "",
    version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
    transaction_date: "2021-08-18T04:17:17.142Z",
    call_purpose: "postman_request",
    source_system: "",
    correlation_id: "",
    requested_output: "",
  },
};

const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
  .execute(payload)
  .catch((err) => console.log(err));

// Do something the response

NodeJS

You may follow the normal installation flow then import the packge into your project.

const { WasmRunner } = require("@coherentglobal/wasm-runner");

/**
 * `id` defines the model version ID and the `url` is
 * the path of the zip relative to this file.
 */
const modelConfig = {
  id: "f30f5935-36c2-4155-aede-523ab2245fd6",
  url: "<zip url>",
};

/**
 * Input values to be executed on the model. The structure and sample
 * data can be found on Spark API Tester.
 */
const payload = {
  request_data: {
    inputs: {
      age: 60,
      insure: "Insure",
      medical: "Yes",
      plan: "Plan 1",
    },
  },
  request_meta: {
    service_uri: "",
    service_uuid: "",
    version: "",
    version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
    transaction_date: "2021-08-18T04:17:17.142Z",
    call_purpose: "postman_request",
    source_system: "",
    correlation_id: "",
    requested_output: "",
  },
};

const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
  .execute(payload)
  .catch((err) => console.log(err));

Ways to load and initialize model

WASM Runner parameter

You may pass the cofig parameters directly to WasmRunner class whenever you create an instance.

const wasmRunner = new WasmRunner({
  id: "f30f5935-36c2-4155-aede-523ab2245fd6",
  url: "<zip url>",
});

// Trigger initialize to load the passed model
await wasmRunner.initialize();

Append

Pass the model config to append function after instantiation.

const wasmRunner = new WasmRunner();
// Pass the config details to `append` function
await wasmRunner.append({
  id: "f30f5935-36c2-4155-aede-523ab2245fd6",
  url: "<zip url>",
});

Combination of both

For scenarios that you need to load a lot of models, you may do both. During the instance creation, you may pass a list of configs to WasmRunner then do append for additional models.

const initialModels = [
  {
    id: "f30f5935-36c2-4155-aede-523ab2245fd6",
    url: "<zip url>",
  },
  {
    id: "a5gf5935-36c2-6621-aede-a41ab226aa53",
    url: "<zip url>",
  },
];

const additionalModel = {
  id: "e8ba9e7e-169c-4752-8a8e-d6eb0c78cb01",
  url: "<zip url>",
};

const wasmRunner = new WasmRunner(initialModels);
await wasmRunner.initialize();
await wasmRunner.append(additionalModel);

const response = await wasmRunner
  .execute(payload)
  .catch((err) => console.log(err));

Development

Setup

Clone the repo, then install the dependencies

$ git clone https://github.com/CoherentCapital/wasm-runner-js.git
$ yarn install

Test

yarn test

Build

For generating distribution package

yarn build

Functions

initialize()

Triggers the loading and integration of WASM files to Runner module. This step is required before the execute step.

Returns: Promise<void>

append(modelConfig)

Could be an alternative to initialize(). This loads additional model that you might need during execute after the Runner instantiation.

Returns: Promise<void>

execute(payload)

Performs the model calculation. Most common approach, Runner will use request_meta.version_id from the payload to locate the model to execute. So it is necessary to ensure that the model is loaded, could be through Runner instantiation or via append.

Returns: Promise<Object>

isExist(id)

Checks if model exists from the list of initialized models.

Returns: Promise<Boolean>

remove(id)

Removes a model. This is the way to clean up memory allocation for unused loaded models.

Returns: Promise<void>

Limitations

Lower Level Error

Please note that if there's lower level error that occurs, wasm runner can't handle that kind of exception.