Adapt Intents
Adapt is a keyword based intent parser. It determines user intent based on a list of keywords or entities contained within a users utterance.
Vocab files define keywords that Adapt will look for in a Users utterance to determine their intent.
These files can be located in either the
vocab/lang-code/ or locale/lang-code/ directories of a Skill. They can have one or more lines to list synonyms or terms that have the same meaning in the context of this Skill. Mycroft will match any of these keywords with the Intent.Consider a simple
Potato.voc. Within this file we might include:potato
potatoes
spud
If the User speaks either:
potato
or
potatoes
or
spud
Mycroft will match this to any Adapt Intents that are using the
Potato keyword.Regular expressions (or regex) allow us to capture entities based on the structure of an utterance.
These files can be located in either the
regex/lang-code/ or locale/lang-code/ directories of a Skill. They can have one or more lines to provide different ways that an entity may be referenced. Mycroft will execute these lines in the order they appear and return the first result as an entity to the Intent Handler.Let's consider a
type.rx file to extract the type of potato we are interested in. Within this file we might include:.* about (?P<Type>.*) potatoes
.* (make|like) (?P<Type>.*) potato
What is this regex doing?
.* matches zero, one or more of any single character. (?P<Type>.*) is known as a Named Capturing Group. The variable name is defined between the , and what is captured is defined after this name. In this case we use .* to capture anything.So our first line would match an utterance such as:
Tell me about sweet potatoes
Whilst the second line will match either:
Do you like deep fried potato
or
How do I make mashed potato
From these three utterances, what will the extracted
Type be:
1. sweet
2. deep fried
3. mashedThis
Type will be available to use in your Skill's Intent Handler on the message object. We can access this using:message.data.get('Type')
Now that we have a Vocab and Regular Expression defined, let's look at how to use these in a simple Skill.
For the following example we will use the two files we outlined above:
Potato.vocType.rx
We will also add some new
.voc files:Like.voc- containing a single line "like"You.voc- containing a single line "you"I.voc- containing a single line "I"
To construct an Adapt Intent, we use the intenthandler() _decorator and pass in the Adapt IntentBuilder.
Both of these must be imported before we can use them:
from adapt.intent import IntentBuilder
from mycroft import intent_handler
The IntentBuilder is then passed the name of the Intent as a string, followed by one or more parameters that correspond with one of our
.voc or .rx files.@intent_handler(IntentBuilder('IntentName')
.require('Potato')
.require('Like')
.optionally('Type')
.one_of('You', 'I'))
In this example:
- the
PotatoandLikekeywords are required. It must be present for the intent to match. - the
Typeentity is optional. A stronger match will be made if this is found, but it is not required. - we require at least one of the
YouorIkeywords.
What are some utterances that would match this intent?
Do you like potato? Do you like fried potato? Will I like mashed potato? Do you think I would like potato?
What are some utterances that would not match the intent?
How do I make mashed potato?
The required
Like keyword is not found.Is it like a potato?
Neither the
You nor I keyword is found.Now we can create our Potato Skill:
from adapt.intent import IntentBuilder
from mycroft import intent_handler
class PotatoSkill(MycroftSkill):
@intent_handler(IntentBuilder('WhatIsPotato').require('What')
.require('Potato'))
def handle_what_is(self, message):
self.speak_dialog('potato.description')
@intent_handler(IntentBuilder('DoYouLikePotato').require('Potato')
.require('Like').optionally('Type').one_of('You', 'I'))
def handle_do_you_like(self, message):
potato_type = message.data.get('Type')
if potato_type is not None:
self.speak_dialog('like.potato.type',
{'type': potato_type})
else:
self.speak_dialog('like.potato.generic')
def create_skill():
return PotatoSkill()
You can download this entire Potato Skill from Github, or see another Adapt intent handler example in the Hello World Skill
One of the most common mistakes when getting started with Skills is that the vocab file doesn't include all of the keywords or terms that a User might use to trigger the intent. It is important to map out your Skill and test the interactions with others to see how they might ask questions differently.
- 1.Compound words like "don't", "won't", "shouldn't" etc. are normalized by Mycroft - so they become "do not", "will not", "should not". You should use the normalized words in your
.vocfiles. Similarly, definite articles like the word "the" are removed in the normalization process, so avoid using them in your.vocor.rxfiles as well. - 2.Tab != 4 Spaces, sometimes your text editor or IDE automatically replaces tabs with spaces or vice versa. This may lead to an indentation error. So make sure there's no extra tabs and that your editor doesn't replace your spaces!
- 3.Wrong order of files directories is a very common mistake. You have to make a language sub-folder inside the dialog, vocab or locale folders such as
skill-dir/locale/en-us/somefile.dialog. So make sure that your.vocfiles and.dialogfiles inside a language subfolder.
The utterance string received from the speech-to-text engine is received all lowercase. As such any string matching you are trying to do should also be converted to lowercase. For example:
@intent_handler(IntentBuilder('Example').require('Example').require('Intent'))
def handle_example(self, message):
utterance = message.data.get('utterance')
if 'Proper Noun'.lower() in utterance:
self.speak('Found it')
It's also really helpful for us if you add an issue to our documentation repo. This means we can make sure it gets covered for all developers in the future.
Last modified 2yr ago