Digital Genius Javascript SDK

Overview

Digital Genius Javascript SDK (digital-genius-javascript-sdk) is a JavaScript library utilizing Digital Genius' middleware API.

The API is fully asynchronous. All methods require an "apiKey" parameter and a callback function.

Usage

Ask

The ask method encapsulates access to the middleware API's "batch" endpoint, specifically eliminating the need for separate "createLog" and subsequent "prediction" call.

It takes a map of parameters with the following keys:

• params['modelgroupId']
• params['externalId']
• params['logExternalId']
• params['logMessageExternalId']
• params['showTopBestAnswers']
• params['logMessageCreatedAt']
• params['logMessageExternalId']
• params['id']
• params['chatLogId']
• params['externalId']
• params['content']
• params['from']
• params['language']
• params['channel']
• params['answerIds']
• params['metadata']
• params['query']

Example

dg.ask(params, API_KEY, function (response) {
    var confidence = response.answers[0].confidence;
    var answer = response.answers[0].automationTemplate;
    console.log(answer + " with " + confidence);
});

Create Log

The createLog method allows for explicit creation of a log in the API. It accepts a JSON object that has keys for query and modelgroupid.

It takes a map of parameters with the following keys:

• params['modelgroupId']
• params['externalId']
• params['logExternalId']
• params['logMessageExternalId']
• params['showTopBestAnswers']
• params['logMessageCreatedAt']
• params['logMessageExternalId']
• params['id']
• params['chatLogId']
• params['externalId']
• params['content']
• params['from']
• params['language']
• params['channel']
• params['answerIds']
• params['metadata']
• params['query']

Example

params = {
     "modelgroupId": "17cc6e32-ee95-4b8d-ae78-58c56e659d90",
     "query" : "Can I bring my bike on the train?"
}

dg.createLog(params, API_KEY, function(response) {
    console.log(response.id);
    console.log(response.modelgroupId);
    console.log(response.createdAt);
    console.log(response.externalId);
    console.log(response.metadata.length);
 });

Prediction

The prediction method extracts a prediction from a previously created log using its modelId.

It takes a map of parameters with the following keys:

• params['modelgroupId']
• params['externalId']
• params['logExternalId']
• params['logMessageExternalId']
• params['showTopBestAnswers']
• params['logMessageCreatedAt']
• params['logMessageExternalId']
• params['id']
• params['chatLogId']
• params['externalId']
• params['content']
• params['from']
• params['language']
• params['channel']
• params['answerIds']
• params['metadata']
• params['query']

Example

params = {
    "modelgroupId": "17cc6e32-ee95-4b8d-ae78-58c56e659d90",
    "query" : "Can I bring my bike on the train?",
    "logExternalId": "ID_EXTERNAL_message_123abc",
    "logMessageExternalId": "ID_EXTERNAL_message_123abc"
}

sdk.prediction(params, API_KEY, function(response) {
    console.log(response.id);
    console.log(response.createdAt);
    console.log(response.logId);
    console.log(response.messageId);
    console.log(response.prediction.answers.length);
});

Installing the Module Locally

There are two ways to use the module locally.

The first way is via npm link. In the root of this project run the following:

npm link

Then in the project using digital-genius-javascript-sdk as a dependency run the following:

npm link digital-genius-javascript-sdk

The other approach, useful if deploying in an Alexa Skill project, is to install the module directly in the project. This can be done as follows.

In the root of this project run the following:

npm pack .

This will create a file named "digital-genius-javascript-sdk-1.0.0.tgz" in the current directory.

In your project's directory run the following:

npm install /path/to/digital-genius-javascript-sdk-1.0.0.tgz

Testing Setup

You will need the following dependencies:

npm install dotenv

This dependency allows for environment specific configs and uses the .env file located in the project root (https://github.com/motdotla/dotenv).

If there is a .env file then notice that we have the following setting. This is also the default value should a .env file not exist.

BASE_URL=https://demo-api.us.dgdeepai.com/api/v1/qa/

If running locally against mock service then just use BASE_URL = http://localhost:3000/. Within the index.js file located in the project root, we can use the dependency by first declaring the config and then leveraging it to get the environment property in the following manner:

require('dotenv').config()
var config = require('config');
...

uri: config.get('ask_url')

npm install -g json-server

This installs a Node module, running an Express server, that lets you specify a JSON file to act as a data source for you mock REST API (https://github.com/typicode/json-server).

Notice how this is set up in server.js file within the /mock directory. There are endpoints with specific http response codes and payloads.

From the command line navigate to the /mock directory and issue the following command:

node server.js

You should end up seem something similar to this:

$ node server.js
JSON Server is running on port 3000

If you run into issues starting up the mock server then you likely need to run npm link from within the /mock directory.

npm link json-server

There are some known issues and some work arounds documented here (https://github.com/typicode/json-server/issues/454 )

Finally, you will need to install the testing framework Mocha (https://mochajs.org/).

npm install mocha

Once thats done, navigate to the project root/test directory and run the test cases.

If the requests are making it to your mock server you will notice information be logged to console about every request.

$ node server.js
JSON Server is running on port 3000
POST /ask 200 2.800 ms - 210
POST /createLog 201 0.364 ms - 621
POST /prediction 201 0.425 ms - 1342

Generated Documentation

Documentation can be generated via jsdoc (http://usejsdoc.org/)

You can install jsdoc as follows:

$ npm install -g jsdoc

And the documentation can be generated with the following command:

$ jsdoc -d docs index.js