Getting Started with Program W
From sourceforge.net
author: A.Caronia(1,2), G.Pilato(1), A.Augello(2), S.Gaglio (1,2)
(1)ICAR- Italian National Research Council, Palermo, Italy, {g.pilato}@icar.cnr.it
(2)DINFO - University of Palermo,Palermo, Italy, {alessandrocaronia} @ inwind .it, {augello}@csai.unipa.it, {gaglio}@unipa.it
Contents |
Preparation
Download Program W
Download the latest Program W distribution. Grab the package that best fits your needs.
Program W offers several choices for how it interacts with users. Depending upon your needs, you may or may not need to download additional software. Here's a quick guide:
| If you want to... | Then you need... |
| Just talk to the bot yourself via a command-line style interface |
|
| Let users talk to the bot via instant messaging programs or IRC |
|
| Experiment with changes to the Program W source code |
|
Get the Java Runtime (or SDK)
You need to download and install a Java 2 version 1.5 compatible JVM. Examples are the Sun JRE (Java Runtime Edition) or SDK (Software Development Kit). The JRE is much smaller than the SDK (~16MB as compared with ~44!!!). You only need the SDK if you want to rebuild the program, or want to develop Java programs of your own. You can download the necessary software and find installation instructions at http://java.sun.com/j2se/1.5.0/download.jsp.
If you want to recompile the program, build the documentation, or rebuild a .war file, you will also need Ant.
Get Some AIML
The Program W download includes a test suite for verifying AIML compatibility, which is enough to check that your installation is working, but doesn't provide for much of a conversation. You can find several choices of freely-available AIML on this site. Pick one and download it.
Get the WordNet
You need to download and install a WordNet by Princeton University. You can download the necessary software and find installation instructions at on this site. Pick one and download it.
Installation
Java
We won't cover installation instructions for the JRE/Java SDK here.
We'll just assume that you've followed the instructions. In the
following, we'll refer to the directory where you installed Java as JAVA_HOME. (If you use Windows, this might be something like C:\jdk1.5.0_06. If you're using Linux, this might be /usr/java/jdk1.5.0_06.)
You should at least be able to type "java -version" at a command line (syntax may vary) and get a response something like:
java version "1.5.0_06" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05) Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode, sharing)
If you get some kind of error like "command not found", check that your system path settings are correct. Or, just try "JAVA_HOME/java -version" (Linux) or "JAVA_HOME\java.exe -version" (Windows), substituting your actual JAVA_HOME path.
WordNet
We won't cover installation instructions for the WordNet by Princeton University here. We'll just assume that you've followed the instructions.
(Windows) When I run the installer for WordNet, I get the installation program for another, unrelated program This is a problem with InstallShield, we think. For now, the workaround is to move the installer (WordNet-2.1.exe) into an empty folder and try again.Program W
If you're upgrading from a previous version, please check the release notes, since some configuration files may have changed.
Unzip/untar the Program W download in a convenient location. On Linux, we suggest /usr/local/ProgramW; on Windows, the root directory (C:\, perhaps) is as good as anything. The unzipping/untarring process will create a directory called ProgramW that will contain all the program files.
Linux users may type:
tar xvjf programw-0.7a-bin.tar.bz2
Windows 95-2000 users could try a free unzip utility such as 7-Zip. Windows XP users will find that XP is able to open the zip file and guide you through extracting it using a "wizard".
We'll refer to the root directory created by the unzip/untar (such as /usr/alice/ProgramW) as ProgramW.
Compile (source downloads only)
If you downloaded the binary version of Program W (programw-0.7a-bin.tar.bz2 or programw-0.7a-bin.zip), you can skip this step and go on to verify installation.
If you downloaded the source version of Program W (programw-0.7a-src.tar.bz2 or programw-0.7a-src.zip), you will need to compile the code before you can run it. As mentioned above, you will need to have installed Ant in order to compile the code. You will also need to have the propertyfile "optional" Ant task installed. The default target in the build.xml file included with Program W will compile the jars:
[noel@vasya ProgramW]$ ant
Buildfile: build.xml
init:
prepare:
[mkdir] Created dir: /home/noel/ProgramW/build.tmp
prepare-src:
compile:
[javac] Compiling 174 source files to /home/noel/ProgramW/build.tmp
jars:
[jar] Building jar: /home/noel/ProgramW/distrib/ProgramD-main.jar
[jar] Building jar: /home/noel/ProgramW/distrib/ProgramD-rhino.jar
BUILD SUCCESSFUL
Total time: 7 seconds
NOTE: If you have a release of JDK 1.5 that is older than Update 6 ("1.5.0_06"), then you will see a few warning messages like this:
[javac] /home/noel/ProgramW/JavaSource/org/aitools/ProgramD/util/ClassRegistry.java:58: warning: [unchecked] unchecked cast
[javac] found : java.lang.Class<capture of ?>
[javac] required: java.lang.Class<? extends B>
[javac] classToRegister = (Class< ? extends B>) Class.forName(classname);
[javac] ^
However, as you can see from annotations in the source code, all these warnings have been evaluated and are known. Prior to Update 6 of JDK 1.5, javac did not pay attention to @SuppressWarnings annotations (see SDN Bug 4986256).
If you use Update 6 or later, you should not see any of these warnings.
In any case, the compile should proceed without errors.
Verify Installation
The Program W distribution includes the set of test cases used to check AIML interpreter functionality, and as shipped, it is configured to load this small AIML set. Therefore, you can verify the installation "out of the box" if you wish, by running the simple console immediately. See First Startup for tips on running the simple console. If all is well, you should see something like this:
[noel@vasya ProgramW]$ bin/simple-console JAVA_HOME is not set in your environment. I found a java executable in "/usr/bin". I have set JAVA_HOME to "/usr". Please consider setting your JAVA_HOME environment variable. [2006-02-23 16:13:20,994] INFO: Starting Program D version 4.6rc1. [2006-02-23 16:13:21,022] INFO: Using Java VM 1.5.0_06-b05 from Sun Microsystems Inc. [2006-02-23 16:13:21,023] INFO: On Linux version 2.6.15-1.1831_FC4 (i386) with 1 processor(s) available. [2006-02-23 16:13:21,085] INFO: 119.1 MB of memory free out of 127.1 MB total in JVM. Configured maximum: 254.1 MB. [2006-02-23 16:13:21,085] INFO: Predicates with no values defined will return: "undefined". [2006-02-23 16:13:21,109] INFO: Initializing FlatFileMultiplexor. [2006-02-23 16:13:21,110] INFO: Initializing org.aitools.ProgramD.interpreter.RhinoInterpreter. [2006-02-23 16:13:21,113] INFO: The AIML Watcher is not active. [2006-02-23 16:13:21,146] INFO: Starting up the Graphmaster. [2006-02-23 16:13:21,178] INFO: Configuring bot "SampleBot". [2006-02-23 16:13:21,679] INFO: Loaded 287 input substitutions. [2006-02-23 16:13:21,683] INFO: Loaded 19 gender substitutions. [2006-02-23 16:13:21,719] INFO: Loaded 9 person substitutions. [2006-02-23 16:13:21,763] INFO: Loaded 60 person2 substitutions. [2006-02-23 16:13:21,796] INFO: Loaded 4 sentence-splitters. [2006-02-23 16:13:21,826] INFO: Configured testing. [2006-02-23 16:13:21,827] INFO: Loading file:/home/noel/ProgramW/resources/testing/AIML.aiml.... [2006-02-23 16:13:22,207] INFO: 100 unique categories loaded in 1.029 seconds. [2006-02-23 16:13:22,208] WARN: 1 path-identical categories were encountered, and handled according to the COMBINE merge policy. [2006-02-23 16:13:22,301] INFO: 125.7 MB of memory free out of 127.1 MB total in JVM. (Configured maximum: 254.1 MB.) [2006-02-23 16:13:22,438] INFO: vasya -> SampleBot: "CONNECT"; SampleBot -> vasya: "Connected to test case AIML set." Interactive shell: type "/exit" to shut down; "/help" for help. [YourBot] user>
The third line from the bottom indicates that a category from the AIML.aiml testsuite has been matched. If you want, you can now run the entire test suite to verify functionality by typing /test
at the prompt. A lot of information will scroll by quickly, ending with
a report of the number of successful test cases. All cases should
succeed:
[YourBot] user> /test [2006-02-23 16:17:49,655] INFO: Loading tests from "file:/home/noel/ProgramW/resources/testing/AIML.xml". ... [2006-02-23 16:17:52,782] INFO: 109/109 tests succeeded. [2006-02-23 16:17:52,836] INFO: Created new test report "/var/log/ProgramD/test-reports/test-report-2006-02-23-16-17-52.xml".
Please note that on Windows platforms, and possibly others (but not Linux), you will need to adjust this item in core.xml in order for the test of the <system/> element to succeed:
<!--The string to prepend to all <system> calls (platform-specific). [String: ]
* Windows requires something like "cmd /c "; Linux doesn't (just comment out)-->
<entry key="ProgramD.system-interpreter.prefix"></entry>
You should also be able to exit the program smoothly:
[YourBot] user> /exit [2006-02-23 16:24:55,543] INFO: Exiting at user request. [2006-02-23 16:24:55,544] INFO: Program D is shutting down. [2006-02-23 16:24:55,544] INFO: Shutting down all ManagedProcesses. [2006-02-23 16:24:55,544] INFO: Finished shutting down ManagedProcesses. [2006-02-23 16:24:55,544] INFO: PredicateMaster saving all cached predicates (278) [2006-02-23 16:24:55,614] INFO: Shutdown complete.
Now that you know you have a working installation, please skim through the rest of these notes and decide what else you want to configure.
AIML
We suggest creating a subdirectory called "aiml" in your ProgramW directory, and then arranging your AIML files there in a way that makes sense to you. You'll need to unzip/untar as above.
Note that, starting with version 4.5 of Program W, your AIML must
declare the AIML namespace URI. The AIML set you download may not yet
have been properly formatted in this way; if this is so, you should
make the changes yourself. The namespace declaration is made on the
opening tag of the root element of the document (the <aiml> tag). At minimum, you should add this declaration:
xmlns="http://alicebot.org/2001/AIML-1.0.1"
Also, if your AIML contains HTML markup (which is common in many AIML sets), you will need to do two things:
- Declare the HTML or XHTML namespace and assign it to a prefix. This should also be done on the root element. This may look like:
xmlns:html="http://www.w3.org/1999/xhtml"
- Add the prefix you associated with the HTML/XHTML namespace to all HTML/XHTML elements in the document. (This is less onerous than it might sound if you use a shell script or batch file.) For instance, every instance of
<br />
- should become
<html:br/>
Additionally, please note that your HTML/XHTML markup (all of the
markup, in fact) must be valid XMLin other words, an opening tag must
have a corresponding closing tag (<some-element></some-element>), and an empty element ("atomic tag") must be properly notated (<some-element/>).
This will all be obvious to you if you are using contemporary standards and standards-based tools, but several years ago the notion of well-formed XML was not something universally familiar, and so some AIML sets still include orphaned tags and other detritus that needs to be cleaned up.
So, starting from a root element that looks simply like:
<aiml>
you will wind up with something like:
<aiml version="1.0.1" xmlns="http://alicebot.org/2001/AIML-1.0.1"
xmlns:html="http://www.w3.org/1999/xhtml"
optional step
For purposes of editing AIML locally, you would be well advised to include an xsi:schemaLocation
notation pointing to a local copy of the AIML schema. If you do not,
then your XML editing application will attempt to connect to the
aitools.org server to grab the schema whenever it needs to validate
AIML, which is probably undesirable (for you and for us). (Note that Program W itself will not
connect to the aitools.org serverit knows to look at the local copy of
the schema.) Just as you would keep a copy of the XHTML schema locally
for validating XHTML, you want to keep and point to a copy of the AIML
schema. A copy of the AIML schema is included in the Program W
distribution. There are two ways of pointing to it. The most direct
approach is to add the following, again to the root element:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://alicebot.org/2001/AIML-1.0.1 resources/schema/AIML.xsd"
However, this has the disadvantage that it hard-codes a local file
path in your AIML file. (It is also technically incorrect, since the
second part of the schemaLocation is supposed to be a
"canonical" URI.) So, if you are using an XML system that supports the
use of XML Catalogs, you can enter the following:
xsi:schemaLocation="http://alicebot.org/2001/AIML-1.0.1 http://aitools.org/aiml/schema/AIML.xsd"
and then, in your catalog file, include an entry like this:
<system systemId="http://aitools.org/aiml/schema/AIML.xsd" uri="./schema/AIML.xsd"/>
Again, an example catalog file is included in the Program W distribution.
Configuration/Deployment
There's a lot to configure with Program W. What's needed for you really depends on how you want to use the program. If you want to use Program W with chat interfaces like AOL Instant Messenger or IRC, you will be interested in the information about "CListeners". If you are putting together a high-volume application, and/or want to do database-based log analysis, you will want to refer to the "Database" section. If you want to deploy Program W as a web application, the section "Deploying the War File" will be important to you. And in any case, you will be interested in the first section, about bot configuration:
Bots
Program W lets you configure an unlimited[1] number of bots that can run at the same time. The bots are configured in the ProgramW/conf/bots.xml file. (In previous releases, this file was called startup.xml.)
Open the bots.xml file. Notice that the root element is called <bots/>. Inside <bots/>, we place one or more <bot/> elements. These <bot/> elements are not the same as the AIML tag of the same name.
Each <bot/> element has two important attributes: id and enabled.
The first one assigns an identifier, which should be unique, for the
bot. The identifier will be used internally by the engine and will be
written to some log resources. The enabled attribute should have either of the values "true" or "false". If the value is "true", then Program W will try to load that bot when the server starts up. Switching enabled to "false" is an easy way to quickly turn off a bot configuration that you don't want to use (although a restart is required).
Within the <bot> element we define bot properties, listeners, default predicates, substitutions, sentence-splitters and learn directives.
Bot Properties
Bot properties are predicates that cannot be changed during the runtime life of the bot, but which can be included in AIML patterns for matching. A common property to define for a bot is "name". Bot properties are defined in individual <property> elements inside a bot's <properties> element, as in this example:
<property name="master" value="Joe Schmoe"/>
This associates the bot property name "master" with the value "Joe Schmoe".
The included bots.xml file uses a <properties/> element with a href attribute that points to a separate file, properties.xml.
This approach, which can also be used for predicates, sentence
splitters, and substitutions, allows easier maintenance of these items,
and makes it possible for multiple bots to use the same sets of these
elements. You can, if you wish, also define these items in the same
file, as children of the <properties/> (or other) element, omitting the href attribute.
Properties don't mean anything unless your AIML uses them. You
can display the value of a bot property inside an AIML template by
using the form <bot name="property-name"/>.
Default Predicates
Default predicates can be thought of as your bot's "assumptions" about new users. While AIML allows you to use <setname="predicate-name"...something...<code></set> and <getname="predicate-name"/>
forms without any sort of "declaration", Program W does allow you to
set default values to associate with any predicate names you wish, so
that you have more control over what is returned by <getname="predicate-name"/> if a corresponding <set> has not yet happened for a given user.
The <predicates/> element, if it exists, may directly include one or more <predicate/> children, or it may use an "href" attribute, as in the provided example, that points to another file where the predicates are defined.
You can also use <predicate/> elements to mark a predicate as return-name-when-set. For instance, this predicate definition is included in a sample file:
<predicate name="he" default="somebody" set-return="name"/>
This means that when <setname="he"...</set> is included in a template, the name of the predicate, "he", will be displayed, rather than whatever value is associated with the name by the <set/>.
Substitutions
Substitutions have several different purposes, depending on their type. Input substitutions contribute to the process of input normalization. Person substitutions provide macros for transformations by the <person/> element; likewise Person2 and Gender apply to the <person2/> and <gender/> elements, respectively.
Starting in version 4.5, the find attributes of
substitutions are parsed as regular expressions. This lends a great
deal more power and precision to the input normalization step, and to
the Gender, Person and Person2 processors. For a guide to the regular expression syntax that is available, see the JDK documentation.
Each individual substitution specification, regardless of whether it is inside an <input/>, <gender/>, <person/> or <person2/>, takes the same form as this example from conf/substitutions.xml:
<substitute find="\bbecasue\b" replace="because"/>
This means that, when this substitution is applied, each instance of the separate word "becasue" will be replaced with "because". (This is an example of typo correction in Program W.)
Note the use of the \b marker, which is regular
expression notation for "word boundary". In previous versions of
Program W, you were advised to pad find and replace strings with
spaces, as a way of approximating word boundary matching. This is no
longer advised, and in fact will not work properly now that regular
expression support is included.
Sentence-Splitters
Sentence-splitters, as described in the AIML spec, are:
...heuristics applied to an input that attempt to break it into "sentences". The notion of "sentence", however, is ill-defined for many languages, so the heuristics for division into sentences are left up to the developer.
Since sentence-splitters are applied to the input after substitution normalizations, they can be more general rules. The entire collection of example sentence-splitters shipped with Program W is:
<sentence-splitters>
<splittervalue="."/>
<splittervalue="!"/>
<splittervalue="?"/>
<splittervalue=";"/>
</sentence-splitters>
As with some other examples, these are defined in a separate file that is pointed to by the href attribute on the <sentence-splitters/> element.
Testing Configuration
A bot can be configured with a test suitea set of test
casesdesigned to test that a bot gives appropriate responses to
particular inputs. Within the <testing/> element, you specify a <test-suite-path/, which should point to a file somewhere that matches the test suite schema (documented elsewhere), and a <report-directory/>,
which is where reports of individual test runs will be written. As
shipped, Program W is configured to use its standard AIML test suite,
and to write reports to a directory /var/log/ProgramD/test-reports (On Windows this will be translated to C:\var\log\ProgramD\test-reports, substituting the current drive letter for C:.)
Learn Directives
Learn directives function identically to the <learn/> element in AIML, but in this context are processed immediately upon startup of Program W.
You can use simple "glob"-like wildcard patterns for specifying files to load. For example, the shipped startup.xml file has this single learn directive:
<learn>../aiml/standard/*.aiml</learn>
The path specification is relative to the current file, so this
indicates that within a directory reached by going one level up (to the
main ProgramW directory), and then into a directory called aiml, and from there into a subdirectory called standard, the program should load all files that end in .aiml. Note that files containing AIML are not
required to have this or any particular suffix; also, if you direct the
program to learn files that do not contain any AIML, you will receive a
warning but nothing will be loaded from that file.
Listeners
In current Program W nomenclature, a "listener" is a program that
knows how to speak a particular protocol and interpret messages for the
bot. For instance, the IRCListener understands the popular IRC protocol and allows you to connect your bot to any IRC server.
You can enable one or more listeners for each bot. Each listener
has its own unique configuration parameters, which are specific to the
requirements of the protocol for which it's designed. You'll find
examples of each currently-available listener in the ProgramW/conf/bots.xml file.
Listeners for a given bot are specified within the <listeners/> element, in individual <listener/> elements. Each <listener> element must have two attributes: class, and enabled. The value for class must be the fully-qualified class name of a listener that is somewhere in the Java classpath for Program W. The example bots.xml includes an example of each type currently known. The value of enabled must be "true" or "false", allowing the listener to be switched on or off with ease.
The parameters for a listener are specifed in individual <parameter/> elements within the <listener/>. For example:
<parameter name="host" value="irc.freenode.net"/> <parameter name="port" value="6667"/> <parameter name="nick" value="your-nick"/> <parameter name="channel" value="#some-channel"/>
These are the parameters set for the example use of the IRCListener, whose class is "org.aitools.ProgramD.listener.IRCListener".
When you enable a chat listener, you will see its output mixed in with the console output. You can also interact with some listeners if they implement the "commandable" interface.
Database
You are not required to install, configure or use a database in order to use Program W. The default configuration is entirely based on text files in order to make setup quick, painless, and no more resource-intensive than necessary.
However, for heavy-volume situations, and/or for cases where you want to collect dialogue in a form that can perhaps be more easily mined, you may wish to use a database.
We have done the most extensive testing with MySQL; however, other users have connected Program W with various other DBMSes. The major point is that you must have a JDBC driver for the database you wish to use. We include the MySQL JDBC driver with the Program W distribution for convenience.
If you do want to use a database, you need to configure it properly in the ProgramW/core.xml file. The relevant part of the file is this:
<!--
DATABASE CONFIGURATION
* This is only meaningful if you are using a database-enabled Multiplexor
* and/or the database-based chat logging.
-->
<!--Typical mySQL configuration-->
<!--The URL of the database to use. [String: jdbc:mysql:///ProgramDbot]-->
<entry key="ProgramD.database.url">jdbc:mysql:///ProgramDbot</entry>
<!--The database driver to use. [String: com.mysql.jdbc.Driver]-->
<entry key="ProgramD.database.driver">com.mysql.jdbc.Driver</entry>
<!--The maximum number of simultaneous connections to the database. [int: 25]-->
<entry key="ProgramD.database.connections">25</entry>
<!--The username which with to access the database. [String: ProgramD]-->
<entry key="ProgramD.database.user">ProgramD</entry>
<!--The password for the database. [String: yourpassword]-->
<entry key="ProgramD.database.password">yourpassword</entry>
You should set these values to match your database installation. Remember that the driver class must be available from the Java classpath.
DBMultiplexor
If you want to store predicates in the database, you must enable the DBMultiplexor. This can be done by switching the comment marks in ProgramW/core.xml so that this:
<!--The Multiplexor to use. [String: org.aitools.ProgramD.multiplexor.FlatFileMultiplexor]-->
<entry key="ProgramD.multiplexor-classname">org.aitools.ProgramD.multiplexor.FlatFileMultiplexor</entry>
<!--<entry key="ProgramD.multiplexor">org.aitools.ProgramD.multiplexor.DBMultiplexor</entry>-->
becomes this:
<!--The Multiplexor to use. [String: org.aitools.ProgramD.multiplexor.FlatFileMultiplexor]-->
<!--<entry key="ProgramD.multiplexor-classname">org.aitools.ProgramD.multiplexor.FlatFileMultiplexor</entry>-->
<entry key="ProgramD.multiplexor">org.aitools.ProgramD.multiplexor.DBMultiplexor</entry>
If DBMultiplexor is enabled, Program W will expect to find two tables called users and predicates in the configured database. The SQL commands for creating these tables are in ProgramW/database/db-multiplexor.script.
Database Chat Logging
Database chat logging stores each exchange with the bot in a
database. This is useful for monitoring conversations, data mining,
etc. To enable this feature, you must enable the appropriate appenders
in conf/log4j.xml by uncommenting this element:
<appender-ref ref="DBChatlog" />
(inside the <logger name="ProgramD"/> element).
Shell and Console
In its usual configuration, Program W displays information about
what it is doing while it starts, runs, and shuts down. We call this
the "console". Also, you can interact with Program W via a simple
shell, if desired. Sometimes it is simpler to use this shell than to
open a web browser or IM program. Both the console and shell can be
configured to suit your needs. Configuration for the format of messages
to the console is done in the ProgramW/conf/log4j.xml file.
If you want to run Program W as a background process, you should
turn off the interactive shell. Otherwise, depending upon your
operating system, the program may be "suspended" or may not run
properly. To turn off the shell, set the ProgramD.console.use-shell property in core.xml to false.
AIMLWatcher
The AIML Watcher is a useful feature that watches to see if you change your AIML files. This allows you to update AIML without restarting the bot.
As a security feature, the AIML Watcher only watches files that were loaded by a <learn/> directive. If you put a new file into a directory with other AIML files, that file will not
be automatically loaded (but you can load it with the /load shell
command if you have access to the console and have not disabled the
shell).
You can enable the AIML Watcher by setting ProgramD.use-watcher to true in core.xml.
First Startup
Starting Program W
Running from the command line
There are two sample "configurations" provided for running Program W directly from a command line (or batch/shell script). Additional configurations can easily be created, to customize the environment in which you run Program W.
To start Program W in the simplest way, run ProgramW/bin/simple-console (*nix) or ProgramW\bin\simple-console.bat (Windows).
If you're using Windows and you launch the batch file by double-clicking it, but there are some configuration problems, the console window might disappear before you have time to read the messages. You are advised in this case to open a command prompt and run the batch file from there.
Starting the server script should look something like this:
[noel@vasya ProgramW]$ bin/simple-console JAVA_HOME is not set in your environment. I found a java executable in "/usr/bin". I have set JAVA_HOME to "/usr". Please consider setting your JAVA_HOME environment variable. [2006-02-27 14:11:33,254] INFO: Starting Program W version 4.6rc1. [2006-02-27 14:11:33,305] INFO: Using Java VM 1.5.0_06-b05 from Sun Microsystems Inc.. [2006-02-27 14:11:33,307] INFO: Running on Linux version 2.6.15-1.1831_FC4 (i386) with 1 processor available. [2006-02-27 14:11:33,356] INFO: 126.0 MB of memory free out of 127.1 MB total in JVM. Configured maximum: 254.1 MB. [2006-02-27 14:11:33,357] INFO: Predicates with no values defined will return: "undefined". [2006-02-27 14:11:33,357] INFO: Initializing FlatFileMultiplexor. [2006-02-27 14:11:33,359] INFO: Initializing org.aitools.ProgramW.interpreter.RhinoInterpreter. [2006-02-27 14:11:33,457] INFO: The AIML Watcher is active. [2006-02-27 14:11:33,457] INFO: Starting up the Graphmaster. [2006-02-27 14:11:33,463] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/bots.xml". [2006-02-27 14:11:33,563] INFO: Configuring bot "SampleBot". [2006-02-27 14:11:33,611] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/properties.xml". [2006-02-27 14:11:33,778] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/predicates.xml". [2006-02-27 14:11:33,836] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/substitutions.xml". [2006-02-27 14:11:34,009] INFO: Loaded 287 input substitutions. [2006-02-27 14:11:34,011] INFO: Loaded 19 gender substitutions. [2006-02-27 14:11:34,058] INFO: Loaded 9 person substitutions. [2006-02-27 14:11:34,118] INFO: Loaded 60 person2 substitutions. [2006-02-27 14:11:34,119] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/sentence-splitters.xml". [2006-02-27 14:11:34,177] INFO: Loaded 4 sentence-splitters. [2006-02-27 14:11:34,179] INFO: Loading "file:/home/noel/workspace/ProgramW/conf/listeners.xml". [2006-02-27 14:11:34,280] INFO: Configured testing. [2006-02-27 14:11:34,281] INFO: Loading file:/home/noel/workspace/ProgramW/resources/testing/AIML.aiml.... [2006-02-27 14:11:34,841] INFO: 135 categories loaded in 1.2740 seconds. [2006-02-27 14:11:34,841] INFO: 135 total categories currently loaded. [2006-02-27 14:11:34,842] WARN: 1 path-identical categories were encountered, and handled according to the COMBINE merge policy. [2006-02-27 14:11:34,961] INFO: 125.7 MB of memory free out of 127.1 MB total in JVM. Configured maximum: 254.1 MB. [2006-02-27 14:11:35,058] INFO: vasya -> SampleBot: "CONNECT"; SampleBot -> vasya: "Connected to test case AIML set." Interactive shell: type "/exit" to shut down; "/help" for help. [YourBot] user>
If there are any errors while starting up, an explanation will be printed and the server will shut down. If you encounter a confusing error message, please file a bug report!!!
The interactive shell is not available when you run Program W as a web application.
Understanding the Console
While the bot is running, information will be printed to the console to tell you what's going on.
Shutdown Messages
Before the bot server can shut down, it must stop the http server and must save any predicates left in the cache. It also must stop all listeners. There are several different ways to shut down, but all of them should cause Program W to print information that looks like this:
[2006-02-27 14:12:28,713] INFO: Exiting at user request. [2006-02-27 14:12:28,714] INFO: Program W is shutting down. [2006-02-27 14:12:28,714] INFO: Shutting down all ManagedProcesses. [2006-02-27 14:12:28,714] INFO: Finished shutting down ManagedProcesses. [2006-02-27 14:12:28,714] INFO: PredicateMaster saving all cached predicates (2) [2006-02-27 14:12:28,824] INFO: Shutdown complete.
"ManagedProcesses" are such things as the http server and listeners. Sometimes one or more of these may take a long time to shut down. Unless you are in a great hurry, you should allow this process to complete properly. The saving of cached predicates should be very fast.
Using the Shell
The simplest use of the shell is to talk to your bot(s). However, there are some other capabilities available to you. All shell commands in Program W are preceded by a / (slash) character. If you type "/help" at a shell prompt, you can see the list of available commands:
[YourBot] user> /help Shell commands are preceded by a "/". Available commands: /memory shows statistics on free/available memory /categories lists the number of categories currently loaded /bots lists loaded bots /test suite [run-count] runs specified test suite on current bot /who prints the id of the current bot /aiml aiml-fragment tries to process a fragment of template-side AIML /files lists the files loaded by the current bot /load filename loads/reloads given filename for active bot /help prints this help /commandables lists available "shell commandables" (such as some listeners) /unload filename unloads given filename for active bot /talkto botid switches conversation to given bot
Loading AIML
The /load command lets you load new AIML files, or reload files (useful if you have disabled the AIML Watcher.)
Unloading AIML
The /unload command lets you unload
an AIML file that is currently in memory. You must unload using the
pathname that was originally used to load it, which can be a little
tricky to get right.
Listing Loaded Bots
You can see which bots are currently loaded with the /bots command.
Talking to a Different Bot
You can switch the bot with whom you are conversing by using the /talkto
command. You must use a valid bot id as the argument. (The bot id is
not necessarily the same as the value associated with its "name"
property. To see bot ids, look at your startup.xml file or use the /bots command.
Each time you switch bots, the connect string will be sent to the bot.
Trying to talk to a botid that doesn't exist will result in an error message.
Connecting via a Chat Interface
If you have correctly configured one or more listeners (see Listeners above), then you should be able to start the appropriate chat client and communicate with your bot. Add your bot to your IM client's contact list so you can see when the bot successfully comes online.
Shutting Down
If you start Program W with the shell enabled, you can shut down the bot from the console by typing the /exit command.
If the shell is disabled, you can shut down the bot by pressing the interrupt key sequence for your operating system; this is often Ctrl-C. Or, on *nix systems, you can send the main JVM process a SIGINT signal with the kill command.