My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# Zulip Echo Bot with Verbose Logging
2
3An enhanced echo bot that demonstrates the Zulip bot framework with comprehensive logging and CLI configuration. The bot responds to direct messages and mentions by echoing back the message content, with detailed logging at every step.
4
5## Features
6
7- **Responds to direct messages and @mentions in channels**
8- **Comprehensive logging** with multiple verbosity levels
9- **Command-line interface** with help and configuration options
10- **Detailed message tracing** for debugging
11- **Structured logging** using the OCaml logs library
12- **Built-in commands**: help, ping, and echo
13- **Avoids infinite loops** by ignoring its own messages
14
15## Prerequisites
16
171. A Zulip account and server
182. A bot user created in Zulip (Settings → Bots → Add a new bot)
193. OCaml and dependencies installed
20
21## Setup
22
23### 1. Create a Bot in Zulip
24
251. Go to your Zulip settings
262. Navigate to "Bots" section
273. Click "Add a new bot"
284. Choose "Generic bot" type
295. Give it a name (e.g., "Echo Bot")
306. Note down the bot email and API key
31
32### 2. Configure Authentication
33
34Create a `~/.zuliprc` file with your bot's credentials:
35
36```ini
37[api]
38email=echo-bot@your-domain.zulipchat.com
39key=your-bot-api-key
40site=https://your-domain.zulipchat.com
41```
42
43Replace the values with your actual bot credentials.
44
45### 3. Build the Bot
46
47```bash
48# From the zulip directory
49dune build
50
51# Or build just the echo bot
52dune build zulip/examples/echo_bot.exe
53```
54
55## Running the Bot
56
57### Basic Usage
58
59```bash
60# Show help and available options
61dune exec echo_bot -- --help
62
63# Run with default settings (info level logging)
64dune exec echo_bot
65
66# Run with verbose logging (shows all info messages)
67dune exec echo_bot -- -v
68
69# Run with debug logging (shows everything)
70dune exec echo_bot -- -vv
71
72# Use custom config file
73dune exec echo_bot -- -c /path/to/bot.zuliprc
74
75# Combine options
76dune exec echo_bot -- -vv -c ~/my-bot.zuliprc
77```
78
79### Example Output with Different Verbosity Levels
80
81**Default (no flags) - Info level:**
82```
83echo_bot: [INFO] Starting Zulip Echo Bot
84echo_bot: [INFO] Log level: Info
85echo_bot: [INFO] =============================
86
87echo_bot: [INFO] Echo bot is running!
88echo_bot: [INFO] Send a direct message or mention @echobot in a channel.
89echo_bot: [INFO] Commands: 'help', 'ping', or any message to echo
90echo_bot: [INFO] Press Ctrl+C to stop.
91```
92
93**Verbose (-v) - Info level with more details:**
94```
95echo_bot: [INFO] Starting Zulip Echo Bot
96echo_bot: [INFO] Log level: Info
97echo_bot: [INFO] =============================
98
99echo_bot: [INFO] Loaded authentication for: echo-bot@your-domain.zulipchat.com
100echo_bot: [INFO] Server: https://your-domain.zulipchat.com
101echo_bot: [INFO] Bot identity created: Echo Bot (echo-bot@your-domain.zulipchat.com)
102echo_bot: [INFO] Echo bot is running!
103echo_bot: [INFO] Processing message with 12 fields
104echo_bot: [INFO] Message metadata: type=private, sender=John Doe (john@example.com), id=12345
105echo_bot: [INFO] Processing message from John Doe (ID: 123): Hello bot!
106echo_bot: [INFO] Sending private reply: Echo from John Doe: Hello bot!
107```
108
109**Debug (-vv) - Full debug output:**
110```
111echo_bot: [INFO] Starting Zulip Echo Bot
112echo_bot: [DEBUG] Creating Zulip client
113echo_bot: [DEBUG] Creating bot storage for echo-bot@your-domain.zulipchat.com
114echo_bot: [DEBUG] Creating bot handler
115echo_bot: [DEBUG] Creating bot runner
116echo_bot: [DEBUG] Received message for processing
117echo_bot: [DEBUG] Extracted field content: Hello bot!
118echo_bot: [DEBUG] Extracted field sender_email: john@example.com
119echo_bot: [DEBUG] Extracted field sender_full_name: John Doe
120echo_bot: [DEBUG] Extracted field type: private
121echo_bot: [DEBUG] Extracted field sender_id: 123
122echo_bot: [DEBUG] Extracted field id: 12345
123echo_bot: [DEBUG] No bot mention to remove
124echo_bot: [DEBUG] Generated response: Echo from John Doe: Hello bot!
125```
126
127## Testing the Bot
128
129### Direct Message Test
1301. Open Zulip
1312. Send a direct message to your bot
1323. Type: `Hello bot!`
1334. The bot should respond: `Echo from [Your Name]: Hello bot!`
134
135### Channel Mention Test
1361. In any channel, type: `@echobot Hello everyone!`
1372. The bot should respond: `Echo from [Your Name]: Hello everyone!`
138
139### Special Commands
140
141- **`help`** - Get usage information
142- **`ping`** - Bot responds with "Pong! 🏓"
143- Any other text - Bot echoes it back
144
145## How It Works
146
147The echo bot:
1481. **Initializes logging** based on CLI verbosity flags
1492. **Connects to Zulip** using the real-time events API
1503. **Listens for messages** where it's mentioned or direct messaged
1514. **Logs message details** at various verbosity levels
1525. **Extracts fields** with debug logging for each field
1536. **Processes content** and removes bot mentions
1547. **Generates responses** with appropriate logging
1558. **Sends back echo** with type-appropriate reply
1569. **Ignores own messages** to prevent loops
157
158## Code Structure
159
160- **Logging Setup**: Creates a custom log source `echo_bot` for structured logging
161- **Bot Handler Module**: Implements the `Bot_handler.S` signature with comprehensive logging
162- **Field Extraction**: Helper functions with debug logging for each field
163- **Message Processing**: Detailed logging of message metadata and content
164- **Response Generation**: Logs response creation and type determination
165- **CLI Interface**: Cmdliner-based argument parsing with help text
166- **Verbosity Control**: Maps CLI flags to log levels (Info/Debug)
167- **Error Handling**: Catches and logs exceptions with backtraces
168
169## Customization
170
171You can modify the echo bot to:
172- Add more commands (parse for specific keywords)
173- Store conversation history (use `Bot_storage`)
174- Integrate with external APIs
175- Format responses differently
176- Add emoji reactions
177
178## Troubleshooting
179
180### Bot doesn't respond
181- Check that the bot is actually running (look for console output)
182- Verify the bot has permissions in the channel
183- Check that you're mentioning the bot correctly (@botname)
184- Look for error messages in the console
185
186### Authentication errors
187- Verify your `.zuliprc` file has the correct credentials
188- Ensure the API key hasn't been regenerated
189- Check that the bot user is active in Zulip
190
191### Build errors
192- Make sure all dependencies are installed: `opam install zulip zulip_bot eio_main`
193- Clean and rebuild: `dune clean && dune build`
194
195## Next Steps
196
197Once you have the echo bot working, you can:
1981. Extend it with more complex command parsing
1992. Add persistent storage for user preferences
2003. Integrate with external services
2014. Build more sophisticated bots using the same framework
202
203## Example Extensions
204
205### Adding a Command Parser
206```ocaml
207let parse_command content =
208 match String.split_on_char ' ' content with
209 | "!echo" :: rest -> Some ("echo", String.concat " " rest)
210 | "!reverse" :: rest -> Some ("reverse", String.concat " " rest)
211 | _ -> None
212```
213
214### Using Bot Storage
215```ocaml
216(* Store user preferences *)
217let _ = Bot_storage.put storage ~key:"user_prefs" ~value:"{...}" in
218
219(* Retrieve later *)
220let prefs = Bot_storage.get storage ~key:"user_prefs" in
221```
222
223### Sending to Specific Channels
224```ocaml
225Bot_handler.Response.ChannelMessage {
226 channel = "general";
227 topic = "Bot Updates";
228 content = "Echo bot is online!";
229}
230```