A generic platform that routes commands and conversations from voice or text-based clients to 3rd party backends. Functionality is added via plugins, checkout the Plugins section for more information.

View online demo.

npm install -g genie-router

This will make genie-router globally available on the system.

genie-router and its plugins must be configured with the configuration file. It must be provided at startup:

genie-router -c config.json

See config.json.dist for more details.

git clone https://github.com/genie-ai/genie-router.git
cd genie-router
npm install

This will make genie-router available in the directory you cloned the repository in. Run genie-router using ./bin/genie-router -c config.json.

genie-router can also be used as a module in your existing project.

npm install --save genie-router

Then you can initialize the router via:

const app = new Router(config)

Here you need to parse and provide the configuration object yourself.

Copy config.json.dist and update the values to your liking. See read-config documentation for more details on how values can be declared.

When genie-router starts it will attempt to load its plugins. The default location is $HOME/.genie-router, if that location does not exist, it will be created, the echo and cli-local plugin will be installed by default.

You can override the default plugin location, by using the pluginStore configuration attribute. When you override the location, make sure that the configured path exists, genie-router will not attempt to create it.

"pluginStore": {
  "location": "/home/user/.config/genie-router"
}

It is possible for plugins to store data persistently, such as authorized sessions and other small amounts of data. The data is all stored in a JSON file, namespaced per plugin. By default it is stored in ${USER}/.genie-router/storage.json but the location of the file can be configured.

"storage": {
    "location": "/etc/genie-router/store.json"
}

To enable HTTP support in general (plugins can use the http library to handle HTTP requests themselves), add a http attribute to the config:

"http": {
  "enabled": true,
  "port": 3001
}

You need to set enabled to true and configure the port on which to listen on. The default is 3001. When http is enabled, you can install plugins exposing HTTP urls.

There is a HTTP API plugin available that exposes a way for external clients to send a message using genie-router.

defaultBrain is the brain that should be selected by default when no brainSelector returns a brain suggestion. The brainStickiness is the time period (in seconds) when a previously selected brain in a client overrides the configured default brain. The default value for the stickiness is 120 seconds.

A small example to explain it some more:

1. The brain-mentions plugin is used to be able to select a different brain by using its name
2. The default brain is echo, but the google-assistant is also used.
3. When the user inputs something, the input is simply echood by the echo plugin
4. The user types ask google-assistant what is so special about 42?
5. The stickiness of the brain now dictates that any input received that is not picked up by a brainSelector is then handled by the google_assistant plugin, not the default echo.

Plugins can be installed by running npm install --save <plugin-identifier> in the plugins folder. Then create an entry in the config.json file in the plugins attribute with the key of the plugin. Include any additional configuration information as explained in the plugin readme.

Implementing your own is simple. You need to implement a npm module of which the index returned is an object with a client, brain or brainSelector attribute, which is a function. See the cli-local or echo plugins for simple examples.

There are four types of plugins: clients, brains, listeners and brain selectors. One plugin must be at least one of these four types, but can also be a combination of them.

A client takes input and echoes the resulting output. A brain takes text as input, does something with it, and returns an output. Brain selectors parse the input text and return the name of a brain to use for processing the input. Listeners can listen to events, currently only input.heard and output.reply are supported.

Want your plugin added here? Update the readme and create a Pull Request.