Skip to main content

Python bindings for Snips Hermes Protocol

Project description

Hermes Python

Build Status PyPI version

The hermes-python library provides python bindings for the Hermes protocol that snips components use to communicate together over MQTT. hermes-python allows you to interface seamlessly with the Snips platform and kickstart development of Voice applications.

hermes-python abstracts away the connection to the MQTT bus and the parsing of incoming and outcoming messages from and to the components of the snips platform.

hermes-python supports the snips-platform at version 1.1.0 - 0.61.1.

Installation

The library is packaged as a pre-compiled platform wheel, available on PyPi. It can be installed with :

pip install hermes-python

Or you can add it to your requirements.txt file.

Requirements

The wheel is available for Python 2.7+ and Python 3.5

The wheel supports the following platform tags :

  • manylinux1_x86_64
  • armv7l, armv6
  • macos

Usage

The lifecycle of a script using hermes-python has the following steps :

  • Initiating a connection to the MQTT broker
  • Registering callback functions to handle incoming intent parsed by the snips platform
  • Listening to incoming intents
  • Closing the connection

Let's quickly dive into an example : Let's write an app for a Weather Assistant ! This code implies that you created a weather assistant using the snips Console, and that it has a searchWeatherForecast intent.

Here is a code example for python2.7 :

from hermes_python.hermes import Hermes

MQTT_ADDR = "localhost:1883"	# Specify host and port for the MQTT broker 

def subscribe_weather_forecast_callback(hermes, intentMessage):	# Defining callback functions to handle an intent that asks for the weather. 
	print("Parsed intent : {}".format(intentMessage.intent.intent_name))


with Hermes(MQTT_ADDR) as h: # Initialization of a connection to the MQTT broker
	h.subscribe_intent("searchWeatherForecast", subscribe_weather_forecast_callback) \  # Registering callback functions to handle the searchWeatherForecast intent
         .start() 

# We get out of the with block, which closes and releases the connection. 

Initialization

The connection to your MQTT broker can be configured with the hermes_python.ffi.utils.MqttOptions class.

The Hermes client uses the options specified in the MqttOptions class when establishing the connection to the MQTT broker.

Here is a code example :

from hermes_python.hermes import Hermes
from hermes_python.ffi.utils import MqttOptions

mqtt_opts = MqttOptions()

def simple_intent_callback(hermes, intent_message):
    print("I received an intent !")

with Hermes(mqtt_options=mqtt_opts) as h:
    h.subscribe_intents().loop_forever()

Here are the options you can specify in the MqttOptions class :

  • broker_address: The address of the MQTT broker. It should be formatted as ip:port.
  • username: Username to use on the broker. Nullable
  • password: Password to use on the broker. Nullable
  • tls_hostname: Hostname to use for the TLS configuration. Nullable, setting a value enables TLS
  • tls_ca_file: CA files to use if TLS is enabled. Nullable
  • tls_ca_path: CA path to use if TLS is enabled. Nullable
  • tls_client_key: Client key to use if TLS is enabled. Nullable
  • tls_client_cert: Client cert to use if TLS is enabled. Nullable
  • tls_disable_root_store: Boolean indicating if the root store should be disabled if TLS is enabled.

Let's connect to an external MQTT broker that requires a username and a password :

from hermes_python.hermes import Hermes
from hermes_python.ffi.utils import MqttOptions

mqtt_opts = MqttOptions(username="user1", password="password", broker_address="my-mqtt-broker.com:18852")

def simple_intent_callback(hermes, intent_message):
    print("I received an intent !")

with Hermes(mqtt_options=mqtt_opts) as h:
    h.subscribe_intents().loop_forever()

Examples

Handling the intent_message object

Coming soon.

Providing TTS feedback for a voice application

Coming soon.

Documentation

Hermes protocol documentation

If you want to dive deeper into how Snips components communicate together, check out the specification of the hermes-protocol here. You can also check this repository for other language bindings.

API

Coming soon.

Release Checklist

Everytime you need to perform a release, do the following steps :

  • [x] Commit all changes to the project for said release
  • [x] Write all the changes introduced in the Changelog (HISTORY.rst file) and commit it
  • [x] Run tests
  • [x] Bump the version and commit it
  • [ ] Upload to PyPI

Building from sources

Creating macOS wheels

The build script : build_scripts/build_macos_wheels.sh uses pyenv to generate hermes-python wheels for different versions of python.

To be able to run it, you need to :

  • install pyenv : brew install pyenv. Then follow the additional steps (detailled here).
  • you then have to install python at different versions: pyenv install --list to list the available version to install.
  • Before installing and building the different python version from sources, install the required dependencies : https://github.com/pyenv/pyenv/wiki. (This was told in the first step).

You should be good to go !

History

0.3.3 (2019-03-06)

  • Fixes a bug with publish_start_session_notification that didn't take the text parameter into account.

0.3.2 (2019-02-25)

  • Fixes an important bug that gave the argument hermes the wrong type for every registered callback.
  • Fixes an important bug that caused the program to crash when parsing intentMessage that had no slots.

0.3.1 (2019-02-25)

  • Fixes import bug with templates, the hermes_python.ffi.utils module now re-exports MqttOptions

0.3.0 (2019-02-25)

  • IntentClassifierResult's probability field has been renamed to confidence_score.
  • Introduces support for snips-platform 1.1.0 - 0.61.1.

0.2.0 (2019-02-04)

  • Introduces options to connect to the MQTT broker (auth + TLS are now supported).

0.1.29 (2019-01-29)

  • Fixes bug when deserializing TimeIntervalValue that used wrong encode method instead of decode.

0.1.28 (2019-01-14)

  • Fixes bug when the __exit__ method was called twice on the Hermes class.
  • Introduces two methods to the public api : connect and disconnect that should bring more flexibility

0.1.27 (2019-01-07)

  • Fixed broken API introduced in 0.1.26 with the publish_continue_session method of the Hermes class.
  • Cast any string that goes in the mqtt_server_adress parameter in the constructor of the Hermes class to be a 8-bit string.

0.1.26 (2019-01-02)

  • LICENSING : This wheel now has the same licenses as the parent project : APACHE-MIT.
  • Subscription to not recognized intent messages is added to the API. You can now write your own callbacks to handle unrecognized intents.
  • Adds send_intent_not_recognized flag to continue session : indicate whether the dialogue manager should handle non recognized intents by itself or sent them as an IntentNotRecognizedMessage for the client to handle.

0.1.25 (2018-12-13)

  • Better error handling : Errors from wrapped C library throw a LibException with detailled errors.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for hermes-python, version 0.3.3
Filename, size File type Python version Upload date Hashes
Filename, size hermes_python-0.3.3-cp27-cp27m-macosx_10_14_x86_64.whl (2.2 MB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp27-cp27m-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp27-cp27mu-linux_armv6l.whl (2.9 MB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp27-cp27mu-linux_armv7l.whl (2.9 MB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp27-cp27mu-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp27 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp34-cp34m-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp34 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp35-cp35m-linux_armv6l.whl (2.9 MB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp35-cp35m-linux_armv7l.whl (2.9 MB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp35-cp35m-macosx_10_14_x86_64.whl (2.2 MB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp35-cp35m-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp35 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp36-cp36m-macosx_10_14_x86_64.whl (2.2 MB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp36-cp36m-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp37-cp37m-macosx_10_14_x86_64.whl (2.2 MB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size hermes_python-0.3.3-cp37-cp37m-manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp37 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page