API Reference

The Hermes Client

class hermes_python.hermes.Hermes(broker_address=None, rust_logs_enabled=False, mqtt_options=<hermes_python.ontology.MqttOptions object>, use_json_api=False)
configure_dialogue(configure_message)

Publish configuration message for different aspects of the Dialogue system.

Parameters:configure_message – DialogueConfiguration the configuration that will be sent to the dialogue Manager
Returns:the current instance of Hermes to allow chaining.
disable_sound_feedback(site_message)

Toggles off the sound feedback for the snips platform for a given site_id and optionally for a session_id defined in the site_message.

Parameters:site_message – SiteMessage where the sound feedback will be turned off.
Returns:the current instance of Hermes to allow chaining.
enable_sound_feedback(site_message)

Toggles on the sound feedback for the snips platform for a given site_id and optionally for a session_id defined in the site_message.

Parameters:site_message – SiteMessage where the sound feedback will be turned on.
Returns:the current instance of Hermes to allow chaining.
loop_forever()

This is a convenience method to loop forever in a blocking fashion.

loop_start()

to set a thread running to call a infinite loop for you.

publish_continue_session(session_id, text, intent_filter, custom_data=None, send_intent_not_recognized=False, slot_to_fill=None)

Publishes a ContinueSession message to the Dialogue Manage to continue a dialogue session.

Parameters:
  • session_id – The identifier of the session to be continued.
  • 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. Can be an empty list.
  • send_intent_not_recognized – An optional boolean to indicate whether the dialogue manager should handle non recognized intents by itself or sent them as an IntentNotRecognizedMessage for the client to handle. This setting applies only to the next conversation turn. The default value is false (and the dialogue manager will handle non recognized intents by itself)
  • slot_to_fill – is an Optional string. It requires intent_filter to contain a single value. If set, the dialogue engine will not run the the intent classification on the user response and will go straight to slot filling, assuming the intent is the one passed in the intent_filter, and searching the value of the given slot.
Returns:

the current instance of Hermes to allow chaining.

publish_end_session(session_id, text)

Publishes a EndSession message to the Dialogue Manager to end a dialogue session.

When the handler received the intents it needs, or when the handler wants to explicitly end a running session, it should send this endSession message with the given session_id.

Parameters:
  • session_id – Session identifier to end.
  • text – The text the TTS should say to end the session.
Returns:

the current instance of Hermes to allow chaining.

publish_start_session_action(site_id, session_init_text, session_init_intent_filter, session_init_can_be_enqueued, session_init_send_intent_not_recognized, custom_data)

Publishes a StartSession message to the Dialogue Manager to initiate a new session.

This message can be sent by the handler code to programmatically initiate a new session. Use this type when you need the end user to respond. The Dialogue Manager will start the session by asking the TTS to say the text (if any) and wait for the answer of the end user.

Parameters:
  • site_id – Site where the user started the interaction.
  • session_init_text – Text that the TTS should say at the beginning of the session.
  • session_init_intent_filter – A list of intents names to restrict the NLU resolution on the first query.
  • session_init_can_be_enqueued – if true, the session will start when there is no pending one on this siteId, if false, the session is just dropped if there is running one.
  • custom_data – Additional information that can be provided by the handler. Each message related to the new session - sent by the Dialogue Manager - will contain this data.
Returns:

the current instance of Hermes to allow chaining.

publish_start_session_notification(site_id, session_initiation_text, custom_data, text='')

Publishes a StartSession message to the Dialogue Manager to initiate a new session.

This message can be sent by the handler code to programmatically initiate a new session. Use this type when you only want to inform the user of something without expecting a response.

Parameters:
  • site_id – Site where the user started the interaction.
  • session_initiation_text – Text the TTS should say.
  • custom_data – Additional information that can be provided by the handler. Each message related to the new session - sent by the Dialogue Manager - will contain this data.
  • text – Text the TTS should say. This parameter was introduced by mistake and shouldn’t be used.
Returns:

the current instance of Hermes to allow chaining.

register_sound(sound)

Register a sound that can later be played by the TTS.

Parameters:sound – a sound to be played by the TTS.
Returns:the current instance of Hermes to allow chaining.
request_injection(injection_request)

Publishes an injection request to the platform.

Note that this function is asynchronous. You can check the status of the injection by registering a injection complete callback with the subscribe_injection_complete method of hermes.

Parameters:injection_request – An object that contains the different injection requests operations.
Returns:the current instance of Hermes to allow chaining.
request_injection_reset(injection_reset_request)

Publishes an injection reset request to the platform.

Note that this function is asynchronous. You can check the status of the injection reset by registering a injection reset complete callback with the subscribe_injection_reset_complete method of hermes.

Parameters:injection_reset_request – An request object to reset the injection to its factory settings;
Returns:the current instance of Hermes to allow chaining.
start()

DEPRECATED. This method is just kept for compatibility with previous versions of the library.

subscribe_injection_complete(user_callback_injection_complete)

Registers a callback to be triggered when an injection process is completed.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • injectionCompleteMessage :
    • A python representation of the message of completion for an injection operation (for json_repr set to False)
    • A json representation of the the message of completion for an injection operation (for json_repr set to True)
Parameters:user_callback_injection_complete (Callable[[Hermes, InjectionCompleteMessage]) – the callback that will be executed when a launched injection operation is completed.
Returns:the current instance of Hermes to allow chaining.
subscribe_injection_reset_complete(user_callback_injection_reset_complete)

Registers a callback to be triggered when an injection reset process is completed.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • injectionResetCompleteMessage:
    • A python representation of the message of completion for an injection reset operation (for json_repr set to False)
    • A json representation of the the message of completion for an injection reset operation (for json_repr set to True)
Parameters:user_callback_injection_reset_complete (Callable[[Hermes, InjectionResetCompleteMessage]) –
Returns:
subscribe_intent(intent_name, user_callback_subscribe_intent)

Registers a callback to be triggered when the intent intent_name is recognized.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • intentMessage :
    • A python representation of the intent parsed by the NLU engine (for json_repr set to False)
    • A json representation of the intent parsed by the NLU engine. (for json_repr set to True)
Parameters:
  • intent_name – the name of the intent to subscribe to.
  • user_callback_subscribe_intent – the callback that will be executed when intent_name is recognized.
Returns:

the current instance of Hermes to allow chaining.

subscribe_intent_not_recognized(user_callback_subscribe_intent_not_recognized)

Register a callback when the Dialogue Manager doesn’t recognize an intent.

Note that you need to have initialized a session, (or call publish_continue_session method on an existing session) with the intent_not_recognized field set to true. Otherwise, the DialogueManager will take care itself of not recognized intent and the callback you registered will never be called.

The callback will be called with the following parameters :
  • hermes: the current instance of the Hermes object
  • intentNotRecognizedMessage : message that the handler receives from the Dialogue Manager when an intent is not recognized.
Parameters:user_callback_subscribe_intent_not_recognized – the callback executed when an intent is not recognized.
Returns:the current instance of Hermes to allow chaining.
subscribe_intents(user_callback_subscribe_intents)

Register a callback to be triggered everytime an intent is recognized.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • intentMessage : A python representation of the intent parsed by the NLU engine.
Parameters:user_callback_subscribe_intents – The callback to be executed when any intent is parsed by the platform.
Returns:the current instance of Hermes to allow chaining.
subscribe_session_ended(user_callback_subscribe_session_ended)

Register a callback when the Dialogue Manager ends a session.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • sessionEndedMessage : message that the handler receives from the Dialogue Manager when a session is ended.
Parameters:user_callback_subscribe_session_ended – the callback to be executed when a new dialogue session is ended.
Returns:the current instance of Hermes to allow chaining.
subscribe_session_queued(user_callback_subscribe_session_queued)

Register a callback when the Dialogue Manager queues the current session.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • sessionQueuedMessage : message that the handler receives from the Dialogue Manager when a session is queued.
Parameters:user_callback_subscribe_session_queued – the callback to be executed when a new dialogue session is queued.
Returns:the current instance of Hermes to allow chaining.
subscribe_session_started(user_callback_subscribe_session_started)

Register a callback when the Dialogue Manager starts a new session.

The callback will be called with the following parameters :
  • hermes : the current instance of the Hermes object
  • sessionStartedMessage : message that the handler receives from the Dialogue Manager when a session is started.
Parameters:user_callback_subscribe_session_started – the callback to be executed when a new dialogue session is started.
Returns:the current instance of Hermes to allow chaining.

Ontology

Session

class hermes_python.ontology.dialogue.session.StartSessionMessage(session_init, custom_data=None, site_id=None)
__init__(session_init, custom_data=None, site_id=None)
Parameters:
  • session_init (SessionInit) – The way this session was created
  • custom_data (Text) – An optional piece of data that will be given back in IntentMessage, IntentNotRecognizedMessage, SessionQueuedMessage, SessionStartedMessage and SessionEndedMessage that are related to this session
  • site_id (Text) – The site where the session should be started, a value of None will be interpreted as the default one
class hermes_python.ontology.dialogue.session.EndSessionMessage(session_id, text=None)
__init__(session_id, text=None)
Parameters:
  • session_id (Text) – The id of the session to end
  • text (Optional[Text]) – An optional text to say to the user before ending the session
class hermes_python.ontology.dialogue.session.ContinueSessionMessage(session_id, text, intent_filter, custom_data, send_intent_not_recognized, slot=None)
__init__(session_id, text, intent_filter, custom_data, send_intent_not_recognized, slot=None)
Parameters:
  • session_id (Text) – Identifier of the dialogue session during which this intent was parsed.
  • text (Text) –
  • intent_filter (List[Text]) – a list of allowed intent names that the dialogue manager will use to filter incoming intents. Nullable argument
  • custom_data (Optional[Text]) – Nullable argument.
  • send_intent_not_recognized (bool) – An optional boolean to indicate whether the dialogue manager should handle non recognized intents by itself or sent them as an IntentNotRecognizedMessage for the client to handle. This setting applies only to the next conversation turn. The default value is false (and the dialogue manager will handle non recognized intents by itself)
  • slot (Optional[Text]) – An optional string, requires intent_filter to contain a single value. If set, the dialogue engine will not run the the intent classification on the user response and go straight to slot filling, assuming the intent is the one passed in the intent_filter, and searching the value of the given slot
class hermes_python.ontology.dialogue.session.SessionStartedMessage(session_id, custom_data, site_id, reactivated_from_session_id)
__init__(session_id, custom_data, site_id, reactivated_from_session_id)

A message that the handler receives from the Dialogue Manager when a session is started.

Parameters:
  • session_id (Text) – Session identifier that was started.
  • custom_data (Optional[Text]) – Custom data provided in the start session request on.
  • site_id (Text) – Site where the user interaction is taking place.
  • reactivated_from_session_id – NOT IMPLEMENTED YET. This feature is coming soon. This optional field indicates this session is a reactivation of a previously ended session. This is for example provided when the user continues talking to the platform without saying the hotword again after a session was ended.
class hermes_python.ontology.dialogue.session.SessionEndedMessage(session_id, custom_data, site_id, termination)
__init__(session_id, custom_data, site_id, termination)

A message that the handler receives from the Dialogue Manager when a session is ended.

Parameters:
  • session_id (Text) – Session identifier that was started.
  • custom_data (Optional[Text]) – Custom data provided in the start session request on.
  • site_id (Text) – Site where the user interaction is taking place.
  • termination (SessionTermination) – Structured description of why the session has been ended.
class hermes_python.ontology.dialogue.session.SessionQueuedMessage(session_id, custom_data, site_id)
__init__(session_id, custom_data, site_id)

A message that the handler receives from the Dialogue Manager when a session is queued.

Parameters:
  • session_id (Text) – Session identifier that was started.
  • custom_data (Optional[Text]) – Custom data provided in the start session request on.
  • site_id (Text) – Site where the user interaction is taking place
class hermes_python.ontology.dialogue.session.SessionInitAction(text=None, intent_filter=[], can_be_enqueued=True, send_intent_not_recognized=False)

Bases: hermes_python.ontology.dialogue.session.SessionInit

__init__(text=None, intent_filter=[], can_be_enqueued=True, send_intent_not_recognized=False)
Parameters:
  • text (Optional[Text]) – An optional text to say to the user
  • intent_filter (Optional[List[str]]) – An optional list of intent name to restrict the parsing of the user response to
  • can_be_enqueued (bool) – An optional boolean to indicate if the session can be enqueued if it can’t be started immediately (ie there is another running session on the site). The default value is true
  • send_intent_not_recognized (bool) – An optional boolean to indicate whether the dialogue manager should handle non recognized intents by itself or sent them as an IntentNotRecognizedMessage for the client to handle. This setting applies only to the next conversation turn. The default value is false (and the dialogue manager will handle non recognized intents by itself)
class hermes_python.ontology.dialogue.session.SessionInitNotification(text='')

Bases: hermes_python.ontology.dialogue.session.SessionInit

__init__(text='')

The session doesn’t expect a response from the user. If the session cannot be started, it will enqueued.

Parameters:text (Text) –
class hermes_python.ontology.dialogue.session.SessionInit

Intent

class hermes_python.ontology.dialogue.intent.IntentMessage(session_id, custom_data, site_id, input, intent, slots, alternatives, asr_tokens, asr_confidence)
__init__(session_id, custom_data, site_id, input, intent, slots, alternatives, asr_tokens, asr_confidence)

A python representation of the intent parsed by the NLU engine.

Parameters:
  • session_id (Text) – Identifier of the dialogue session during which this intent was parsed.
  • custom_data (Text) – Custom data passed by the Dialogue Manager in the current dialogue session.
  • site_id (Text) – Site where the user interaction took place.
  • input (Text) – The user input that has generated this intent.
  • intent (IntentClassifierResult) – Structured description of the intent classification.
  • slots (SlotMap) – Structured description of the detected slots for this intent if any.
  • alternatives (List[NluIntentAlternative]) – A list of alternatives intent resolutions
  • asr_tokens (List[List[AsrToken]]) – The tokens detected by the ASR. The first list represents the different ASR invocations
  • asr_confidence (float) – Confidence of the asr capture
class hermes_python.ontology.dialogue.intent.IntentClassifierResult(intent_name, confidence_score)
__init__(intent_name, confidence_score)

Structured description of the intent classification.

Parameters:
  • intent_name (Text) – name of the intent.
  • confidence_score (float) – confidence_score that the parsed sentence is the intent_name intent.
class hermes_python.ontology.dialogue.intent.IntentNotRecognizedMessage(site_id, session_id, input, custom_data, confidence_score, alternatives)
Members:
__init__(site_id, session_id, input, custom_data, confidence_score, alternatives)

A message that the handler receives from the Dialogue manager when an intent is not recognized and that the session was initialized with the intent_not_recognized flag turned on.

Parameters:
  • site_id (Text) – Site where the user interaction is taking place.
  • session_id (Text) – Session identifier that was started.
  • input (Optional[Text]) – The user input that has generated this intent. This parameter is nullable
  • custom_data (Optional[Text]) – Custom data passed by the Dialogue Manager in the current dialogue session. This parameter is nullable
  • confidence_score (float) – Between 0 and 1
  • alternatives (List[NluIntentAlternatives]) – A list of alternatives intent resolutions
class hermes_python.ontology.nlu.NluIntentAlternative(intent_name, confidence_score, slots)
__init__(intent_name, confidence_score, slots)

Alternative resolution provided by the NLU engine

Parameters:
  • intent_name (Optional[Text]) – name of the alternative intent.
  • confidence_score (float) – confidence score of the alternative intent
  • slots (SlotMap) – slot map of the parsed slots for this alternative intent.

Slots

class hermes_python.ontology.nlu.NluSlot(slot_value, raw_value, alternatives, entity, slot_name, range_start, range_end, confidence_score)
__init__(slot_value, raw_value, alternatives, entity, slot_name, range_start, range_end, confidence_score)
Parameters:
  • slot_value (SlotValue) – Parsed value of the slot into a structure.
  • raw_value (Text) – Unparsed, raw value of the detected slot.
  • alternatives (List[SlotValue]) – Alternatives resolutions of the slot.
  • entity (Text) –
  • slot_name (Text) – name of the detected slot.
  • range_start (int) – Index in the parsed sentence, at which the slot starts
  • range_end (int) – Index in the parsed sentence, at which the slot ends.
  • confidence_score (float) – confidence level of the parsing of the detected slot.
class hermes_python.ontology.nlu.SlotMap(data)
__init__(data)

A helper class (which is a subclass of the collections.abc.Mapping class) which allows to access slots using a dot notation.

Parameters:data (Mapping[Text, SlotsList]) – A map-like that has slot-name as key, and a SlotsList as a value.
class hermes_python.ontology.nlu.SlotsList

A helper class that is a list of NluSlot. It’s a subclass of list that makes it easier to reach slot_values that are deeply nested in the IntentMessage datastructure.

all()

Returns a list of value`s field of the `slot_value field of all NluSlot occurences in the SlotsList

first()

Returns the value field of the slot_value field of the first NluSlot occurence in the SlotsList

class hermes_python.ontology.nlu.NluSlot(slot_value, raw_value, alternatives, entity, slot_name, range_start, range_end, confidence_score)

Slot Values

class hermes_python.ontology.slot.SlotValue(value_type, value)
__init__(value_type, value)

A structured representation of values a slot can take.

Parameters:
  • value_type – a constant that defines the type of the Slot Value.
  • value – The parsed value according to the value_type of the slot.
class hermes_python.ontology.slot.CustomValue(string_value)
__init__(string_value)

A structured representation of Custom Value slot type.

Parameters:string_value – a string value
class hermes_python.ontology.slot.NumberValue(value)
__init__(value)

A structured representation of Number Value slot type.

Parameters:value
class hermes_python.ontology.slot.OrdinalValue(value)
__init__(value)

A structured representation of Ordinal Value slot type.

Parameters:value – an integer value.
class hermes_python.ontology.slot.AmountOfMoneyValue(unit, value, precision)
__init__(unit, value, precision)

A structured representation of a slot type that represents an amount of money.

Parameters:
  • unit – monetary unit.
  • value – the amount of money in unit.
  • precision – numerical precision.
class hermes_python.ontology.slot.TemperatureValue(unit, value)
__init__(unit, value)

A structured representation of a slot type that represents a temperature.

Parameters:
  • unit – unit used to measure the temperature.
  • value – value expressed in unit unit.
class hermes_python.ontology.slot.InstantTimeValue(value, grain, precision)
__init__(value, grain, precision)

A structured representation of a slot type that represents a date.

Parameters:
  • value
  • grain
  • precision
class hermes_python.ontology.slot.TimeIntervalValue(from_date, to_date)
__init__(from_date, to_date)

A structured representation of a slot type that represents a time interval.

Parameters:
  • from_date – date at which starts the interval.
  • to_date – date at which the interval ends.
class hermes_python.ontology.slot.DurationValue(years, quarters, months, weeks, days, hours, minutes, seconds, precision)
__init__(years, quarters, months, weeks, days, hours, minutes, seconds, precision)

A structured representation of a slot type that represents a duration.

Parameters:
  • years – number of years the duration lasts.
  • quarters – number of quarters the duration lasts.
  • months – number of months the duration lasts.
  • weeks – number of weeks the duration lasts.
  • days – number of days the duration lasts.
  • hours – number of hours the duration lasts.
  • minutes – number of minutes the duration lasts.
  • seconds – number of seconds the duration lasts.
  • precision
class hermes_python.ontology.slot.PercentageValue(value)
__init__(value)

A structured representation of Percentage Value slot type.

Parameters:value
class hermes_python.ontology.slot.MusicArtistValue(string_value)
__init__(string_value)

A structured representation of Percentage Value slot type. A structured representation of Custom Value slot type. :param value: :param string_value: a string value

class hermes_python.ontology.slot.MusicAlbumValue(string_value)
__init__(string_value)

A structured representation of Custom Value slot type.

Parameters:string_value – a string value
class hermes_python.ontology.slot.MusicTrackValue(string_value)
__init__(string_value)

A structured representation of Custom Value slot type.

Parameters:string_value – a string value
class hermes_python.ontology.slot.CityValue(string_value)
__init__(string_value)

A structured representation of City Value slot type.

Parameters:string_value – a string value
class hermes_python.ontology.slot.CountryValue(string_value)
__init__(string_value)

A structured representation of Country Value slot type.

Parameters:string_value – a string value
class hermes_python.ontology.slot.RegionValue(string_value)
__init__(string_value)

A structured representation of Region Value slot type.

Parameters:string_value – a string value

Injection

class hermes_python.ontology.injection.InjectionRequestMessage(operations, lexicon={}, cross_language=None, id=None)
__init__(operations, lexicon={}, cross_language=None, id=None)
Parameters:
  • operations (List[InjectionRequestOperation]) – List of operations to execute in the order of the list on a model
  • lexicon (Mapping[Text, List[Text]]) – List of pre-computed prononciations to add in a model
  • cross_language (Optional[Text]) – Language for cross-language G2P
  • id (Optional[Text]) – The id of the InjectionRequestMessage that was processed
class hermes_python.ontology.injection.InjectionCompleteMessage(request_id)
__init__(request_id)
Parameters:request_id (Text) – The id of the injection request that just completed.
class hermes_python.ontology.injection.InjectionResetRequestMessage(request_id)
__init__(request_id)
Parameters:request_id (Text) – The id of the injection reset request.
class hermes_python.ontology.injection.InjectionResetCompleteMessage(request_id)
__init__(request_id)
Parameters:request_id (Text) – The id of the injection reset request that just completed.
class hermes_python.ontology.injection.InjectionRequestOperation(values)
__init__(values)

Initialize self. See help(type(self)) for accurate signature.

class hermes_python.ontology.injection.AddInjectionRequest(values)

Bases: hermes_python.ontology.injection.InjectionRequestOperation

__init__(values)

Initialize self. See help(type(self)) for accurate signature.

class hermes_python.ontology.injection.AddFromVanillaInjectionRequest(values)

Bases: hermes_python.ontology.injection.InjectionRequestOperation

__init__(values)

Initialize self. See help(type(self)) for accurate signature.