Padatious Intents
Last updated
Last updated
Padatious is a machine-learning, neural-network based intent parser. Unlike Adapt, which uses small groups of unique words, Padatious is trained on the sentence as a whole.
Padatious has a number of key benefits over other intent parsing technologies.
With Padatious, Intents are easy to create
The machine learning model in Padatious requires a relatively small amount of data
Machine learning models need to be trained. The model used by Padatious is quick and easy to train.
Intents run independently of each other. This allows quickly installing new skills without retraining all other skill intents.
With Padatious, you can easily extract entities and then use these in Skills. For example, "Find the nearest gas station" -> { "place":"gas station"}
Padatious uses a series of example sentences to train a machine learning model to identify an intent.
The examples are stored in a Skill's vocab/lang or local/lang directory, in files ending in the file extension .intent. For example, if you were to create a tomato Skill to respond to questions about a tomato, you would create the file
vocab/en-us/what.is.a.tomato.intent
This file would contain examples of questions asking what a tomato is.
These sample phrases do not require punctuation like a question mark. We can also leave out contractions such as "what's", as this will be automatically expanded to "what is" by Mycroft before the utterance is parsed.
Each file should contain at least 4 examples for good modeling.
The above example allows us to map many phrases to a single intent, however often we need to extract specific data from an utterance. This might be a date, location, category, or some other entity.
Let's now find out Mycroft's opinion on different types of tomatoes. To do this we will create a new intent file: vocab/en-us/do.you.like.intent
with examples of questions about mycroft's opinion about tomatoes:
Note the {type} in the above examples. These are wild-cards where matching content is forwarded to the skill's intent handler.
In the above example, {type} will match anything. While this makes the intent flexible, it will also match if we say something like Do you like eating tomatoes?. It would think the type of tomato is "eating" which doesn't make much sense. Instead, we can specify what type of things the {type} of tomato should be. We do this by defining the type entity file here:
vocab/en-us/type.entity
which might contain something like:
This must be registered in the Skill before use - most commonly in the initialize() method:
Now, we can say things like "do you like greenish tomatoes?" and it will tag type as: "greenish". However if we say "do you like eating tomatoes?" - the phrase will not match as "eating" is not included in our type.entity file.
Let's say you are writing an Intent to call a phone number. You can make it only match specific formats of numbers by writing out possible arrangements using # where a number would go. For example, with the following intent:
the number.entity could be written as:
Let's say you wanted to create an intent to match places:
This alone will work, but it will still get a high confidence with a phrase like "How do I get to the boss in my game?". We can try creating a .entity file with things like:
The problem is, now anything that is not specifically a mix of New York City, San Francisco, or something on Georgia Street won't match. Instead, we can specify an unknown word with :0. This would would be written as:
Now, while this will still match quite a lot, it will match things like "Directions to Baldwin City" more than "How do I get to the boss in my game?"
NOTE: Currently, the number of :0 words is not fully taken into consideration so the above might match quite liberally, but this will change in the future.
Sometimes you might find yourself writing a lot of variations of the same thing. For example, to write a skill that orders food, you might write the following intent:
Rather than writing out all combinations of possibilities, you can embed them into one or more lines by writing each possible option inside parentheses with | in between each part. For example, that same intent above could be written as:
or even on a single-line:
Nested parentheses are supported to create even more complex combinations, such as the following:
Which would expand to:
There is no performance benefit to using parentheses expansion. When used appropriately, this syntax can be much clearer to read. However more complex structures should be broken down into multiple lines to aid readability and reduce false utterances being included in the model. Overuse can even result in the model training timing out, rendering the Skill unusable.
The intent_handler() decorator can be used to create a Padatious intent handler by passing in the filename of the .intent file as a string.
You may also see the @intent_file_handler decorator used in Skills. This has been deprecated and you can now replace any instance of this with the simpler @intent_handler decorator.
From our first example above, we created a file vocab/en-us/what.is.a.tomato.intent. To register an intent using this file we can use:
This decorator must be imported before it is used:
Now we can create our Tomato Skill:
See a Padatious intent handler example in the Hello World Skill
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:
If something isn't working as expected, please join us in the ~Skills channel of Mycroft Chat.
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.