Usage¶
The design philosophy of Rhasspy Hermes App is:
It should be easy to create a Rhasspy app with minimal boilerplate code.
All Rhasspy Hermes App code should behave by default in a sensible way.
Reacting to an intent¶
This example app reacts to the default “GetTime” intent that comes with Rhasspy’s installation by telling you the current time:
"""Example app to react to an intent to tell you the time."""
import logging
from datetime import datetime
from rhasspyhermes.nlu import NluIntent
from rhasspyhermes_app import EndSession, HermesApp
_LOGGER = logging.getLogger("TimeApp")
app = HermesApp("TimeApp")
@app.on_intent("GetTime")
async def get_time(intent: NluIntent):
"""Tell the time."""
now = datetime.now().strftime("%H %M")
return EndSession(f"It's {now}")
app.run()
Ignoring the import lines and the logger, what this code does is:
creating a
rhasspyhermes_app.HermesApp
object;defining an async function
get_time
that ends a session by telling the time;running the app.
By applying the app’s rhasspyhermes_app.HermesApp.on_intent()
decorator to the function, this function will be called whenever the app receives an intent with the name “GetTime”.
Try the example app time_app.py with the --help
flag to see what settings you can use to start the app (mostly connection settings for the MQTT broker):
$ python3 examples/time_app.py --help
usage: TimeApp [-h] [--host HOST] [--port PORT] [--username USERNAME]
[--password PASSWORD] [--tls] [--tls-ca-certs TLS_CA_CERTS]
[--tls-certfile TLS_CERTFILE] [--tls-keyfile TLS_KEYFILE]
[--tls-cert-reqs {CERT_REQUIRED,CERT_OPTIONAL,CERT_NONE}]
[--tls-version TLS_VERSION] [--tls-ciphers TLS_CIPHERS]
[--site-id SITE_ID] [--debug] [--log-format LOG_FORMAT]
optional arguments:
-h, --help show this help message and exit
--host HOST MQTT host (default: localhost)
--port PORT MQTT port (default: 1883)
--username USERNAME MQTT username
--password PASSWORD MQTT password
--tls Enable MQTT TLS
--tls-ca-certs TLS_CA_CERTS
MQTT TLS Certificate Authority certificate files
--tls-certfile TLS_CERTFILE
MQTT TLS client certificate file (PEM)
--tls-keyfile TLS_KEYFILE
MQTT TLS client key file (PEM)
--tls-cert-reqs {CERT_REQUIRED,CERT_OPTIONAL,CERT_NONE}
MQTT TLS certificate requirements for broker (default:
CERT_REQUIRED)
--tls-version TLS_VERSION
MQTT TLS version (default: highest)
--tls-ciphers TLS_CIPHERS
MQTT TLS ciphers to use
--site-id SITE_ID Hermes site id(s) to listen for (default: all)
--debug Print DEBUG messages to the console
--log-format LOG_FORMAT
Python logger format
Asyncio¶
Every function that you decorate with Rhasspy Hermes App should be defined with the async
keyword. However, you don’t have to use the async functionality.
For apps which are time intensive by e.g. using database queries or API calls, we recommend the use of asynchronous functions. These allow your code to handle multiple requests at the same time and therefore cutting down on precious runtime.
Try the example app async_advice_app.py.
Other example apps¶
The GitHub repository has a couple of other example apps showing the library’s functionality:
Building an app on this library¶
If the API of this library changes, your app possibly stops working when it updates to the newest release of Rhasspy Hermes App. Therefore, it’s best to define a specific version in your requirements.txt
file, for instance:
rhasspy-hermes-app==0.2.0
This way your app keeps working when the Rhasspy Hermes App adds incompatible changes in a new version.
The project adheres to the Semantic Versioning specification with major, minor and patch version.
Given a version number major.minor.patch, this project increments the:
major version when incompatible API changes are made;
minor version when functionality is added in a backwards-compatible manner;
patch version when backwards-compatible bug fixes are made.
More information¶
More information about the usage of the Rhasspy Hermes App library can be found in the API reference.