Snips apps server

When you write the action code of an app using code snippets in the console, and deploy this app with sam, an action folder is built out of a template, with your code snippet injected into it. The generated folder is stored in /var/lib/snips/skills. The Snips apps server will be inspecting this folder, and running the actions contained in it.

Similarly, if you write your own action code, and structure it into an action folder following certain specifications, the Snips apps server (currently still called snips-skill-server, renaming is in progress) will take care of running it into the background. Let's see what these specifications are.

Specifications

snips-skill-server will try and run action files in /var/lib/snips/skills

Required (to be runnable by snips-skill-server)

  • action files name beginning with action-*

  • action folders must be put in /var/lib/snips/skills

  • each action-* must be executable (chmod +x action-*)

  • if the action is written in Python, the first line of the file must be #!/usr/bin/env python2

Recommended if your app is in Python

  • setup.sh file to setup the virtualenv with sam or manually set up a virtualenv named venv

How it works

Actions can come from different sources: snippets from the console, public github repositories installed with sam, or code manually installed by the user. This section is here to help you understand how you can leverage the Snips apps server (still called snips-skill-server, renaming in progress) to run your own code.

The snips-skill-server service is used to run each action-* present in the /var/lib/snips/skills/

These action files must have their permissions set as executable. An action typically contains code connecting to the MQTT server and "looping forever" on it. Typical example of such an executable is a python script using the hermes-python library to listen to intents being detected, and reacted to it.

The first line of this python file must have #!/usr/bin/env python2 to run properly.

Each of these executable will be started by the app server, and restarted in case the process exits/crashes.

If a subfolder named venv exists, the snips-skill-server will try to activate the virtualenv before starting the executables (ie sourcing venv/bin/activate before starting the executable). This can be used to easily install dependencies for a python script.

Any other file or folder is ignored by the snips-skill-server.

Examples

Here you'll find some apps written by Snips' team:

Other interesting files

setup.sh

By convention any configuration needed to be done before running should be done in a script named setup.sh. sam will automatically launch such a script upon install of an app. If not using sam the user should launch it by hand.

The rights required to run this script should be only write access to the app directory, this script should not be used to install systemwide dependencies, and just be used to for example setup a python virtualenv or compile some source files.

config.ini

By convention also, actions files should read their configuration in a file named config.ini. A section secret should be used for parameters that are sensitive (passwords / api keys...) The other section global is used for everything else.

In the console you can setup parameters for your apps:

When using the snippets, you can access global parameters with conf['global']['parameterName']. For end-user parameters use conf['secret']['parameterName']

snips-template

The snips-template executable can be used to generate action folders from snippets included by the console in assistant.zip files. Future version should include a bootstrap command to generate empty app folders.

By default snips-template will generate one action- file per intent, but this is not something required by the spec (ie you can manage mulitple intents in the same executable if you want)

The Snips templates are available on Github: https://github.com/snipsco/snips-actions-templates