= Purpose

This set of libraries and one main program -- micro_blog_bot.rb -- aims at
simplifying automated response systems ("bots") for popular micro-blogging
services such as Twitter.com and Identi.ca.


== How to make your own bot
After you have set up the framework, it is just as easy as shown below to
make your own micro-blogging bot. However, in order to make them run you
need to set up the framework first. See sections +Setup+ and +Bot account
data+ below.

=== Sample chat bot with default functionality:
 require (File.join(File.dirname(__FILE__), '') + 'micro_blog_bot_runner')

 class SampleBot < MicroBlogBot
   # for a sample chatbot no changes are needed
 end

 MicroBlogBotRunner.new(SampleBot.new).run

This is actual code taken from +sample_chatbot.rb+.

=== Sample shadow bot
A starting point for building a user output augmenting bot or a gateway.

 require (File.join(File.dirname(__FILE__), '') + 'micro_blog_bot_runner')

 class MicroBlogShadow < MicroBlogBot
   def act_upon_message(msg)
     screen_name = msg['screen_name']
        msg_text = msg['text'];
       timestamp = msg['created_at']; timestamp.gsub!(/ \+0000/, '')

     @talk.log "received '#{msg_text}' by @#{screen_name} at #{timestamp}"
   end
 end

 MicroBlogBotRunner.new(MicroBlogShadow.new).run

=== Launch & Shutdown of the sample bots
Copy above sample code to a text file or just take the pre-packed
+sample_chat.rb+ and run it from the command line:

  $ ruby sample_chatbot.rb

Once launched, you can interact with the bot through the micro-blogging
service chosen. For example, try

  @yourbotname help

assuming your bot's micro-blogging service's account nick name is
+yourbotname+.

To shut down, give

  @yourbotname shutdown

through the service.


== Setup

After I ran the n-th times into trouble with RubyGems and some updated
individual gem, I gave the Debian Ruby package another try and -- what
miracle! -- this time everything looked just fine.

However, the point in mentioning this is to state that I honestly have no
clue of what Debian's Ruby package may have additionally to it what a
standard installation of a plain Ruby may have not.

Anyways, here's what I know for sure what you need to get the bot run:
* The bot relies on the Twitter gem by J. Nunemaker (@jnunemaker), which in
  turn depends on the gem echoe. So, you need to install the +twitter+ gem
  and the +echoe+ gem. (I state this explicitely, as +twitter+ 0.4.1 did not
  make RubyGems to also install +echoe+, in my case.)
* On Debian, aside of just the main Ruby package, you will need to install
  the +ruby-dev+ package also, so you'll get +mkmf+, and +libdbm-ruby+ too.


=== Using the twitter gem

The bot framework relies on the twitter gem. Up to version 0.4.1 the gem
support both, Twitter and Identica. By version 0.5.0 the gem dropped Identica
support.

Though, as Twitter itself struggles more often but Identica does, it's
usually more painless to develop a bot against Identica first, then switch
to Twitter and enforce that the bot runs well against Twitter too.

To achieve that, the bot framework currently makes use of two different
versions of the twitter gem, v0.4.1 and v0.6.12. 0.4.1 gets used when
connecting to Identica, 0.6.12 for Twitter.

There's a little price in that: 0.4.1 does not support sending direct
messages. The bot framework handles that by sending direct messages as
replies instead when using the 0.4.1 version of the twitter gem.

This issue needs improvement. A helping hand here would be welcomed.


Update:
Twitter gem 0.6.15 requires +newgem+ which in turn demands a whole bunch of
further gems. First, on a current Debian Lenny, using Debian's rubygems, the
dependencies of the +newgem+ cannot get resolved (which renders twitter gem
0.6.15 unsuitable for Debian Lenny). Second, that whole bunch of dependencies
reminds of half a rails environment. Then, if we need all those gems anyways,
then why not switch to the twitter4r (!) gem instead? Also, as John removed
identica support from the twitter gem, another alternative would be to fork
the twitter gem altogether to have support for identica too and no
dependencies on gems that don't play with Debian Lenny's rubygems. That's
going to be reviewed. However, for the time being, I put the bot framework's
dependencies to twitter gem 0.4.1 for identica support and to 0.6.12 for
Twitter support (and Lenny support also). If you want to help to resolve that
issue, feel free to join. The repository lays at
http://github.com/dagobart/mbbot/tree/master


==== Why developing against Identica is better

Twitter restricts the number of accesses to 150 times _per_ _hour_. During
development this is rather inconvenient when you need to try things out.
Identica's restrictions are more relaxed.

Even more, as Identica is free software, you can install your own Identica
server and develop against _that_. Despite I couldn't find a suitable
installation howto for Debian, I assume that by that you could drop the
messages-per-hour restriction to zero.


=== Patching gem twitter 0.4.1 and 0.6.12

During development I stumbled upon some minor flaws in the underlying twitter
gem the micro-blogging bot uses, in both versions used by the bot, 0.4.1 and
0.6.12. While the flaws are there, the bot may not work properly in all its
aspects.

There are different issues with and patches for twitter gem 0.4.1 and twitter
gem 0.6.12.

As we currently rely on the specific gem versions, I include patches for them.
So, prior to launching the bot you need to make sure the respective patch is
in place. You do so by actually patching the Twitter gem.


==== Patching gem twitter 0.4.1

In patches/gems/twitter-0.4.1/lib/twitter/ there is a file named
base.wrs.diff. That is the patch. You apply it by copying it to where the
Twitter gem's base.rb file resides (helpful: locate
twitter-0.4.1/lib/twitter/). Then you execute this command:

  $ patch base.rb base.wrs.diff

And that's it for 0.4.1


==== Patching gem twitter 0.6.12

In patches/gems/twitter-0.6.12/lib/twitter/ there is a file named
add_public_timeline_method.patch. That is the patch. You apply it by copying
it to where the twitter gem's base.rb file resides (helpful: locate
twitter-0.6.12/lib/twitter/). Then you execute this command:

  $ patch base.rb add_public_timeline_method.patch

And that's it for 0.6.12


== Bot account data

Sharing your bot's account data is abuse-prone. Therefore, all account data
this here package shares, is dummy data.

In order to get a bot of your own set up and use-able, you have to do two
things:
# Register a user account for your bot with any micro-blogging service with
  an API compatible to Twitter's one.
# Make one or more valid login data files.

The first, you perform just the same way as you'd register any other new
account with the micro-blogging service.

The second, you achieve by just copying these files to some of your own:

  $ cd config/credentials/
  $ cp twitterbot.yaml my-twitterbot.yaml
  $ cp twitterbot.yaml my-bot.yaml
  $ cp twitterbot.yaml my-identibot.yaml

Note, that the 'my-'s are not just an indicator for placeholder file names
but the names are really meant to feature a prepended 'my-'. If you long for
alternative names, you of course can create just files with those names, but
you need to update the micro_blog_consts.rb consts
+VALID_*_CREDENTIALS__DO_NOT_CHECK_IN+ with your alternative names then.

Once you have these three files in place you need to enter valid credentials
there. Obviously, +my-twitterbot.yaml+ is for Twitter credentials and
+my-identibot.yaml+ for Identica. (Note, that it's +identibot+, not
+identicabot+.) Below, we go into my-bot.yaml, too. The files are structured
and easily understood. As an example, here's the original twitterbot.yaml:

        account:
          service: twitter


        twitter:
          peer: dagobart      # testing needs a second user to bond with
          supervisor: dagobart  # the user who is allowed to shut down the bot
    user: twitterbot
          password: secret

        identica:
          peer: dagobart
          supervisor: dagobart
          user: identicabot
          password: secret
          use_alternative_api: 'identi.ca/api'

As you can see, there is an +account+, a +twitter+ and an +identica+ block in
here, and you might wonder about the latter, since this file seems to be for
Twitter credentials. The answer is: As you've seen above, we actually use
this file as a master for all the other credentials files. Also, it's simply
handy to be able to switch between different services just by changing the
+service+ line of the +account+ block. Remember the Fail Whales phase of
Twitter? There you have it. Just switch to the alternative then.


=== How do I get the actual credentials files?

Simple: In your +my-identibot.yaml+, set +service+ to +identica+, in
+my-twitterbot.yaml+ keep it on +twitter+, and in +my-bot.yaml+ just make
your choice.

+my-identibot.yaml+ and +my-twitterbot.yaml+ are for tests, but if Twitter
fail whales +my-bot.yaml+ is your place to go to switch to an alternative
service.


=== Sections of the credentials file(s)

The +twitter+ and +identica+ blocks are designed similarly:
* Each features a user and a password field. Enter here the nick name of your
  bot and the password for that account.
* The +peer+ entry is needed for running the test suite, especially the
  message threading and reply-to tests. Please do me a favor and replace the
  current +dagobart+ -- which is my regular user account at both, Twitter and
  Identica, -- by any account you control: If you'd run your tests against
  @dagobart, it would flood my replies, and I might have no chance to ever
  get rid of those test message the tests of your bot create.
* The +supervisor+ field enables you to control your bot online via an
  alternative account, say your common one. "Control" currently means that
  you can initiate shutting down your bot online. If you keep this field
  clear, just everyone can shutdown your bot.
* On +identica+, there is an additional field, +use_alternative_api+. This is
  for telling the bot, which URL to talk to to interact with any
  micro-blogging service other than Twitter itself. So, Identica has its API
  at +identi.ca/api+, and an other service would have its somewhere else.

Actually, this +use_alternative_api+ field enables you to make use of
whatever alternative micro-blogging service you might want to use: Just copy
the +identica+ block, rename it appropriately, update login, peer and
supervisor fields, and the +use_alternative_api+ field. Finally, set
+service+ in the +account+ block to your new service.


=== Feel free to delete

In any of the credentials files mentioned above, you are free to delete the
blocks you don't need. Essential are only the +account+ block and that
service block the +account+ block+ refers to.


== Dealing with down times of a service

Especially when running the test suite against Twitter it is rather likely
your current IP address will be blacklisted for a while: I very often
experienced that the first test suite run went through quite well, and then
testing a minor change just a few minutes later made #400 errors going off
all over the place.

On testing against Identica, I never had that. So, you might conclude, then
why not just test against Identica only? -- The answer is: Identica has other
flaws.

So, you don't get around to test against all the services your bot shall run
at.

To deal with the Twitter rejects, you could either get a new IP every second
test suite run or wait until you're allowed again. (Which might look lame at
first, though I did just that sometimes, by continuing to develop, time
passed..)

However, to shortcut this, I introduced a +SERVICE_IS_AVAILABLE+ hash. Just
set +twitter+ to +false+ once it nags again, and test against Identica only
for a while. Just make sure you re-enable it later and run your tests
against Twitter too.


= Benefits

* The bot is optimized for running permanently.
* Simple command and answer bots can be done in a matter of minutes, just by
  modifying the +@commands+ hash of +MicroBlogBot+.
  . dsifry introduced a tokenizer. You may want to play with that instead.
* The chat bot can deal with public @replies and private direct messages. It
  answers by direct messages whenever possible. -- Where direct messages are
  not possible it uses @replies.
* In case our bot gets followed by a user who has protected their updates (or
  by a user whose account got disabled by the µB service's admins between
  them following the bot and the bot following them back) the bot will handle
  the issue appropriately.
* All base classes are diligently tested and girdled with tests, therefore if
  modifications are going to break anything, you will know quickly.
  . Because of major improvements, as of Aug 11, 2009 the tests are
    incomplete now.


= Known shortcomings

* Although the bot is optimized for running permanently, there may be
  unhandled exceptions (i.e. crashes) that require manual restart. Sending a
  notification once a crash occurs would be nice. Feel free to add such.
* There is no way to delete messages. Hence, messages generated during tests
  don't get cleaned up afterwards. This could annoy followers of your bot.
  (My bot lost some of them due to test messages.) However, you could take
  your chances and run tests only when your bot's followers are offline.
* It's untested what might happen once a followee decides to change their
  nick name.
* Because of those major improvements applied in July/August 2009, as of
  Aug 11, 2009 the tests are rather incomplete now.
* All the class files are full of +FIXME+s and minor +fixme+s, and need
  tidying up.


= Contribute to the MicroBlogBot framework

The code is full of FIXMEs and the most of the tests are out of date. I'd
be delighted if you'd go over the code and fixed some FIXMEs or updated
some of the tests.

Also, if you'd like to contribute some code of your own feel free to do
so. Also, adding documentation to de code would be greatly appreciated.

Especially grateful I'd be if you'd roll the bot framework files to a
gem.


Looking forward to hear from you. Just send an e-mail.


= Authors

This micro-blogging chat bot mini-framework was developed in January/February
and July/August 2009 by Wolfram R. Sieber <Wolfram.R.Sieber@GMail.com> aka
@dagobart aka A.F. Contributions were added by David Sifry in August 2009.