eggdrop1.6 +/-
                              ___                             
   .-----..-----..-----. __ .'  _|.--.--.
   |  -__||  _  ||  _  ||__||  ._||  |  |
   |_____||___  ||___  |    |__|  |_____|
          |_____||_____|
                              version 2.0.2
				

                              Copyright (C) 2002, ch3mical
                              CitizenK@mad.scientist.com
                              irc.secsup.org (EFnet)



Table of Contents:				section
==================				=======

* Introduction to egg-fu			1.
* Basic usage					2.
    |-How it learns				2.1
    |-How it responds				2.2
    |-Getting started				2.3
    |   `-Configuring your script		2.3.1
    |-Basic commands				2.4
    `-Chatter-mode vs. Info-mode		2.5
* Advanced usage				3.
    |-Inline Operands				3.1
    |-Inline Options				3.2
    |   |-Using them in responses		3.2.1
    |   `-Configuring Inlines			3.2.2
    |-Changing the sex or age of your bot**	3.3
    `-Configuring for an alternate language**	3.4
* Usage tips and tricks				4.

( ** requires modifying crucial files, and possible risk of breaking egg-fu )




1. Introduction to egg-fu
=========================

First of all, what IS egg-fu?  egg-fu is an eggdrop script coded in Tcl
designed to simulate artificial intelligence, and engage an IRC user in
conversation.  The program is not actually artificially intelligent, as
it doesn't make it's own decisions or form it's own opinions, it simply
imitates such behavior by listening to what people say in a channel and
remembering key points and 'learning' new things to say in this manner.
When a topic that egg-fu recognizes is brought up or a keyword is said,
egg-fu will randomly pick a tid-bit of information it has learned about
it and respond appropriately, according to your own configurations.

This is the main function of egg-fu.  To learn and respond.  However,
egg-fu can be configured as a medium for storing and retrieving infor-
mation only when prompted.

egg-fu was based on the infoegg bot (which is based on infobot).  Info
egg was designed such that it would learn by listening and only respond
to questions.  It's learning matrices were very simple.  It was these,
that egg-fu was modeled after, and greatly improved upon.  egg-fu talks
and reacts much more fluidly and intuitively than info egg and requires
no prompting to respond, unless configured that way.  Being able to re-
spond to any line of text sent to a channel (provided it's a topic that
egg-fu knows)  makes it's speech appear more life-like.  In addition to
its own learning capacity, all the teaching methods (features) coded in
allow you to tweak egg-fu's responses to give it an even more realistic
personality.

What prompted me to create egg-fu was when I was idly tweaking the code
in infoegg and fixing bugs. When I realized how much work I was putting
into it, I decided to make my own.  The code was at first loosely based
on infoegg's code, but has since been coded out. However I still credit
infoegg's author to the birth of egg-fu.

I hope you enjoy using egg-fu as much as I enjoy coding it.  I'm always
open to suggestions, criticism, and bug-reports.   Have fun!

							- ch3mical


2. Basic Usage
==============

In case you downloaded egg-fu thinking it was a stand-alone program,
you're wrong; egg-fu is a script for the Eggdrop IRC bot.  You need to
have an installed copy of Eggdrop to be able to run egg-fu.




2.1. How it learns
==================

egg-fu will listen to all the channels in it's config until it hears a
declaration such as "this IS that."  This is what triggers egg-fu to
remember something.  If the keyword or topic already exists, or is similar
enough to another topic, the rest of the statement is stored under that
topic as an alternate response.  So when egg-fu hears "pizza is good" and
later hears "pizza is here!" it will know that pizza is 'good' and 'here'
Therefore, when someone idly mentions pizza ("mmm I like pizza") egg-fu
will respond with something like "Didn't you say pizza is here?"  Each
time egg-fu hears something new, or new information on an old topic, it
will store that tid-bit in it's brain for future reference.  There are
many features coded into egg-fu that allow you to teach it special methods
and types of responses, these will be explained in the advanced section.

What egg-fu does NOT learn from: statements that don't define anything as
fact or opinion.  An example is a statement such as "this sucks!" since
egg-fu doesn't know what 'this' is.  egg-fu will not associate any one
statement with the previous statement, therefore egg-fu will not make the
assosiation when you say "I hate my computer" followed by "It's too old."  
However, saying "My computer is too old" will trigger egg-fu to learn.




2.2. How it responds
====================

Each line sent to a channel egg-fu is monitoring is processed and it will
try to determine if the subject is anything it has learned about.  I like
to think of this as it's 'interest' in a subject.  If it's 'interested' in
the subject of the last statement, it will form a reply based on what
facts and opinions it's accumulated so far.  If the subject is too vague
matching more than one other subject in it's memory, egg-fu will then try
to pick the more accurate subject.

There are two factors that randomize the formation of the response. (1) is
the number of tid-bits known about the subject in case.  If there are more
than one tid-bit known about 'pizza' for example, egg-fu will randomly
select one of them. (2) is the sentence structure.  The sentence structure
responses are fully configurable, as will be explained later, and is
randomly selected from your personalized list of possible structures.  An
example of a possible response to the subject "camaro" based on the
default structures is "Well, someone said the 68 Camaro is really nice"  
or "Do you think the 68 Camaro is really nice?"  As you can see, the
subject egg-fu picked as "68 Camaro" even though it might also have heard
about the 71 camaro, and the tid-bit was "really nice"

A key point, if you teach it "your website is nice" it will reply to "your
website", "blah blah your website", "blah your website blah", and just
"website", but NOT to "blah website".  Make sense?

Also, in this version the bot will generalize ideas into one keyword, such
as if you teach it "the meaning of life is to question the meaning of
life" it will file "life is boring" under "the meaning of life".  It's
still in development...meaning it won't always be so vague, the reason for
this is because I intend to expand the way egg-fu thinks about a topic,
and even insert some sort of topic relation system, so when it learns "a
rose is red" and "a fire-truck is red" it will (in theory) be able to also
make the association that both a rose and a fire-truck are red.  This
method of 'thinking' is very difficult to emulate in AI.

By all means send me any questions or comments you may have about egg-fu's
learning or response methods, I'm always open to new opinions and ideas.




2.3. Getting started
====================

Now, in order to start using egg-fu, you'll need to have a copy of Eggdrop
1.6 or higher installed (http://www.egghelp.org).  It might be possible to
run egg-fu on older versions of eggdrop, but it's not tested and not
recommended.

Assuming you already have eggdrop installed and working, you'll need to
add the following line somewhere in your eggdrop.conf file:

	source egg-fu/egg-fu.2.0.1.tcl

If you un-packaged egg-fu somewhere other than your eggdrop directory,
you'll have to put the correct path to your egg-fu directory, or cd to the
directory that contains the egg-fu directory and move it into your eggdrop
directory using the following command:

	mv egg-fu ~/eggdrop

egg-fu will now run using the default configuration, but it's highly
recommended that you edit your personal configuration first, here's how...




2.3.1. Configuring your script
=============================

Open the .tcl file in your egg-fu directory using any editor.  I prefer
pico, so I'll use that in my examples:

	pico egg-fu/egg-fu.2.0.1.tcl

Now scroll down to where it says "SETUP THE SCRIPT"  The first option
'workingchans' is where you define which channels you want egg-fu to learn
and respond in.  If you want egg-fu to operate in all your eggdrop's
active channels, leave it blank, otherwise list the channels separated
with spaces.

	set workingchans "#chan1 #chan2 #chan3"

The next option is 'otherbots'.  This one is important because if you have
other bots running in any of the channels defined in 'workingchans' it
usually causes egg-fu to learn a lot of non-sense.  Just list each bot (or
even annoying humans) that you'd like egg-fu to ignore separated by space.
Otherwise, leave it blank.

	set otherbots "infobot dark-bot annoying_guy soundbot"

The next option is 'wordfile', this defines the location of your word
file.  You really shouldn't need to change this, unless you have another
wordfile already that you would like egg-fu to use.  It searches for the
file in relation to the location of the eggdrop executable (NOT the egg-fu
tcl). So if eggdrop executable is in /home/lamer/eggdrop and brain.txt is
in /home/lamer/eggdrop/egg-fu, you'd set this to "egg-fu/brain.txt"

	set wordfile "egg-fu/brain.txt"

The next option, 'mdirect' is a toggle.  Set it to either 1 (yes/on) or 0
(no/off). 'mdirect' toggles the "misdirection learning" which will strip
of a leading "nick:" when a user is addressing someone else.  I recommend
setting this to 1

	set mdirect 1

The next series of options (5 in all) control the way egg-fu is used in
the channels. The first option 'it' refers to the command character used
for the triggers. Example, if you set 'it' to "!" and your learning
trigger ('ltrigger') is "set" you would type "!set this is that" to teach
egg-fu something in the channel.  Set 'lrntrig' to 1 to force egg-fu to
use a trigger when learning (anything else will be ignored).  Toggle
'asktrig' and set 'atrigger' in the same fashion, if you wish to use
ask-triggers.

The next 3 options have to do with which eggdrop user-modes will be
required to teach or ask egg-fu, and the last option for being allowed to
use <ctcp> and <notice> operands.  Set them according to eggdrop user-mode
standard.  "-" means ALL will be able to access it.

	set lnreqmo "-"

	set akreqmo "-"

	set cnreqmo "o|o"

And finally the last option is a tweak to fine-tune the range of response
in your egg-fu script, the default is 4 and is more than enough in most
cases.  The most common reason for wanting to change the range value would
be for configuring for a different language, since the subject would fall
in different areas of the sentence.  Never set this higher than 100.
Truthfully, anything over 20 is rediculous, in my opinion, since most
conversations on IRC are in sentences less than 10-20 words.

Now you're done setting up the basic egg-fu configuration.  Start up your
eggdrop bot now and egg-fu will create the birth_certificate.egg file
required for egg-fu to function and continue loading eggdrop.




2.4. Basic commands
===================

To lock or unlock a keyword (wiping any entries and rendering it
un-usable until unlocked), simply type either:

	lock <keyword>
	unlock <keyword>

Lock/unlock require master (+m) user-mode priveledges within the bot.


To freeze/thaw a keyword (saving it's entries, allowing egg-fu to use them
as responses but not learning more for that keyword) type either:

	freeze <keyword>
	thaw <keyword>

Freeze/thaw require operator (+o) user-mode priveledges within the bot.


To force egg-fu to forget a keyword and all it's entries, type:

	forget <keyword>

Forget also requires operator (+o) user-mode priveledges within the bot.

Be careful when using these commands, using too vague of a keyword can
affect more than one keyword in your brain wordfile. <keyword> can be more
than one word.


Typing "tell <nick> <keyword>" will make egg-fu send the response to
<nick> in a private message.




2.5. Chatter-mode vs. Info-mode
===============================

Chatter-mode is simply when you have egg-fu set to run without learn/ask
triggers and let it just learn and talk based on what is said in the
channel.

Info-mode is when you have the commands linked to the triggers, so egg-fu
will only respond or learn when the proper triggers are used, and
optionally if the person has user-mode access.

What is the point of being able to do this?  Well, not everyone is looking
for a bot that spews stuff out when people talk on the channel.  You may
want to setup your bot to handle frequently asked questions in a
support/help channel of some sort.  You're able to control how questions
are asked and who can ask them and also who can set responses to
questions but utilizing the triggers and user-mode options.




3. Advanced usage
=================

Now the good stuff!  Here I'll try to go into detail on the purpose and
usage of all the features of egg-fu.

When adding a response to a keyword, you can add multiple responses in one
instance by separating them with the pipe ('|') character.

	my computer is slow | old | a peice of junk!

Also, if you want to fix a typo in a response, use the following syntax:

	<keyword> =~ s/<typo>/<correction>

Example:

	my computer =~ s/peice/piece




3.1. Inline Operands
====================

Inline Operands (or InOps) tell egg-fu how to send the response.  The
following InOps are currently available:

<reply>  : Sends the text verbatim.

	Hello is <reply> Hi!

<action> : Sends the text in a /me style action.

	Hello is <action> waves hello

<notice> : Sends the text in a /notice

	Hello is <notice> Welcome!

<ctcp>   : Sends the text in a /ctcp  (used for ping, etc)

	ping is <ctcp> PING

All InOps by-pass the random sentence structures.




3.2. Inline Options
===================

Inline Options (or InOpts) are dynamic variables replaced by egg-fu each
time the response is used.  The following is a list of available InOpts
and their function.

$who      : returns the nick of who triggered the response.
$nick     : returns a random nick from the channel's nick list
$date     : returns the system time according to the server hosting your egg
$day      : returns a random day (not the actual day)
$month    : returns a random month (not the actual month)
$animal   : returns a random animal
$item     : returns a random object
$adj      : returns a random adjective
$question : returns the entire string that triggered the response
$keyword  : returns the keyword that triggered the response
$age      : returns the age of your bot
$sex      : returns the sex of your bot
$birthday : returns age and birthdate of your bot **

( ** Due to the nature of the responses coded for $birthday, it MUST be
used in conjunction with the <reply> operand, ie. born is <reply> $birthday )




3.2.1. Using Inlines in responses
=================================

Using these inlines is not complicated.  For Inline Operands, the operand
MUST be the first 'word' in the response.  For instance:

	hello is <reply> Hi there!

The following is an example of a NON-WORKING Inline Operand:

	hello is Hi there <reply> How are you?

ALL operands work the same way.  As of this version, there is not yet a
way to make a multi-line response, but I will code in a method with the
next version.

For Inline Options, you can place the options anywhere within the return
string, but not in the keyword.  The following are some examples of
acceptable uses of Inline Options:

	hello is $who is here

	insult is $who is a $animal

Inline Operands and Options may also be combined in the same response
string, here are a few examples:

	hello is <reply> Hi, $who, how are you today?

	hello is <action> waves hello to $who...

	insult is <reply> You're a $adj $animal's $item!

Keep in mind, if you use the same Inline Option in one response, it will
return the same value each instance, for example the following response:

	insult is <action> hits $who with a $item and a $item!

Will return:

	* egg-fu hits ch3mical with a UNIX manual and a UNIX manual!

I might consider changing this effect to give a random response per each
instance of the same Inline Option, if I decide I like it better that way,
or if I get enough feedback from you people saying I should :P but for now
I'm not going to bother because I don't see many instances that anyone
would use multiples of an option in a single response.




3.2.2. Configuring Inlines
==========================

Just below the basic setup in the .tcl file, it says "These fields can be
modifed if you wish!" this is where you can modify all your responses and
most Inline Options.  This is NOT RECOMMENDED if you don't know what
you're doing!!  There's a good chance you could handicap your egg-fu
script with even ONE badly misplaced { } bracket!  You likely won't get
much 

The only part you should modify is the stuff between the { } brackets,
like this:

  {I heard that !Q is !A}
  {Did you know that !Q is !A?}
  {!Q is !A}

You can delete any of these lines or add more as you see fit.  The little
tags (!Q, !A, !U) are markers for where the question (!Q), the answer
(!A), and the asker (!U) will be placed in the response.




3.3. Changing the sex or age of your bot
========================================

Warning: This process is potentially dangerous to the function of egg-fu.

If you edit birth_certificate.egg located in your eggdrop directory, you
can modify the sex of your bot, changing it to boy, girl or anything you
want.  The contents of your birth certificate will look something like:

	04/06/2002 01:03
	boy

So, as you can see, you can change the date, time and sex of your bot by
carefully modifying these values, but DO NOT change the order and position
of the values, it MUST ALWAYS be in the format:

	MM/DD/YYYY HH:MM
	SEX

The thing about the SEX value is, with the default entry, it will reply
with "I'm a $sex" depending on the value SEX in the birth certificate, so
if you change it to "alien" your bot will be saying "I'm a alien!" which
is bad grammar :P   My suggestion is, if you change the SEX to anything
other than boy/girl, you should make egg-fu forget the default "boy or
girl" keyword reply, and set it to something more appropriate, such as
"I'm an $sex!"  if you have it set to alien or "I'm $sex" if you change
it to male/female.

Whatever you decide to do, DO NOT change the order of the values, or
delete/move/rename the birth_certificate.egg file.

In the future, when I code in DCC commands, these values will be
configurable from DCC.




3.4. Configuring for an alternate language
==========================================

This is definately a bit tricky and requires some skill and a lot of
tweaking.

First of all, depending on your skill, you can change all your inlines and
response patterns as described in section 3.2.1 but that only accounts for
responses.  In order to learn you'll still have to say "keyword IS value"
however the keyword and value can be in your language of choice.  In order
to get proper learning ability you're going to need to modify the code
that triggers learning.

Before I go into that, do note that languages that use a drastically
different character map (such as chinese, japanese, korean, etc) may not
work at all.  But all the germanic and romance languages shouldn't have a
problem, with a little work and tweaking.

To start, setup all your inlines and response patterns as described in
section 3.2.1.  After you've done this, find the following line in the
egg-fu tcl file:

	bind pubm $req(ln) "* is *" learnit
                              ^^
                       only change this

Here you will need to replace "is" with whatever is the equivilent in your
language.  For instance, in spanish "es" means "is"  So you'd change the
above line to this:

	bind pubm $req(ln) "* es *" learnit

Seems simple at first, but you'll soon notice a major difference in the
way egg-fu is responding.  Since not all languages use the same sentence
structure as english, obviously there will be a lot of times the bot
simply will not make sense.  This is where tweaking comes in, if you
carefully tweak your response patterns and the bind above, soon you'll get
a good balance of the two and egg-fu will make much more sense.  It takes
time and patience, though.

The final issue is the second 'learnit' bind, directly under the one shown
above is:

	bind pubm $req(ln) "* isn't *" learnit

You should comment out this line entirely, by putting a hash mark (#) in
front of it like so:

	#bind pubm $req(ln) "* isn't *" learnit

Again, be very careful when editing the code in these areas, one wrong
letter in the wrong place could ruin the function of your egg-fu.  I won't
be able to help very much with converting egg-fu to your language, since I
only speak english fluidly, but just play around with it.




4. Usage tips and tricks
========================

*  Locking.  To reduce responses that simply don't make sense, it's
   recommended to lock words like WHY, WHERE, HOW, WHY, and acronyms like
   WTF.  So when someone says wtf or what in channel, your bot won't reply
   "Did you know wtf is my dog doing" or "I've been told what is wrong
   with your bot?"

*  Names.  People on IRC love to talk shit, so for nicks of regular people
   in your channel, you might want to freeze or even lock their nick, so
   when you get comedians trying to say "<your-nick> is lame!!" to teach
   your bot to bad-mouth you, the bot will just ignore it. (And to get
   back at them you can say "<nick> is lamest!" and "freeze <nick>" and
   then laugh in their face when they try to change it! Buahhaaha)

*  The wordfile format is still compatible with infobot, so you can import
   your wordlist into egg-fu by moving it to the location you set.  Or if
   you want to preserve your current wordfile, you can append your old
   wordfile to the egg-fu wordfile by typing

	cat oldlist.txt >> brain.txt

   Assuming both files are in the same directory.

*  Freezing a lock.  While possible, freezing a lock can be both a good
   way to make sure a certain word/term isn't used, and also keep even the
   owner from using it.  When a locked word is frozen it's no longer
   possible to UNlock this word.  The only way to then unlock would be to
   directly modify the brain wordfile.

*  Forgetting.  Forgetting certain words with special characters in it may
   be tricky because of the reg_sub matching used in Tcl (if you don't
   know what a reg_sub is, don't worry).  To get around this, wildcard
   matching IS ALLOWED when using the forget command.  What does this
   mean? it means you have to be VERY carefull when forgetting, a command
   of 'forget *' would wipe your entire brain wordfile.  So to forget
   those words with special characters that just won't seem to go away,
   use the following syntax:

   (if [test] => blah)

	forget *test*



Have fun!


			Copyright (C) 2002, ch3mical
