Matchbot v1.0

Use Matchbot at your own risk. I accept no responsibly for any type of damage cause by the proper or improper use of the files in this distribution.

What is Matchbot?

Matchbot is a simple Java application for creating scripted 'Chatterbots' and embedding them in any system that can support/interact with Java.

What is Matchbot not?

• The MatchbotEngine is to all intents and purposes 'stateless', it is therefore not possible to create 'bots that will remember visitors to your site.
• Matchbot has no capabilities to use external sources such as search engines on behalf of the user (however it can be scripted to show URLs).
• Matchbots cannot 'learn from the user' nor 'learn from text files'. Everything that the 'bot says must be scripted by you.

Features of Interest

Still with me after all that negativity? Good! There are some features of Matchbot that are less common to 'bot engines:

• The Matchbot applet loads scripts into the vistor's browser so, once started, the user does not have long world-wide-waits in their conversation - because no extra connections to the server are necessary!
• You can make links (similar to hyperlinks) from the main script to others which will be loaded dynamically if required.

• The Engine will make use of any Synonyms that you tell it to.

E.g. chap,man,lad and bloke all (roughly) mean 'male'
By allowing you to specify which words you wish to mean the same thing, Matchbots can appear to 'understand' more words and slang than they actually do.

 

Setting up the distribution?

Setting up the bot is easy. Simply copy zip file to the directory where you wish to place the 'Bot and unzip it.

What's in the distribution archive?

After unzipping the zip you will have the following files:

MatchbotDoc.html  (This file)
classfiles
jar file (containing class files)
the html page containing the applet tag for the MatchbotApplet
triggers.mbt example triggers file
synonyms.mbt example triggers file
nutrition.mbt example triggers file for dynamic loading.

What is a Script?

A script is the basis for a Matchbot personality, it tells your Matchbot what to say and when to say it.
Scripts are made up of 'trigger-response' pairs. The response is used if the trigger matches the users input.

   TRIGGER  :  *What*your*name*
   RESPONSE :  My name is Matchbot!

This means that if the user asks for the bots name, it should reply "My name is Matchbot!".

When the user enters their sentence, it is stripped of all punctuation and then tested against each trigger, starting from the top of the script. When a trigger is found that matches, its response will be used. If you put more than one line after the trigger, one of the responses will be chosen at random. //TODO //HERE You can also give the same response to a number of different triggers, other trigger options. eg // Hints. If your triggers arn't working the way you expect have a look in the Java console in your browser when the applet is running. If there are any problems with the script, Matchbot will print them here. // topics. In normal conversation, when there is a mutual understanding as to what is being discussed, it is natural to drop the subject of the conversation, leading to questions in like "are they?" or even just "why?". Grouping triggers into topics allows Matchbots to cope with this sort of conversation. topics

Triggers can be grouped into Topics.

The information given above should be enough to get you started writing a Matchbot personality. However, there are a few 'special' trigger options...

Showing URLs

When writing triggers, the MatchbotEngine allows you to store an arbitary string with each trigger.
In the MatchbotApplet, these strings are taken as URLs to be shown if the trigger fires.

To associate a string with a trigger, you place the string in brackets after the trigger condition.

Thus, if you wish a script to show the 'Altavista' search engine if the user types:

    "Hey, load altavista for me"

you would include the following trigger in the script:

 *load*altavista*(http://altavista.digital.com)>avLoad 
 There you go.

When triggered in the MatchbotApplet, this would:

• Load altavista into the frame named in the 'targetFrame' applet parameter.
• Change the topic to [avLoad]
• Respond with "There you go."

NOTE:You don't have to change topic when you are using URLs.
I simply included the topic change for completeness. The URL would still be shown if ">avLoad" was removed from the trigger.

If you are intending to write your own client, calling MatchbotEngine.getURLToShow() after MatchbotEngine.respond(); will return any bracketed text (without the brackets) defined for the trigger.
null is returned if nothing was defined.

(See Skeleton Code for full example.)

The matchbot engine See the triggers.mbt file. see the synonyms.mbt file for an example.

What topic am I in?

You might find it useful to add 'debug' triggers into topics eg.

[pets]

# Main topic triggers

*_topic_*
The current topic is 'pets'

this way you can check what the current topic is.

Where are my triggers going?

If a trigger is defined in the triggers.mbt file before a [topic] declaration is made,
the trigger is placed in the default [*] topic.

To * or not to *?

Its best to only use a '*' trigger in the root [*] topic.

Matchbot will change from a subtopic to the topic tree root [*] if no trigger matches in the subtopic

If you have a '*' trigger in the subtopic, it will always match and the user may not be able to get out of the topic.
Of course there are ways round this, but you should only play if you are sure you know what you are doing.

If you want a sort of catch all (say in the [work] topic) using:

*work*

provides a fair (and much safer) alternative to a '*' trigger.

Watcha tryna say?

You can also add entries in the synonym file to 'map' contractions to their expanded form.

# These examples are from synonyms.mbt
how is=hows
let us=lets
i am=im

Setting up a Profanity filter

If you want to have a profanity filter, that is - the program gives a standard message if the user types in rude words:

In the synomns file, map the swear words to a rootstring, EG:

profword=paycut,taxman,etc

Then in the triggers file add

*profword*
Hey not so harsh!

(Of course, this will also produce the response 'Hey not so harsh' if the users sentence contains the word 'profword' so choose your rootstring with care..)

Say Something! (Default responses)

To set responses that will be said if no other triggers match
add a '*' (trigger that matches everything) at the end of the default topic [*]

*
I didn't understand that!?
What are you on about?
Was that English?

Remember, a trigger can have as many responses as you care to write, and in this case the more the better.

Line up in an orderly fashion!

Remember to order the triggers in each topic with the most complicated triggers at the top, and the simplest ones at the bottom.

In the worst case, if you put a trigger with a '*' trigger at the start of a topic, then no other triggers will ever be tested.
(Because the first trigger maches anything)

Data files

Blank lines in any machbot datafile will be ignored (trigger and synonym files)

You can also put comments in any data file by starting them with the '#' character.
(Note this means that responses should not contain the '#' character or the rest of the response will be ignored.)

Where does it all end?

If you use a trigger such as "*you*" it will also match sentences that contain the word "your", "yourself" etc

If you dont want this to happen, add underlines to show the word terminator

*you_*

And if you dont want it to match 'thankyou'

then use:

*_you_*

Let me out of here!

Although you have to be careful with '*' triggers in subtopics you can have some fun with them.

Suppose that you wish a bot to seem offended, simply change topic to the [bot_offended] topic given below and the bot will ignore any other input until the user apologises.

[bot_offended]

*sorry*>*                # If they say sorry we will let them out of this subtopic
Ok, I forgive you


*                        # If they say anything else....
I refuse to talk to you until you have apologised...

Whats going on?

When the MatchbotEngine loads trigger and data files, it writes out any syntax problems it found, or changes it made to triggers to the Java console. (The Engine transforms any synonyms it finds in a triggers to the rootstring.)

Finally, here's a few possible setups and applications for Matchbot.

Setups:

As the MatchbotEngine has been written as a module, it can be used in a number of ways:

Applet Embedded in Webpage:
The setup given in the distribution file. All processing in done by the visitors browser. (The MatchbotEngine loads scripts dynamically from the server as required.)

Server-Side:
The Engine could be embedded into a servlet or dedicated-server.
(Although both of these seem a little OTT given the Engines limited functionality.)
The client-side interface could then be written in any language that can connect to the server.

Script-Interface:
If you want a non-Java interface but don't have the access to run anything server-side, it is possible to write a 'stub' applet making the Engine available to client-side scripting languages. With such an applet in place, the interface can be created with script/HTML. The script then only has to call the applet for responses to user input.

Applications:

• Just for fun like MeBot, the example script in the distribution.

• HTML Documentation interface / file server.
  - Fed up of typing in URL's for files that you commonly use, and want something a bit more interesting than a link-filled HTML jump page. "Give me the sun javascript reference stuff, (please)"

• Web-site guide.
  - (This is something that Matchbots can do as well as the commercial bots. )
  - Let a bot guide visitors around your site by answering questions such as, "whats new?", "are there any free downloads?" and "show me a sitemap!" (and showing the relevant pages).

Components. Placing data files // All of the data files must be in the same directory (they do NOT have to be with the applet) // They must be on the same server due to unsigned applet security restrictions.

Skeleton code for using the MatchbotEngine

If you wish to have a Matchbot on your web-page, then you can simply write your own scripts and use the MatchbotApplet to embed them into your web-page.
However the MatchbotApplet is a very plain example of an interface and you might want to use the MatchbotEngine in your own applets or applications.

Below is the minimum code necessary to use the MatchbotEngine.

   /* The engine is stateless so we must remember the current topic ID */
   private String strCurrentTopic = "*";
   
   /* We now instantiate a MatchbotEngine                                        
    * The creator takes the following parameters:                                
    *    The URL path to the data files                                          
    *    The name of the primary triggers file                                   
    *    The name of the synonmys file                                           
    *    A flag setting the use of dynamic loading. true = use dynamic loading   */
   MatchbotEngine mbEngine = new MatchbotEngine(
                                                "http://datapath/",
                                                "triggers.mbt",
                                                "synonyms.mbt",
                                                false 
                                               );


   /* Having instantiated an engine, you can handle user input */
   while (pseudo_doInput)
   {
      /* The respond method returns the scripts response to strUserInput   
       * Note that we pass in the current topic                            */
      String strResponse = mbEngine.respond(strUserInput, strCurrentTopic);

      pseudo_print (strResponse);
      
      /* We must remember the new topic as the engine is stateless */
      strCurrentTopic = mbEngine.getCurrentTopic();

      /* We can also find out if the trigger specifies a URL to show         
       * if a URL is returned, it will be exactly as it was specified in the script */
      String showURL = mbEngine.getURLToShow();
      if (showURL != null)
      {
         pseudo_showURL (showURL);
      }
   } // End while