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)

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)

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)

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)

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.

on_hotword(function: Callable[[rhasspyhermes.wake.HotwordDetected], None]) → Callable[[rhasspyhermes.wake.HotwordDetected], None]

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]]

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]

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)

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)

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()

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])

Bases: object

Helper class for topic subscription.

topic

The MQTT topic.

data

A dictionary holding extracted data for the given placeholder.