Expando is a translation language for easily defining user utterance examples when building conversational interfaces for Natural Language Understanding services like API.AI, LUIS, or the Alexa Skills Kit. This is roughly analagous to the concept of building grammars for speech recognition systems.
What's all this, then?
The following line of Expando:
(is it possible to|can I|how do I) return (something|an item)
...would be expanded by producing the Cartesian product of the phrases in parentheses that are separated by pipes:
is it possible to return something is it possible to return an item can I return something can I return an item how do I return something how do I return an item
This encoding makes it much easier to manage multiple user utterance examples when building conversational interfaces.
Using Expando, you can:
- House your intents and entities in version control, simplifying collaboration.
- Use the CLI to automatically update your intents and entities (only supports API.AI, at the moment).
- Make use of the expansion syntax to dramatically simplify the encoding of utterance examples.
This reference implementation of the Expando language is built with Ruby, and packaged as a gem. You can install it with:
$ gem install expando
The Expando CLI features an
init command for initializing new Expando projects:
$ mkdir support-bot $ cd support-bot $ expando init ✓ intents directory created ✓ entities directory created ✓ .expando.rc.yaml file created ✓ circle.yaml file created
This will create
entities directories, for housing the utterance examples themselves, as well as some configuration files.
Configure API.AI integration
If you'll be using Expando to update the intents and entities of an existing API.AI agent, you'll need to copy the client access token and developer access token for the agent to
# API.AI credentials - add the credentials for your agent below :client_access_token: REPLACE_WITH_TOKEN :developer_access_token: REPLACE_WITH_TOKEN
Set up continuous integration
circle.yaml file can be used to configure CircleCI to enable automatically updating an API.AI agent when commits are pushed to your Expando project's repo.
Create intent and entity files
Let's assume we have an agent on API.AI named
support-bot. If we want to use the Expando syntax for one of this agent's intents named
openHours, we'd create a file in the
intents directory named
It's also possible to create expandable entity examples in the same manner. A file named
entities/products.txt would match to a
products entity on API.AI.
Currently, Expando supports phrase combinations, and optional phrases.
Using the above example, we could include the following line of Expando in the file
(when|what times) are you open
This would be expanded by creating a version of this utterance with each of the phrases enclosed by paretheses and separated by pipes:
when are you open what times are you open
If multiple sets of phrases are included on the same line, a Cartesian product of each of the phrases will be created. The following line of Expando:
(when|what times) are (you|y'all|you guys) open
...would result in this full list of utterances:
when are you open when are y'all open when are you guys open what times are you open what times are y'all open what times are you guys open
By making the final phrase in a set blank, you can make it optional. The following Expando:
what are your (open|) hours
...would result in:
what are your open hours what are your hours
It's also possible to make an entire set of phrases optional:
what are your (open|business|) hours
what are your open hours what are your business hours what are your hours
Essentially, you're making the last phrase in the set an empty string.
In order to update intents or entities on API.AI, use the following commands:
$ expando update intents $ expando update entities
It's also possible to target specific entities or intents for updating:
$ expando update intents openHours
You can also access full help for the Expando CLI:
$ expando --help
..and also help for specific Expando CLI commands:
$ expando update --help