Getting started: creating bots

You can create your own bots from scratch, you can build upon an already existing bot or you can compose a new one from exported sections of other bots (like a collage). A bot usually consists of the following parts or sections:

Quick start

First though, in case you simply want to load a bot and get on with it, try this:

• Load a thesaurus: open the thesaurus tab, right click in the middle of the thesaurus, select ‘import/thesaurus’ and go to ‘{My documents}/NND/Thesauri’ and select one of the files (preferably small.thesaurus.xml).
• Import the project properties: from the menu: ‘file\import\project properties’ and go to ‘{My documents/NND/Topics}’ and select ‘globals.globals.xml’.
• Import some topics: from the menu: ‘file\import\topics’ and go to ‘{My documents/NND/Topics}’ select all the topics listed in the directory. If you only select some, keep in mind that some topics rely on others. Those with general names like ‘Subject, Object, DateTime,..’ (and there ‘simple’ versions as well) should always be loaded. Alternatively, you can select an AIML set to import in the same way (be certain the select ‘*.AIML ‘ in the file filter).

And that’s it. Save the project, make certain that the chatbot window is open (from the menu: ‘file/view/communication channels/chatbot’) and you are ready to chat. For a more detailed explanation:

Chatbot module

The first thing you’ll need to have is a module that implements the chatbot itself. At the time of writing, the default project template (which gets loaded whenever you start a new project) already contains a chatbot module. So, if you aren’t interested in creating your own engines, you can safely skip the next part and directly go the the project’s  properties section. But you are free to implement your own engine or change the already existing one to your own specifications. The module that the default project template uses is also included with the installer and can be found under ‘{My documents/NND/Modules}. To install a module, you can use the menu ‘file/import/module’ and select the ‘.nnm’ file’.  Alternately, you can import it  from the module manager, which is also opened from the file menu.

If you decide to use your own engine, you’ll need to make certain the designer knows which module provides the support for the  binding paths. That is, whenever you use a thesaurus, asset, topic or other path (see later) in an output pattern or code section, the system needs to know how to interpret these paths (this is not hardcoded, but can be defined by the user). At the time of writing, this has been implemented in the chatbot module. So if you create your own engine, be certain to either include the source files that define those bindings, define them yourself or keep the original chatbot module also loaded in the project. In the module manager, every module is a radio button, which allows you to select the module that provides binding support. If there is no module selected, the topics editor will rumble a lot whenever it needs to use one of the bindings, so be certain to select a valid one.

The project’s properties

In the project’s properties, you can provide values for the global settings, specific to the current project. This includes some preferences like your and the bot’s name, birthday, gender and module specific settings. The project’s properties page can be opened from the menu (view/project properties) or from the toolbar on the project tool-page (first button).

The module specific properties currently include the following items:

• Auto resolve synonyms. When switched on, the system will find all the available synonyms for every word in the input and try to search a match for every possible input combination. This setting is useful when you don’t want to rely on thesaurus paths. Switching on this setting can slow down the system, but can be helpful to improve matching capabilities of simple pattern definitions.
• The ‘end of sentence signs’ is a list of all the indexed strings that the system recognizes as sentence terminators. When any of these strings is found in the input and the system has found a complete pattern, but there is still input data left, it will try to match a next sentence. These strings will also terminate any variable collection. It is however still perfectly legal to use these strings in your pattern definitions, they will be matched like any other text.
• ‘Rely on the weight provided by the STT engine’ determines how STT input should be handled. Most sound-to-text engines have the ability to provide multiple possible results, each with a weight. The default chatbot module can take these weights and use them to further determine the most appropriate input. This property is only useful when using voice input, otherwise it has no effect.
• ‘Single top pattern’ determines if the engine stops matching after it found a first pattern that isn’t a sub-pattern (and there is no sentence end) or if it continues and tries to find a next pattern if there was still input left. By default, this is turned off, since the sentence endings already make certain that there are multiple patterns found when required. Sometimes however, the input doesn’t have any sentence signs. In which case this switch can be useful. Keep in mind though that when this property is turned on, the pattern matcher will most likely have to verify a lot more possible matches and things can slow down considerably.
• ‘Symbols to skip’ is another list with all the strings (and other neurons) that the pattern matcher should skip in the input. This contains a space, tab, enter and line feed, but also some formatting indicators like ‘FirstUpperCase’.
• A final flag is used to determine how output of multiple rules is combined. This flag only becomes useful if you use sub-topics/rules in your input patterns.

In general, there shouldn’t be much of a need to change any of these module specific settings. You should be able to leave them as they are depicted in the image to the right.

The properties page contains some other useful tabs for starting out. These include:

• Say on startup: If you like your bot to start the conversation, this is where you put all the possible output statements that can be used as openings for a conversation. The bot will pick 1 at random. When this section is empty, the bot will wait until you initiate a conversation.
• Fall back: If the bot can’t match any input-patterns against the input, it will return a default text ‘No output defined’. In this section, you can overwrite this default value with your custom output. If multiple outputs are specified, one will be picked at random.
• Repetition: In this section you can specify global conditional outputs for handling repetition in the input. A system variable ($Repeatcount) provides access to the nr of repeating patterns that the bot found.

Other sections include:

• Do on startup: this contains code that is executed when the bot is first started.
• Do after output: this section also contains code, but which is executed after every input/output pair.
• Context: The section is used for declaring asset paths to memory that can be used in operations that require context.
• Mappings: This page contains a bunch of references to neurons that the system needs to know about. In general, it’s best to leave these values as they are defined in the default template project.

All these properties and global patterns can be exported and imported to/from an xml file from the main menu (‘file/import’ and ‘file/export’).

Thesaurus data

A second piece of the puzzle consists out of the thesaurus. This is a collection of words that are grouped together in a tree-like structure. The default template and some of the demos have an empty thesaurus. This allows you to use whichever thesaurus that you like, including one for a different language (although the current version is still mostly geared for English, particularly for verb conjugations).

Luckily the installer already contains 2 thesauri: one that was imported from Wordnet (called wordnet.thesaurus.xml), which is pretty big but currently not yet properly set up to work with the topics (things like numbers and conjugations are missing). There is also a smaller, but much better organized thesaurus, called ‘small.thesaurus.xml). It contains far less words, but the basis is properly set up to do conversions from pronouns to objects or months to numbers and so on. To import a thesaurus into your projects, you should right click on the thesaurus tool-window and select import, thesaurus. The file to import is in xml format, so you can edit this manually if you want, though this is only advised for building thesauri in other languages.

Once you have a basic data set, you can extend this, either by manually entering new words or by importing more data, as other sub sections in xml format, or you can also import comma separated lists of words. Simply copy the list to the clipboard or a file, right click on the thesaurus node where the items should be added, select import). All the words in comma separated lists will become children of the selected node.

Topics

The next important part to think about are the topics. This is where you define how the bot needs to respond to different input. Like the other sections, you can import already existing topics (from the menu: file/import/topic). This includes topics that were previously exported from the designer or AIML files. Importing multiple topics at once is also supported, just select multiple files in the dialog box. Imported topics will appear in the project view. From there, you can rename, organize or delete all the topics in the project. Note that every topic should have a unique name, topics with duplicate names get a red icon (and can’t be used as sub-topics).

Creating new topics

Of course, at some point, you will want to create your own content. To start a new topic, use one of the toolbar buttons or the insert menu. This will show a new topic (a unique name will automatically be generated) with an empty ‘Input’ and ‘Output’ section.

To create a new rule, simply start typing in one of these sections. This will automatically create a new rule and input or output pattern. In the simplest form, you put the exact input text that needs to be matched on the left and the bot’s response to the right. When you are ready to move on to calculations and do-sections, you can press ctrl-D to show/hide them (or press on the drop-down buttons). Shft-Ctrl-D will hide/show them all at once.

Selecting and editing patterns

You can either select a section of text within a single pattern (just like in any other text editor) or you can select multiple patterns at once (for deleting, copying,…). If you want to select all the patterns of a single section (for instance, all the ‘input’ patterns in a rule), double-click on the word ‘Input’ (or ‘Output’, depending on the section you want). To select multiple patterns in different sections, keep the ctrl key pressed while clicking inside the patterns. Every selected pattern is displayed with a darker, heavier line. Rules can also be selected by clicking on the area around the patterns but outside of the text. Selected rules will also have a darker, heavier border. Finally, you can use the arrow keys to move around anywhere on the topic, not just within a single pattern.

Delete, cut, copy and paste are done in the usual manner: with the delete button, ctrl-x, ctrl-c, ctrl-v, you know the drill. If you have a need to insert a rule or pattern somewhere, use the ctrl+I shortcut. Depending on the cursor position, a new pattern or rule will be inserted. The ‘Search and replace’ dialog can be shown with the Ctrl+F shortcut, the button on the toolbar or the menu command (Edit/view). To activate topic-search, make certain that the topic is selected. Many tool-windows also have search-capabilities, if one of them is active while pressing the search command, the search of the local tool-frame will be used.
Finally, the topic editor has a spell checker that can be turned on/off in the options dialog (Tools/options – editing tab).

Variables, questions and answers

Even the simpler bots need a way to pass some data from the input to the output section and handle question/answer type of situations. The first can be done by using variables in the input patterns. The second rule in the example to the right (called ‘I am’) contains a variable ($value) in every pattern. As you have probably already guessed, variables start with a ‘$’. To display the value in the output, simply use the same variable name in the output pattern. Notice in the last output line that I placed a ‘\’ in between ‘$value’ and ‘.’. That’s because I wanted to show the ‘.’ on the screen and not define a binding path (more about that in other tutorials).

When the rule can be activated in response to a question that the bot just asked, like the ‘I am’ rule to the right, which can be the answer to ‘What’s your name’ (asked by the rule ‘Hello’), then you might want to respond differently compared to when it was activated without the question. In the ‘hello’ example, when the user first says ‘I am xxx’, the bot will respond with ‘Hi there xxx. What’s up’. But if the user had first said hello’, then the bot will respond with ‘What would you like to talk about xxx? This is accomplished by the extra ‘Response for’ part in the second rule. You can add ‘these parts to the output section by clicking on the ‘+’ sign that appears to the right of the ‘output’ header when you hover the mouse over it. When you click on the + sign, a drop down box appears where you can select the output pattern for which this rule can be an answer for. The dropdown box has several sections, so you can select outputs on the current topic or from other topics. It’s also possible to add multiple outputs to a single ‘Response for’ by clicking on the ‘+’ sign that appears after the ‘Response for’ header. With the red ‘x’ you can remove references to an output pattern. When you remove the last one, the entire part will disappear.

Note: if you don’t get a drop down-box after pressing the ‘+’ sign, but another text box instead, then you are in AIML-mode, which will be explained in a later topic. To switch between AIML and NND mode for the ‘Responses for’ section, press the button on the topic editor’s local toolbar. Be careful though not to mix different styles in the same responses-for list.

When an output contains a question, and you want to say something specific in case that the user didn’t respond to it (because none of the rules where activated that have been designed as possible responses), then you have to add 1 or more outputs to the ‘When not replied’ section which can be activated by clicking on the first blue ‘V’ after the output pattern (it becomes visible when you hoover above the pattern or when it is selected). The ‘When not replied’ part is most likely not used often, unless you plan to build an SS-style interrogation bot or just a really annoying personality.

There are other ways that question-answers can be done (like the AIML approach), but that’s outside the scope of this tutorial.

Creating characters

If you feel like creating your own characters, this is certainly possible. The current system uses a set of images that are bundled together with an xml file. The images can easily be generated with tools like DAZ3D, Poser,… Basically, you need an image for each animation frame and mouth position. Some packages will allow you to semi-automate this export process. Here’s a small tool to automatically compress the images to only the difference. This way, you can use multiple animations at once.

At the time of writing, the xml files still need to be edited manually. The structure is an extension of the CSS file format. Basically, it consists out of the following sections:

• CharacterInfo: information about the character
• Animations: a list of available animations and all the frames for each animation
• VisemeGroups: defines which image goes with which letters.
• IdleLevels: declares which animations should be played during idle time and how.
• BackgroundAnimations: optionally animations that should always play in some sort of loop (useful for things like breathing)
• Backgrounds: optionally a set of images that compose the background image. When multiple images are used, parts of the background can be hidden during animations.

To install your newly created character, create a new directory in {my documents}\nnd\characters. Give the directory the same name as your character and put the xml file in the directory. The exact location of the images is specified in the xml file, but usually you put these together in the same dir or sub.

For more information on creating your own characters, check out the tutorial on creating your own characters.