BotModules/Infobot.txt

   1 The Infobot Protocol
   2 ====================
   3
   4 Reverse engineered from infobot 0.45.3 by Ian Hickson.
   5
   6
   7 QUERY
   8 -----
   9
  10 If a bot is asked something by a user and does not know the answer, it
  11 may send queries to all the bots it knows. Queries must be in private
  12 messages and should have the following form:
  13
  14    :INFOBOT:QUERY <target> subject
  15
  16 ...where "target" is the name of the user who sent the query in the
  17 first place, and "subject" is the question that was asked.
  18
  19 In reality, "target" may be any string of non-whitespace character, so
  20 it could be used as an internal ID.
  21
  22 A bot receiving a QUERY message must not try to contact the user given
  23 by "target" (that string should be treated as opaque) and must not
  24 make any assumptions about the "subject" string (it could contain
  25 *anything*, including high bit characters and the works).
  26
  27 It is an error for the "subject" string to contain either "=is=>" or
  28 "=are=>". Receiving bots may ignore this error, however.
  29
  30 Bot authors should carefully consider the potential for cascades
  31 before writing bots that chain QUERY messages. (As in, send out QUERY
  32 messages if they are unable to respond to a QUERY message themselves).
  33 In general, this is not a recommended behaviour.
  34
  35 Bot authors are urged to write protection into their bots to avoid
  36 being affected by poorly written bots that cause cascades.
  37
  38
  39 REPLY
  40 -----
  41
  42 Upon receiving a QUERY message, a bot may, if it has information on
  43 "subject", opt to send a private message back to the originating bot
  44 in the form of a REPLY message. Bots must not send unsolicited REPLY
  45 messages. The form of the REPLY message is:
  46
  47    :INFOBOT:REPLY <target> subject =database=> object
  48
  49 ...where "target" is the string of the same name from the original
  50 QUERY message, "subject" is the second string from the original QUERY
  51 message, "database" is one of "is" or "are" depending on the whether
  52 "subject" is determined to be singular or plural respectively, and
  53 "object" is the string that should be assumed to be the answer to
  54 "subject". The string may contain special formatting codes, these are
  55 described below.
  56
  57 Upon receiving a REPLY message, bots should first check that they are
  58 expecting one. If they are, the user identified by the "target" string
  59 should be contacted and given the information represented by the
  60 "object" string. (Remember that the "target" string need not actually
  61 be the nick of the original user; it could be an internal key that
  62 indirectly identifies a user.)
  63
  64 Bots should carefully check the integrity and authenticity of the
  65 "target" string, and must check that "database" is one of "is" or
  66 "are". The "subject" string ends at the first occurance of either
  67 "=is=>" or "=are=>". It is *not* an error for the "object" string to
  68 contain either of those substrings.
  69
  70 Bots may opt to store the information given by a REPLY request so that
  71 future questions may be answered without depending on other bots.
  72
  73 It is suggested that bots credit which bot actually knew the
  74 information when reporting back to the user.
  75
  76
  77 DUNNO
  78 -----
  79
  80 (This is not part of the original infobot protocol. And is, as of
  81 2002-02-05, only supported by the mozbot2 Infobot module.)
  82
  83 Upon receiving a QUERY message, a bot may, if it has no information on
  84 the "subject" in question, reply with a DUNNO message. This message
  85 has basically the same form as the QUERY message:
  86
  87    :INFOBOT:DUNNO <target> subject
  88
  89 The DUNNO message indicates that the bot is not aware of the answer to
  90 the question, but would like to be informed of the answer, should the
  91 first bot ever find out about it. The "target" string should, as with
  92 the QUERY string, be considered opaque.
  93
  94 Upon receiving a DUNNO message, there are several possible responses.
  95 If the bot is aware of the answer to "subject", then it should treat
  96 the DUNNO message as if it was a QUERY message (typically resulting in
  97 a REPLY message). This can occur if, for example, another bot has sent
  98 a REPLY to the original QUERY before this bot has had the chance to
  99 send the DUNNO message.
 100
 101 If the first bot still doesn't know the answer, however, it may store
 102 the DUNNO request internally. If, at a future time, the bot is
 103 informed (either directly by a user or through a REPLY message) about
 104 the answer to "subject", then it may send a REPLY message to the bot
 105 that sent the DUNNO request, informing the bot of the value it learnt.
 106
 107
 108 SPECIAL STRINGS
 109 ---------------
 110
 111 The "object" string in the REPLY message may contain several special
 112 flags.
 113
 114    $who
 115    If the string contains the string "$who" then, when the string is
 116    given to the user, it should be replaced by the name of the user.
 117
 118    |
 119    Multiple alternative replies may be encoded in one reply, those
 120    should be separated by a vertical bar.
 121
 122    <reply>
 123    If the string is prefixed by "<reply>" then the string should not
 124    be prefixed by "subject is" or "subject are" as usual.
 125
 126    <action>
 127    The string should be returned via a CTCP ACTION.
 128
 129    <alias>
 130    The string should be taken as the name of another entry to look up.
 131
 132
 133 EXAMPLES
 134 --------
 135
 136 In these examples, A, B and C are bots, and x, y and z are people.
 137
 138 The first example shows a simple case of one bots asking two other
 139 bots for help, one of which gives a reply and the other of which says
 140 it has no idea.
 141
 142   +-------- originator of private message
 143   |
 144   |    +--- target of private message
 145   |    |
 146   V    V
 147   z -> A: what is foo?
 148   A -> z: I have no idea.
 149   A -> B: :INFOBOT:QUERY <z> foo
 150   A -> C: :INFOBOT:QUERY <z> foo
 151   B -> A: :INFOBOT:REPLY <x> foo =is=> bar
 152   C -> A: :INFOBOT:DUNNO <C> foo
 153   A -> x: B knew: foo is bar
 154   A -> C: :INFOBOT:REPLY <C> foo =is=> bar
 155
 156 Note how the DUNNO in this case comes after the REPLY and thus is
 157 immediately answered.
 158
 159 The next example uses <alias>. One bot knows the answer to the
 160 question as an alias to another word, but when the original bot asks
 161 about _that_ word, it is the second bot that can help.
 162
 163   z -> A: what is foo?
 164   A -> z: I have no idea.
 165   A -> B: :INFOBOT:QUERY <z> foo
 166   A -> C: :INFOBOT:QUERY <z> foo
 167   B -> A: :INFOBOT:REPLY <x> foo =is=> <alias>bar
 168   C -> A: :INFOBOT:DUNNO <C> foo
 169   A -> B: :INFOBOT:QUERY <z> bar
 170   A -> C: :INFOBOT:QUERY <z> bar
 171   A -> C: :INFOBOT:REPLY <C> foo =is=> <alias>bar
 172   B -> A: :INFOBOT:DUNNO <B> bar
 173   C -> A: :INFOBOT:REPLY <x> bar =is=> baz
 174   A -> z: C knew: bar is baz
 175   A -> B: :INFOBOT:REPLY <B> bar =is=> baz
 176
 177 Note how the credit actually goes to the second bot. A better bot
 178 might remember all the bots involved and credit all of them. A better
 179 bot might also remember what the original question was and reply "foo
 180 is baz" instead of "bar is baz".
 181
 182 Next we have some examples of special codes. If we have:
 183
 184   foo is bar|<alias>baz|<reply>foo to you too|<action>foos|$who
 185   baz is foo
 186
 187 ...then the following are valid responses when asked about foo:
 188
 189   <A> foo is bar
 190   <A> baz is foo
 191   <A> foo to you too
 192   * A foos
 193   <A> foo is z
 194
 195 -- end --