ChatterBean: Flexible Alicebot

Table of Contents

Latest News

2006.05.07 Version 00.008 is now available. This version implements the following new features:

Special thanks to Andreas Matthias, Charles Chevallier and Lindsay Steele to their suggestions and reports, and my appologies if I forgot to mention anyone else.

2005.11.07 Version 00.007 is now available. This version implements the transformational elements, making it the first ChatterBean release to support the full set of AIML 1.0.1 tags. A lot of work is yet to be done before the project reaches standard compliance (for one thing, correct whitespace handling is yet to be implemented), let alone fulfill its stated objectives. Still, an important milestone has been reached.

As you probably guessed, another change in this release is a new version number system. From now on, every release will have a series number and a version number. Version numbers are assigned sequentially within a series, while series numbers follow this convention:

Whether the series number will keep advancing after ChatterBean upgrades to production status is not yet decided.

2005.07.17 - Version 0.7.5 Alpha is now available. This version implements the atomic template elements <input>, <thatstar> and <topicstar>; the conditional elements <random> and <condition>; the capture element <gossip>; and the covert element <learn>. This leaves only the transformational elements to implement before ChatterBean supports the full set of AIML 1.0.1 tags. Also, a new approach to filling the contents of matched wildcards has been implemented, which greatly improves the quality and stability of the wildcard matching mechanism.

2005.05.17 - Version 0.7.0 Alpha is now available. This version implements many new tags, including the long-awaited <topic> tag; this makes 07.0 Alpha the first version of ChatterBean to implement the complete match path. For a complete list of implemented tags, together with important notes, see the section on Supported AIML Tags. Also, a customized XML file (context.xml) has been created to store both predicate defaults and bot predicate values.

2005.05.09 - Version 0.6.5 Alpha is now available. Changes in this version include:

For more details, read the new section on Developer-Friendly Features.

Another change, probably more appealing for AIML end-users, is that from now on ChatterBean will be distributed in two versions: source-code and binary. The later takes the form of a jar file that can be executed from the command-line, opening a very simple graphical user interface. See the section on Download, Building and Usage Information for more details.

2005.04.03 - Version 0.5.0 Alpha is now available. This release gets much closer, feature and architecture-wise, to my vision of a developer-friendly AIML engine. Changes include:

By the way, I have decided to leave the "bug" mentioned in the last release -- by which punctuations don't appear in the contents of <star> tags -- unchanged, since there are situations where you don't want the punctuation to be present.

2005.03.25 - Version 0.1.3 Alpha is now available. Along with several bugfixes and some improvements, this release brings a new, platform-independent set of scripts for building, testing and running the application (see the list below for more details). Besides, I have changed the application's name from ProgramJ to ChatterBean, in order to avoid confusion with J-Alice, another AIML engine project.

Change Log

2005.02.07 - Version 0.1.2 Alpha is now available. This release provides several bugfixes, a new, constant-time implementation for the Responder interface (the HashMaster class) and a new way for passing startup-time configuration parameters, using property files, instead of the old configuration.txt unformatted text format. It still implements a very restricted subset of AIML, and is not as well documented as it should; but at least the architecture got to a point where major changes are unlikely (although the API interface may still change some).


ChatterBean is an AIML interpreter (also known as "Alicebot") written in pure Java. Its ultimate objectives are:

ChatterBean is free software, licensed under the GPL. All the usual claims about help wanted and no guarantees apply.

Development Plan: Path to 1.0

The following list underlines the tasks that must be completed in order for ChatterBean to reach version 1.0. They are organised in order of priority, which gives a general idea of what will be done first, although some intermingling can occur (for example, some refactoring is very likely to be done before all the AIML tags are implemented).

Developer-Friendly Features

One of the main directives of the ChatterBean project is that the implementation must be easy to customize or assimilate by other systems. This section lists the currently available features that have been developed for this purpose.

Automated Tests

ChatterBean's test engine can be a great help for developers wanting to experiment with the implementation: if anything is to unexpectedly break after a modification, either the unit tests or the acceptance tests will probably spot it. They also serve as examples of use for the classes of the API, illustrating common scenarios.

The black-box ("acceptance") tests are implemented as a BeanShell script that drives ChatterBean's console interface, feeding it with a pre-determined set of requests, recording the responses and comparing them with the expected ones. Should any output differ from what is expected, the expected and actual responses are printed, together with the line of the expected response in the responses file. For example:

      $ java -jar bsh.jar acceptance.bsh
      Testing ChatterBean
      Line 6:
        expected: Yes, I am an AliceBot.
        actual:   Yes, I am an ALICE Bot.

If no differences are found, the script simply prints "0k".

      $ java -jar bsh.jar acceptance.bsh
      Testing ChatterBean

The white-box ("unit") tests are implemented with the help of the jUnit unit testing framework. Tests are collected into test classes, which follow a naming convention: FooTest is the name of the test class which contains the tests for the Foo class. Occasionally, there will also be a FooMother class, which is responsible for creating instances of the framework class for the respective test class. Test classes and mother classes are always located in the same package of their respective framework class.

Not all framework classes have test classes: some of them are too simple to warrant tests, or are better tested through their wrappers.

Encapsulation and Easy Instantiation

ChatterBean's framework is conveniently encapsulated within the ChatterBean class. Creating a fully configured AliceBot can be as easy as instantiating a class:

      AliceBot bot = new ChatterBean("relative_path_to/configuration_properties.xml");
      String response = bot.respond("Good night, Alice.");

Plug-in Architecture

Because ChatterBean is constituted of many small classes exchanging messages among each other, it is easy to tap into the flow of execution and customize its behaviour, by writing specialized classes and connecting them in place. For example, imagine you want your Alicebot to fetch and persist predicates in a data base. This could be easily accomplished by writing a specialized Context class:

      This is not intended as a proper example of JDBC use; this class is only
      meant to illustrate the possibilities of customization provided by the
      ChatterBean framework.
      public class DBContext extends Context
        private Connection con = DriverManager.getConnection("jdbc:odbc:con", "user", "pass");
        public Object property(String name)
          Statement stmt = con.createStatement();
          ResultSet rs = stmt.executeQuery("SELECT VALUE FROM PROPERTIES WHERE NAME = '" + predicate + "'");
          return rs.getString("VALUE");
        public void property(String name, Object value)
          Statement stmt = con.createStatement();
          stmt.executeUpdate("UPDATE PROPERTIES SET VALUE = '" + value + " WHERE NAME = '" + name + "'");

Now you can connect an instance of this class to your AliceBot:

      AliceBot bot = new ChatterBean("relative_path_to/configuration_properties.xml");
      bot.setContext(new DBContext());

Alternatively, you can create an instance of the ChatterBeanParser class, configure it to use your context class, and then use it to create a new AliceBot:

      ChatterBeanParser parser = new ChatterBeanParser();
      AliceBot bot = parser.parse("relative_path_to/configuration_properties.xml");

Reflexive AIML Parsing Framework

In the ChatterBean framework, the result of parsing an AIML file is an object tree, with objects representing each parsed tag and its contents. The classes used to build that tree are located inside the bitoflife.chatterbean.aiml package; every time ChatterBean's AIML parser reads a tag, it uses reflection to create an instance of a class with the same name of the tag, feed it with attributes and, perhaps, add children objects to it. For example, every time the parser reads a <category> tag, it creates an instance of the bitoflife.chatterbean.aiml.Category class. The parser code simply assumes that, for every tag it reads, there will be a class with the same name inside the bitoflife.chatterbean.aiml package; there is no program code telling it what tags are valid or not.

This design makes it possible to easily add new tags to the known set, simply by writing new classes into the bitoflife.chatterbean.aiml package. Valid tag classes follow these guidelines:

For examples of this protocol, read the source code of the tag classes inside the bitoflife.chatterbean.aiml package.

Supported AIML Tags

This is the list of AIML tags supported by ChatterBean at the moment of its latest release. Support for the remaining tags will be added over the next releases.

[1] Forward-compatible processing is not yet implemented, so the value of the version attribute won't make any difference to the interpreter. Hopefully this will be fixed before a new version of the AIML standard comes out.

[2] The format of the date is defined by the value of the dateFormat predicate, which must be a valid Java date and time pattern string. This makes it possible to change the date format at runtime (after the bot learns the country the user lives in, for example).

[3] If the output bot predicate contains a file path, the current implementation of this tag writes the results of processing its contents to that file; if the bot predicate contains a directory path, the results will be written into a file named gossip-<value of the <id> tag>.txt, which will be created if it doesn't already exist.

[4] The current implementation of this tag returns the value of the id bot predicate, if it is defined; otherwise, it will return the value of the Context object's hash code.

[5] As implemented, this tag executes code in the context of the window Javascript object of an underlying browser. This limit valid invokations to standard environment features (such as the alert() function) and top-level user-defined functions, but it is well enough to add a nice AJAX-like responsiveness to web bots.

[6] As implemented by ChatterBean, this tag passes the result of processing its contents to a BeanShell script interpreter, and returns the contents of the result enviroment variable (or the value of the last expression, if it evaluates to something and result was not set). Not only this implementation makes the tag more portable, it gives the botmaster access to a powerful Java scripting environment.

Third-Party Includes

The ChatterBean distribution package includes the following third-party, GPL software as a convenience to its users. Independent release copies, together with source code files, can be found at their respective project home pages:

Download, Building and Usage Information

ChatterBean is currently distributed in two versions: binary and source. The former is more convenient for end-users who just want to play with an AIML chatterbot on their local machines, while the later is aimed at developers who want to study and play with the implementation.

ChatterBean is a Java 5 application, so you'll need release 1.5.0 or later of either the Java Run-Time Environment (if you just intend to run the binary version) or the Java Development Kit (if you want to build it from source). For details, go to Sun's Java Homepage.

Binary Version

If all you want is to run an AIML chatterbot on your local machine, you can download ChatterBean's binary-only version. Unpack the ZIP file to a convenient directory, open a command-line prompt and type:

java -cp bsh.jar -jar chatterbean.bin.00.008.jar path_to/properties.xml

Where path_to/properties.xml is the path to the configuration file of the bot you intend to run. If you need an example, look in the Sample Alicebots section.

Source Version

If you are a developer interested in studying an AIML interpreter or embedding AIML features into your application, then you can download ChatterBean's source version. Create a new directory to host the application, then download and unpack the distribution package into it. The base directory contains some BeanShell scripts that automate the most common tasks related to ChatterBean; you can run these scripts with the help of the bsh.jar executable JAR file. Opening a command prompt inside the program's installation directory, you can type:

The purpose of bsh.jar is allowing users to run ChatterBean's distribution scripts regardless the OS they use. If you have any problems with it, please contact me.

Sample Alicebots

Licensing Information

Copyleft © 2005-2006 Hélio Perroni Filho
ICQ: 2490863

ChatterBean is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

ChatterBean is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with ChatterBean (look at the Programj/Alpha/Documents/ directory of the program archive); if not, either write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA, or visit (


AIML was developed by Dr. Richard S. Wallace and the A.L.I.C.E. Foundation. For more information on AIML, visit the A.L.I.C.E. homepage.

© 2005 Hélio Perroni Filho (
Valid XHTML 1.0!
Hosted by
GridHoster Web Hosting