mycroft package

MycroftSkill class

class mycroft.MycroftSkill(name=None, emitter=None)[source]

Abstract base class which provides common behaviour and parameters to all Skills implementation.

add_event(name, handler, need_self=False)[source]

Create event handler for executing intent

Parameters:
  • name – IntentParser name
  • handler – method to call
  • need_self – optional parameter, when called from a decorated intent handler the function will need the self variable passed as well.
bind(emitter)[source]

Register emitter with skill.

cancel_scheduled_event(name)[source]

Cancel a pending event. The event will no longer be scheduled to be executed

Parameters:name (str) – Name of event
converse(utterances, lang='en-us')[source]

Handle conversation. This method can be used to override the normal intent handler after the skill has been invoked once.

To enable this override thise converse method and return True to indicate that the utterance has been handled.

Parameters:
  • utterances (list) – The utterances from the user
  • lang – language the utterance is in

Returns: True if an utterance was handled, otherwise False

disable_intent(intent_name)[source]

Disable a registered intent

enable_intent(intent_name)[source]

Reenable a registered intent

get_intro_message()[source]

Get a message to speak on first load of the skill. Useful for post-install setup instructions.

Returns:message that will be spoken to the user
Return type:str
get_response(dialog='', data=None, announcement='', validator=None, on_fail=None, num_retries=-1)[source]

Prompt user and wait for response

The given dialog or announcement will be spoken, the immediately listen and return user response. The response can optionally be validated.

Example

color = self.get_response(‘ask.favorite.color’)

Parameters:
  • dialog (str) – Announcement dialog to read to the user
  • data (dict) – Data used to render the dialog
  • announcement (str) – Literal string (overrides dialog)
  • validator (any) –

    Function with following signature def validator(utterance):

    return utterance != “red”
  • on_fail (any) –
    Dialog or function returning literal string
    to speak on invalid input. For example:
    def on_fail(utterance):
    return “nobody likes the color red, pick another”
  • num_retries (int) – Times to ask user for input, -1 for infinite NOTE: User can not respond and timeout or say “cancel” to stop
Returns:

User’s reply or None if timed out or canceled

Return type:

str

get_scheduled_event_status(name)[source]

Get scheduled event data and return the amount of time left

Parameters:name (str) – Name of event
Returns:the time left in seconds
Return type:int
initialize()[source]

Invoked after the skill is fully constructed and registered with the system. Use to perform any final setup needed for the skill.

location

Get the JSON data struction holding location information.

location_pretty

Get a more ‘human’ version of the location as a string.

location_timezone

Get the timezone code, such as ‘America/Los_Angeles’

make_active()[source]

Bump skill to active_skill list in intent_service this enables converse method to be called even without skill being used in last 5 minutes

register_entity_file(entity_file)[source]

Register an Entity file with the intent service. And Entity file lists the exact values that an entity can hold. For example:

=== ask.day.intent === Is it {weekday}?

=== weekday.entity === Monday Tuesday …

Parameters:entity_file – name of file that contains examples of an entity. Must end with .entity
register_intent(intent_parser, handler, need_self=False)[source]

Register an Intent with the intent service.

Parameters:
  • intent_parser – Intent or IntentBuilder object to parse utterance for the handler.
  • handler – function to register with intent
  • need_self – optional parameter, when called from a decorated intent handler the function will need the self variable passed as well.
register_intent_file(intent_file, handler, need_self=False)[source]

Register an Intent file with the intent service. For example:

=== food.order.intent === Order some {food}. Order some {food} from {place}. I’m hungry. Grab some {food} from {place}.

Optionally, you can also use <register_entity_file> to specify some examples of {food} and {place}

In addition, instead of writing out multiple variations of the same sentence you can write:

=== food.order.intent === (Order | Grab) some {food} (from {place} | ). I’m hungry.

Parameters:
  • intent_file – name of file that contains example queries that should activate the intent
  • handler – function to register with intent
  • need_self – use for decorator. See <register_intent>
register_vocabulary(entity, entity_type)[source]

Register a word to an keyword

Parameters:
  • entity – word to register
  • entity_type – Intent handler entity to tie the word to
remove_context(context)[source]

remove_context removes a keyword from from the context manager.

remove_event(name)[source]

Removes an event from emitter and events list

Parameters:name – Name of Intent or Scheduler Event
report_metric(name, data)[source]

Report a skill metric to the Mycroft servers

Parameters:
  • name (str) – Name of metric. Must use only letters and hyphens
  • data (dict) – JSON dictionary to report. Must be valid JSON
schedule_event(handler, when, data=None, name=None)[source]

Schedule a single event.

Parameters:
  • handler – method to be called
  • when (datetime) – when the handler should be called
  • data (dict, optional) – data to send when the handler is called
  • name (str, optional) – friendly name parameter
schedule_repeating_event(handler, when, frequency, data=None, name=None)[source]

Schedule a repeating event.

Parameters:
  • handler – method to be called
  • when (datetime) – time for calling the handler
  • frequency (float/int) – time in seconds between calls
  • data (dict, optional) – data to send along to the handler
  • name (str, optional) – friendly name parameter
send_email(title, body)[source]

Send an email to the registered user’s email

Parameters:
  • title (str) – Title of email
  • body (str) – HTML body of email. This supports simple HTML like bold and italics
set_context(context, word='')[source]

Add context to intent service

Parameters:
  • context – Keyword
  • word – word connected to keyword
settings

Load settings if not already loaded.

shutdown()[source]

This method is intended to be called during the skill process termination. The skill implementation must shutdown all processes and operations in execution.

speak(utterance, expect_response=False)[source]

Speak a sentence.

Parameters:
  • utterance (str) – sentence mycroft should speak
  • expect_response (bool) – set to True if Mycroft should listen for a response immediately after speaking the utterance.
speak_dialog(key, data=None, expect_response=False)[source]

Speak a random sentence from a dialog file.

Args

key (str): dialog file key (filename without extension) data (dict): information used to populate sentence expect_response (bool): set to True if Mycroft should listen

for a response immediately after speaking the utterance.
translate(text, data=None)[source]

Load a translatable single string resource

The string is loaded from a file in the skill’s dialog subdirectory
‘dialog/<lang>/<text>.dialog’

The string is randomly chosen from the file and rendered, replacing mustache placeholders with values found in the data dictionary.

Parameters:
  • text (str) – The base filename (no extension needed)
  • data (dict, optional) – a JSON dictionary
Returns:

A randomly chosen string from the file

Return type:

str

translate_list(list_name, data=None)[source]

Load a list of translatable string resources

The strings are loaded from a list file in the skill’s dialog subdirectory.

‘dialog/<lang>/<list_name>.list’

The strings are loaded and rendered, replacing mustache placeholders with values found in the data dictionary.

Parameters:
  • list_name (str) – The base filename (no extension needed)
  • data (dict, optional) – a JSON dictionary
Returns:

The loaded list of strings with items in consistent

positions regardless of the language.

Return type:

list of str

translate_namedvalues(name, delim=None)[source]

Load translation dict containing names and values.

This loads a simple CSV from the ‘dialog’ folders. The name is the first list item, the value is the second. Lines prefixed with # or // get ignored

Parameters:
  • name (str) – name of the .value file, no extension needed
  • delim (char) – delimiter character used, default is ‘,’
Returns:

name and value dictionary, or [] if load fails

Return type:

dict

translate_template(template_name, data=None)[source]

Load a translatable template

The strings are loaded from a template file in the skill’s dialog subdirectory.

‘dialog/<lang>/<template_name>.template’

The strings are loaded and rendered, replacing mustache placeholders with values found in the data dictionary.

Parameters:
  • template_name (str) – The base filename (no extension needed)
  • data (dict, optional) – a JSON dictionary
Returns:

The loaded template file

Return type:

list of str

update_scheduled_event(name, data=None)[source]

Change data of event.

Parameters:name (str) – Name of event

FallbackSkill class

class mycroft.FallbackSkill(name=None, emitter=None)[source]

Bases: mycroft.skills.core.MycroftSkill

FallbackSkill is used to declare a fallback to be called when no skill is matching an intent. The fallbackSkill implements a number of fallback handlers to be called in an order determined by their priority.

classmethod make_intent_failure_handler(ws)[source]

Goes through all fallback handlers until one returns True

register_fallback(handler, priority)[source]

register a fallback with the list of fallback handlers and with the list of handlers registered by this instance

classmethod remove_fallback(handler_to_del)[source]

Remove a fallback handler

Parameters:handler_to_del – reference to handler
remove_instance_handlers()[source]

Remove all fallback handlers registered by the fallback skill.

shutdown()[source]

Remove all registered handlers and perform skill shutdown.

Api class

class mycroft.Api(path)[source]

Generic object to wrap web APIs

intent_handler decorator

mycroft.intent_handler(intent_parser)[source]

Decorator for adding a method as an intent handler.

intent_file_handler decorator

mycroft.intent_file_handler(intent_file)[source]

Decorator for adding a method as an intent file handler.

adds_context decorator

mycroft.adds_context(context, words='')[source]

Adds context to context manager.

removes_context decorator

mycroft.removes_context(context)[source]

Removes context from the context manager.