Training Abot
Abot's training interface offers a powerful way to teach Abots without needing to recompile, even in production. The training interface enables you to define "intents" of sentences. While you should always prefer setting triggers of Commands and Objects for higher accuracy when building your plugins, training can help Abot learn new concepts and grow over time. It's therefore best as a secondary tool when Abot's out-of-the-box support for Commands and Objects falls a little short.
The training interface communicates with an external service defaulting to itsabot.org, but that domain may be changed by setting the ITSABOT_URL environment variable. By offloading training to a separate service, the changes are propagated to every Abot when it boots up. For example, in a clustered deployment of your Abot across multiple machines, each Abot will sync from a central source of truth. In that way, this architecture is similar to Docker with Docker Hub.
Since itsabot.org hosts your training data, you'll need to first publish your plugin. To do that, run this command:
$ abot plugin publish github.com/your_username/your_plugin_name
To be published, your plugin will have to successfully compile and have a valid plugin.json. After you run the publish command, sign in on itsabot.org and ensure the plugin's available on your profile. If so, you'll see a green OK! under the Errors column.
With the plugin published, you should see this in your Abot admin panel:
The yellow message warns you that while you can access the training data, you'll need to authenticate your Abot with itsabot.org in order to make any changes, like adding new training sentences, modifying intents, or deleting sentences. To authenticate your Abot with itsabot.org, we use auth tokens.
You can generate an auth token at https://www.itsabot.org/profile:
Generate an auth token, and copy it into your Abot under Account Connect:
Then if you return to the training interface, you'll be able to add new sentences and intents.
This approach allows you to issue revocable training access for your plugins to multiple Abots. Anyone with admin access to those Abots will be able to train your plugin, so take care to keep auth tokens safe. It's best to create one auth token per Abot, so you can revoke each Abot individually at a later time.
On the training page, click + Train sentence. That brings up a form like this:
Enter a few sentences and an associated intent to train Abot. You may want to namespace your intent to something only you would use, preventing other plugins from mistakenly using the same intent.
Training Tips and Tricks
- You'll probably need at least 3 similar training sentences for Abot to understand each concept you intend to teach it, but sometimes more, especially if sentences for multiple intents involve similar words/structure.
- Try to train each intent with an equal or close-to-equal number of example sentences. For example, if you have five training sentences for get_weather, you should try to have five sentences for get_raining.
- Name your intents something that no other developer would likely use, otherwise two plugins might duplicate the same intent, and Abot won't know where to route the request. Try namespacing them under your initials or company name.
- Your training data will not affect any other installed plugins. Each plugin trains its own, independent classifier.
When you've trained several sentences, you'll be looking at something like this:
Be sure to restart your Abot whenever you change training data, as Abot loads training data and trains its classifiers on boot. Now when you send Abot a sentence similar to those on which you've trained Abot, like "what's it like outside?", Abot correctly classifies the sentence as having the get_weather intent. We'll demonstrate this with ABOT_DEBUG=true, so we can see the intent that Abot assigns the sentence and how strongly Abot believes it to be "get_weather".
But since we've trained Abot on only one type of intent, it'll classify everything as get_weather. It's up to us to teach it additional intents, so that it understands that every sentence it sees doesn't necessarily have a "get_weather" intent.
After doing that, we'll need to add support to our plugin to listen for these newly trained intents. In your plugin, you can modify any StructuredInput trigger to include Intents: []string{"your_intent"}. Here you can see I've added intents for get_weather and get_raining to my keyword handlers.
After you modify your plugin, be sure to re-run abot plugin install and abot server.
That's it! We've just trained Abot about the intent behind multiple sentences and programmed our plugin to listen for those intents.