PRTS Discord Bot

PRTS is a Discord bot built to unify your workflows in one place through integrations, enhanced by AI. It provides conversational assistance, tool-driven workflows, Google Calendar automation, and a reminder system.

NOTE: PRTS is actively evolving and remains a work in progress.

Core Capabilities

• LLM chat fallback for natural conversation when no explicit command is matched.
• Tool-enabled responses for:
  • arithmetic and quick calculations
  • Python execution in an isolated sandbox
  • terminal command execution in an isolated sandbox
  • engineering/scientific unit conversion
• Google Calendar integration:
  • connect flow via OAuth
  • create, find, remove events
  • set event reminders
  • support for natural-language scheduling via tool calls
• To-do assistant:
  • /todo_start, /dump, and /list slash commands
  • periodic DM reminder loop for overdue pending tasks
• Safety responses for crisis content and politically sensitive requests.
• Message-level controls:
  • user rate limiting with warning, hard-limit, and cooldown stages
  • optional reply-trigger mode (process direct replies to bot messages without prefix)

Architecture Overview

• main.py: application entrypoint.
• bot/client.py: central message router, command dispatch, gates (admin/ban/rate-limit), and fallback handling.
• bot/cogs/llm.py: LLM interaction, runtime context injection, tool-call handling, safety/leak guards.
• tools/llm_api.py: chat-completions wrapper with multi-step tool-call loop.
• tools/toolcalls/tool_registry.py: available tools and Google Calendar NL actions.
• bot/cogs/gcal.py: slash commands for calendar operations.
• oauth_server.py: OAuth callback/token handling.
• settings.py: centralized config loader for environment variables and runtime feature flags.

Quick Start

1. Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. Create environment file:

cp .env.example .env

4. Configure required values in .env:

• DISCORD_TOKEN
• BOT_PREFIX
• LLM_API_KEY (required for hosted LLM providers; not required when LLM_PROVIDER=ollama)
• Google OAuth settings (CLIENT_ID, CLIENT_SECRET, OAUTH_BASE_URL, OAUTH_REDIRECT_URI)
• Supabase settings (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)

5. Run the bot:

python main.py

Configuration Notes

• settings.py is the single source of truth for runtime configuration.
• Environment variables are loaded and parsed there (tokens, API keys, OAuth settings, prefixes).
• Feature flags (for example reply-trigger behavior and message silence modes) are also defined there.
• Recent prompt context is enabled by default and injects a small recent channel window into every LLM request.
• You can tune that default context size with RECENT_CONTEXT_MESSAGE_COUNT or disable it with RECENT_CONTEXT_ENABLED=false.
• Prompts that look like channel-history recall requests are handled with deterministic extended context injection so the model can answer from the current channel without asking for a channel ID.
• LLM backend selection is opt-in via LLM_PROVIDER:
  • default: hosted Groq-compatible mode
  • optional: ollama for local OpenAI-compatible requests
• LLM HTTP requests default to a 120-second timeout; override with LLM_REQUEST_TIMEOUT_SECONDS if needed.
• When LLM_PROVIDER=ollama, the default endpoint is http://localhost:11434/v1 and the default model is llama3.1:8b.
• Existing hosted setups do not need any .env changes.

Example Use Cases

• Ask technical questions and get concise engineering-focused answers.
• Solve quick calculations or unit conversions directly in chat.
• Run Python-based analysis and return results/files in Discord.
• Schedule reminders and calendar events using natural language.
• Update or remove calendar events without switching apps.