API reference¶

This is the API documentation of the SnipsKit package, covering all modules and classes.

snipskit.apps¶

This module contains a class to create Snips apps.

You can create a Snips app in two ways:

By subclassing snipskit.hermes.apps.HermesSnipsApp: This creates a Snips app using the Hermes Python library.
By subclassing snipskit.mqtt.apps.MQTTSnipsApp: This creates a Snips app using the MQTT protocol directly.

HermesSnipsApp is a subclass of HermesSnipsComponent and adds assistant and config attributes for access to the assistant’s configuration and the app’s configuration, respectively.

MQTTSnipsApp is a subclass of MQTTSnipsComponent and adds assistant and config attributes for access to the assistant’s configuration and the app’s configuration, respectively.

Both classes include the SnipsAppMixin mixin of this module to read the assistant’s configuration from the location defined in snips.toml.

Note

This class requires you to have a Snips assistant installed.

If you don’t need access to the assistant’s configuration nor an app-specific configuration, you can create a subclass of SnipsComponent.

Note

If you only need access to the Snips configuration and the assistant’s configuration without the need to connect to the MQTT broker, you can use the SnipsAppMixin class.

class snipskit.apps.SnipsAppMixin(snips=None, config=None)[source]¶

Bases: object

A mixin for classes that should have access to a Snips app’s configuration, the Snips assistant’s configuration and the Snips configuration.

The classes HermesSnipsApp and MQTTSnipsApp include this mixin, primarily to avoid code duplication for reading the assistant’s configuration from the location defined in snips.toml.

You can also subclass this mixin for easy access to the Snips configuration and the assistant’s configuration without the need to connect to the MQTT broker.

assistant¶

The assistant configuration. Its location is read from the Snips configuration file.

Type:	`AssistantConfig`

config¶

The app configuration.

Type:	`AppConfig`

snips¶

The Snips configuration.

Type:	`SnipsConfig`

__init__(snips=None, config=None)[source]¶

Initialize the mixin by setting the config, snips and assistant attributes.

To initialize the assistant attribute, the location of the assistant is read from the Snips configuration file. If the location is not specified there, a default AssistantConfig object is created.

Parameters:	snips (`SnipsConfig`, optional) – a Snips configuration. If the argument is not specified, a default `SnipsConfig` object is created for a locally installed instance of Snips. config (`AppConfig`, optional) – an app configuration. If the argument is not specified, the app has no configuration.

New in version 0.3.0.

snipskit.components¶

This module contains a class to create components to communicate with Snips.

A Snips component (a subclass of SnipsComponent) can communicate with Snips services. There are two subclasses of SnipsComponent in other modules:

snipskit.hermes.components.HermesSnipsComponent: a Snips component using the Hermes Python library;
snipskit.mqtt.components.MQTTSnipsComponent: a Snips component using the MQTT protocol directly.

Note

If you want to create a Snips app with access to an assistant’s configuration and a configuration for the app, you need to instantiate a HermesSnipsApp or MQTTSnipsApp object, which is a subclass of HermesSnipsComponent or MQTTSnipsComponent respectively, adding assistant and config attributes. See the module snipskit.apps.

class snipskit.components.SnipsComponent(snips=None)[source]¶

Bases: object

Connect with a Snips instance and give access to a Snips configuration.

This is an abstract base class. You don’t instantiate an object of this class, but an object of one of its subclasses: HermesSnipsComponent or MQTTSnipsComponent

snips¶

The Snips configuration.

Type:	`SnipsConfig`

__init__(snips=None)[source]¶

Initialize a Snips component.

Parameters:	snips (`SnipsConfig`, optional) – a Snips configuration. If the argument is not specified, a default `SnipsConfig` object is created for a locally installed instance of Snips.

initialize()[source]¶: If you have to initialize a component in your subclass of SnipsComponent, add your code in this method. It will be called between connecting to Snips and starting the event loop.

snipskit.config¶

This module gives a way to access the configuration of a locally installed instance of Snips, a Snips assistant and a Snips skill.

Classes:

AppConfig: Gives access to the configuration of a Snips app, stored in an INI file.
AssistantConfig: Gives access to the configuration of a Snips assistant, stored in a JSON file.
MQTTConfig: Represents the configuration for a connection to an MQTT broker.
SnipsConfig: Gives access to the configuration of a locally installed instance of Snips, stored in a TOML file.

class snipskit.config.AppConfig(filename=None)[source]¶

Bases: configparser.ConfigParser

This class gives access to the configuration of a Snips app as a configparser.ConfigParser object.

filename¶

The filename of the configuration file.

Type:	str

Example

>>> config = AppConfig()  # Use default file config.ini
>>> config['secret']['api-key']
'foobar'
>>> config['secret']['api-key'] = 'barfoo'
>>> config.write()

__init__(filename=None)[source]¶

Initialize an AppConfig object.

Parameters:	filename (optional) – A filename for the configuration file. If the filename is not specified, the default filename ‘config.ini’ in the current directory is chosen.

write(*args, **kwargs)[source]¶

Write the current configuration to the app’s configuration file.

If this method is called without any arguments, the configuration is written to the filename attribute of this object.

If this method is called with any arguments, they are forwarded to the configparser.ConfigParser.write() method of its superclass.

class snipskit.config.AssistantConfig(filename=None)[source]¶

Bases: collections.UserDict

This class gives access to the configuration of a Snips assistant as a dict.

filename¶

The filename of the configuration file.

Type:	str

Example

>>> assistant = AssistantConfig('/opt/assistant/assistant.json')
>>> assistant['language']
'en'

__init__(filename=None)[source]¶

Initialize an AssistantConfig object.

Parameters:

filename (str, optional) –

The path of the assistant’s configuration file.

If the argument is not specified, the configuration file is searched for in the following locations, in this order:

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

Raises:

FileNotFoundError – If the specified filename doesn’t exist.
AssistantConfigNotFoundError – If there’s no assistant configuration found in the search path.
json.JSONDecodeError – If the assistant’s configuration file doesn’t have a valid JSON syntax.

Examples

>>> assistant = AssistantConfig()  # default configuration
>>> assistant2 = AssistantConfig('/opt/assistant/assistant.json')

class snipskit.config.MQTTConfig(broker_address='localhost:1883', username=None, password=None, tls_hostname=None, tls_ca_file=None, tls_ca_path=None, tls_client_key=None, tls_client_cert=None, tls_disable_root_store=False)[source]¶

Bases: object

This class represents the configuration for a connection to an MQTT broker.

New in version 0.4.0.

broker_address¶

The address of the MQTT broker, in the form ‘host:port’.

Type:	str

username¶

The username to authenticate to the MQTT broker. ‘None’ if there’s no authentication.

Type:	str

password¶

The password to authenticate to the MQTT broker. ‘None’ if there’s no authentication.

Type:	str

tls_hostname¶

The TLS hostname of the MQTT broker. ‘None’ if no TLS is used.

Type:	str

tls_ca_file¶

Path to the Certificate Authority file. Can be ‘None’.

Type:	str

tls_ca_path¶

Path to the Certificate Authorify files. Can be ‘None’.

Type:	str

tls_client_key¶

Path to the private key file. Can be ‘None’.

Type:	str

tls_client_cert¶

Path to the client certificate file. Can be ‘None’.

Type:	str

tls_disable_root_store¶

Whether the TLS root store is disabled.

Type:	bool

__init__(broker_address='localhost:1883', username=None, password=None, tls_hostname=None, tls_ca_file=None, tls_ca_path=None, tls_client_key=None, tls_client_cert=None, tls_disable_root_store=False)[source]¶

Initialize a MQTTConfig object.

All arguments are optional. The default values are:

broker_address: ‘localhost:1883’
tls_disable_root_store: False
all other arguments: None

class snipskit.config.SnipsConfig(filename=None)[source]¶

Bases: collections.UserDict

This class gives access to a snips.toml configuration file as a dict.

filename¶

The filename of the configuration file.

Type:	str

mqtt¶

The MQTT options of the Snips configuration.

Type:	`MQTTConfig`

Example

>>> snips = SnipsConfig()
>>> snips['snips-hotword']['audio']
['default@mqtt', 'bedroom@mqtt']

__init__(filename=None)[source]¶

Initialize a SnipsConfig object.

The mqtt attribute is initialized with the MQTT connection settings from the configuration file, or the default value ‘localhost:1883’ for the broker address if the settings are not specified.

Parameters:

filename (str, optional) –

The full path of the config file. If the argument is not specified, the file snips.toml is searched for in the following locations, in this order:

/etc/snips.toml
/usr/local/etc/snips.toml

Raises:

FileNotFoundError – If filename is specified but doesn’t exist.
SnipsConfigNotFoundError – If there’s no snips.toml found in the search path.
TomlDecodeError – If filename doesn’t have a valid TOML syntax.

Examples

>>> snips = SnipsConfig()  # Tries to find snips.toml.
>>> snips_local = SnipsConfig('/usr/local/etc/snips.toml')

snipskit.exceptions¶

This module contains exceptions defined for the SnipsKit library.

exception snipskit.exceptions.SnipsKitError[source]¶

Bases: Exception

Base class for exceptions raised by SnipsKit code.

By catching this exception type, you catch all exceptions that are defined by the SnipsKit library.

exception snipskit.exceptions.AssistantConfigNotFoundError[source]¶

Bases: snipskit.exceptions.SnipsKitError

Raised when the assistant’s configuration is not found in the search path.

exception snipskit.exceptions.SnipsConfigNotFoundError[source]¶

Bases: snipskit.exceptions.SnipsKitError

Raised when there’s no snips.toml found in the search path.

snipskit.hermes¶

This module contains classes to create components that communicate with Snips services using the Hermes Python library.

snipskit.hermes.apps¶

This module contains a class to create Snips apps using the Hermes Python library.

Example:

from snipskit.hermes.apps import HermesSnipsApp
from snipskit.hermes.decorators import intent


class SimpleSnipsApp(HermesSnipsApp):

    def initialize(self):
        print('App initialized')

    @intent('User:ExampleIntent')
    def example_intent(self, hermes, intent_message):
        print('I received intent "User:ExampleIntent"')

class snipskit.hermes.apps.HermesSnipsApp(snips=None, config=None)[source]¶

Bases: snipskit.apps.SnipsAppMixin, snipskit.hermes.components.HermesSnipsComponent

A Snips app using the Hermes Python library.

assistant¶

The assistant configuration. Its location is read from the Snips configuration file and otherwise a default location is used.

Type:	`AssistantConfig`

config¶

The app configuration.

Type:	`AppConfig`

snips¶

The Snips configuration.

Type:	`SnipsConfig`

hermes¶

The Hermes object.

Type:	`hermes_python.hermes.Hermes`

__init__(snips=None, config=None)[source]¶

Initialize a Snips app using the Hermes protocol.

Parameters:	snips (`SnipsConfig`, optional) – a Snips configuration. If the argument is not specified, a default `SnipsConfig` object is created for a locally installed instance of Snips. config (`AppConfig`, optional) – an app configuration. If the argument is not specified, the app has no configuration.

snipskit.hermes.components¶

This module contains a class to create components to communicate with Snips using the Hermes Python library.

Note

If you want to create a Snips app with access to an assistant’s configuration and a configuration for the app, you need to instantiate a HermesSnipsApp object, which is a subclass of HermesSnipsComponent and adds assistant and config attributes.

Example:

from snipskit.hermes.components import HermesSnipsComponent
from snipskit.hermes.decorators import intent


class SimpleSnipsComponent(HermesSnipsComponent):

    def initialize(self):
        print('Component initialized')

    @intent('User:ExampleIntent')
    def example_intent(self, hermes, intent_message):
        print('I received intent "User:ExampleIntent"')

class snipskit.hermes.components.HermesSnipsComponent(snips=None)[source]¶

Bases: snipskit.components.SnipsComponent

A Snips component using the Hermes Python library.

snips¶

The Snips configuration.

Type:	`SnipsConfig`

hermes¶

The Hermes object.

Type:	`hermes_python.hermes.Hermes`

snipskit.hermes.decorators¶

This module contains decorators to apply to methods of a HermesSnipsComponent object.

By applying one of these decorators to a method of a HermesSnipsComponent object, this method is registered as a callback to the corresponding event. When the event fires (e.g. an intent happens), the method is called.

Example:

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):
        print('I received intent "User:ExampleIntent"')

snipskit.hermes.decorators.intent(intent_name)[source]¶

Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered when the intent intent_name is recognized.

Parameters:	intent_name (str) – The intent you want to subscribe to.

snipskit.hermes.decorators.intent_not_recognized(method)[source]¶: Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered when the dialogue manager doesn’t recognize an intent.

snipskit.hermes.decorators.intents(method)[source]¶: Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered everytime an intent is recognized.

snipskit.hermes.decorators.session_ended(method)[source]¶: Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered when the dialogue manager ends a session.

snipskit.hermes.decorators.session_queued(method)[source]¶: Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered when the dialogue manager queues the current session.

snipskit.hermes.decorators.session_started(method)[source]¶: Apply this decorator to a method of class HermesSnipsComponent to register it as a callback to be triggered when the dialogue manager queues starts a new session.

snipskit.mqtt¶

This module contains classes to create components that communicate with Snips services using the MQTT protocol directly.

snipskit.mqtt.apps¶

This module contains a class to create Snips apps using the MQTT protocol directly.

Example:

from snipskit.mqtt.apps import MQTTSnipsApp
from snipskit.mqtt.decorators import topic


class SimpleSnipsApp(MQTTSnipsApp):

    def initialize(self):
        print('App initialized')

    @topic('hermes/hotword/toggleOn')
    def hotword_on(self, client, userdata, msg):
        print('Hotword activated')

class snipskit.mqtt.apps.MQTTSnipsApp(snips=None, config=None)[source]¶

Bases: snipskit.apps.SnipsAppMixin, snipskit.mqtt.components.MQTTSnipsComponent

A Snips app using the MQTT protocol directly.

assistant¶

The assistant configuration. Its location is read from the Snips configuration file and otherwise a default location is used.

Type:	`AssistantConfig`

config¶

The app configuration.

Type:	`AppConfig`

snips¶

The Snips configuration.

Type:	`SnipsConfig`

mqtt¶

The MQTT client object.

Type:	paho.mqtt.client.Client

__init__(snips=None, config=None)[source]¶

Initialize a Snips app using the MQTT protocol.

Parameters:	snips (`SnipsConfig`, optional) – a Snips configuration. If the argument is not specified, a default `SnipsConfig` object is created for a locally installed instance of Snips. config (`AppConfig`, optional) – an app configuration. If the argument is not specified, the app has no configuration.

snipskit.mqtt.components¶

This module contains a class to create components to communicate with Snips using the MQTT protocol directly.

Note

If you want to create a Snips app with access to an assistant’s configuration and a configuration for the app, you need to instantiate a MQTTSnipsApp object, which is a subclass of MQTTSnipsComponent and adds assistant and config attributes.

Example:

from snipskit.mqtt.components import MQTTSnipsComponent
from snipskit.mqtt.decorators import topic


class SimpleSnipsComponent(MQTTSnipsComponent):

    def initialize(self):
        print('Component initialized')

    @topic('hermes/hotword/toggleOn')
    def hotword_on(self, topic, payload):
        print('Hotword on {} is toggled on.'.format(payload['siteId']))

class snipskit.mqtt.components.MQTTSnipsComponent(snips=None)[source]¶

Bases: snipskit.components.SnipsComponent

A Snips component using the MQTT protocol directly.

snips¶

The Snips configuration.

Type:	`SnipsConfig`

mqtt¶

The MQTT client object.

Type:	paho.mqtt.client.Client

publish(topic, payload, json_encode=True)[source]¶

Publish a payload on an MQTT topic on the MQTT broker of this object.

Parameters:	topic (str) – The MQTT topic to publish the payload on. payload (str) – The payload to publish. json_encode (bool, optional) – Whether or not the payload is a dict that will be encoded as a JSON tring. The default value is True. Set this to False if you want to publish a binary payload as-is.

Returns: A paho.mqtt.MQTTMessageInfo object.

snipskit.mqtt.decorators¶

This module contains decorators to apply to methods of a MQTTSnipsComponent object.

By applying one of these decorators to a method of a MQTTSnipsComponent object, this method is registered as a callback to the corresponding event. When the event fires (e.g. an MQTT topic is published), the method is called.

Example:

from snipskit.mqtt.apps import MQTTSnipsApp
from snipskit.mqtt.decorators import topic

class SimpleSnipsApp(MQTTSnipsApp):

    @topic('hermes/hotword/toggleOn')
    def hotword_on(self, topic, payload):
        print('Hotword on {} is toggled on.'.format(payload['siteId']))

snipskit.mqtt.decorators.topic(topic_name, json_decode=True)[source]¶

Apply this decorator to a method of class MQTTSnipsComponent to register it as a callback to be triggered when the MQTT topic topic_name is published.

The callback needs to have the following signature:

method(self, topic, payload)

Parameters:	topic_name (str) – The MQTT topic you want to subscribe to. json_decode (bool, optional) – Whether or not the payload will be decoded as JSON to a dict. The default value is True. Set this to False if you want to subscribe to a topic with a binary payload.

snipskit.tools¶

This module contains some useful tools for the snipskit library.

snipskit.tools.find_path(paths)[source]¶

Given a search path of files or directories with absolute paths, find the first existing path.

Parameters:	paths (list) – A list of strings with absolute paths.
Returns:	The first path in the list paths that exists, or None if none of the paths exist.
Return type:	string

Example

The following example works if the file system has a file /usr/local/etc/snips.toml (e.g. on macOS with Snips installed):

>>> find_path(['/etc/snips.toml', '/usr/local/etc/snips.toml'])
'/usr/local/etc/snips.toml'