MegaHAL, the eggdrop module

Artificially Intelligent conversation with learning capability and psychotic personality.

version 3.7.1, with special changes to the script and very, very minor changes to the module itself by rglx.

requirements

• recent version of eggdrop ( https://www.eggheads.org/ ) compiled, running, set up and operational in a channel already
• the megahal.mod folder (not the main repository, but the subfolder here which should contain the Makefile and the .c and .h files)
• the training text files of your choosing

installation

1. stop your bot and make a backup of your userfile, channelfile, and while you're at it, everything else in ~/eggdrop.
2. add the megahal.mod folder (not the whole repository! just the subdirectory!) to eggdrop's source code directory under eggdrop-<version>/src/mod/. inside eggdrop-<version>/src/mod/megahal.mod/ should be Makefile, megahal.c, and megahal.h.
3. seriously, make that backup.
4. from your source code directory, run ./configure plus whatever your usual options are (for say, pointing to a specifically compiled tcl version, or compiling in SSL, or something)
5. after that's done, make config (or if you used the interactive module setup make iconfig) then make -jX (where X is how many logical cores your machine has) and finally make install (if you used the interactive module setup, please make sure to enable compilation and installation of megahal when it asks.)
6. copy scripts/ and text/ and data/ to your eggdrop installation's directory along with their contents
7. edit the configuration section of scripts/megahal.tcl and then return here
8. ensure you have proper directory structure (save for what's not been generated by the bot yet) before starting
9. add source scripts/megahal.tcl to the bottom of your bot's main configuration, below most everything else.
10. start your bot. it should appear on IRC after generating a brain out of the stock training files.
11. run !brainsave in IRC to save your bot's brain. if everything went smoothly this should tell you some information about your bot in addition to making sure the bot's working OK.
12. anywhere you want the bot talking on its own, run .chanset <#channel> +megahal in DCC (or the bot's console if you use a tmux session and the -nt execution argument)

contributing (see the issues section)

if you found some old copy of the source for a different 3.x version of megahal.mod, diff it against this one, and tell me what you find, or just upload it somewhere and hit me up in the issues section. i'm always looking for more cool things to add to this repository. it's not just gonna be for 3.7.

i won't be changing brain structures or other lower-level things like that in the main part of this repository, only some polishing of the main code.

technical documentation

most of this i've just gathered over years and years of running an eggdrop bot with this module loaded on an irc channel (or in one instance, a telegram group chat) and just experimenting with the bot or debugging mysterious crashes on startup or what have you, so some of it could be flat out wrong compared to what zev, z0rc, hutch, and the others know as facts.

also, it might kill YOUR brain to know what goes on inside megahal's. you've been warned.

changes since v3.7 (found on z0rc's github)

• changed the main binds inside the megahal module to be pubm instead of pub, which was preventing other AI scripts from hearing things from IRC.
• overhaul of the megahal.tcl script, including:
  • addition of a proper age counter for the brain
  • deeper explanations of the configuration
  • now requiring the script for functionality (as it does lots of things for you)

directory structure aka "what files do what"

partial directory listing of your bot

+ eggdrop/ - eggdrop's working/install directory
|
+---+ scripts/ - eggdrop's scripts folder
|   |
|   |---- megahal.tcl - companion script for megahal that adds functionality - see notes below
|   |
|   \---- <your bot's other scripts>
|
|
+---+ modules-<version>/ - eggdrop's modules folder (typically this is symlinked when `make install` is run to modules/ along with the main binary)
|   |
|   |---- megahal.so - the main megahal module itself.
|   |
|   \---- <your bot's other modules>
|
|
+---+ text/ - eggdrop's data directory (for userfiles and whatnot)
|   |
|   +---+ megahal/
|   |   |
|   |   \---+ megahal.trn - main training text file. see notes below
|   |       + megahal.aux - another training file. see notes below
|   |       + megahal.ban - another training file. see notes below
|   |       + megahal.swp - another training file. see notes below
|   |
|   \--- <your bot's motd, help texts, and other things>
|
|
+---+ data/ - eggdrop's data directory (for userfiles and whatnot)
    |
    +---+ megahal/
    |   |
    |   \---+ megahal.brn - the brain itself. little is known of the human brain, and this holds true here as well.
    |       + megahal.dic - holds megahal's entire dictionary of words (for construction of sentences)
    |       + megahal.phr - hold all phrases megahal has encountered (for structural considerations)
    |       + megahal.age - contains a unix timestamp of the brain's first known load or generation date.
    |
    \--- <your userfile, channel file, and some script data>   
   

megahal.tcl

this script was originally developed by a number of other people and when Nexor wrote 3.7's custom folder configuration options the script didn't respect any of the settings it had, so i took some quality time and rewrote it. as a result, the script is required for running with this version of megahal.

features (aka why should you use it)

• allows some simple statistics reporting about the brain
• automatically saves the brain every ten minutes
• eases management of multiple brains to an extent
• allows controlling frequency of replies and toggling learning mode on and off temporarily

changes

(since version 3.7 which the script wasn't fully supporting)

1. added an age timestamping file in the brain directory (megahal.age) which contains either the last modified time (as reported by filesystem) of the brain, or the current timestamp if the brain file is absent. you can change this to a more accurate value after it's created.
2. repaired lobotomy and restorebrain commands and added functionality with the new age timestamp file
3. changed all returned messages to NOTICEs to the channel they're run in to prevent other bots from learning output from this one
4. bumped the version number
5. actually handle saving/restoring properly and support preservation of .phr and .dic files to prevent horrible things from occurring

commands

commands added as a part of the companion script

• !savebrain - trims the brain down to your maximum nodes and then saves the brain to file, reporting some statistics afterwards.
• !trimbrain <nodes?> - trims the brain down to your maximum nodes or specified number, then saves the brain.
• !braininfo - reports some information about the bot's current brain
• !lobotomy - backs up the bot's current brain and deletes it, retraining it from start
• !restorebrain - restores the bot's most recent (but not current) brain, and reloads it from disk. might take some time depending on how big it is.
• !talkfrequency - on-the-fly, temporary (until bot restart/rehash) adjustment of talking frequency.
• !learningmode - on-the-fly, temporary (until bot restart/rehash) enable/disable of learning lines from the channels its in

megahal.so

not much to say here... it's the compiled version of the megahal module for eggdrop. see the contributors section way down below for more info on who wrote it. basically uninterpretable to me, i only barely managed to adjust the following:

• changed pub binding of botnicks and * to pubm to allow another AI or something to see the messages.

commands

commands added from the module itself

• !forget - forces the bot to forget a certain phrase
• !forgetword - forces the bot to remove a word from its dictionary
• !megaver - reports current version of megahal

megahal.trn

contains a bunch of sentences whose purpose is to expand the vocabulary and the phrases the bot knows. there's currently some limitations that i've run into so I'll go ahead and list those here:

• don't have a single line longer than 256 bytes, incuding the trailing newline. this will cause the bot to segfault while training a brain anew from this file. lines from IRC can (seemingly) be as expansive as 512 with no issues, but this file is particularly restrictive.
• don't put weird characters in it. anything non-ascii will likely cause issues (and thus, a segfault) while training a brain anew.
• don't make it fucking huge. i think the maximum safest value for this is probably around 100MB. the relation between this file's size and RAM use on training start is exponential, but afterwards it can (until it tries to generate a sentence) drop back down.

megahal.aux, megahal.ban, and megahal.swp

contain words that can either:

• be only used as supplementary keywords attached to other words inside the brain
• not be used as keywords at all
• be swapped with other keywords to get a different set of possibilites

megahal.brn, megahal.phr, and megahal.dic

brain, phrase file, and dictionary. these comprise the entirety of your bot's brain! you should not mix and match with other brains' phrasefiles and dictionaries. the script will keep track of these for you.

megahal.age

generated by the companion script. contains a unix timestamp of when the brain was created or earliest known modified time, whichever we could find that's earlier. you can edit this once it's created to be more accurate.

contributors

• original megahal code by Jason Hutchens (1999)
• eggdrop module and initial companion script by Zev ^Baron^ Toledano (up to 3.5), z0rc (3.6), and Nexor (v3.7)
• further minor revisions by rglx (2021)
• for more information plus an enormous changelog look in <../../megahal.mod/megahal.c> in the comments :)