Python bindings for Snips Hermes Protocol
Project description
Hermes Python
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 asip:port
.username
: Username to use on the broker. Nullablepassword
: Password to use on the broker. Nullabletls_hostname
: Hostname to use for the TLS configuration. Nullable, setting a value enables TLStls_ca_file
: CA files to use if TLS is enabled. Nullabletls_ca_path
: CA path to use if TLS is enabled. Nullabletls_client_key
: Client key to use if TLS is enabled. Nullabletls_client_cert
: Client cert to use if TLS is enabled. Nullabletls_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 :
- Commit all changes to the project for said release
- Write all the changes introduced in the Changelog (HISTORY.rst file) and commit it
- Run tests
- 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.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-exportsMqttOptions
0.3.0 (2019-02-25)
IntentClassifierResult
'sprobability
field has been renamed toconfidence_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 wrongencode
method instead ofdecode
.
0.1.28 (2019-01-14)
- Fixes bug when the
__exit__
method was called twice on theHermes
class. - Introduces two methods to the public api :
connect
anddisconnect
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for hermes_python-0.3.2-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 153a466f55b6b7b931b64a6cb2a3da85460c178dc566daef3267739f1120109e |
|
MD5 | feb057b9b18378974093b72ef3aa65db |
|
BLAKE2b-256 | e56e0231b32262cc294640090d6e07b9bed53d0f07e453dfc286e0829ff88556 |
Hashes for hermes_python-0.3.2-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd9a04e2c42b9779a0c9cbc6203b88e617fda44be741607eb5b3933425ea81e0 |
|
MD5 | a3ff920aa8c299841b20a9fe42ffaad2 |
|
BLAKE2b-256 | 526f3ea933981460d66ef53fa4d2adcee5e5d071c8b0e67ccbcfbd90d493c48e |
Hashes for hermes_python-0.3.2-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5888362ec7646fd8d83fc5bea5497b0f00dda6c5cf3debcfaf9c5fe3b90c4d4d |
|
MD5 | 1665b83cf05978b15968f9324809cecf |
|
BLAKE2b-256 | f3932d11a2a0f0c4194c488ad6c7b65075ae4e78c984b88f1c99cb04f9cf47b6 |
Hashes for hermes_python-0.3.2-cp36-cp36m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b469031712b0e4cf99181deefb603969fdd29cdd5d707b83ded0176bfa6f1ab7 |
|
MD5 | 188d88def1d0155b3764df8528234798 |
|
BLAKE2b-256 | f280bb32b38a9793a6d34e97d2e0fffd9e87474137ad7e30d0b6ba4f74f89e64 |
Hashes for hermes_python-0.3.2-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 852481e070b98c5ef4c96bff53675dfdf316525511d48af02780e71411445cfd |
|
MD5 | 65b176a7aa9c45587244207087767b20 |
|
BLAKE2b-256 | b7e7821de9d92d4d3ce80a0f01fcf31911fb665a6bba4525033e5b52eb16864a |
Hashes for hermes_python-0.3.2-cp35-cp35m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 479930ee9af28f9b661e63748d0b2faed4d2e47030e0959dfe5b4f8c64699603 |
|
MD5 | 67405360a9c68986e4d49c7d74e51819 |
|
BLAKE2b-256 | 260e9ec10b463bf30a7a1e64ec58be54a23115abdd6d525da726b3e207140957 |
Hashes for hermes_python-0.3.2-cp35-cp35m-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 09701f200e8b2f973482697b6ea7c8bfa8a40487b383e24d50e4e82fec01e3f0 |
|
MD5 | 4b1e7c17adb98536ecf6ce4b26d6dca0 |
|
BLAKE2b-256 | 140a359ac7684f667696cff7b50d8edffb3f1969631e083cca872f5ccbb97d64 |
Hashes for hermes_python-0.3.2-cp35-cp35m-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 98303bdc06a875affde55536407334ea00e0ac9062b9768a067a9ec0799b8279 |
|
MD5 | aa96f421fbf188c506a76c6dcfc77819 |
|
BLAKE2b-256 | 1491fb930a9c1f0a79cdeb6311ba05fd78477da8655f477d29eb2813da23848e |
Hashes for hermes_python-0.3.2-cp34-cp34m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93680256ba12d7cd6b10767f762cdbf62d2f3eabae20c52c65a5731c1a8d7aa3 |
|
MD5 | a458650eb6dcd1d3e6650b360f6006fb |
|
BLAKE2b-256 | 8bc7fcc458a51013d4e932563db6314a32ef78b9a896d272c3a91a3d78fa0d39 |
Hashes for hermes_python-0.3.2-cp27-cp27mu-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 77ab13857dd5e629441f1275046ee1b3b8af2687595aba3fb475584430196170 |
|
MD5 | 801c78e89cb3f2bb24659c5194b2e365 |
|
BLAKE2b-256 | d6be371870f0ace609b67fb7514cc2d84ed677bc0bd6a0618bfb988fe843773b |
Hashes for hermes_python-0.3.2-cp27-cp27mu-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7015381064f2b583fcf03dd220e51b452f07f1b38fcc2253d04f89e1754799b9 |
|
MD5 | 36757c952f8635e22e8c3e707f9c75c5 |
|
BLAKE2b-256 | d93052e3d90f2c5ba8f901c924bf06faa42b39d76b2a5f77cac0018f89eed1f8 |
Hashes for hermes_python-0.3.2-cp27-cp27mu-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f316ecf89559b46f66612ff3ec9de86ba443f889e0573a043294222b1bb1fbaa |
|
MD5 | 3a913f72bc152013276c2aa536bf18c5 |
|
BLAKE2b-256 | 970c17b3f81312b5854e8120bb90c76f133cc57ee92729b9bc346cc4fddbbf85 |
Hashes for hermes_python-0.3.2-cp27-cp27m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed194fbb5c464be5943c6305b8bcfb6349f15b73e22592b819a11ee4b102cb1d |
|
MD5 | c2bb0abd2977a0786ef9bf197f4e5e13 |
|
BLAKE2b-256 | 8d3cce15a3f504af39bcc24b108d9a3992d42b28425674167ae7300dbc336e90 |
Hashes for hermes_python-0.3.2-cp27-cp27m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d0149d793795d0c11a06d94377021126a2824eca1205dc369fcbb52f073ae6bf |
|
MD5 | e7d3ca6e8486db332ddfcc5d3f56d7d0 |
|
BLAKE2b-256 | c94934e71d0ee999a47e67d0bb79bd02dc9a4df6e415c36788dd96baacdded5d |