FernandoJVideiraandClaude Opus 5.5
7ae1fa5747
/tldr [since] summarizes the messages in the channel it is run in that the caller has not been summarized yet, using a small local model on Ollama, and replies ephemerally. The answer streams into the reply as it is written. - Per-user, per-channel cursor (tldr_cursors) so each run picks up where the last left off; `since:` (e.g. 6h, 2d, max 7d) peeks without moving it. First use covers the last 24h, and a stale cursor never reaches back more than 7 days. - Only summarizes channels both the caller and the bot can read. - The transcript drops bots, system messages, reactions and filler, turns links, GIFs, images and files into short tags ([link: site], [image], [file: name], preview titles), marks replies, and writes a date marker where the chat paused for 3h or more so the model can keep topics apart. - The prompt asks for one bullet per conversation, oldest first, with a worked example; it was tuned against a synthetic chat and a real export with qwen3:4b-instruct-2507 (the default model). - One model call at a time across the bot, one /tldr per user. - docker-compose: Ollama service (CPU only, 8g memory cap: 6g killed the runner mid-request), model pull on startup. Needs the tldr_cursors migration (velox-dashboard-api 000016). Co-Authored-By: Claude Opus 5.5 <[email protected]>
136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# Velox Bot
|
|
|
|
A Discord bot written in Go with a PostgreSQL backing store.
|
|
|
|
It currently includes:
|
|
|
|
- Fun commands (`/ping`, `/joke`, `/dice`, `/rps`, …)
|
|
- Leveling system (opt-in per server via `/slvl toggle`)
|
|
- Meeting rooms (voice lobby → auto-created temporary voice channels)
|
|
- Scheduling (1:1 sessions with DM invites + reaction-based accept/decline/reschedule)
|
|
- Projects (list/create projects + helpers)
|
|
- Music (Lavalink-powered `/play`, `/queue`, `/volume`)
|
|
- Twitch live notifications (per-guild `/config` setup)
|
|
- Welcome messages, DMs, and default role assignment (per-guild `/config` setup)
|
|
- Focused moderation tools (`/moderation purge|timeout|untimeout|kick|ban|unban|slowmode`)
|
|
- Server logging system (edits/deletes/joins/leaves/roles/ban/kick/mod actions)
|
|
|
|
When the bot is added to a new server for the first time, toggleable systems are defaulted to **disabled** and a setup DM is sent to the inviter (or server owner fallback) with enable instructions.
|
|
|
|
## Requirements
|
|
|
|
- Go (see `go.mod`)
|
|
- PostgreSQL 16+ (or use the provided `docker-compose.yml`)
|
|
- (Optional) [Air](https://github.com/air-verse/air) for live reload during development
|
|
- (Optional) Lavalink if you want music commands
|
|
|
|
## Configuration
|
|
|
|
The app loads environment variables from `.env` (see `internal/config/config.go`).
|
|
|
|
Required:
|
|
|
|
- `BOT_TOKEN`: Discord bot token
|
|
- `APP_ID`: Discord application ID
|
|
- `GUILD_ID`: Target guild/server ID (commands are registered per-guild)
|
|
- `DB_HOST`: Postgres connection string (pgx), e.g. `postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable`
|
|
|
|
Optional (music):
|
|
|
|
- `LAVALINK_HOST`: Lavalink WebSocket/HTTP host (depends on your Lavalink setup)
|
|
- `LAVALINK_PASSWORD`: Lavalink password
|
|
|
|
Optional (Twitch live notifications):
|
|
|
|
- `TWITCH_CLIENT_ID`: Twitch Client ID used to query live status
|
|
|
|
Optional (`/tldr` summaries, needs an [Ollama](https://ollama.com) server; the compose file includes one):
|
|
|
|
- `OLLAMA_HOST`: Ollama base URL (default `http://ollama:11434`)
|
|
- `TLDR_MODEL`: Ollama model tag (default `qwen3:4b-instruct-2507-q4_K_M`)
|
|
- `TLDR_THREADS`: CPU threads the model may use (default `6`; keep it well below your core count)
|
|
|
|
## Database setup
|
|
|
|
If you use the compose file:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Then apply the schema:
|
|
|
|
```bash
|
|
psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql
|
|
```
|
|
|
|
## Run
|
|
|
|
Plain Go:
|
|
|
|
```bash
|
|
go run .
|
|
```
|
|
|
|
With live reload (Air):
|
|
|
|
```bash
|
|
air
|
|
```
|
|
|
|
If you use `just`, a small workflow is included:
|
|
|
|
```bash
|
|
just up # start postgres
|
|
just start # start postgres + run air
|
|
just down # stop postgres
|
|
```
|
|
|
|
## Commands (high-level)
|
|
|
|
- **Fun**
|
|
- `/ping`, `/joke [type]`, `/coinflip`, `/dice <expr>`
|
|
- `/rps <hand>`, `/rpsstats`, `/rpsleaderboard` (server only)
|
|
- **Help**
|
|
- `/help` (sends a DM with command reference)
|
|
- **Leveling**
|
|
- `/slvl ...` admin/config
|
|
- `/rank`, `/leaderboard`, `/rewards`
|
|
- **Meetings** (**Manage Server**)
|
|
- `/meeting set-lobby`, `/meeting lock`, `/meeting lock-private`, `/meeting unlock`, `/meeting invite`, `/meeting uninvite`
|
|
- **Timezone**
|
|
- `/timezone set`, `/timezone show`
|
|
- **Scheduling**
|
|
- `/schedule create`, `/schedule list`, `/schedule reschedule`
|
|
- **Projects**
|
|
- `/projects list`, `/projects create`, `/projects add-helper`
|
|
- **Music** (requires **DJ** role)
|
|
- `/play`, `/queue`, `/volume`
|
|
- **Moderation** (focused + practical)
|
|
- `/moderation purge amount:<1-100>` — Fast recent message cleanup (**Manage Messages**)
|
|
- `/moderation timeout user:@someone duration:<10m|1h|...> [reason]` — Temporary member timeout (**Moderate Members**)
|
|
- `/moderation kick user:@someone [reason]` — Kick member (**Kick Members**)
|
|
- `/moderation ban user:@someone [delete_days] [reason]` — Ban member (**Ban Members**)
|
|
- `/moderation unban user_id:<id> [reason]` — Unban by user ID (**Ban Members**)
|
|
- `/moderation untimeout user:@someone [reason]` — Remove timeout (**Moderate Members**)
|
|
- `/moderation slowmode channel:#channel seconds:<0-21600>` — Control channel flood (**Manage Channels**)
|
|
- **Twitch live notifications** (**Manage Server**)
|
|
- `/config addstreamer username:<twitch-name>` — Add a streamer for notifications
|
|
- `/config removestreamer username:<twitch-name>` — Remove a streamer
|
|
- `/config settwitchnotificationchannel channel:#channel` — Channel for live pings
|
|
- **Welcome / onboarding** (**Manage Server**)
|
|
- `/config setwelcomechannel channel:#channel` — Channel for welcome messages
|
|
- `/config setwelcomemessage message:"..."` — Server welcome template (supports `{user}`, `{server}`)
|
|
- `/config setwelcomedm message:"..."` — DM welcome template (supports `{user}`, `{server}`)
|
|
- `/config setwelcomegif url:<image-url>` — GIF/image used in welcome embed
|
|
- `/config setdefaultrole role:@role` — Role automatically granted on join
|
|
- **Logging** (**Manage Server**)
|
|
- `/config setlogchannel channel:#channel` — Set where logs are sent
|
|
- `/config enablelogging` — Enable event/moderation logs
|
|
- `/config disablelogging` — Disable event/moderation logs
|
|
|
|
## Notes
|
|
|
|
- Slash commands are registered to the configured `GUILD_ID` on startup.
|
|
- Some features require server permissions (e.g. **Manage Server**) or roles (e.g. **DJ** for music).
|