Python bindings for Snips Hermes Protocol
Project description
Hermes Python
.. image:: https://travis-ci.org/snipsco/hermes-protocol.svg :target: https://travis-ci.org/snipsco/hermes-protocol
.. image:: https://badge.fury.io/py/hermes-python.svg :target: https://badge.fury.io/py/hermes-python
About
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.
Requirements
Pre-compiled wheels are available for Python 2.7+ and Python 3.5
The pre-compiled wheels supports the following platform tags :
-
manylinux1_x86_64
-
armv7l
,armv6
-
macos
If you want to install hermes-python
on another platform, you have
to build it from source.
Installation
The library is packaged as a pre-compiled platform wheel, available on
PyPi <https://pypi.org/project/hermes-python/>
_.
It can be installed with : pip install hermes-python
.
Or you can add it to your requirements.txt file.
Building from source
If you want to use hermes-python
on platforms that are not
supported, you have to manually compile the wheel.
You need to have rust installed :
curl https://sh.rustup.rs -sSf
Clone, the hermes-protocol
repository :
::
git clone git@github.com:snipsco/hermes-protocol.git cd hermes-protocol
You need to compile the dynamically linked shared object library :
::
mkdir -p platforms/hermes-python/target CARGO_TARGET_DIR=platforms/hermes-python/target cargo rustc --lib --manifest-path hermes-mqtt-ffi/Cargo.toml --release -- --crate-type cdylib mv platforms/hermes-python/target/release/libhermes_mqtt_ffi.dylib platforms/hermes-python/hermes_python/dylib/
You can then build the wheel :
::
virtualenv env source env/bin/activate python setup.py bdist_wheel
The built wheels should be in platforms/hermes-python/dist
You can install those with pip : pip install platforms/hermes-python/dist/<your_wheel>.whl
Tutorial
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 <https://console.snips.ai/>
_, and that it has a
searchWeatherForecast
intent.
::
from hermes_python.hermes import Hermes
MQTT_ADDR = "localhost:1883" # Specify host and port for the MQTT broker
def subscribe_weather_forecast_callback(hermes, intent_message): # Defining callback functions to handle an intent that asks for the weather. print("Parsed intent : {}".format(intent_message.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.
This app is a bit limited as it only prints out which intent was detected by our assistant. Let’s add more features.
Handling the IntentMessage
object
In the previous example, we registered a callback that had this signature.
::
subscribe_intent_callback(hermes, intent_message)
The intent_message
object contains information that was extracted
from the spoken sentence.
For instance, in the previous code snippet, we extracted the name of the recognized intent with
::
intent_message.intent.intent_name
We could also retrieve the associated confidence score the NLU engine had when classifying this intent with
::
intent_message.intent.confidence_score
Extracting slots
Here are some best practices when dealing with slots. The
IntentMessage
object has a slots
attribute.
This slots
attributes is a container that is empty when the
intent message doesn’t have slots :
::
assert len(intent_message.slots) == 0
This container is a dictionary where the key is the name of the slot, and the value is a list of all the slot values for this slot name.
You can access these values in two ways :
::
assert len(intent_message.slots.slot1) == 0 assert len(intent_message.slots["slot1"]) == 0
The slot values are of type NluSlot
which is a deeply nested
object, we offer convenience methods to rapidly access the
slot_value attribute of the NluSlot.
To access the first slot_value
of a slot called myslot
, you
can use :
::
intent_message.slots.myslot.first()
You can also access all the slot_value
of a slot called myslot
:
::
intent_message.slots.myslot.all()
Let’s add to our Weather assistant example.
We assume that the searchWeatherForecast
has one slot called
forecast_location
, that indicates which location the user would
like to know the weather at.
Let’s print all the forecast_location
slots :
::
for slot in intent_message.slots.forecast_location: name = slot.slot_name confidence = slot.confidence_score print("For slot : {}, the confidence is : {}".format(name, confidence))
The dot notation was used, but we can also use the dictionary notation :
::
for slot in intent_message.slots.forecast_location: name = slot["slot_name"] print(name)
Some convenience methods are available to easily retrieve slot values :
Retrieving the first slot value for a given slot name
::
slot_value = intent_message.slots.forecast_location.first()
Retrieving all slot values for a given slot name
::
slot_values = intent_message.slots.forecast_location.all()
Coming back to our example, we can now have the app print the
forecast_location
slot value back to the user :
::
def subscribe_weather_forecast_callback(hermes, intent_message): slot_value = intent_message.slots.forecast_location.first().value print("The slot was : {}".format(slot_value)
Managing sessions
Snips platform includes support for conversations with back and forth communication between the Dialogue Manager and the client code. For a conversation, the dialogue manager creates sessions.
Starting a session
A session can be started in two manners :
-
with a notification
-
with an action
Ending a session
Slot Filling
Configuring MQTT options
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. 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()
Configuring Dialogue
hermes-python
offers the possibility to configure different
aspects of the Dialogue system.
Enabling and disabling intents on the fly
It is possible to enable and disable intents of your assistant on the fly. Once an intent is disabled, it will not be recognized by the NLU.
Note that intents in the intent filters of started or continued session will take precedence over intents that are enabled/disabled in the configuration of the Dialogue.
You can disable/enable intents with the following methods :
::
from hermes_python.ontology.dialogue.session import DialogueConfiguration
dialogue_conf = DialogueConfiguration()
.disable_intent("intent1")
.enable_intent("intent2")
.enable_intents(["intent1", "intent2"])
.disable_intents(["intent2", "intent1"])
hermes.configure_dialogue(dialogue_conf)
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 (source/HISTORY.rst file) and commit it - [ ] Run tests - [ ] Build the documentation and commit the README.rst - [ ] Bump the version and commit it - [ ] Upload to PyPI
Build details
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
-
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 :
Link here <https://github.com/pyenv/pyenv/wiki/>
_
That’s it ! History
0.4.4 (2019-03-20) ^^^^^^^^^^^^^^^^^^
- Adds support to configure the Dialogue Mananger : enabling and disabling intents on the fly.
- Adds slot filling API : You can ask for a specific slot when continuing a session
- adding support for
OrdinalSlot
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.4.0-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 57a51d41943b44c31960510c356c8f913ccac077f185e4ca310713c94645d1d4 |
|
MD5 | 73c998004a0ff536b721da6321f27814 |
|
BLAKE2b-256 | a08706db57a21c03af7c709029db2f2892cfaffb3744664ece265c6d853ee8f7 |
Hashes for hermes_python-0.4.0-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 83a6f8465fdcadc06733763d14870074ff512ea9deb7cf83fe89058d280a2f3b |
|
MD5 | ce0ba2c2d1dcfaf8103199dab218bfbf |
|
BLAKE2b-256 | c6ed11cc79dc0e24de371850fd1982ad0ee0777226f550827a224f0d0e43ea7b |
Hashes for hermes_python-0.4.0-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 176267535038e9611e1f862710700a0e8a24d41019cd3ce88c0bd5a9bb9e55a2 |
|
MD5 | 1789bd23703d8f9c0a509b950ea169f6 |
|
BLAKE2b-256 | 153dc02987ccedfd2de6169bc76fab21914849f2a5a05b4c4bd581d99cade434 |
Hashes for hermes_python-0.4.0-cp36-cp36m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e5fc49f01336c0e9df3266a9e29dcf2956a5b5bbec6f76a3c45d7624e40d423c |
|
MD5 | f7a8be31496cc60e6b8c934ce951f03a |
|
BLAKE2b-256 | 7122c156d76a6f9d05520e1fc9db8c88edd2e671bdfd5c9a5bf055665a5589e4 |
Hashes for hermes_python-0.4.0-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74b394a239e1e586d3d58270b640c13f0cbddd97ea51d999d7fc031f4f5e9559 |
|
MD5 | 36080979d9d512186b8332b44e78d82c |
|
BLAKE2b-256 | beb6c82e6f6939abfb838c02478ed6a8f92e7e46274347e9777a8a3b2f2e8316 |
Hashes for hermes_python-0.4.0-cp35-cp35m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5bd6270b4de6b9d9dba35e498cc1a4e6888391947983804db221d5f4d10e3288 |
|
MD5 | 6c554fc160f9266e01f342a1fb6ef212 |
|
BLAKE2b-256 | 4dde4ecb327f789a025a4a4637954ce0a61d4c40dabe2e022df2ccc232663872 |
Hashes for hermes_python-0.4.0-cp35-cp35m-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 762f86d3b04b93fa41fe2c3a376deeb9241a085a9cae60566f79c408330a0772 |
|
MD5 | d24870d9c90cc41707610e33c4cc8d06 |
|
BLAKE2b-256 | 6a3c4da4d8ced8bde8d88d4ea5eb007114ed972ffd9dd69a4a2630c401a1d1df |
Hashes for hermes_python-0.4.0-cp35-cp35m-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 038e58ecbe77a68a989fa744cb1b5947f673375c9162166c08332d3118aa22af |
|
MD5 | 54771afff5622ea70b3e41cb91e9675b |
|
BLAKE2b-256 | 90f2abc34094dd6e168fc5364450bfcc5caf601e01fb90525972025371d21027 |
Hashes for hermes_python-0.4.0-cp34-cp34m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d51e9aa3fa1803b0f3e49f64870680e90b833faffdd4c3bad4cc37a56058b44a |
|
MD5 | ed929d2aa3455f23541da99ddef5950c |
|
BLAKE2b-256 | fb5ccd1b7e4e3a3ea3f57d24aed3208ad4216e26c6bf486f027736629bec2708 |
Hashes for hermes_python-0.4.0-cp27-cp27mu-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b7e0bbe9a01a79d31d6acccba4599228794a4e60aa102dccd137939b5785c98d |
|
MD5 | ed78d6068aef5817c4f53175e7222feb |
|
BLAKE2b-256 | 9dd453042d8b15778d3e82f9093266c2a9a54e99bd81d779c2c6c6ed0e616bbc |
Hashes for hermes_python-0.4.0-cp27-cp27mu-linux_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ad33918697f02ece73e2a0808d78fba0fa845d3ff202d11b4782a6a8ec5450a |
|
MD5 | ec8a2767222f0d1131d640fddd3ad075 |
|
BLAKE2b-256 | f318a90135f6ac3908ea79552371b2e7f64ca997ad3a43a5228bf908212ea772 |
Hashes for hermes_python-0.4.0-cp27-cp27mu-linux_armv6l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e2fe390455bfadd7fecd5be3d504971394f71d2b8fba27df2186e3e561c9fda9 |
|
MD5 | 2a7d19130fffaf164ff11981559d770d |
|
BLAKE2b-256 | ef48f089fa295091ab76485a2bf7c5fcd4eaceb382d5329fd7f2b2100c27e558 |
Hashes for hermes_python-0.4.0-cp27-cp27m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 017793f5c0a535c2e7eda73b2dd0f9b66cdd3d6cc576fb838a131f8580d2b34f |
|
MD5 | e26505a81d2f9be1ebcf4bbfacc038db |
|
BLAKE2b-256 | 4f87c61445f7e843fab8bc3aa390991f6943c548f85d380432d3e24ad23f7554 |
Hashes for hermes_python-0.4.0-cp27-cp27m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f6668dcd1038bed940e132531b57d9a41a10d0a65b1568c03ffbc319097bf1f6 |
|
MD5 | 6b3a72a18f6922e8b48cdad5efc9db78 |
|
BLAKE2b-256 | fb8d8e8cb3e5ca9f632f6c894243797ffaf8d53df0fcf5bc0f5c6acdfc4b7ea2 |