Projects

A project contains the entire neural network (in binary form) together with a bunch of configuration files in a directory. This directory is accompanied by the main project file. Both have the same name.  When moving around a project, make certain you have both file and directory. When opening and saving projects, you only need to worry about the file, the directory will be created/managed automatically (done in such a way that extra directories like for version control systems, will remain functioning).
The project files themselves (extension ‘.dpl’), are simple xml files which contain various configuration data for the designer. In general though, you don’t need to edit this file manually, all settings can be managed from within the designer.
The most important files in the project directory are binary and should never be manually edited. Some files are xml based, but apart from the test-cases, should be left ‘as-is’ since they contain vital configurations for the internal network.

Topic files

Topics form a major component of a chatbot designer project. They define what the bot can do. Internally, topics are stored as neurons, but in order to share a topic across multiple projects and users, Topic files were introduced. This is an xml file (extension ‘topic.xml’) that contains all the rules defined in the project.

The designer provides functionality to import and export topics one by one or in bulk from the File menu or the context menu on the Project tool-window. So ideally, you should never be confronted with the internals of these files. For the die-hard text-editor fans, here’s a little more details on the structure:

A minimal topic file should contain a topic, name, rules and questions sections. Like:

<Topic>
  <Name>Who has</Name>
  <Rules />
  <Questions />
</Topic>

And a bit more challenging, containing a single rule with 1 input and output pattern pattern:

<Topic>
  <Name>Time</Name>
  <Rules>
    <Rule>
      <Name>new rule 1</Name>
      <Patterns>
        <Pattern>
          <Expression>What time is it [?]</Expression>
        </Pattern>
      </Patterns>
      <Conditionals />
      <Outputs>
        <Output>
          <Expression>It is $time:hour\:$time:minute\.</Expression>
          <QuestionCanFollow>True</QuestionCanFollow>
        </Output>
      </Outputs>
      <IsOutputSequenced />
      <DoPatterns />
      <Calculate />
  </Rules>
  <Questions />
</Topic>

For the curious, the expression: $time:hour\:$time:minute\.  is used to render something like 17:30. The expression has to be split up in 4 parts:

time:hour	returns the hour
\:	we need to escape the : cause it is just after a variable path. If we don’t do this, the parser thinks that we will specify another function call.
time:minute	returns the minute part of the time value.
\.	The . also needs to be escaped, otherwise the parser thinks we are trying to further specify the path.

Global patterns

In the ‘chatbot properties’ view (From the menu: View/chatbot properties), you can specify a bunch of global patterns like the opening statements, fallback values, ‘do-patterns’ that need to be executed at startup, just after each statement,…  This also includes all the OS function-mappings that were declared in the ‘OS channel’.  All these can be exported/imported using 1 file, with the extension ‘global.xml’. Import/export can be done from the menu: ‘file/import/global patterns’ or ‘file/export/global patterns’. 

As you probably already guessed, this is also in xml format, but like with the topics, the content can be fully managed from within the designer, so there is no need to edit it manually.

Thesaurus files

Thesaurus files are used to share, exchange or replace part of, or the entire thesaurus that is used in a single project (thesauri are project specific and not shared across different projects within the designer). It’s the same routine again as for the previous file types: the extension is ‘thesaurus.xml’, yes, it’s an xml file format and can be fully managed from within the designer. In fact, for the thesaurus, it is more than advised to use the designer and not edit it manually since a thesaurus node can be hard to define as there are multiple levels at which words are stored. The only scenario where you might have to do some manual editing, is when you create a new thesaurus, completely from scratch when all the functionality needs to be preserved and you don’t have access to a network-designer version of the chatbot designer. In that case, the ‘bindings’ section on certain words (numbers, pronouns like I, me, myself,.. needs to be done manually. Here’s a small example of a binding for the object ‘myself’:

  <Object Name="myself">
    <Text Value="myself" Index="0" POSGRP="false" />
    <Bindings>
      <ref>I</ref>
      <ref>Singular</ref>
    </Bindings>
  </Object>

Importing/exporting is done from the context menu on the thesaurus. If no node is selected, the entire thesaurus will be exported, or the content of the imported file will be added to the root. If a node is selected during an import operation, all items will be added as a child of the selected node. For export, only the selected item and all it’s children will be exported recursively.

It’s also possible to import or export just a single level of children of a selected node, in the form of comma-separated-value (csv) files.  For imports, you don’t even need to get the data from a file, but you can just as easily use the clipboard: just copy a csv list to the clipboard, go to the context menu of the parent node and select ‘Import\wordlist from clipboard’. This feature allows you to quickly build up trees of related words.

Asset files

Assets store concrete information like ‘you are reading this now’ and ‘I have written this text’. By now, the theme should have become clear to you: asset files are stored in the xml format, they have the extension ‘asset.xml’. But here’s where we stray a little from the path: currently asset import/export is only supported in the pro version (that is, it’s still a little bit under construction, so it will soon be available). The same for editing: the pro will have an asset editor, but not the basic version. The latter only has the chatbot window for adding input statements.

Test cases

Test case files aren’t independent files like ‘topic thesaurus, asset or global patterns’ files, but are rather part of the project directory. As such, you can’t currently export or import them automatically from within the designer (though you can fully manage them as in copy, delete, edit,.. from within the designer). That said, they do deserve a special mention since it could sometimes be useful to extract some test-cases and copy them to other projects. And, because a test-case file is actually a stand-alone xml file, this is certainly possible.

Test case files are located at {project directory}\DesignerData\  and have the extension ‘TESTCASE’. If you copy a test-case from one project to another, or you want to delete some manually, make certain that the project is closed.

CCS files (characters)

As a final file format, I’d like to talk a little about characters and their files. A character is stored as an xml file (extension ccs) together with a bunch of images. These images can be located in a subdirectory of the ccs file, as long as the path can be described, relative to the ccs file.

For the chatbot designer to be able to use a character, the files (and possibly directory structure) of the char need to be copied to the directory: {My documents}\NND\Characters\CharName,  where ‘Charname’ is the name of the character. Best to do this when the chatbot designer isn’t running.

Unfortunately, ccs files can’t yet be edited in the designer (or any other UI tool). They need to be created manually. Luckily, the structure is relatively simple and allows for lots of copy/paste. More info on the file structure will come shortly.

Note: Deprecated!

The next screen cast is ready. It demonstrates some of the features found in the ‘asset’ editor.

For instance, the abstract can be ‘a house’ while the concrete is ‘The house that I live in,… my house. Aici needs a way to distinguish the 2 and be able to find relationships between both. This is done through the use of different data structures.

Objects

Lets start with the objects, these are the simplest. They represent abstract knowledge. Every interpretation of every word is represented by an object. For instance, ‘house’ can mean the house that you live in, but could also refer to a musical style. So there is an object for each interpretations of the word. Furthermore some words can have synonyms, words that have the same meaning. For instance, ‘house’ and ‘home’ could be considered as synonyms, or house and ‘house music’. With ‘house music’ being a compound word: 2 words joined together to form a new meaning. Other examples of compound words are: car factory, fire hose, film studio,…

Another bit of information that can be useful to know about a word, is how it should be interpreted in the context of a sentence: can it be a noun, verb, adjective,…. Sometimes, a word can have multiple interpretations, while being used as the same sentence type (like house), sometimes multiple sentence types are allowed for a single meaning (colors for instance can be used as adjectives or nouns: ‘my eyes are blue’, ‘that blue is pretty’ ). As a speed optimization, we group all the objects together that have the same part of speech, but with different meanings in ‘Pos-groups’, though this is not required.

As a visual example, let’s take the objects ‘hello’ and ‘goodbye’ (as in a greeting). Both are nouns (it’s an hello and a goodbye). Both have multiple synonyms: hi, howdy, bye,..  So here’s how this would look like:

Relationships between objects: the Thesaurus

Objects are stored in a thesaurus like structure to indicate relationships between them. For instance, both ‘aici’ and ‘jan’ are names, so  this could be expressed in a thesaurus relationship like in the 2 images below:

Notice (to the left) that the ‘noun’ filter was selected in the thesaurus together with the ‘is a’ relationship. To the right, you can see how this is represented internally: Name points to an ‘is a’ cluster, which contains all the related objects. So the ‘Noun filter works by only displaying objects that point to ‘noun’ or are clustered by a ‘noun’ pos-group while the ‘is a’ relationship will filter out all but the clusters attached to the roots using this ‘is a’ neuron.

Sometimes a root object doesn’t have any children (as in cluster-children, not in the thesaurus). This makes the object a dummy, a placeholder that shouldn’t be used for input or output directly, but only for filtering. Some examples of these dummies can be seen when the ‘pronouns’ are selected.

The thesaurus relationships can be used in frames to filter the input in a general way and to perform lookups by the actions. For instance, the ‘be name’ frame (in the ‘names’ editor) has an ‘object flow’ element that filters on ‘name’ through the ‘is a’ relationship, as seen in the image below.

This means that the frame is only selected when the input contains the result of an object flow that is the child of an ‘is a’ cluster, attached to ‘name’ or one of it’s thesaurus children (so multiple levels are allowed).

To create this type of filter by the way, you simply drag ‘name’ from the thesaurus to the filter area.

Actions also make use of these thesaurus relationships in a very similar way. For instance, an action could check if an object  is allowed to/can be the name of something (‘my name is Jan’). Or, in sentences like: ‘this is blue’, the thesaurus is used to find out what ‘blue’ actually is: a color (I’m jumping here, keep with me, It will become clear very soon).

An object can also be the child of multiple items in a thesaurus. For instance, ‘blue’ is both the child of ‘colorful’ and ‘sad’ (child of ‘emotional’). Note that these are all adjectives, hence we say ‘colorful’ instead of ‘color’. To find out which relationship to take, we can make use of a log of previously made statements or a list of focused objects. The most important usage of either color(ful) or emotion(al) in this log, triggers it for the new input. Most important can be interpreted very broadly: it could be ‘newest log item’, or ‘most talked about’,… If it is impossible to solve this, a question needs to be asked.

Anyway, once you have figured out which path to take in the thesaurus: colorful, we still have an adjective. If the same logical concept/idea can be expressed in multiple parts of speech, using different words (like color-colorful) and you want to be able to jump between the 2, you need to have a relationship between them. As I already stated, we interpret ‘blue’ as a ‘color’, not ‘colorful’. Why, will become more clear when we talk about the assets, for now lets just take it that we need to change from adjective or verb to noun. As you can see in the image, the thesaurus has a special section to define this type of relationship: the left part of the table contains the link meaning, the right section is the ‘from’ part of the link.

The same can be done for verb conjugations. In English, a verb usually has 3 different conjugational forms, other languages have others, so the thesaurus allows you to define this type of relationship free form, much like the part of speech relationships. When you create a new verb though, the designer will try to fill in all the conjugations (if it finds neurons titled ‘present particle’, ‘past particle’ and ‘third person present’. It’s always best to check them before storing the default though, since it doesn’t know about irregular verbs and sometimes it/I may simply goof up.

The verb conjugations, compared to the part-of-speech relationships, are used a bit differently. These serve their purpose while parsing the input and generating output. Some flow elements try to search for conjugation relationships while filtering (in the ‘FilterCode’ tab) in order to get the correct parse. For instance, in the ‘model verbs flow’, this is used to make certain that a verb is the present particle. The same goes for generating output: when a verb is used in certain situations (ex: ‘what’ contains a verb instead of a noun), we need to generate it’s present particle form (or another, depending on the exact situation).

Assets

Up until now, all relationships were between objects, so between abstract knowledge only. To record a network’s experiences (the data that it records), we use assets and asset relationships.

At it’s core, an asset is a cluster with meaning ‘asset’ (we’re very original here), which contains a number of child neurons that represent property-value pairs for that asset. This is done through links to objects and/or other assets, using the meanings: attribute, value, amount,… From this basic structure, we can start to play and create meaningful relationships.

As usual, a picture says a thousand words, so to the left, I’ve displayed a debug view of the ‘text channel’ neuron (the text input channel of AICI). Why this neuron? If you look closely, it has a link that points to an ‘asset’ cluster, using the meaning ‘Pr:You’. So with this image, I’ve got 2 birds with 1 stone: the asset and how to find the asset that AICI is using for the person on the other side of the channel .

A text channel stores a reference to the asset that represents the entity it is communicating with using a link with meaning ‘Pr:you.

As a side note, linking ‘you’ to the text channel, allows the system to talk to multiple users at the same time: each on their own channel.

So what’s stored in this asset anyway? As you can see, there are 2 child neurons in the asset, so 2 data items: the first has an attribute (property) of ‘entity’ and a (property) value of ‘animate entity’. The second asset-child  points to ‘eye’ for the attribute, the value is another asset and it has a general amount of ‘plural’.

Note that the attribute should always be a noun. Having a fixed transformation point facilitates the search.  Why a noun: well, all adjectives and action-verbs can be converted to a noun, but not the other way round. This conversion can be done using the part of speech relationships that were previously described.

The ‘entity’ property is how AICI tries to classify assets: is it an object, animate, animal, human,… If you look at the thesaurus (in the designer), ‘entity’ is a noun-root and the asset-child’s value is one of it’s children. This is a rule: when the value is an object, it must have a thesaurus relationship with the attribute. This type of child asset represents the ‘x is an y’ type of relationship. Here, it is ‘I am an animate entity’, an other example could be:  ‘I am a human’, which would/should map to the same asset-child.

- An asset-child with an object as value represents an ‘x is an y’ sentence structure.
- In this case, the value must have a thesaurus relationship with the attribute. This relationship can span multiple levels.

AICI at the moment,  presumes that an ‘entity’ that is able to communicate through a text channel, must be animate (mammal, AI,…). So, even if this information is not yet provided, it is presumed to be the case. This is done cause the property and value play a role in other parts of the network.

The second asset-child has another asset as value. This type of relationships represents the ‘x has an y’ sentence structure. More specifically, in this example we said: ‘I have blue eyes’. This also explains the undefined ‘plural’ amount: eyes is plural and was converted into a single value, but since we don’t know exactly how many, we keep a ref to the multiple. The sub asset also has it’s own child-asset, which defines the ‘color-blue’ part of the example sentence. Through this nesting, it is possible to describe complex entities that consist out of multiple parts of knowledge.

An asset-child that references another asset as value, represents an ‘x has an y’ sentence structure.

Objects referencing assets

Assets aren’t exactly islands, independent of everything else. No, they too are referenced in many different ways. We already saw 2: assets attached to child-assets, and to the text-channels.  There’s one more reference worth mentioning at this moment: objects that reference assets. Yes, assets don’t just reference objects, it can also go the other way round. This is used to represent general knowledge about general things, like: ‘a human has hands’, as depicted in the image to the right. The same thing is also valid for statements like ‘an x is a y’: they are represented as assets, linked from objects.

Note: I did a bit of recycling with regards to the meaning of the link from the object: it also uses ‘asset’, which is the same as the meaning for the cluster.

An object that references an asset cluster, using ‘asset’ as meaning for the link, is used to represent statements of the form: ‘an x is/has a y’

The important difference between stand alone assets and assets that are linked to objects, are the information that they represent about the agent of a sentence: stand alone assets represent concrete agents: I, you, the book,… while object referenced assets represent abstract agents: a book, a human,…

These 2 data structures: objects and assets, are simple, but, I believe, flexible enough to represent a whole world of information. It is not as much the the querying and reshaping of the data as it will, in the end, be the automatic creation of these structures which I believe will ultimately be the truly interesting thing. With a query, we can retrieve data, reshaping it allows us to find truths, fallacies and falsities in the data, but a correct automatic creation of a new, complex asset, is in fact, a new entity.

In the end, all is just structure.