Rave: Google Wave Robots in Ruby

Google Wave
There's been a lot of talk about Google Wave lately, so what's Wave all about? Wave is a protocol, that extends XMPP. In practice, it contains elements of email, instant messaging and threaded discussion. Oh, and document management. Yeah, it seems to do just about everything. The problem with that is that it makes it really hard to describe. It always sounds like it is trying to be everything - to solve every problem. But really, it's all about online collaborative communication. Here, take a look at the demo from the Google I/O keynote this year. It makes more sense once you've seen it in action.

Wave is in an alpha release right now. As far as I know, only the attendees of Google I/O have accounts on the sandbox. Hopefully that will change before too long. Google's only saying that it will be released "before the end of the year" right now. In the mean time, there's a ton of information on the main Wave site, the wave protocol site, and the Google blog.

Some Terminology
There are three primary components to Google Wave: waves, wavelets and blips. Waves are the central component. Think of a wave as a conversation. A wave has one or more wavelets, which are sort of like sub-conversations, or threads of discussion under a conversation. Finally, blips are the actual messages in the discussion, so a wavelet can contain one or more blips. There's a better description of these terms in the protocol spec.

Wasn't This Post Supposed to be About Robots?
Here's what's really cool about Google Wave: there's an API for building extensions for it. There are three things that a developer can do with Wave: embed a wave on a website, build gadgets to be embedded in a wave, and build robots. There's a discussion on each of these on the Wave API site. My focus here is going to be on robots, because let's face it, robots are awesome.

Robots are automated participants in a wave. They can do basically anything that a human participant can do: they can read the conversation, add to the conversation, and they can edit a conversation. So you can, for example, build a spell checker that reads everthing you post to a wave and edits it to change typos as you type. There are some cool examples of things you can do with robots in the Google I/O keynote demo.

Google Wave Robot Tools
Google released two toolkits for building robots, one in Java, and one in Python. Furthermore, there is currently a restriction in place that requires robots to live on Google App Engine. So that means that a robot has to either be in Python or Java... or some other language implemented on the JVM. Happily, for those of us who prefer to code in Ruby, we've got JRuby. Now all we need is an implementation of the robot client API in Ruby.

Rave: A Google Wave robot client framework for Ruby
There are several parallel efforts to create a Ruby implementation of the robot API. The rest of this post is going to focus on Rave, but I just wanted to link to the other implementations that I'm aware of:

Both Rave and Google Wave are super-alpha. There are a lot of things in the protocol that aren't implemented in Rave yet. And the protocol is changing, so the things that are implemented are likely to break at some point. I will try to keep up, but if you notice anything broken, or if you have a need for something that isn't implemented yet, shoot me an email: diminish7 at gmail dot com.

Okay. You've been warned.

The Basics
Since Google currently requires that all robots run on App Engine, this tutorial assumes you are using JRuby. You should have JRuby already installed, and you should have the App Engine SDK installed. You can find more information on JRuby at http://jruby.org/, and you can find more information about the App Engine SDK at http://code.google.com/appengine/downloads.html

What We're Going to Build
I hate it when people yell in writing. I want a robot that will moniter discussions and tone down any yelling. So, for example, this robot will turn a post like "I'M NOT YELLING!!!!" into "I'm not yelling." The full source for this robot is in git under examples/appropriate-casey/. Here's how you build it yourself:

Install Rave

sudo jruby -S gem install rave

Start a new Rave Project
Rave comes with a "rave" executable that, among other things, sets up the project structure for you. Setting up a new project looks like this:

jruby -S rave create [robot_name] [options]

The options include profile_url and image_url, which will set the URL for the robot's profile and avatar, respectively. Here's how the example project "appropriate casey" was set up:

jruby -S rave create appropriate-casey

I haven't bothered to create an avatar for casey, but if I had, I would instead have done:

jruby -S rave create appropriate-casey image_url=http://myimageurl/avatar.png

This will stub out a project called "appropriate-casey". It automatically creates a robot class AppropriateCasey, creates the config files for both Rack and Warbler, and creates the appengine-web.xml file that App Engine will need. For the App Engine file, it assumes that the App Engine project name is the same as the robot's name. So in this case, the application name is appropriate-casey, which means I have to have the URL http://appropriate-casey.appspot.com. If you name your robot something different than the App Engine application ID, just change the line in appengine-web.xml.

Build your robot!
The robot.rb file that Rave created contains a class that extends Rave::Models::Robot. All of the logic needed for your robot to talk to App Engine is included in Rave::Models::Robot, so all you really need to do now is define your robot's event listeners. Here is a list of the events that Google Wave can send your robot:
To add a listener to your robot that will respond to a given event, just define a method with the lower-case version of the event name, that accepts an event and a context. So, I want appropriate-casey to do something whenever a document is changed (the DOCUMENT_CHANGED event), so I add the following method to my robot:

def document_changed(event, context)
# Do some stuff

The Event object contains the following properties:
  • type (the type of event, "DOCUMENT_CHANGED" in this case)
  • timestamp (the timestamp that the event occurred)
  • modified_by (the user ID of the user who modified the document)
  • properties (varies by event type, but this will be a range of affected text in this case)
The Context object contains the following properties:
  • waves (a hash - the keys are the wave IDs, and the values are the waves)
  • wavelets (a hash - the keys are the wavelet IDs, and the values are the wavelets)
  • blips (a hash - the keys are the blip IDs, and the values are the blips)
  • operations (an array of operations)
See the Google Wave protocol documentation for definitions of each of these things...

So, with Appropriate Casey, I want to create a robot that looks for people "shouting" in Waves. To do this, I just create a document_changed method in my robot that looks something like this:

def document_changed(event, context)
unless event.modified_by == "appropriate-casey@appspot.com" ||
event.modified_by == "spelly@gwave.com"
context.blips.values.each do |blip|
if blip.content
new_sentence = true
blip.content.length.times do |index|
range = index..index+1
char = blip.content[index, 1]
if char =~ /[A-Z]/ && !new_sentence
blip.set_text_in_range(range, char.downcase)
elsif char =~ /[a-z]/ && new_sentence
blip.set_text_in_range(range, char.upcase)
elsif char == "!"
if new_sentence
blip.set_text_in_range(range, ".")
new_sentence = (char =~ /\.!?/ || (char =~ /\s/ && new_sentence))

For simplicity's sake, I'm brute-forcing this a bit. It would be better to look at the event properties and just change the range of text that the event is telling me about.

So that's it, my robot is now ready to go: just 17 lines of code.

Packaging for deploy
I'm assuming that you have an application set up on App Engine already. Again, for the time being, all robots have to be on App Engine to work with Google Wave.

First of all, we need to turn our project into the correct format for App Engine. There is a utility
in the "rave" executable for this, so from your robot's top-level folder, run:

jruby -S rave war

This is basically just a wrapper around the warbler gem, but with some additional cleanup to get things in the right format for App Engine. For example, the complete JRuby jar is too large for App Engine, so Rave breaks it up into two jars. Once you've run "rave war", you'll see a tmp/ folder, and a .war file. You can ignore the .war file, as App Engine needs the unpacked version. The tmp/war folder is what will get deployed.

The worst part about App Engine is testing...

Rave includes a "server" command that starts up Rack for your application, but that is of limited use, since App Engine has many App Engine-specific issues. Better to use the App Engine SDK (which is still not a perfect match to the deployed environment, but it's better). The App Engine SDK comes with a dev_server command. From your project directory run:

path/to/appengine_sdk/bin/dev_server tmp/war

This will start the development server on port 8080. You can now hit the following three URLs:
The first two are GETs, but the last one requires a POST. See the Google Wave protocol for the expected body of the POST if you want to test locally.

Use the App Engine SDK to deploy. From your project directory run:

path/to/appengine_sdk/bin/appcfg update tmp/war

Using the Robot
From a Google Wave client, start a new wave, and invite your robot as a participant. Your robot's user name will be [robot_name]@appspot.com. So Casey is at appropriate-casey@appspot.com.

The End
That's it. You now have a working robot! Enjoy!