npm package: @soulmachines/smskillsdk
Description: NodeJS package for the Soul Machines Skill API
Author: Soul Machines Ltd
Latest version: 1.4.0-rc.0

# 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

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

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

```js
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.

```js
// 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

```js
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>, name: string, value: unknown, sessionId?: string, scope?: MemoryScope)`

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

Arguments:

- `memories: Array<Memory>`: The array of Memory objects which will be operated on
- `name: string`: The name of Memory 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>, name: string, sessionId?: string, scope?: MemoryScope): [boolean, unknown]`

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

Arguments:

- `memories: Array<Memory>`: The array of Memory objects to be searched
- `name: string`: The name of Memory 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 Memory objects will be considered)

Returns:

- `[boolean, unknown]`: A flag indicating whether the Memory was found and its corresponding value; this can be unpacked as shown below

```js
let found, value;
[found, value] = getMemoryValue(memories, "name", "sessionId");
```

### Common session memory values

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

```js
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`