AIML 2.0 Reference

This page documents the Pandorabots implementation of AIML 2.0. The elements on this page may be used on both the Playground and the Developer Portal server.

Elements

<aiml>

The AIML root element delimits a block of AIML code. All other elements must be descendents of the root element.

Attributes

version (optional)
Specifies the AIML version that the document is written in.

Usage

<?xml version="1.0" encoding="UTF-8"?>
<aiml version="2.0">
<!-- AIML code goes here -->
</aiml>

<bot />

The bot element is used to recall custom bot properties defined in the .properties file. These variables are accessible to all users of the bot.

Attributes

name (required)
Specifies the name of the property being recalled. If no property exists under the specified name, the bot element will return the value of the property named default-property.

Usage

<category>
  <pattern>WHAT IS YOUR NAME</pattern>
  <template>My name is <bot name="name" /></template>
</category>

<br />

Creates a line break in the response string. Identical to the HTML <br> element.

<category>

The category element delimits a base unit of knowledge in an AIML-based chatbot. In a very broad sense, a single category accepts an input, and returns an output.

All AIML elements (with the exception of the AIML root element and the topic element) must be contained within a category block.

Usage

<category>
<pattern>HI</pattern>
<template>Hello world!</template>
</category>

<condition>

The condition element is used to create an IF-THEN-ELSE type of control flow within a bot's response. This is done by checking the value of a predicate, and returning a response depending on that value.

Attributes

name (required)
Specifies the name of the predicate whose value will be checked.

Usage

The condition element is used in conjunction with list elements written with value attributes. If the value of the predicate referenced in the condition element matches that of any list element's value, that list element will be returned.

If the list element contains no value attribute, it will be returned in the case that no other list elements match the predicate's value.

<category>
<pattern>DO YOU FIND ME ATTRACTIVE</pattern>
<template>
  <condition name="gender">
    <li value="male">I find you very handsome.</li>
    <li value="female">I find you very pretty.</li>
    <li>I find you very attractive.</li>
  </condition>
</template>
</category>

In this example, the bot will check the value of a predicate named gender. In the case that the predicate's value is either "male" or "female", one of the first two list elements will be returned. If neither of these conditions is met, then the third list element will be returned.

<date />

Returns the date of the user's locale.

Attributes

format (optional)
Specifies the format of the returned date. This can be written like arguments to UNIX's strftime function. More on this here.

Usage

<category>
<pattern>WHAT IS THE DATE</pattern>
<template>Today is <date format="%B %d, %Y" /></template>
</category>

<denormalize>

The denormalize element attempts to match its contents against the names of properties found in denormal.substitution. If a match is found, the denormalize element and its contents will be replaced by the property's value.

The properties found in denormal.substitution are used to reverse transformations done by normal.substitution.

Usage

During input pre-processing, normal.subsitution removes punctuation. We can see this by echoing the part of the input that originally contained some puncutation:

<category>
<pattern>SAY *</pattern>
<template><star /></template>
</category>

<!--

Input: Say pandorabots.com
Output: pandorabots dot com

-->

This punctuation can be re-inserted by using the denormalize element:

<category>
<pattern>SAY *</pattern>
<template><denormalize><star /></denormalize></template>
</category>

<!--

Input: Say pandorabots.com
Output: pandorabots.com

-->

<eval>

The eval element is used to reference variables found in an outer category from within a nested category. This allows you to echo wildcard contents from an outer category from within a learn category.

Anything found within an eval element will be evaluated first, before the new category is created.

Usage

<category>
<pattern>THE * IS BLUE</pattern>
<template>
  I will remember that the <star /> is blue.
  <learn>
    <category>
    <pattern>WHAT COLOR IS THE <eval><star /></eval></pattern>
    <template>The <eval><star /></eval> is blue</template>
    </category>
  </learn>
</template>
</category>

<!--

Input: The sky is blue.
Output I will remember that the sky is blue.

Input: What color is the sky?
Output: The sky is blue.

-->

<explode>

The explode element is used to break a single word in to multiple words, by inserting spaces in between each character.

Usage

<category>
<pattern>EXPLODE *</pattern>
<template><explode><star /></explode></template>
</category>

<!--

Input: Explode coffee
Output: c o f f e e

-->

<first>

The first element returns the first word found in its contents. This is an implementation of list processing in AIML.

Usage

<category>
<pattern>FIRST *</pattern>
<template><first><star /></first></template>
</category>

<!--

Input: First a b c d
Output: a

-->

<formal>

The formal element returns its contents with each word capitalized.

Usage

<category>
<pattern>FORMAL *</pattern>
<template><formal><star /></formal></template>
</category>

<!--

Input: Formal george washington
Output: George Washington

-->

<gender>

The gender element attempts to match its contents against the names of properties found in gender.substitution. If a match is found, the gender element and its contents will be replaced by the property's value.

The gender.substitution file contains properties whose names and values contain pronouns of opposite genders.

Usage

<category>  
<pattern>DOES IT BELONG TO *</pattern>  
<template>No, it belongs to <gender><star/></gender></template>  
</category>

<!--

Input: Does it belong to her?
Output: No, it belongs to him

-->

<get />

The get element is used to return the value of a particular predicate.

Attributes

name (required)
Specifies the name of the predicate to recall. If the predicate does not yet have a value, then the get element will return the default value for that predicate as specified in the .pdefaults file. If no default is specified, then the get element will return the value of the property default-get.

Usage

<category>
<pattern>WHAT IS MY NAME</pattern>
<template><get name="name" /></template>
</category>

<category>
<pattern>MY NAME IS *</pattern>
<template>Nice to meet you, <set name="name"><star /></template>
</category>

<!--

Input: What is my name?
Output: unknown

Input: My name is Daniel.
Output: Nice to meet you, Daniel.

Input: What is my name?
Output: Daniel.

-->

As seen in the above example, the first category returns the default-get property value ("unknown") in the case that no custom predicate name has been set. Once the second category has been engaged, the get element returns the custom value of the predicate.

To avoid returning the value of default-get, you can use a condition element to first check whether or not a predicate has been set. By using a wildcard as the list element's value attribute, we can check for any value of the predicate other than an empty string.

<category>
<pattern>WHAT IS MY NAME</pattern>
<template>
  <condition name="name">
    <li value="*"><get name="name" /></li>
    <li>You have not told me your name.</li>
  </condition>
</template>
</category>

<id />

The id element returns the current botid, along with the client_name of whoever has issued the input. botid is the same as app_id/botname.

<img />

The image element returns an image found at a specified URL. Identical to the HTML <img> tag.

Attributes

src (required)
Specifies the URL where the image can be found.

<input />

The input element returns the entire user's input. This is distinct from the star element, which returns only contents captured by a wildcard in the matched pattern.

Usage

<category>
<pattern>Stop repeating me</pattern>
<template><input /></template>
</category>

<!--

Input: Stop repeating me
Output: Stop repeating me

-->

<interval>

The interval element is used in conjunction with the date element to calculate the difference between two different times/dates.

Attributes

format
Specifies the format of the returned date. This can be written like arguments to UNIX's strftime function. More on this here.

Child tags

<from>
Specifies the date from which the interval should begin.

<to>
Specifies the date at which the interval should end.

<style>
Specifies the style in which the interval should be returned. Can contain years, months, days, or seconds.

Usage

To calculate the difference between the current date and the bot's birthdate, make sure to include a birthdate property in the .properties file, in a format that matches the format you intend to be working with.

<category>
<pattern>AGE IN YEARS</pattern>
<template>
  <interval format="%B %d, %Y">
    <style>years</style>
    <from><bot name="birthdate"/></from>
    <to><date format="%B %d, %Y" /></to>
  </interval>
</template>
</category>

The style element specifies that the interval should be returned in years.

<learn>

The learn element allows the user to generate new category blocks from within a conversation. This powerful introduced in AIML 2.0 allows users to actually teach the bot new information.

Categories generated by the learn element are stored in memory, and are only accessible with the client_name that was used to create them.

Usage

<category>
<pattern>I LIKE COFFEE</pattern>
<template>
  I will remember that you like coffee.
  <learn>
    <category>
    <pattern>WHAT DO I LIKE</pattern>
    <template>You like coffee.</template>
    </category>
  </learn>
</template>
</category>

<!--

Input: I like coffee.
Output: I will remember that you like coffee.

Input: What do I like?
Output: You like coffee

-->

<learnf>

The learnf element is identical to the learn element in syntax, however, the generated category is written to an .aiml file that you may specify with the property learn-filename. If the file has not yet been created, it will be created when your bot "learns" its first category.

<li>

The list item element can be a child of both <condition> and <random>. It allows you to attach mulitple responses, each of which is chosen under certain circumstances.

Attributes

value (optional)
You may specify a value when the list item element is the child of a condition element. The list item element will be returned if the value matches that of the predicate referenced in the condition element.

<loop />

The loop element is used to iterate over a set of list item elements that are contained in a condition block.

Usage

To use the loop element, you must have a list item element with a value, and a second one that has no specified value. The loop element will be a child of the second list item, signifying that each time the second item is returned by the condition block, a loop occurs.

This means that you can modify a variable (like a predicate) when the second condition is met. If the value of the new predicate matches that of the first list item, then the loop will break.

<category>
<pattern>COUNT TO <set>number</set></pattern>
<template>
  <think><set name="count">0</set></think>
  <condition name="count">
    <li><value><star/></value></li>
    <li>
      <set name="count">
        <map><name>successor</name><get name="count"/></map>
      </set>
      <loop/>
    </li>
  </condition>
</template>
</category>

<!--

Input: Count to 6
Output: 1 2 3 4 5 6

-->

This example takes advantage of the built in set number, which verifies am input word as a number, and the built in map successor, which maps integers to their successive integers.

Before the condition block, the count predicate is initialized with the value 0. If the user input was Count to 0, then the first list item will be returned (echoing the number found in the input).

Otherwise, the second item will be returned, and the count predicate is reset as the successive integer to the one found in the input. The loop element will run the condition again, and will continue to return the second list item until the predicate count matches the value of <star />.

<lowercase>

The lowercase element transforms all letters in its contents to lowercase.

<map>

The map element is used to reference a .map file, which attempts to match the map element's contents to one of its own properties, returning the property's value. Maps are data structures that provide key-value pairs.

Attributes

name (required)
Specifies the name of the .map file to match contents against.

Usage

This example uses state2capital.map and state.set, both from the Rosie chatbot repository.

<category>
<pattern>WHAT IS THE CAPITAL OF <set>state</set></pattern>
<template>
  <map name="state2capital"><star /></map> is the capital of <star />
</template>
</category>

<!--

Input: What is the capital of California?
Output: Sacramento is the capital of California

-->

This category shows how maps and sets can be used in conjunction with each other to create "facts" in your bot's knowledge base. The state.set file is called in the pattern to verify that the user's input actually contained a state. If the wildcard contents does exist in the set file, it is then passed in as an input to state2capital.map. If it matches any of the keys in the map file, then the map element will return as associated value.

<normalize>

<oob>

The out-of-band element serves as a delimiter for a portion of the bot's response that will communicate something beyond the conversation. While the out-of-band element serves no purpose to your bot internally, it can be used by the bot to "control" an application. By running the bot's response through an XML parser, you can separate the bot's text response from its out-of-band contents.

Usage

Imagine you have built a mobile application that integrates a chatbot into some of your phone's native features. One feature your application offers is the ability to place a call to someone in your contact list simply by telling the chatbot to call that person.

<category>
<pattern>CALL *</pattern>
<template>
  Calling <star />.
  <oob><call><star /></call></oob>
</template>
</category>

<!--

Input: Call Mom.
Output: Calling Mom. <oob><call>Mom</call></oob>

-->

Notice that the out-of-band element remains intact even after it has been sent back to the client. To truly integrate out-of-band elements into an application, the application must parse the bot's response as XML to delimit its constituent parts. You can then return the contents of the out-of-band element to an event handler in your application, and the remainder to display to your user.

<pattern>

The pattern element is the block within each category that defines a linguistic pattern against which the user's input can be matched. The pattern may contain letters, numbers, spaces, and a number of other symbols including wildcards. For more detailed information on patterns, see the section labeled Pattern-side reference.

Usage

<category>
<pattern>HI</pattern>
<template>Hello there.</template>
</category>

<person>

The person element attempts to match its contents against the person.substitutions file, which transforms pronouns between first and second person. If the contents forms a match with the name of a property in that file, then the person element and its contents will be replaced by the property's value.

Usage

<category>
<pattern>I AM *</pattern>  
<template>You are <person><star/></person></template>  
</category>

<!--

Input: I am waiting for you
Output: You are waiting for me

-->

In the above example, the phrase "waiting for you" is echoed in the template using <star />. But because the tag descends from the person element, the pronoun "you" is transformed to "me".

<person2>

The person2 element is identical to the person element, however, it is used to transform pronouns between first and third person.

Usage

<category>  
<pattern>GIVE THE * TO *</pattern>  
<template>User has asked me to give the <star/> to <person2><star index="2"/></person2></template>  
</category>

<!--

Input: Give the password to me
Output: User has asked me to give the password to them

-->

<program>

The program element returns the name and version number of the AIML interpreter being used.

Usage

Using this element on the Playground:

<category>
<pattern>PROGRAM</pattern>
<template><program /></template>
</category>

<!--

Input: Program
Output: Pandorabots AIML Interpreter 2.0

-->

<random>

The random element can be used in conjunction with list item elements to provide a set of potential bot responses, one of which will be returned at random in the case that the category is matched.

This is a very useful tag to use in default categories, or categories that you think will be matched very often, because it can provide your bot with a less repetitive personality.

Usage

<category>
<pattern>HI</pattern>
<template>
  <random>
    <li>Hello!</li>
    <li>Well hello there.</li>
    <li>Howdy.</li>
    <li>Good day.</li>
    <li>Hi, friend.</li>
  </random>
</template>
</category>

If the user's input is "HI", then one of the list item elements will be returned to the user at random.

<request />

The request element returns the user's input specified by its historical index value.

Attributes index Specifies the historical index of the user's input to recall. index="0" refers to the current input.

Usage

<category>
<pattern>WHAT DID I JUST SAY</pattern>
<template><request index="1" /></template>
</category>

<!--

Input: Hi
Output: Hi there!

Input: What did I just say?
Output: Hi

-->

<response />

The response element returns the bot's response specified by its historical index value.

Attributes index Specifies the historical index of the bot response to recall. index="0" refers to the current response.

Usage

<category>
<pattern>WHAT DID YOU JUST SAY</pattern>
<template><request index="1" /></template>
</category>

<!--

Input: Hi
Output: Hi there!

Input: What did you just say?
Output: Hi there!

-->

<rest>

The rest element is a list processing tag that returns the contents of the element while omitting the first word.

Usage

<category>
<pattern>REST *</pattern>
<template><rest><star /></rest></template>
</category>

<!--

Input: Rest A B C D
Output: B C D

-->

<sentence>

The sentence element capitalizes the first word of its contents, as if the contents were the beginning of a sentence.

<set>

The set element is used to set a predicate variable. Predicates are not hardcoded like properties, and can be initialized during conversation. This means that input from the user can be echoed in the value of a predicate.

Attributes name (required) The name attribute specifies a name for the predicate you will set. The predicate can then be recalled under the same name using the get element.

Usage

<category>
<pattern>MY NAME IS *</pattern>
<template>
  Nice to meet you, <set name="username"><star />.</set>
</template>
</category>

<category>
<pattern>WHAT IS MY NAME</pattern>
<template>Your name is <get name="username" />.</template>
</category>

<!--

Input: My name is Daniel.
Output: Nice to meet you, Daniel.

Input: What is my name?
Output: Your name is Daniel.

-->

<size />

The size element returns the number of category blocks contained in the current bot.

<sr />

The sr element is shorthand for <srai><star /></srai>. Because this is one of the most often-used combinations of elements, AIML allows you to write as a shortened version.

<srai>

The srai element allows your bot to recursively call categories after transforming the user's input. The acronym "srai" has no official meaning, but is sometimes defined as symbolic reduction or symbolic recursion.

Usage

The most typical use case of the srai element is to "reduce" an input by removing unecessary words, or by translating the input in to a shorter, more concise version.

<category>
<pattern>HELLO GOOD DAY</pattern>
<template><srai>HI</template>
</category>

<category>
<pattern>BONJOUR</pattern>
<template><srai>HI</template>
</category>

<category>
<pattern>GUTEN TAG</pattern>
<template><srai>HI</srai></template>
</category>

<category>
<pattern>HI</pattern>
<template>Hello there!</template>
</category>

In the case that the user's input is "Hello good day," "Bonjour," or "Guten Tag," the first three categories will recurse, and give the bot a new input "HI". This will then match the fourth category, returning its response to the user.

<sraix >

The sraix element allows a bot to call categories that exist within another bot, and return response as if it was its own. This allows the creation of many bots, each with a specific purpose, that may connect with each other to form a sort of "neural network" of AIML categories.

Attributes bot (required) Specifies the bot to call out to, defined by the botid. On the Pandorabots Playground, the botid is equivalent to username/botname. On the Developer Portal, it is defined as app_id/botname.

<star />

The star element is used to echo portions of the user's input that were captured by wildcards.

Attributes index Specifies which wildcard to echo (used when multiple wildcard are present). If no index is specified, defaults to 0.

Usage

<category>
<pattern>MY FAVORITE * IS *</pattern>
<template>Your favorite <star /> is <star index="2" /></template>
</category>

<!--

Input: My favorite color is blue
Output: Your favorite color is blue

-->

<template>

The template element is the portion of category that defines its return value. It can contain a variety of other elements: some which return text directly to the user, and some which cause recursion and trigger new categories. Every category must contain a template block.

Usage

<category>
<pattern>HI</pattern>
<template>Hello there!</template>
</category>

<that>

The that element is an optional child of the category element that is used to establish the context of the pattern. If a category contains a that element, the pattern can only be matched if the last sentence of the bot's previous response matches the contents of that. In a sense, the that element binds a pattern to the immediate context of the conversation.

This is very useful for contextualizing common, simple user inputs such as "yes" or "no."

The that element follows all the rules of the pattern element: it may not contain punctuation, it may use wildcard symbols, and should be written in all caps.

Usage

<category>
<pattern>I LIKE COFFEE</pattern>
<template>Do you take cream or sugar in your coffee?</template>
</category>

<category>
<pattern>YES</pattern>
<that>DO YOU TAKE CREAM OR SUGAR IN YOUR COFFEE</that>
<template>I do too.</template>
</category>

<category>
<pattern>NO</pattern>
<that>DO YOU TAKE CREAM OR SUGAR IN YOUR COFFEE</that>
<template>Really? I have a hard time drinking black coffee.</template>
</category>

In this example, we have accounted a possible conversation timeline, where the user initiates the conversation, and the bot responds by asking the user a yes or no question. The problem, however, is that there area near infinite number of questions the user may answer with "yes" or "no", so how does the bot know the context of the user's answer? Because the second and third categories contain that blocks, they are both bound to a particular context. These categories will not be matched unless the bot's previous response matches "DO YOU TAKE CREAM OR SUGAR IN YOUR COFFEE".

<thatstar />

The thatstar element is used to echo wildcard contents found inside of <that> tags.

Attributes index Specifies the index of the wildcard to echo. If no index is specified, defaults to 0.

Usage

<category>
<pattern>I LIKE IT TOO</pattern>
<that>I LIKE *</that>
<template>What do you like best about <thatstar /></template>
</category>

<!--

Input: ...
Output: I like coffee.

Input: I like it too.
Output: What do you like best about coffee?

-->

This type of category is useful for dealing with pronoun resolution (anaphora). If the user inputs the word "it", you can implement a that element and a thatstar element to keep a reference to the original noun in question.

<think>

The think element allows your bot to set predicates without actually displaying the contents of a set element to the user. This is sometimes referred to as "silently" setting a predicate.

Usage

Consider this example, which sets a predicate, but does so in a way that the contents of the set element is actually returned to the user as part of the template:

<category>
<pattern>MY NAME IS *</pattern>
<template>
  Nice to meet you, <set name="name"><star /></set>
</template>
</category>

<!--

Input: My name is Daniel
Output: Nice to meet you, Daniel

-->

You can use the think tag to set the name predicate, without actually repeating the value of the predicate to the user:

<category>
<pattern>MY NAME IS *</pattern>
<template>
  <think><set name="name"><star /></set></think>
  I will remember your name.
</template>
</category>

<!--

Input: My name is Daniel
Output: I will remember your name

-->

<topic>

The topic element allows your to contextualize categories according to the value of a predicate named is "topic". Like the that element, topic binds a pattern to a particular context, however, it does this according to the persistance of a predicate rather than the previous bot response.

The topic element is unique to most AIML elements in that it appears outside of category blocks. You can wrap a number of categories within a topic element to bind all of those categories.

It should also be noted that the predicate name "topic" is reserved for this purpose.

Attributes name (required) Refers to a possible value of the topic predicate.

Usage

<category>
<pattern>LET US TALK ABOUT *</pattern>
<template>
  OK, I like <set name="topic"><star /></set>
</template>
</category>

<topic name="coffee">

<category>
<pattern>I DRINK IT PLAIN</pattern>
<template>I prefer mine with cream and sugar</template>
</category>

</topic>

<topic name="tea">

<category>
<pattern>I DRINK IT PLAIN</pattern>
<template>I prefer mine with honey and lemon</template>
</category>

</topic>

<!--

Input: Let us talk about coffee
Output: OK, I like coffee

Input: I drink it plain
Output: I prefer mine with cream and sugar

Input: Let us talk about tea
Output: OK, I like tea

Input: I drink it plain
Output: I prefer mine with honey and lemon

-->

This rudimentary example shows how setting the topic can also assist in contextualizing an input. If the user says something like "I drink it plain," the bot must have some way of knowing what "it" refers to in order to provide a relevent answer. This is illustrated in the above example via the different things one might add to coffee or tea. Depending on the value of the topic predicate, the bot will know which set of beverage additions to respond with.

<topicstar />

<uppercase>

The uppercase element transforms all letters in its contents to uppercase.