Skip to main content

mts1b-discordbot

Discord community-support bot. Chat-with-docs powered by mts1b-llm + Algolia retrieval. Routes by channel, manages roles, handles auto-moderation.

Repo: github.com/MTS1B/mts1b-discordbot Layer: 7 Wave: 3 (months 8-12) Depends on: foundation, platform, llm, discord.py Audience: community.mts1b.investmentparadisellc.com Discord users

What it is​

A Discord bot that:

  1. Answers questions in #help using docs as context (RAG over Algolia index)
  2. Manages roles (auto-grant based on GitHub OAuth)
  3. Cross-posts release announcements + drift alerts
  4. Auto-moderates spam + off-topic posts
  5. Routes user-reported issues to GitHub via mts1b-githubbot

Channels supported​

ChannelBot role
#announcementspost-only (releases, security advisories)
#generallisten, occasionally chime in if directly mentioned
#helpactive — RAG-based answers, deflect to docs
#dev-{repo}answer dev questions per-repo (15 channels at launch)
#showcaseencourage + react
#pluginshelp with mts1b-pluginsdk
#offtopicinactive

Chat-with-docs​

User in #help: "How do I write a custom factor?"

Bot (after ~3s):
  Great question! Writing a custom factor:

  1. Define a function that takes a UniversePanel and **params, returns
     a (T, A) ndarray.
  2. Decorate with @register("f_your_name").
  3. The name must start with "f_".

  Example:
  ```python
  from mts1b_quantkit.factors import register, zscore_cross_sectional

  @register("f_my_momentum")
  def f_my_momentum(panel, h=21):
      return zscore_cross_sectional(panel.close[-1] / panel.close[-h] - 1)

Full guide: https://docs.mts1b.investmentparadisellc.com/docs/concepts/factor-system

Want to backtest it? See: https://docs.mts1b.investmentparadisellc.com/docs/tutorials/custom-strategy


The RAG flow:

1. Embed user question
2. Retrieve top 5 docs sections via Algolia (`O23N9EQJYS`, index `MTS1B documentation`)
3. Send retrieved context + question to `mts1b-llm` persona `community_helper`
4. Post answer with citations (links to the actual doc pages)

## Module layout

mts1b_discordbot/ ├── bot/ │ ├── client.py # discord.py client │ ├── events/ │ │ ├── message.py │ │ ├── reaction.py │ │ └── member_join.py │ └── slash_commands/ │ ├── ask.py │ ├── search_docs.py │ └── report_bug.py ├── rag/ │ ├── algolia_retriever.py │ └── prompt_builder.py ├── roles/ │ ├── github_oauth_mapper.py # GitHub contributor → Discord role │ └── policies.py ├── moderation/ │ ├── automod.py │ └── escalation.py ├── routing/ │ ├── crosspost_releases.py # GH release → #announcements │ └── drift_alerts.py # mts1b-research drift → #announcements └── governor/ └── budget.py # daily LLM budget cap per channel


## Slash commands

/ask QUESTION ← Pose a question; bot answers from docs /search QUERY ← Algolia search; bot lists top 5 doc links /report-bug TITLE ← Opens a GitHub issue from a thread /learn TOPIC ← Suggests learning order through docs /roles ← Show current roles + how to get more


## Role system

Auto-grant via GitHub OAuth:

| GitHub status | Discord role |
|---|---|
| Member of MTS1B org | `@member` |
| Has merged ≥ 1 PR | `@contributor` |
| Maintainer (CODEOWNERS) | `@maintainer` |
| GitHub Sponsor | `@sponsor` (gold) |
| Has merged ≥ 10 PRs | `@core-contributor` |

Linking: user runs `/link-github` → OAuth flow → role granted within 5 seconds.

## Cross-posts

Two cross-post sources:

| Source | Trigger | Destination | Format |
|---|---|---|---|
| GitHub Releases | new release published | `#announcements` | embed with changelog excerpt |
| `mts1b-research/drift` | drift_zscore < -1.5 | `#announcements` | warn + link to drift dashboard |
| Security advisory | new GHSA published | `#announcements` (pinned 7d) | embed with severity |

## Auto-moderation

Light-touch:

| Trigger | Action |
|---|---|
| Spam (rapid identical messages) | warn + 1h timeout |
| External link from new account | drop + ask for context |
| Off-topic financial advice request | redirect to docs disclaimer |
| Crypto pump-and-dump shilling | delete + ban |

All escalations log to `mts.v1.discordbot.moderation.*` for audit.

## Budget

```yaml title="mts1b-discordbot/config.yaml"
budget:
  daily_usd: 3.0
  per_channel_daily_cap_usd: 1.0
  cooldown_per_user_seconds: 30   # rate-limit /ask per user

When daily budget exhausts, the bot falls back to keyword-search responses (no LLM).

Privacy​

  • Conversation history is NOT stored beyond the conversation context window.
  • /ask queries are logged anonymously for usage stats; no user IDs.
  • The bot does NOT read private DMs (Discord doesn't allow + we don't ask for the scope).

Build + test​

pip install -e ".[dev]"
pytest -m unit
DISCORD_BOT_TOKEN=... pytest -m live --channel-id=...

Roadmap​

VersionItems
0.1 (Wave 3)Chat-with-docs, role mgmt, cross-posts, automod
0.2 (Wave 3)Code-example execution (sandboxed)
0.3Voice channel support (TTS answers)
1.0 (LTS)Stable bot persona

See also​