Usage

The design philosophy of SnipsKit is:

  • It should be easy to create a Snips app with minimal boilerplate code.
  • All SnipsKit code should behave by default in a sensible way, tuned for a Snips installation.

Prerequisites

This document presupposes that you:

Creating Snips apps using Hermes Python

You can create a Snips app using Hermes Python by subclassing the HermesSnipsApp class. This is a convenience class that removes a lot of boilerplate code, which it executes behind the curtains without you having to think about it.

But you still have to know how to use the Hermes Python library, because you’ll use it to read slots, publish messages, and so on. Think of the HermesSnipsApp class as an addon that makes your life in the Hermes Python world a little easier.

Creating a simple Snips app using Hermes Python

A simple Snips app that listens to a specific intent and then says a message, is created like this:

Example hermes_listen_for_intent.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#!/usr/bin/env python3
from snipskit.hermes.apps import HermesSnipsApp
from snipskit.hermes.decorators import intent


class SimpleSnipsApp(HermesSnipsApp):

    @intent('User:ExampleIntent')
    def example_intent(self, hermes, intent_message):
        hermes.publish_end_session(intent_message.session_id,
                                   'I received ExampleIntent')


if __name__ == "__main__":
    SimpleSnipsApp()

You can download the file hermes_listen_for_intent.py from our GitHub repository.

Let’s dissect this code. In line 1, we signal to the shell that this file is to be run by the Python 3 interpreter. In lines 2 and 3 we import the HermesSnipsApp class and the intent() decorator that we use.

Beginning from line 6 we define a class for our Snips App, inheriting from the HermesSnipsApp app. By inheriting from this class, you get a lot of functionality for free, which we’ll explain in a minute.

In line 9, we define a callback method. This method will be called when an intent is recognized. Which intent? This is defined by the decorator intent() in line 8. So this line says: “If the intent ‘User:ExampleIntent’ is recognized, call the method example_intent.

Then inside the example_intent method, you can use the hermes and intent_message objects from the Hermes Python library. In this simple case, we end the session by saying a message.

In line 14, we check if the Python file is run on the commandline. If it is, we create a new object of the class we defined. When we initialize this object, it automatically reads the MQTT connection settings from the snips.toml file, connects to the MQTT broker, registers the method with the intent() decorator as a callback method for the intent ‘User:ExampleIntent’ and starts the event loop so the app starts listening to events from the Snips platform.

Reading the configuration of the app, the assistant and Snips

Each HermesSnipsApp or MQTTSnipsApp object has attributes that give the app access to the app’s configuration (AppConfig), the assistant’s configuration (AssistantConfig) and the configuration of Snips (SnipsConfig). The following example (for HermesSnipsApp, but it works the same for MQTTSnipsApp) shows the use of these three attributes:

Example hermes_configuration.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
#!/usr/bin/env python3
from snipskit.hermes.apps import HermesSnipsApp
from snipskit.config import AppConfig
from snipskit.hermes.decorators import intent


class SimpleSnipsApp(HermesSnipsApp):

    @intent('User:TurnOn')
    def example_turn_on(self, hermes, intent_message):
        switch = self.config['secret']['switch']
        hermes.publish_end_session(intent_message.session_id,
                                   'You want me to turn on {}'.format(switch))

    @intent('User:Name')
    def example_name(self, hermes, intent_message):
        name = self.assistant['name']
        hermes.publish_end_session(intent_message.session_id,
                                   'My name is {}'.format(name))

    @intent('User:Master')
    def example_master(self, hermes, intent_message):
        try:
            master = self.snips['snips-audio-server']['bind'].split('@')[0]
        except KeyError:
            master = 'default'
        hermes.publish_end_session(intent_message.session_id,
                                   'My master site is {}'.format(master))


if __name__ == "__main__":
    SimpleSnipsApp(config=AppConfig())

You can download the file hermes_configuration.py from our GitHub repository.

With self.config you get access to this app’s configuration as an AppConfig object, which is a subclass of configparser.ConfigParser. This example requires you to have a file ‘config.ini’ in the same directory as the app, with the following content:

[global]
[secret]
switch=light1

Note

To get access to the app configuration, don’t forget to add the argument config=AppConfig() when initializing your app. If you don’t need any app configuration, this argument can be left out.

With self.assistant you get access to the assistant’s configuration as an AssistantConfig object, which behaves like a dict. This reads the configuration from the assistant’s directory, which is normally ‘/usr/share/snips/assistant/assistant.json’ on a Raspbian system.

And with self.snips you get access to the configuration of Snips, which also behaves like a dict. This reads the configuration from the Snips configuration file, which is normally ‘/etc/snips.toml’ on a Raspbian system.

Reading the assistant’s configuration outside an app

When you create a HermesSnipsApp or MQTTSnipsApp object, it reads the location of the assistant from ‘snips.toml’ and creates an AssistantConfig object with the correct path, which gives you access to the assistant’s configuration. See the previous section for an example.

You can also create an AssistantConfig object outside an app object, reading its configuration from a specified file:

assistant = AssistantConfig('/opt/assistant/assistant.json')

The file argument is optional. If you leave it empty, the AssistantConfig object tries to read its configuration from the following files, in this order:

  • /usr/share/snips/assistant/assistant.json
  • /usr/local/share/snips/assistant/assistant.json

Note that the AssistantConfig object doesn’t read its location from ‘snips.toml’ in this case.

If you want to create an AssistantConfig object outside an app object and initialize it from the location specified in ‘snips.toml’, you need to use the SnipsAppMixin.assistant attribute to get an AssistantConfig object with the correct path.

For instance, this could be interesting if you want to know the language of the user’s assistant before initializing your app:

language = SnipsAppMixin().assistant['language']