The skill SPI is the interface between the CVI core and the skills. A skill is implemented in a microservice, and exposes a HTTP interface. This HTTP interface must conform to the Skill SPI. If the service is developed in a JVM based language, the Skill SPI artifact can be used directly. If the artifact isn’t used, all the HTTP calls and payloads must conform the SPI.

Caller Authentication

Especially external hosted skills shall be able to validate their caller (CVI-Core) - via Basic Auth. The base64 encoded key value pair consists of the username 'cvi' and a password, which is an skill dependent api_key and can be configured through CVI-Core Admin UI.

Attribute types

Name

Description

Example

Fill policy

Remarks

ZIP_CODE

Zip code from the device metadata

81549

device

-

ROOM

Device name from the device metadata

Wohnzimmer

device

-

TIMEZONE

Timezone from the device metadata

Europe/Berlin

device

Is always set

FREETEXT

Pass the intent as it is from the NLU

foobar

-

-

DEVICE_NAME

Device name from the device metadata

Wohnzimmer

device

-

OTHER_DEVICE_NAMES

Names of the other devices of the user

[Wohnzimmer, Küche]

device

-

DYNAMIC_DEVICE_DATA

Dynamic device data which was sent in the request

foobar

device

The name of the attribute determines which field is read from the dynamic device metadata

STT_TEXT

Raw text from the NLU

wie ist das wetter in darmstadt?

Skill needs the STT_RESULT permission

-

VERIFICATION

Result of the user verification

{"confidence":0.9945837788767735,"status":"SUCCESSFUL"}

verification

-

Error responses and their effects

Also see here.

HTTP Status Code

Error Code

Error Message

Cause

Effect in CVI core

404

1

intent not found

skill invoke with the wrong intent

SkillException, respond with an InvokeException on controller

400

2

invalid token

given third party token is invalid

invoke skill with an surely refreshed token second time, if this one fails again prompt the user by voice to relogin

400

3

Bad request

expected arguments like locale are missing

SkillException, respond with an InvokeException on controller

504

4

Timeout

Timeout

prompt the user by voice to try again later

500

999

internal error

not considered situation, unhandled exception

SkillException, respond with an InvokeException on controller

Skill SPI

Overview

Interface between CVI Core and the skills

Contact information

Contact : CVI Team

License information

License : Proprietary
Terms of service : null

URI scheme

Host : yourhostname.com
BasePath : /

Tags

  • skill-spi-controller : Skill Spi Controller

Paths

invoke

POST /v1/yourskill

Parameters

Type Name Description Schema

Body

request
required

request

Responses

HTTP Code Description Schema

200

OK

201

Created

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • skill-spi-controller

info

GET /v1/yourskill/info

Responses

HTTP Code Description Schema

200

OK

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Consumes

  • application/json

Produces

  • application/json

Tags

  • skill-spi-controller

Definitions

CardDto

Card

Name Description Schema

data
optional

Generic data

object

type
required

Type of the card

string

version
required

Version of the data field

integer (int64)

InvokeSkillRequestDto

Skill invocation request

Name Description Schema

context
required

Context

session
required

Session

spiVersion
required

SPI version

string

InvokeSkillResponseDto

Skill invocation response

Name Description Schema

card
optional

Card to create

pushNotification
optional

Push notification to send to a device.

result
optional

Skill result in machine-readable format

session
optional

Session

text
required

Text for the user

string

type
required

Result type

enum (TELL, ASK, ASK_FREETEXT)

PushNotificationDto

Messaging data for a push notification to be sent to the client or app.

Name Schema

messagePayload
optional

string

targetName
optional

string

ResultDto

Result

Name Description Schema

data
required

Data. Fields are defined by the skill

object

local
required

True if the local part of the skill should be executed on the client
Example : false

boolean

targetDeviceId
optional

Id of the controlled device

string

SessionRequestDto

Session in the invoke request

Name Description Schema

attributes
required

Map of string to string values, which the skill has set

< string, string > map

id
required

Session id

string

new
required

True if the session is a new one or false if the session has been resumed
Example : false

boolean

SessionResponseDto

Session in the response

Name Description Schema

attributes
required

Map of string to string values, which the skill wants to persist in the session

< string, string > map

SkillContextAttributeValueDto

Skill context attribute value

Name Description Schema

extras
optional

Contains extra information for skills. e.g. literal.

< string, string > map

id
required

Attribute ID

integer (int32)

nestedIn
optional

List of IDs of attributes this attribute is nested in.

< integer (int32) > array

overlapsWith
optional

List of IDs of attributes this attribute overlaps with.

< integer (int32) > array

value
required

Value

string

SkillContextDto

Skill context

Name Description Schema

attributes
required

Skill attributes

< string, < string > array > map

attributesV2
optional

< string, < SkillContextAttributeValueDto > array > map

configuration
required

Skill configurations

< string, < object > array > map

intent
required

Intent which lead to the skill execution

string

locale
required

Locale

string

tokens
required

Skill tokens

< string, string > map

SkillInfoResponseDto

Skill information

Name Description Schema

skillId
optional

Id of the skill

string

skillSpiVersion
optional

Version of the SPI

string

skillVersion
optional

Version of the Skill

string

supportedLocales
optional

Supported locales

< string > array

Versioning in Skill SPI

Skill spi versioning is now supported. Skill invocation contracts become more flexible in cvi-core:

  • Fields can be added or removed to skill invoke request or response.

  • Data structure for existing field can be changed. For example, luis entity date range doesn’t allow half opened range for 1.0 like 1745-01-01/1746-01-01 but from 1.1 the value can be 1745-01-01/ or /1746-01-01)

Every 60 seconds (see skillMetadata.cacheheating.intervalInMs in application.yml cvi-core sends a GET /info request to the skill to cache the metadata from the skill and the spi version that will be used for an invoke. By default, if cvi-core doesn’t understand the skill spi version returned by skill it considers it as 1.0 All versions below 1.0 are considered as 1.0.

Different versions of skill spi reported by cvi-core can be visualized at this grafana dashboard.

Skill spi version migration

When a skill wants to start support new version for backwards compatibility it has to support old version and a new one for a short period.

cvi-core caches the spiVersion of the skill for 2 minutes (see caches → skills-metadata section in application.yml) Meanwhile a scheduled task queries every skill info every 1 minute (see skillMetadata.cacheheating.intervalInMs in application.yml) refreshing cache state with skill metadata and spi version.

Cached spi version value helps to avoid big number of invocations to every skill. But this introduces a prioblem of migrations. After skill deployment skill can return the new spi version but cvi-core will still use the old, cached one. In this case cvi-core will send the old request till the cache is refreshed. When deploying cvi-core and skill some pods can still have only the old version of spi but skill can ask for the new version. Especially with a canary releases that are about to be introduced to cvi-core.

To fix this problem the new spiVersion text field is introduced to skill invocation request. By setting this field cvi-core indicates to a skill the version of the response it’s waiting for.

Migration to the new version of skill spi

  • Ensure that cvi-core supports required spi version. Check CHANGELOG.md for the versions currently supported. If it is not the case, the fallback version is 1.0 and this can break the existing things.

  • Check the spi versions used for the skill at Skill Invocations grafana dashboard. Ensure that updated skill supports all the versions currently used as well as a new one.

  • Promote your skill. For some time after promotion cvi-core still keeps the cached version and will use the old one.

  • Wait till caches expire and ensure in grafana that only the new spi version is used.

  • Now you can remove the legacy code from your skill and promote it again.