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.3 (2019-03-06)
- Fixes a bug with
publish_start_session_notification
that didn't take thetext
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-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.3-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7be625585b607ebc9816349bc7c6a2c78a310415f890416da41e947dcf09c8d4 |
|
MD5 | 85bf6eecba940f665e3cee9f9f9e7fc9 |
|
BLAKE2b-256 | 1d56121559c4484fab43518b6ba9b235d6fc6e1644fc70bc6b7d5a7de1f1cd9a |
Hashes for hermes_python-0.3.3-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed9eda4991323941584f6291626b413561fd35cb65d083ce375c2bdfe45f67fc |
|
MD5 | 148acc8dd6d808ca8a54d91aab4c0d90 |
|
BLAKE2b-256 | e57404812648136587851c46de8f9be9a3b79190a94c1b188aad0622381be7e0 |
Hashes for hermes_python-0.3.3-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 10d3ef0fea0315d181396fbee4a39c7a2750930dc9711a52baf1a6114d0bdf19 |
|
MD5 | 9fbb6b32eacb3285869a1d2288a11d37 |
|
BLAKE2b-256 | 7db6cd99f97ab5066ddfe46a1f1a3d677b17bb8adcad760957973bf9159b55dc |
Hashes for hermes_python-0.3.3-cp36-cp36m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0bb4fe16014c48f80d333cfd5f52f9e1953d386c643c6a6000438e2cb598a945 |
|
MD5 | b719b8f172d9b874c045383f0720b454 |
|
BLAKE2b-256 | 1e4de7807d560cbb5ffc37d05b995c56b284e4c590407fb29f74a2c3c0a2763f |
Hashes for hermes_python-0.3.3-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 806a958085f3ae7a95b2116b78a2372244451431032019aae70074be8f47b21a |
|
MD5 | 1306ce30594efcaa75006708cbcf37e3 |
|
BLAKE2b-256 | b4909e53d9ed06a77e3b5b76f981f329269356f4947a3cb4abe8eb6328277890 |
Hashes for hermes_python-0.3.3-cp35-cp35m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ca5e01ff24945926df6827637b595d5de40eca2e840b08cec9d6ead64fa986d |
|
MD5 | 77b13fe219b6de53949bfb746cfe199f |
|
BLAKE2b-256 | f56110b9e5173d570b3c4b3f1ebfc1ccd9f662259685d97e9cb024df93cb49d9 |
Hashes for hermes_python-0.3.3-cp35-cp35m-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b374886d12c8853e85755640c365baf06e259921e21bc0e69ac6b64d07b53a36 |
|
MD5 | 58d05b0f6cbc928880743e759d15169f |
|
BLAKE2b-256 | 11e84b2d7f02c71e8a6d9a9ff437a58149668d5edf795dafda99477ea5e4cc4d |
Hashes for hermes_python-0.3.3-cp35-cp35m-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5b1aabdb42c9010ab3782c40958c6bd52bad59845cd873f7a8167f1cb9f5b0c1 |
|
MD5 | c798336d288a0889af9cf99c8d52d1f3 |
|
BLAKE2b-256 | 83a2d6eff02079027e7e04180542c31ccd1d44eeca147dbe5126c682ed1729a8 |
Hashes for hermes_python-0.3.3-cp34-cp34m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d4d457c5a70e21d7b01ca990c07903e73079aa14f63f9daf89f5a28b5b0736bc |
|
MD5 | 1beb0757059d8d8cf62d9c9d4850d771 |
|
BLAKE2b-256 | 581f51463318ef74a3f0c24ac4283f7ab9eba2a3f523860baf3905228f0b5bc5 |
Hashes for hermes_python-0.3.3-cp27-cp27mu-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ca9950f4073ceb2b0a5088c5caffde1ec34906fc5bfc0eeac1058751c9f44f2d |
|
MD5 | cc4984cfef3b9b3bd06b67599e006f4e |
|
BLAKE2b-256 | 4d95c6662d63f03d92b790e2a28e693b6423811187aae748c521b145ca038c85 |
Hashes for hermes_python-0.3.3-cp27-cp27mu-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 73f173f47bd5dfd06dbb6441d124259ab2c645b5c4e819879e8bbec810c3a26f |
|
MD5 | 028039238cb57b448a5507098bd8e0c7 |
|
BLAKE2b-256 | 2f8e55d8947320ce3b1e26623cbbc57c5bd937fee7ef9bfebf48f138e5b572e8 |
Hashes for hermes_python-0.3.3-cp27-cp27mu-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 336ff7aa58a0e953808b094dd0bac7a3b560ab1f77b983f321059cfecbf5839f |
|
MD5 | 563c66ca0962c0db309022372fe1f326 |
|
BLAKE2b-256 | 091567160376ed7d611763238738bab6b42311e850b0ee1831c116078d187796 |
Hashes for hermes_python-0.3.3-cp27-cp27m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c16f4d680c31a6ea2f0780a873449db8354d0d5e7cc9ffe751e78a208165cc4c |
|
MD5 | 68edd9ddef19b48ef5b2c7df85269f1f |
|
BLAKE2b-256 | 995c9216c4768ff062f4716a138fc11eea45bfd1eb116cb6491a42598335db9c |
Hashes for hermes_python-0.3.3-cp27-cp27m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2cd87628515c7fa45f0c345f92b0d0132764e5c42915f9444433f60114f6648b |
|
MD5 | d716d4457ca5b74c46189248f534e554 |
|
BLAKE2b-256 | b3ee2fbb8721b5161f0a8fa4f026966747e728d1feba34a96c753e5758e507db |