Skip to main content

smskillsdk (NodeJS)

The Skills NodeJS SDK package contains data types for the session and execute endpoints specified within the Skills REST API, along with a range of utility functions for working with the memory data structure.

Installation​

This package is intended for use with NodeJS 14 and above.

npm install @soulmachines/smskillsdk

Usage​

Accessing request/response models​

import {
  SessionRequest,
  SessionResponse,
  ExecuteRequest,
  ExecuteResponse,
} from "@soulmachines/smskillsdk";

Sub-models used within these request and response models can also be imported using

import { Output, Intent, Variables } from "@soulmachines/smskillsdk";

In general, a developer should implement separate handler functions for the session and execute endpoints which takes a SessionRequest or ExecuteRequest as an argument and returns a SessionResponse or ExecuteResponse respectively. These objects can be serialized to JSON and returned within the HTTP response body. An example implementation of a handler function for generating an ExecuteResponse and a route method is shown below.

// execute endpoint handler containing response generation logic
function executeHandler(request: ExecuteRequest): ExecuteResponse {

    // response generation logic here

    const variables = {
        "public": {
            "card": { ... }
        }
    } as Variables;

    const output = {
        "text": "Text for the digital person to speak",
        variables
    } as Output;

    const response = {
        output,
        "memory": [],
        "endConversation": true
    } as ExecuteResponse;
    return response;
}

// route method
app.post("/", (req, res) => {
    const executeRequest = request.body as ExecuteRequest;
    const executeResponse = executeHandler(executeRequest);
    response.json(executeResponse);
})

Working with memory​

The memory field within the request and response models of the session/execute endpoints can be used to persist state between conversation turns and share information between skills within a single session.

The data structure is comprised of an array of Memory objects

class Memory {
    name: string;
    value: any | null;
    sessionId?: string;
    scope?: MemoryScope;
}

where the name field acts as a key. The optional sessionId field can be used to differentiate between objects having the same name value, while the optional scope field can be used to control whether objects are shared between skills or remain private to a single skill (the default scope is MemoryScope.Private). Setting scope: MemoryScope.Public will mean that this particular memory object will be viewable and editable by all skills within a particular session.

Note that memory objects with the same name but different session ID/scope will be treated as unique.

We offer a range of utility functions to work with the memory data structure:

serializeMemory(data: Record<string, unknown>, sessionId?: string, scope?: MemoryScope): Array<Memory>​

Converts an object into an array of memory objects with an optional session ID and scope.

Arguments:

  • data: Record<string, unknown>: An object to be converted; keys should be strings
  • sessionId: string: An optional session ID to be assigned to each memory object
  • scope: MemoryScope: An optional scope to determine if the memory objects should be able to be shared with other skills within the session (default: MemoryScope.Private)

Returns:

  • Array<Memory>: An array of memory objects

deserializeMemory(memories: Array<Memory>, sessionId?: string, scope?: MemoryScope): Record<string, unknown>​

Converts an array of memory objects into an object, filtered using an optional session ID or scope value. If there are multiple valid memory objects with the same name, the value closest to the end of the memories array will be returned.

Arguments:

  • memories: Array<Memory>: An array of memory objects to be converted
  • sessionId?: string: If provided, will only deserialize memory objects with a matching session ID
  • scope: MemoryScope: If provided, will only deserialize memory objects with a matching scope (otherwise all memory objects will be treated as valid)

Returns:

  • Record<string, unknown>

setMemoryValue(memories: Array<Memory>, key: string, value: unknown, sessionId?: string, scope?: MemoryScope)​

Sets a value in an array of Memory objects corresponding to a key and optional session ID or scope. If an object with a matching key/session ID/scope exists, its value will be overwritten.

Arguments:

  • memories: Array<Memory>: The list of memory objects which will be operated on
  • key: string: The key to search for
  • value: unknown: The value to set
  • sessionId: string: If provided, only memory objects with a matching session ID will be considered; if none are found, a new memory object with a session ID will be created
  • scope: MemoryScope: If provided, only memory objects with a matching scope will be considered (defaults to MemoryScope.Private)

Returns:

  • No return value, the array of memory objects is modified in-place

getMemoryValue(memories: Array<Memory>, key: string, sessionId?: string, scope?: MemoryScope): [boolean, unknown]​

Retrieves the first valid value from an array of memory objects corresponding to a key and optional session ID or scope value.

Arguments:

  • memories: Array<Memory>: The array of memory objects to be searched
  • key: string: The key to search for
  • sessionId: string: If provided, only memory objects with a matching session ID will be considered
  • scope: MemoryScope: If provided, only memory objects with a matching scope will be considered (otherwise all objects will be considered)

Returns:

  • [boolean, unknown]: A flag indicating whether the key/value pair was found, and the corresponding value; this can be unpacked as shown below
let found, value;
[found, value] = getMemoryValue(memories, "key", "sessionId");

Common session memory values​

We have defined two memory objects which can be used to share information in a common format between skills:

interface UserIdentity {
  firstName?: string;
  lastName?: string;
  preferredName?: string;
  id?: string;
}

interface UserLocation {
  city?: string;
  country?: string;
}

Users may define their own objects to work across their skills, or to expose information to other skills. These values can be set and retrieved from a memory array using the following helper functions:

  • setUserIdentity(memories: Array<Memory>, firstName?: string, lastName?: string, preferredName?: string, id?: string): void
  • getUserIdentity(memories: Array<Memory>): UserIdentity | null
  • setUserLocation(memories: Array<Memory>, city?: string, country?: string): void
  • getUserLocation(memories: Array<Memory>): UserLocation | null

Async API​

Import Skills Async API message models from smskillsdk:

import {
  UserConversationMessage,
  SkillConversationMessage,
} from '@soulmachines/smskillsdk';

These message models correspond to the message payloads, all messages sent/received on the websocket connection via the async API will have the following format, as per the AsyncAPI standard:

{
    "name": "<message_name>",
    "payload": { <message_payload> }
}

Payloads can be deserialized/serialized in the same way as for the skill_api, example with express-ws package:

router.ws('/', async (ws: WebSocket, req: express.Request) => {
  ws.on('message', async (message: string) => {
    const msg = JSON.parse(message);
    if (msg.name == 'conversation') {
        const usr_msg: UserConversationMessage = msg.payload;
        const response: SkillConversationMessage = { text: `Echo: ${usr_msg.text}` };
        const serialized_response = JSON.stringify({ name: 'skillConversation', payload: response });
        await ws.send(serialized_response);
    }
  })
});