Skip to content

README.md

Latest commit

 

History

History
201 lines (141 loc) · 6.86 KB

README.md

File metadata and controls

201 lines (141 loc) · 6.86 KB

Boo Boo — the (un)friendly Discord AI bot

Boo is a snark-powered Discord bot that blends LLM chat, image understanding, and handy utilities into a single docker-compose stack. It’s built for discord servers that want a fast, context-aware assistant with guardrails, a tiny admin API, and a smooth UX.

  • Conversational AI with per-guild system prompts
  • Automatic image captioning/analysis, with generation workflows
  • Short-term context in Redis for channel summaries
  • Long-term storage and editable prompts in Postgres (via a lightweight Go API + web UI)
  • GIFs, weather, pings, bonks, and more ...

✨ Features at a glance

Category What Boo does
AI chat Conversational replies via OpenRouter, per-server editable system prompt, mentions/replies/DM support, rolling context from Redis
Vision Auto image caption/analysis on upload
Utilities /weather, /bonk @user, /ping, /skibidi, /get_prompt, /summary
UX & Mod "Guys-check" for inclusive language nudges, oversized replies sent as text attachments, supports stickers and custom emojis
Admin !@sync to refresh slash commands, prompt editor served by the Go manager on http://localhost:8080

🏗 Repository layout

.
├─ compose.yml           # 4 services: postgres, redis, manager, discord-bot
├─ Dockerfile            # Python 3.12 (uv) base for the bot
├─ src/                  # Discord bot (Python / discord.py 2.5)
├─ manager/              # Go API + static Tailwind UI for prompts and token stats
└─ assets/               # diagrams and images

⚙️ Architecture

  • bot: Python 3.12 container with cogs, tools, and all commands
  • manager: Go (Gin) API for prompts/messages/tokens + static prompt editor
  • redis: 15-minute rolling message buffer per channel for AI summaries
  • postgres: persistent storage (prompts, messages, token usage)

🚀 Quick start (Docker)

  1. Clone the repo
git clone https://github.com/VVIP-Kitchen/boo.git
cd boo

  1. Create a .env file (see sample below)

  2. Bring the stack up

docker compose up -d

When the Discord gateway connects, the bot goes online. Open http://localhost:8080 to view or edit per-guild system prompts.

.env sample

# Discord
DISCORD_TOKEN=YOUR_DISCORD_BOT_TOKEN
ADMIN_LIST=123456789012345678,987654321098765432
CONTEXT_LIMIT=40

# APIs
TENOR_API_KEY=XXXXXXXXXXXX
TOMORROW_IO_API_KEY=XXXXXXXXXXXX
OPENROUTER_API_KEY=XXXXXXXXXXXX
OPENROUTER_MODEL=meta-llama/llama-4-maverick
EXA_API_KEY=XXXXXXXXXXXX
MANAGER_API_TOKEN=super-secure-shared-secret

# Database (compose wires these for containers)
POSTGRES_USER=db-user
POSTGRES_PASSWORD=db-password
POSTGRES_DB=db-name

The compose file wires these services for the bot:

postgres:5432, redis:6379, manager:8080

🛠 Running locally (without Docker)

# Python venv
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Start Redis and Postgres locally (or disable features that need them)
export $(cat .env | xargs)
python src/main.py

Run the Go manager separately:

cd manager
go run ./cmd/api

🗨 Commands

Trigger Description
/ping Check latency
/skibidi Ritual noises
/weather Realtime weather via Tomorrow.io
/bonk @user Random Tenor bonk GIF
/summary TL;DR of last 15 minutes in the channel
/get_prompt Download the current system prompt
/update_prompt Update system prompt from uploaded file
/add_prompt Add system prompt from uploaded file
reset chat Type in channel to clear context buffer
!@sync Owner-only; resync slash commands

Notes:

  • Context is kept per-guild; DMs are supported with a separate context.
  • Image uploads are analyzed automatically; multi-image messages are processed in sequence.
  • Oversized replies are delivered as .txt attachments.

🔐 Permissions and configuration

  • ADMIN_LIST controls privileged commands like sync. Comma-separated user IDs are required.
  • The bot requests message content and presence intents for context and UX features.
  • Rate-limit handling: if OpenRouter returns 429, Boo relays the retry ETA.

📦 Manager API (Go)

Endpoints (served on port 8080 inside the network; mapped to localhost:8080 via compose):

  • GET /docs — Swagger UI for the manager API (pulls /openapi.json)
  • GET /admin — prompt manager UI (token stored client-side to call the API)
  • GET /prompt?guild_id=… — fetch per-guild system prompt
  • POST /prompt — add prompt
  • PUT /prompt?guild_id=… — update prompt
  • POST /message — archive messages (write-only)
  • POST /token — record token usage
  • GET /token/stats?guild_id=…&author_id=…&period=[daily|weekly|monthly|yearly] — usage stats

A minimal Tailwind UI is served as static files for prompt editing.

🔐 Authentication: Every API call must include Authorization: Bearer <MANAGER_API_TOKEN>. The Python bot and worker load this token via MANAGER_API_TOKEN and automatically attach it to all requests. When exposing the manager service publicly, share the same token with any external client that needs access.

🧩 Extensibility

  • Add commands: create a new cog in src/commands and load it in bot/bot.py.
  • Swap LLMs: change OPENROUTER_MODEL or extend LLMService for different providers/tools.
  • Storage: extend manager/internal services and the Python DBService to track more analytics.
  • Emoji/stickers: tweak utils/emoji_utils.py to adjust patterns and rendering.

🤝 Contributing

See CONTRIBUTING

📄 License

MIT. Summon responsibly.

⚙️ Tech Stack

  • Python 3.12, discord.py 2.5
  • OpenRouter (LLM chat + vision)
  • Redis, Postgres
  • Go (Gin) manager with Tailwind UI
  • Docker Compose

🌐 DeepWiki

Ask DeepWiki