Skip to content

Latest commit

 

History

History
406 lines (323 loc) · 9.19 KB

README.md

File metadata and controls

406 lines (323 loc) · 9.19 KB
Raw

Boilerplate for remote skill

Table of Contents

Authentication

Skill can authenticate incoming converse requests.

BY default - the skill will respond to any incoming converse request. By default it will not authenticate incoming converse requests to make sure that they are coming from a core that this skill is registered to. in order to enable such authentication, change the parameter AUTHENTICATE_REQUESTS to true in the '.env' configuration file

After enabling the authentication, all incoming calls to the skill will be authenticated using a key. The key is generated by the core when the skill is registered to the core, the key should be stored in the keys.txt file found in res/assets/keys.txt.

A key is also used in order to access the skill swagger page, in order to get access just add one of the keys in your key.txt file to the header (you can also create a new key).

JSON Interface Reference

Manifest

This section defines the skill configuration which is used by the core to access and control the skill.

{
    "name": "string",
    "description": "string",
    "private": false,
    "author": "string",
    "version": "string",
    "license": "string",
    "callword": "string",
    "lifetime": "string",
    "threshold": 0,
    "languages": [
      "string", "string"
    ],
    "tags": [
      "string"
    ],
    "nlu": [
      "string"
    ],
    "services": [
      {
        "name": "string",
        "description": "string",
        "url": "string",
        "attributes": [
          {
            "name": "string",
            "type": "string",
            "required": false
          },
          {
            "name": "string",
            "type": "string",
            "required": true
          }
        ]
      }
    ]
}

Parameters Description

Parameter Description Type Required
name The skill name string Yes
description Description of the skill string No
private false for common skill boolean no
author Author name string No
version Skill version string Yes
license string No
languages Supported languages by the skill string array no
tags string array No
nlu Supported NLU engines string array No
services No

Skill Version

If an skill is going to be published, it should start at 1.0.0, though it is not mandatory.

After this, changes should be handled as follows:

  • (PATCH) Bug fixes and other minor changes: Patch release, increment the last number, e.g. 1.0.1
  • (MINOR) New features which don't break existing features: Minor release, increment the middle number, e.g. 1.1.0
  • (MAJOR) Changes which break backwards compatibility: Major release, increment the first number, e.g. 2.0.0

See Semantic Versioning for more information.

Request

This defines the request interface that is sent to the skill action handler function

{
  "id": "string",
  "version": "string",
  "language": "string",
  "text": "string",
  "retext": "string",
  "attributes": {
  },
  "context": {
    "user" : {
      "id": "string"
    },
    "session" : {
      "id": "string",
      "new": true,
      "attributes" : {
      }
    },
    "application" : {
      "id": "string",
      "attributes": {
      }
    }
  }
}

Parameters Description

Parameter Description Type Required
id request id string yes
version Request version string yes
language User text query language string no
text User query as text string yes
retext User query after text reformatting string yes
attributes The extracted intent and entities from user request object yes
context: Request context data object yes
Request Context Types
Context Type Description
user
application Application specific context
session
User Context Object
Parameter Description Type Required
id User unique id string yes
Application Context Object
Parameter Description Type Required
id Application unique id string yes
attributes object yes
Session Context Object
Parameter Description Type Required
new boolean yes
attributes object yes

Response

This defines the format of the response that that the skill should return to the interact core.

{
  "version": "string",
  "reject": "boolean",
  "error": "number",
  "shouldEndSession": "boolean",
  "speech": {
    "text": "string",
    "display": "string",
    "expressiveness": "string"
  },
  "card": {
    "type": "string",
    "title": "string",
    "subtitle": "string",
    "content": {
    }
  },
  "context": {
    "user": {
    },
    "session": {
    },
    "application": {
    }
  },
  "metrics": {
    "skill": "string"
  }
}

Parameters Description

Parameter Description Type Required
version Response version string yes
reject boolean yes
shouldEndSession boolean yes
context object yes

Speech Object

Parameter Description Type Required
text string yes
expressiveness string yes

Card Object

Parameter Description Type Required
type string yes
title string yes
subtitle string yes
content object no

Response Context Types

Context Description
user
session

API Reference

Method API Description
GET /v1/api/manifest Returns the skill manifest as a JSON object.
GET /v1/api/nlu Returns NLU metadata which is used by the interact core NLU engines.
GET /v1/api/intents Returns skill intents descriptors.
GET /v1/api/healthCheck Check the status (health) of the skill.
POST /v1/api/converse Get a response from user input or event.

NLU

The Natural Language Understanding includes data required by the Interact core to extract intents and entities.

Intents Descriptors

The intents file is optional metadata file which includes skill intent descriptors. The information in this file is applied by the core to extracted intent (after NLU extraction phase). The skill developer can use the intents descriptors to increase the accuracy of the skill and to control intent behavior.

{
  "<intent name>" :
  {
    "visibility" : "string",
    "entities" : [
      {
        "name" : "string",
        "required" : "boolean"
      }
    ]
  }
}
Parameter Description Type Required
visibility Can be use to hide or show intent to core string No

Watson Conversation Service (WCS)

{
  "workspace": {
    "en-US": {
      "name:": "string",
      "workspaceId": "string"
    },
    "de-DE": {
      "name": "string",
      "workspaceId": "string"
    }
  }
}

Regular expressions

API.AI

Languages

TBD

Logging

TBD

Running

Locally

To run skill locally you can use the following command

npm start

Note! Make sure the port is not used by any other skill / server as the skill will not start.

Docker

Prerequisites

Locally

  • Build the image
docker build -t skill-boileplate:local .
  • Create and run a container
docker run --name fun -p 3000:3000 -e PORT=3000 -it skill-boileplate:local

Bluemix

For more information how to build and run containers in Bluemix you can refer to Adding Docker images to your organization's private Bluemix images registry

  • Build your image and push it to your private Bluemix registry.
bx ic build -t registry.ng.bluemix.net/<namespace>/skill-boileplate:v1.0.0 .

Tip: Run bx ic namespace get to retrieve your namespace information.

  • Create a container from your image.
bx ic create --name skill-boileplate -p 3001:3001 -e PORT=3001 registry.ng.bluemix.net/<namespace>/skill-boileplate:v1.0.0

Note: Select port that will not conflict with other skill

  • If can be published as public skill, bind a public IP address to your container.
bx ic bind <ip address> <container ID>

Tip: You can see your public IP addresses by running bx ic ips. To request a new one, run bx ic ip request.

How To Manually Test Skill

The skill (locally or hosted) can be tested directly with the skill converse REST API. Use the following json block in the skill swagger page.

{
  "id": "001",
  "text": "hello world",
  "retext": "hello world",
  "version": "1.0",
  "language": "en-US",
  "attributes": {
    "intent": "hello-world"
  },
  "context": {
    "user": {
      "id": "user-001"
    },
    "application": {
      "id": "app-001",
      "attributes": {
      }
    },
    "session": {
      "new": true,
      "attributes": {
      },
      "version": "1.0"
    }
  }
}

Tests

Running all the tests:

$ npm test