HOW TO CREATE A MIND IN BILLY v3.1
==================================
Greg Leedberg, 2001



SECTION 1: INTRODUCTION
=======================
Billy's "mind" is used to store many types of information that Billy has
learned.  Different types of information are stored in different
"memory banks", which as a whole make up Billy's mind.  Some of these
memory banks are defined completely by the construct developer, and
some are just given a start by you and are added to later by Billy as he
learns.  You should be aware as you are creating a mind what banks are
of what type.  All memory bank names end with ".BFB" because at run time,
the .MND file is nothing more than an archive of files, which are
de-archived when a file is loaded, and then re-archived when the file
is closed.  Each of these files are the individual memory banks, and
each one ends with the ".BFB" extension (which is a tribute to the
Billy program's name back in version 1.0 - Best Friend Billy).  Some
memory banks are more complex than others to design, but each is
described in as much detail is needed below.  Despite the fact that
this document seems to reveal all of the "secrets" of Billy, there is
still much, much more to him as far as the processing that occurs inside
him and how he chooses how he should best respond to an input.  Even if
you have created a mind and completely understand all that is in this
manual, predicting what Billy will say should still prove to be tough
(if not impossible) under some coniditions.

SECTION 2: HOW TO CREATE A MIND FILE
====================================
Creating a mind file can be either really easy, or really... not easy.
If you're reading this document, then you're probably already
bored with "easy".  When you click on Cusomize | Create Mind,
you are given to modes to choose from, Simple and Advanced.  "Simple"
mode is described in MANUAL.TXT, and this file describes just
"Advanced" mode.  Advanced mode revolves around the idea of you
creating the individual memory banks on your own.  Section 3
describes the format and language of each memory bank in detail,
so you should read that fully before you start making your
mind file.  Through the editing of memory banks, you have virtually
COMPLETE control over the personality of the mind file.  When you
create the memory banks, they must all be in separate files,
but can reside anywhere on your hard disk.  Note that if you
plan on keeping them in the same directory as Billy, don't give them
the extension "BFB", as Billy will then confuse them with the
real memory banks and, in short, you'll end up losing them.

After you select "Advanced" mode and give the name of the mind file,
you will be at a screen that will prompt you for each memory bank.
Give the file name (and path, if it's not in the current directory)
for each memory bank file.  If you did not create an individual
memory bank, you can just press <ENTER> to use the default
BILLY.MND version of that bank.

Unfortunately, you can't cancel out of this screen -- there is no "X"
for this window.  If you decide you don't want to go through with it,
just press <ENTER> for all the banks and then delete the created
mind file.

SECTION 3: A NOTE ON GLOBAL VARIABLES
=====================================
Rather than continually listing these, I'll just list here what the global
variables are.  These are variables that can be used in many instances
in Billy's mind to plug in certain values that may change.  If you can
use these in a specific memory bank, that should be noted in the
section dealing specifically with that bank.  The global variables are:

&botname       - The name of the bot
&username      - The name of the user
&day           - The day of the week
&time          - The time of the day
&sigother      - The name of the person they have a relationship with
@age           - The age of the bot
@gender        - The gender of the bot
@location      - The location of the bot
@relationship  - The relationship type the bot has

The "&" and "@" refer to two different types of global variables, but you
need not worry about the difference at this point.

SECTION 4: THE MEMORY BANKS
===========================
4.1: MEM.BFB
============
MEM.BFB is more commonly referred to as Billy's language memory bank.  Since
Billy is based on "free form" sentence generation (he usually is able to
make up sentences intelligently on his own rather than using preprogrammed
sentences), this is the file that stores all of Billy's language and his
sense of grammar.  In actuality, this file simply stores many many sentences,
and Billy can analyze grammar and vocabulary patterns, and use those patterns
to synthesize his own sentences.  If you wish to enter a sentence in this
bank, first, the first line of the file must be "***".  After this instance,
the three-asterisk symbol is used only AFTER sentences, to separate them.
To enter a sentence, each word gets its own line, and capitalization should
be as you would want Billy to use it.  Punctuation MUST be included at
the end of the sentence (".", "!", "?").  As stated, after each sentence,
including the last one, you must have "***".  So, to have a MEM.BFB bank
with the sentences "I am great." and "How are you?", it would look like this:

***
I
am
great.
***
How
are
you?
***

Billy automatically adds EVERY sentence he sees used in conversation (this
is one of the big learning capabilities of Billy).  Global variables
(refer to section 3) starting with a "&" can be used in this memory bank,
but remember that this bank is oriented as having been said by THE USER,
so if you want Billy to say is own name, you must reverse your thought
and enter "&username" in the file, and if you want him to say the user's
name, you must enter "&botname".  The reason for this?  When a user says
"My name is Greg", (assuming their name really is Greg), Billy first
changes that to "My name is &username", then stores it as such in
MEM.BFB.  When it is to be spit back at some point, you wouldn't
want BILLY to say, "My name is Greg", so internally, Billy switches
"&username" to "&botname", but only after having been taken from
MEM.BFB.

4.2: CONTEXT.BFB and CONTEXT2.BFB
=================================
These two memory banks are certainly the most complex.  They also help to
define a particular mind's "personality" more than any other bank.  These
are the files that contain all the sequences of words that Billy should
look for, and how he should respond to those sequences (indivdual sequences
of words are called CONTEXTS in the world of Billy).  Let's start simple.
CONTEXT.BFB and CONTEXT2.BFB use the same "language" to control the
context/response search.  The difference between the two files is that
CONTEXT.BFB handles STATEMENTS, while CONTEXT2.BFB handles QUESTIONS.
Questions are identified by Billy (predictably) by whether or not the
sentence ends with a question mark ("?").  Everything else is a STATEMENT.
The reason the two types of sentences get their own banks is that quite
often, the same sequence of words can have two very different responses
depending on whether it is a question or a statement.

Each of these banks contains many, many, context/response sequences, so
first I will explain how to build just one.  Predicatably, a single
sequence is divided into two sections, the CONTEXT section, and the
RESPONSE section.  These begin with the control statements
"###CONTEXT###" and "###RESPONSE###", both of which get their own line,
and must be uppercase.  So, a simplified sequence would look like this:

###CONTEXT###
[the context to look for]
###RESPONSE###
[how to respond to it]

I will first explain the CONTEXT section.  You have to understand how Billy
looks for these contexts.  He loops through the sentence, taking each
word at a time and looking for each of these contexts relative to the
"current" word in the loop.  The current word is numbered word 0.  Each
word in a sentence will eventually be word 0, but only after each word
before it has been.  The word immediately following word 0 is word 1, the
next one is word 2.  You must use these numbers to have Billy look for
contexts.  Within the CONTEXT section, you must have, on a line by itself,
a word to look for (in uppercase), and on the next line, the "number" of
that word in the context.  Almost all of the time, the first word of the
context will be 0.  Remember, this does not mean it is the first word of
the sentence, just the current word that Billy is on in the loop.  Also
keep in mind that punctuation will have been stripped, and contractions
will have been expanded.  So, to look for the context "How tall are you?",
the context section would look like:

###CONTEXT###
HOW
0
TALL
1
ARE
2
YOU
3

The use of the numbers makes it so that you can look for more than just
uniterrupted sequences of words.  As a technical note, you CAN use
negative numbers (in theory) to access words that came before the
"0" word, but you can't type "-1" in the file.  Instead, add the
absolute value of the number to 1000, and use that.  So, -4 would
be 1004.

The next feature which makes this more complex is the use of variables in
the context section.  Rather than specific words, there are some "global
variables" within Billy that you can use in the context section.   Refer
to section 3 for a list of the global variables.  When you use global
variables, Billy "plugs in" whatever the acutal value of the variable
is, and looks for that in the sentence.

In addition to these variables, you can look for TYPES of words.  When
Billy analyzes a sentence, he puts an ID on each word that he can
indentify.  To look at these IDs in the context, use the following list:

*NOUN          - Nouns
*NOUNMARK      - Noun markers (A, AN, THE, HIS, HER, YOUR, MY)
*STUFFING      - Stuffing
*DEF           - Definition words (IS, ARE, HAVE, DO, HAS)
*GREETING      - Greetings (HI, HELLO, HOWDY, ALLO)
*PERSON        - Pronouns (HE, SHE)

Now, on to the response section.  The response section tells Billy how to
respond to the associated context, and can contain ANY number of possible
responses -- Billy will randomly pick one.  Each response gets its own
line.  There are two possible types of responses, FREE FORM and TEMPLATE,
and each will be described.

Billy has a built-in ability to create his own sentences using knowledge
stored in his language memory bank.  This is the basis of FREE FORM
responses.  Rather than telling Billy exactly how to respond to the
context, free form responses allow you to give Billy a few "keywords"
that should be included in the final response, and he will generate the
most intelligent sentence he can using those words.  A free form response
takes up one line, and is just a sequence of keywords, all in uppercase.
So, to tell Billy to respond with a free form response using the keywords
"I" and "tall",  the response section would look like this:

###RESPONSE###
I TALL

A word of caution is that if you tell Billy to make a response with a keyword
that does not exist in his language memory bank, then you may very well
create an infinite loop when he goes to do what you've told him to do.  As
such, every time you specify a free form response, you should enter at least
one sentence in his language memory that uses these keywords.  So, for the
above example, I might include in his language memory:

I
am
very
tall.
***

This way, right from the start "I am very tall." will be a possible response
to the context.  Over time, Billy will learn more about the words "I" and
"TALL", and will create his own responses.  It is with free form responses
that the different types of global variables come into play.  If you
noticed, some global variables have a "&" as their first character,
while some have a "@".  The ones with an "&" can be used in free form
responses -- those variables are recorded in the language bank as
variables.  The others are not stored as variables in the language
bank (otherwise, for example, anytime the user used the number that just
happens to be Billy's age in a sentence, it be recorded as the "age"
variable, even if that was not the right context) and cannot be used
in free form responses.

The other type of response is called a "template" response, and was created
to enable you to include variables in a response which may not exist in
Billy's language bank.  Template responses are merely template sentences
where certain variables are "plugged in", they are not intelligently
generated by Billy.  As such, you should only use them when you want to
use variables -- using them for normal sentences results in Billy 3.x
being no different from Billy 2.x.

Template sentences are identified by the first word being "@@T".  After this
is a space, and the template sentence.  The primary variables you will
probably be using in template responses are "context variables" -- these
let you plug in words from the context, and they all being with "@".
To plug in the "0" word, you would use "@0".  To plug in the "4" word,
you would use "@4", and so on.

There are some special flags you can use with context variables.  The
"P" flag switches some pronouns, which you may want to switch when
echoed back by Billy.  It switches "HE" to "HIM", and "SHE" to "HER".
The way you specify this flag is "@Px", with x being the word number.
The other flag is "R", with reverses some pronouns you may want reversed.
It switches "MY" to "YOUR" and "YOUR" to "MY".  The way you specify this
is "@Rx", with x being the word number.

Additionally, you can use any global variables you wish in a template
response, and it is only in template repsonses that you can use the
"@" globals.  So, a template response that should say "I am [age] years
old and quite tall, [user name]!" would look like:

###RESPONSE###
@@T I am @age years old and quite tall, &username!

This complete context/response sequence would be coded as follows, then:

###CONTEXT###
HOW
0
TALL
1
ARE
2
YOU
3
###RESPONSE###
I TALL
@@T I am @age years old and quite tall, &username!

One additional point to be made is this: Multiple possible responses is
the norm, but there may be cases where you want multiple contexts to
result in the same group of possible responses.  For example, in the
example above, in addition to a sentence such as "How tall are you?", you
may want to look for "How short are you?" (I know, it's awkward :) ).  This
is achieved with just an extra ###CONTEXT### section.  So, the example now
looks like this:

###CONTEXT###
HOW
0
TALL
1
ARE
2
YOU
3
###CONTEXT###
HOW
0
SHORT
1
ARE
2
YOU
3
###RESPONSE###
I TALL
@@T I am @age years old and quite tall, &username!

Either way, you get a random response picked from the same group.

Note also, that either of these files may, if you wish, be an empty file.
If this is the situation, then Billy will handle ALL input as he would if
the input did not meet any of the contexts in these files.  In this case,
he uses the algorithm from DAISY to extract keywords directly from the
input and build a response on these.  This is fun as a computer science
experiment to see how intelligent a computer really can be, with no
human guidance, but it tends to sound much less intelligent.

4.3: NOUNS.BFB and STUFFING.BFB
===============================
These are two separate memory banks, but their uses are tied together.
When Billy gets input from the user, he tries to identify certain types
of words.  Some of these types are hard-coded into the Billy source,
but for the sake of being able to learn, some are not and can be added
to by Billy as he learns.  One type of words that is important for Billy
to be able to identify are NOUNS.  A mind file starts out with knowledge
of nouns purely from what is contained in "NOUNS.BFB".  On each line
of this bank should be a separate noun, in uppercase.  As a rule, try
to put every noun you can possibly think of in this bank, as any noun will
help Billy seem that much more intelligent.

Over time, Billy can learn new nouns.  One type of word that is hard-coded
into Billy is referred to as a "noun marker".  A noun marker is a word
that tells Billy that a noun is following.  In Billy 3.1, the defined
noun markers are: A, AN, THE, MY, HIS, HER, YOUR.  As soon as Billy sees
any of these words, he assumes a noun is coming.  The problem is, there
may be words in between the noun and the noun marker.  Assuming that the
noun that is coming is currently unknown to Billy (and so will be learned),
Billy looks for words that I refer to as STUFFING after the noun marker.
STUFFING consists of anything that would come between a noun and a noun
marker, most usually ADJECTIVES.  Billy's starting knowledge of stuffing
is stored in STUFFING.BFB, and has the same format as NOUNS.BFB (one per
line, uppercase).  Once again, put every piece of stuffing that you can
think of in this file, to help Billy better identify nouns.

Additionally, Billy can learn more STUFFING.  If he sees a noun marker, and
sees a noun he already knows a few words later, he automatically puts
all the words in between the two into his STUFFING.BFB bank.  Clearly,
if he wrongly assumes a word is a noun or a piece of stuffing, he will
start making wrong assumptions, which is why these banks are so important
to Billy's intelligence.

4.4: ARE.BFB, DO.BFB, and WILL.BFB
==================================
These banks all share the same format and similar purpose (they all help
Billy answer yes/no questions), but respond to different specific questions.
ARE.BFB contains the information needed for Billy to answer "Are you..."
questions.  Similarly, DO.BFB and WILL.BFB contain the information for
Billy to answer "Do you..." and "Will you..." questions, respecively.
You can design Billy to answer in a certain way (yes/no) for specific
questions, but whenever Billy encounters a question he doesn't already
know the answer to, he randomizes the answer, and remembers what he
said.  In my default BILLY.MND file, there are no preset question/answer
pairs.

In all of these banks, the first section determines the possible responses
if Billy has an answer of "yes".  The first line of this section is the
number of possible positive responses.  Following should be each possible
response, on its own line.

The next section determines the possible responses if Billy has an answer of
"no".  The first line of this section (which follows the last possible
positive response) is the number of possible negative responses.  Following
should be each possible response, on its own line.  So, for example, in
the default BILLY.MND's ARE.BFB bank, there are 4 possible "yes" responses,
and 4 possible "no" responses:

4
Yeah, I am.
Obviously, I am.
Yes!  You didn't already know that?
Of course I am, just like you.
4
Not at all.
Can't say that I am!
I wish I was.  Really, I do.
Maybe you are, but I sure am not!

When Billy answers yes or no, he will randomly pick one of the appropriate
responses.

The next section of the bank contains specific questions, and whether they should
be answered as positive or negative.  As I said, Billy will automatically
fill in this section, but you may want to have some presets.  Each
question takes up two lines.  The first line is the question (case doesn't
matter) and the second line is either a "0" or a "1".  A "0" signifies
a negative response, while a "1" signifies a positive response.  So,
a further example of the ARE.BFB bank, with Billy designed to answer
positively to "Are you happy?":

4
Yeah, I am.
Obviously, I am.
Yes!  You didn't already know that?
Of course I am, just like you.
4
Not at all.
Can't say that I am!
I wish I was.  Really, I do.
Maybe you are, but I sure am not!
Are you happy?
1

4.5: BOTINFO.BFB
================
This is a fairly straight-forward memory bank.  It contains all of the
information that can be changed through the Customize | This Mind
menu.  If you choose to edit this directly, the file format is as
follows (excluding the brackets):

[Bot name]
[Relationship type]
[Name of person in relationship]
[Gender]
[Age]
[Location]

4.7: KNOW.BFB
=============
This memory bank serves as the basis for Billy's "knowledge".  Whenever he learns
a new fact, it is stored here, and whenever he is asked a question (other than
"Are you...", "Do you...", or "Will you..."), he gets his answer from here.
Any facts you want to Billy to know and be able to answer questions on can be 
stored here, each on its own line.  For example, if you want Billy to know 
that the sky is blue and sharks are dangerous, the file would look like this:

the sky is blue.
sharks are dangerous.

This file is very straight forward and easy to design.

4.8: BAD.BFB
============
This memory bank simply stores sentences that Billy should try and avoid saying.
He automatically adds to this file when you use the "Don't say that" command,
but if you find there are some troublesome sentences during the development
of your mind file, you can add them here.  Each sentence gets its own
line, and case does not matter.  As is somewhat explained in the manual,
he'll do his best to avoid these, but sometimes he just can't, so don't
be surprised if every now and then one of these does sneak into conversation.

4.9: NAMES.BFB
==============
Billy has the capability to flag certain words in sentences as referring to
people.  In addition to pre-programmed pronoun-type words, he looks for the
names which appear in this file.  Each name should be uppercase, and on
its own line.

4.10: GREETING.BFB
=================
This is another fairly simple memory bank.  This bank just stores all of the
possible greetings Billy can say to start a conversation.  Each possible
greeting gets its own line, and you may use any of the global variables
you wish.

4.11: EMOTICON.BFB
==================
Billy is able to randomly add "emoticons" (also known as smileys) to the ends
of sentences.  This memory bank lets you control what "smileys" he is capable
of using, as well as how often they should show up.  The format for this
file is that the first line is an integer.  The integer represents the "rate"
at which the emoticons should show up.  So, if you want them showing up
every 20 sentences, the integer would be 20.  Note that they are randomized,
so the rate is just an average.  Following the rate, each possible emoticon
gets its own line in the file.  You may duplicate emoticons to increase
their individual frequency of showing up (useful for making some common ones
show up frequently, while keeping some special ones that only show up rarely).
An example EMOTICON.BFB might look like this:

30
:)
:)
;)
:-O

4.12: VERSION.BFB
================
This bank is not created by you, rather it is created automatically by
Billy when the mind is created.  For your reference, this is the file
that allows different versions of Billy (both past and future) to know
whether they can successfully load and use this mind file.  This depends
on the version of Billy for which it was created, and this is why Billy
creates it automatically.
