Composable backend selection, Telegram support, and Diataxis docs

README.md

@@ -21,6 +21,7 @@ It is built on [csp](https://github.com/point72/csp), [csp-gateway](https://gith
 `csp-bot` makes it easy to build extensible command-driven bots, and has some key features:
 
 - connect to multiple backend chat platforms from the same instance
+- supports Slack, Symphony, Discord, and Telegram
 - register custom commands across backends
 - create scheduled commands
 - create asynchronous commands

csp_bot/config/backend/discord.yaml

@@ -0,0 +1,7 @@
+# @package modules.bot.config
+discord:
+  _target_: csp_bot.DiscordConfig
+  bot_name: ${bot_name}
+  config:
+    _target_: chatom.discord.DiscordConfig
+    token: ${oc.env:DISCORD_TOKEN}

csp_bot/config/backend/slack.yaml

@@ -0,0 +1,8 @@
+# @package modules.bot.config
+slack:
+  _target_: csp_bot.SlackConfig
+  bot_name: ${bot_name}
+  config:
+    _target_: chatom.slack.SlackConfig
+    bot_token: ${oc.env:SLACK_BOT_TOKEN}
+    app_token: ${oc.env:SLACK_APP_TOKEN}

csp_bot/config/backend/symphony.yaml

@@ -0,0 +1,7 @@
+# @package modules.bot.config
+symphony:
+  _target_: csp_bot.SymphonyConfig
+  bot_name: ${bot_name}
+  config:
+    _target_: chatom.symphony.SymphonyConfig
+    bot_private_key_content: ${oc.env:SYMPHONY_BOT_KEY}

csp_bot/config/backend/telegram.yaml

@@ -0,0 +1,7 @@
+# @package modules.bot.config
+telegram:
+  _target_: csp_bot.TelegramConfig
+  bot_name: ${bot_name}
+  config:
+    _target_: chatom.telegram.TelegramConfig
+    bot_token: ${oc.env:TELEGRAM_BOT_TOKEN}

csp_bot/config/gateway/all.yaml

@@ -1,51 +1,13 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - slack
+      - discord
+      - symphony
+      - telegram
   - _self_
 
-discord_bot_name: ???
-discord_token: ???
-slack_bot_name: ???
-slack_app_token: ???
-slack_bot_token: ???
-symphony_bot_name: ???
-symphony_cert: ???
-symphony_key: ???
-telegram_bot_name: ???
-telegram_bot_token: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      discord_config:
-        _target_: csp_bot.DiscordConfig
-        bot_name: ${discord_bot_name}
-        adapter_config:
-          _target_: csp_bot.DiscordAdapterConfig
-          token: ${discord_token}
-      slack_config:
-        _target_: csp_bot.SlackConfig
-        bot_name: ${slack_bot_name}
-        adapter_config:
-          _target_: csp_bot.SlackAdapterConfig
-          app_token: ${slack_app_token}
-          bot_token: ${slack_bot_token}
-      symphony_config:
-        _target_: csp_bot.SymphonyConfig
-        bot_name: ${symphony_bot_name}
-        adapter_config:
-          _target_: csp_bot.SymphonyAdapterConfig
-          cert_string: ${symphony_cert}
-          key_string: ${symphony_key}
-      telegram_config:
-        _target_: csp_bot.TelegramConfig
-        bot_name: ${telegram_bot_name}
-        adapter_config:
-          _target_: csp_bot.TelegramAdapterConfig
-          bot_token: ${telegram_bot_token}
-
 hydra:
   job:
-    name: csp-bot--discord[${discord_bot_name}]-slack[${slack_bot_name}]-symphony[${symphony_bot_name}]-telegram[${telegram_bot_name}]
+    name: csp-bot-all

csp_bot/config/gateway/bot.yaml

@@ -0,0 +1,16 @@
+# @package _global_
+defaults:
+  - /modules
+  - _self_
+
+bot_name: CSP Bot
+
+modules:
+  bot:
+    _target_: csp_bot.Bot
+    config:
+      _target_: csp_bot.BotConfig
+
+hydra:
+  job:
+    name: csp-bot

csp_bot/config/gateway/discord.yaml

@@ -1,23 +1,10 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - discord
   - _self_
 
-bot_name: ???
-token: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      discord_config:
-        _target_: csp_bot.DiscordConfig
-        bot_name: ${bot_name}
-        adapter_config:
-          _target_: csp_bot.DiscordAdapterConfig
-          token: ${token}
-
 hydra:
   job:
-    name: csp-bot-discord[${bot_name}]
+    name: csp-bot-discord

csp_bot/config/gateway/mixed.yaml

@@ -1,33 +1,11 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - slack
+      - discord
   - _self_
 
-discord_bot_name: ???
-discord_token: ???
-slack_bot_name: ???
-slack_app_token: ???
-slack_bot_token: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      discord_config:
-        _target_: csp_bot.DiscordConfig
-        bot_name: ${discord_bot_name}
-        adapter_config:
-          _target_: csp_bot.DiscordAdapterConfig
-          token: ${discord_token}
-      slack_config:
-        _target_: csp_bot.SlackConfig
-        bot_name: ${slack_bot_name}
-        adapter_config:
-          _target_: csp_bot.SlackAdapterConfig
-          app_token: ${slack_app_token}
-          bot_token: ${slack_bot_token}
-
 hydra:
   job:
-    name: csp-bot--discord[${discord_bot_name}]-slack[${slack_bot_name}]
+    name: csp-bot-mixed

csp_bot/config/gateway/slack.yaml

@@ -1,25 +1,10 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - slack
   - _self_
 
-bot_name: ???
-app_token: ???
-bot_token: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      slack_config:
-        _target_: csp_bot.SlackConfig
-        bot_name: ${bot_name}
-        adapter_config:
-          _target_: csp_bot.SlackAdapterConfig
-          app_token: ${app_token}
-          bot_token: ${bot_token}
-
 hydra:
   job:
-    name: csp-bot-slack[${bot_name}]
+    name: csp-bot-slack

csp_bot/config/gateway/symphony.yaml

@@ -1,25 +1,10 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - symphony
   - _self_
 
-bot_name: ???
-cert: ???
-key: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      symphony_config:
-        _target_: csp_bot.SymphonyConfig
-        bot_name: ${bot_name}
-        adapter_config:
-          _target_: csp_bot.SymphonyAdapterConfig
-          cert_string: ${cert}
-          key_string: ${key}
-
 hydra:
   job:
-    name: csp-bot-symphony[${bot_name}]
+    name: csp-bot-symphony

csp_bot/config/gateway/telegram.yaml

@@ -1,23 +1,10 @@
 # @package _global_
 defaults:
-  - /modules
+  - bot
+  - /backend:
+      - telegram
   - _self_
 
-bot_name: ???
-bot_token: ???
-
-modules:
-  bot:
-    _target_: csp_bot.Bot
-    config:
-      _target_: csp_bot.BotConfig
-      telegram_config:
-        _target_: csp_bot.TelegramConfig
-        bot_name: ${bot_name}
-        adapter_config:
-          _target_: csp_bot.TelegramAdapterConfig
-          bot_token: ${bot_token}
-
 hydra:
   job:
-    name: csp-bot-telegram[${bot_name}]
+    name: csp-bot-telegram

csp_bot/tests/test_config.py

@@ -1,7 +1,7 @@
 """Tests for BotConfig and related configuration classes."""
 
 from csp_bot import BotConfig
-from csp_bot.bot_config import SlackConfig, SymphonyConfig
+from csp_bot.bot_config import SlackConfig, SymphonyConfig, TelegramConfig
 
 
 class TestBotConfig:
@@ -13,6 +13,7 @@ def test_empty_config(self):
         assert config.discord is None
         assert config.slack is None
         assert config.symphony is None
+        assert config.telegram is None
 
     def test_config_with_slack(self):
         """Test creating a BotConfig with Slack backend."""
@@ -23,6 +24,17 @@ def test_config_with_slack(self):
         assert config.slack is not None
         assert "general" in config.slack.channels
 
+    def test_config_with_multiple_backends(self):
+        """Test creating a BotConfig with several backends at once."""
+        config = BotConfig(
+            slack=SlackConfig(bot_name="Bot"),
+            telegram=TelegramConfig(bot_name="Bot"),
+        )
+        assert config.slack is not None
+        assert config.telegram is not None
+        assert config.discord is None
+        assert config.symphony is None
+
 
 class TestBackendConfig:
     """Tests for backend configuration classes."""

docs/wiki/Backends.md

@@ -0,0 +1,65 @@
+`csp-bot` connects to chat platforms through `csp` adapters, wrapped by [`chatom`](https://github.com/Point72/chatom) for a unified message, user, and channel model.
+This page is the reference for which backends exist, how to authenticate them, and what each one can do.
+
+## Supported backends
+
+| Backend  | Adapter                                                                                     | Support   |
+| :------- | :------------------------------------------------------------------------------------------ | :-------- |
+| Slack    | [point72/csp-adapter-slack](https://github.com/point72/csp-adapter-slack)                   | Official  |
+| Symphony | [point72/csp-adapter-symphony](https://github.com/point72/csp-adapter-symphony)             | Official  |
+| Discord  | [csp-community/csp-adapter-discord](https://github.com/csp-community/csp-adapter-discord)   | Community |
+| Telegram | [csp-community/csp-adapter-telegram](https://github.com/csp-community/csp-adapter-telegram) | Community |
+
+The adapters are optional dependencies — install the ones you need:
+
+```bash
+pip install csp-adapter-slack csp-adapter-telegram
+```
+
+## Credentials
+
+Each backend reads its credentials from environment variables, matching the names used by the built-in `backend` configs.
+
+| Backend  | Environment variables                | `chatom` config field     |
+| :------- | :----------------------------------- | :------------------------ |
+| Slack    | `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN` | `bot_token`, `app_token`  |
+| Discord  | `DISCORD_TOKEN`                      | `token`                   |
+| Symphony | `SYMPHONY_BOT_KEY`                   | `bot_private_key_content` |
+| Telegram | `TELEGRAM_BOT_TOKEN`                 | `bot_token`               |
+
+To set a field other than the default (for example, a Symphony key on disk rather than in the environment), override it in your own config:
+
+```yaml
+# @package modules.bot.config
+symphony:
+  config:
+    bot_private_key_path: /path/to/bot-key.pem
+    bot_certificate_path: /path/to/bot-cert.pem
+```
+
+For platform-specific setup of tokens and bot accounts, follow the adapter guides:
+
+- [Slack Adapter setup](https://github.com/Point72/csp-adapter-slack/wiki/Setup)
+- [Symphony Adapter setup](https://github.com/Point72/csp-adapter-symphony/wiki/Setup)
+- [Discord Adapter setup](https://github.com/csp-community/csp-adapter-discord/wiki/Setup)
+- [Telegram Adapter](https://github.com/csp-community/csp-adapter-telegram/wiki)
+
+## Feature matrix
+
+| Backend  | Public Room | Private Room | User-initiated IM | Threads | Reactions | Attachments |
+| :------- | :---------- | :----------- | :---------------- | :------ | :-------- | :---------- |
+| Slack    | X           | X            | X                 | X       | X         |             |
+| Symphony | X           | X            | X                 |         |           |             |
+| Discord  | X           | X            | X                 | X       | X         |             |
+| Telegram | X           | X            | X                 |         |           |             |
+
+## Response formatting
+
+Response formatting varies between backends, and built-in commands render their output in the right dialect for each one.
+
+| Backend  | Format           | Tables | Images |
+| :------- | :--------------- | :----- | :----- |
+| Slack    | Minimal Markdown | No     | Yes    |
+| Symphony | Custom HTML      | Yes    | Yes    |
+| Discord  | Minimal Markdown | No     | Yes    |
+| Telegram | HTML             | No     | Yes    |

docs/wiki/Commands.md

@@ -0,0 +1,26 @@
+`csp-bot` ships a small set of built-in commands and makes it easy to add your own.
+
+Because chat platforms each have their own command registration and syntax, `csp-bot` adopts an IRC-like `/`-initiated command syntax.
+On most platforms you interact with the bot by tagging it and then giving a command:
+
+```raw
+@CSP Bot /help
+```
+
+Most commands accept their own arguments, and many can be redirected to another channel by appending `/channel <channel name>`.
+
+## Built-in commands
+
+| Name     | Command     | Description                                                    |
+| :------- | :---------- | :------------------------------------------------------------- |
+| Help     | `/help`     | Get help with bot commands. Syntax: `/help [command]`          |
+| Echo     | `/echo`     | Echo a message. Syntax: `/echo <message> [/channel <channel>]` |
+| Schedule | `/schedule` | Schedule a command to run later or on a cron schedule          |
+| Status   | `/status`   | Display system status. Syntax: `/status [/channel <channel>]`  |
+
+Which commands a bot exposes is controlled by configuration; see [Configuration](Configuration).
+
+## More commands
+
+Community-supported commands live in [csp-community/csp-bot-commands](https://github.com/csp-community/csp-bot-commands).
+To write your own, see [Writing Commands](Writing-Commands).