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 a ContinueSession or EndSession 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 a EndSession 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 the intent_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 the hotword 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 a ContinueSession or EndSession object.

If the function returns a ContinueSession object, the intent’s session is continued after saying the supplied text. If the function returns a a EndSession 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 the intent 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 a ContinueSession or EndSession 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 a EndSession 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 the intent_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 a bytes 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.

run()[source]

Run the app. This method:

  • subscribes to all MQTT topics for the functions you decorated;

  • connects to the MQTT broker;

  • starts the MQTT event loop and reacts to received MQTT messages.

class rhasspyhermes_app.TopicData(topic: str, data: Dict[str, str])[source]

Bases: object

Helper class for topic subscription.

topic

The MQTT topic.

data

A dictionary holding extracted data for the given placeholder.