]> git.somenet.org - irc/bugbot.git/blob - BotModules/Infobot.txt
GITOLITE.txt
[irc/bugbot.git] / 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 --