Brains

This document covers all you need to know about brains.

How the brain works

A brain is the place where all the bot data is stored. The storage is organized in two parts: global scope (not user-specific bot data) and user scope (user-specific bot data). User data is further organized into conversations.

By convention, to avoid collisions, data used internally by Botfuel Dialog, as opposed to by the developer of the bot, is stored with keys prefixed with an underscore (_).

Global scope

This data is not user-specific. The Brain class comes with two methods allowing it to read/write bot data: botGet and botSet.

botGet

/**
 * Gets a value for a key within the global scope.
 * @async
 * @param {String} key - the key
 * @returns {Promise.<*>} the value
 */
async botGet(key)

botSet

/**
 * Sets a value for a key within the global scope.
 * @async
 * @param {String} key - the key
 * @param {*} value - the value
 * @returns {Promise.<*>} the new value
 */
async botSet(key, value)

User data

The Brain class comes with two methods allowing it to read/write user data: userGet and userSet.

userGet

/**
 * Gets a value for a key within the scope of the user.
 * @async
 * @param {String} userId - the user id
 * @param {String} key - the key
 * @returns {Promise.<*>} the value
 */
async userGet(userId, key)

userSet

/**
 * Sets a value for a key within the scope of the user.
 * @async
 * @param {String} userId - the user id
 * @param {String} key - the key
 * @param {*} value - the value
 * @returns {Promise.<Object>} the updated user
*/
async userSet(userId, key, value)

Conversations

User data is further organized into conversations. A conversation is a sequence of messages exchanged between the bot and the user. A new conversation is automatically created when the duration of the previous one has exceeded the maximum permitted duration.

The Brain class comes with two methods allowing it to read/write data in the last conversation: conversationGet and conversationSet.

conversationGet

/**
 * Gets the value for a given key within the scope of the last conversation of a user.
 * @async
 * @param {String} userId - user id
 * @param {String} key - last conversation key
 * @returns {Promise.<*>} the value
 */
async conversationGet(userId, key)

conversationSet

/**
 * Sets a value for a key within the scope of the last conversation of a user.
 * @async
 * @param {String} userId - the user id
 * @param {String} key - the key
 * @param {*} value - the  value
 * @returns {Promise.<Object>} the updated conversation
 */
async conversationSet(userId, key, value)

Example of user data

The following user data are stored in the brain of this sample bot when the user says:

Hello
I leave for Paris
{
  '38d3a867-8ae5-486d-95f0-13ec7dd2602a': {
    _userId: '38d3a867-8ae5-486d-95f0-13ec7dd2602a',
    _conversations: [
      {
        _dialogs: {
          stack: [
            {
              name: 'travel',
              entities: [
                {
                  dim: 'city',
                  body: 'paris',
                  values: [
                    {
                      value: 'Paris',
                      type: 'string'
                    }
                  ],
                  start: 12,
                  end: 17
                }
              ],
              blocked: false
            }
          ],
          previous: [
            {
              name: 'greetings',
              entities: [],
              blocked: false,
              date: 1519941532516
            }
          ]
        },
        _createdAt: 1519941531773,
        travel: {
          time: undefined,
          city: {
            dim: 'city',
            body: 'paris',
            values: [
              {
                value: 'Paris',
                type: 'string'
              }
            ],
            start: 12,
            end: 17
          }
        },
        uuid: '53e5f1c8-c49e-4896-aecf-f3c8b8825f63'
      }
    ],
    _createdAt: 1519941531773,
    greetings: {
      greeted: true
    }
  }
}

Brain configuration and implementations

The brain is configured using the brain key. It defaults to { name: 'memory' }.

Botfuel Dialog comes with two pre-configured brains:

  • 'memory' (non-persistent in-memory brain)
  • 'mongo' (MongoDB brain)

Conversation duration

The duration of a conversation is the limit beyond which a new conversation is automatically created by the bot.

Its default value is 86400000ms (1 day).

To change this value, add the entry conversationDuration: <maximum duration in ms> to your brain config:

{
  brain: {
    name: '<brain key>',
    conversationDuration: '3600000' // one hour
  }
}

In-memory brain

MemoryBrain is an in-memory implementation of the brain. This means that data is not saved in a persistent storage such as a database, instead it is saved only in memory. This implementation is suited for testing but not for production bots.

MongoDB brain

MongoBrain relies on a MongoDB database for persistence. It is suited for production bots.

How to write your own brain

Simply add brain: '{ name: '<your brain key>' } to your config file and, under the root of the bot, a file brains/<your brain key>-brain.js.

Implementing a brain implies subclassing the Brain abstract class and implementing the following methods:

  • addConversation
  • addUser
  • botGet
  • botSet
  • clean
  • conversationSet
  • fetchLastConversation
  • getUser
  • hasUser
  • userSet