ChatScript 3 Tutorial

https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/OVERVIEWS-AND-TUTORIALS/ChatScript-Tutorial.md

Building a simple but useful chatbot - one that can help a human plan a travel.

$ mkdir RAWDATA/TEST

$ touch RAWDATA/TEST/tutorial.top

$ cp RAWDATA/filesHarry.txt RAWDATA/filesmine.txt

        RAWDATA/HARRY/simplecontrol.top # default bot control
        RAWDATA/TEST/tutorial.top # tutorial bot data

From now on, we will work with the file RAWDATA/TEST/tutorial.top

3.1 Speaking ( topic: , t: )

topic: ~introductions []
t: Hello, talk to me!

>:build mine

# The keyword t: defines a sentence to say within a topic (it's called a "gambit", as the bot says it without waiting for our input)

3.2 Saying more ( ^keep, random selection [], ^repeat )

topic: ~introductions []
t: ^keep() [Hello] [Hi] [Hey], [talk] [speak] [say something] to me!

the ^keep function tells the bot not to erase the rule after it is used (normally, rules are used only once and then discarded).

topic: ~introductions []
t: ^keep() ^repeat() [Hello] [Hi] [Hey], [talk] [speak] [say something] to me!

A bot normally doesn't like to repeat itself, except when we tell it explicitly using the ^repeat() macro

3.3 Listening ( u:, ^reuse )

Now let's build a bot that listens and reacts to what we say:

topic: ~introductions []
t: [Hello] [Hi] [Hey], [talk] [speak] [say something] to me!
u: (what are you) ^keep() ^repeat() I am a bot.
u: (where do you live) ^keep() ^repeat() I live on your computer.
u: ([what where]) ^keep() ^repeat() Good question.

Note that the match is case-insensitive ('what matches 'What'), and uses canonical forms of verbs and nouns ('do' matches 'did').The engine uses a POS tagger to detect nouns, verbs and other types of words, and convert them to canonical form.

topic: ~introductions keep repeat []
t: HI () [Hello] [Hi] [Hey], [talk] [speak] [say something] to me!
u: WHAT (what are you)  I am a bot.
u: (tell me about yourself) ^reuse(WHAT) ^reuse(HI)
u: (where do you live)  I live on your computer.
u: ([what where]) Good question.

3.4 Short-term memory ( * _ )

Our previous bots could listen and talk. The third thing a bot should do is remember
Building our travel-agent bot. Our bot will try to understand where the user is and where he wants to be, and will try to supply useful information.

topic: ~introductions keep repeat []
t: [Hello] [Hi] [Hey], I will help you plan your travel. Just tell me where you want to go.
u: (I want to go to _*) OK, you want to go to _0.

We use * as a wildcard that means "0 or more words"

In the input pattern, we use _ before the wildcard to capture what the user actually said.

In the output, we use _0 to refer to the first thing we captured ( if we have more patterns to capture, we can use _1, _2, ... _9)

HARRY:  Hello, I will help you plan your travel. Just tell me where you want to go.
copper: > I want to go to the moon.
HARRY:  OK, you want to go to a moon.
copper: > I want to go to earth
HARRY:  OK, you want to go to earth.

3.5 Long_term memory ( $ )

We can create "long-term memory" by using $-variables. 

topic: ~introductions keep repeat []
t: [Hello] [Hi] [Hey], I will help you plan your travel. Just tell me where you want to go and where you want to go to.
u: (be * at _*)
   OK, you want to go from _0.
   $source = '_0
u: ([go fly travel] to _*)
   $target = '_0
   OK, you want to go to $target .
u: (what do I want)
   You want to go from $source to $target .

Here is a sample dialog:

HARRY:  Hey, I will help you plan your travel. Just tell me where you want to go and where you want to go to.
copper: > I am at Earth
HARRY:  OK, you want to go from Earth.
copper: > I would like to fly to the moon.
HARRY:  OK, you want to go to the moon.
copper: > Actually, I want to go to the sky.
HARRY:  OK, you want to go to the sky.
copper: > What do I want?
HARRY:  You want to go from Earth to the sky.

3.6 Dialog Management ( conditions )

Check if the user already said where he wants to go, and if not, ask him specifically. For this kind of tasks, we can use conditions.

topic: ~introductions keep repeat []
t: [Hello] [Hi] [Hey], I will help you plan your travel. Just tell me where you want to go and where you want to go to.
u: (be * at _*)
   $source = '_0
u: (go to _*)
   $target = '_0
u: (!$source)
   Where are you?
u: (!$target)
   Where to you want to go ?
u: ($source $target)
   You want to go from $source to $target .

Help you plan your travel. Just tell me where you are and where you want to go to.

copper: > :reset
HARRY:  Hi, I will help you plan your travel. Just tell me where you want to go and where you want to go to.
copper: > 
HARRY:  Where are you?
copper: > 
HARRY:  Where are you?
copper: > great!
HARRY:  Where are you?
copper: > hello
HARRY:  Where are you?
copper: > I am at Hod Hasharon
HARRY:  Where to you want to go?
copper: > I don't know
HARRY:  Where to you want to go?
copper: > I want to go to Jerusalem
HARRY:  You want to go from Hod Hasharon to Jerusalem.
copper: > really?
HARRY:  You want to go from Hod Hasharon to Jerusalem.
copper: > Actually I am at Haifa.
HARRY:  You want to go from Haifa to Jerusalem.

Those familar with Dialog System terminology will probably notice that we implement an information-state-update dialog manager. The information state is defined by the variable. In each volley, the system first tries to understand what eh user said, then updates the current state, and then generates output to the user.

Our previous bot didn't pay any attention to context - it just looked for an input pattern, so it didn't understand that the words Hod Hasharon are actually a reply to the previous question Where are you?.

topic: ~introductions keep repeat []
t: [Hello] [Hi] [Hey], I will help you plan your travel.
   $issue = null   # initialize the current issue

u: SOURCE (be * at _*)
   $source = '_0   # remember the source
   $issue = null   # clear the current issue

u: TARGET (go to _*)
   $target = '_0
   $issue = null

u: ($issue=source _*) ^reuse(SOURCE)
   # If current issue is source, then assume the
   # user answered the question about his source.

u: ($issue=target _*) ^reuse(TARGET)
   # there must be no spaces between the variable name and the = operator.
u: (!$source)
   $issue = source  # Remember that we asked the user about his source
   Where are you?

u: (!$target)
   $issue = target
   Where to you want to go ?
   
u: ($source $target)
   You want to go from $source to $target .

HARRY:  Hi, I will help you plan your travel.
copper: > :reset
HARRY:  Hi, I will help you plan your travel.
copper: > great!
HARRY:  Where are you?
copper: > grete!
HARRY:  Where to you want to go?
copper: > ferer
HARRY:  You want to go from greet to freer.
copper: > I am at Haifa
HARRY:  You want to go from Haifa to freer.

3.7 Implicit Confirmations ( ^respond )

   Confirm that bot understood the user correctly. There are two types of confirmation:

• Implicit confirmation --- just tell the user what we understood.
• Explicit confirmation --- tell the user what we understood, and ask him/her if it's correct.

By default, the bot stops processing the rules when it finds a rule that products output, so after the confirmation you want to go from Haifa the bot doesn't go on and ask the next quest Where do you want to go, utill the user says another thing.

topic: ~introductions []
t: [Hello] [Hi] [Hey], I will help you plan your travel. 
   ^respond(~question)

u: SOURCE (be * at _*)
   $source = '_0
   OK, you want to go from _0 .
   ^respond(~question)

u: TARGET (go to _*)
   $target = '_0
   OK, you want to go to $target .
   ^respond(~question)

u: DEFAULT ()
   ^respond(~question)

topic ~question repeat keep nostay []

u: (!$source)
   Where are you ?

u: (!$target)
   Where do you want to go ?

u: ($source $target)
   You want to go from $source to $target .

The ^respond tells the bot to use the ~question subtopic, and add whatever text it gets from it to the current statement.
'nostay' means we don't 'stays' in the ~question topic.

HARRY:  Hi, I will help you plan your travel.
copper: > greate
HARRY:  Where are you?
copper: > I am at Haifa
HARRY:  OK, you want to go from Haifa. Where do you want to go?
copper: > I don't know
HARRY:  I don't know what to say.
copper: > go to Jeru
HARRY:  OK, you want to go to Jeru. You want to go from Haifa to Jeru.

3.8 Explicit Confirmation ( rejoinders: a: b: c: .... )

   Sometimes we want to explicitly ask the user what he meant. In this case we expect a yes/no answer, but the meaning of the answer obviously depends on the context - the question that we just asked. One way to handle this is to use rejoinders.

   Here, every time the user answers our question, we ask him if that's what he meant.

topic: ~introductions repeat keep []
t: [Hello] [Hi] [Hey], I will help you plan your travel. 
   ^respond(~question)

u: SOURCE (at _*)
   Is your current location \" '_0 \" ?
   a: (~yes)
      $source = '_0
      ^respond(~question)
   a: (~no)
      OK, so where are you ?

u: TARGET (to _*)
   Is your destination  \" '_0 \" ? 
   a: (~yes)
     $target = '_0
     ^respond(~question)
   a: (~no)
     OK, so where do you want to go ?

u: DEFAULT ()
   ^respond(~question)

topic ~question repeat keep nostay []

u: (!$source)
   Where are you ?

u: (!$target)
   Where do you want to go ?

u: ($source $target)
   You want to go from $source to $target .

a sample dialog:

HARRY:  Hi, I will help you plan your travel. 
copper: > hello
HARRY:  Where are you?
copper: > hello
HARRY:  Where are you?
copper: > at Haifa
HARRY:  Is your current location "Haifa"?
copper: > no
HARRY:  OK, so where are you?
copper: > at Ramt Gan
HARRY:  Is your current location "Ramt Gan"?
copper: > yes
HARRY:  Where do you want to go?
copper: > actually I am at Givat Shmuel
HARRY:  Is your current location "Gilat Shmuel"?
copper: > sure
HARRY:  Where do you want to go?
copper: > to Jerusalem
HARRY:  Is your destination "Jerusalem"?
copper: > y
HARRY:  Where do you want to go?
copper: > to Jerusalem
HARRY:  Is your destination "Jerusalem"?
copper: > yeah
HARRY:  You want to go from Gilat Shmuel to Jerusalem.

3.9 Knowledeg ( ^createfact, table: )

  Our previous bot could understand what the user wants, but it couldn't really help reash his goal because it had no knowledge of transportation means. We can give our bot some knowledge by creating facts.