API reference¶
This is the API documentation of the Rhasspy Hermes App package, covering all modules and classes.
rhasspyhermes_app¶
Helper library to create voice apps for Rhasspy using the Hermes protocol.
-
class
rhasspyhermes_app.
ContinueSession
(custom_data: Optional[str] = None, text: Optional[str] = None, intent_filter: Optional[List[str]] = None, send_intent_not_recognized: bool = False)[source]¶ Bases:
object
Helper class to continue the current session.
-
text
¶ The text the TTS should say to start this additional request of the session.
-
intent_filter
¶ A list of intents names to restrict the NLU resolution on the answer of this query.
-
custom_data
¶ An update to the session’s custom data. If not provided, the custom data will stay the same.
-
send_intent_not_recognized
¶ Indicates whether the dialogue manager should handle non recognized intents by itself or send them for the client to handle.
-
-
class
rhasspyhermes_app.
EndSession
(text: Optional[str] = None, custom_data: Optional[str] = None)[source]¶ Bases:
object
Helper class to end the current session.
-
text
¶ The text the TTS should say to end the session.
-
custom_data
¶ An update to the session’s custom data. If not provided, the custom data will stay the same.
-
-
class
rhasspyhermes_app.
HermesApp
(name: str, parser: Optional[argparse.ArgumentParser] = None, mqtt_client: Optional[paho.mqtt.client.Client] = None)[source]¶ Bases:
rhasspyhermes.client.HermesClient
A Rhasspy app using the Hermes protocol.
-
args
¶ Command-line arguments for the Hermes app.
Example:
"""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") def get_time(intent: NluIntent): """Tell the time.""" now = datetime.now().strftime("%H %M") return EndSession(f"It's {now}") app.run()
-
__init__
(name: str, parser: Optional[argparse.ArgumentParser] = None, mqtt_client: Optional[paho.mqtt.client.Client] = None)[source]¶ Initialize the Rhasspy Hermes app.
- Parameters
name – The name of this object.
parser – An argument parser. If the argument is not specified, the object creates an argument parser itself.
mqtt_client – An MQTT client. If the argument is not specified, the object creates an MQTT client itself.
-
notify
(text: str, site_id: str = 'default')[source]¶ Send a dialogue notification.
Use this to inform the user of something without expecting a response.
- Parameters
text – The text to say.
site_id – The ID of the site where the text should be said.
-
on_dialogue_intent_not_recognized
(function: Callable[[rhasspyhermes.dialogue.DialogueIntentNotRecognized], Union[ContinueSession, EndSession, None]]) → Callable[[rhasspyhermes.dialogue.DialogueIntentNotRecognized], None][source]¶ Apply this decorator to a function that you want to act when the dialogue manager failed to recognize an intent and you requested to notify you of this event with the sendIntentNotRecognized flag.
The decorated function has a
rhasspyhermes.dialogue.DialogueIntentNotRecognized
object as an argument and can return aContinueSession
orEndSession
object or have no return value.If the function returns a
ContinueSession
object, the current session is continued after saying the supplied text. If the function returns a aEndSession
object, the current session is ended after saying the supplied text, or immediately when no text is supplied. If the function doesn’t have a return value, nothing is changed to the session.Example:
@app.on_dialogue_intent_not_recognized def not_understood(intent_not_recognized: DialogueIntentNotRecognized): print(f"Didn't understand "{intent_not_recognized.input}" on site {intent_not_recognized.site_id}")
If an intent hasn’t been recognized, the
not_understood
function is called with theintent_not_recognized
argument. This object holds information about the not recognized intent.
-
on_hotword
(function: Callable[[rhasspyhermes.wake.HotwordDetected], None]) → Callable[[rhasspyhermes.wake.HotwordDetected], None][source]¶ Apply this decorator to a function that you want to act on a detected hotword.
The decorated function has a
rhasspyhermes.wake.HotwordDetected
object as an argument and doesn’t have a return value.Example:
@app.on_hotword def wake(hotword: HotwordDetected): print(f"Hotword {hotword.model_id} detected on site {hotword.site_id}")
If a hotword has been detected, the
wake
function is called with thehotword
argument. This object holds information about the detected hotword.
-
on_intent
(*intent_names: str) → Callable[[Callable[[rhasspyhermes.nlu.NluIntent], Union[rhasspyhermes_app.ContinueSession, rhasspyhermes_app.EndSession]]], Callable[[rhasspyhermes.nlu.NluIntent], None]][source]¶ Apply this decorator to a function that you want to act on a received intent.
- Parameters
intent_names – Names of the intents you want the function to act on.
The decorated function has a
rhasspyhermes.nlu.NluIntent
object as an argument and needs to return aContinueSession
orEndSession
object.If the function returns a
ContinueSession
object, the intent’s session is continued after saying the supplied text. If the function returns a aEndSession
object, the intent’s session is ended after saying the supplied text, or immediately when no text is supplied.Example:
@app.on_intent("GetTime") def get_time(intent: NluIntent): return EndSession("It's too late.")
If the intent with name GetTime has been detected, the
get_time
function is called with theintent
argument. This object holds information about the detected intent.
-
on_intent_not_recognized
(function: Callable[[rhasspyhermes.nlu.NluIntentNotRecognized], Union[ContinueSession, EndSession, None]]) → Callable[[rhasspyhermes.nlu.NluIntentNotRecognized], None][source]¶ Apply this decorator to a function that you want to act when the NLU system hasn’t recognized an intent.
The decorated function has a
rhasspyhermes.nlu.NluIntentNotRecognized
object as an argument and can return aContinueSession
orEndSession
object or have no return value.If the function returns a
ContinueSession
object, the current session is continued after saying the supplied text. If the function returns a aEndSession
object, the current session is ended after saying the supplied text, or immediately when no text is supplied. If the function doesn’t have a return value, nothing is changed to the session.Example:
@app.on_intent_not_recognized def not_understood(intent_not_recognized: NluIntentNotRecognized): print(f"Didn't understand "{intent_not_recognized.input}" on site {intent_not_recognized.site_id}")
If an intent hasn’t been recognized, the
not_understood
function is called with theintent_not_recognized
argument. This object holds information about the not recognized intent.
-
async
on_raw_message
(topic: str, payload: bytes)[source]¶ This method handles messages from the MQTT broker.
- Parameters
topic – The topic of the received MQTT message.
payload – The payload of the received MQTT message.
Warning
Don’t override this method in your app. This is where all the magic happens in Rhasspy Hermes App.
-
on_topic
(*topic_names: str)[source]¶ Apply this decorator to a function that you want to act on a received raw MQTT message.
- Parameters
topic_names – The MQTT topics you want the function to act on.
The decorated function has a
TopicData
and abytes
object as its arguments. The former holds data about the topic and the latter about the payload of the MQTT message.Example:
@app.on_topic("hermes/+/{site_id}/playBytes/#") def test_topic1(data: TopicData, payload: bytes): _LOGGER.debug("topic: %s, site_id: %s", data.topic, data.data.get("site_id"))
Note
The topic names can contain MQTT wildcards (+ and #) or templates ({foobar}). In the latter case, the value of the named template is available in the decorated function as part of the
TopicData
argument.
-